@grampro/kit 0.0.0-stage → 2.4.1

package/source/components/date-picker/README.md

@@ -0,0 +1,141 @@
+# DatePicker and DateRangePicker
+
+Two date fields built on one engine and styled to match the DataGrid and the
+Combobox. No runtime dependencies besides React 19.
+
+- **`<DatePicker>`** — one date.
+- **`<DateRangePicker>`** — a start and an end, with a live preview between them.
+
+Both support typed entry in the user's own date order, min/max limits, blocked
+days, month and year panels, week numbers, forms, full keyboard control, dark
+mode and right-to-left layouts.
+
+## Setup
+
+```ts
+import { DatePicker, DateRangePicker } from "@/components/date-picker";
+import "@/components/date-picker/styles.css";
+```
+
+The stylesheet reads the shared `--gbs-*` variables when you set them on
+`:root`, so every component in the library shares one theme, and falls back to
+the same default palette otherwise.
+
+## Basic usage
+
+```tsx
+const [date, setDate] = useState<Date | null>(null);
+
+<DatePicker label="Start date" value={date} onChange={setDate} />;
+
+const [range, setRange] = useState<DateRange>({ start: null, end: null });
+
+<DateRangePicker label="Period" value={range} onChange={setRange} />;
+```
+
+Both are controlled with `value` + `onChange`, or uncontrolled with
+`defaultValue`. `value`, `defaultValue`, `min` and `max` accept a `Date`, an ISO
+`yyyy-mm-dd` string or a timestamp; `onChange` always gives you `Date` objects at
+local midnight. The range picker's `onChange` also receives a `complete` flag,
+which is `false` after the first of the two clicks.
+
+## Props
+
+Shared by both components:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `min` / `max` | `Date \| string \| number` | — | Earliest and latest selectable day. |
+| `isDateDisabled` | `(date: Date) => boolean` | — | Called per rendered day; return true to block it. |
+| `locale` | `string` | runtime locale | Decides month names, field order and the first day of the week. |
+| `weekStartsOn` | `0`–`6` | locale's first day | 0 is Sunday. |
+| `format` | `Intl.DateTimeFormatOptions \| (date, locale) => string` | `{ year, month: "short", day }` | How the chosen date is written in the field. |
+| `numberOfMonths` | `number` | `1` (range: `2`) | Months shown side by side. |
+| `showWeekNumbers` | `boolean` | `false` | Adds an ISO week column. |
+| `showToday` | `boolean` | `true` (range: `false`) | The "Today" shortcut in the footer. |
+| `allowInput` | `boolean` | `true` | Let people type a date. When false the field is read-only and opens on click. |
+| `fixedWeeks` | `boolean` | `true` | Always six week rows, so the popover never changes height. |
+| `label`, `description`, `error` | `ReactNode` | — | Field label, hint and error message. `error` also marks the control invalid. |
+| `placeholder` | `string` | the locale's pattern | e.g. `dd/mm/yyyy`. |
+| `required`, `disabled`, `readOnly` | `boolean` | `false` | Field states. |
+| `clearable` | `boolean` | `true` | Show the clear button. |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `"md"` | Control height and font size. |
+| `name` | `string` | — | Posts `yyyy-mm-dd` in a hidden input. The range picker posts `name-start` and `name-end`. |
+| `className`, `classNames`, `style` | — | — | Styling hooks. Slots: `root`, `label`, `control`, `input`, `popover`, `calendar`, `day`, `footer`, `presets`. |
+| `localeText` | `Partial<DatePickerLocaleText>` | English | Overrides UI text. |
+| `onOpenChange` | `(open: boolean) => void` | — | Fires when the calendar opens or closes. |
+| `ref` | `Ref<DatePickerHandle<T>>` | — | `open()`, `close()`, `toggle()`, `focus()`, `clear()`, `getValue()`. |
+
+`DatePicker` adds `value` / `defaultValue` (`Date \| null`) and `closeOnSelect`
+(default `true`). `DateRangePicker` adds `value` / `defaultValue`
+(`{ start, end }`), `presets` and `closeOnSelect` (closes once both ends are set).
+
+## Typed entry
+
+People can type instead of picking. Input is read in the locale's own field
+order, so `03/04/2026` is 3 April in `en-GB` and 4 March in `en-US`. ISO
+(`2026-03-12`) is accepted in every locale, month names work (`12 Mar 2026`), and
+a missing year or month falls back to the month on screen. The calendar follows
+along as you type. Text that isn't a date, or a date outside the limits, shows a
+message when the field loses focus and leaves the value untouched.
+
+## Range presets
+
+```tsx
+<DateRangePicker
+  value={range}
+  onChange={setRange}
+  presets={[
+    { label: "Last 7 days", range: { start: addDays(new Date(), -6), end: new Date() } },
+    { label: "This month", range: { start: startOfMonth(new Date()), end: new Date() } },
+  ]}
+/>
+```
+
+## Keyboard
+
+| Keys | Action |
+| --- | --- |
+| **Enter**, **↓** | Open the calendar (from the field). |
+| **←** / **→** | Previous / next day (swapped in right-to-left layouts). |
+| **↑** / **↓** | Same weekday, previous / next week. |
+| **Home** / **End** | First / last day of the week. |
+| **Page Up** / **Page Down** | Previous / next month. |
+| **Shift + Page Up/Down** | Previous / next year. |
+| **Enter**, **Space** | Choose the focused day. |
+| **Escape** | Close and return focus to the calendar button. |
+
+Each month is a `role="grid"` where only the focused day is tabbable, which is
+the WAI-ARIA pattern for a date picker. The calendar renders in the top layer
+through the native Popover API, so it is never clipped by a scrolling parent
+(including inside a DataGrid cell).
+
+## Theming
+
+Override `--dp-*` variables (they default to the grid's `--dg-*`):
+
+```css
+.dp-root { --dp-accent: #7c3aed; --dp-radius: 12px; --dp-day-size: 38px; }
+```
+
+State attributes for styling: `data-state="open"`, `data-size`, `data-invalid`,
+`data-disabled` on the root and control; `data-today`, `data-selected`,
+`data-outside`, `data-weekend` on days; `data-in-range`, `data-range-start`,
+`data-range-end` on day cells.
+
+## Headless use
+
+`useDatePicker()` holds the whole engine (selection, visible months, typed
+input, keyboard movement, popover state) and is exported if you want a different
+UI on top. The framework-free helpers — `buildMonth`, `buildMonths`, `parseDate`,
+`formatDate`, `moveByKey`, `normalizeRange`, `isInRange`, `toISODate` — are
+exported from `@/components/date-picker/core` and also run on a server.
+
+## Known limits
+
+- Dates only: no time-of-day or time zone selection. Values are local midnight.
+- One range per field; multiple disjoint ranges aren't supported.
+- Only the Gregorian calendar is handled, though month and weekday names,
+  field order and the first day of the week all follow the locale.
+- When rendering on a server, pass `locale` explicitly so the server and the
+  browser format the field identically.

package/source/components/date-picker/core/calendar.ts

@@ -0,0 +1,266 @@
+import type {
+  CalendarDay,
+  CalendarMonth,
+  CalendarWeek,
+  DateInput,
+  DateLimits,
+  DateRange,
+} from "./types";
+
+/**
+ * Every date in this package is a local-time Date at midnight. Keeping one
+ * convention means day comparisons never depend on hours, time zones or DST,
+ * and `toISODate` never shifts a day the way `toISOString` does.
+ */
+export function startOfDay(date: Date): Date {
+  const copy = new Date(date.getTime());
+  copy.setHours(0, 0, 0, 0);
+  return copy;
+}
+
+/** Strict `yyyy-mm-dd` in local time; null for anything else, including `2026-02-31`. */
+export function parseISODate(text: string): Date | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text.trim());
+  if (!match) return null;
+  const year = Number(match[1]);
+  const month = Number(match[2]) - 1;
+  const day = Number(match[3]);
+  const date = new Date(year, month, day);
+  date.setHours(0, 0, 0, 0);
+  const valid =
+    date.getFullYear() === year && date.getMonth() === month && date.getDate() === day;
+  return valid ? date : null;
+}
+
+export function toISODate(date: Date): string {
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${date.getFullYear()}-${month}-${day}`;
+}
+
+/** Normalizes a prop value. ISO strings are read as local dates, not UTC. */
+export function toDate(value: DateInput | null | undefined): Date | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") {
+    const iso = parseISODate(value);
+    if (iso) return iso;
+  }
+  const date = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : startOfDay(date);
+}
+
+/** Negative when `a` is the earlier day, 0 on the same day. Ignores the time. */
+export function compareDay(a: Date, b: Date): number {
+  return (
+    a.getFullYear() - b.getFullYear() || a.getMonth() - b.getMonth() || a.getDate() - b.getDate()
+  );
+}
+
+export const isSameDay = (a: Date | null | undefined, b: Date | null | undefined): boolean =>
+  a != null && b != null && compareDay(a, b) === 0;
+
+export const isSameMonth = (a: Date, b: Date): boolean =>
+  a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+
+export const daysInMonth = (year: number, month: number): number =>
+  new Date(year, month + 1, 0).getDate();
+
+export function addDays(date: Date, amount: number): Date {
+  const copy = new Date(date.getFullYear(), date.getMonth(), date.getDate() + amount);
+  copy.setHours(0, 0, 0, 0);
+  return copy;
+}
+
+/** Keeps the day of the month where the target month is long enough (Jan 31 + 1 → Feb 28). */
+export function addMonths(date: Date, amount: number): Date {
+  const year = date.getFullYear();
+  const month = date.getMonth() + amount;
+  const day = Math.min(date.getDate(), daysInMonth(year, month));
+  const copy = new Date(year, month, day);
+  copy.setHours(0, 0, 0, 0);
+  return copy;
+}
+
+export const startOfMonth = (date: Date): Date =>
+  new Date(date.getFullYear(), date.getMonth(), 1);
+
+export const endOfMonth = (date: Date): Date =>
+  new Date(date.getFullYear(), date.getMonth() + 1, 0);
+
+export function clampDate(date: Date, min?: Date | null, max?: Date | null): Date {
+  if (min && compareDay(date, min) < 0) return startOfDay(min);
+  if (max && compareDay(date, max) > 0) return startOfDay(max);
+  return date;
+}
+
+export function isDayDisabled(date: Date, limits: DateLimits = {}): boolean {
+  if (limits.min && compareDay(date, limits.min) < 0) return true;
+  if (limits.max && compareDay(date, limits.max) > 0) return true;
+  return limits.isDateDisabled?.(date) === true;
+}
+
+interface WeekInfoLocale {
+  getWeekInfo?(): { firstDay: number };
+  weekInfo?: { firstDay: number };
+}
+
+/**
+ * First day of the week for a locale, 0 = Sunday. Browsers expose this through
+ * `Intl.Locale`; where they don't, ISO Monday is used unless `explicit` is given.
+ */
+export function resolveWeekStart(locale?: string, explicit?: number): number {
+  if (explicit !== undefined) return ((explicit % 7) + 7) % 7;
+  try {
+    const tag = locale ?? new Intl.DateTimeFormat().resolvedOptions().locale;
+    const info = new Intl.Locale(tag) as unknown as WeekInfoLocale;
+    const firstDay = info.getWeekInfo?.().firstDay ?? info.weekInfo?.firstDay;
+    if (typeof firstDay === "number") return firstDay % 7;
+  } catch {
+    // Locale data is unavailable in this runtime; fall through to the ISO default.
+  }
+  return 1;
+}
+
+/** ISO 8601 week number: week 1 is the one holding the first Thursday of the year. */
+export function getISOWeek(date: Date): number {
+  const target = startOfDay(date);
+  target.setDate(target.getDate() - ((target.getDay() + 6) % 7) + 3);
+  const firstThursday = new Date(target.getFullYear(), 0, 4);
+  firstThursday.setDate(firstThursday.getDate() - ((firstThursday.getDay() + 6) % 7) + 3);
+  const week = 7 * 24 * 60 * 60 * 1000;
+  return 1 + Math.round((target.getTime() - firstThursday.getTime()) / week);
+}
+
+export interface BuildMonthOptions extends DateLimits {
+  /** 0 = Sunday. Default Monday. */
+  weekStartsOn?: number;
+  /** Always six week rows, so the popover height never jumps. Default true. */
+  fixedWeeks?: boolean;
+  /**
+   * Injected so a test can pin "today". `null` marks no day at all, which is
+   * what a server render and the hydrating render pass (see core/today.ts).
+   */
+  today?: Date | null;
+}
+
+export function buildMonth(
+  year: number,
+  month: number,
+  options: BuildMonthOptions = {},
+): CalendarMonth {
+  const { weekStartsOn = 1, fixedWeeks = true, today = startOfDay(new Date()) } = options;
+  const first = new Date(year, month, 1);
+  const lead = (first.getDay() - weekStartsOn + 7) % 7;
+  const rows = fixedWeeks ? 6 : Math.ceil((lead + daysInMonth(year, month)) / 7);
+
+  const weeks: CalendarWeek[] = [];
+  let cursor = addDays(first, -lead);
+  for (let row = 0; row < rows; row++) {
+    const days: CalendarDay[] = [];
+    for (let column = 0; column < 7; column++) {
+      const weekday = cursor.getDay();
+      days.push({
+        date: cursor,
+        day: cursor.getDate(),
+        key: toISODate(cursor),
+        outside: cursor.getMonth() !== month || cursor.getFullYear() !== year,
+        today: today !== null && compareDay(cursor, today) === 0,
+        weekend: weekday === 0 || weekday === 6,
+        disabled: isDayDisabled(cursor, options),
+      });
+      cursor = addDays(cursor, 1);
+    }
+    weeks.push({ weekNumber: getISOWeek(days[0].date), days });
+  }
+  return { year, month, weeks };
+}
+
+/** `count` consecutive months starting at the month of `start`. */
+export function buildMonths(
+  start: Date,
+  count: number,
+  options: BuildMonthOptions = {},
+): CalendarMonth[] {
+  return Array.from({ length: Math.max(1, count) }, (_, index) => {
+    const month = addMonths(startOfMonth(start), index);
+    return buildMonth(month.getFullYear(), month.getMonth(), options);
+  });
+}
+
+/** Puts a backwards range the right way round, so dragging in either direction works. */
+export function normalizeRange(range: DateRange): DateRange {
+  const { start, end } = range;
+  if (start && end && compareDay(start, end) > 0) return { start: end, end: start };
+  return range;
+}
+
+export function isInRange(date: Date, start: Date | null, end: Date | null): boolean {
+  if (!start || !end) return false;
+  return compareDay(date, start) >= 0 && compareDay(date, end) <= 0;
+}
+
+export interface MoveOptions {
+  weekStartsOn?: number;
+  /** Swaps the arrow keys, so "next day" stays to the reading-forward side. */
+  rtl?: boolean;
+  shiftKey?: boolean;
+}
+
+/** Where a key press moves the focused day, or null when the key isn't ours. */
+export function moveByKey(date: Date, key: string, options: MoveOptions = {}): Date | null {
+  const { weekStartsOn = 1, rtl = false, shiftKey = false } = options;
+  const offsetInWeek = (date.getDay() - weekStartsOn + 7) % 7;
+  switch (key) {
+    case rtl ? "ArrowRight" : "ArrowLeft":
+      return addDays(date, -1);
+    case rtl ? "ArrowLeft" : "ArrowRight":
+      return addDays(date, 1);
+    case "ArrowUp":
+      return addDays(date, -7);
+    case "ArrowDown":
+      return addDays(date, 7);
+    case "Home":
+      return addDays(date, -offsetInWeek);
+    case "End":
+      return addDays(date, 6 - offsetInWeek);
+    case "PageUp":
+      return addMonths(date, shiftKey ? -12 : -1);
+    case "PageDown":
+      return addMonths(date, shiftKey ? 12 : 1);
+    default:
+      return null;
+  }
+}
+
+/** Arrow-key movement inside the month and year panels. Returns null for other keys. */
+export function moveInGrid(
+  index: number,
+  key: string,
+  columns: number,
+  count: number,
+  rtl = false,
+): number | null {
+  const clamp = (next: number) => Math.max(0, Math.min(count - 1, next));
+  switch (key) {
+    case rtl ? "ArrowRight" : "ArrowLeft":
+      return clamp(index - 1);
+    case rtl ? "ArrowLeft" : "ArrowRight":
+      return clamp(index + 1);
+    case "ArrowUp":
+      return clamp(index - columns);
+    case "ArrowDown":
+      return clamp(index + columns);
+    case "Home":
+      return 0;
+    case "End":
+      return count - 1;
+    default:
+      return null;
+  }
+}
+
+/** The page of years holding `year`, so the year panel pages in steady blocks. */
+export function yearPage(year: number, size = 12): number[] {
+  const start = Math.floor(year / size) * size;
+  return Array.from({ length: size }, (_, index) => start + index);
+}

package/source/components/date-picker/core/format.ts

@@ -0,0 +1,170 @@
+import { parseISODate } from "./calendar";
+
+/** `Intl.DateTimeFormat` is expensive to build, and these are reused every render. */
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+function formatter(locale: string | undefined, options: Intl.DateTimeFormatOptions) {
+  const key = `${locale ?? ""}|${JSON.stringify(options)}`;
+  let found = formatters.get(key);
+  if (!found) {
+    found = new Intl.DateTimeFormat(locale, options);
+    formatters.set(key, found);
+  }
+  return found;
+}
+
+export const DEFAULT_DATE_FORMAT: Intl.DateTimeFormatOptions = {
+  year: "numeric",
+  month: "short",
+  day: "numeric",
+};
+export const DEFAULT_INPUT_PLACEHOLDER = "dd/mm/yyyy";
+
+export function formatDate(
+  date: Date,
+  locale?: string,
+  options: Intl.DateTimeFormatOptions = DEFAULT_DATE_FORMAT,
+): string {
+  return formatter(locale, options).format(date);
+}
+
+export function formatMonthYear(year: number, month: number, locale?: string): string {
+  return formatter(locale, { year: "numeric", month: "long" }).format(new Date(year, month, 1));
+}
+
+export function monthNames(locale?: string, width: "long" | "short" = "long"): string[] {
+  const format = formatter(locale, { month: width });
+  return Array.from({ length: 12 }, (_, month) => format.format(new Date(2024, month, 1)));
+}
+
+export interface WeekdayName {
+  short: string;
+  long: string;
+}
+
+/** The seven weekday names, ordered from `weekStartsOn`. */
+export function weekdayNames(locale?: string, weekStartsOn = 1): WeekdayName[] {
+  const short = formatter(locale, { weekday: "short" });
+  const long = formatter(locale, { weekday: "long" });
+  // 2024-01-07 was a Sunday, so index 0 lines up with `Date.prototype.getDay`.
+  return Array.from({ length: 7 }, (_, offset) => {
+    const date = new Date(2024, 0, 7 + ((weekStartsOn + offset) % 7));
+    return { short: short.format(date), long: long.format(date) };
+  });
+}
+
+export type DateField = "day" | "month" | "year";
+
+/** The order a locale writes a numeric date in, used for parsing and the placeholder. */
+export function fieldOrder(locale?: string): DateField[] {
+  const parts = formatter(locale, {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(2024, 10, 22));
+  const order = parts
+    .map((part) => part.type)
+    .filter((type): type is DateField => type === "day" || type === "month" || type === "year");
+  return order.length === 3 ? order : ["day", "month", "year"];
+}
+
+function separator(locale?: string): string {
+  const parts = formatter(locale, {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(2024, 10, 22));
+  const literal = parts.find((part) => part.type === "literal" && part.value.trim());
+  return literal ? literal.value.trim() : "/";
+}
+
+/** A hint in the locale's own order, e.g. `dd/mm/yyyy` or `mm/dd/yyyy`. */
+export function inputPlaceholder(locale?: string): string {
+  if (!locale) return DEFAULT_INPUT_PLACEHOLDER;
+  const hint: Record<DateField, string> = { day: "dd", month: "mm", year: "yyyy" };
+  return fieldOrder(locale)
+    .map((field) => hint[field])
+    .join(separator(locale));
+}
+
+/** Two-digit years follow the usual pivot: 00-68 is 2000s, 69-99 is 1900s. */
+function expandYear(year: number): number {
+  if (year >= 100) return year;
+  return year <= 68 ? 2000 + year : 1900 + year;
+}
+
+function build(year: number, month: number, day: number): Date | null {
+  if (month < 0 || month > 11 || day < 1 || day > 31) return null;
+  const date = new Date(year, month, day);
+  date.setHours(0, 0, 0, 0);
+  const valid =
+    date.getFullYear() === year && date.getMonth() === month && date.getDate() === day;
+  return valid ? date : null;
+}
+
+/** Matches a written month name, long or short, by either being a prefix of the other. */
+function monthFromWords(words: string, locale?: string): number | null {
+  const needle = words.toLocaleLowerCase();
+  const names = [...monthNames(locale, "long"), ...monthNames(locale, "short")];
+  const index = names.findIndex((name) => {
+    const candidate = name.toLocaleLowerCase().replace(/\.$/, "");
+    return candidate.startsWith(needle) || needle.startsWith(candidate);
+  });
+  return index === -1 ? null : index % 12;
+}
+
+/**
+ * Reads what someone typed into the field. ISO is accepted everywhere; anything
+ * else is read in the locale's field order, so `03/04/2026` is 3 April in
+ * en-GB and 4 March in en-US. Month names work too (`12 Mar 2026`).
+ * Missing parts fall back to `reference`. Returns null when it isn't a date.
+ */
+export function parseDate(
+  text: string,
+  locale?: string,
+  reference: Date = new Date(),
+): Date | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+
+  const iso = parseISODate(trimmed);
+  if (iso) return iso;
+
+  let month: number | null = null;
+  const words = trimmed.match(/\p{L}+/gu);
+  if (words) {
+    month = monthFromWords(words.join(" "), locale);
+    if (month === null) return null;
+  }
+
+  const numbers = (trimmed.match(/\d+/g) ?? []).map(Number);
+  if (numbers.length === 0) return null;
+
+  const order = fieldOrder(locale);
+
+  if (month !== null) {
+    // A month name was given, so the numbers are the day and maybe the year.
+    if (numbers.length === 1) {
+      return build(reference.getFullYear(), month, numbers[0]);
+    }
+    const yearFirst = numbers[0] >= 32;
+    const year = expandYear(yearFirst ? numbers[0] : numbers[1]);
+    const day = yearFirst ? numbers[1] : numbers[0];
+    return build(year, month, day);
+  }
+
+  if (numbers.length >= 3) {
+    const fields = numbers[0] >= 1000 ? (["year", "month", "day"] as DateField[]) : order;
+    const value = (field: DateField) => numbers[fields.indexOf(field)];
+    return build(expandYear(value("year")), value("month") - 1, value("day"));
+  }
+
+  if (numbers.length === 2) {
+    const dayFirst = order.indexOf("day") < order.indexOf("month");
+    const day = dayFirst ? numbers[0] : numbers[1];
+    const monthNumber = dayFirst ? numbers[1] : numbers[0];
+    return build(reference.getFullYear(), monthNumber - 1, day);
+  }
+
+  return build(reference.getFullYear(), reference.getMonth(), numbers[0]);
+}

package/source/components/date-picker/core/index.ts

@@ -0,0 +1,41 @@
+// Framework-free date helpers: the same calendar building, parsing and
+// formatting the components use, so a server (or a test) can reproduce them.
+export {
+  addDays,
+  addMonths,
+  buildMonth,
+  buildMonths,
+  clampDate,
+  compareDay,
+  daysInMonth,
+  endOfMonth,
+  getISOWeek,
+  isDayDisabled,
+  isInRange,
+  isSameDay,
+  isSameMonth,
+  moveByKey,
+  moveInGrid,
+  normalizeRange,
+  parseISODate,
+  resolveWeekStart,
+  startOfDay,
+  startOfMonth,
+  toDate,
+  toISODate,
+  yearPage,
+} from "./calendar";
+export type { BuildMonthOptions, MoveOptions } from "./calendar";
+export {
+  DEFAULT_DATE_FORMAT,
+  fieldOrder,
+  formatDate,
+  formatMonthYear,
+  inputPlaceholder,
+  monthNames,
+  parseDate,
+  weekdayNames,
+} from "./format";
+export type { DateField, WeekdayName } from "./format";
+export { getServerToday, getToday, subscribeToToday } from "./today";
+export type * from "./types";

package/source/components/date-picker/core/today.ts

@@ -0,0 +1,72 @@
+import { addDays, startOfDay } from "./calendar";
+
+/**
+ * The current local day, as one value every picker on the page shares.
+ *
+ * It exists as a store rather than a `new Date()` in each component for two
+ * reasons. A date read once at mount goes stale: a page left open overnight
+ * keeps marking yesterday. And a date read during a server render is a value
+ * the browser cannot reproduce — it may be on the other side of midnight, or in
+ * another time zone — so rendering it would hand hydration a mismatch.
+ *
+ * `getServerToday` answers `null`, which React also uses for the client's
+ * hydrating render. The markup therefore agrees with the server exactly, no
+ * marker either side, and the real day arrives in the re-render straight after
+ * hydration. A page with no server render never sees the null: React reads
+ * `getToday` on the first pass, so the marker is there from the first paint.
+ *
+ * One timer serves every subscriber, set for the next local midnight and
+ * computed with `addDays` so it survives a daylight-saving change. A machine
+ * that slept through midnight fires it late, and the tick then reads the clock
+ * rather than trusting the schedule.
+ */
+
+let current: Date | null = null;
+let timer: ReturnType<typeof setTimeout> | undefined;
+const listeners = new Set<() => void>();
+
+const readClock = () => startOfDay(new Date());
+
+function schedule(): void {
+  clearTimeout(timer);
+  timer = undefined;
+  if (listeners.size === 0 || current === null) return;
+  // A deadline already passed (a long sleep) collapses to zero and catches up.
+  timer = setTimeout(tick, Math.max(0, addDays(current, 1).getTime() - Date.now()));
+}
+
+function tick(): void {
+  const next = readClock();
+  if (current === null || next.getTime() !== current.getTime()) {
+    current = next;
+    for (const listener of listeners) listener();
+  }
+  schedule();
+}
+
+export function subscribeToToday(listener: () => void): () => void {
+  listeners.add(listener);
+  if (listeners.size === 1) {
+    // Nothing was watching the clock, so whatever is cached may be a day old.
+    current = readClock();
+    schedule();
+  }
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+  };
+}
+
+/** Today, as a cached value: the same object until the day actually changes. */
+export function getToday(): Date {
+  current ??= readClock();
+  return current;
+}
+
+/** Null on the server and through hydration; see the note above. */
+export function getServerToday(): null {
+  return null;
+}