@lotics/ui 13.8.0 → 13.9.0

package/docs/composition.md

@@ -213,6 +213,15 @@ a dashboard. Card stat rails use `KPICard`.
   re-implementation. (Exempt: a component's own internal chrome — a calendar's header/weekday/a11y
   labels, a gantt axis — renders its own set.)
 
+  **Reduced-precision date values.** A `date` field may store an ISO 8601 truncated value —
+  `"2026-05"` (month) or `"2026"` (year) — for a document that carries only that precision.
+  `formatDate` renders only the parts present: a month value → `05/2026` (`date` style) /
+  `thg 5, 2026` (`medium`), a year value → `2026`; no day is fabricated and `time` is ignored
+  (a calendar period has no clock). **`toISODate(value)`** (`Date`/ISO → the picker/workflow date
+  string) PRESERVES those partials verbatim — it returns `"2026-05"` / `"2026"` unchanged, so a
+  form round-trip never expands them to a fabricated `"2026-05-01"`. Comparisons and sorting treat
+  a partial as its period start (`"2026" < "2026-05" < "2026-05-01"`).
+
 ## Every number is a door
 
 Except the KPI strip: a component that summarizes records leads to the records behind it when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "13.8.0",
+  "version": "13.9.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/format_date.test.ts

@@ -63,6 +63,34 @@ describe("formatDate", () => {
   });
 });
 
+describe("formatDate — reduced precision", () => {
+  test("month value renders MM/YYYY (numeric, locale order), no fabricated day", () => {
+    expect(formatDate("2026-05", { locale: "vi-VN" })).toBe("05/2026");
+    expect(formatDate("2026-05", { locale: "en-US" })).toBe("05/2026");
+  });
+
+  test("year value renders just the year", () => {
+    expect(formatDate("2026", { locale: "vi-VN" })).toBe("2026");
+    expect(formatDate("2026", { format: "medium", locale: "en-US" })).toBe("2026");
+    expect(formatDate("2026", { format: "monthYear", locale: "en-US" })).toBe("2026");
+  });
+
+  test("compact drops the year on a month value", () => {
+    expect(formatDate("2026-05", { locale: "vi-VN", compact: true })).toBe("05");
+  });
+
+  test("readable styles drop the day for a month value", () => {
+    expect(formatDate("2026-05", { format: "monthYear", locale: "en-US" })).toBe("May 2026");
+    expect(formatDate("2026-05", { format: "medium", locale: "en-US" })).toBe("May 2026");
+    expect(formatDate("2026-05", { format: "long", locale: "en-US" })).toBe("May 2026");
+    expect(formatDate("2026-05", { format: "dayMonth", locale: "en-US" })).toBe("May");
+  });
+
+  test("time is ignored for a reduced-precision value (a period has no clock)", () => {
+    expect(formatDate("2026-05", { locale: "vi-VN", time: true })).toBe("05/2026");
+  });
+});
+
 describe("parseDate", () => {
   test("parses an ISO datetime to local wall-clock", () => {
     const d = parseDate("2026-05-22T14:30");
@@ -81,6 +109,17 @@ describe("parseDate", () => {
     expect(parseDate(null)).toBeNull();
     expect(parseDate("")).toBeNull();
   });
+
+  test("parses a reduced-precision value to its period start", () => {
+    const month = parseDate("2026-05");
+    expect(month?.getFullYear()).toBe(2026);
+    expect(month?.getMonth()).toBe(4);
+    expect(month?.getDate()).toBe(1);
+    const year = parseDate("2026");
+    expect(year?.getFullYear()).toBe(2026);
+    expect(year?.getMonth()).toBe(0);
+    expect(year?.getDate()).toBe(1);
+  });
 });
 
 describe("toISODate", () => {
@@ -89,4 +128,11 @@ describe("toISODate", () => {
     expect(toISODate("2026-05-22T14:30")).toBe("2026-05-22");
     expect(toISODate(null)).toBe("");
   });
+
+  test("PRESERVES reduced precision verbatim — never fabricates a day", () => {
+    expect(toISODate("2026-05")).toBe("2026-05");
+    expect(toISODate("2026")).toBe("2026");
+    // Whitespace-trimmed but otherwise unchanged.
+    expect(toISODate("  2026-05  ")).toBe("2026-05");
+  });
 });

package/src/format_date.ts

@@ -24,6 +24,9 @@ export interface FormatDateOptions {
   emptyLabel?: string;
 }
 
+/** The precision a value carries — a `date` field may store a reduced ISO form. */
+type DatePrecision = "year" | "month" | "day";
+
 const READABLE_OPTS: Record<"medium" | "long" | "dayMonth" | "monthYear", Intl.DateTimeFormatOptions> = {
   medium: { day: "numeric", month: "short", year: "numeric" },
   long: { day: "numeric", month: "long", year: "numeric" },
@@ -31,32 +34,67 @@ const READABLE_OPTS: Record<"medium" | "long" | "dayMonth" | "monthYear", Intl.D
   monthYear: { month: "long", year: "numeric" },
 };
 
+const ISO_YEAR = /^(\d{4})$/;
+const ISO_YEAR_MONTH = /^(\d{4})-(\d{2})$/;
 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");
 
 /**
- * Parse a Date or a canonical timezone-naive ISO value as local wall-clock.
- * `new Date("2024-03-15")` parses date-only strings as **UTC** midnight, which then
- * shifts under local formatting — a phantom time and an off-by-one date in negative-offset
- * zones. Building the Date from its parts keeps it naive, matching how a date picker reads the
- * same value. A `Date` passes through; non-ISO strings fall back to the native parser. Returns
- * `null` for null / empty / unparseable input.
+ * Parse a Date or a canonical timezone-naive ISO value as local wall-clock, carrying the
+ * PRECISION it was written at. `new Date("2024-03-15")` parses date-only strings as **UTC**
+ * midnight, which then shifts under local formatting — a phantom time and an off-by-one date in
+ * negative-offset zones. Building the Date from its parts keeps it naive, matching how a date
+ * picker reads the same value. A reduced-precision value ("2024-03" / "2024") anchors at its
+ * period start (day/month → 1) but is tagged so the formatter never fabricates the missing parts.
+ * A `Date` passes through at day precision; non-ISO strings fall back to the native parser.
+ * Returns `null` for null / empty / unparseable input.
  */
-export function parseDate(value: Date | string | null | undefined): Date | null {
+function parseNaive(value: Date | string | null | undefined): { date: Date; precision: DatePrecision } | null {
   if (value == null) return null;
-  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : { date: value, precision: "day" };
   const s = value.trim();
   if (!s) return null;
+
+  const y = ISO_YEAR.exec(s);
+  if (y) {
+    const d = new Date(Number(y[1]), 0, 1);
+    return Number.isNaN(d.getTime()) ? null : { date: d, precision: "year" };
+  }
+  const ym = ISO_YEAR_MONTH.exec(s);
+  if (ym) {
+    const d = new Date(Number(ym[1]), Number(ym[2]) - 1, 1);
+    return Number.isNaN(d.getTime()) ? null : { date: d, precision: "month" };
+  }
   const m = ISO_DATE_TIME.exec(s);
   const d = m
     ? new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4] ?? 0), Number(m[5] ?? 0), Number(m[6] ?? 0))
     : new Date(s);
-  return Number.isNaN(d.getTime()) ? null : d;
+  return Number.isNaN(d.getTime()) ? null : { date: d, precision: "day" };
+}
+
+/**
+ * A Date or ISO value → a local wall-clock `Date` (period start for a reduced-precision value).
+ * "" / null / unparseable → `null`. Use {@link formatDate} for display; this is for callers that
+ * need the `Date` itself (a picker anchor, an axis position).
+ */
+export function parseDate(value: Date | string | null | undefined): Date | null {
+  return parseNaive(value)?.date ?? null;
 }
 
-/** A Date or ISO value → "yyyy-MM-dd" (the `DatePicker` / workflow date value). "" when empty. */
+/**
+ * A Date or ISO value → the `DatePicker` / workflow date value. "" when empty.
+ *
+ * **Reduced precision is PRESERVED, not expanded.** A `date` field may carry "YYYY-MM" or "YYYY";
+ * those are returned verbatim so a round-trip through a form never fabricates a day (writing back
+ * "2026-05-01" for a value the user entered as "2026-05" would corrupt it). A full value (Date,
+ * `yyyy-MM-dd`, or a datetime) reassembles as "yyyy-MM-dd".
+ */
 export function toISODate(value: Date | string | null | undefined): string {
+  if (typeof value === "string") {
+    const s = value.trim();
+    if (ISO_YEAR.test(s) || ISO_YEAR_MONTH.test(s)) return s;
+  }
   const d = parseDate(value);
   if (!d) return "";
   return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
@@ -71,11 +109,24 @@ export function toISODate(value: Date | string | null | undefined): string {
  * 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}.)
+ *
+ * **Reduced-precision values render only the parts they carry** — a month-year value shows
+ * `05/2026` (numeric) / `thg 5, 2026` (readable), a bare year shows `2026`; no day is fabricated
+ * and `time` is ignored (a calendar period has no clock).
  */
 export function formatDate(value: Date | string | null | undefined, options: FormatDateOptions = {}): string {
   const { format = "date", time = false, locale = "vi-VN", compact = false, emptyLabel = "" } = options;
-  const date = parseDate(value);
-  if (!date) return emptyLabel;
+  const parsed = parseNaive(value);
+  if (!parsed) return emptyLabel;
+  const { date, precision } = parsed;
+
+  // Reduced precision: no day, no time. A bare year is locale-invariant.
+  if (precision === "year") {
+    return String(date.getFullYear());
+  }
+  if (precision === "month") {
+    return formatMonthYear(date, format, locale, compact, emptyLabel);
+  }
 
   let dateStr: string;
   if (format === "date") {
@@ -107,3 +158,42 @@ export function formatDate(value: Date | string | null | undefined, options: For
   // 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;
 }
+
+/**
+ * Render a month-year value (no day) in the given style: numeric `MM/YYYY` in locale part order
+ * for the `date` style (year dropped when `compact`), a word month for the readable styles (the
+ * style's `day` part is omitted). `monthYear` is sentence-cased like the full-precision path.
+ */
+function formatMonthYear(
+  date: Date,
+  format: DateFormatStyle,
+  locale: string,
+  compact: boolean,
+  emptyLabel: string,
+): string {
+  if (format === "date") {
+    let parts: Intl.DateTimeFormatPart[];
+    try {
+      parts = new Intl.DateTimeFormat(locale, { month: "2-digit", year: "numeric" }).formatToParts(date);
+    } catch {
+      return emptyLabel;
+    }
+    return parts
+      .filter((p) => p.type === "month" || (!compact && p.type === "year"))
+      .map((p) => p.value)
+      .join("/");
+  }
+
+  const base = READABLE_OPTS[format];
+  const monthOpts: Intl.DateTimeFormatOptions = base.year
+    ? { month: base.month, year: base.year }
+    : { month: base.month };
+  let dateStr: string;
+  try {
+    dateStr = new Intl.DateTimeFormat(locale, monthOpts).format(date);
+  } catch {
+    return emptyLabel;
+  }
+  if (format === "monthYear") dateStr = dateStr.charAt(0).toUpperCase() + dateStr.slice(1);
+  return dateStr;
+}

package/src/format_date_negative_zone.test.ts

@@ -0,0 +1,26 @@
+// Pin a NEGATIVE-offset zone (UTC-5) before importing the formatter. The old
+// fall-through `new Date("2026-05")` parses as UTC midnight, which in a
+// negative-offset zone lands on the PREVIOUS month ("2026-04-30T19:00"), drifting
+// a month-precision value back a month. The naive part-based construction must
+// keep "2026-05" on May regardless of the runtime zone.
+process.env.TZ = "America/New_York";
+
+import { describe, expect, test } from "vitest";
+import { formatDate, toISODate } from "./format_date";
+
+describe("formatDate — reduced precision in a negative-offset zone", () => {
+  test("a month value does not drift to the previous month", () => {
+    expect(formatDate("2026-05", { locale: "en-US" })).toBe("05/2026");
+    // January is the adversarial case — a backward drift would land in Dec 2025.
+    expect(formatDate("2026-01", { locale: "en-US" })).toBe("01/2026");
+  });
+
+  test("a year value stays on its year", () => {
+    expect(formatDate("2026", { locale: "en-US" })).toBe("2026");
+  });
+
+  test("toISODate preserves the partial (no drift, no fabricated day)", () => {
+    expect(toISODate("2026-01")).toBe("2026-01");
+    expect(toISODate("2026")).toBe("2026");
+  });
+});