@lotics/ui 2.6.0 → 2.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -31,6 +31,7 @@
     "./kpi_card": "./src/kpi_card.tsx",
     "./kpi_strip": "./src/kpi_strip.tsx",
     "./empty_state": "./src/empty_state.tsx",
+    "./format_date": "./src/format_date.ts",
     "./format_money": "./src/format_money.ts",
     "./kanban": "./src/kanban/index.ts",
     "./calendar": "./src/calendar/index.ts",

package/src/format_date.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "vitest";
+import { formatDate, parseDate, toISODate } from "./format_date";
+
+describe("formatDate", () => {
+  test("formats an ISO date in the home market (dd/MM/yyyy)", () => {
+    expect(formatDate("2026-05-22", { locale: "vi-VN" })).toBe("22/05/2026");
+  });
+
+  test("formats a Date object, not just an ISO string", () => {
+    expect(formatDate(new Date(2026, 4, 22), { locale: "vi-VN" })).toBe("22/05/2026");
+  });
+
+  test("compact drops the year (dd/MM)", () => {
+    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("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("date-only ISO does not drift across local timezone (wall-clock parse)", () => {
+    // `new Date('2026-01-01')` is UTC midnight; in negative-offset zones it formats as Dec 31.
+    expect(formatDate("2026-01-01", { locale: "vi-VN" })).toBe("01/01/2026");
+  });
+
+  test("empty input returns the empty label", () => {
+    expect(formatDate(null)).toBe("");
+    expect(formatDate("")).toBe("");
+    expect(formatDate(undefined, { emptyLabel: "—" })).toBe("—");
+    expect(formatDate("not-a-date", { emptyLabel: "—" })).toBe("—");
+  });
+});
+
+describe("parseDate", () => {
+  test("parses an ISO datetime to local wall-clock", () => {
+    const d = parseDate("2026-05-22T14:30");
+    expect(d).not.toBeNull();
+    expect(d?.getFullYear()).toBe(2026);
+    expect(d?.getMonth()).toBe(4);
+    expect(d?.getDate()).toBe(22);
+    expect(d?.getHours()).toBe(14);
+    expect(d?.getMinutes()).toBe(30);
+  });
+
+  test("passes a valid Date through and rejects an invalid one", () => {
+    const d = new Date(2026, 0, 1);
+    expect(parseDate(d)).toBe(d);
+    expect(parseDate(new Date("nonsense"))).toBeNull();
+    expect(parseDate(null)).toBeNull();
+    expect(parseDate("")).toBeNull();
+  });
+});
+
+describe("toISODate", () => {
+  test("Date or ISO value → yyyy-MM-dd", () => {
+    expect(toISODate(new Date(2026, 4, 22))).toBe("2026-05-22");
+    expect(toISODate("2026-05-22T14:30")).toBe("2026-05-22");
+    expect(toISODate(null)).toBe("");
+  });
+});

package/src/format_date.ts

@@ -0,0 +1,71 @@
+export type DateFormatStyle = "date" | "datetime";
+
+export interface FormatDateOptions {
+  /** "date" → 22/05/2026 · "datetime" → 22/05/2026 14:30. Default "date". */
+  format?: DateFormatStyle;
+  /** 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. */
+  compact?: boolean;
+  /** Rendered for null / empty / unparseable input. Default "". */
+  emptyLabel?: string;
+}
+
+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.
+ */
+export function parseDate(value: Date | string | null | undefined): Date | null {
+  if (value == null) return null;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+  const s = value.trim();
+  if (!s) return null;
+  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;
+}
+
+/** A Date or ISO value → "yyyy-MM-dd" (the `DatePicker` / workflow date value). "" when empty. */
+export function toISODate(value: Date | string | null | undefined): string {
+  const d = parseDate(value);
+  if (!d) return "";
+  return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+}
+
+/**
+ * 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.
+ */
+export function formatDate(value: Date | string | null | undefined, options: FormatDateOptions = {}): string {
+  const { format = "date", 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 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;
+}