Download the PHP package kapital-online/filament-form-components without Composer

Kapital Filament Form Components

🇬🇧 English

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:

1. Tekli seçim native HTML <select> elementi kullanır ve disabled attribute doğal olarak çalışır
2. Çoklu seçim daha iyi UX için Choices.js kütüphanesi kullanır
3. 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.

Kurulum

1. composer.json'a Ekleyin

Bu yerel bir paket olduğu için root composer.json dosyasına ekleyin:

2. Composer'ı Güncelleyin

Paket Laravel'in package discovery mekanizması ile otomatik olarak yüklenecektir.

Kullanım

Temel Kullanım (Drop-in Replacement)

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

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:

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:

Ö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

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

Minimum sayıda seçim zorunluluğu:

Özellikler:

• Backend validasyonu
• Closure desteği ile dinamik limitler

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:

Ö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

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:

Ö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

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

Resource Kullanımı

List Page Kullanımı

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

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

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

Teknik Detaylar

Nasıl Çalışır

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

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

• Laravel: 9.x, 10.x
• Filament: v3.x
• PHP: 8.0.2+

Sorun Giderme

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

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

Composer paketi bulamıyor

Paketin doğru konumda olduğundan emin olun:

• Yol: lib/filament-form-components/
• Root composer.json dosyasında paket require bölümünde var
• composer update veya composer dump-autoload çalıştırın

Max/min validasyon çalışmıyor

Validasyon kuralları otomatik olarak eklenir. Kontrol edin:

1. ->multiple() kullanıyorsunuz
2. Form validate ediliyor
3. 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:

1. Single select uses native HTML <select> elements where disabled attributes work natively
2. Multiple select uses Choices.js library for better UX
3. 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.

Installation

1. Add to composer.json

Since this is a local package, add it to your root composer.json:

2. Update Composer

The package will be auto-discovered via Laravel's package discovery mechanism.

Usage

Basic Usage (Drop-in Replacement)

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

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:

Disabled options will appear grayed out and cannot be selected.

2. Maximum Selectable Items (maxSelectable)

Limit the number of items that can be selected:

Features:

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

3. Minimum Selectable Items (minSelectable)

Require a minimum number of selections:

Features:

• Backend validation
• Supports closures for dynamic limits

4. Select All Option (selectAllOption)

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

Features:

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

5. Deselect All Option (deselectAllOption)

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

Features:

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

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

Resource Usage

List Page Usage

Add the trait to your resource list page class:

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

All Features Comparison

Technical Details

How It Works

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

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

• Laravel: 9.x, 10.x
• Filament: v3.x
• PHP: 8.0.2+

Troubleshooting

Disabled options still selectable

Make sure you're importing the correct Select component:

Composer can't find the package

Ensure the package is in the correct location:

• Path: lib/filament-form-components/
• Root composer.json has the package in require section
• Run composer update or composer dump-autoload

Max/min validation not working

The validation rules are automatically added. Check:

1. You're using ->multiple()
2. The form is being validated
3. 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.