## Getting Started

### Minimal Setup
1. **Install via Composer** (preferably in a Dockerized Symfony 8.4 environment):
   ```bash
   composer require chrisdev/ux-components

Ensure Docker is running and use the provided Makefile for all commands:

make install  # Installs dependencies (PHP, Node, etc.)
make dev      # Starts dev server

First Use Case: Render a basic component (e.g., a Card) in a Twig template:

{{ include('ux_components::card.html.twig', {
    title: 'Example Card',
    content: 'This is a reusable Symfony UX Card component.'
}) }}

Verify the component appears on /home (demo route).

Key Directories

Components: templates/ux_components/ (Twig templates for reusable components).
Stimulus Controllers: assets/controllers/ (Stimulus logic for interactivity).
Demos: templates/demo/ (pre-built pages showcasing components).

Implementation Patterns

1. Component Integration Workflow

Step 1: Discover Existing Components

Browse templates/ux_components/ for pre-built components (e.g., card.html.twig, modal.html.twig).
Use grep or IDE search to find components by functionality (e.g., "dropdown" or "table").

Step 2: Reuse or Extend

Reuse: Include the component directly in Twig:

{{ include('ux_components::dropdown.html.twig', {
    items: ['Option 1', 'Option 2'],
    label: 'Select an item'
}) }}

Extend: Copy the component template to your project (e.g., templates/components/custom_card.html.twig) and modify it. Override Stimulus controllers if needed (e.g., assets/controllers/custom_card_controller.js).

Step 3: Configure via Twig

All components accept configuration via Twig parameters. Example for a Badge:

{{ include('ux_components::badge.html.twig', {
    text: 'Warning',
    type: 'warning',  // 'primary', 'success', 'danger', etc.
    pill: true
}) }}

Step 4: Add Interactivity (Stimulus)

For dynamic behavior (e.g., modals, dropdowns), extend the Stimulus controller:

// assets/controllers/modal_controller.js
import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
  connect() {
    console.log('Custom modal logic');
  }
}

Attach to your Twig template:

<div data-controller="modal" data-action="click->modal#toggle">
  {{ include('ux_components::modal.html.twig') }}
</div>

2. Dark Mode Support

Components are designed with Tailwind’s dark mode classes (e.g., dark:bg-gray-800).

Ensure your layout includes:

<html class="{{ 'dark' if app.request.attributes.get('_route') == 'dark_mode' }}">

Toggle dark mode via a Stimulus controller or route.

3. Dockerized Development

Run Linting/Testing:

make lint      # Runs Twig/PHP lint
make phpstan   # Static analysis

Rebuild Assets:
```
make build     # Compiles Tailwind/JS
```

Hot Reload:

make dev       # Starts Symfony server with Vite HMR

4. Demo Pages

Use /demo routes to test components in isolation. Example:

// templates/demo/card_demo.html.twig
{% extends 'ux_components::base.html.twig' %}

{% block body %}
    {{ include('ux_components::card.html.twig', {
        title: 'Demo Card',
        content: 'This is a demo.'
    }) }}
{% endblock %}

Gotchas and Tips

Pitfalls

Direct Preline Usage
- Issue: Components must not directly use Preline UI markup. Always wrap Preline in a Symfony UX Twig Component.
- Fix: Extend an existing component (e.g., modal.html.twig) instead of copying Preline’s HTML.

Bootstrap CSS

Issue: The package forbids Bootstrap CSS (allowed only via Symfony UX Icons).

Fix: Use Tailwind classes exclusively. Example:

<!-- ❌ Avoid -->
<button class="btn btn-primary">Click</button>

<!-- ✅ Prefer -->
<button class="bg-blue-500 text-white px-4 py-2 rounded">Click</button>

Component Bloat
- Issue: Creating overly specific components (e.g., UserCard) violates the "one responsibility" rule.
- Fix: Use a generic Card component with configurable props:
```
{{ include('ux_components::card.html.twig', {
    title: 'User Profile',
    content: user|json_encode,
    icon: 'user'
}) }}
```
Stimulus Controller Naming
- Issue: Stimulus controllers must match the component’s template name (e.g., modal_controller.js for modal.html.twig).
- Fix: Follow the convention or alias controllers in config/packages/stimulus.php:
```
stimulus:
    controllers:
        custom_modal: 'assets/controllers/modal_controller.js'
```
Dark Mode Inconsistencies
- Issue: Components may not respect dark mode if Tailwind classes are missing.
- Fix: Add dark: variants to all background/color classes. Example:
```
<div class="bg-white dark:bg-gray-800">
```

Debugging Tips

Twig Component Not Rendering?
- Verify the template path is correct (e.g., ux_components::card.html.twig).
- Check for missing use statements in Twig:
```
{% use 'ux_components::_partials/macros.html.twig' %}
```
Stimulus Not Working?
- Ensure the controller is imported in assets/app.js:
```
import './controllers/modal_controller';
```
- Check the browser’s Network tab for 404s on Stimulus JS files.
Tailwind Classes Not Applying?
- Run make build to recompile assets.
- Verify tailwind.config.js includes all necessary paths:
```
content: [
    './templates/**/*.html.twig',
    './assets/**/*.js'
],
```

Extension Points

Add a New Component
- Steps:
  1. Create templates/ux_components/new_component.html.twig.
  2. Add a Stimulus controller at assets/controllers/new_component_controller.js.
  3. Document the component’s props in a README.md under docs/components/.
- Example Structure:
```
templates/ux_components/
├── new_component.html.twig
└── _partials/
    └── new_component_macros.html.twig
assets/controllers/
└── new_component_controller.js
```

Override Defaults Globally

Extend the base template (templates/base.html.twig) to modify all components:

{% block ux_components %}
    {{ parent() }}  {# Renders default components #}
    {{ include('ux_components::custom_partial.html.twig') }}
{% endblock %}

Customize Preline Behavior

Override Preline’s JS initialization in assets/app.js:

import { initPreline } from './preline';
initPreline(); // Customize options here

Configuration Quirks

Symfony UX Autocomplete

Requires a dedicated route and controller. Example:

# config/routes.yaml
ux_autocomplete:
    path: /_ux-autocomplete
    controller: App\Controller\AutocompleteController::search

Configure the Twig component:

{{ include('ux_components::autocomplete.html.twig', {
    endpoint: path('ux_autocomplete'),
    placeholder: 'Search...'
}) }}

ChartJS Integration
- Ensure symfony/ux-chartjs is installed and the component is initialized in assets/app.js:
```
import { initChartJS } from './chartjs';
initChartJS();
```

Icons

Use Symfony UX Icons (Bootstrap Icons) via Twig:

{{ include('ux_components::icon.html.twig', { name: 'person' }) }}

Custom icons

Ux Components Laravel Package