README

Türkçe

Filament form componentleri için geliştirilmiş özellikler: çoklu seçim, devre dışı seçenekler ve daha fazlası.

Sorun

Filament v2'de disableOptionWhen() metodu tekli seçim (dropdown) için mükemmel çalışır, ancak multiple() aktif edildiğinde çalışmaz. Bunun nedeni:

Tekli seçim native HTML <select> elementi kullanır ve disabled attribute doğal olarak çalışır
Çoklu seçim daha iyi UX için Choices.js kütüphanesi kullanır
Filament'in transformOptionsForJs() metodu Choices.js'e sadece label ve value gönderir, disabled durumunu göndermez

Bu paket bu sorunu çözer ve ek özellikler ekler.

Çözüm

Bu paket Filament'in Select componentini extend eder ve transformOptionsForJs() metodunu override ederek disabled özelliğini ekler. Choices.js zaten disabled seçenekleri desteklediği için ek JavaScript gerekmez.

Sürüm seçimi ve uyumluluk

Filament ve Laravel sürümünüze uygun satırdaki komutu kullanın. Composer paket adı kapital-online/filament-form-components olmalıdır.

Filament	Laravel	En düşük PHP	Paket sürümü	Composer komutu
2.x	9.x	8.0.2	`^1.2`	`composer require kapital-online/filament-form-components:"^1.2"`
2.x	10.x	8.1	`^1.2`	`composer require kapital-online/filament-form-components:"^1.2"`
3.x	10.x	8.1	`^2.1`	`composer require kapital-online/filament-form-components:"^2.1"`
3.x	11.x	8.2	`^2.1`	`composer require kapital-online/filament-form-components:"^2.1"`
4.x	11.28+ (11.x)	8.3	`^3.0`	`composer require kapital-online/filament-form-components:"^3.0"`

main, Filament 3 için 2.x hattıdır. Laravel 11 desteği v2.1.0 ile gelir; bu nedenle Filament 3 projelerinde ^2.1 seçilir.
3.x bakım dalı, Filament 4 için v3.0.0 ve sonrası sürümleri içerir. Bu hat illuminate/support:^11.28 ve PHP ^8.3 ister; Laravel 12 ve üzerini kapsamaz.
Filament 2 projeleri eski v1.2.0 / ^1.2 hattını kullanır. Eski satırlar etiketin bağımlılıklarına dayanır; son doğrulama Filament 3 + Laravel 10/11 ve Filament 4 + Laravel 11 üzerinde yapılmıştır.

PHP alt sınırları paket ve framework gereksinimlerini birlikte gösterir; Filament 3 gereksinimleri ve Laravel sürüm tablosu de geçerlidir.

Kurulum

Özel depoya erişebilen GitHub kimliği veya SSH anahtarınızla, VCS kaydı henüz yoksa ekleyin:

composer config repositories.filament-form-components vcs git@github.com:Kapital-Online/filament-form-components.git

Ardından tablodaki uygun composer require komutlarından yalnız birini çalıştırın. Filament 3 + Laravel 10/11 örneği:

composer require kapital-online/filament-form-components:"^2.1"

Filament 4 + Laravel 11.28+ / PHP 8.3 için bunun yerine:

composer require kapital-online/filament-form-components:"^3.0"

@dev veya dev-main yerine yayımlanan sürüm aralığını kullanın. ^2.1 ve ^3.0 kendi ana sürüm hatlarında kalır; Filament yükseltmesi uygulama ve diğer eklentilerle birlikte yapılmalıdır. Paket Laravel'in package discovery mekanizması ile otomatik olarak yüklenir.

Kullanım

Temel Kullanım (Drop-in Replacement)

Filament'in Select componentini Kapital'in Select'i ile değiştirin:

// Önce
use Filament\Forms\Components\Select;

// Sonra
use Kapital\Filament\FormComponents\Components\Select;

// Kullanım tamamen aynı
Select::make('field_name')
    ->options([
        '1' => 'Seçenek 1',
        '2' => 'Seçenek 2',
        '3' => 'Seçenek 3',
    ])
    ->multiple()
    ->disableOptionWhen(fn ($value) => $value === '2')

Artık disableOptionWhen() çoklu seçim ile mükemmel çalışıyor!

Özellikler

1. Düzeltilmiş `disableOptionWhen()` Çoklu Seçim İle

Ana özellik - devre dışı seçenekler artık çoklu seçimde düzgün çalışıyor:

Select::make('tags')
    ->relationship('tags', 'name')
    ->multiple()
    ->disableOptionWhen(fn ($value) => Tag::find($value)?->is_system ?? false)

Devre dışı seçenekler soluk görünür ve seçilemez.

2. Maksimum Seçilebilir Öğe (`maxSelectable`)

Seçilebilecek öğe sayısını sınırlayın:

Select::make('categories')
    ->options([...])
    ->multiple()
    ->maxSelectable(3) // Maksimum 3 seçim yapılabilir

Özellikler:

Backend validasyonu (aşılırsa form gönderilmez)
Frontend validasyonu Choices.js ile (kullanıcı dostu geri bildirim)
Closure desteği ile dinamik limitler

->maxSelectable(fn () => auth()->user()->isPremium() ? 10 : 3)

3. Minimum Seçilebilir Öğe (`minSelectable`)

Minimum sayıda seçim zorunluluğu:

Select::make('required_tags')
    ->options([...])
    ->multiple()
    ->minSelectable(2) // En az 2 seçim gerekli

Özellikler:

Backend validasyonu
Closure desteği ile dinamik limitler

->minSelectable(fn () => auth()->user()->isAdmin() ? 0 : 1)

4. Tümünü Seç Seçeneği (`selectAllOption`)

"Tümünü Seç" butonu ekler. Tıklandığında disabled olmayan tüm seçenekleri otomatik seçer:

Select::make('permissions')
    ->options([...])
    ->multiple()
    ->selectAllOption() // "Tümünü Seç" butonu ekler
    ->disableOptionWhen(fn($value) => $value === 'dangerous_permission') // Disabled olanlar seçilmez

Özellikler:

Disabled seçenekleri otomatik filtreler
Form alanının yanında hint action olarak görünür
Closure desteği ile dinamik gösterim

->selectAllOption(fn () => auth()->user()->isAdmin())

5. Tümünü Temizle Seçeneği (`deselectAllOption`)

"Tümünü Temizle" butonu ekler. Tıklandığında tüm seçimleri kaldırır:

Select::make('filters')
    ->options([...])
    ->multiple()
    ->deselectAllOption() // "Tümünü Temizle" butonu ekler

Özellikler:

Tüm seçimleri bir tıkla temizler
Kırmızı renkte ve X ikonu ile görünür
Closure desteği ile dinamik gösterim

->deselectAllOption(fn () => auth()->user()->canClearAll())

6. Master-Detail Table (Filament v3)

Bu paket Filament v3 resource tabloları için master-detail altyapısı da içerir.

Öne çıkanlar:

Satır bazlı aç/kapa detayı (ikonlu)
Detail içeriğini sadece açılınca render etme (lazy)
Mevcut Filament table zinciriyle uyumlu kullanım
Relation/query/livewire tabanlı detail tanımına uygun fluent API

Gerekli Importlar

use Filament\Tables\Table;
use Kapital\Filament\FormComponents\Resources\Table as MasterDetailResourceTable;

Resource Kullanımı

public static function table(Table $table): Table
{
    if ($table instanceof MasterDetailResourceTable) {
        $table->masterDetailLivewire(
            component: 'overdue-payment-plan-report-transactions-table',
            parameters: fn (OverduePaymentPlanReport $record): array => [
                'userId' => $record->user_id,
            ],
            key: fn (OverduePaymentPlanReport $record): string => 'overdue-payment-plan-report-' . $record->getKey(),
        );
    }

    return $table
        ->columns([
            // Filament columns...
        ]);
}

List Page Kullanımı

İlgili resource list page sınıfında trait eklenmelidir:

use Kapital\Filament\FormComponents\Tables\Concerns\InteractsWithMasterDetailTable;

class ListOverduePaymentPlanReports extends ListRecords
{
    use InteractsWithMasterDetailTable;
}

API Özeti

masterDetailLivewire(component, parameters, key, expandable, expandIcon, collapseIcon, wrapperClass)
masterDetailRelation(relation)
masterDetailQuery(closure)

Not: Filament v3 Resource::table() method imzası Filament\Tables\Table beklediği için method parametresi Filament tipiyle kalmalıdır. Paketin master-detail özellikleri runtime’da instanceof MasterDetailResourceTable ile etkinleştirilir.

Bilinen Kısıt / Öneri

Nested modal içinde tekrar modal açan table action akışları Alpine/Livewire tarafında sorun çıkarabilir. Bu tip senaryolarda detail içeriğini aynı sayfada inline açmak veya action akışını modal dışına taşımak daha stabil sonuç verir.

Gerçek Dünya Örneği

use Kapital\Filament\FormComponents\Components\Select;
use App\Models\Tag;

Select::make('tags')
    ->label('Sipariş Etiketleri')
    ->relationship('tags', 'name')
    ->multiple()
    ->disableOptionWhen(function ($value) {
        // Sistem etiketlerini devre dışı bırak - kaldırılamazlar
        return Tag::find($value)?->is_system ?? false;
    })
    ->selectAllOption() // "Tümünü Seç" butonu (disabled olanları atlar)
    ->deselectAllOption() // "Tümünü Temizle" butonu
    ->maxSelectable(5) // Sipariş başına maksimum 5 etiket
    ->minSelectable(1) // En az 1 etiket gerekli
    ->searchable()
    ->preload()
    ->helperText('Sistem etiketleri devre dışıdır ve değiştirilemez.')

Tüm Özellikler Karşılaştırması

Özellik	Filament v2 Select	Kapital Enhanced Select
Tekli seçim + `disableOptionWhen()`	✅ Çalışıyor	✅ Çalışıyor
Çoklu seçim + `disableOptionWhen()`	❌ Bozuk	✅ Düzeltildi
`maxSelectable()`	❌ Yok	✅ Var
`minSelectable()`	❌ Yok	✅ Var
`selectAllOption()`	❌ Yok	✅ Var
`deselectAllOption()`	❌ Yok	✅ Var
Diğer tüm Filament özellikleri	✅	✅ Tam uyumlu

Teknik Detaylar

Nasıl Çalışır

Düzeltme oldukça basit. Paket tek bir metodu override eder:

protected function transformOptionsForJs(array $options): array
{
    return collect($options)
        ->map(fn ($label, $value): array => [
            'label' => $label,
            'value' => strval($value),
            'disabled' => $this->isOptionDisabled($value, $label), // Bu satır eklendi
        ])
        ->values()
        ->all();
}

Choices.js (Filament'in çoklu seçim için kullandığı kütüphane) disabled özelliğini doğal olarak destekler. Bunu options array'ine ekleyerek, devre dışı seçenekler otomatik olarak çalışır.

Validasyon

Tüm validasyon güvenlik için backend'de gerçekleşir:

maxSelectable() bir max:X validasyon kuralı ekler
minSelectable() bir min:X validasyon kuralı ekler
Devre dışı seçenekler sunucu tarafında validate edilir (client-side bypass edilse bile gönderilemez)

Frontend özellikleri (Choices.js maxItemCount gibi) kullanıcı dostu geri bildirim sağlar ancak güvenlik için bunlara güvenilmez.

Uyumluluk

Paket sürümü, Laravel ve PHP gereksinimleri için sürüm seçimi tablosuna bakın. main dalındaki kullanım örnekleri Filament 3 içindir; Filament 4 sürümü 3.x dalında tutulur.

Sorun Giderme

Devre dışı seçenekler hala seçilebiliyor

Doğru Select componentini import ettiğinizden emin olun:

// Doğru
use Kapital\Filament\FormComponents\Components\Select;

// Yanlış
use Filament\Forms\Components\Select;

Composer paketi bulamıyor

Kurulum tanımlarını kontrol edin:

Paket adı kapital-online/filament-form-components olmalı.
Uygulamanın composer.json dosyasında VCS deposu ve tablodaki sürüm aralığı bulunmalı.
GitHub kimliğiniz veya SSH anahtarınız depoyu okuyabilmeli; etiketli kurulum için lib/ altında yerel paket kopyası gerekmez.

Max/min validasyon çalışmıyor

Validasyon kuralları otomatik olarak eklenir. Kontrol edin:

->multiple() kullanıyorsunuz
Form validate ediliyor
Validasyon hataları için Laravel loglarını kontrol edin

English

Enhanced Filament form components with extended functionality for multiple select, disabled options, and more.

The Problem

In Filament v2, the disableOptionWhen() method works perfectly for single select dropdowns, but fails to work when multiple() is enabled. This is because:

Single select uses native HTML <select> elements where disabled attributes work natively
Multiple select uses Choices.js library for better UX
Filament's transformOptionsForJs() method only passes label and value to Choices.js, omitting the disabled state

This package fixes this issue and adds additional features for enhanced select components.

The Solution

This package extends Filament's Select component and overrides the transformOptionsForJs() method to include the disabled property. Choices.js already supports disabled options natively, so no additional JavaScript is required.

Version selection and compatibility

Choose the package line that matches your Filament and Laravel versions. The Composer package name is kapital-online/filament-form-components.

Filament	Laravel	Minimum PHP	Package version	Composer command
2.x	9.x	8.0.2	`^1.2`	`composer require kapital-online/filament-form-components:"^1.2"`
2.x	10.x	8.1	`^1.2`	`composer require kapital-online/filament-form-components:"^1.2"`
3.x	10.x	8.1	`^2.1`	`composer require kapital-online/filament-form-components:"^2.1"`
3.x	11.x	8.2	`^2.1`	`composer require kapital-online/filament-form-components:"^2.1"`
4.x	11.28+ (11.x)	8.3	`^3.0`	`composer require kapital-online/filament-form-components:"^3.0"`

main contains the Filament 3 2.x line. Laravel 11 support starts at v2.1.0, so use ^2.1 for Filament 3 projects.
The 3.x maintenance branch contains v3.0.0 and later for Filament 4. It requires illuminate/support:^11.28 and PHP ^8.3; Laravel 12 and later are outside this range.
Filament 2 projects use the legacy v1.2.0 / ^1.2 line. Legacy rows describe tag dependency constraints; recent verification covers Filament 3 with Laravel 10/11 and Filament 4 with Laravel 11.

The PHP column combines package and framework minimum requirements. See the Filament 3 requirements and Laravel version table.

Installation

Use a GitHub identity or SSH key with read access to the repository. Add the VCS repository to your application if it is not already configured:

composer config repositories.filament-form-components vcs git@github.com:Kapital-Online/filament-form-components.git

Run one matching composer require command from the table. For Filament 3 with Laravel 10/11:

composer require kapital-online/filament-form-components:"^2.1"

For Filament 4 with Laravel 11.28+ / PHP 8.3, use this instead:

composer require kapital-online/filament-form-components:"^3.0"

Use a released version constraint instead of @dev or dev-main. ^2.1 stays on 2.x and ^3.0 stays on 3.x; upgrade Filament together with the application and its other plugins. Laravel discovers the package automatically.

Usage

Basic Usage (Drop-in Replacement)

Simply replace Filament's Select component with Kapital's Select:

// Before
use Filament\Forms\Components\Select;

// After
use Kapital\Filament\FormComponents\Components\Select;

// Usage remains exactly the same
Select::make('field_name')
    ->options([
        '1' => 'Option 1',
        '2' => 'Option 2',
        '3' => 'Option 3',
    ])
    ->multiple()
    ->disableOptionWhen(fn ($value) => $value === '2')

Now disableOptionWhen() works perfectly with multiple() enabled!

Features

1. Fixed `disableOptionWhen()` with Multiple Select

The primary feature - disabled options now work correctly with multiple select:

Select::make('tags')
    ->relationship('tags', 'name')
    ->multiple()
    ->disableOptionWhen(fn ($value) => Tag::find($value)?->is_system ?? false)

Disabled options will appear grayed out and cannot be selected.

2. Maximum Selectable Items (`maxSelectable`)

Limit the number of items that can be selected:

Select::make('categories')
    ->options([...])
    ->multiple()
    ->maxSelectable(3) // Maximum 3 selections allowed

Features:

Backend validation (prevents form submission if exceeded)
Frontend validation via Choices.js (user-friendly feedback)
Supports closures for dynamic limits

->maxSelectable(fn () => auth()->user()->isPremium() ? 10 : 3)

3. Minimum Selectable Items (`minSelectable`)

Require a minimum number of selections:

Select::make('required_tags')
    ->options([...])
    ->multiple()
    ->minSelectable(2) // At least 2 selections required

Features:

Backend validation
Supports closures for dynamic limits

->minSelectable(fn () => auth()->user()->isAdmin() ? 0 : 1)

4. Select All Option (`selectAllOption`)

Adds a "Select All" button. When clicked, automatically selects all non-disabled options:

Select::make('permissions')
    ->options([...])
    ->multiple()
    ->selectAllOption() // Adds "Select All" button
    ->disableOptionWhen(fn($value) => $value === 'dangerous_permission') // Disabled ones won't be selected

Features:

Automatically filters out disabled options
Appears as a hint action next to the field
Supports closures for dynamic visibility

->selectAllOption(fn () => auth()->user()->isAdmin())

5. Deselect All Option (`deselectAllOption`)

Adds a "Deselect All" button. When clicked, clears all selections:

Select::make('filters')
    ->options([...])
    ->multiple()
    ->deselectAllOption() // Adds "Clear All" button

Features:

Clears all selections with one click
Appears in red color with X icon
Supports closures for dynamic visibility

->deselectAllOption(fn () => auth()->user()->canClearAll())

6. Master-Detail Table (Filament v3)

This package also includes a master-detail infrastructure for Filament v3 resource tables.

Highlights:

Row-level expand/collapse detail with icon
Lazy detail rendering (content is mounted only when expanded)
Compatible with standard Filament table chaining
Fluent API suitable for relation/query/livewire detail definitions

Required Imports

use Filament\Tables\Table;
use Kapital\Filament\FormComponents\Resources\Table as MasterDetailResourceTable;

Resource Usage

public static function table(Table $table): Table
{
    if ($table instanceof MasterDetailResourceTable) {
        $table->masterDetailLivewire(
            component: 'overdue-payment-plan-report-transactions-table',
            parameters: fn (OverduePaymentPlanReport $record): array => [
                'userId' => $record->user_id,
            ],
            key: fn (OverduePaymentPlanReport $record): string => 'overdue-payment-plan-report-' . $record->getKey(),
        );
    }

    return $table
        ->columns([
            // Filament columns...
        ]);
}

List Page Usage

Add the trait to your resource list page class:

use Kapital\Filament\FormComponents\Tables\Concerns\InteractsWithMasterDetailTable;

class ListOverduePaymentPlanReports extends ListRecords
{
    use InteractsWithMasterDetailTable;
}

API Summary

masterDetailLivewire(component, parameters, key, expandable, expandIcon, collapseIcon, wrapperClass)
masterDetailRelation(relation)
masterDetailQuery(closure)

Note: Filament v3 Resource::table() signature must keep Filament\Tables\Table as the method argument. Package master-detail features are enabled at runtime via instanceof MasterDetailResourceTable.

Known Limitation / Recommendation

Nested table actions that open another modal inside an existing modal may cause Alpine/Livewire issues. In such cases, prefer inline detail rendering on the same page or move the action flow outside nested modals.

Real-World Example

use Kapital\Filament\FormComponents\Components\Select;
use App\Models\Tag;

Select::make('tags')
    ->label('Order Tags')
    ->relationship('tags', 'name')
    ->multiple()
    ->disableOptionWhen(function ($value) {
        // Disable system tags - they cannot be removed
        return Tag::find($value)?->is_system ?? false;
    })
    ->selectAllOption() // "Select All" button (skips disabled ones)
    ->deselectAllOption() // "Clear All" button
    ->maxSelectable(5) // Maximum 5 tags per order
    ->minSelectable(1) // At least 1 tag required
    ->searchable()
    ->preload()
    ->helperText('System tags are disabled and cannot be changed.')

All Features Comparison

Feature	Filament v2 Select	Kapital Enhanced Select
Single select with `disableOptionWhen()`	✅ Works	✅ Works
Multiple select with `disableOptionWhen()`	❌ Broken	✅ Fixed
`maxSelectable()`	❌ Not available	✅ Available
`minSelectable()`	❌ Not available	✅ Available
`selectAllOption()`	❌ Not available	✅ Available
`deselectAllOption()`	❌ Not available	✅ Available
All other Filament features	✅	✅ Fully compatible

Technical Details

How It Works

The fix is remarkably simple. The package overrides a single method:

protected function transformOptionsForJs(array $options): array
{
    return collect($options)
        ->map(fn ($label, $value): array => [
            'label' => $label,
            'value' => strval($value),
            'disabled' => $this->isOptionDisabled($value, $label), // Added this line
        ])
        ->values()
        ->all();
}

Choices.js (the library Filament uses for multiple selects) natively supports the disabled property. By including it in the options array, disabled options automatically work.

Validation

All validation happens on the backend for security:

maxSelectable() adds a max:X validation rule
minSelectable() adds a min:X validation rule
Disabled options are validated server-side (cannot be submitted even if client-side is bypassed)

Frontend features (like Choices.js maxItemCount) provide user-friendly feedback but aren't relied upon for security.

Compatibility

See the version selection table for package, Laravel and PHP requirements. Usage examples on main target Filament 3; the Filament 4 release line lives on 3.x.

Troubleshooting

Disabled options still selectable

Make sure you're importing the correct Select component:

// Correct
use Kapital\Filament\FormComponents\Components\Select;

// Wrong
use Filament\Forms\Components\Select;

Composer can't find the package

Check the installation configuration:

Use the package name kapital-online/filament-form-components.
The application's composer.json must contain the VCS repository and a matching version constraint from the table.
Your GitHub identity or SSH key must have read access; tagged installations do not require a local package copy under lib/.

Max/min validation not working

The validation rules are automatically added. Check:

You're using ->multiple()
The form is being validated
Check Laravel logs for validation errors

License

MIT

Credits

Created by Kapital Online for internal use and open-sourced for the community.

Contributing

This is an internal package, but suggestions and bug reports are welcome.

kapital-online / filament-form-components

Package info

Security

Statistics

README

Türkçe

Sorun

Çözüm

Sürüm seçimi ve uyumluluk

Kurulum

Kullanım

Temel Kullanım (Drop-in Replacement)

Özellikler

1. Düzeltilmiş disableOptionWhen() Çoklu Seçim İle

2. Maksimum Seçilebilir Öğe (maxSelectable)

3. Minimum Seçilebilir Öğe (minSelectable)

4. Tümünü Seç Seçeneği (selectAllOption)

5. Tümünü Temizle Seçeneği (deselectAllOption)

6. Master-Detail Table (Filament v3)

Gerekli Importlar

Resource Kullanımı

List Page Kullanımı

API Özeti

Bilinen Kısıt / Öneri

Gerçek Dünya Örneği

Tüm Özellikler Karşılaştırması

Teknik Detaylar

Nasıl Çalışır

Validasyon

Uyumluluk

Sorun Giderme

Devre dışı seçenekler hala seçilebiliyor

Composer paketi bulamıyor

Max/min validasyon çalışmıyor

English

The Problem

The Solution

Version selection and compatibility

Installation

Usage

Basic Usage (Drop-in Replacement)

Features

1. Fixed disableOptionWhen() with Multiple Select

2. Maximum Selectable Items (maxSelectable)

3. Minimum Selectable Items (minSelectable)

4. Select All Option (selectAllOption)

5. Deselect All Option (deselectAllOption)

6. Master-Detail Table (Filament v3)

Required Imports

Resource Usage

List Page Usage

API Summary

Known Limitation / Recommendation

Real-World Example

All Features Comparison

Technical Details

How It Works

Validation

Compatibility

Troubleshooting

Disabled options still selectable

Composer can't find the package

Max/min validation not working

License

Credits

Contributing

1. Düzeltilmiş `disableOptionWhen()` Çoklu Seçim İle

2. Maksimum Seçilebilir Öğe (`maxSelectable`)

3. Minimum Seçilebilir Öğe (`minSelectable`)

4. Tümünü Seç Seçeneği (`selectAllOption`)

5. Tümünü Temizle Seçeneği (`deselectAllOption`)

1. Fixed `disableOptionWhen()` with Multiple Select

2. Maximum Selectable Items (`maxSelectable`)

3. Minimum Selectable Items (`minSelectable`)

4. Select All Option (`selectAllOption`)

5. Deselect All Option (`deselectAllOption`)