docs: add CardFlex, events, filter options, override patterns, enum support

Author: ManukMinasyan

docs/content/2.essentials/1.integration-patterns.md

@@ -153,5 +153,62 @@ public static function getPages(): array
 }
 ```
 
-**Use when:** Adding Kanban views to existing Filament resources  
+**Use when:** Adding Kanban views to existing Filament resources
 **Benefits:** Inherits resource permissions, policies, and global scopes automatically
+
+## Extending Board Behavior
+
+Override these methods to customize board behavior for your specific needs.
+
+### Custom Card Movement Logic
+
+Override `moveCard()` to add custom logic when cards are moved:
+
+```php
+public function moveCard(
+    string $cardId,
+    string $targetColumnId,
+    ?string $afterCardId = null,
+    ?string $beforeCardId = null
+): void {
+    // Call parent to handle the actual move
+    parent::moveCard($cardId, $targetColumnId, $afterCardId, $beforeCardId);
+
+    // Add custom logic
+    $task = Task::find($cardId);
+
+    if ($targetColumnId === 'completed') {
+        $task->update(['completed_at' => now()]);
+        $task->assignee->notify(new TaskCompletedNotification($task));
+    }
+}
+```
+
+### Custom Record Fetching
+
+Override `getBoardRecords()` for complex filtering logic:
+
+```php
+public function getBoardRecords(string $columnId): \Illuminate\Support\Collection
+{
+    return $this->getEloquentQuery()
+        ->where($this->getBoard()->getColumnIdentifier(), $columnId)
+        ->where('team_id', auth()->user()->current_team_id)  // Custom filter
+        ->with(['assignee', 'priority', 'labels'])           // Eager loading
+        ->orderBy($this->getBoard()->getPositionIdentifier())
+        ->get();
+}
+```
+
+### Custom Count Logic
+
+Override `getBoardRecordCount()` if you need custom counting:
+
+```php
+public function getBoardRecordCount(string $columnId): int
+{
+    return $this->getEloquentQuery()
+        ->where($this->getBoard()->getColumnIdentifier(), $columnId)
+        ->where('is_archived', false)  // Exclude archived from count
+        ->count();
+}

docs/content/2.essentials/2.customization.md

@@ -31,6 +31,61 @@ public function board(Board $board): Board
 }
 ```
 
+## CardFlex Layout
+
+Use `CardFlex` to arrange multiple elements in a flexible row with intelligent wrapping:
+
+```php
+use Filament\Infolists\Components\TextEntry;
+use Filament\Infolists\Components\ImageEntry;
+use Relaticle\Flowforge\Components\CardFlex;
+
+->cardSchema(fn (Schema $schema) => $schema->components([
+    TextEntry::make('title')->weight('bold'),
+    CardFlex::make([
+        TextEntry::make('priority')->badge(),
+        TextEntry::make('due_date')->icon('heroicon-o-calendar'),
+        ImageEntry::make('assignee.avatar_url')->circular()->size(24),
+    ])
+        ->wrap()              // Enable wrapping on small screens
+        ->justify('between')  // Horizontal: 'start', 'end', 'between', 'center'
+        ->align('center'),    // Vertical: 'start', 'end', 'center'
+]))
+```
+
+### CardFlex Options
+
+| Method | Description | Default |
+|--------|-------------|---------|
+| `wrap(bool $wrap = true)` | Enable/disable wrapping | `false` |
+| `justify(string $justify)` | Horizontal alignment | `'start'` |
+| `align(string $align)` | Vertical alignment | `'start'` |
+
+### Real-World Example
+
+```php
+->cardSchema(fn (Schema $schema) => $schema->components([
+    TextEntry::make('title')
+        ->weight('bold')
+        ->size('lg'),
+    TextEntry::make('description')
+        ->limit(100)
+        ->color('gray'),
+    CardFlex::make([
+        TextEntry::make('priority')
+            ->badge()
+            ->icon('heroicon-o-flag'),
+        TextEntry::make('due_date')
+            ->badge()
+            ->date()
+            ->icon('heroicon-o-calendar'),
+        TextEntry::make('assignedTo.name')
+            ->badge()
+            ->icon('heroicon-o-user'),
+    ])->wrap()->justify('start'),
+]))
+```
+
 ## Column Actions
 
 Add actions to column headers for creating new cards or bulk operations:

docs/content/2.essentials/3.database-schema.md

@@ -19,6 +19,37 @@ Schema::create('tasks', function (Blueprint $table) {
 });
 ```
 
+## Enum Support
+
+Flowforge automatically handles PHP `BackedEnum` for status fields. No manual conversion needed:
+
+```php
+// Define your enum
+enum TaskStatus: string
+{
+    case Todo = 'todo';
+    case InProgress = 'in_progress';
+    case Done = 'done';
+}
+
+// Cast in your model
+class Task extends Model
+{
+    protected $casts = [
+        'status' => TaskStatus::class,
+    ];
+}
+
+// Flowforge automatically converts column IDs to enum values
+Column::make('todo')      // → TaskStatus::Todo
+Column::make('in_progress') // → TaskStatus::InProgress
+Column::make('done')      // → TaskStatus::Done
+```
+
+::callout{type="info"}
+When a card moves between columns, Flowforge detects the `BackedEnum` cast and converts the column identifier to the appropriate enum value automatically.
+::
+
 ## Position Column
 
 The `flowforgePositionColumn()` method creates a `DECIMAL(20,10)` column for drag-and-drop functionality:

docs/content/2.essentials/4.api-reference.md

@@ -20,6 +20,9 @@ navigation:
 | `searchable(array)` | Enable search on specified fields | |
 | `filters(array)` | Add filtering capabilities | |
 | `cardAction(string)` | Make cards clickable with action | |
+| `cardsPerColumn(int)` | Cards to load per column (pagination) | |
+| `filtersFormWidth(Width)` | Filter panel width | |
+| `filtersFormColumns(int)` | Columns in filter form | |
 
 ## Board Methods
 
@@ -125,7 +128,45 @@ $this->getBoardPositionInColumn(string $columnId): string
 ## Performance Features
 
 - **Intelligent Pagination**: Efficiently handles 100+ cards per column
-- **Infinite Scroll**: Smooth loading with 80% scroll threshold  
+- **Infinite Scroll**: Smooth loading with 80% scroll threshold
 - **Optimistic UI**: Immediate feedback with rollback on errors
 - **Fractional Ranking**: Prevents database locks during reordering
-- **Query Optimization**: Cursor-based pagination with eager loading
+- **Query Optimization**: Cursor-based pagination with eager loading
+
+## Livewire Events
+
+Flowforge dispatches these events for frontend integration and custom logic:
+
+| Event | Payload | When Fired |
+|-------|---------|------------|
+| `kanban-card-moved` | `cardId`, `columnId`, `position` | After a card is moved |
+| `kanban-items-loaded` | `columnId`, `loadedCount`, `totalCount`, `isFullyLoaded` | After pagination loads more cards |
+| `kanban-all-items-loaded` | `columnId`, `totalCount` | After "Load All" completes |
+
+### Listening to Events
+
+```php
+use Livewire\Attributes\On;
+
+#[On('kanban-card-moved')]
+public function onCardMoved(string $cardId, string $columnId, string $position): void
+{
+    // Custom logic when a card moves (e.g., send notification, update analytics)
+}
+
+#[On('kanban-items-loaded')]
+public function onItemsLoaded(string $columnId, int $loadedCount, int $totalCount, bool $isFullyLoaded): void
+{
+    // Track loading progress
+}
+```
+
+### JavaScript Listeners
+
+```javascript
+document.addEventListener('livewire:init', () => {
+    Livewire.on('kanban-card-moved', ({ cardId, columnId }) => {
+        console.log(`Card ${cardId} moved to ${columnId}`);
+    });
+});
+```