Getting Started

Minimal Steps

Installation:
```
composer require allyoullneed/advanced-controls
```
Ensure your project uses Laravel 10+ and Livewire 4 (verified compatibility in changelog).
First Use Case: Replace a basic Blade <select> with the package’s enhanced <x-select> in a Livewire component:
```
<x-select wire:model="user.role" :options="$roles" placeholder="Choose a role" />
```
- Key Attributes:
  - wire:model for Livewire reactivity.
  - :options for dynamic data binding.
  - filter (v1.1.0+) for searchable dropdowns:
```
<x-select wire:model="search" :options="$users" filter placeholder="Search users..." />
```
Where to Look First:
- Component List: Check the official documentation for the full suite (e.g., Tab, Avatar, Chart, MenuItem).
- Livewire Integration: Focus on components with wire:model support (e.g., Select, Tab, form fields).
- Changelog: Review recent fixes (e.g., v1.1.4 for Livewire pinning, v1.1.1 for dropdown alignment) to avoid known issues.

Implementation Patterns

Usage Patterns

Livewire-Driven Components:
- Two-Way Binding: Use wire:model for components like Select, Checkbox, or Tab:
```
<x-tab wire:model="activeTab" :tabs="$tabs" />
```
- Dynamic Data: Pass arrays/objects via attributes:
```
<x-select :options="$dynamicOptions" wire:model="selectedOption" />
```
Form Integration:
- Error Handling: Components auto-highlight errors when Livewire validation fails (added in v1.0.1).
- Example:
```
<x-input wire:model="form.name" label="Name" />

```

Nested Components:

Menus with Submenus: Use MenuItem for hierarchical navigation:

<x-menu>
    <x-menuItem title="Dashboard" href="/dashboard" />
    <x-menuItem title="Settings">
        <x-slot name="submenu">
            <x-menuItem title="Profile" href="/profile" />
        </x-slot>
    </x-menuItem>
</x-menu>

Charts:

CDN Configuration: Specify chart libraries (e.g., Chart.js) via config:

// config/advanced-controls.php
'charts' => [
    'cdn' => 'https://cdn.jsdelivr.net/npm/chart.js',
],

Usage:

<x-chart type="line" :data="$chartData" class="h-64" />

Tables of Contents (ToC):
- Automatic Generation: Use <x-toc> for dynamic navigation:
```
<x-toc selector="h2,h3" class="bg-gray-100 p-4" />
```

Workflows

Component Replacement Workflow:

Before: Custom Blade + Alpine/Livewire.
After: Replace with <x-Component> tags, migrate props to attributes.

Example:

- <div x-data="{ activeTab: 'home' }">
-   <button @click="activeTab = 'home'">Home</button>
- </div>
+ <x-tab wire:model="activeTab" :tabs="['home', 'profile']" />

Livewire Component Pairing:

Backend Logic: Handle data in Livewire classes:

// app/Http/Livewire/UserSettings.php
public $role;
public $roles = ['admin', 'editor', 'user'];

protected $rules = ['role' => 'required'];

Frontend View:

<x-select wire:model="role" :options="$roles" />

Theming:
- Tailwind Classes: Override styles via class attribute:
```
<x-select class="bg-white border-gray-300" />
```
- CSS Variables: Extend via custom CSS (limited support; test per component).

Integration Tips

Statamic Projects:
- Use components in Statamic control panels or entry templates:
```
<x-avatar :user="$entry->author()" size="md" />
```
- Leverage Statamic’s $entry data for dynamic options:
```
<x-select :options="$entry->categories()->pluck('title', 'id')" />
```
Asset Pipeline:
- Vite/Laravel Mix: Ensure no conflicts with existing JS/CSS. Test components in isolation.
- CDN Fallback: For charts, verify CDN availability in offline modes.

Testing:

Livewire Tests: Use Livewire::test() to validate component interactions:

public function test_select_component()
{
    Livewire::test(SelectComponent::class)
        ->set('value', 'option2')
        ->assertSet('value', 'option2');
}

Blade Rendering: Test static rendering with @test directives.

Fallbacks:

Graceful Degradation: Wrap components in @if checks for unsupported environments:

@if (class_exists(\Allyoullneed\AdvancedControls\Select::class))
    <x-select wire:model="value" :options="$options" />
@else
    <select wire:model="value">
        @foreach($options as $key => $value)
            <option value="{{ $key }}">{{ $value }}</option>
        @endforeach
    </select>
@endif

Gotchas and Tips

Pitfalls

Livewire Version Mismatch:
- Issue: Components assume Livewire 4. Explicitly check compatibility if using older/new versions.
- Fix: Pin Livewire to ^4.0 in composer.json:
```
"require": {
    "livewire/livewire": "^4.0"
}
```
Statamic-Specific Assumptions:
- Issue: Some components may rely on Statamic helpers (e.g., $entry data). Test in vanilla Laravel.
- Fix: Mock Statamic data in tests or use Laravel’s native collections.

Chart Loading:

Issue: CDN-based charts may fail if blocked or slow. Offline modes unsupported.

Fix: Self-host chart libraries or use a fallback:

@if(config('advanced-controls.charts.cdn'))
    <x-chart type="line" :data="$data" />
@else
    <div class="text-gray-500">Charts unavailable (CDN blocked)</div>
@endif

Accessibility (a11y):
- Issue: Limited ARIA attribute support (e.g., Select fixes in v1.1.4). Screen reader testing recommended.
- Fix: Manually add ARIA labels where needed:
```
<x-select aria-label="User role selection" wire:model="role" :options="$roles" />
```
Component Registration:
- Issue: Components must be registered on every request (fixed in v1.0.8). Artisan commands may fail.
- Fix: Ensure AdvancedControlsServiceProvider is loaded in config/app.php.

Dynamic Options:

Issue: Select components may not update options reactively if :options is static.

Fix: Use Livewire properties for dynamic data:

// Livewire class
public $options = [];
public function mount() {
    $this->options = User::pluck('name', 'id');
}

<x-select wire:model="userId" :options="$options" />

Debugging

Livewire Wire:Model Issues:
- Symptom: Component value not updating.
- Debug:
  - Check for typos in wire:model (e.g., wire:model="user.role" vs. wire:model="userrole").
  - Verify the Livewire property exists in the class (public $role;).
  - Use {{ dd($this->role) }} in the Livewire class to inspect values.
Component Not Rendering:
- Symptom: Blade tag outputs raw text (e.g., <x-select> instead of the component).
- Debug:
  - Ensure the component is published (run `php artisan vendor:publish --tag=advanced

Advanced Controls Laravel Package