Livewire Table Kit Laravel Package

## Getting Started

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

2. Configure Tailwind (add to app.css or tailwind.config.js):

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

   Then run npm run build.

3. Generate a table component (replace User with your model):

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

   This auto-generates a UsersTable class with inferred columns (searchable/sortable fields, badges for booleans/statuses).

4. Use the table in a Blade view:

   @livewire('users-table')
   

First Use Case: Quick Table with Default Features

For a basic table with search, sorting, and pagination:

// app/Livewire/Tables/UsersTable.php
use Unlab\LivewireTableKit\Livewire\Components\Tables\BaseTable;

class UsersTable extends BaseTable {
    public function query() { return User::query(); }
    public function columns() { return [Column::make('Name')->field('name')->searchable()->sortable()]; }
}

This leverages the generator’s heuristics for minimal setup.

Implementation Patterns

1. Column Configuration

• Dynamic Values: Use ->value(fn($row) => ...) for computed columns (e.g., full names, formatted dates).

  Column::make('Full Name')->value(fn($row) => "{$row->first_name} {$row->last_name}")
  

• Conditional Logic: Combine with Blade views for complex rendering:

  Column::make('Status')->view('custom.status-cell')->field('status')
  

• Responsive Columns: Hide on mobile/desktop:

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

2. Filter Workflows

• Multi-Step Filtering:

  Filter::select('status', 'Status', ['active', 'pending'])
        ->display('dropdown') // UI mode
        ->placeholder('All')  // Reset option
  

• Custom Query Logic:

  Filter::text('search', 'Search')
        ->query(fn($query, $value) => $query->where('name', 'like', "%{$value}%"))
  

• Collapsible Filters: Use filterToolbarMode('dropdown') in your table class to hide filters by default.

3. Action Patterns

• Bulk Actions:

  ActionColumn::make()->actions([
      TableAction::wire('Delete Selected', fn() => $this->bulkDelete(), icon: 'trash'),
  ]);
  

• Row-Specific Actions:

  ActionColumn::make()->actions([
      TableAction::link('Edit', fn($row) => route('users.edit', $row), icon: 'pencil'),
  ]);
  

• Event-Driven Confirmations: Handle bulk delete via actionBulkDelete() and dispatch openBulkDeleteConfirm events.

4. Export Integration

• Custom Export Columns:

  public function exportColumns(): array {
      return [
          Column::make('ID')->field('id'),
          Column::make('Email')->field('email')->exportable(),
      ];
  }
  

• PDF Customization: Override methods like exportPdfTitle() or exportPdfOrientation() in your table class.

5. Reusable Components

• Extend BaseTable: Override methods like defaultSortField() or perPageOptions() for global table behavior.
• Shared Filters: Define filters in a trait and reuse across tables:

  trait SharedFilters {
      public function sharedFilters(): array {
          return [Filter::select('role', 'Role', ['admin', 'user'])];
      }
  }
  

6. AI-Assisted Development

• MCP Server: Install the MCP server for AI-driven table generation:

  php artisan livewire-table-kit:install-mcp
  

• Codex Skills: Use the packaged SKILL.md to generate tables via AI prompts (e.g., "Create a table for Order model with status filters").

Gotchas and Tips

Pitfalls

1. Flux UI Dependency:

   • The package relies on Flux UI 2+. Ensure it’s installed (composer require flux/flux) and configured in your project.
   • Fix: Add @import 'flux'; to your CSS if styles are missing.

2. Tailwind Configuration:

   • Forgetting to add the package’s views to Tailwind’s content array will break styles.
   • Fix: Verify @source in CSS or content: [...] in tailwind.config.js.

3. Generator Overrides:

   • The generator’s schema heuristics may misidentify fields (e.g., treating is_active as a badge when it’s a string).
   • Fix: Manually adjust the generated columns() method or override the make:livewire-table stub.

4. Export Dependencies:

   • CSV/XLSX/PDF exports require Maatwebsite Excel and DomPDF. Install them if exports fail:

     composer require maatwebsite/excel barryvdh/laravel-dompdf
     

5. Filter Persistence:

   • Filters reset on table refresh unless you persist them (e.g., via session or URL parameters).
   • Tip: Use use WithPagination, WithSearch, WithFilters; traits from Livewire to manage state.

6. Bulk Delete Confirmation:

   • The openBulkDeleteConfirm event requires a modal component (e.g., Flux’s Modal). Ensure your layout includes it.
   • Fix: Add @livewireScripts and @fluxScripts to your Blade layout.

Debugging Tips

1. Table Data Not Updating:

   • Check if query() returns the correct Eloquent builder. Use dd($this->query()->toSql()) to inspect the query.
   • Ensure refreshTable events are dispatched correctly (e.g., after filter changes).

2. Filter Not Applying:

   • Verify the filter’s key matches the field name in query(). Use dd($this->filters) to debug filter payloads.

3. Export Issues:

   • For PDFs, check DomPDF’s logs (storage/logs/laravel.log) for errors like missing fonts.
   • For XLSX, ensure Maatwebsite Excel is configured in config/excel.php.

4. Styling Problems:

   • Use browser dev tools to inspect Flux components. Override styles with !important if needed (e.g., for BadgeColumn colors).

Performance Tips

1. Eager Load Relationships:

   • Add with() to your query() to avoid N+1 queries:

     public function query() { return User::with('roles')->query(); }
     

2. Limit Columns in Exports:

   • Exclude non-essential columns from exports to reduce file size:

     public function exportColumns() { return array_filter($this->columns(), fn($col) => $col->isExportable()); }
     

3. Debounce Search:

   • Add a debounce to search filters to reduce database load:

     public function updatedSearch($value) {
         $this->debounce(500, fn() => $this->refreshTable());
     }
     

Extension Points

1. Custom Column Types:

   • Extend BaseColumn to create specialized columns (e.g., AvatarColumn, ProgressColumn):

     class AvatarColumn extends BaseColumn {
         public function render($value) { return "<img src='{$value}' class='h-8 w-8'>"; }
     }
     

2. Dynamic Filter Options:

   • Fetch filter options dynamically (e.g., from a database):

     Filter::select('department', 'Department', fn() => Department::pluck('name', 'id'))
     

3. Event Hooks:

   • Listen to refreshTable or notify events in your table class:

     protected $listeners = ['refreshTable' => 'logRefresh'];
     public function logRefresh() { \Log::info('Table refreshed'); }
     

4. Override Views:

   • Publish and modify the package’s Blade views (e.g., resources/views/vendor/livewire-table-kit/...) for custom UI.

5. Localization:

   • Publish the language file and override translations:

     php artisan vendor:publish --tag=livewire-table-kit-lang
     

   • Modify resources/lang/en/livewire-table-kit.php.

Config Quirks

1. Default Per-Page Options:

   • Override perPageOptions() to change pagination defaults (e.g., [5, 10, 20]).

2. Empty State Customization:

   • Modify the empty state message