### Install Filament Flex Fields

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/index.md

Install the plugin using Composer and register its assets using the Artisan command.

```bash
composer require janczakb/filament-flex-fields
php artisan filament:assets
```

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

### Barcode Scanner Field Migration and Model Setup

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/barcode-scanner-field.md

Example of setting up the database migration with a nullable and unique string column for the SKU, and configuring the model's fillable properties.

```php
// Migration
$table->string('sku')->nullable()->unique();

// Model — plain string, no special cast
protected $fillable = ['sku'];
```

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

### Development Commands

Source: https://github.com/janczakb/filament-flex-fields/blob/main/README.md

Install dependencies, run tests, and perform static analysis for the project.

```bash
composer install
composer test          # Pest — 99+ PHP tests
composer analyse       # PHPStan

npm install
npm run build          # CSS + JS → resources/dist/
npm run test:js        # Node unit tests
npm run test:e2e       # Playwright playground tests (requires FLEX_FIELDS_PLAYGROUND_URL)
composer format        # Laravel Pint
```

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

### Full Form Example with Date and Time Fields

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/date-and-time-fields.md

This example demonstrates integrating various date and time components within a Filament form section, including required fields and recommended defaults.

```php
use Filament\Schemas\Components\Section;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexDateField;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexDatePicker;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexDateRangeField;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexDateTimePicker;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexTimeField;
use Bjanczak\FilamentFlexFields\Enums\DateTimeGranularity;

Section::make('Schedule')
    ->schema([
        FlexDateField::make('date')
            ->required()
            ->withRecommendedDefaults(),

        FlexDatePicker::make('date_with_calendar')
            ->withRecommendedDefaults(),

        FlexTimeField::make('time')
            ->hourCycle(24)
            ->withRecommendedDefaults(),

        FlexDateTimePicker::make('date_time')
            ->granularity(DateTimeGranularity::Minute)
            ->withRecommendedDefaults(),

        FlexDateRangeField::make('range')
            ->withRecommendedDefaults(),
    ]);
```

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

### Basic TranslatableFields Setup (JSON/Array Storage)

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/translatablefields.md

Initialize TranslatableFields with specified locales and schema for JSON/array storage.

```php
TranslatableFields::make('Content')
    ->locales(['pl' => 'PL', 'en' => 'EN'])
    ->schema([
        FlexTextInput::make('title')->hiddenLabel(),
        FlexTextareaField::make('body')->hiddenLabel(),
    ]);
```

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

### Install Spatie laravel-translatable

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/translatablefields.md

Install the Spatie laravel-translatable package using Composer.

```bash
composer require spatie/laravel-translatable
```

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

### Model and Database Setup for Link Preview

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/link-preview-field.md

Configure your database migration, Eloquent model, and factory/seeder to store and use the link preview URL.

```php
// Migration
$table->string('article_url')->nullable();

// Model — no special cast required
protected $fillable = ['article_url'];

// Factory / seeder
'article_url' => 'https://laravel.com',
```

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

### ScheduleField Configuration API Example

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Provides an example of configuring various aspects of the ScheduleField, including days to render, timezone visibility, time step, slot limits, and visual variants.

```php
ScheduleField::make('hours')
    ->days(['mon', 'tue', 'wed', 'thu', 'fri'])
    ->timezone(null)
    ->lockedDays(['sat', 'sun'])
    ->copySourceDay('mon')
    ->workdays(['mon', 'tue', 'wed', 'thu', 'fri'])
    ->minSlots(1)
    ->maxSlots(6)
    ->timeStep(5)
    ->variant('soft');
```

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

### Basic Field Initialization

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/date-and-time-fields.md

Demonstrates the initialization of a generic component field. This example is a placeholder and assumes the existence of a `Component` class and its `make` method.

```php
Component::make('field_name')
    ->Field();
```

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

### Multi-currency State Example

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

This example shows the internal representation of multi-currency state, storing the amount in minor units and the currency code.

```php
[
    'amount' => 125050,   // minor units
    'currency' => 'EUR',
]
```

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

### LinkPreviewField Configuration Examples

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Illustrates configuring the LinkPreviewField with various options like prefix, variant, preview disabling, visit link visibility, and custom icons.

```php
use Bjanczak\FilamentFlexFields\Support\GravityIcon;

LinkPreviewField::make('path')
    ->prefix('https://')
    ->variant('soft')
    ->preview(false);

LinkPreviewField::make('url')
    ->showVisitLink(false)
    ->visitIcon(GravityIcon::Link)
    ->resolveInitialPreviewOnServer(false);
```

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

### Basic FlexRadiolist Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/flexradiolist.md

Demonstrates the basic setup of a FlexRadiolist with custom options, including descriptions and icons. Use this for standard selection scenarios.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexRadiolist;

FlexRadiolist::make('delivery')
    ->label('Delivery method')
    ->options([
        'standard' => 'Standard',
        'express' => [
            'label' => 'Express',
            'description' => '2–5 business days',
            'icon' => 'heroicon-o-bolt',
        ],
    ])
    ->default('express');
```

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

### Full MatrixChoiceField Example (Checkbox Mode)

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/matrixchoicefield.md

Demonstrates a comprehensive MatrixChoiceField setup with checkbox mode, including labels, helper text, row configurations (required, max selections), column definitions with icons, row/cell disabling logic, and default values.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\MatrixChoiceField;

MatrixChoiceField::make('feature_priorities')
    ->label('Feature priorities')
    ->helperText('Assign priority per feature. Dark mode High blocks CSV High.')
    ->mode('checkbox')
    ->size('md')
    ->color('primary')
    ->rows([
        'dark_mode' => [
            'label' => 'Dark mode',
            'description' => 'UI theme support',
            'required' => true,
            'max_selections' => 1,
        ],
        'csv_export' => [
            'label' => 'CSV export',
            'min_selections' => 1,
            'max_selections' => 2,
        ],
        'api_access' => [
            'label' => 'API access',
            'disabled' => true,
        ],
    ])
    ->matrixColumns([
        'low' => 'Low',
        'medium' => 'Medium',
        'high' => [
            'label' => 'High',
            'icon' => 'heroicon-o-bolt',
        ],
    ])
    ->requiredRows(['dark_mode'])
    ->disabledCells([
        // Static: always lock CSV → Low (example)
        // 'csv_export' => ['low'],
    ])
    ->disableCellWhen('csv_export', 'high', 'dark_mode', 'high')
    ->disableRowWhen('api_access', 'dark_mode', 'low')
    ->default([
        'dark_mode' => ['high'],
        'csv_export' => ['medium'],
    ]);
```

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

### Basic ProgressBar Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/progressbar.md

Demonstrates the fundamental setup of a ProgressBar with a label, value, maximum, and visual properties like size and color. Use this for standard progress tracking.

```php
use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\ProgressBar;

ProgressBar::make()
    ->label('Upload')
    ->value(60)
    ->max(100)
    ->showValue(true)
    ->size('md')
    ->color('primary');
```

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

### Example .env Configuration for Link Preview

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/link-preview-field.md

Set environment variables to override default scrape behavior settings like cache TTL, rate limits, and timeouts.

```env
FLEX_FIELDS_LINK_PREVIEW_CACHE_TTL=43200
FLEX_FIELDS_LINK_PREVIEW_RATE_LIMIT=30
FLEX_FIELDS_LINK_PREVIEW_TIMEOUT=10
```

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

### Basic ItemCard Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/itemcard.md

Demonstrates the basic setup of an ItemCard with a title, description, icon, and chevron. Ensure necessary imports are included.

```php
use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\ItemCard;
use Filament\Support\Icons\Heroicon;

ItemCard::make('Language')
    ->description('Choose your preferred language')
    ->icon(Heroicon::GlobeAlt)
    ->chevron();
```

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

### Basic NumberStepper Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/numberstepper.md

Demonstrates the fundamental setup of a NumberStepper field, including setting labels, min/max values, step increments, and optional suffixes.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\NumberStepper;

NumberStepper::make('quantity')
    ->label('Quantity')
    ->minValue(0)
    ->maxValue(99)
    ->step(1)
    ->suffix('kg')
    ->variant('primary')
    ->size('lg');
```

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

### Basic SelectField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/selectfield.md

Demonstrates the basic setup for a single-select field with rich options and a searchable dropdown, and a multi-select field with chips.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\SelectField;

SelectField::make('framework')
    ->label('Framework')
    ->options([
        'laravel' => [
            'label' => 'Laravel',
            'description' => 'PHP web framework',
            'icon' => 'heroicon-o-bolt',
        ],
        'livewire' => 'Livewire',
    ])
    ->searchable()
    ->variant('bordered')
    ->size('md');

SelectField::make('tags')
    ->multiple()
    ->options(['draft' => 'Draft', 'published' => 'Published'])
    ->chipColor('primary');
```

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

### SocialLinksField Configuration Example

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Shows how to configure the SocialLinksField with custom platforms, excluding default ones, setting a maximum number of links, enabling reordering, and enabling auto-formatting of URLs.

```php
SocialLinksField::make('social_links')
    ->excludePlatforms([SocialPlatform::Vk, SocialPlatform::Twitch])
    ->customPlatforms([
        [
            'value' => 'mastodon',
            'label' => 'Mastodon',
            'hosts' => ['mastodon.social'],
        ],
    ])
    ->maxLinks(6)
    ->reorderable()
    ->autoFormatUrls();
```

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

### Basic ScheduleField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Demonstrates the basic setup for a ScheduleField, including setting the label, default timezone, time step, and making it a required field.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\ScheduleField;

ScheduleField::make('opening_hours')
    ->label('Opening hours')
    ->timezone('Europe/Warsaw')
    ->timeStep(15)
    ->required();
```

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

### Basic SwitchField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/switchfield.md

Demonstrates the basic setup of a SwitchField with a label, description, badge, and layout configuration. Use this for standard boolean toggles in forms.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\SwitchField;

SwitchField::make('notifications')
    ->label('Notifications')
    ->description('Receive email updates')
    ->badge('New')
    ->badgeColor('primary')
    ->layout('card')
    ->accepted();
```

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

### Basic ChoiceCards Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/choicecards.md

Demonstrates the basic setup of the ChoiceCards component with labels, helper text, and options including rich descriptions and prices. Sets a default selection.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\ChoiceCards;

ChoiceCards::make('plan')
    ->label('Select a plan')
    ->helperText('Choose the plan that suits your needs')
    ->options([
        'starter' => [
            'label' => 'Starter',
            'description' => 'For individuals',
            'price' => '$5',
            'price_suffix' => '/mo',
        ],
        'pro' => 'Pro',
    ])
    ->layout('stack')
    ->default('pro');
```

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

### Basic SegmentControl Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/segmentcontrol.md

Demonstrates the basic setup of a SegmentControl with custom options, including labels, icons, and tooltips. Use this for standard segmented control implementations.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\SegmentControl;

SegmentControl::make('alignment')
    ->label('Alignment')
    ->options([
        'left' => 'Left',
        'center' => [
            'label' => 'Center',
            'icon' => 'heroicon-o-bars-3',
            'tooltip' => 'Centered text',
        ],
        'right' => 'Right',
    ])
    ->variant('ghost')
    ->fullWidth();
```

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

### Basic CreditCardField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/creditcardfield.md

Demonstrates the basic setup for the CreditCardField component, including setting its name, label, variant, and enabling CVV focus flip.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\CreditCardField;

CreditCardField::make('card')
    ->label('Payment method')
    ->variant('midnight')
    ->flipOnCvvFocus()
    ->required();
```

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

### Basic ProgressCircle Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/progresscircle.md

Demonstrates the fundamental setup of a ProgressCircle component, setting its value, display text, size, and color.

```php
use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\ProgressCircle;

ProgressCircle::make()
    ->value(69)
    ->displayValue('69%')
    ->size('md')
    ->color('primary');
```

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

### Minimal ScheduleField State Example

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/schedule-field.md

Illustrates the minimal JSON structure for the ScheduleField state, including timezone and enabled/disabled days with their respective time slots.

```json
{
  "timezone": "Europe/Warsaw",
  "days": {
    "mon": {
      "enabled": true,
      "slots": [
        { "from": "09:00", "to": "17:00", "type": "slot" }
      ]
    },
    "sat": {
      "enabled": false,
      "slots": []
    }
  }
}
```

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

### Basic CountryField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/countryfield.md

Demonstrates the basic setup of a CountryField, including setting a label and making it required. It also shows how to pre-select a default country.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\CountryField;

CountryField::make('country')
    ->label('Country')
    ->defaultCountry('PL')
    ->required();
```

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

### Database Migration and Model Setup for Icon Picker

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/icon-picker-field.md

Defines the database schema for storing icon names and configures the Eloquent model to accept these values.

```php
// Migration
$table->string('menu_icon')->nullable();
```

```php
// Model — no special cast required
protected $fillable = ['menu_icon'];
```

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

### FlexDateRangeField Example

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/date-and-time-fields.md

Example of a date range field with start and end datetimes. The format depends on the 'granularity' setting.

```php
[
    'start' => '2026-06-10T09:00:00',
    'end' => '2026-06-14T17:00:00',
]
```

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

### Basic PriceRangeField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/pricerangefield.md

Demonstrates the fundamental setup of a PriceRangeField with common configurations like label, min/max values, step, prefix, histogram, input visibility, variant, and default state.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\PriceRangeField;

PriceRangeField::make('price_range')
    ->label('Price range')
    ->min(0)
    ->max(5000)
    ->step(1)
    ->prefix('$')
    ->histogram([30, 74, 85, 36, 98])
    ->showInputs()
    ->variant('bordered')
    ->default(['min' => 100, 'max' => 1124]);
```

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

### Custom Avatar Resolution

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/usercolumn.md

Define a custom callback to resolve the avatar URL for a user. This example uses a Filament convention for getting the avatar URL from the model.

```php
UserColumn::make('owner')
    ->getAvatarUrlUsing(fn (User $record): ?string => $record->getFilamentAvatarUrl());
```

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

### Date Range Field Validation Example

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/date-and-time-fields.md

Configures a date range field, disallowing the same day for start and end, setting minimum and maximum date bounds, and marking it as required.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexDateRangeField;

FlexDateRangeField::make('leave')
    ->required()
    ->allowSameDay(false)
    ->minValue('2026-01-01')
    ->maxValue('2026-12-31');
```

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

### Basic TrackSlider Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/trackslider.md

Demonstrates the basic setup of a TrackSlider component with common configurations like label, min/max values, step, suffix, and output display.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\TrackSlider;

TrackSlider::make('volume')
    ->label('Volume')
    ->min(0)
    ->max(100)
    ->step(5)
    ->suffix('%')
    ->trackLabel('Volume level')
    ->variant('secondary')
    ->showOutput()
    ->size('md');
```

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

### Basic FlexChecklist Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/flexchecklist.md

Demonstrates how to create a FlexChecklist with custom options, including descriptions and icons, and set minimum and maximum selection limits. Also shows an example with exact selection constraints and disabled options.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexChecklist;

FlexChecklist::make('features')
    ->label('Included features')
    ->options([
        'wifi' => 'Wi‑Fi',
        'parking' => [
            'label' => 'Parking',
            'description' => 'On-site parking included',
            'icon' => 'heroicon-o-truck',
        ],
    ])
    ->minSelections(1)
    ->maxSelections(3)
    ->color('primary');

FlexChecklist::make('permissions')
    ->options(['read' => 'Read', 'write' => 'Write', 'admin' => 'Admin'])
    ->exactSelections(2)
    ->disabledOptions(['admin']);
```

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

### Dynamic Format Whitelist using Closure

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/barcode-scanner-field.md

This example shows how to dynamically set the allowed barcode formats based on the record's properties using a Closure. This allows for conditional format whitelisting.

```php
BarcodeScannerField::make('code')
    ->formats(fn (): array => $this->record?->requires_qr_only
        ? [BarcodeFormat::Qr]
        : [BarcodeFormat::Ean13, BarcodeFormat::Code128]);
```

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

### Credit Card Field Example State

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/creditcardfield.md

Example of the expected state structure for the CreditCardField, including number, name, expiry, and CVV.

```php
[
    'number' => '4242424242424242',
    'name' => 'Jane Doe',
    'expiry' => '12/28',
    'cvv' => '123',
]
```

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

### Icon Picker Field Definition Example

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/icon-picker-field.md

Example of how to define an Icon Picker field with specific configurations for sets, layout, grid columns, and preloading.

```php
new FlexFieldDefinition(
    slug: 'menu_icon',
    label: 'Menu icon',
    type: FieldType::IconPicker,
    config: [
        'sets' => ['heroicons'],
        'layout' => 'icons',
        'grid_columns' => 8,
        'preload' => true,
    ],
);
```

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

### Example Translation Override

Source: https://github.com/janczakb/filament-flex-fields/blob/main/README.md

Customize timezone names by creating or modifying the timezones.php file within your published vendor translations. This example shows how to override the default name for 'Europe/Warsaw'.

```php
// lang/vendor/filament-flex-fields/pl/timezones.php
return [
    'Europe__Warsaw' => 'Warszawa',
];
```

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

### Start Slug Suffix from a Specific Number

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/slugfield-and-titleslugfield.md

Configure the starting number for slug suffixes when collisions occur. If 'my-post' exists, the preview might generate 'my-post-5' based on this setting.

```php
SlugOptions::create()
    ->generateSlugsFrom('title')
    ->saveSlugsTo('slug')
    ->startSlugSuffixFrom(5);
```

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

### Basic VideoField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/videofield.md

Demonstrates how to create a VideoField with common options like setting a label, aspect ratio, title, enabling controls, and allowing YouTube embeds.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\VideoField;

VideoField::make('trailer_url')
    ->label('Trailer')
    ->ratio('16:9')
    ->title('Product trailer')
    ->controls()
    ->allowYoutube();

VideoField::make('tutorial')
    ->src('https://cdn.example.com/tutorial.mp4')
    ->poster('/images/tutorial-poster.jpg')
    ->skipSeconds(15)
    ->pictureInPictureable()
    ->compactControls();
```

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

### Basic LinkPreviewField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Demonstrates the basic instantiation of the LinkPreviewField with required and placeholder configurations.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\LinkPreviewField;

LinkPreviewField::make('article_url')
    ->label('Article URL')
    ->required();

LinkPreviewField::make('landing_page')
    ->previewLayout('card')
    ->previewDebounce(750)
    ->placeholder('https://example.com');
```

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

### Date Range Picker with Optional Time

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/date-and-time-fields.md

FlexDateRangeField enables selection of a start and end date, with optional time components displayed under the calendar. Configure granularity and whether the same day is allowed for start and end.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexDateRangeField;
use Bjanczak\FilamentFlexFields\Enums\DateTimeGranularity;

FlexDateRangeField::make('booking_range')
    ->label('Booking period')
    ->granularity(DateTimeGranularity::Minute)
    ->allowSameDay(false)
    ->default([
        'start' => '2026-06-10T09:00:00',
        'end' => '2026-06-14T17:00:00',
    ])
    ->withRecommendedDefaults();
```

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

### Filament Resource Example with EAN Validation

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/barcode-scanner-field.md

This example demonstrates configuring the BarcodeScannerField within a Filament resource. It specifies allowed EAN formats, enables checksum validation, and disables manual input, suitable for retail product scanning.

```php
use Filament\Forms\Form;
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\BarcodeScannerField;
use Bjanczak\FilamentFlexFields\Enums\BarcodeFormat;

public static function form(Form $form): Form
{
    return $form->schema([
        BarcodeScannerField::make('ean')
            ->label('EAN barcode')
            ->formats([BarcodeFormat::Ean13, BarcodeFormat::Ean8])
            ->validateChecksum()
            ->allowManualInput(false)
            ->helperText('Scan the product barcode with your camera.')
            ->columnSpanFull(),
    ]);
}
```

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

### Basic DualListboxField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/duallistboxfield.md

Demonstrates the fundamental setup of a DualListboxField, including setting a label, defining options with labels and descriptions, and configuring minimum/maximum items, searchability, reordering, list height, and variant.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\DualListboxField;

DualListboxField::make('permissions')
    ->label('Permissions')
    ->options([
        'read' => ['label' => 'Read', 'description' => 'View records'],
        'write' => 'Write',
        'delete' => 'Delete',
    ])
    ->minItems(1)
    ->maxItems(5)
    ->searchable()
    ->reorderable()
    ->listHeight('16rem')
    ->variant('bordered');
```

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

### Basic AudioField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/audiofield.md

Demonstrates how to create an AudioField with a label and enable looping. The state is expected to be an audio URL.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\AudioField;

AudioField::make('preview_url')
    ->label('Voice message')
    ->fullWidth()
    ->loop();
```

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

### Eloquent Model Setup for Spatie Tags

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/tags-field.md

Configure your Eloquent model to use the `HasTags` trait from `spatie/laravel-tags`.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Tags\HasTags;

class Candidate extends Model
{
    use HasTags;

    protected $fillable = ['name'];
}
```

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

### Basic FlexSpatieTagsField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/tags-field.md

Initialize the `FlexSpatieTagsField` for a model implementing `Spatie\`Tags\`HasTags`. Ensure `spatie/laravel-tags` is installed.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\Spatie\FlexSpatieTagsField;

FlexSpatieTagsField::make('tags')
    ->type('skills');
```

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

### Basic FlexSlider Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Demonstrates creating a basic FlexSlider for volume control with percentage suffix and a primary color.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexSlider;

FlexSlider::make('volume')
    ->range(0, 100)
    ->step(5)
    ->showValue()
    ->suffix('%')
    ->color('primary');
```

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

### Basic LinkPreviewField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/link-preview-field.md

Demonstrates the basic instantiation of LinkPreviewField with a label and placeholder. It also shows how to set a default URL and configure the preview layout and debounce time.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\LinkPreviewField;

LinkPreviewField::make('article_url')
    ->label('Article URL')
    ->placeholder('https://example.com/article')
    ->required();

LinkPreviewField::make('landing_page')
    ->label('Landing page')
    ->previewLayout('card')
    ->previewDebounce(750)
    ->default('https://laravel.com');
```

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

### commitDecimalsOnBlur()

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Determines whether fractional digits should be padded on blur. For example, `,6` becomes `,60`. Defaults to true.

```APIDOC
## commitDecimalsOnBlur(bool|Closure $condition = true)

### Description
Pads fractional digits on blur (e.g., `,6` → `,60`). Defaults to true.

### Method
Not Applicable (Configuration method)

### Parameters
- **condition** (bool|Closure) - Optional - Set to true to enable padding on blur, false to disable. Defaults to true.
```

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

### IconColumn Show Label and Name

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/iconcolumn.md

Examples of enabling the display of the human-readable label and/or the technical icon name.

```php
IconColumn::make('menu_icon')
    ->showLabel(); // "Check Circle" from heroicon-o-check-circle

IconColumn::make('menu_icon')
    ->showLabel()
    ->showName(); // label + heroicon-o-check-circle
```

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

### Basic ItemCardStack Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/itemcardstack.md

Demonstrates how to create an ItemCardStack with multiple ItemCard components, including descriptions, icons, and actions. Ensure necessary imports are present.

```php
use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\ItemCard;
use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\ItemCardStack;

ItemCardStack::make()
    ->schema([
        ItemCard::make('Profile')
            ->description('Update your personal information')
            ->icon(Heroicon::OutlinedUser)
            ->chevron()
            ->pressableAction(fn () => $this->openProfile()),
        ItemCard::make('Security')
            ->variant('secondary')
            ->description('Manage passwords and 2FA')
            ->icon(Heroicon::OutlinedKey)
            ->chevron(),
    ]);

```

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

### Configure Fields to Store

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/mappickerfield.md

Specify which address parts to store and display. Must include at least one valid key from ALL_FIELDS.

```php
MapPickerField::make('field_name')
    ->fields(['value1', 'value2']);
```

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

### TranslatableFields Setup with Spatie Integration

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/translatablefields.md

Configure TranslatableFields to work with Spatie's laravel-translatable by enabling the `spatieTranslatable` option.

```php
TranslatableFields::make('Content')
    ->spatieTranslatable(true)
    ->locales(['pl' => 'PL', 'en' => 'EN'])
    ->schema([
        FlexTextInput::make('title')->hiddenLabel(),
        FlexTextareaField::make('body')->hiddenLabel(),
    ]);
```

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

### Basic SocialLinksField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/social-links-field.md

Demonstrates the basic setup of the SocialLinksField in a Filament form. Ensure the component is imported correctly.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\SocialLinksField;

SocialLinksField::make('social_links')
    ->label('Social profiles')
    ->required();
```

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

### Single Translatable Field

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/translatablefields.md

Use for single fields like titles or names. Each locale gets its own input tab.

```php
TranslatableFields::make('Title')
    ->locales(['ar' => 'Arabic', 'en' => 'English'])
    ->directionByLocale()
    ->emptyBadgeWhenAllFieldsAreEmpty()
    ->activeTabWithValue()
    ->schema([
        FlexTextInput::make('title')->label('Title')->hiddenLabel(),
    ]);
```

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

### Apply Recommended Defaults

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Apply a preset bundle of recommended settings specific to the component's mode. Refer to the 'Preset bundle' documentation for more details on what this preset includes.

```php
->withRecommendedDefaults()
```

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

### Enable Spatie Translatable Support

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/translatablefields.md

Mark fields for Spatie-aware hydration to indicate intent. Hydration auto-detects HasTranslations when the package is installed.

```php
TranslatableFields::make('field_name')
    ->spatieTranslatable(true);
```

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

### Time Field Validation Example

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/date-and-time-fields.md

Configures a time field with a 24-hour cycle, minimum and maximum time constraints, and marks it as required.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexTimeField;

FlexTimeField::make('business_hours')
    ->hourCycle(24)
    ->minValue('09:00')
    ->maxValue('17:00')
    ->required();
```

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

### Apply Recommended Defaults

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/date-and-time-fields.md

Applies a preset bundle of configurations specific to the component's mode. Refer to the 'Preset bundle' documentation for more details.

```php
Component::make('field_name')
    ->withRecommendedDefaults('Brak danych');
```

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

### Basic FlexColorPickerField Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/flexcolorpickerfield.md

Demonstrates the basic setup for a FlexColorPickerField, including setting a label and making it required. It also shows how to enable the alpha slider and configure a grid layout with custom dimensions and RGBA output.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexColorPickerField;

FlexColorPickerField::make('brand_color')
    ->label('Brand color')
    ->alpha()
    ->required();

FlexColorPickerField::make('accent')
    ->layout(FlexColorPickerField::LAYOUT_GRID)
    ->gridColumns(17)
    ->gridRows(11)
    ->rgba()
    ->alpha();
```

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

### Basic Portrait Product Card

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Example of a CoverCard configured as a portrait product card with background image, title, description, and a book now action.

```php
use Bjanczak\FilamentFlexFields\Filament\Actions\Action;
use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\CoverCard;
use Filament\Notifications\Notification;

CoverCard::make()
    ->backgroundImage('https://cdn.example.com/yacht.jpg')
    ->backgroundColor('#e4e4e7')
    ->ratio('3:4')
    ->topTitle('Azimut 55 Fly')
    ->topDescription('Mediterranean charter')
    ->footerTitle('From €4,900 / week')
    ->footerDescription('Early booking discount')
    ->footerAction(
        Action::make('book')
            ->label('Book now')
            ->action(fn () => Notification::make()->title('Booking started')->success()->send())
    );
```

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

### Basic FlexSlider Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/flexslider.md

Demonstrates the basic configuration of a FlexSlider for volume control and a price range.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexSlider;

FlexSlider::make('volume')
    ->range(0, 100)
    ->step(5)
    ->showValue()
    ->suffix('%')
    ->color('primary');

FlexSlider::make('price_range')
    ->range(0, 1000)
    ->step(10)
    ->fillTrack([false, true, false])
    ->prefix('$')
    ->trackLabel('Budget')
    ->decimalPlaces(0);
```

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

### SlugField Default Pattern Derivation

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/slugfield-and-titleslugfield.md

By default, SlugField derives its validation pattern from `slugSeparator()`. This example shows the default behavior with a hyphen separator.

```php
// Auto (default) — follows slugSeparator('-')
SlugField::make('slug'), // validates hello-world
```

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

### ScheduleField State with Split Shift and Break

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/schedule-field.md

Provides an example of the ScheduleField state format representing a split shift with a defined break period.

```json
{
  "timezone": "Europe/Warsaw",
  "days": {
    "mon": {
      "enabled": true,
      "slots": [
        { "from": "09:00", "to": "12:00", "type": "slot" },
        { "from": "12:00", "to": "13:00", "type": "break" },
        { "from": "13:00", "to": "17:00", "type": "slot" }
      ]
    }
  }
}
```

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

### Gradient Strip (No Image)

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/covercard.md

Shows how to create a gradient background strip without an image. This example uses a specific linear gradient, a 3:1 aspect ratio, and light tone, with footer text.

```php
CoverCard::make()
    ->backgroundGradient('linear-gradient(90deg, rgb(15 23 42) 0%, rgb(30 58 138) 50%, rgb(14 116 144) 100%)')
    ->ratio('3:1')
    ->tone('light')
    ->fullWidth()
    ->footerTitle('Launch week')
    ->footerDescription('Limited offer');
```

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

### Apply Production Presets and Styling

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/translatablefields.md

Configure various display and behavior options, including direction by locale, empty badge labels, active tab selection, and panel borders.

```php
TranslatableFields::make('field_name')
    ->directionByLocale()
    ->emptyBadgeWhenAllFieldsAreEmpty('Brak danych')
    ->activeTabWithValue()
    ->withRecommendedDefaults('Brak danych')
    ->borderedPanels(true);
```

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

### Using IconPickerField Value in Filament

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/icon-picker-field.md

Illustrates how to use the selected icon name from an IconPickerField in Filament, for example, to set the icon for another component.

```php
->icon(fn (Get $get): ?string => $get('menu_icon'))
```

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

### AudioField Basic Usage

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Demonstrates creating an AudioField with a label, full width, and loop enabled. Also shows setting a static source and custom waveform.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\AudioField;

AudioField::make('preview_url')
    ->label('Voice message')
    ->fullWidth()
    ->loop();

AudioField::make('jingle')
    ->src('/audio/notification.mp3')
    ->waveform([20, 45, 80, 60, 35, 90, 50, 30])
    ->size('lg');
```

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

### Configure Currency Field

Source: https://github.com/janczakb/filament-flex-fields/blob/main/COMPONENTS.md

Example of making a currency field with specific currency settings. This sets the default currency and enables a selection of multiple currencies.

```php
CurrencyField::make('price')
    ->currency('VND')
    ->currencies(['VND', 'EUR', 'USD']);
```

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

### Custom Suffix Generator for Slugs

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/slugfield-and-titleslugfield.md

Provide a custom function to generate suffixes for duplicate slugs. This example prepends 'v' and increments the iteration number.

```php
SlugOptions::create()
    ->generateSlugsFrom('title')
    ->saveSlugsTo('slug')
    ->usingSuffixGenerator(fn (string $slug, int $iteration): string => 'v'.($iteration + 1));
```

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

### LinkPreviewField with URL Prefix

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/link-preview-field.md

Illustrates how to use the `prefix()` method to prepend a URL scheme. The saved state includes the full URL, while the input display shows only the suffix for better readability. Whitespace is trimmed, and empty strings are converted to null.

```php
LinkPreviewField::make('blog_path')
    ->prefix('https://')
    ->default('https://acme.test/blog/launch');

// Saved state: "https://acme.test/blog/launch"
// Input display: "acme.test/blog/launch"
```

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

### Flex Field Definition for Tags

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/tags-field.md

Define a tags field within a FlexFieldDefinition configuration. This example shows comma-separated labels and custom split keys.

```php
new FlexFieldDefinition(
    slug: 'labels',
    label: 'Labels',
    type: FieldType::Tags,
    config: [
        'separator' => ',',
        'split_keys' => ['Tab', 'Enter'],
        'max_tags' => 5,
        'show_tag_count' => true,
        'variant' => 'secondary',
    ],
);
```

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

### Adding Descriptions to FlexChecklist Options

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/flexchecklist.md

Demonstrates how to provide descriptive text for each option in a FlexChecklist using the `descriptions()` method.

```php
FlexChecklist::make('field_name')
    ->descriptions(['value1', 'value2']);
```

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

### Schema and Display Components

Source: https://github.com/janczakb/filament-flex-fields/blob/main/README.md

Implement schema and display components for presenting data in a structured and visually appealing manner. Examples include ProgressCircle and ItemCardGroup.

```php
use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\ItemCardGroup;
use Bjanczak\FilamentFlexFields\Filament\Schemas\Components\ProgressCircle;

ProgressCircle::make()
    ->value(72)
    ->displayValue('72%')
    ->variant('semicircle');

ItemCardGroup::make([
    // Polished card-based settings rows…
]);
```

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

### Configuring Grid Columns for Layout

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/choicecards.md

Shows how to configure the number of columns for the 'grid' and multi-column 'media' layouts in ChoiceCards. Supports responsive column counts.

```php
->gridColumns(3)

->gridColumns([
    'default' => 1,
    'sm' => 2,
    'md' => 3,
    'lg' => 4,
])
```

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

### Set Date of Birth Bounds

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/date-and-time-fields.md

Example of setting minimum and maximum dates for a date of birth field, ensuring it falls within a valid range.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexDatePicker;

FlexDatePicker::make('birth_date')
    ->minDate(now()->subYears(150))
    ->maxDate(now())
    ->required();
```

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

### Defining Simple Options

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/choicecards.md

Shows how to define a basic list of options for the ChoiceCards component using simple key-value pairs.

```php
ChoiceCards::make('field_name')
    ->options([
        'option_1' => 'Option 1',
        'option_2' => 'Option 2',
    ]);
```

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

### Date Field Validation Example

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/date-and-time-fields.md

Configures a date field with required validation, minimum and maximum date constraints, and a callback to mark weekends as unavailable.

```php
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\FlexDateField;
use Carbon\Carbon;

FlexDateField::make('starts_on')
    ->required()
    ->minValue('2026-06-01')
    ->maxValue(Carbon::parse('2026-12-31'))
    ->isDateUnavailable(fn (Carbon $date) => $date->isWeekend());
```

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

### Whitelist with Custom Platform

Source: https://github.com/janczakb/filament-flex-fields/blob/main/docs/social-links-field.md

Combine predefined platforms with custom platform definitions using `platforms()` and `customPlatforms()`.

```php
SocialLinksField::make('fediverse')
    ->platforms(['mastodon', SocialPlatform::Website])
    ->customPlatforms([
        [
            'value' => 'mastodon',
            'label' => 'Mastodon',
            'placeholder' => 'https://mastodon.social/@username',
            'hosts' => ['mastodon.social', 'mastodon.online'],
        ],
    ]);
```