Filament Timepicker Laravel Package

Product Decisions This Supports

• Time-entry UX as a differentiating feature, not a nice-to-have. If our users enter times frequently — scheduling, booking, clinic/appointment slots, shift planning, dispatch windows — this package replaces a dropdown of 96 options with a type-ahead that accepts 3p, 330, 1530, 9.30. That is a measurable input-speed and error-rate decision, and it is cheap to test behind a single field swap.
• Build vs. buy for a "smart input" primitive. The alternative is 2–4 weeks of one engineer building parsing, keyboard nav, dropdown positioning, validation, and accessibility from scratch, plus the ongoing tail of bug reports (this package's own v1.1.0 changelog is essentially a catalogue of those bugs: focus-commit on Tab, panel mispositioning, stale reactive config). Buying is clearly correct if we need even two of those behaviours.
• Data-model decision: wall-clock vs. timezone-aware storage. This package commits to wall-clock H:i with a deliberate "never introduce a timezone shift" contract and a regression test guarding it. Adopting it means a schedule slot is a local wall-clock fact — which is right for "the 3:00 PM appointment at this location," but wrong for cross-timezone coordination. That is a product decision to make explicitly, before the schema is written, not after.
• Validation and guardrail decisions become configuration. minTime()/maxTime() are now enforced both client-side and via a server validation rule (so pastes, $set, and imports can't bypass them), and strict() additionally confines input to the interval grid. Business rules like "no bookings before 08:00 or after 18:00, on the quarter hour" become field config rather than custom validation code — a roadmap lever we can flip per-market or per-plan.
• Derived-field decisions get cheap. durationFrom() and defaultDuration() let a start time auto-fill an end time and label options with their duration ("3:00 PM — 30 min"). That is a real scheduling product feature (avoiding zero-length or overlapping bookings) available as two chained calls.
• Accessibility and compliance roadmap. Keyboard navigation (Home/End/PageUp/PageDown), aria-invalid on error, and the removal of a focus-commit bug that silently wrote values into untouched optional fields are procurement-relevant for enterprise/health customers running accessibility audits.
• Scope discipline for our own roadmap. Because it only depends on filament/forms and not the full panel package, we can ship the same field in a plain Livewire admin surface without dragging a panel dependency in — which affects whether an internal-tools roadmap item is one sprint or three.

When to Consider This Package

Adopt when:

• We are on Filament v4 or v5 and building forms where time-of-day is a first-class input, especially high-frequency or back-office operator entry.
• Our domain is wall-clock scheduling — appointments, bookings, opening hours, shifts at a site — where "15:00" is a fact, not a UTC instant.
• We want bounded, gridded input (business hours, quarter-hour slots) as declarative field config rather than bespoke validation.
• We are on a custom Filament theme: v1.1.0 ships its own CSS asset that reads Filament's runtime --gray-* variables, so no @source line or theme surgery is required.
• We accept the trade of a small, single-maintainer package in exchange for a narrow, well-tested surface (PHP + JS test suites that share one parse-cases fixture, so the mirrored parsers can't drift silently).

Look elsewhere when:

• We are not on Filament — this is a Filament form field, not a general Livewire or Blade component. Porting it is a rewrite of the view and asset pipeline.
• We need true timezone-aware scheduling — converting, storing in UTC, or rendering per-user-local times. The timezone() method is an explicit no-op by design; using it as if it worked is the most likely integration mistake.
• We need a date + time range picker, recurrence rules, or calendar UI — out of scope. This is a single time field.
• We require vendor SLAs, security review programmes, or long-term support commitments. Three stars, zero dependents, and one maintainer means the realistic mitigation is pinning a version and budgeting a fork, not negotiating support.
• We need sub-minute precision or seconds-aware pickers as the default — seconds() exists but the parsing grammar and UX are minute-granular.
• We want drop-in parity with Filament's native TimePicker without behaviour change — native() and timezone() are no-ops for signature compatibility only; if a migration must be invisible, that's a docs-and-expectations conversation, not a free swap.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a recurring, cheap-to-solve usability problem wherever staff or customers type a time into our admin tools — 96-item dropdowns, inconsistent formats, and validation that only catches bad values after submit. This is an MIT-licensed, actively maintained form field for Filament (our admin stack) that turns a free-typed entry like "3p" or "330" into a validated, business-hours-bounded time value, with keyboard and screen-reader support, in roughly the time it takes to install a dependency. It was extracted from a real production scheduling app, which is why it has opinionated defaults on the two things that actually break scheduling software: timezone drift on stored times, and validation that can be bypassed. Cost is near zero; the main residual risk is that it is a small, single-maintainer package, which we mitigate by pinning a version and keeping our usage to the documented public API. Recommendation: pilot it on one scheduling form this cycle and expand only if input-error rates and entry time improve.

For engineering (the honest version): It's a standalone Filament Standalone Plugin — no Plugin object, all config in the service provider — requiring filament/forms only, so no panel dependency leaks in. The public API (interval, minTime, maxTime, durationFrom, defaultDuration, displayFormat, seconds, strict) is declared a stable contract. It stores wall-block H:i with parsing normalisation in dehydrateStateUsing; do not treat timezone() as functional. It mirrors a PHP and a JS parser that are kept in lockstep by a shared JSON fixture in both suites — so if we add format support, we change both parsers and add a fixture row, or CI fails. There is a server-side validation rule that catches anything bypassing the client. The known sharp edges are documented in the changelog and AGENTS.md: wire:ignore on the Alpine root is load-bearing (removing it breaks the teleported panel after Livewire morphs), reactive minTime/maxTime/interval closures reach the browser through a data-config sibling element, and the panel is positioned imperatively rather than via a :style binding. Read the first two of those before touching the view. Test coverage is genuinely good for a package this size — JS suite, PHP suite, architecture tests, and feature tests rendering through a real Livewire component. Pin the version, run php artisan filament:assets on upgrade, and keep our consumer-side regression test that asserts slot times store as wall-clock.