Getting Started

Minimal Setup

Install the package:
```
composer require elnasnato/laraliveui
```

Add directives to your layout (resources/views/layouts/app.blade.php):

<head>
    @laraliveuiAppearance
</head>
<body>
    @livewireScripts
    @laraliveuiScripts
</body>

Import CSS (resources/css/app.css):

@import 'tailwindcss';
@import '../../vendor/elnasnato/laraliveui/dist/laraliveui.css';
@custom-variant dark (&:where(.dark, .dark *));

First Use Case: Replace a Basic Button

Replace a standard Laravel button with the package’s component:

<laraliveui:button variant="primary" wire:click="submitForm">
    Submit
</laraliveui:button>

Implementation Patterns

Component Composition

Use dot notation for nested components:

<laraliveui:modal name="confirmation-modal">
    <laraliveui:modal.trigger>
        <laraliveui:button variant="danger">Delete</laraliveui:button>
    </laraliveui:modal.trigger>
    <laraliveui:modal.dialog>
        <h3>Confirm Deletion</h3>
        <p>Are you sure?</p>
    </laraliveui:modal.dialog>
</laraliveui:modal>

Livewire Integration

Leverage Livewire’s reactivity with wire: directives:

<laraliveui:input
    name="email"
    placeholder="Email"
    wire:model="form.email"
    wire:change="validateEmail"
/>

Dynamic Forms with Repeaters

Use <laraliveui:repeater> for dynamic form fields:

<laraliveui:repeater wire:model="items">
    <laraliveui:repeater.item>
        <laraliveui:input name="name" placeholder="Item name" />
        <laraliveui:button icon="trash" wire:click="removeItem({{ $index }})" />
    </laraliveui:repeater.item>
    <laraliveui:repeater.add-button>Add Item</laraliveui:repeater.add-button>
</laraliveui:repeater>

Layout Patterns

Combine layout components for consistent UIs:

<laraliveui:layout>
    <laraliveui:layout.header>
        <laraliveui:navbar>
            <laraliveui:navbar.brand>My App</laraliveui:navbar.brand>
            <laraliveui:navbar.menu>
                <laraliveui:navbar.item>Dashboard</laraliveui:navbar.item>
            </laraliveui:navbar.menu>
        </laraliveui:navbar>
    </laraliveui:layout.header>
    <laraliveui:layout.main>
        @yield('content')
    </laraliveui:layout.main>
    <laraliveui:layout.sidebar>
        <laraliveui:navlist>
            <laraliveui:navlist.item>Settings</laraliveui:navlist.item>
        </laraliveui:navlist>
    </laraliveui:layout.sidebar>
</laraliveui:layout>

Icons

Use Heroicons-based SVG icons:

<laraliveui:icon name="magnifying-glass" class="text-gray-500" />
<laraliveui:icon name="check-circle" variant="solid" class="text-green-500" />

Gotchas and Tips

Pitfalls

Asset Loading Order:
- Place @laraliveuiAppearance in <head> and @laraliveuiScripts before </body> to avoid FOUC (Flash of Unstyled Content).
- Ensure laraliveui.css is imported after tailwindcss in app.css.
Livewire Conflicts:
- Avoid naming Livewire properties the same as laraliveui: component attributes (e.g., wire:model="name" vs. name="name"). Use wire:key or unique property names.
Dark Mode:
- The @laraliveuiAppearance directive toggles dark mode via data-theme attribute. If using custom dark mode logic, ensure it doesn’t conflict with laraliveui.appearance in localStorage.
Pro Components:
- The 18 "pro" components (e.g., rover, wizard) may require additional licensing clarification. Check the documentation for usage rights.

Debugging

Missing Components:
- Run php artisan view:clear and composer dump-autoload if components fail to render.
- Verify the laraliveui: namespace is registered by checking LaraliveuiServiceProvider::bootComponentPath().
JavaScript Errors:
- Ensure @laraliveuiScripts is placed after @livewireScripts in your layout.
- Check browser console for window.LaraLiveUI initialization errors.

Styling Issues:

Override Tailwind classes in your app.css after importing laraliveui.css:

@layer components {
    .laraliveui-button-primary {
        @apply bg-blue-600 hover:bg-blue-700;
    }
}

Tips

Customization:
- Publish Blade files for deep customization:
```
php artisan laraliveui:publish
```
- Override component logic in resources/views/vendor/laraliveui/.

Performance:

Lazy-load heavy components (e.g., <laraliveui:table>) using Alpine.js:

<div x-data="{ loaded: false }" x-show="loaded">
    <laraliveui:table @load="loaded = true" />
</div>

Accessibility:
- Use aria-* attributes provided by the package (e.g., <laraliveui:modal> includes aria-modal="true").
- Extend with custom ARIA labels if needed:
```
<laraliveui:button aria-label="Submit form">Submit</laraliveui:button>
```
Starter Kit:
- For new projects, use the starter kit to bootstrap auth, profiles, and layouts:
```
laravel new my-app --using=elnasnato/laraliveui-starter-kit
```
Icon Customization:
- Replace icons by publishing the resources/views/vendor/laraliveui/icon directory and overriding individual .blade.php files.

Livewire + Alpine:

Combine with Alpine.js for dynamic behavior:

<laraliveui:dropdown x-data="{ open: false }">
    <laraliveui:dropdown.trigger @click="open = !open">
        <laraliveui:button>Menu</laraliveui:button>
    </laraliveui:dropdown.trigger>
    <laraliveui:menu x-show="open" @click.away="open = false">
        <!-- Menu items -->
    </laraliveui:menu>
</laraliveui:dropdown>

Theming:

Extend the default theme by adding custom CSS variables:

@layer components {
    .laraliveui-button {
        --laraliveui-button-primary: #3b82f6;
        --laraliveui-button-secondary: #6b7280;
    }
}

Laraliveui Laravel Package