Filament Flatpickr Laravel Package

Technical Evaluation

Architecture fit filament-flatpickr is a presentation-layer adapter and nothing more: a Filament form-field class that swaps the stock DateTimePicker for a Flatpickr-backed input, rendering through Alpine and registering JS/CSS via Filament's asset pipeline. No migrations, models, routes, policies, queues, or scheduled jobs. For a TPM this is the decisive fact, because it sets the size of the decision: the blast radius is a handful of form schema entries, and reverting is a one-line field swap. That means this does not need architecture review, a design doc, or a roadmap line item — it is a small ticket inside existing admin-tooling work, authorized at team level with a documented reverse path.

The corollary matters just as much: because the change is cheap, the temptation is to let it spread field by field until it is load-bearing without anyone deciding that. A TPM's job here is to keep it a deliberate, enumerated set of fields — not a default.

Fit is clean only where Filament's native picker genuinely falls short: inline calendars, single-input date ranges, multi-date selection, altInput-style friendly display formats, time-only inputs, and granular disabled-date rules. Where native inputs already satisfy the UX, adopting this buys dependency risk for zero functional gain, and the correct call is "no."

Integration feasibility composer require savannabits/filament-flatpickr plus one field in a schema — hours for a Filament-fluent developer. The actual cost sits in two diligence gates that a TPM owns and should not delegate to optimism:

• Provenance and license check (blocking). The Composer package name is savannabits/filament-flatpickr while the linked repository is coolsam/flatpickr. Someone must confirm in writing that these are the same artifact, who holds publish rights, and whether this is a fork chain. No composer require until that is resolved and recorded in the ticket.
• Production asset-path proof. Flatpickr assets must register through the real Vite / filament:assets pipeline, not just php artisan serve. A staging build with the production asset path is the minimum evidence before go-live is scoped.

Definition of done for the feasibility spike is not "the calendar opens." It is "the calendar opens in staging, the value round-trips correctly through Livewire, and the provenance question is answered in writing."

Technical risk

• Provenance mismatch — as above; blocking, and cheap to resolve now versus expensive after it is in a release.
• Adoption risk — ~102 stars, zero dependents, effectively bus factor of one. There is no third-party production validation to borrow confidence from; the confidence has to be manufactured internally.
• Framework churn — Filament majors routinely break third-party field APIs and asset registration. Assume this package lags or breaks, and that we own verification on every upgrade.
• Livewire state sync — Flatpickr's imperative API against wire:model two-way binding is the classic failure point, most visible on validation-error re-renders and edit-existing-record hydration.
• Date/timezone correctness — server TZ vs. browser TZ, DST boundaries, locale display formats. These produce a "stored one day off" defect that the UI hides and standard QA will not reproduce.
• Release metadata — the 2026-06-14 release date needs confirmation as genuine; if real, active maintenance, if not, treat as stale.
• No visible CI/test evidence in the supplied signals — request it rather than assume its absence.

The risk taxonomy a TPM should communicate upward: these failures are silent data-correctness bugs, not crashes. Operators won't report them, because the screen looks right. That distinction is what justifies the QA matrix as an exit criterion rather than a nice-to-have.

Key questions

1. Which Filament, Livewire, and PHP versions are in the Composer constraints, and is our target panel inside that range?
2. How are Flatpickr JS/CSS registered — Filament asset API, publish step, or manual @vite — and is it CSP-safe under our headers?
3. Does the field behave correctly inside Repeaters, Builders, table filters, and with disabled / readonly / dehydrated(false)?
4. How is the value serialized into the Livewire payload, and is timezone handling documented anywhere we can point an auditor at?
5. Is there a test suite and CI, and what has the release cadence been over the trailing twelve months?
6. Is the codebase thin enough that an internal fork is cheaper than carrying an unplanned single-maintainer dependency?

Integration Approach

Stack fit Laravel 10/11/12 + Livewire 3 + Filament 3/4 panels. One Composer dependency, one field class, optional config publish. No schema, queue, worker, or auth surface. Nothing else in the application changes, which is what keeps the approval path short and the rollback trivial.

Migration path Do not wholesale-swap every datetime field. Keep Filament's native DateTimePicker as the panel default and substitute per-field only where Flatpickr semantics are required — typically a handful of range or inline-calendar fields on internal admin screens. Explicitly exclude customer-facing surfaces where a broken date input is unrecoverable and visible to the customer rather than to an operator.

Compatibility Pin exact versions in composer.json; no floating ranges. Treat every Filament major as breaking until proven otherwise. Confirm the PHP floor and check for conflicts against other installed panel plugins before merging. Wrap the field in an internal alias (e.g. App\Filament\Fields\DateRange) so reverting to native is a one-line change and the decision stays reversible without a refactor — this wrapper is the single highest-leverage thing a TPM can insist on, because it converts a dependency decision into a configuration decision.

Sequencing

1. Provenance and license check — Composer ↔ GitHub mapping, publish rights, maintainer identity. Hard gate; no code until closed.
2. Time-boxed spike (one sprint) on a low-traffic admin screen: one form, one field, full edge-case matrix — null, edit-existing hydration, DST boundary, non-UTC timezone, validation-failure re-render, repeatable rows.
3. Commit the internal wrapper class and version pin to the repo before any second field is added.
4. Feature-flag per panel; validate against a real locale/timezone matrix in staging, not just UTC.
5. Roll out panel by panel, documenting pin, wrapper, known edge cases, and revert procedure in the README.
6. Add a recurring review item to each Filament major upgrade checklist, with a named owner.

Exit criterion for the spike, stated up front: create, edit, validation re-render, and at least two timezones, all documented. Default to "no-go" if native pickers already cover the use case.

Operational Impact

Maintenance The surface is small if pinned and wrapped, but the burden shifts onto us at every Filament upgrade. Budget roughly half a day per Filament major for verification, and put it on the upgrade checklist with a name against it rather than a good intention. If the field becomes load-bearing on a revenue-relevant screen, fork it under the org — the code is thin enough that a fork is cheaper than an unplanned dependency failing at a bad moment.

Support MIT, community-only, no SLA, single maintainer. The escalation path is "open an issue and wait" or "fix our own fork." That is an acceptable posture for internal admin tooling and an unacceptable one anywhere a broken date input is customer-facing and unrecoverable. State this explicitly when the request reaches you, so the constraint is understood before it is tested.

Scaling Negligible. Client-side only; Flatpickr adds tens of KB per page and no server or database load. The one measurable cost is JS initialization on very large forms — benchmark if any screen carries 20+ pickers, otherwise treat scaling as a non-issue and say so.

Failure modes

• Filament upgrade breaks asset registration → picker degrades to a bare text input, silently.
• Livewire re-render drops the selected value after a validation round-trip.
• Timezone drift writes the value one day off for non-UTC users.
• Assets missing in production because a publish or Vite step was skipped.
• CSP blocks inline initialization.
• Upstream abandonment leaves no fix path.

Because these are silent and non-reproducible in casual testing, QA must cover create, edit, re-render, and validation across at least two timezones. Treat that matrix as the spike's exit criterion, and treat any team that proposes skipping it as the primary risk in this ticket.

Ramp-up Hours, not days, for a Filament-fluent developer. The real budget is QA discipline around date semantics and timezone behavior, which is a habit, not a training cost. Ship a short internal note capturing the pinned version, the wrapper class path, known edge cases, and the revert procedure — that note is what makes the decision survivable past the tenure of whoever made it.

Scoring read: opportunity (22.46) runs meaningfully hotter than the composite (15.22). Translate that gap for stakeholders as "desirable capability, immature artifact" — spend diligence on maturity, provenance, and support, not on whether the capability is worth having. Recommendation: authorise the one-sprint, time-boxed prototype on a low-traffic admin screen using the two things the native picker handles awkwardly (single-input range and inline calendar), then make a documented go/no-go — defaulting to "no" where native pickers already cover the use case.