## Getting Started

### Minimal Steps to First Use
1. **Installation**:
   ```bash
   composer require evolution-cms/evo-ui
   php artisan vendor:publish --tag=evo-ui --force

Ensure your Evolution CMS version is 3.5.7+ for symlink support.

Basic Blade Integration: Replace legacy manager layouts with x-evo::layout in your module’s Blade files:
```
<x-evo::layout :title="'My Module'">
    
</x-evo::layout>
```

First Component: Use evo-ui.module-table for a preconfigured table (requires a preset):

<livewire:evo-ui.module-table
    preset="my-module.items"
    :context="['moduleUrl' => route('my.module.url')]"
    :perPage="cookie('evo-ui.tables.my-module.items.perPage', 20)"
/>

Note: Per-page preference now persists via cookies by default.

Verify Assets: Check public/assets/modules/evo-ui for published DaisyUI/Livewire assets. If symlinks fail, manually publish:
```
php artisan vendor:publish --tag=evo-ui-assets --force
```

Implementation Patterns

Core Workflows

Shell Integration:
- Replace legacy manager/iframe with x-evo::layout for module-specific assets.
- Use x-evo::module-tabs for tabbed interfaces:
```
<x-evo::module-tabs :items="$tabs" :active="$activeTab" />
```

Table Configuration: Define a preset in your module’s config (e.g., config/my-module.php):

'tables' => [
    'items' => [
        'columns' => ['id', 'title', 'status'],
        'filters' => ['search', 'status'],
        'actions' => ['edit', 'delete'],
        'multiSelect' => true, // New in v1.0.5
        'cleanState' => true,  // New in v1.0.5
    ],
],

Reference it in Blade:

<livewire:evo-ui.module-table preset="my-module.items" />

Forms: Use evo-ui.form for settings/resources with support for repeated fields:

<livewire:evo-ui.form preset="my-module.settings" />

Define fields in config:

'forms' => [
    'settings' => [
        'fields' => [
            'title' => ['type' => 'text', 'label' => 'Title'],
            'status' => ['type' => 'select', 'options' => ['active', 'draft']],
            'description' => ['type' => 'rich-text'], // Fixed repeated initialization
        ],
    ],
],

Issue Workspace (Kanban/List): Extend EvoUI\Contracts\WorkspaceProvider for dynamic surfaces (e.g., dIssues):

class MyWorkspaceProvider implements WorkspaceProvider {
    public function getColumns(): array { ... }
    public function getItems(): array { ... }
}

$this->app->bind('evo-ui.workspace.my-module', MyWorkspaceProvider::class);

Shared Components: Leverage pre-built components with improved typography:
- Buttons: <x-evo::button type="primary" icon="edit" />
- Modals: <x-evo::modal> with evo-ui.modal Livewire.
- Rich Editors: <x-evo::rich-editor /> (fixed repeated initialization).
- Tables: Now support responsive list layout on narrow screens.

Integration Tips

Theme Sync: EvoUI auto-syncs with Evolution’s themes (evolight, evodark). Override via:
```
config(['evo-ui.theme' => 'custom']);
```
Session State: Table filters/sorting persist via session(). Clear with:
```
session()->forget('evo-ui.tables.my-module.items');
```
Asset Isolation: Use evo::partials.assets in Blade to load module-specific CSS/JS:
```
@evo('partials.assets', ['module' => 'my-module'])
```

Livewire Bridge: Access Evolution services via EvoUI\Livewire\ManagerBridge:

use EvoUI\Livewire\ManagerBridge;
$bridge = app(ManagerBridge::class);
$user = $bridge->user(); // Evolution CMS user

Per-Page Preference: Leverage cookie-based per-page settings:

<livewire:evo-ui.module-table
    preset="my-module.items"
    :perPage="cookie('evo-ui.tables.my-module.items.perPage', 20)"
/>

Gotchas and Tips

Pitfalls

Symlink Dependencies:
- Issue: Stale assets if symlinks fail (e.g., shared hosting).
- Fix: Force publish:
```
php artisan vendor:publish --tag=evo-ui-assets --force
```
- Check: Verify public/assets/modules/evo-ui exists post-install.
Preset Mismatches:
- Issue: preset="..." not found throws LivewireException.
- Fix: Ensure presets are defined in config/evo-ui.php or module config.
Session Conflicts:
- Issue: Legacy manager sessions may override EvoUI state.
- Fix: Clear old sessions:
```
session()->flush();
```
DnD Quirks:
- Issue: Drag handles (x-evo::reorder-rail) fail if _uid is missing.
- Fix: Ensure all draggable items have a stable _uid:
```
<x-evo::dnd-option-row :uid="'item-{$item->id}'" />
```
Theme Overrides:
- Issue: DaisyUI classes conflict with legacy CSS.
- Fix: Scope EvoUI styles:
```
.evo-ui { /* All EvoUI styles here */ }
```
Mouse Wheel Scrolling:
- Issue: Mouse wheel may not scroll inside embedded manager frames.
- Fix: Ensure frames are properly embedded and updated to v1.0.5.

Debugging

Livewire Logs: Enable debug mode in config/evo-ui.php:
```
'debug' => env('APP_DEBUG', true),
```
Check storage/logs/livewire.php.
Preset Validation: Use the evo-ui:validate Artisan command:
```
php artisan evo-ui:validate --preset="my-module.items"
```
Asset Loading: Verify DaisyUI/Livewire are loaded via browser dev tools. If missing:
- Check resources/views/vendor/evo-ui/assets.blade.php.
- Ensure evo::partials.assets is called in the layout.
Testing: Use the new Livewire testing foundation shims for module table tests:
```
use EvoUI\Testing\LivewireShims;
```

Extension Points

Custom Components: Extend shared components by publishing views:
```
php artisan vendor:publish --tag=evo-ui-views --force
```
Override in resources/views/vendor/evo-ui/components/.

Livewire Hooks: Listen to table/form events:

public function mounted() {
    $this->dispatch('evo-ui::table-ready', data: ['preset' => 'my-module.items']);
}

Workspace Providers: Add custom providers to config/evo-ui.php:

'workspaces' => [
    'my-module' => \App\Providers\MyWorkspaceProvider::class,
],

Field Types: Register custom form fields via service providers:

EvoUI::extend('custom-field', function () {
    return new CustomFieldComponent();
});

Multi-Select and Clean State: Enable new table features in presets:

'tables' => [
    'items' => [
        'multiSelect' => true,
        'cleanState' => true,
    ],
],

Pro Tips

Performance: Lazy-load heavy components (e.g., rich editors) with:
```
@if($showEditor)
    <x-evo::rich-editor />
@endif
```
Localization: Override translations via lang/vendor/evo-ui.
Testing: Use the package’s smoke tests and new Livewire shims:
```
composer test -- --filter
```

Evo Ui Laravel Package