Livewire Table Kit Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require unlab/livewire-table-kit

Add Tailwind source path (v4):

@source "../../vendor/unlab/livewire-table-kit/resources/views/**/*.blade.php";

Run npm run build.

2. Generate a Table:

   php artisan make:livewire-table App\Models\User UsersTable
   

   This creates a scaffolded UsersTable component with:

   • Basic search
   • Default columns (ID, name, email)
   • Pagination
   • Sorting

3. First Use Case:

   // app/Http/Livewire/UsersTable.php
   public function columns(): array {
       return [
           Column::make('ID')->field('id')->sortable(),
           Column::make('Name')->field('name')->searchable(),
       ];
   }
   

   <!-- resources/views/livewire/users-table.blade.php -->
   <livewire:users-table />
   

Key First Steps

• Verify Tailwind Integration: Ensure styles compile after adding the source path.
• Test Basic Functionality: Check search, sorting, and pagination work out-of-the-box.
• Customize Columns: Override columns() to match your model schema.

Implementation Patterns

Core Workflow

1. Model-Driven Development:

   • Use make:livewire-table to auto-generate a table from an Eloquent model.
   • The generator infers searchable/sortable fields and creates sensible defaults.

2. Column Configuration:

   // Dynamic value resolution
   Column::make('Full Name')
       ->value(fn ($row) => "{$row->first_name} {$row->last_name}")
       ->searchableRaw('CONCAT(first_name, " ", last_name)');
   
   // Custom Blade view for cells
   Column::make('Status')
       ->field('status')
       ->view('custom.status-cell');
   

3. Filter Integration:

   // Multi-select filter (checkbox)
   Filter::checkbox('tags', 'Tags', [
       'php' => 'PHP',
       'laravel' => 'Laravel',
       'livewire' => 'Livewire',
   ])->display('dropdown');
   
   // Custom query logic
   Filter::text('search_bio')
       ->query(fn ($query, $value) => $query->where('bio', 'like', "%{$value}%"));
   

4. Action Patterns:

   // Row-level actions
   ActionColumn::make()->actions([
       TableAction::wire('Edit', fn ($row) => "edit({$row->id})"),
       TableAction::link('View', fn ($row) => route('users.show', $row)),
   ]);
   
   // Bulk actions
   public function supportsBulkDelete(): bool => true;
   public function actionBulkDelete(array $payload): void {
       User::whereIn('id', $payload)->delete();
   }
   

5. Export Workflow:

   // Sync export (default)
   public function supportsExport(): bool => true;
   
   // Queued export (for large datasets)
   protected function exportType(): string => 'queued';
   protected function exportFilename(string $ext): string {
       return "users_export_{$this->search}.{$ext}";
   }
   

Integration Tips

• Flux UI Dependency: Ensure your project uses Flux UI 2+ for consistent styling.
• Tailwind Breakpoints: Use responsive column hiding:

  Column::make('Notes')->hiddenOn('sm');
  

• Event-Driven Extensions: Listen for refreshTable events to trigger data reloads:

  $this->dispatch('refreshTable');
  

• Custom Styling: Override Blade views in resources/views/vendor/livewire-table-kit/.

Gotchas and Tips

Common Pitfalls

1. Tailwind Configuration:

   • Issue: Styles not compiling after adding source path.
   • Fix: Ensure node_modules is rebuilt (npm run build).
   • Pro Tip: Use tailwind.config.js for v3:

     content: [
         './vendor/unlab/livewire-table-kit/resources/views/**/*.blade.php',
         './resources/**/*.blade.php',
     ],
     

2. Filter Conflicts:

   • Issue: Filters overriding each other unexpectedly.
   • Fix: Use unique key values in Filter::*() methods.
   • Debug: Check the filters() array for duplicate keys.

3. Export Failures:

   • Issue: PDF/Excel exports timing out.
   • Fix: Switch to queued mode:

     protected function exportType(): string => 'queued';
     

   • Config: Adjust livewire-table-kit.export.queued in config/livewire-table-kit.php:

     'disk' => 'public',
     'directory' => 'exports',
     'queue' => 'default',
     

4. Sorting Quirks:

   • Issue: Custom value() columns not sortable.
   • Fix: Explicitly define the sort field:

     Column::make('Full Name')
         ->value(fn ($row) => "{$row->first_name} {$row->last_name}")
         ->sortable('full_name'); // Custom sort field
     

5. Bulk Actions:

   • Issue: actionBulkDelete not triggering.
   • Fix: Ensure supportsBulkDelete() returns true and the method is public.
   • Debug: Add logging to verify $payload contains expected IDs.

Debugging Tips

• Livewire Logs: Use $this->emit('alert', 'Debug message') in your table class.
• Filter State: Dump the current filter state:

  dd($this->filters);
  

• Query Inspection: Override query() to log the final query:

  public function query(): Builder {
      $query = User::query();
      \Log::info('Table query:', ['query' => $query->toSql(), 'bindings' => $query->getBindings()]);
      return $query;
  }
  

Extension Points

1. Custom Columns:

   • Extend Unlab\LivewireTableKit\Livewire\Components\Tables\Columns\Column for reusable column types (e.g., AvatarColumn).

2. Filter Enhancements:

   • Add Filter::custom() to support non-standard inputs (e.g., date ranges):

     Filter::custom('date_range', 'Date Range', function () {
         return view('livewire-table-kit::filters.date-range');
     })->query(function ($query, $value) {
         return $query->whereBetween('created_at', $value);
     });
     

3. Export Customization:

   • Override exportPdfTitle() or exportPdfMargins() for branded PDFs.
   • Extend the ExportService to add custom export formats (e.g., JSON).

4. AI Integration:

   • Use the MCP server for dynamic table generation:

     php artisan livewire-table-kit:install-mcp
     

   • Prompt the AI to generate table components from natural language:

     Create a Livewire table for the Order model with columns for ID, customer name, total, and status. Include filters for status and date range, and add edit/view actions.
     

Configuration Quirks

• Queued Exports:

  • Ensure the queue worker is running (php artisan queue:work).
  • Verify the export disk has write permissions.

• PDF Chunking:

  • Adjust exportPdfChunkSize() and exportPdfChunkThreshold() for large datasets:

    protected function exportPdfChunkSize(): int => 200;
    protected function exportPdfChunkThreshold(): int => 1000;
    

• Filter Toolbar:

  • Collapse filters into a dropdown for mobile:

    protected function filterToolbarMode(): string => 'dropdown';
    

Performance Tips

• Lazy Loading: Use ->lazy() on columns for large datasets:

  Column::make('Description')->lazy()->field('description');
  

• Pagination: Optimize perPageOptions() for expected dataset sizes:

  protected function perPageOptions(): array => [20, 50, 100];
  

• Export Optimization: For queued exports, pre-filter data to reduce payload size:

  protected function exportType(): string => 'queued';
  protected function exportFilename(string $ext): string {
      return "filtered_{$this->search}_{$ext}";
  }
  

---