docs: update field type customization reference

Expand documentation on field type customization, covering settings, multi-value support, unique constraints, table filters, and import handling.

Author: ManukMinasyan

docs/content/2.essentials/3.field-types.md

@@ -191,13 +191,120 @@ FieldSchema::multiChoice()   // For MULTI_CHOICE data type
 ->priority(50)                       // Sort order (lower = first)
 ->formComponent($component)          // Form field component
 ->tableColumn($column)               // Table column component
+->tableFilter($filter)               // Table filter component
 ->infolistEntry($entry)             // Read-only display component
-->availableValidationRules($rules)  // User-selectable validation rules
-->defaultValidationRules($rules)    // Always-applied validation rules
-->searchable()                      // Enable table search
-->sortable()                        // Enable table sorting
-->filterable()                      // Enable table filtering
-->encryptable()                     // Allow field encryption
+->availableValidationRules($rules)  // Validation rules users can toggle per field
+->defaultValidationRules($rules)    // Validation rules always applied to this field type
+->searchable()                      // Enable globally-searchable in tables (default: true)
+->sortable()                        // Enable column sorting in tables (default: true)
+->filterable()                      // Enable table filter for this field type (default: false)
+->encryptable()                     // Allow users to enable encryption for this field
+```
+
+::callout{type="info"}
+A field type needs **both** `filterable()` and `tableFilter()` for filters to appear in tables. `filterable()` enables the capability; `tableFilter()` provides the filter component.
+::
+
+### Settings
+
+Add type-specific configuration options that appear in the field editor when your field type is selected. Settings are stored per custom field instance.
+
+`withSettings()` takes two arguments:
+1. A [Spatie Laravel Data](https://spatie.be/docs/laravel-data/v4/introduction) class defining the settings structure
+2. An array of Filament form components (or a `Closure` returning them) for the settings UI
+
+```php
+use Spatie\LaravelData\Data;
+use Filament\Forms\Components\TextInput;
+
+class CurrencySettings extends Data
+{
+    public function __construct(
+        public string $currencySymbol = '$',
+        public int $decimalPlaces = 2,
+    ) {}
+}
+
+// In your field type's configure() method:
+return FieldSchema::float()
+    ->key('acme-currency')
+    ->label('Currency')
+    ->withSettings(CurrencySettings::class, [
+        TextInput::make('currency_symbol')
+            ->label('Currency Symbol')
+            ->default('$'),
+        TextInput::make('decimal_places')
+            ->label('Decimal Places')
+            ->numeric()
+            ->default(2),
+    ]);
+```
+
+The settings form components are automatically shown/hidden based on the selected field type. Access stored settings via `$customField->settings` in your component closures.
+
+### Multi-Value & Constraints
+
+Control whether users can store multiple values in a single field and enforce uniqueness.
+
+```php
+->supportsMultiValue()
+->supportsUniqueConstraint()
+->defaultItemValidationRules($rules)
+->requiresLookupType()
+```
+
+**`supportsMultiValue()`** -- Shows an "Allow Multiple Values" toggle in the field editor. When enabled by the user, the field accepts multiple values (e.g., multiple emails or phone numbers) and a "Max Values" input appears. Used by Email, Phone, Link, and Record field types.
+
+**`supportsUniqueConstraint()`** -- Shows a "Unique per Entity Type" toggle in the field editor. When enabled by the user, a `UniqueCustomFieldValue` validation rule is applied to prevent duplicate values across records of the same entity type. Used by Email, Phone, Link, Text, Textarea, and Number field types.
+
+**`defaultItemValidationRules(array $rules)`** -- Validation rules automatically applied to **each individual item** in a multi-value field. These are not user-configurable -- they are hardcoded per field type. Only available for `MULTI_CHOICE` data types; throws `InvalidArgumentException` otherwise.
+
+**`requiresLookupType()`** -- Replaces the user-defined options UI with an entity type selector. The field stores references to records of the selected entity type instead of static option values. Import/export treats these as entity references. Currently used by the Record field type.
+
+Example -- the Email field type combines these to support multiple unique emails with per-item validation:
+
+```php
+return FieldSchema::multiChoice()
+    ->key('email')
+    ->supportsMultiValue()
+    ->supportsUniqueConstraint()
+    ->withArbitraryValues()
+    ->withoutUserOptions()
+    ->defaultItemValidationRules(['email', 'max:254']);
+```
+
+### Import Customization
+
+Control how field values appear in import templates and how raw import data is transformed before storage.
+
+```php
+->importExample('99.99')
+->importTransformer(function (mixed $state): ?float {
+    // Transform raw import value into the correct storage format
+})
+```
+
+**`importExample(string $example)`** -- Displayed as a sample value in the import template UI, helping users understand the expected format for this field type.
+
+**`importTransformer(Closure $transformer)`** -- Receives the raw value from the import file and returns the transformed value for storage. Without a transformer, the raw value is stored as-is. The closure signature is `function (mixed $state): mixed`.
+
+Example -- the Currency field type strips formatting characters on import:
+
+```php
+return FieldSchema::float()
+    ->key('currency')
+    ->importExample('99.99')
+    ->importTransformer(function (mixed $state): ?float {
+        if (blank($state)) {
+            return null;
+        }
+
+        if (is_string($state)) {
+            $state = preg_replace('/[^0-9.-]/', '', $state);
+        }
+
+        return round(floatval($state), 2);
+    });
 ```
 
 ### Component Types