@lotics/ui 4.5.0 → 4.6.0

package/AGENTS.md

@@ -340,7 +340,9 @@ surfaces' sparkles/severity glyphs, not functional affordances.
   · **Gate header**: a `Dialog` uses `DialogHeaderTitle`; a popover form uses `Text size="sm"
     weight="semibold"` + an optional `xs muted` subtitle.
 - **Time-constrained data gets a period filter** in the header band — `DateRangeFilterField`, never
-  a static period badge. Every period-dependent number MUST follow the selection.
+  a static period badge. Every period-dependent number MUST follow the selection. Pass `includeTime`
+  when the time-of-day matters: the trigger previews the chosen time (locale-aware 24h/12h) and the
+  hour/minute selects label themselves from the `labels` prop (`hour`/`minute`/`dayPeriod`).
 - **Keyboard & focus — use `tabIndex`, never `focusable`.** RN-Web's `Pressable` silently ignores
   `focusable` (it writes its own `tabIndex`), so set a pressable control's tab-stop status with
   `tabIndex={0 | -1}` (`focusable` only works on a plain `View`/`TextInput`). Roving widgets
@@ -367,8 +369,13 @@ surfaces' sparkles/severity glyphs, not functional affordances.
   can't show; if there are none, drop the strip. Card stat rails use `KPICard`.
 - **Numbers**: free-standing numerals `<Text tabular>`. Money: `formatMoney(n)` from
   `@lotics/ui/format_money` (`compact` for strip captions). Dates: `formatDate(value, opts)` from
-  `@lotics/ui/format_date` (`format:"datetime"`, `compact` → dd/MM). Never hand-roll grouping/₫ or
-  dd/MM.
+  `@lotics/ui/format_date` — the date-VALUE formatter. `format` (date STYLE) ∈ `date` (22/05/2026) ·
+  `medium` (22 thg 5, 2026) · `long` (22 tháng 5, 2026) · `dayMonth` (22 thg 5) · `monthYear`
+  (Tháng 5 2026); **`time: true` is orthogonal** — prepends the 24h time to ANY style
+  (`14:30 22/05/2026`, `14:30 22 tháng 5, 2026`); `compact` drops the year on `date`. It's `Intl` +
+  the product's conventions (stable `/`, naive-ISO parse, 24h time-first, `emptyLabel`) — never
+  hand-roll a date via `Intl`/`padStart` for value display. (Exempt: a component's own internal
+  chrome — a calendar's header/weekday/a11y labels, a gantt axis — renders its own set.)
 - **Every number is a door** (except the KPI strip). A component that summarizes records leads to
   the records behind it when pressed — switch to the filtered list, expand in place, or navigate.
   Expansion happens IMMEDIATELY below the pressed element — the composable `Accordion` family

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",

package/src/date_filter.tsx

@@ -9,6 +9,7 @@ import { Switch } from "./switch";
 import { useScreenSize } from "./use_screen_size";
 import { SegmentLabels } from "./date_segments";
 import { PresetId, PRESET_IDS, getPresetValue } from "./date_filter_presets";
+import { formatDate } from "./format_date";
 
 type SelectionMode = "single" | "range";
 
@@ -93,18 +94,9 @@ function presetLabel(id: PresetId, labels: DateFilterLabels): string {
   }
 }
 
+/** The panel's readable date label for a selected bound — the canonical `medium` style. */
 function formatDateDisplay(date: Date | null, locale: string | undefined): string {
-  if (!date) return "";
-  const isoDate = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
-  try {
-    return new Intl.DateTimeFormat(locale, {
-      month: "short",
-      day: "numeric",
-      year: "numeric",
-    }).format(date);
-  } catch {
-    return isoDate;
-  }
+  return formatDate(date, { format: "medium", locale });
 }
 
 // =============================================================================

package/src/date_range_filter_field.tsx

@@ -7,6 +7,7 @@ import { Button } from "./button";
 import { PressableHighlight } from "./pressable_highlight";
 import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
 import { DateFilter, DateFilterValue, DateFilterLabels } from "./date_filter";
+import { formatDate } from "./format_date";
 
 // =============================================================================
 // DateRangeFilterField — the common filter composition over DateFilter:
@@ -33,7 +34,8 @@ export interface DateRangeFilterFieldProps {
   includeTime?: boolean;
   /** Translated labels (presets + footer + placeholder). Defaults to English. */
   labels?: Partial<DateRangeFilterFieldLabels>;
-  /** BCP-47 locale for the calendar + trigger date display. Defaults to "en-US". */
+  /** BCP-47 locale for the calendar + trigger date display. Date display defaults to
+   *  the kit's home market (vi-VN, via `formatDate`) when unset. */
   locale?: string;
   testID?: string;
 }
@@ -43,17 +45,18 @@ const EMPTY_VALUE: DateFilterValue = {
   end: { date: null, time: null },
 };
 
-function formatDate(date: Date | null, locale: string | undefined): string {
+/**
+ * A bound's date + its separate "HH:mm" time → one localized string via the kit's
+ * canonical `formatDate` (time-first "HH:mm dd/MM/yyyy"). Date-only when there is no
+ * time; "" when there is no date.
+ */
+function formatBound(date: Date | null, time: string | null, locale: string | undefined): string {
   if (!date) return "";
-  try {
-    return new Intl.DateTimeFormat(locale, {
-      day: "2-digit",
-      month: "2-digit",
-      year: "numeric",
-    }).format(date);
-  } catch {
-    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
-  }
+  const m = time ? /^(\d{1,2}):(\d{2})/.exec(time) : null;
+  if (!m) return formatDate(date, { locale });
+  const dt = new Date(date);
+  dt.setHours(Number(m[1]), Number(m[2]), 0, 0);
+  return formatDate(dt, { time: true, locale });
 }
 
 /**
@@ -64,21 +67,14 @@ function formatDate(date: Date | null, locale: string | undefined): string {
  * period rhythm, not date pairs.
  */
 function formatRangeDisplay(start: Date, end: Date, locale: string | undefined): string {
-  if (start.toDateString() === end.toDateString()) return formatDate(start, locale);
+  if (start.toDateString() === end.toDateString()) return formatDate(start, { locale });
 
   const wholeMonth =
     start.getDate() === 1 &&
     start.getMonth() === end.getMonth() &&
     start.getFullYear() === end.getFullYear() &&
     end.getDate() === new Date(end.getFullYear(), end.getMonth() + 1, 0).getDate();
-  if (wholeMonth) {
-    try {
-      const label = new Intl.DateTimeFormat(locale, { month: "long", year: "numeric" }).format(start);
-      return label.charAt(0).toUpperCase() + label.slice(1);
-    } catch {
-      return `${start.getMonth() + 1}/${start.getFullYear()}`;
-    }
-  }
+  if (wholeMonth) return formatDate(start, { format: "monthYear", locale });
 
   const wholeYear =
     start.getFullYear() === end.getFullYear() &&
@@ -88,7 +84,27 @@ function formatRangeDisplay(start: Date, end: Date, locale: string | undefined):
     end.getDate() === 31;
   if (wholeYear) return String(start.getFullYear());
 
-  return `${formatDate(start, locale)} – ${formatDate(end, locale)}`;
+  return `${formatDate(start, { locale })} – ${formatDate(end, { locale })}`;
+}
+
+/**
+ * The trigger text. An untimed range folds to a compact period (month / year /
+ * day) via `formatRangeDisplay`. Once a time is set (and `includeTime`) a timed
+ * window isn't a clean period, so it shows "time date – time date". "" when there
+ * is no value (caller shows the placeholder).
+ */
+function formatTrigger(value: DateFilterValue, includeTime: boolean, locale: string | undefined): string {
+  const { start, end } = value;
+  const sTime = includeTime ? start.time : null;
+  const eTime = includeTime ? end.time : null;
+
+  if (start.date && end.date && !sTime && !eTime) {
+    return formatRangeDisplay(start.date, end.date, locale);
+  }
+  if (start.date || end.date) {
+    return `${formatBound(start.date, sTime, locale)} – ${formatBound(end.date, eTime, locale)}`;
+  }
+  return "";
 }
 
 export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
@@ -97,12 +113,7 @@ export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
   const [open, setOpen] = useState(false);
 
   const hasValue = Boolean(value.start.date || value.end.date);
-  const display =
-    value.start.date && value.end.date
-      ? formatRangeDisplay(value.start.date, value.end.date, locale)
-      : hasValue
-        ? `${formatDate(value.start.date, locale)} – ${formatDate(value.end.date, locale)}`
-        : labels.placeholder;
+  const display = formatTrigger(value, Boolean(includeTime), locale) || labels.placeholder;
 
   return (
     <Popover open={open} onOpenChange={setOpen} side="bottom" align="start">

package/src/format_date.test.ts

@@ -14,12 +14,40 @@ describe("formatDate", () => {
     expect(formatDate("2026-05-22", { locale: "vi-VN", compact: true })).toBe("22/05");
   });
 
-  test("datetime includes 24h time", () => {
-    expect(formatDate("2026-05-22T14:30", { locale: "vi-VN", format: "datetime" })).toBe("22/05/2026 14:30");
+  test("time prepends the 24h time, then the locale date", () => {
+    expect(formatDate("2026-05-22T14:30", { locale: "vi-VN", time: true })).toBe("14:30 22/05/2026");
   });
 
-  test("compact datetime drops the year, keeps the time", () => {
-    expect(formatDate("2026-05-22T09:05", { locale: "vi-VN", format: "datetime", compact: true })).toBe("22/05 09:05");
+  test("time + compact is time-first and drops the year", () => {
+    expect(formatDate("2026-05-22T09:05", { locale: "vi-VN", time: true, compact: true })).toBe("09:05 22/05");
+  });
+
+  test("time composes with a readable style — the orthogonal axis", () => {
+    expect(formatDate("2026-09-22T14:30", { format: "long", time: true, locale: "en-US" })).toBe("14:30 September 22, 2026");
+  });
+
+  test("medium — readable, abbreviated month", () => {
+    expect(formatDate("2026-05-22", { format: "medium", locale: "en-US" })).toBe("May 22, 2026");
+    // vi word output is ICU-dependent; assert the day + year are present (day-first locale).
+    expect(formatDate("2026-05-22", { format: "medium", locale: "vi-VN" })).toMatch(/22.*2026/);
+  });
+
+  test("long — readable, full month name", () => {
+    expect(formatDate("2026-09-22", { format: "long", locale: "en-US" })).toBe("September 22, 2026");
+    expect(formatDate("2026-09-22", { format: "long", locale: "vi-VN" })).toMatch(/22.*2026/);
+  });
+
+  test("dayMonth — day + abbreviated month, no year", () => {
+    expect(formatDate("2026-09-22", { format: "dayMonth", locale: "en-US" })).toBe("Sep 22");
+    expect(formatDate("2026-09-22", { format: "dayMonth", locale: "vi-VN" })).not.toMatch(/2026/);
+  });
+
+  test("monthYear — a period label, sentence-cased", () => {
+    expect(formatDate("2026-05-22", { format: "monthYear", locale: "en-US" })).toBe("May 2026");
+    // Leading character is upper-cased even where the locale lowercases the month name.
+    const vi = formatDate("2026-05-22", { format: "monthYear", locale: "vi-VN" });
+    expect(vi.charAt(0)).toBe(vi.charAt(0).toUpperCase());
+    expect(vi).toMatch(/2026/);
   });
 
   test("date-only ISO does not drift across local timezone (wall-clock parse)", () => {

package/src/format_date.ts

@@ -1,16 +1,36 @@
-export type DateFormatStyle = "date" | "datetime";
+/**
+ * The date STYLE — orthogonal to time (pass `time: true` to prepend a 24h time to any of these).
+ * `date` reassembles dd/MM with a stable "/"; the readable styles use word months in locale order.
+ * NOT for a component's own internal chrome — a calendar's header / weekday / a11y labels, a gantt
+ * axis — which render their own internally-consistent label set with `Intl` directly.
+ */
+export type DateFormatStyle =
+  | "date" // 22/05/2026 — numeric
+  | "medium" // 22 thg 5, 2026 / Sep 22, 2026 — readable, abbreviated month
+  | "long" // 22 tháng 5, 2026 / September 22, 2026 — readable, full month
+  | "dayMonth" // 22 thg 5 / Sep 22 — day + abbreviated month, no year
+  | "monthYear"; // Tháng 5 2026 / May 2026 — a period label (sentence-cased)
 
 export interface FormatDateOptions {
-  /** "date" → 22/05/2026 · "datetime" → 22/05/2026 14:30. Default "date". */
+  /** The date style. Default "date". */
   format?: DateFormatStyle;
+  /** Prepend the 24h time — "14:30 <date>". Composes with ANY `format`. Default false. */
+  time?: boolean;
   /** BCP-47 locale. Defaults to the product's home market, "vi-VN". */
   locale?: string;
-  /** Drop the year — "22/05" instead of "22/05/2026" — for dense rows / timelines. */
+  /** Drop the year ("22/05") on the numeric `date` style. */
   compact?: boolean;
   /** Rendered for null / empty / unparseable input. Default "". */
   emptyLabel?: string;
 }
 
+const READABLE_OPTS: Record<"medium" | "long" | "dayMonth" | "monthYear", Intl.DateTimeFormatOptions> = {
+  medium: { day: "numeric", month: "short", year: "numeric" },
+  long: { day: "numeric", month: "long", year: "numeric" },
+  dayMonth: { day: "numeric", month: "short" },
+  monthYear: { month: "long", year: "numeric" },
+};
+
 const ISO_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
 
 const pad2 = (n: number) => String(n).padStart(2, "0");
@@ -43,29 +63,47 @@ export function toISODate(value: Date | string | null | undefined): string {
 }
 
 /**
- * THE date formatter — the date sibling of `formatMoney`. Accepts a `Date` OR an ISO string and
- * returns a localized display string; defaults to the home market: `22/05/2026` (date) /
- * `22/05/2026 14:30` (datetime). `compact` drops the year for dense rows (`22/05`). Never
- * hand-roll dd/MM with `padStart` / `getMonth` — call this.
+ * THE date-value formatter — the date sibling of `formatMoney`. Accepts a `Date` OR an ISO string
+ * and returns a localized display string; defaults to the home market. `format` picks the date
+ * style: `date` → `22/05/2026` · `medium` → `22 thg 5, 2026` · `long` → `22 tháng 5, 2026` ·
+ * `dayMonth` → `22 thg 5` · `monthYear` → `Tháng 5 2026`. **`time: true` prepends the 24h time to
+ * ANY style** — `14:30 22/05/2026`, `14:30 22 tháng 5, 2026` (time-first). `compact` drops the
+ * year on the numeric `date` style. Never hand-roll a date with `padStart` / `getMonth` / a raw
+ * `Intl.DateTimeFormat` for VALUE display — call this. (Component-internal chrome is exempt — see
+ * {@link DateFormatStyle}.)
  */
 export function formatDate(value: Date | string | null | undefined, options: FormatDateOptions = {}): string {
-  const { format = "date", locale = "vi-VN", compact = false, emptyLabel = "" } = options;
+  const { format = "date", time = false, locale = "vi-VN", compact = false, emptyLabel = "" } = options;
   const date = parseDate(value);
   if (!date) return emptyLabel;
-  // Use Intl only for the locale-aware part ORDER (dd/MM for vi-VN, MM/dd for en-US), then
-  // reassemble with a consistent "/" — Intl's own separator is inconsistent across CLDR (vi-VN
-  // uses "/" with a year but "-" without). The time is appended as a stable 24h " HH:mm" (no
-  // locale comma, no AM/PM), matching the compact data convention.
-  let parts: Intl.DateTimeFormatPart[];
-  try {
-    parts = new Intl.DateTimeFormat(locale, { day: "2-digit", month: "2-digit", year: "numeric" }).formatToParts(date);
-  } catch {
-    return emptyLabel;
+
+  let dateStr: string;
+  if (format === "date") {
+    // Numeric: Intl only for the locale-aware part ORDER (dd/MM for vi-VN, MM/dd for en-US), then
+    // reassemble with a consistent "/" — Intl's own separator is inconsistent across CLDR (vi-VN
+    // uses "/" with a year but "-" without). `compact` drops the year.
+    let parts: Intl.DateTimeFormatPart[];
+    try {
+      parts = new Intl.DateTimeFormat(locale, { day: "2-digit", month: "2-digit", year: "numeric" }).formatToParts(date);
+    } catch {
+      return emptyLabel;
+    }
+    dateStr = parts
+      .filter((p) => p.type === "day" || p.type === "month" || (!compact && p.type === "year"))
+      .map((p) => p.value)
+      .join("/");
+  } else {
+    // Readable styles: word months in locale order — Intl's output is correct here (the separator
+    // inconsistency that forces the numeric reassembly is specific to the all-numeric form).
+    try {
+      dateStr = new Intl.DateTimeFormat(locale, READABLE_OPTS[format]).format(date);
+    } catch {
+      return emptyLabel;
+    }
+    // A period label leads a line → sentence-case (a no-op where the locale already capitalizes).
+    if (format === "monthYear") dateStr = dateStr.charAt(0).toUpperCase() + dateStr.slice(1);
   }
-  let out = parts
-    .filter((p) => p.type === "day" || p.type === "month" || (!compact && p.type === "year"))
-    .map((p) => p.value)
-    .join("/");
-  if (format === "datetime") out += ` ${pad2(date.getHours())}:${pad2(date.getMinutes())}`;
-  return out;
+
+  // Time-first: a stable 24h "HH:mm " prepended (no locale comma, no AM/PM), per the product convention.
+  return time ? `${pad2(date.getHours())}:${pad2(date.getMinutes())} ${dateStr}` : dateStr;
 }

package/src/inline_date_picker.tsx

@@ -67,7 +67,9 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
     [value, commit],
   );
 
-  const display = formatDate(value, { format, locale, emptyLabel: "" });
+  // `format` here is the field config (date vs datetime); the display formatter only needs
+  // whether to show a time → map it to the orthogonal `time` flag.
+  const display = formatDate(value, { time: format === "datetime", locale, emptyLabel: "" });
 
   return (
     <View>

package/src/time_field.tsx

@@ -10,7 +10,6 @@ import {
   fieldOrder,
   from12h,
   getTimeLayout,
-  placeholderFor,
   to12h,
 } from "./date_segments";
 
@@ -119,13 +118,13 @@ export function TimeField(props: TimeFieldProps) {
     "hour" | "minute" | "dayPeriod",
     { options: Option[]; onSelect: (v: string) => void; label: string; width: number }
   > = {
-    hour: { options: hourOptions, onSelect: setHour, label: segmentLabels.hour, width: 58 },
-    minute: { options: minuteOptions, onSelect: setMinute, label: segmentLabels.minute, width: 58 },
+    hour: { options: hourOptions, onSelect: setHour, label: segmentLabels.hour, width: 78 },
+    minute: { options: minuteOptions, onSelect: setMinute, label: segmentLabels.minute, width: 78 },
     dayPeriod: {
       options: periodOptions,
       onSelect: setPeriod,
       label: segmentLabels.dayPeriod,
-      width: 66,
+      width: 78,
     },
   };
 
@@ -142,7 +141,7 @@ export function TimeField(props: TimeFieldProps) {
             options={c.options}
             onSelect={c.onSelect}
             accessibilityLabel={c.label}
-            placeholder={placeholderFor(type)}
+            placeholder={c.label}
             disabled={disabled}
             width={c.width}
           />