Getting Started

Install with composer require shayanys/iranian-date-picker. Before committing, confirm the version you get is compatible with your Filament major — the last release (2023-04-26) predates Filament v3 stable, so budget time to test on v2 or an early v3.
Read the repository README first; with 24 stars, no docs site, and zero dependents, that file plus src/ is your only source of truth. Skim the service provider to see what it auto-registers and whether there are publishable config/assets.
If assets need publishing, run php artisan vendor:publish for the package tag and php artisan filament:assets. A calendar that refuses to open is almost always a missing asset, not a logic bug.
First use case: a single Jalali date field on a resource form — birthday, due_date, delivery_at — where the operator picks in the Persian calendar but you persist a normal Gregorian DATE/DATETIME column so the rest of your app (Eloquent casts, Carbon, reports) keeps working.

Implementation Patterns

Form field: drop the provided component into your schema, e.g. IranianDatePicker::make('due_date')->label('تاریخ سررسید'). Keep the underlying column a standard date cast.
Store Gregorian, render Jalali: this is the pattern that keeps you portable. Use an accessor or TextColumn::formatStateUsing() with verta()/Morilog\Jalali for display, and let the picker handle input.
Validation: validate against Gregorian boundaries, not Jalali strings. Convert in a before() hook or a custom rule so "not before today" and min/max windows stay correct across leap months.
Table filters and widgets: reuse the same component inside a filter closure, then convert the picked range to Gregorian in ->query(fn ($q, $data) => $q->whereBetween(...)).
Repeaters and nested forms: generally safe, but add a ->key() if Livewire re-renders leave stale inputs or a picker attached to the wrong row.
Testing: create fixtures with Gregorian dates and assert on the stored column; don't assert on widget output, which is locale/JS dependent.

Maintenance risk: 24 stars, 0 dependents, last release over a year stale. Treat it as a small wrapper, not infrastructure — fork it if it breaks against your Filament version.
Version drift: Filament component namespaces and Field base classes changed between v2 and v3. A Class not found error usually means version mismatch, not a bug in your code.
Storage ambiguity: confirm whether the field dehydrates a Jalali string or a Gregorian Y-m-d. Dump $livewire->data after submit; if it's Jalali, add ->dehydrateStateUsing(fn ($state) => Jalali::toGregorian($state)) before saving.
Timezone: the JS picker likely assumes Asia/Tehran. If your app runs UTC, selections near midnight shift by a day — normalize in a mutator or set the app timezone explicitly.
Debugging: check the browser console for 404s on the picker bundle first, then inspect the Livewire payload to see exactly what state the field emits.
Extension point: for time selection, ranges, or custom formatting, wrap the package's component and layer your own JS rather than patching vendor/.
Alternative: morilog/jalali plus Filament's stock DatePicker with a format()/dehydrateStateUsing conversion is a viable drop-in if you'd rather not depend on an unmaintained plugin.