@lotics/ui 2.6.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "2.6.0",
+  "version": "3.0.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -31,8 +31,8 @@
     "./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",
     "./gantt": "./src/gantt/index.ts",
     "./ring_gauge": "./src/ring_gauge.tsx",
@@ -164,19 +164,6 @@
     "./landmark": "./src/landmark.tsx",
     "./skip_link": "./src/skip_link.tsx",
     "./text_utils": "./src/text_utils.ts",
-    "./cell_text": "./src/cell_text.tsx",
-    "./cell_number": "./src/cell_number.tsx",
-    "./cell_number_format": "./src/cell_number_format.ts",
-    "./cell_date": "./src/cell_date.tsx",
-    "./cell_date_format": "./src/cell_date_format.ts",
-    "./cell_select": "./src/cell_select.tsx",
-    "./grid/engine": "./src/grid/engine.tsx",
-    "./grid/layout": "./src/grid/layout.ts",
-    "./grid/use_virtual_grid": "./src/grid/use_virtual_grid.ts",
-    "./grid/skeleton_row": "./src/grid/skeleton_row.tsx",
-    "./grid/data_grid": "./src/grid/data_grid.tsx",
-    "./grid/data_grid_context": "./src/grid/data_grid_context.ts",
-    "./grid/search_highlight": "./src/grid/search_highlight.ts",
     "./column_filter": "./src/column_filter.tsx",
     "./chip_group": "./src/chip_group.tsx"
   },

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;
+}

package/src/react_native.d.ts

@@ -2,9 +2,9 @@ import "react-native";
 
 // Augments react-native's types with the web-only fields @lotics/ui consumes:
 // Pressable's `hovered` callback state, plus web-only ViewStyle / TextStyle
-// properties (cursor, outline, boxShadow, etc.) used by the grid + primitives.
+// properties (cursor, outline, boxShadow, etc.) used by its primitives.
 //
-// Each consumer (frontend, iframe_runtime, container-invoices, future iframe
+// Each consumer (frontend, container-invoices, future iframe
 // apps) ships its own copy of this file in its `src/`. TypeScript doesn't
 // auto-pick-up `.d.ts` files inside node_modules dependencies; the augmentation
 // has to be visible in the consumer's `include`. The CLI starter template

package/src/cell_date.tsx

@@ -1,30 +0,0 @@
-import { memo, useMemo } from "react";
-import { Text } from "./text";
-import { DateFormatOptions, formatDateValue } from "./cell_date_format";
-
-export interface CellDateProps extends DateFormatOptions {
-  value: string | null | undefined;
-  /** Label to render when the value parses as Invalid Date. Defaults to "Invalid date". */
-  invalidLabel?: string;
-  userSelect?: "none" | "auto";
-}
-
-/**
- * Pure-presentational date cell. Renders an empty Text for null/empty values,
- * a danger-coloured Text for unparseable values, and a locale-formatted Text
- * otherwise. Locale and format are explicit so iframe apps don't need to wire
- * a translation layer.
- */
-export const CellDate = memo(function CellDate(props: CellDateProps) {
-  const { value, format, locale, dateStyle, timeStyle, invalidLabel = "Invalid date", userSelect } = props;
-
-  const content = useMemo(() => {
-    const formatted = formatDateValue(value, { format, locale, dateStyle, timeStyle });
-    if (formatted === null) {
-      return <Text color="danger">{invalidLabel}</Text>;
-    }
-    return formatted;
-  }, [value, format, locale, dateStyle, timeStyle, invalidLabel]);
-
-  return <Text userSelect={userSelect}>{content}</Text>;
-});

package/src/cell_date_format.test.ts

@@ -1,32 +0,0 @@
-// Force a positive-offset zone (UTC+7) before importing the formatter: the old
-// `new Date("2024-03-15")` UTC-parse would surface a phantom "07:00" here, and a
-// negative-offset zone would shift the date a day. The wall-clock parse must keep
-// the value naive so output is timezone-independent.
-process.env.TZ = "Asia/Ho_Chi_Minh";
-
-import { describe, it, expect } from "vitest";
-import { formatDateValue } from "./cell_date_format";
-
-describe("formatDateValue — wall-clock (no timezone shift)", () => {
-  it("renders a date-only value as midnight, not the zone offset", () => {
-    const out = formatDateValue("2024-03-15", { format: "datetime", locale: "en-US" });
-    expect(out).toMatch(/3\/15\/2024/);
-    expect(out).toMatch(/12:00\s?AM/i); // midnight — not 7:00 AM
-  });
-
-  it("keeps the same calendar day for a date field in any zone", () => {
-    expect(formatDateValue("2024-03-15", { format: "date", locale: "en-US" })).toBe("3/15/2024");
-  });
-
-  it("renders a datetime value at its literal wall-clock time", () => {
-    expect(formatDateValue("2024-03-15T09:30", { format: "datetime", locale: "en-US" })).toMatch(
-      /9:30\s?AM/i,
-    );
-  });
-
-  it("returns '' for empty and null (sentinel) for unparseable input", () => {
-    expect(formatDateValue("")).toBe("");
-    expect(formatDateValue(null)).toBe("");
-    expect(formatDateValue("not-a-date")).toBeNull();
-  });
-});

package/src/cell_date_format.ts

@@ -1,73 +0,0 @@
-export type DateCellFormat = "date" | "datetime";
-
-export interface DateFormatOptions {
-  format?: DateCellFormat;
-  /** BCP-47 locale tag for Intl.DateTimeFormat. Defaults to "en-US". */
-  locale?: string;
-  dateStyle?: "full" | "long" | "medium" | "short";
-  timeStyle?: "full" | "long" | "medium" | "short";
-}
-
-const ISO_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
-
-/**
- * Parse a canonical, timezone-naive ISO value as wall-clock time in the local zone.
- * `new Date("2024-03-15")` parses date-only strings as **UTC** midnight, which then
- * shifts under Intl's local formatting — a phantom time on date-only values and an
- * off-by-one date in negative-offset zones. Building the Date from its parts keeps
- * it naive, matching how the picker reads the same value. Non-ISO input falls back
- * to the native parser.
- */
-function parseWallClock(value: string): Date | null {
-  const m = ISO_DATE_TIME.exec(value.trim());
-  const date = 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(value);
-  return isNaN(date.getTime()) ? null : date;
-}
-
-/**
- * Format an ISO date string to a localized display string.
- * Returns "" for null/empty input. Returns null (sentinel) for unparseable input
- * so callers can render an error state.
- */
-export function formatDateValue(
-  value: string | null | undefined,
-  options: DateFormatOptions = {},
-): string | null {
-  if (!value) return "";
-
-  const date = parseWallClock(value);
-  if (!date) return null;
-
-  const locale = options.locale ?? "en-US";
-  const { format = "date", dateStyle = "short", timeStyle = "short" } = options;
-  const includeTime = format === "datetime";
-
-  // Intl's `dateStyle: "short"` yields a 2-digit year in many locales (en-US: "5/22/26",
-  // vi-VN: "22/05/26"); for data cells we want a compact numeric format with the full year.
-  // When we override to explicit date parts, the time parts must also be explicit — Intl
-  // forbids mixing `dateStyle`/`timeStyle` with `year`/`month`/`day`/`hour`/`minute`/etc.
-  const intlOptions: Intl.DateTimeFormatOptions =
-    dateStyle === "short"
-      ? {
-          year: "numeric",
-          month: "numeric",
-          day: "numeric",
-          ...(includeTime ? { hour: "numeric", minute: "numeric" } : {}),
-        }
-      : { dateStyle, ...(includeTime ? { timeStyle } : {}) };
-
-  try {
-    return new Intl.DateTimeFormat(locale, intlOptions).format(date);
-  } catch {
-    return value;
-  }
-}

package/src/cell_number.test.ts

@@ -1,42 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { formatNumberValue } from "./cell_number_format";
-
-describe("formatNumberValue", () => {
-  it("returns empty string for null", () => {
-    expect(formatNumberValue(null, { format: "number" })).toBe("");
-  });
-
-  it("returns empty string for undefined", () => {
-    expect(formatNumberValue(undefined, { format: "number" })).toBe("");
-  });
-
-  it("formats plain number as toString", () => {
-    expect(formatNumberValue(42, { format: "number" })).toBe("42");
-    expect(formatNumberValue(3.14, {})).toBe("3.14");
-  });
-
-  it("formats percentage with % suffix", () => {
-    expect(formatNumberValue(75, { format: "percentage" })).toBe("75%");
-    expect(formatNumberValue(0, { format: "percentage" })).toBe("0%");
-  });
-
-  it("formats currency with explicit currency code", () => {
-    const result = formatNumberValue(1000, { format: "currency", currency: "USD" });
-    expect(result).toContain("US");
-  });
-
-  it("defaults to VND when currency format has no currency code", () => {
-    const result = formatNumberValue(1000, { format: "currency" });
-    expect(result).toBeTruthy();
-    expect(result.length).toBeGreaterThan(0);
-  });
-
-  it("respects an explicit locale override", () => {
-    const result = formatNumberValue(1000, {
-      format: "currency",
-      currency: "USD",
-      locale: "en-US",
-    });
-    expect(result).toMatch(/^\$/);
-  });
-});

package/src/cell_number.tsx

@@ -1,25 +0,0 @@
-import { memo } from "react";
-import { Text } from "./text";
-import { formatNumberValue, NumberFormatOptions } from "./cell_number_format";
-
-export interface CellNumberProps extends NumberFormatOptions {
-  value: number | null | undefined;
-  userSelect?: "none" | "auto";
-  align?: "left" | "right" | "center";
-}
-
-/**
- * Pure-presentational number cell. Format and locale are explicit, so iframe
- * apps consuming `@lotics/ui` without `@lotics/shared` can render numbers the
- * same way the records grid does.
- */
-export const CellNumber = memo(function CellNumber(props: CellNumberProps) {
-  const { value, format, currency, locale, userSelect, align } = props;
-  const text = formatNumberValue(value, { format, currency, locale });
-
-  return (
-    <Text numberOfLines={1} userSelect={userSelect} align={align}>
-      {text}
-    </Text>
-  );
-});

package/src/cell_number_format.ts

@@ -1,42 +0,0 @@
-export type NumberCellFormat = "number" | "currency" | "percentage";
-
-export const NUMERIC_FORMATS: ReadonlySet<string> = new Set<NumberCellFormat>([
-  "number",
-  "currency",
-  "percentage",
-]);
-
-export function isNumericFormat(value: string | undefined): value is NumberCellFormat {
-  return value !== undefined && NUMERIC_FORMATS.has(value);
-}
-
-export interface NumberFormatOptions {
-  format?: NumberCellFormat;
-  currency?: string;
-  /** BCP-47 locale tag passed to Number.prototype.toLocaleString. Defaults to "vi-VN". */
-  locale?: string;
-}
-
-export function formatNumberValue(
-  value: number | null | undefined,
-  options: NumberFormatOptions,
-): string {
-  if (value === null || value === undefined) {
-    return "";
-  }
-
-  const locale = options.locale ?? "vi-VN";
-
-  if (options.format === "currency") {
-    return value.toLocaleString(locale, {
-      style: "currency",
-      currency: options.currency || "VND",
-    });
-  }
-
-  if (options.format === "percentage") {
-    return `${value}%`;
-  }
-
-  return String(value);
-}

package/src/cell_select.tsx

@@ -1,68 +0,0 @@
-import { memo, useMemo } from "react";
-import { type ColorName } from "./colors";
-import { View } from "react-native";
-import { Badge } from "./badge";
-
-export interface SelectCellOption {
-  key: string;
-  name: string;
-  color?: ColorName;
-}
-
-export interface CellSelectProps {
-  /**
-   * Selected key(s). Accepts a single string, an array of keys, or null/undefined.
-   * Unknown keys are silently dropped (no matching option = nothing rendered).
-   */
-  value: string | string[] | null | undefined;
-  options: ReadonlyArray<SelectCellOption>;
-  /** Multi-select renders every selected key. Single-select renders only the first. */
-  multi?: boolean;
-  /** Force multi-select rendering even for single-select fields (filter previews). */
-  showAll?: boolean;
-  userSelect?: "none" | "auto";
-}
-
-/**
- * Pure-presentational select cell. Maps selected keys against the supplied
- * options[] to produce coloured Badges. Iframe apps that already have an
- * options table can render the same Lotics select-badge UI without depending
- * on `@lotics/shared` field schemas.
- */
-export const CellSelect = memo(function CellSelect(props: CellSelectProps) {
-  const { value, options, multi = false, showAll = false, userSelect = "none" } = props;
-
-  const content = useMemo(() => {
-    const selected: string[] =
-      value === null || value === undefined
-        ? []
-        : Array.isArray(value)
-          ? value
-          : [value];
-
-    const renderBadge = (key: string) => {
-      const option = options.find((o) => o.key === key);
-      if (!option) return null;
-      return <Badge key={key} color={option.color} label={option.name} userSelect={userSelect} />;
-    };
-
-    if (multi || showAll) {
-      return selected.map(renderBadge).filter(Boolean);
-    }
-
-    const first = selected[0];
-    return first === undefined ? null : renderBadge(first);
-  }, [value, options, multi, showAll, userSelect]);
-
-  return (
-    <View
-      style={{
-        flexDirection: "row",
-        gap: 4,
-        alignItems: "center",
-      }}
-    >
-      {content}
-    </View>
-  );
-});

package/src/cell_text.tsx

@@ -1,45 +0,0 @@
-import { memo } from "react";
-import { Platform } from "react-native";
-import { Text } from "./text";
-import { colors } from "./colors";
-
-export type TextCellFormat = "text" | "link";
-
-export interface CellTextProps {
-  value: string | null | undefined;
-  format?: TextCellFormat;
-  userSelect?: "none" | "auto";
-}
-
-/**
- * Pure-presentational text cell. `format: "link"` renders as a clickable
- * anchor on web (preserving right-click / middle-click behavior); on native
- * it falls through to plain Text — link navigation is the caller's job there.
- */
-export const CellText = memo(function CellText(props: CellTextProps) {
-  const { value, format = "text", userSelect } = props;
-
-  if (format === "link" && value && Platform.OS === "web") {
-    const href = /^https?:\/\//i.test(value) ? value : `https://${value}`;
-    return (
-      <a
-        href={href}
-        target="_blank"
-        rel="noopener noreferrer"
-        onClick={(e) => {
-          e.stopPropagation();
-        }}
-      >
-        <Text numberOfLines={1} style={{ color: colors.blue["600"] }} userSelect={userSelect}>
-          {value}
-        </Text>
-      </a>
-    );
-  }
-
-  return (
-    <Text numberOfLines={1} userSelect={userSelect}>
-      {value}
-    </Text>
-  );
-});