### Install Flowforge Package (Composer)

Source: https://relaticle.github.io/flowforge/getting-started/installation

Installs the Flowforge package using Composer. This is the first step in the setup process.

```bash
composer require relaticle/flowforge

```

--------------------------------

### Generate Flowforge Task Board (Artisan)

Source: https://relaticle.github.io/flowforge/getting-started/installation

Creates a new Kanban board for your specified model. This command generates the necessary page and configuration for your board.

```bash
php artisan flowforge:make-board TaskBoard --model=Task

```

--------------------------------

### Install BCMath PHP Extension on Ubuntu/Debian

Source: https://relaticle.github.io/flowforge/getting-started/upgrading

This command installs the BCMath PHP extension, which is a requirement for Flowforge v3.x and v4.x due to changes in how positions are stored. This is specific to Ubuntu/Debian-based systems.

```bash
sudo apt-get install php-bcmath
```

--------------------------------

### Install Flowforge v4.x using Composer

Source: https://relaticle.github.io/flowforge/getting-started/upgrading

This command installs the latest v4.x version of the Flowforge package using Composer. Ensure you are running a compatible version of PHP and Laravel as per the upgrade requirements.

```bash
composer require relaticle/flowforge:^4.0
```

--------------------------------

### Real-World CardFlex Layout Example (PHP)

Source: https://relaticle.github.io/flowforge/essentials/customization

A practical example of using CardFlex within a card schema, combining text entries for title, description, and multiple styled entries for priority, due date, and assigned user. It showcases wrapping and justification.

```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'),
]))
```

--------------------------------

### Optimize Board Query for Performance

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Provides an example of an optimized Eloquent query for the board, including eager loading relationships and selecting only necessary fields. This helps improve board loading performance with many cards.

```php
// Optimized query example
->query(
    Task::query()
        ->with(['assignee', 'priority'])  // Eager load relationships
        ->select(['id', 'title', 'status', 'position'])  // Select only needed fields
)
```

--------------------------------

### Register Task Board Page in Filament

Source: https://relaticle.github.io/flowforge/getting-started/installation

Registers the generated TaskBoard page within your Filament admin panel configuration, making it accessible in the navigation.

```php
->pages([
    App\Filament\Pages\TaskBoard::class,
])

```

--------------------------------

### Flowforge Optional Commands

Source: https://relaticle.github.io/flowforge/getting-started/installation

Provides optional commands for Flowforge maintenance, such as repairing corrupted or missing position data.

```bash
php artisan flowforge:repair-positions

```

--------------------------------

### Enable Drag-Drop with Pagination Disabled

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Demonstrates how to programmatically load all items in a column to enable drag-and-drop functionality when pagination is active. It shows checking and loading columns.

```php
// Check if column is fully loaded
$this->isColumnFullyLoaded('todo'); // Returns false with pagination

// Load all cards programmatically
$this->loadAllItems('todo');

// Now drag-drop is enabled
$this->isColumnFullyLoaded('todo'); // Returns true
```

--------------------------------

### Include Flowforge CSS Assets (Filament Theme)

Source: https://relaticle.github.io/flowforge/getting-started/installation

Adds Flowforge CSS styles to your custom Filament theme. Requires a pre-existing custom Filament theme.

```css
@source "../../../../vendor/relaticle/flowforge/resources/views/**/*.blade.php";

```

--------------------------------

### Configure Board with Position Identifier

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Ensures cards are draggable by adding the necessary `positionIdentifier` to the board configuration. This is crucial for the drag-and-drop functionality to work correctly.

```php
public function board(Board $board): Board
{
    return $board
        ->query(Task::query())
        ->columnIdentifier('status')
        ->positionIdentifier('position')  // Required for drag-drop
        ->columns([...]);
}
```

--------------------------------

### Update Flowforge Position Service Usage (v2.x to v3.x)

Source: https://relaticle.github.io/flowforge/getting-started/upgrading

This code illustrates the changes in Flowforge's position service between v2.x and v3.x. It shows how to obtain a new position, transitioning from the `Rank` service to the `DecimalPosition` service.

```php
// Before (v2.x)
use Relaticle\Flowforge\Services\Rank;
$position = Rank::forEmptySequence()->get();
$position = Rank::after($lastRank)->get();

// After (v3.x)
use Relaticle\Flowforge\Services\DecimalPosition;
$position = DecimalPosition::forEmptyColumn();
$position = DecimalPosition::after($lastPosition);
```

--------------------------------

### Create Migration for Position Column (Artisan)

Source: https://relaticle.github.io/flowforge/getting-started/installation

Generates a new migration file to add the 'position' column to your database table, which is essential for Flowforge's drag-and-drop functionality.

```bash
php artisan make:migration add_position_to_tasks_table

```

--------------------------------

### Flowforge Diagnostic and Rebalancing Commands

Source: https://relaticle.github.io/flowforge/getting-started/upgrading

Flowforge v3.x introduces new Artisan commands for managing item positions. `diagnose-positions` checks for inconsistencies, while `rebalance-positions` redistributes positions to ensure proper ordering.

```bash
php artisan flowforge:diagnose-positions   # Check for issues
php artisan flowforge:rebalance-positions  # Redistribute positions
```

--------------------------------

### Update Flowforge Position Service Usage (v2.x to v4.x)

Source: https://relaticle.github.io/flowforge/getting-started/upgrading

This code shows the refactoring required when migrating from Flowforge v2.x to v4.x. It demonstrates the change in how to obtain a position value, moving from the `Rank` service to the `DecimalPosition` service.

```php
// Before (v2.x)
use Relaticle\Flowforge\Services\Rank;
$position = Rank::forEmptySequence()->get();

// After (v4.x)
use Relaticle\Flowforge\Services\DecimalPosition;
$position = DecimalPosition::forEmptyColumn();
```

--------------------------------

### Verify Database Schema with PHP Artisan

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Checks the status of database migrations using the `php artisan migrate:status` command. This helps in understanding which migrations have been applied and which are pending.

```bash
php artisan migrate:status
```

--------------------------------

### Debug Empty Board by Dumping Data

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Temporarily adds a `dd()` call to the board method to inspect the data being retrieved by the Eloquent query. This helps verify if data exists and is being fetched correctly.

```php
// Add to board method temporarily
dd($this->getEloquentQuery()->get());
```

--------------------------------

### Add Position Column to Database Table (PHP)

Source: https://relaticle.github.io/flowforge/getting-started/installation

Applies the 'position' column to your database table using the generated migration. This column is automatically handled for database-specific collations.

```php
Schema::table('tasks', function (Blueprint $table) {
    $table->flowforgePositionColumn('position'); // Handles database-specific collations automatically
});

```

--------------------------------

### Add Flowforge Position Column to Existing Table (PHP)

Source: https://relaticle.github.io/flowforge/essentials/database-schema

Provides an example migration to add a `flowforgePositionColumn` to an existing 'tasks' table, including an optional unique constraint for concurrent safety.

```php
<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('tasks', function (Blueprint $table) {
            $table->flowforgePositionColumn('position');

            // Recommended: Add unique constraint for concurrent safety
            $table->unique(['status', 'position'], 'unique_position_per_column');
        });
    }

    public function down(): void
    {
        Schema::table('tasks', function (Blueprint $table) {
            $table->dropUnique('unique_position_per_column');
            $table->dropColumn('position');
        });
    }
};
```

--------------------------------

### Test Livewire Drag and Drop Functionality in PHP

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

A temporary Livewire component method for testing drag and drop functionality. It moves a task to 'in_progress' status and uses `dd()` to display the updated status.

```php
// Add to board component temporarily
public function testDragDrop()
{
    $task = Task::first();
    $this->moveCard($task->id, 'in_progress');
    dd($task->fresh()->status);
}
```

--------------------------------

### Implement Required Traits for Actions

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Ensures that the component uses the `InteractsWithActions` and `InteractsWithForms` traits, which are necessary for card and column actions to function properly within Flowforge.

```php
class TaskBoard extends BoardPage
{
    use InteractsWithActions;  // Required
    use InteractsWithForms;   // Required
    
    public function board(Board $board): Board
    {
        return $board
            ->cardActions([
                EditAction::make()->model(Task::class),  // Model required
            ]);
    }
}
```

--------------------------------

### Pagination Control - Livewire

Source: https://relaticle.github.io/flowforge/essentials/api-reference

Offers Livewire methods for managing card pagination within columns. This includes loading more cards, loading all cards to enable reordering, checking if all cards are loaded, and getting the position for new cards.

```php
// Load more cards for pagination
$this->loadMoreItems(string $columnId, ?int $count = null)

// Load all cards to enable reordering
$this->loadAllItems(string $columnId)

// Check if all cards are loaded
$this->isColumnFullyLoaded(string $columnId): bool

// Get position for new card in column
$this->getBoardPositionInColumn(string $columnId): string

```

--------------------------------

### Run Flowforge Position Repair Command

Source: https://relaticle.github.io/flowforge/getting-started/upgrading

After performing database schema changes related to the position column, this Artisan command should be run. It helps repair and re-index positions, especially after a quick upgrade or if using the 'regenerate' strategy.

```bash
php artisan flowforge:repair-positions
```

--------------------------------

### Ensure Query Returns Records for Board

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Checks for potential issues like global scopes or soft deletes that might prevent the query from returning records for the board. It suggests using `withoutGlobalScopes()` to bypass these.

```php
// Check for global scopes, soft deletes, etc.
->query(Task::withoutGlobalScopes()->get())
```

--------------------------------

### Clear View Cache with PHP Artisan

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Clears the application's view cache using the `php artisan view:clear` command. This is useful when changes to Blade views are not reflecting correctly.

```bash
php artisan view:clear
```

--------------------------------

### Include Flowforge Views in Theme CSS

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Specifies the CSS import rule required in your theme's CSS file to ensure Flowforge components are correctly styled. This prevents styling issues and broken layouts.

```css
/* Required in your theme CSS file */
@source "../../../../vendor/relaticle/flowforge/resources/views/**/*.blade.php";
```

--------------------------------

### Include Filament Assets in Layout

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Ensures that Filament's CSS and JavaScript assets are included in your application's layout. This is necessary for Flowforge's Alpine components and action modals to function correctly.

```html
{{-- Required in your layout --}}
<head>
    @filamentStyles
</head>
<body>
    {{ $slot }}
    @filamentScripts
</body>
```

--------------------------------

### Upgrade Position Column (Preserve Order)

Source: https://relaticle.github.io/flowforge/getting-started/upgrading

This PHP code snippet provides a method to upgrade the 'position' column while preserving the existing order of items. It involves adding a temporary new column, copying data, swapping columns, and then running a repair command.

```php
public function up(): void
{
    // Add temporary column
    Schema::table('tasks', function (Blueprint $table) {
        $table->decimal('position_new', 20, 10)->nullable();
    });

    // Copy order (positions will be regenerated by repair command)
    DB::statement('UPDATE tasks SET position_new = CAST(position AS DECIMAL(20,10))');

    // Swap columns
    Schema::table('tasks', function (Blueprint $table) {
        $table->dropColumn('position');
    });
    Schema::table('tasks', function (Blueprint $table) {
        $table->renameColumn('position_new', 'position');
    });
}
```

--------------------------------

### Upgrade Position Column (Quick - Resets Order)

Source: https://relaticle.github.io/flowforge/getting-started/upgrading

This PHP code snippet demonstrates a quick method to upgrade the 'position' column in your database schema to support Flowforge v3.x/v4.x. This approach drops the existing column and adds a new one using the `flowforgePositionColumn()` macro, which resets the order of items.

```php
public function up(): void
{
    Schema::table('tasks', function (Blueprint $table) {
        $table->dropColumn('position');
    });

    Schema::table('tasks', function (Blueprint $table) {
        $table->flowforgePositionColumn();
    });
}
```

--------------------------------

### Add Position Generation in Create Action

Source: https://relaticle.github.io/flowforge/essentials/troubleshooting

Modifies the form data during creation to include the correct status and position for new cards, especially when created via column actions. This prevents cards from appearing in random positions.

```php
CreateAction::make()
    ->mutateFormDataUsing(function (array $data, array $arguments): array {
        if (isset($arguments['column'])) {
            $data['status'] = $arguments['column'];
            $data['position'] = $this->getBoardPositionInColumn($arguments['column']);
        }
        return $data;
    })
```

--------------------------------

### Configure Board Essentials - PHP

Source: https://relaticle.github.io/flowforge/essentials/api-reference

Sets up the essential configuration for a Flowforge board, including the data source, column identifier, position identifier, and defining the board's columns. This is a required step for basic board functionality.

```php
public function board(Board $board): Board
{
    return $board
        ->query(Task::query())                    // Required: Data source
        ->columnIdentifier('status')              // Required: Column field
        ->positionIdentifier('position')          // Required: Position field
        ->columns([
            Column::make('todo')->label('To Do')->color('gray'),
            Column::make('done')->label('Done')->color('green'),
        ]);
}

```

--------------------------------

### Integrate Kanban Board with Filament Resource

Source: https://relaticle.github.io/flowforge/essentials/integration-patterns

This snippet shows how to create a Kanban board view for a Filament resource, specifically for campaign tasks. It defines the board's columns, query logic to fetch tasks for the current campaign and user's team, and registers the new board page within the resource's routes. Dependencies include the Filament framework and Flowforge components.

```php
<?php

namespace App\Filament\Resources\CampaignResource\Pages;

use App\Filament\Resources\CampaignResource;
use Relaticle\Flowforge\Board;
use Relaticle\Flowforge\BoardResourcePage;
use Relaticle\Flowforge\Column;

class CampaignTaskBoard extends BoardResourcePage
{
    protected static string $resource = CampaignResource::class;
    
    public function board(Board $board): Board
    {
        return $board
            ->query(
                // Get tasks for this specific campaign and current user's team
                $this->getRecord()
                    ->tasks()
                    ->whereHas('team', fn($q) => $q->where('id', auth()->user()->current_team_id))
                    ->getQuery()
            )
            ->columnIdentifier('status')
            ->positionIdentifier('position')
            ->columns([
                Column::make('backlog')->label('Backlog')->color('gray'),
                Column::make('in_progress')->label('In Progress')->color('blue'),
                Column::make('review')->label('Review')->color('amber'),
                Column::make('completed')->label('Completed')->color('green'),
            ]);
    }
}

// Register in your CampaignResource
public static function getPages(): array
{
    return [
        'index' => Pages\ListCampaigns::route('/'),
        'create' => Pages\CreateCampaign::route('/create'),
        'edit' => Pages\EditCampaign::route('/{record}/edit'),
        'tasks' => Pages\CampaignTaskBoard::route('/{record}/tasks'), // Add this line
    ];
}

```

--------------------------------

### Implement Search and Filtering for Kanban Boards (PHP)

Source: https://relaticle.github.io/flowforge/essentials/customization

Enables search and filtering capabilities for Kanban boards. It includes searching by title, description, and assignee name, and provides filters for priority (multi-select) and assigned user (relationship-based), plus an 'overdue' toggle filter.

```php
use Filament\Tables\Filters\SelectFilter;
use Filament\Tables\Filters\Filter;

public function board(Board $board): Board
{
    return $board
        ->searchable(['title', 'description', 'assignee.name'])
        ->filters([
            SelectFilter::make('priority')
                ->options(['low' => 'Low', 'medium' => 'Medium', 'high' => 'High'])
                ->multiple(),
            SelectFilter::make('assigned_to')
                ->relationship('assignee', 'name')
                ->searchable()
                ->preload(),
            Filter::make('overdue')
                ->label('Overdue')
                ->query(fn (Builder $query) => $query->where('due_date', '<', now()))
                ->toggle(),
        ]);
}
```

--------------------------------

### Configure Column Appearance with Colors (PHP)

Source: https://relaticle.github.io/flowforge/essentials/customization

Demonstrates how to configure a column's appearance, specifically setting its color using various supported formats. This includes using string-based Tailwind CSS color names, Filament Color constants, semantic color names, and custom hex color codes.

```php
use Filament\Support\Colors\Color;

Column::make('todo')
    ->label('To Do')
    ->color('gray')        // Supports multiple color formats
    ->icon('heroicon-o-queue-list')
```

```php
use Filament\Support\Colors\Color;

Column::make('todo')->color(Color::Gray)
Column::make('in_progress')->color(Color::Blue)
Column::make('done')->color(Color::Green)
```

```php
Column::make('todo')->color('gray')
Column::make('in_progress')->color('blue')
Column::make('done')->color('green')
```

```php
Column::make('urgent')->color('#ff0000')
Column::make('normal')->color('#3b82f6')
Column::make('completed')->color('#22c55e')
```

```php
use Filament\Support\Colors\Color;

->columns([
    Column::make('todo')
        ->color('gray'),                    // Tailwind color name
    Column::make('in_progress')
        ->color(Color::Blue),                // Color constant
    Column::make('review')
        ->color('primary'),                  // Semantic color
    Column::make('done')
        ->color('#22c55e'),                  // Custom hex
])
```

--------------------------------

### Arrange Card Elements with CardFlex Layout (PHP)

Source: https://relaticle.github.io/flowforge/essentials/customization

Demonstrates using the CardFlex component to arrange multiple elements within a card in a flexible row that wraps on smaller screens. It allows for justification and alignment of elements.

```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'
]))
```

--------------------------------

### PHP Livewire Event Listeners for Kanban

Source: https://relaticle.github.io/flowforge/essentials/api-reference

Listen to Kanban events like 'kanban-card-moved' and 'kanban-items-loaded' using Livewire's #[On] attribute. These methods allow custom logic execution based on specific Kanban interactions, such as updating analytics or tracking loading progress.

```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
}
```

--------------------------------

### Add Column Actions for Card Creation (PHP)

Source: https://relaticle.github.io/flowforge/essentials/customization

Implements column actions for Kanban boards, specifically a 'CreateAction' to add new tasks. It configures the action with a form including text input for title and a select input for priority, with data mutation for status and position.

```php
use Filament\Actions\CreateAction;
use Filament\Forms\Components\TextInput;
use Filament\Forms\Components\Select;

public function board(Board $board): Board
{
    return $board
        ->columnActions([
            CreateAction::make()
                ->label('Add Task')
                ->model(Task::class)
                ->form([
                    TextInput::make('title')->required(),
                    Select::make('priority')
                        ->options(['low' => 'Low', 'medium' => 'Medium', 'high' => 'High'])
                        ->default('medium'),
                ])
                ->mutateFormDataUsing(function (array $data, array $arguments): array {
                    if (isset($arguments['column'])) {
                        $data['status'] = $arguments['column'];
                        $data['position'] = $this->getBoardPositionInColumn($arguments['column']);
                    }
                    return $data;
                }),
        ]);
}
```

--------------------------------

### Configure Board Content - PHP

Source: https://relaticle.github.io/flowforge/essentials/api-reference

Enhances board configuration by defining the attribute used for card titles and setting up rich card content using a schema. This allows for more detailed and structured information to be displayed on each card.

```php
->recordTitleAttribute('title')                   // Card title field
->cardSchema(fn(Schema $schema) => $schema        // Rich card content
    ->components([
        TextEntry::make('description'),
        TextEntry::make('due_date')->date(),
    ])
)

```

--------------------------------

### Generate Task Positions with Factory (PHP)

Source: https://relaticle.github.io/flowforge/essentials/database-schema

Illustrates how to integrate Flowforge's `DecimalPosition` service into a Laravel factory to generate correct position values for tasks, ensuring proper ordering.

```php
use Relaticle\Flowforge\Services\DecimalPosition;

class TaskFactory extends Factory
{
    /** @var array<string, string> Track last position per status */
    private static array $lastPositions = [];

    public function definition(): array
    {
        $status = $this->faker->randomElement(['todo', 'in_progress', 'done']);

        return [
            'title' => $this->faker->sentence(3),
            'status' => $status,
            'position' => $this->generatePositionForStatus($status),
        ];
    }

    private function generatePositionForStatus(string $status): string
    {
        if (!isset(self::$lastPositions[$status])) {
            $position = DecimalPosition::forEmptyColumn();
        } else {
            $position = DecimalPosition::after(self::$lastPositions[$status]);
        }

        self::$lastPositions[$status] = $position;

        return $position;
    }
}
```

--------------------------------

### Configure Board Actions - PHP

Source: https://relaticle.github.io/flowforge/essentials/api-reference

Adds interactive elements to the board by defining actions for cards and column headers. This includes actions like editing, deleting cards, and creating new items within columns, making the board more dynamic.

```php
->cardActions([
    EditAction::make()->model(Task::class),
    DeleteAction::make()->model(Task::class),
])
->columnActions([
    CreateAction::make()->model(Task::class),
])
->cardAction('edit')                              // Make cards clickable

```

--------------------------------

### Standalone Livewire Task Board Component (PHP)

Source: https://relaticle.github.io/flowforge/essentials/integration-patterns

This Livewire component creates a standalone task board using Flowforge. It requires Filament packages and specific layout configurations. The component defines the board's columns and data source.

```php
<?php

namespace App\Livewire;

use App\Models\Task;
use Filament\Actions\Concerns\InteractsWithActions;
use Filament\Actions\Contracts\HasActions;
use Filament\Forms\Concerns\InteractsWithForms;
use Filament\Forms\Contracts\HasForms;
use Livewire\Component;
use Relaticle\Flowforge\Board;
use Relaticle\Flowforge\Column;
use Relaticle\Flowforge\Concerns\InteractsWithBoard;
use Relaticle\Flowforge\Contracts\HasBoard;

class TaskBoard extends Component implements HasBoard, HasActions, HasForms
{
    use InteractsWithActions;
    use InteractsWithBoard {
        InteractsWithBoard::getDefaultActionRecord insteadof InteractsWithActions;
    }
    use InteractsWithForms;

    public function board(Board $board): Board
    {
        return $board
            ->query(Task::query())
            ->columnIdentifier('status')
            ->positionIdentifier('position')
            ->columns([
                Column::make('todo')->label('To Do')->color('gray'),
                Column::make('in_progress')->label('In Progress')->color('blue'),
                Column::make('completed')->label('Completed')->color('green'),
            ]);
    }

    public function render()
    {
        return view('livewire.task-board');
    }
}

```

--------------------------------

### Diagnose Flowforge Positions Command (Bash)

Source: https://relaticle.github.io/flowforge/essentials/database-schema

Shows how to use the `flowforge:diagnose-positions` artisan command to check for and identify issues like gaps, inversions, or duplicates in task positions.

```bash
php artisan flowforge:diagnose-positions \
    --model=App\\Models\\Task \
    --column=status \
    --position=position
```

--------------------------------

### Integrate PHP BackedEnum for Task Status (PHP)

Source: https://relaticle.github.io/flowforge/essentials/database-schema

Demonstrates how to use PHP BackedEnums for the 'status' field in a 'Task' model, allowing Flowforge to automatically map column identifiers to enum values.

```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
```

--------------------------------

### Configure Board Search and Filtering - PHP

Source: https://relaticle.github.io/flowforge/essentials/api-reference

Implements search and filtering capabilities for the board, allowing users to find specific cards based on various fields and criteria. It also configures the layout, width, and number of columns for the filter panel.

```php
use Filament\Tables\Enums\FiltersLayout;
use Filament\Support\Enums\Width;

->searchable(['title', 'description'])            // Enable search
->filters([
    SelectFilter::make('priority'),
    Filter::make('overdue')->query(fn($q) =>
        $q->where('due_date', '<', now())
    ),
])
->filtersLayout(FiltersLayout::AboveContent)      // Display filters above board
->filtersFormWidth(Width::Large)                  // Filter panel width
->filtersFormColumns(3)                           // Columns in filter form

```

--------------------------------

### JavaScript Livewire Event Listeners for Kanban

Source: https://relaticle.github.io/flowforge/essentials/api-reference

Implement JavaScript listeners for Livewire Kanban events, such as 'kanban-card-moved'. This allows for client-side interactions and logging when specific Kanban actions occur, like a card being moved. The listener is set up within the 'livewire:init' event.

```javascript
document.addEventListener('livewire:init', () => {
    Livewire.on('kanban-card-moved', ({ cardId, columnId }) => {
        console.log(`Card ${cardId} moved to ${columnId}`);
    });
});
```

--------------------------------

### Standalone Livewire Layout Configuration (PHP)

Source: https://relaticle.github.io/flowforge/essentials/integration-patterns

This PHP code snippet demonstrates how to configure a Livewire component to use a specific Blade layout. It ensures that Filament's assets are included in the layout, which are necessary for Flowforge components to function correctly.

```php
public function render()
{
    return view('livewire.task-board')
        ->layout('components.layouts.app');
}

```

--------------------------------

### Filament Layout App Configuration (Blade)

Source: https://relaticle.github.io/flowforge/essentials/integration-patterns

This Blade snippet shows the essential structure of a Filament layout file (`app.blade.php`). It includes directives for `@filamentStyles` and `@filamentScripts`, which are crucial for loading Filament's CSS and JavaScript, including dependencies like Alpine.js required by Flowforge.

```blade
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    @filamentStyles
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body class="antialiased">
    {{ $slot }}

    @filamentScripts
</body>
</html>

```

--------------------------------

### Customize Record Fetching in Flowforge Board

Source: https://relaticle.github.io/flowforge/essentials/integration-patterns

This PHP code overrides the `getBoardRecords` method to implement custom filtering and eager loading for board records. It fetches records for a specific column, applies a team ID filter, and eagerly loads associated relationships like 'assignee', 'priority', and 'labels'. This allows for more complex data retrieval logic than the default implementation. It requires extending the `BoardResourcePage` class.

```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();
}

```

--------------------------------

### Standalone Livewire Task Board View (Blade)

Source: https://relaticle.github.io/flowforge/essentials/integration-patterns

This Blade view renders the task board component. It includes a heading and displays the board instance provided by the Livewire component. This is the frontend representation of the task board.

```blade
{{-- resources/views/livewire/task-board.blade.php --}}
<div>
    <h1 class="text-2xl font-bold mb-6">Task Board</h1>
    {{ $this->board }}
</div>

```

--------------------------------

### Add Card Actions for Editing and Deleting (PHP)

Source: https://relaticle.github.io/flowforge/essentials/customization

Configures actions for individual cards, including 'EditAction' and 'DeleteAction' for the Task model. It also sets the cards to be clickable for editing.

```php
use Filament\Actions\EditAction;
use Filament\Actions\DeleteAction;

public function board(Board $board): Board
{
    return $board
        ->cardActions([
            EditAction::make()->model(Task::class),
            DeleteAction::make()->model(Task::class),
        ])
        ->cardAction('edit'); // Makes cards clickable
}
```

--------------------------------

### Customize Kanban Card Content with Filament Schema Components (PHP)

Source: https://relaticle.github.io/flowforge/essentials/customization

Defines the schema for Kanban cards using Filament's TextEntry components to display priority, due date, and assignee information. It utilizes badges and icons for better visual representation.

```php
use Filament\Infolists\Components\TextEntry;
use Filament\Schemas\Schema;

public function board(Board $board): Board
{
    return $board
        ->cardSchema(fn (Schema $schema) => $schema->components([
            TextEntry::make('priority')->badge()->color(fn ($state) => match($state) {
                'high' => 'danger',
                'medium' => 'warning',
                'low' => 'success',
                default => 'gray'
            }),
            TextEntry::make('due_date')->date()->icon('heroicon-o-calendar'),
            TextEntry::make('assignee.name')->icon('heroicon-o-user'),
        ]));
}
```

--------------------------------

### Configure Column Display - PHP

Source: https://relaticle.github.io/flowforge/essentials/api-reference

Customizes the appearance and behavior of individual columns on the board. This includes setting a display name, applying a color theme, and associating an icon with the column header.

```php
Column::make('identifier')
    ->label('Display Name')                       // Column header text
    ->color('blue')                              // Column color theme
    ->icon('heroicon-o-flag')                    // Column header icon

```

--------------------------------

### Create Tasks Table Schema with Flowforge Columns (PHP)

Source: https://relaticle.github.io/flowforge/essentials/database-schema

Defines the necessary fields for a 'tasks' table to support Kanban functionality, including a unique `flowforgePositionColumn` for drag-and-drop ordering.

```php
Schema::create('tasks', function (Blueprint $table) {
    $table->id();
    $table->string('title');                         // Card title
    $table->string('status');                        // Column identifier
    $table->flowforgePositionColumn();               // Drag-and-drop ordering
    $table->timestamps();
});
```

--------------------------------

### Filament Page Task Board Component (PHP)

Source: https://relaticle.github.io/flowforge/essentials/integration-patterns

This PHP code defines a Filament Page component for a task board. It extends Flowforge's `BoardPage` and configures the board's data source and columns. This is suitable for dedicated Kanban pages within a Filament admin panel.

```php
<?php

namespace App\Filament\Pages;

use App\Models\Task;
use Relaticle\Flowforge\Board;
use Relaticle\Flowforge\BoardPage;
use Relaticle\Flowforge\Column;

class TaskBoard extends BoardPage
{
    protected static ?string $navigationIcon = 'heroicon-o-view-columns';
    
    public function board(Board $board): Board
    {
        return $board
            ->query(Task::query())
            ->columnIdentifier('status')
            ->positionIdentifier('position')
            ->columns([
                Column::make('todo')->label('To Do')->color('gray'),
                Column::make('in_progress')->label('In Progress')->color('blue'),
                Column::make('completed')->label('Completed')->color('green'),
            ]);
    }
}

```

--------------------------------

### Move Card Between Columns - Livewire

Source: https://relaticle.github.io/flowforge/essentials/api-reference

Provides a Livewire method to programmatically move a card from one column to another. It allows specifying the target column and optionally the position relative to other cards.

```php
// Move card between columns
$this->moveCard(string $cardId, string $targetColumnId, ?string $afterCardId = null, ?string $beforeCardId = null)

```

--------------------------------

### Customize Card Movement Logic in Flowforge Board

Source: https://relaticle.github.io/flowforge/essentials/integration-patterns

This PHP snippet demonstrates how to override the `moveCard` method in a Flowforge board to add custom logic when a card is moved between columns. It first calls the parent method to handle the actual card movement and then implements specific actions, such as updating a task's completion timestamp and notifying the assignee when a task is moved to the 'completed' column. This requires extending the `BoardResourcePage` class.

```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));
    }
}

```

--------------------------------

### Customize Record Counting in Flowforge Board

Source: https://relaticle.github.io/flowforge/essentials/integration-patterns

This PHP snippet overrides the `getBoardRecordCount` method to provide custom logic for counting records within a board column. It specifically excludes archived records from the count, allowing for more refined reporting. This method is useful when the default count does not meet specific business requirements. It requires extending the `BoardResourcePage` class.

```php
public function getBoardRecordCount(string $columnId): int
{
    return $this->getEloquentQuery()
        ->where($this->getBoard()->getColumnIdentifier(), $columnId)
        ->where('is_archived', false)  // Exclude archived from count
        ->count();
}

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.