@lotics/ui 1.11.1 → 1.13.0

package/src/date_segments.ts

@@ -0,0 +1,347 @@
+// =============================================================================
+// Date segment logic
+//
+// Locale-derived segment layout + per-segment editing for the segmented date
+// field. The displayed order (d/m/y vs m/d/y vs y/m/d), separators, and 12h-vs-
+// 24h time are all derived from the locale via Intl.DateTimeFormat — nothing is
+// hardcoded. Canonical values stay ISO and flow through date_picker_value.ts.
+//
+// Pure logic, kept separate from the React component so it can be unit-tested.
+// =============================================================================
+
+import { DateParts, pad, parsePart, parseText, partsToIso } from "./date_picker_value";
+
+export type SegmentType = "year" | "month" | "day" | "hour" | "minute" | "dayPeriod";
+
+/** Accessible names per segment. Keys match {@link SegmentType} so `labels[type]` resolves. */
+export interface SegmentLabels {
+  year: string;
+  month: string;
+  day: string;
+  hour: string;
+  minute: string;
+  dayPeriod: string;
+}
+
+export type LayoutSegment =
+  | { kind: "field"; type: SegmentType }
+  | { kind: "literal"; value: string };
+
+export interface DateLayout {
+  /** Field + literal segments in locale display order. */
+  segments: LayoutSegment[];
+  /** Whether time is shown in 12-hour form (with an AM/PM segment). */
+  hour12: boolean;
+  /** Localized AM/PM strings (only meaningful when hour12). */
+  amText: string;
+  pmText: string;
+}
+
+/** Committed segment values. `hour` is canonical 0–23 regardless of display. */
+export interface SegmentBuffer {
+  year: number | null;
+  month: number | null;
+  day: number | null;
+  hour: number | null;
+  minute: number | null;
+}
+
+export function emptyBuffer(): SegmentBuffer {
+  return { year: null, month: null, day: null, hour: null, minute: null };
+}
+
+// -----------------------------------------------------------------------------
+// Layout derivation
+// -----------------------------------------------------------------------------
+
+// Distinct sample components (2023 / 01 / 02 / 13:45) so part mapping is reliable.
+const SAMPLE = new Date(2023, 0, 2, 13, 45, 0);
+
+const FIELD_TYPE: Record<string, SegmentType | undefined> = {
+  year: "year",
+  month: "month",
+  day: "day",
+  hour: "hour",
+  minute: "minute",
+  dayPeriod: "dayPeriod",
+};
+
+// Intl formatters are costly to construct; derive each layout once.
+const layoutCache = new Map<string, DateLayout>();
+
+function dayPeriodText(locale: string, hour: number): string {
+  const part = new Intl.DateTimeFormat(locale, { hour: "2-digit", minute: "2-digit" })
+    .formatToParts(new Date(2023, 0, 2, hour, 0))
+    .find((p) => p.type === "dayPeriod");
+  return part?.value ?? (hour < 12 ? "AM" : "PM");
+}
+
+function partsToSegments(parts: Intl.DateTimeFormatPart[], hour12: boolean): LayoutSegment[] {
+  const segments: LayoutSegment[] = [];
+  for (const part of parts) {
+    const type = FIELD_TYPE[part.type];
+    if (type) {
+      if (type === "dayPeriod" && !hour12) continue;
+      segments.push({ kind: "field", type });
+    } else {
+      segments.push({ kind: "literal", value: part.value });
+    }
+  }
+  return segments;
+}
+
+export function getDateLayout(locale: string, hasTime: boolean): DateLayout {
+  const key = `${locale}|${hasTime}`;
+  const cached = layoutCache.get(key);
+  if (cached) return cached;
+
+  // Follow the locale's own field order and separators verbatim — including whether
+  // time leads (vi-VN: "HH:mm dd/MM/yyyy") or the date does (en-US: "MM/DD/YYYY,
+  // HH:mm AM/PM"), and 12h-vs-24h. Nothing is hardcoded.
+  const dtf = new Intl.DateTimeFormat(locale, {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    ...(hasTime ? { hour: "2-digit", minute: "2-digit" } : {}),
+  });
+  const hour12 = hasTime ? (dtf.resolvedOptions().hour12 ?? false) : false;
+  const segments = partsToSegments(dtf.formatToParts(SAMPLE), hour12);
+
+  const layout: DateLayout = {
+    segments,
+    hour12,
+    amText: hour12 ? dayPeriodText(locale, 9) : "AM",
+    pmText: hour12 ? dayPeriodText(locale, 21) : "PM",
+  };
+  layoutCache.set(key, layout);
+  return layout;
+}
+
+/** Time-only layout (hour / minute / dayPeriod), for a standalone time field. */
+export function getTimeLayout(locale: string): DateLayout {
+  const key = `time|${locale}`;
+  const cached = layoutCache.get(key);
+  if (cached) return cached;
+
+  const dtf = new Intl.DateTimeFormat(locale, { hour: "2-digit", minute: "2-digit" });
+  const hour12 = dtf.resolvedOptions().hour12 ?? false;
+  const layout: DateLayout = {
+    segments: partsToSegments(dtf.formatToParts(SAMPLE), hour12),
+    hour12,
+    amText: hour12 ? dayPeriodText(locale, 9) : "AM",
+    pmText: hour12 ? dayPeriodText(locale, 21) : "PM",
+  };
+  layoutCache.set(key, layout);
+  return layout;
+}
+
+/** Editable field segments in display order (literals dropped). */
+export function fieldOrder(layout: DateLayout): SegmentType[] {
+  const order: SegmentType[] = [];
+  for (const seg of layout.segments) if (seg.kind === "field") order.push(seg.type);
+  return order;
+}
+
+// -----------------------------------------------------------------------------
+// 12-hour conversions
+// -----------------------------------------------------------------------------
+
+export function to12h(hour24: number): { h12: number; pm: boolean } {
+  const pm = hour24 >= 12;
+  const mod = hour24 % 12;
+  return { h12: mod === 0 ? 12 : mod, pm };
+}
+
+export function from12h(h12: number, pm: boolean): number {
+  const base = h12 % 12;
+  return pm ? base + 12 : base;
+}
+
+// -----------------------------------------------------------------------------
+// Per-segment editing
+// -----------------------------------------------------------------------------
+
+function bounds(type: SegmentType, hour12: boolean): { min: number; max: number } {
+  switch (type) {
+    case "year":
+      return { min: 1, max: 9999 };
+    case "month":
+      return { min: 1, max: 12 };
+    case "day":
+      return { min: 1, max: 31 };
+    case "hour":
+      return hour12 ? { min: 1, max: 12 } : { min: 0, max: 23 };
+    case "minute":
+      return { min: 0, max: 59 };
+    case "dayPeriod":
+      return { min: 0, max: 1 };
+  }
+}
+
+export function placeholderFor(type: SegmentType): string {
+  switch (type) {
+    case "year":
+      return "yyyy";
+    case "month":
+      return "mm";
+    case "day":
+      return "dd";
+    case "hour":
+      return "hh";
+    case "minute":
+      return "mm";
+    case "dayPeriod":
+      return "--";
+  }
+}
+
+export interface DigitResult {
+  /** In-progress text for the segment. */
+  text: string;
+  /** Parsed numeric value (display domain — for `hour` in 12h mode this is 1–12). */
+  value: number;
+  /** When true the segment is full and focus should advance to the next field. */
+  complete: boolean;
+}
+
+/** Apply a typed digit to a numeric segment's in-progress text. */
+export function typeDigit(
+  type: SegmentType,
+  currentText: string,
+  digit: string,
+  hour12: boolean,
+): DigitResult {
+  const { max } = bounds(type, hour12);
+
+  if (type === "year") {
+    const text = (currentText + digit).slice(-4);
+    return { text, value: Number(text), complete: text.length >= 4 };
+  }
+
+  let text = currentText + digit;
+  let value = Number(text);
+  if (value > max) {
+    // The accumulated value overflows — restart from the freshly typed digit.
+    text = digit;
+    value = Number(digit);
+  }
+  // Advance once two digits are in, or when no second digit could keep it in range.
+  const complete = text.length >= 2 || value * 10 > max;
+  return { text, value, complete };
+}
+
+/** Step a numeric segment up/down, wrapping within its range. */
+export function incrementSegment(
+  type: SegmentType,
+  current: number | null,
+  delta: number,
+  hour12: boolean,
+): number {
+  if (type === "year") {
+    if (current == null) return new Date().getFullYear();
+    return Math.min(9999, Math.max(1, current + delta));
+  }
+  const { min, max } = bounds(type, hour12);
+  if (current == null) return delta > 0 ? min : max;
+  const range = max - min + 1;
+  return (((current - min + delta) % range) + range) % range + min;
+}
+
+/** Convert a typed `hour` segment value (display domain) to a canonical 0–23 hour. */
+export function setHourField(buffer: SegmentBuffer, typed: number, hour12: boolean): number {
+  if (!hour12) return typed;
+  const pm = buffer.hour == null ? false : to12h(buffer.hour).pm;
+  return from12h(typed, pm);
+}
+
+/** Set the AM/PM half-day, preserving the displayed 12-hour value. */
+export function withDayPeriod(buffer: SegmentBuffer, pm: boolean): number {
+  const h12 = buffer.hour == null ? 12 : to12h(buffer.hour).h12;
+  return from12h(h12, pm);
+}
+
+// -----------------------------------------------------------------------------
+// Display + value mapping
+// -----------------------------------------------------------------------------
+
+/** Zero-padded display text for a committed segment, or null when unset. */
+export function displayValue(
+  type: SegmentType,
+  buffer: SegmentBuffer,
+  layout: DateLayout,
+): string | null {
+  switch (type) {
+    case "year":
+      return buffer.year == null ? null : String(buffer.year).padStart(4, "0");
+    case "month":
+      return buffer.month == null ? null : pad(buffer.month);
+    case "day":
+      return buffer.day == null ? null : pad(buffer.day);
+    case "minute":
+      return buffer.minute == null ? null : pad(buffer.minute);
+    case "hour":
+      if (buffer.hour == null) return null;
+      return layout.hour12 ? pad(to12h(buffer.hour).h12) : pad(buffer.hour);
+    case "dayPeriod":
+      if (buffer.hour == null) return null;
+      return to12h(buffer.hour).pm ? layout.pmText : layout.amText;
+  }
+}
+
+export function valueToSegments(iso: string, hasTime: boolean): SegmentBuffer {
+  const p = parsePart(iso);
+  if (!p) return emptyBuffer();
+  return {
+    year: p.y,
+    month: p.mo,
+    day: p.d,
+    hour: hasTime ? p.h : null,
+    minute: hasTime ? p.mi : null,
+  };
+}
+
+export function isBufferEmpty(buffer: SegmentBuffer, hasTime: boolean): boolean {
+  const dateEmpty = buffer.year == null && buffer.month == null && buffer.day == null;
+  if (!hasTime) return dateEmpty;
+  return dateEmpty && buffer.hour == null && buffer.minute == null;
+}
+
+/** Compose a canonical ISO value, or null when the buffer is incomplete/invalid. */
+export function segmentsToValue(buffer: SegmentBuffer, hasTime: boolean): string | null {
+  if (buffer.year == null || buffer.month == null || buffer.day == null) return null;
+  if (hasTime && (buffer.hour == null || buffer.minute == null)) return null;
+  const parts: DateParts = {
+    y: buffer.year,
+    mo: buffer.month,
+    d: buffer.day,
+    h: hasTime ? (buffer.hour as number) : 0,
+    mi: hasTime ? (buffer.minute as number) : 0,
+  };
+  const iso = partsToIso(parts, hasTime);
+  // Reject impossible dates (Feb 30) and sub-1000 years that can't round-trip.
+  return parsePart(iso) ? iso : null;
+}
+
+// -----------------------------------------------------------------------------
+// Field configuration — the layout + value↔buffer mapping the segment engine
+// uses to drive a date / datetime field.
+// -----------------------------------------------------------------------------
+
+export interface SegmentsConfig {
+  layout: DateLayout;
+  toBuffer: (value: string) => SegmentBuffer;
+  toValue: (buffer: SegmentBuffer) => string | null;
+  isEmpty: (buffer: SegmentBuffer) => boolean;
+  /** Parse loosely-typed/pasted text to a canonical value, or null. */
+  parse: (text: string) => string | null;
+}
+
+export function dateSegmentsConfig(locale: string, hasTime: boolean): SegmentsConfig {
+  return {
+    layout: getDateLayout(locale, hasTime),
+    toBuffer: (value) => valueToSegments(value, hasTime),
+    toValue: (buffer) => segmentsToValue(buffer, hasTime),
+    isEmpty: (buffer) => isBufferEmpty(buffer, hasTime),
+    parse: (text) => parseText(text, hasTime),
+  };
+}