## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require flux-clone/ui

The package auto-registers its service provider.

Tailwind Configuration: Add the package's view path to your tailwind.config.js:

module.exports = {
  content: [
    // ... existing paths
    "./vendor/flux-clone/ui/resources/views/**/*.blade.php",
  ],
}

Or for Tailwind 4 (CSS):

@source "../vendor/flux-clone/ui/resources/views/**/*.blade.php";

First Use Case: Replace a basic form input with the package's <x-flux-clone::input>:
```
<x-flux-clone::input name="email" label="Email" type="email" />
```
This immediately adds label, error handling, and styling.

Implementation Patterns

Common Workflows

Form Integration

Validation Errors: The <x-flux-clone::input> component automatically handles Laravel validation errors via $errors:
```
<x-flux-clone::input name="email" label="Email" type="email" />
```
Errors render below the input with red styling.

Livewire Forms: Pair with Livewire for reactive forms:

<x-flux-clone::input wire:model="email" label="Email" />

Modals and Overlays

Named Modals: Use Alpine.js for modal management:

<x-flux-clone::modal name="confirm-delete">
    <!-- Modal content -->
</x-flux-clone::modal>
<x-flux-clone::modal.trigger name="confirm-delete">
    <x-flux-clone::button variant="danger">Delete</x-flux-clone::button>
</x-flux-clone::modal.trigger>

Triggers can be buttons, links, or other components.

Livewire Modals: Combine with Livewire for dynamic content:

<x-flux-clone::modal wire:model="showModal">
    <x-flux-clone::heading>Edit User</x-flux-clone::heading>
    <x-flux-clone::input wire:model="name" label="Name" />
</x-flux-clone::modal>

Tables with Sorting

Sortable Columns: Use the sortable attribute to enable client-side sorting:

<x-flux-clone::table>
    <x-flux-clone::table.head>
        <x-flux-clone::table.row>
            <x-flux-clone::table.cell header sortable="name">Name</x-flux-clone::table.cell>
        </x-flux-clone::table.row>
    </x-flux-clone::table.head>
    <!-- ... -->
</x-flux-clone::table>

For server-side sorting, bind to a Livewire property (e.g., wire:click="sortBy('name')").

Layout Consistency

Card Components: Use <x-flux-clone::card> for consistent card layouts:

<x-flux-clone::card>
    <x-flux-clone::heading>User Profile</x-flux-clone::heading>
    <x-flux-clone::text>John Doe</x-flux-clone::text>
</x-flux-clone::card>

Cards include padding, shadows, and responsive behavior.

Navigation: Build navbars and navlists for consistent UI:

<x-flux-clone::navbar>
    <x-flux-clone::navlist>
        <x-flux-clone::navlist.item href="/dashboard">Dashboard</x-flux-clone::navlist.item>
    </x-flux-clone::navlist>
</x-flux-clone::navbar>

Icons and Feedback

Icons: Use Heroicons via Blade Icons:
```
<x-flux-clone::icon name="check-circle" variant="solid" />
```
Requires blade-ui-kit/blade-heroicons.

Callouts: Display alerts with <x-flux-clone::callout>:

<x-flux-clone::callout type="success">
    User created successfully!
</x-flux-clone::callout>

Types: info, success, warning, danger.

Gotchas and Tips

Pitfalls and Debugging

Tailwind Configuration

Missing Views: If components render as plain text, ensure the package's view path is added to tailwind.config.js.
Dark Mode: Components support dark mode, but ensure your app's HTML has the dark class or use JavaScript to toggle it:
```
document.documentElement.classList.toggle("dark");
```

Livewire Integration

Modal States: Named modals (e.g., name="confirm-delete") require Alpine.js. If using Livewire, prefer wire:model for modals to avoid conflicts:
```
<x-flux-clone::modal wire:model="showModal">
    
</x-flux-clone::modal>
```

Form Handling

Password Visibility: The viewable attribute on <x-flux-clone::input> toggles password visibility with an eye icon. Ensure Alpine.js is loaded (included with Livewire).
Error States: Validation errors rely on Laravel's $errors helper. If errors don't display, verify:
- The input name matches the validation rule.
- The form submits to a route with validation logic.

Sortable Tables

Client-Side Sorting: The sortable attribute enables basic sorting. For server-side sorting, manually bind to Livewire methods:

<x-flux-clone::table.cell
    header
    wire:click="sort('name')"
    class="cursor-pointer"
>
    Name
</x-flux-clone::table.cell>

Tips for Extension

Customizing Components

Publish Views:
```
php artisan vendor:publish --tag=flux-clone-views
```
Override components in resources/views/vendor/flux-clone.

Extending Variants: Add custom button variants by extending the component's Tailwind classes. For example, create a secondary variant in your published view:

@props(['variant' => 'primary'])
<button class="px-4 py-2 rounded-md {{ $variant === 'secondary' ? 'bg-blue-100 text-blue-800' : '' }}">
    {{ $slot }}
</button>

Adding New Components

Reuse Patterns: Copy existing components (e.g., <x-flux-clone::input>) and adapt them for new use cases.
Alpine.js Logic: For interactive components (e.g., modals, dropdowns), leverage Alpine.js directives like x-data, x-show, and x-transition.

Performance

Lazy-Loading: For large tables, use pagination or lazy-loading with Livewire:

<x-flux-clone::table>
    @foreach($users->chunk(10) as $chunk)
        <!-- Render chunk -->
    @endforeach
</x-flux-clone::table>

Debounce Inputs: For search inputs, debounce Livewire updates:

<x-flux-clone::input
    wire:model.debounce.500ms="search"
    label="Search"
/>

Testing

Component Testing: Use Laravel's Blade component testing:

public function test_button_renders()
{
    $component = Blade::render('<x-flux-clone::button>Click</x-flux-clone::button>');
    $this->assertStringContainsString('Click', $component);
}

Livewire Integration: Test Livewire components with the package's components:

public function test_modal_with_livewire()
{
    $this->livewire(ModalComponent::class)
         ->assertSee('Modal Title');
}

Dark Mode Quirks

Custom Colors: If using custom colors, ensure they have dark variants in tailwind.config.js:
```
theme: {
  extend: {
    colors: {
      primary: {
        500: '#3b82f6',
        900: '#1d4ed8',
      },
    },
  },
},
```
Then use bg-primary-500 dark:bg-primary-900 in components.

Icon System

Blade Icons Required: For full icon support, install blade-ui-kit/blade-heroicons. Without it, icons will render as text.
Fallback Icons: Use the <x-flux-clone::icon> component with a fallback:

Ui Laravel Package