Filament Kanban Board Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require invaders-xx/filament-kanban-board
   php artisan vendor:publish --tag="filament-kanban-board-config"

2. Register the Kanban Page: Add to your AppServiceProvider or a dedicated service provider:

   use InvadersXx\FilamentKanbanBoard\FilamentKanbanBoardPlugin;
   
   public function boot(): void
   {
       FilamentKanbanBoardPlugin::make()
           ->register();
   }
   

3. Define a Kanban Page: Create a custom page extending KanbanPage:

   use InvadersXx\FilamentKanbanBoard\Pages\KanbanPage;
   
   class MyKanbanPage extends KanbanPage
   {
       protected static ?string $navigationIcon = 'heroicon-o-rectangle-stack';
       protected static string $navigationGroup = 'Tasks';
   
       public static function getColumns(): array
       {
           return [
               'Backlog',
               'In Progress',
               'Review',
               'Done',
           ];
       }
   
       public static function getCards(): array
       {
           return [
               [
                   'id' => 1,
                   'title' => 'Task 1',
                   'column' => 'Backlog',
                   'description' => 'Description for Task 1',
               ],
               // Add more cards...
           ];
       }
   }
   

4. Register the Page: Add to filament.php under pages:

   'pages' => [
       \App\Filament\Pages\MyKanbanPage::class,
   ],
   

First Use Case

Quick Task Management: Use the Kanban board to visualize and manage tasks for a sprint or project. Start by defining columns (e.g., To Do, In Progress, Done) and populate them with cards representing tasks. Drag-and-drop cards between columns to update their status.

Implementation Patterns

Core Workflows

1. Dynamic Data Fetching: Override getCards() to fetch data dynamically from your database or API:

   public static function getCards(): array
   {
       return Task::query()
           ->select('id', 'title', 'description', 'status')
           ->get()
           ->map(fn ($task) => [
               'id' => $task->id,
               'title' => $task->title,
               'column' => $task->status,
               'description' => $task->description,
           ])
           ->toArray();
   }
   

2. Custom Card Rendering: Extend card rendering by overriding getCardView():

   public function getCardView(): string
   {
       return view('filament-kanban-board::card', [
           'card' => $this->card,
       ]);
   }
   

   Customize the blade template in resources/views/filament-kanban-board.

3. Column Customization: Define column-specific configurations:

   public static function getColumns(): array
   {
       return [
           [
               'name' => 'Backlog',
               'color' => 'gray-100',
               'width' => 25,
           ],
           // Other columns...
       ];
   }
   

4. Integration with Filament Resources: Attach the Kanban board to a Filament resource:

   use InvadersXx\FilamentKanbanBoard\Resources\Concerns\HasKanbanBoard;
   
   class TaskResource extends Resource
   {
       public static function getPages(): array
       {
           return [
               'index' => Pages\ListTasks::route('/'),
               'kanban' => Pages\KanbanTasks::route('/kanban'),
           ];
       }
   }
   
   class KanbanTasks extends KanbanPage
   {
       use HasKanbanBoard;
   
       protected static string $resource = TaskResource::class;
   }
   

Advanced Patterns

1. Real-Time Updates: Use Laravel Echo and Pusher to update the Kanban board in real-time:

   // In your KanbanPage
   public function updatedCard($cardId, $column)
   {
       Task::find($cardId)->update(['status' => $column]);
       // Broadcast update if needed
   }
   

2. Nested Cards: Implement nested cards for subtasks:

   public static function getCards(): array
   {
       return Task::with('subtasks')->get()->map(fn ($task) => [
           'id' => $task->id,
           'title' => $task->title,
           'column' => $task->status,
           'subtasks' => $task->subtasks->map(fn ($subtask) => [
               'id' => $subtask->id,
               'title' => $subtask->title,
           ]),
       ]);
   }
   

   Customize the card view to render nested items.

3. Permissions and Access Control: Restrict access to specific columns or cards:

   public function getColumns(): array
   {
       $columns = parent::getColumns();
       if (!auth()->user()->can('view_all_columns')) {
           unset($columns[2]); // Hide 'Review' column
       }
       return $columns;
   }
   

4. Export Functionality: Add export buttons to CSV/JSON:

   public function getHeaderActions(): array
   {
       return [
           Action::make('export')
               ->icon('heroicon-o-arrow-down-tray')
               ->action(fn () => $this->exportCards()),
       ];
   }
   
   protected function exportCards()
   {
       return response()->json($this->getCards());
   }
   

Gotchas and Tips

Common Pitfalls

1. Column Widths:

   • Ensure column widths sum to 100% to avoid layout issues. Default is 25% per column.
   • Example: ['width' => 20] for a narrower column.

2. Card ID Conflicts:

   • Use unique IDs for cards to avoid JavaScript errors when dragging/dropping. Database IDs are ideal.
   • Avoid duplicate IDs in getCards().

3. Performance with Large Datasets:

   • Paginate or lazy-load cards if dealing with >100 items:

     public static function getCards(): array
     {
         return Task::paginate(20)->items()->toArray();
     }
     

   • Use load() to eager-load relationships.

4. Caching:

   • Cache the getCards() result if data changes infrequently:

     public static function getCards(): array
     {
         return Cache::remember('kanban_cards', now()->addHours(1), function () {
             return Task::all()->toArray();
         });
     }
     

5. JavaScript Conflicts:

   • If using other drag-and-drop libraries, ensure no conflicts with the Kanban board's JS. Check the package's assets for dependencies.

Debugging Tips

1. Check Console for Errors:

   • Open browser dev tools (F12) to debug JavaScript errors, especially when dragging cards.

2. Verify Data Structure:

   • Ensure getCards() returns an array of associative arrays with keys: id, title, column, and optionally description, color, etc.

3. Clear Filament Cache:

   • After making changes, run:

     php artisan filament:cache-reset
     

4. Inspect Network Requests:

   • Use the Network tab to verify API calls (if using dynamic data fetching).

Extension Points

1. Custom Styling:

   • Override Tailwind classes in the published config or via CSS:

     // config/filament-kanban-board.php
     'styles' => [
         'card' => 'bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-700',
         'column' => 'bg-gray-50 dark:bg-gray-900',
     ],
     

2. Custom Actions:

   • Add context menu actions to cards:

     public function getCardActions(): array
     {
         return [
             Action::make('edit')
                 ->icon('heroicon-o-pencil')
                 ->url(fn ($card) => route('tasks.edit', $card['id'])),
         ];
     }
     

3. Event Listeners:

   • Listen for card updates:

     event(new KanbanCardUpdated($cardId, $newColumn));
     

   • Register in EventServiceProvider:

     protected $listen = [
         KanbanCardUpdated::class => [
             TaskStatusUpdated::class,
         ],
     ];
     

4. Localization:

   • Translate column names and labels:

     public static function getColumns(): array
     {
         return [
             __('filament-kanban::columns.backlog'),
             __('filament-kanban::columns.in_progress'),
         ];
     }
     

   • Publish language files:

     php artisan vendor:publish --tag="filament-kanban-board-lang"
     

5. Testing:

   • Test