Architecture

This document describes the real architecture of tonegabes/filament-better-options as implemented in the source code.

High-level overview

flowchart LR
    UserComponent[Checkbox or Radio Component] --> View[Blade view]
    View --> Indicator[option-indicator]
    View --> IconSVG["[@svg](https://github.com/svg) optional"]
    View --> Content[checkbox.content]
    UserComponent -.uses.-> Traits[HasIndicator, HasOptionIcon, HasOptionColor, HasBetterDescriptions, HasExtraTexts, HasItemsCenter]
    Traits --> IconManager[IconManagerService]
    IconManager --> Resolver[IconResolverService]
    Resolver -->|when installed| Phosphor[Phosphor enum]
    Resolver -->|fallback| Heroicons[Heroicons aliases]
    Traits --> Config[better-options config]

Components

Four form components are provided, split in two families and two styles:

Each component is a thin subclass of the Filament native CheckboxList/Radio (or a Field for RadioCards where HasColumns is required) that applies additional traits and sets its view plus a pair of {componentType, componentStyle} for default resolution.

Traits (src/Concerns/)

All visibility toggles accept Closure evaluation via Filament's evaluate().

Enums (src/Enums/)

• ComponentTypes: Checkbox, Radio.
• ComponentStyles: List, Cards.

These are used together by IconManagerService, HasIndicator and HasOptionIcon to look up configuration defaults like icon/indicator positions per {componentType, componentStyle} combination.

Services (src/Services/)

• IconResolverService: detects whether tonegabes/filament-phosphor-icons is installed and, if not, falls back to Heroicons aliases. Consumers can register custom defaults via config('better-options.icons.defaults').
• IconManagerService: resolves the idle/selected indicator icon for a given ComponentTypes + state (idle/selected), delegating to IconResolverService and supporting Filament FilamentIcon::resolve() aliases.

Contracts (src/Contracts/)

• HasExtraText: optional enum-level contract for providing an "extra" string per case.

Configuration (config/better-options.php)

return [
    'components' => [
        'checkbox' => [
            'list'          => [ 'icon_position' => 'after',  'indicator_position' => 'before' ],
            'cards'         => [ 'icon_position' => 'before', 'indicator_position' => 'after'  ],
        ],
        'radio' => [ /* same shape */ ],
    ],
    'icons' => [
        'defaults' => [
            // optional overrides of the built-in icon set
            // 'checkbox_idle' => 'heroicon-o-square',
        ],
    ],
];

Blade views (resources/views/components/)

• Shared subcomponents: option-indicator, search-input, bulk-actions, checkbox/content.
• Per component: checkbox/list.blade.php, checkbox/cards.blade.php and the radio counterparts.

JavaScript (resources/js/better-checkbox.js)

Alpine component registered as checkboxListFormComponent:

• Caches DOM selectors.
• Debounces search input (150ms).
• Batches DOM operations for bulk toggle.
• Listens to Livewire commit hook to re-index options after updates.

Registered via FilamentAsset::register() with loadedOnRequest() to avoid eager loading on unrelated pages.

Styling (resources/css/)

Plain Tailwind 4 CSS files per style, compiled into resources/dist/better-options.css which is registered with FilamentAsset.

Testing

The package ships with a Pest test suite under tests/:

• tests/Unit/: trait-level tests for indicators, icons, extra texts, color resolution.
• tests/Feature/: one test per component + a theme smoke test.
• tests/Fixtures/RolesEnum.php: fixture implementing HasLabel, HasDescription, HasIcon, HasColor, HasExtraText.

orchestra/testbench is used to bootstrap a minimal Laravel + Filament environment.