Filament Nepali Datetime Laravel Package

Technical Evaluation

Architecture fit. Unchanged in principle: the package wraps FilamentDateTimePicker/TextColumn/TextEntry (and now, with v2.1.0, the time-bearing variants) to render and accept Bikram Sambat dates while persisting Gregorian values — correct localization placement, no schema coupling. The release does not alter the core structural critique: calendar logic remains reachable only through UI components, not through an application-owned conversion service. If anything, the addition of a timepicker sharpens it. Date-only conversion has one boundary (the calendar day); datetime conversion adds hour, minute, and second across a UTC+05:45 offset, which is exactly the logic that should live in one owned, tested service rather than inside a Filament component wrapper. Treat the package as a UI adapter, not a calendar library — and now also not a timezone library.

Integration feasibility. Still Composer-installable, MIT, small surface (three-ish components), single maintainer, negligible dependents. v2.1.0 is a minor bump, which suggests semver-compatible and non-breaking, but the release note is a single line ("Timepicker by @rohanAdhikari1 in #13") with no migration guidance, no deprecation notes, and no stated compatibility matrix. We should not infer "non-breaking" from the version number alone — verify that the timepicker is additive (new component/option) rather than a behavioral change to the existing date-only components. The decisive gating questions are now: which Filament major, and does the timepicker wrap Filament's DateTimePicker internals or reimplement its Alpine/JS layer? The former is upgrade-fragile; the latter is upgrade-fragile and requires a manual audit.

Technical risk. Ranked, with the release's effect noted:

1. Calendar-data correctness (highest, unchanged). BS month lengths are irregular (29–32) and table-driven. Finite horizon, silently wrong outside it. v2.1.0 does not touch this.
2. Time-of-day conversion (new, elevated). The timepicker converts a datetime across a 5h45m offset. Every conversion is now a potential off-by-one on the day when the time component crosses midnight in one calendar but not the other. This was previously a footnote under "timezone semantics"; it is now a live feature surface.
3. Filament internal-API churn (elevated). DateTimePicker is a more complex component than DatePicker — more internals, more Livewire binding, more Alpine state. The most upgrade-fragile integration point in the TALL stack just got broader.
4. Livewire state hydration (elevated). Datetime state round-trips more values per interaction (date + time + timezone assumption). Drift and re-conversion on each hydrate/dehydrate cycle is now a larger surface, and "conversion is not idempotent" bugs become easier to introduce.
5. Timezone semantics (elevated, now central). UTC+05:45, no DST. With a time component, the contract must be explicit: is the entered wall-clock time Kathmandu local or app-local? What is stored — UTC, app tz, or naive local? Any ambiguity produces a 5h45m systematic error that looks plausible.
6. Query-layer mismatch (unchanged). BS displayed, AD stored; sorting/filtering/aggregates operate on raw AD. Time components make range filters harder to reason about (inclusive day boundaries in which calendar?).
7. Locale surface (unchanged). Devanagari numerals, Nepali month/weekday names, Saturday week-start, input format parsing — still orthogonal concerns, and now also AM/PM vs 24-hour conventions and Nepali time formatting.

Key questions. Updated for the release; the timepicker questions are the new gate.

• Which Filament major version(s) does composer.json allow, and is that constraint an upper bound or open-ended?
• Is the v2.1.0 timepicker additive? Does it add a new component/flag, or change defaults for existing date-only usage? Any breaking change to existing published views/config?
• What is the timezone contract for the time component? Does it interpret input as Asia/Kathmandu, config('app.timezone'), or naive? What exactly is persisted — UTC, app tz, or local wall clock?
• Does it wrap Filament's DateTimePicker or reimplement the picker JS? If reimplemented, has the Alpine/Livewire layer been audited for clearable state, min/max bounds, keyboard entry, and step/seconds handling?
• Does conversion round-trip exactly (BS→AD→BS) for datetimes, including times near midnight and month/year boundaries?
• Does it delegate conversion to a maintained BS library or embed tables — and what is the supported BS year range at both ends?
• Are BS values ever written to the database, or is AD strictly canonical? Are casts, validation rules, and API resources AD-only?
• How are Devanagari digits, month names, week-start, and 12/24-hour input handled — rejected or coerced?
• Do table filtering and sorting remain correct now that some values carry a time component?
• Is there a test suite, and does it assert against an independent authoritative BS reference rather than its own tables — and does it now cover time-of-day cases?
• What is the documented upgrade policy, and has the maintainer shipped against more than one Filament major?

Integration Approach

Stack fit. Unchanged: Laravel 10/11+, PHP 8.1+, Filament v3 (verify v4), Livewire 3, standard TALL admin panel. Still a pure-admin-surface concern touching no queues, APIs, migrations, or auth. The timepicker widens the blast radius modestly — any resource that captures timestamps (appointments, shifts, deadlines, audit-style fields) becomes a candidate, which is a larger set than date-only fields.

Migration path. The five-step additive/reversible path stands, with one addition driven by v2.1.0:

1. Pin and isolate at an exact version behind an internal facade/alias so a fork swap is a one-line change.
2. Pilot on one low-risk resource — and prefer a date-only pilot first, so the timepicker is validated as a distinct second step rather than bundled into initial adoption.
3. Validate against a golden dataset before any write path: known BS↔AD pairs spanning month-length edge cases, Baisakh 1, the table horizon — extended for v2.1.0 with datetime cases at 00:00, 23:59, 05:45, 18:15, and crossings that land on different calendar days in Kathmandu vs UTC.
4. Promote resource by resource, gated on golden tests in CI.
5. Never migrate existing AD columns to BS; storage stays Gregorian.

Compatibility. Build the explicit three-axis support matrix (Filament major, PHP minor, Livewire) and pin all of it — the package's own constraints may be looser than reality. Two checks before committing, unchanged but sharper post-release: (a) is our Filament version inside the package's tested range or merely its composer.json range; (b) does the timepicker pass through Filament's picker JS or replace it. Given a one-line release note and no changelog detail, also verify empirically that v2.0.5 → v2.1.0 does not alter existing date-only rendering before promoting the upgrade into a shared branch.

Sequencing. Compatibility audit → v2.0.5→v2.1.0 regression check on existing date-only screens → fork-or-facade decision → golden-dataset harness (dated + datetime) → date-only single-resource pilot → timepicker pilot on a separate resource → documented conventions (AD canonical, BS at the edge, timezone explicit) → broader rollout → upstream contribution policy. Steps 1–4 remain the gate; the timepicker adds roughly a half-week of edge-case testing and one JS audit. Realistically: one engineer-week for a defensible date-only pilot, plus three to five days to extend to datetime. The harness is reusable even if the package is abandoned.

Operational Impact

Maintenance. Still vendored code with a friendly upstream. 5 stars, 0 dependents, single maintainer, no downstream production signal, and a release whose entire documentation is a PR link. The steady state is unchanged: we carry the fork, backport Filament compatibility fixes, and extend BS tables. v2.1.0 adds a new component to carry — small, but it means our fork diverges faster. Budget and assign it; the table horizon remains a scheduled maintenance item with a calendar reminder years ahead.

Support. No SLA, no vendor, GitHub issues only; internal escalation terminates at our own engineer. The timepicker slightly raises the cost of being the terminal support tier, because datetime bugs reported by users are harder to reproduce and triage than date-only ones. Still acceptable for admin-panel convenience; still unacceptable for anything a customer invoices against.

Scaling. Runtime cost remains negligible. Organizational scaling risk is unchanged and now slightly worse: every timestamped Filament resource is a new place to draw the AD/BS and local/UTC boundaries incorrectly. Without a written convention — including the timezone contract — divergence accumulates. Multi-region deployments get a sharper edge case: operators in different timezones viewing the same record may expect different calendars and different wall-clock times, and a globally-configured BS rendering with an implicit Nepal timezone is a one-size-fits-none answer that will be wrong for the non-Nepali operator.

Failure modes. Ordered by insidiousness:

• Silent date corruption. Out-of-range/unsupported-year conversion yields a plausible-but-wrong date with no error. Highest severity, lowest detectability. Unchanged by the release.
• Silent timezone shift (new). Timepicker stores or reads the time component in an unspecified timezone; every record is off by 5h45m or by a full day, consistently, with no exception raised. Detected late, because the values look reasonable.
• Off-by-one at boundaries (elevated). Month-end and midnight/UTC+05:45 crossings on datetime values — previously an edge case, now a per-entry risk.
• Post-upgrade UI breakage. A Filament minor bump breaks the wrapper's rendering or Livewire binding; caught in staging if the pilot resources are in the smoke-test set, otherwise by users. Timepicker raises the probability.
• Filter/sort divergence. Users filter in BS, results sort in AD; with time components, day-range semantics are ambiguous in both calendars.
• Input coercion. Devanagari numerals, Nepali month names, or 12/24-hour input silently mangled or rejected on the write path.
• Table exhaustion. Post-horizon dates fail or fabricate.

Ramp-up. Still low mechanically — component-swap, not paradigm shift; productive in under a day for a Filament-fluent engineer. The domain cost is unchanged and the timepicker adds a second axis to it: BS month irregularity, the ~56.7-year offset, Baisakh 1, the UTC+05:45 boundary, and now the local-vs-stored wall-clock semantics. Require a named owner for calendar and timezone correctness, and at least one Nepali-literate reviewer in QA for date- and time-facing acceptance tests. Without that, the date-only pilot will pass, the timepicker will ship, and the edge cases will surface as a slow trickle of "the meeting shows the wrong day" tickets.