Filament Nepali Datetime Laravel Package

Product Decisions This Supports

• Nepal market entry / localization go-no-go. If any part of the roadmap touches Nepal, Bikram Sambat (BS) dates are table stakes: government filings, payroll periods, academic calendars, hospital records, land deeds, and most local businesses operate on BS, not Gregorian. This package answers "can our Filament admin handle BS dates?" with a cheap yes, which removes a common objection in market-entry discussions.
• Build vs. buy for the admin layer. It wraps Filament surfaces — a date picker, a table column, an infolist text entry, and now (v2.1.0) a timepicker — so you avoid building and maintaining custom Filament field subclasses. That's a real one-to-two-week engineering cost avoided for a small team, at the price of a dependency.
• Sets the storage convention decision. The package solves input and display; it does not decide what you persist. The PM-relevant decision it forces is: store UTC/AD in the database, present BS in the UI, and keep conversion at the edge. Locking that in early prevents a later migration where half the tables hold BS strings.
• New in v2.1.0 — time-of-day is now in scope. The timepicker widens the addressable use cases from "which day?" to "which day and when?": clinic appointment slots, exam start times, shift rosters, delivery windows, and booking cutoffs. It also raises a second decision the package does not make for you: whether a stored value is a wall-clock local time (e.g. "09:00 NPT, every Tuesday") or an absolute instant (UTC). Recurring schedules want the former; reminders and SLAs want the latter. Decide before the first table ships.
• Scopes the broader "Nepal localization" epic. It is a calendar-and-clock widget, not a localization suite. Adjacent items this surfaces but does not solve: NPR currency formatting, Devanagari numerals, NPT (+05:45) timezone handling beyond what the widget does, and Nepali fiscal-year reporting (Shrawan–Ashadh). Use it to slice the epic: this package covers the date/time-field slice only.
• Concrete use cases it unblocks: student admission and exam scheduling, patient registration and DOB capture, appointment and consultation booking, HR salary-month and leave-period entry, shift and roster planning, NGO/government grant reporting, and any admin filter where a user needs to pick "last quarter" in BS.
• Roadmap prioritization signal. A five-star, zero-dependent package with a single maintainer is a narrow enabler, not a platform bet. The timepicker is a genuine capability expansion but does not change that calculus. Fund adoption only where a Nepal-facing customer or pilot exists; don't let it justify building a whole Nepal product line on its own.

When to Consider This Package

Adopt when:

• You are on Laravel + Filament and need BS dates and/or times specifically inside forms, tables, or infolists — the exact surfaces it covers.
• The blast radius is internal admin tooling or back-office data entry, where a display bug is annoying rather than statutory.
• Your team has no in-house Nepali-calendar expertise and no appetite to own a BS↔AD conversion table.
• You need combined date + time capture in BS — appointment slots, class times, shift starts — and would otherwise stitch a generic timepicker onto a BS date field yourself.
• You can pin the version, wrap it behind your own component, and swap the underlying converter later without touching every form.
• You will validate conversions yourself against a trusted reference across boundary cases: BS month lengths vary year to year, and the hardcoded lookup table only spans a finite year range. Test the edges of that range and leap-year-adjacent dates before shipping. With v2.1.0, extend the matrix to datetime boundaries: a BS date at 00:00 NPT is 18:15 UTC on the previous Gregorian day, so any code that converts date and time separately, or truncates before converting, will silently shift appointments by a day.

Look elsewhere — or budget build time — when:

• You need BS↔AD conversion outside Filament: APIs, PDFs, exports, mobile apps, notification text, or scheduled jobs. Use a standalone nepali-datetime-style library and keep Filament glue thin.
• You need timezone conversion or recurrence logic, not just a time field. The timepicker captures a wall-clock value; DST-free but odd-offset handling, recurring schedules, duration math, and reminder fan-out are still yours to own.
• You need dates outside the supported conversion range (historical records, long-horizon forecasts).
• You need fiscal-year or period logic, not just a date field. The Nepali FY starts mid-July; that's reporting logic you own.
• You need the whole UI localized into Nepali. This is one component family, not a locale pack.
• Your procurement requires active maintenance, a support SLA, or a security-review trail. Five stars, zero dependents, and a lone maintainer mean no support contract — acceptable only because MIT licensing and a thin wrapper keep exit costs near zero.
• You are on a Filament version other than the one it targets, or you have a Filament major upgrade on the near roadmap. Verify compatibility before committing; the wrapper's surface tracks Filament's internals.

How to Pitch It (Stakeholders)

For executives: This is a small open-source (MIT) component that lets our admin panel accept and display Nepali dates and times — the calendar and clock our Nepal-facing users actually work in. The latest release (v2.1.0) added the timepicker, which extends it from "which day" to "which day and when," covering appointment and shift-scheduling use cases we would otherwise have had to build. It turns a localization blocker into a few days of integration work, with no license cost and no vendor lock-in, because it's a thin wrapper we can replace. The trade-off is unchanged: a young package with one maintainer and no meaningful adoption yet. We mitigate that by pinning the version, keeping conversion behind our own interface, and running our own correctness tests against an independent reference — now including time-of-day and date-boundary cases — before any customer sees it.

For engineering: It's glue, not a calendar engine — and as of v2.1.0, glue for clocks as well as calendars. It gives us Filament-native date picker, timepicker, table column, and infolist entry components that speak Bikram Sambat. Consume it as a pinned dependency (v2.1.0 is a minor, feature-only bump, so moving off 2.0.5 is low-risk but does add new surface to test), wrap it in our own NepaliDateInput / NepaliDateTimeInput, and treat conversion as a separate, tested concern — storage stays UTC/AD, BS is presentation and input only. Plan for a validation matrix around supported date-range boundaries, month-length irregularity, and the new timepicker: combined date+time round-trips, midnight boundaries where the NPT (+05:45) offset rolls the Gregorian date backwards, and whatever precision and seconds handling the component exposes. If we ever need BS dates or times outside Filament, we swap the converter underneath our wrapper and keep the UI unchanged.