Filament Advanced Choice Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require codewithdennis/filament-advanced-choice
   

   Add the CSS source to your Filament theme:

   @source '../../../../vendor/codewithdennis/filament-advanced-choice/resources/**/*.blade.php';
   

   Rebuild assets:

   npm run build
   

2. First Use Case: Replace a basic Radio or CheckboxList in a Filament form with a visually enhanced alternative. For example:

   use CodeWithDennis\FilamentAdvancedChoice\Filament\Forms\Components\RadioCard;
   
   RadioCard::make('plan')
       ->options([
           'basic' => 'Basic Plan',
           'pro' => 'Pro Plan',
       ]);
   

Where to Look First

• Documentation: Focus on the README.md for component examples and API references.
• Enum Support: Check the enum implementation section if you’re using enums for options.
• Deprecation Note: Prefer singular field classes (e.g., RadioCard) over plural aliases (e.g., RadioCards).

Implementation Patterns

Common Workflows

1. Replacing Basic Fields: Swap out Filament’s default Radio or CheckboxList for advanced variants (e.g., RadioCard for a card-based layout with descriptions and extras).

   // Before
   Radio::make('status')->options([
       'active' => 'Active',
       'inactive' => 'Inactive',
   ]);
   
   // After
   RadioCard::make('status')
       ->options([
           'active' => 'Active',
           'inactive' => 'Inactive',
       ])
       ->descriptions([
           'active' => 'User is active and logged in',
           'inactive' => 'User has not logged in recently',
       ]);
   

2. Searchable and Bulk-Actionable Lists: Use searchable() and bulkToggleable() for checkbox-based fields to improve usability in forms with many options.

   CheckboxList::make('tags')
       ->options(['php', 'laravel', 'filament', 'vue'])
       ->searchable()
       ->bulkToggleable();
   

3. Enum Integration: Leverage enums for type safety and reusable option definitions. Implement HasLabel, HasDescription, and HasExtra interfaces.

   enum UserRoleEnum: string implements HasLabel, HasDescription, HasExtra
   {
       case Admin;
       case Editor;
       case Viewer;
   
       public function getLabel(): string { return match($this) { ... }; }
       public function getDescription(): string { return match($this) { ... }; }
       public function getExtra(): ?string { return match($this) { ... }; }
   }
   
   // In form
   RadioStackedCard::make('role')
       ->options(UserRoleEnum::class);
   

4. Conditional Logic: Disable options dynamically using disableOptionWhen().

   CheckboxCard::make('permissions')
       ->options(PermissionEnum::class)
       ->disableOptionWhen(fn (string $value) => auth()->user()->cannot("manage_{$value}"));
   

5. Custom Styling: Apply colors or hide native inputs for a cleaner UI.

   RadioCard::make('priority')
       ->options(PriorityEnum::class)
       ->color(Color::Red)
       ->hiddenInputs();
   

Integration Tips

• Repeater Fields: Ensure form components within repeaters are properly initialized (tested in v1.0.6).
• Validation: Use Filament’s built-in validation rules (e.g., required, min_items) alongside the advanced fields.
• Localization: Translate labels, descriptions, and extras using Filament’s localization features.
• Testing: Test bulk actions and search functionality in forms with large option sets.

Gotchas and Tips

Pitfalls

1. CSS Theme Dependency:

   • Forgetting to add the CSS source or rebuild assets will break styling. Always run npm run build after installation.
   • Fix: Verify the @source directive is in your Filament theme file (e.g., resources/css/filament/app.css).

2. Deprecated Aliases:

   • Using plural aliases (e.g., RadioCards) may trigger deprecation warnings or break in future updates.
   • Fix: Migrate to singular classes (e.g., RadioCard).

3. Enum Implementation:

   • Missing HasExtra interface on enums will ignore the extras() method in card-based fields.
   • Fix: Ensure all enums used with card fields implement HasExtra:

     enum DeliveryTypeEnum implements HasExtra { ... }
     

4. Hidden Inputs:

   • hiddenInputs() removes native browser controls, which may affect accessibility or keyboard navigation.
   • Fix: Use visibleInputs() to revert or ensure ARIA attributes are manually added if hiding inputs.

5. Repeater Fields:

   • Components inside repeaters may not work as expected (fixed in v1.0.6). Test thoroughly if using this feature.
   • Fix: Update to the latest version and ensure repeater fields are properly configured.

6. Cursor Styles:

   • Disabled options use not-allowed cursor by default (added in v2.0.1). Overriding this requires cursorPointer().
   • Fix: Use cursorPointer() to restore default hover behavior:

     CheckboxList::make('options')->cursorPointer();
     

Debugging Tips

1. Styling Issues:

   • If styles aren’t applied, check the browser’s dev tools for 404 errors on CSS files. Ensure the @source directive is correct and assets are rebuilt.

2. Enum Not Rendering:

   • Verify the enum implements all required interfaces (HasLabel, HasDescription, HasExtra for card fields). Use dd() to inspect the enum methods:

     dd(DeliveryTypeEnum::Standard->getLabel());
     

3. Bulk Actions Not Working:

   • Ensure the field is checkbox-based (e.g., CheckboxList, CheckboxCard) and bulkToggleable() is called. Radio fields don’t support bulk actions.

4. Search Not Triggering:

   • Confirm searchable() is called and the field has at least 3 options to avoid UI glitches. Check for JavaScript errors in the console.

Extension Points

1. Custom Field Colors: Extend the Color class or use existing presets (Color::Red, Color::Blue, etc.) for theming.

2. Hidden Input Icons: Override the default heroicon-s-check-circle icon for hidden inputs:

   RadioCard::make('field')->hiddenInputIcon('heroicon-o-x-circle');
   

3. Dynamic Options: Use closures or methods to fetch options dynamically (e.g., from a database):

   CheckboxList::make('categories')
       ->options(fn () => Category::all()->pluck('name', 'id'));
   

4. Custom Layouts: Extend the package’s Blade components to create custom layouts (e.g., grid-based cards). Study the existing components in resources/views.

5. Accessibility: Add custom ARIA attributes or labels to improve accessibility for screen readers:

   RadioCard::make('field')->extraAttributes(['aria-describedby' => 'field-description']);