@terpjs/react-core 0.9.0 → 0.11.0

package/src/dataview/DataViewTable.tsx

@@ -8,10 +8,14 @@ import { DataViewExpandToggle, DataViewExpandableRow } from "./DataViewExpandabl
 import { DataViewRowActions } from "./DataViewRowActions";
 import type { DataViewRowActionsLayout } from "./DataViewRowActions";
 import { SortAscGlyph, SortDescGlyph, SortNoneGlyph } from "./glyphs";
-import { useDataViewText } from "./internal";
+import { useCellFormatter, useDataViewText } from "./internal";
 
 injectTerpStyles();
-import type { DataViewColumn, DataViewRowAction } from "./types";
+import type {
+  ColumnWidth,
+  DataViewColumn,
+  DataViewRowAction,
+} from "./types";
 
 const MIN_COLUMN_WIDTH = 60;
 
@@ -54,6 +58,7 @@ export interface DataViewTableProps<T> {
  */
 export function DataViewTable<T>(props: DataViewTableProps<T>) {
   const { strings, resolve, format } = useDataViewText();
+  const formatCell = useCellFormatter();
   const tableRef = useRef<HTMLTableElement>(null);
 
   // Live widths during a resize drag only — persisted once, on pointer-up.
@@ -93,7 +98,13 @@ export function DataViewTable<T>(props: DataViewTableProps<T>) {
       const onPointerUp = () => {
         cleanup();
         setLiveSizing(null);
-        props.onCommitColumnSizing(current); // one persistence write per drag
+        // ONLY the dragged column is committed, though `current` holds a width for every one of
+        // them. The snapshot exists to stop the other columns jumping when the layout flips to
+        // fixed for the duration of the drag; persisting it would tell the view state the user had
+        // sized the whole table, and `stepOf` would then suppress every declared track — one drag
+        // anywhere would switch the floors off table-wide, and durably so for an app with a view
+        // state repository. `commitColumnSizing` merges, so earlier resizes survive this.
+        props.onCommitColumnSizing({ [columnId]: current[columnId] ?? startWidth }); // one write per drag
       };
       window.addEventListener("pointermove", onPointerMove);
       window.addEventListener("pointerup", onPointerUp);
@@ -102,17 +113,21 @@ export function DataViewTable<T>(props: DataViewTableProps<T>) {
     [props.onCommitColumnSizing],
   );
 
-  const widthOf = (column: DataViewColumn<T>): number | string | undefined => {
-    const live = liveSizing?.[column.id];
-    if (live !== undefined) {
-      return live;
-    }
-    const resized = props.columnSizing[column.id];
-    if (resized !== undefined) {
-      return resized;
-    }
-    return column.meta?.width;
-  };
+  /**
+   * The user's own width for a column, in px, or `undefined` if they have not resized it.
+   *
+   * This and {@link stepOf} are deliberately exclusive: a resized column emits an inline `width`
+   * and NO `data-width`, so the declared step stops applying the moment the user disagrees with
+   * it. Emitting both would put a `min-inline-size` from the sheet against an inline `width`, and
+   * the minimum wins — dragging a column below its declared step would spring back and the
+   * resizer would look broken.
+   */
+  const resizedWidthOf = (column: DataViewColumn<T>): number | undefined =>
+    liveSizing?.[column.id] ?? props.columnSizing[column.id];
+
+  /** The declared track, which applies only while the column is at its default width. */
+  const stepOf = (column: DataViewColumn<T>): ColumnWidth | undefined =>
+    resizedWidthOf(column) === undefined ? column.meta?.width : undefined;
 
   const hasExpand = props.renderExpanded !== undefined;
   const hasActions = props.rowActions !== undefined;
@@ -149,11 +164,13 @@ export function DataViewTable<T>(props: DataViewTableProps<T>) {
           {props.columns.map((column) => {
             const sort = props.sorting.find((entry) => entry.id === column.id);
             const sortable = column.enableSorting !== false;
-            const width = widthOf(column);
+            const width = resizedWidthOf(column);
+            const step = stepOf(column);
             return (
               <th
                 key={column.id}
                 data-column-id={column.id}
+                data-width={step}
                 aria-sort={
                   sort === undefined ? undefined : sort.desc ? "descending" : "ascending"
                 }
@@ -279,9 +296,3 @@ function RowGroup({ children }: { children: ReactNode }) {
   return <>{children}</>;
 }
 
-function formatCell(value: unknown): ReactNode {
-  if (value === null || value === undefined) {
-    return null;
-  }
-  return String(value);
-}

package/src/dataview/README.md

@@ -31,7 +31,7 @@ interface Ticket { id: string; title: string; status: string; created: string }
 const columns: DataViewColumn<Ticket>[] = [
   { id: "title", header: "Title", accessor: (t) => t.title, meta: { mobileSlot: "title" } },
   { id: "status", header: "Status", accessor: (t) => t.status, meta: { mobileSlot: "status" } },
-  { id: "created", header: "Created", accessor: (t) => t.created, meta: { mobileSlot: "date", width: 120 } },
+  { id: "created", header: "Created", accessor: (t) => t.created, meta: { mobileSlot: "date", width: "sm" } },
 ];
 
 const repository = new InMemoryDataViewRepository(tickets, {
@@ -113,12 +113,23 @@ versioned envelope; corrupt data falls back to defaults) and
 
 ## Behaviour notes
 
+- **Default cell rendering** is shared by the table and the card layouts, so a column reads
+  the same on a desktop and a phone: `null` / `undefined` render nothing, a `Date` renders
+  through the app's locale, and anything else is `String(value)`. Pass `cell` to override.
+- **Dates and numbers** in a `cell` renderer should go through `useFormatDate` /
+  `useFormatDateTime` / `useFormatNumber`; `toLocaleDateString()` with no argument asks the
+  visitor's browser rather than the app, and a repo-wide check refuses it.
 - **System columns** are auto-injected in a fixed order — expand toggle, selection
   checkbox, user columns, row-actions (sr-only header) — pinned to narrow widths and
   never hideable/reorderable/resizable.
 - **Column resizing**: drag the header handle; widths update live with no persistence
   writes per pointermove and are persisted once, on pointer-up. Width precedence:
-  pinned system columns → user-resized → static `meta.width` hint → auto.
+  pinned system columns → user-resized → declared `meta.width` step → auto.
+- **Declared column tracks**: `meta.width` is a step (`"xs"` / `"sm"` / `"md"`), not a
+  length, and it binds as a **minimum** — under `table-layout: auto` a specified width is
+  only a preference the algorithm shrinks to fit, so the px hint this replaced did nothing
+  at all. A user resize replaces the step outright rather than competing with it: a resized
+  column stops carrying the attribute, so the floor can never spring a drag back.
 - **Row tone**: `getRowTone={(row) => tone | null}` marks the *row* as being in a
   state (a refused link, a failed run) — the right altitude when the verdict belongs
   to the record, not to one of its cells. The row/card is tinted with the tone's soft

package/src/dataview/index.ts

@@ -22,6 +22,7 @@ export type {
   DataViewRepository,
   DataViewState,
   ViewStateRepository,
+  ColumnWidth,
   DataViewColumn,
   DataViewColumnMeta,
   DataViewDensity,

package/src/dataview/internal.tsx

@@ -1,6 +1,7 @@
-import { createContext, useContext } from "react";
+import { createContext, useCallback, useContext } from "react";
 import type { ReactNode } from "react";
 
+import { useFormatDate } from "../format";
 import { injectTerpStyles } from "../styles";
 import { Menu, MenuItem } from "../ui/Menu";
 import { useUiText } from "../uiText";
@@ -29,6 +30,35 @@ export function useDataViewText(): DataViewTextApi {
   return useContext(DataViewTextContext);
 }
 
+/**
+ * Stringify a cell for a column that declares no `cell` renderer.
+ *
+ * One hook rather than a helper per renderer, because there WERE two: the table had a private
+ * `formatCell` and the mobile card list inlined the same three lines. They agreed, so nothing
+ * caught that they were two, and the first change to either would have made a row render one way
+ * on a desktop and another on a phone.
+ *
+ * The `Date` branch is why that mattered. `accessor` returns `unknown`, so a `Date` is type-legal
+ * and `String(value)` renders `Wed Aug 21 2026 00:00:00 GMT+0200 (Central European Summer Time)`
+ * in a table cell. Nothing in this tree returns one today, which is exactly why it was worth
+ * closing now rather than after an app discovered it.
+ */
+export function useCellFormatter(): (value: unknown) => ReactNode {
+  const formatDate = useFormatDate();
+  return useCallback(
+    (value: unknown) => {
+      if (value === null || value === undefined) {
+        return null;
+      }
+      if (value instanceof Date) {
+        return formatDate(value);
+      }
+      return String(value);
+    },
+    [formatDate],
+  );
+}
+
 export function DataViewTextProvider({
   overrides,
   children,

package/src/dataview/types.ts

@@ -107,14 +107,32 @@ export type DataViewMobileSlot = "title" | "subtitle" | "status" | "date";
  */
 export type DataViewDensity = "comfortable" | "compact";
 
+/**
+ * A column's declared track: a step, not a length.
+ *
+ * The three steps are the three bands the framework's own tables actually declare, and there are
+ * deliberately no others. `lg` and a content-hugging step were both drafted and dropped for the
+ * same reason a component with no consumer is dropped — nothing asks for them, and a step is
+ * additive to add and breaking to remove. The scale is rem, so a declared track follows the root
+ * font size instead of pinning a column to one display's pixels.
+ */
+export type ColumnWidth = "xs" | "sm" | "md";
+
 /** Typed column meta the DataView-specific features read. */
 export interface DataViewColumnMeta {
   /** Human-readable name used in the column-settings menu (falls back to the header). */
   label?: UiText;
   /** Slot in the auto-composed card layout. */
   mobileSlot?: DataViewMobileSlot;
-  /** Fixed width hint (number = px, or any CSS length). */
-  width?: number | string;
+  /**
+   * The column's declared minimum track. Omit for content-based auto sizing.
+   *
+   * A **minimum**, because that is the only thing `table-layout: auto` cannot take away: a
+   * specified `width` is a preference the algorithm shrinks to fit, which is why the px hint this
+   * replaced did nothing at all. A user's own resize replaces the declared track entirely rather
+   * than fighting it.
+   */
+  width?: ColumnWidth;
 }
 
 /** Generic, typed column definition for {@link DataView}. */
@@ -125,7 +143,12 @@ export interface DataViewColumn<T> {
   header: UiText;
   /** The raw value of this column for a row (used by default cell rendering). */
   accessor?: (row: T) => unknown;
-  /** Custom cell renderer; defaults to `String(accessor(row))`. */
+  /**
+   * Custom cell renderer. Without one the accessor's value is rendered by the shared default:
+   * `null` / `undefined` render nothing, a `Date` renders through the app's locale (the same
+   * `useFormatDate` the framework's own screens use), and anything else is `String(value)`.
+   * Table and card layouts share that default, so a column reads the same on both.
+   */
   cell?: (row: T) => ReactNode;
   /** Whether the header offers the 3-state sort toggle (default true). */
   enableSorting?: boolean;

package/src/format.test.tsx

@@ -0,0 +1,213 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import type { ReactNode } from "react";
+
+import { DataView } from "./dataview";
+import { InMemoryDataViewRepository } from "./dataview";
+import type { DataViewColumn } from "./dataview";
+import {
+  formatDate,
+  formatDateTime,
+  formatNumber,
+  useFormatDate,
+  useFormatNumber,
+} from "./format";
+import { LocaleProvider } from "./locale";
+
+afterEach(() => {
+  cleanup();
+  window.localStorage.clear();
+});
+
+// Midday UTC keeps the calendar date stable across most zones, but only most: UTC+13 and UTC+14
+// exist (Pacific/Apia, Pacific/Kiritimati), so at 12:00Z the local date there is already the 8th.
+// No assertion below depends on WHICH day it is — the locale assertions compare two locales against
+// each other, and the shape assertions ask whether the day or the month comes first. An earlier
+// version asserted the literal digit 7 and would have failed in Kiritimati and nowhere else.
+const WHEN = "2026-07-07T12:00:00Z";
+
+const NL = { label: "Nederlands", strings: {} };
+const EN = { label: "English", strings: {} };
+
+describe("the locale-explicit formatters", () => {
+  it("actually varies with the locale it is given", () => {
+    // The whole defect was a missing argument, so the assertion that matters is that the argument
+    // changes the answer. Comparing against one hard-coded string would pass just as happily if
+    // the locale were ignored and both calls fell through to the runner's default.
+    const dutch = formatDate(WHEN, "nl");
+    const american = formatDate(WHEN, "en-US");
+    expect(dutch).not.toBe(american);
+    // Day-first versus month-first is the visible difference, and it survives both an ICU update
+    // and a runner in a zone where the local calendar date is already the next day.
+    expect(dutch).toMatch(/^\d/);
+    expect(american).toMatch(/^[A-Za-z]/);
+  });
+
+  it("adds a time of day only in the date-time form", () => {
+    // The audit log's column is titled "when"; dropping its clock would be a silent downgrade.
+    expect(formatDateTime(WHEN, "en-US")).toMatch(/\d{1,2}:\d{2}/);
+    expect(formatDate(WHEN, "en-US")).not.toMatch(/\d{1,2}:\d{2}/);
+  });
+
+  it("groups and separates numbers the way the locale does", () => {
+    expect(formatNumber(1234.5, "nl")).not.toBe(formatNumber(1234.5, "en-US"));
+    expect(formatNumber(1234.5, "en-US")).toBe("1,234.5");
+  });
+
+  it("renders an em dash for nothing, rather than throwing or printing Invalid Date", () => {
+    // `new Date("whenever")` yields an Invalid Date whose `format` throws a RangeError, so one
+    // malformed row from an API would take down a whole table instead of showing one dash.
+    for (const value of [null, undefined, "", "not a date", Number.NaN]) {
+      expect(formatDate(value, "nl")).toBe("—");
+      expect(formatDateTime(value, "nl")).toBe("—");
+    }
+    expect(formatNumber(null, "nl")).toBe("—");
+    expect(formatNumber(Number.NaN, "nl")).toBe("—");
+  });
+
+  it("builds one formatter per locale, not one per value", () => {
+    // Constructing an Intl formatter costs ~55x using one, and every table cell comes through
+    // here, so the first version of this file turned a locale fix into a rendering cost: a 200-row
+    // table with three date columns built 600 formatters per render. Counting constructions is the
+    // only way to see it — the output is identical either way, which is exactly why it shipped.
+    const original = Intl.DateTimeFormat;
+    let constructed = 0;
+    try {
+      (Intl as { DateTimeFormat: unknown }).DateTimeFormat = function counted(
+        ...args: ConstructorParameters<typeof Intl.DateTimeFormat>
+      ) {
+        constructed += 1;
+        return new original(...args);
+      };
+      for (let index = 0; index < 50; index += 1) {
+        formatDate(`2026-07-${String((index % 28) + 1).padStart(2, "0")}T12:00:00Z`, "en-GB");
+      }
+      expect(constructed).toBe(1);
+      // A second locale is a second formatter, not a cache that answers with the wrong one.
+      formatDate(WHEN, "en-IE");
+      expect(constructed).toBe(2);
+    } finally {
+      (Intl as { DateTimeFormat: unknown }).DateTimeFormat = original;
+    }
+  });
+
+  it("accepts the three shapes a date field arrives in", () => {
+    const iso = formatDate(WHEN, "en-US");
+    expect(formatDate(new Date(WHEN), "en-US")).toBe(iso);
+    expect(formatDate(new Date(WHEN).getTime(), "en-US")).toBe(iso);
+  });
+});
+
+function ShownDate() {
+  return <p data-testid="shown">{useFormatDate()(WHEN)}</p>;
+}
+
+function ShownNumber() {
+  return <p data-testid="shown">{useFormatNumber()(1234.5)}</p>;
+}
+
+/** Render `body` under one app locale and return what it printed. */
+function shownUnder(locale: string, body: ReactNode): string {
+  const { unmount } = render(
+    <LocaleProvider locales={{ nl: NL, "en-US": EN }} defaultLocale={locale}>
+      {body}
+    </LocaleProvider>,
+  );
+  const text = screen.getByTestId("shown").textContent ?? "";
+  unmount();
+  return text;
+}
+
+describe("the hooks", () => {
+  // These compare TWO app locales against each other rather than one against an expected string,
+  // and the reason is worth stating because the first version of this file did the latter and a
+  // mutation proved it worthless. This machine's Node resolves to nl-NL, so
+  // `formatDate(value, undefined)` and `formatDate(value, "nl")` are the same string: a test that
+  // rendered a Dutch provider and asserted the Dutch spelling passed with the hook ignoring its
+  // locale entirely. It would have failed on an English host and passed here, which is worse than
+  // no test. Two locales cannot agree unless the locale is being dropped, on any host.
+
+  it("reads the app's locale, not the machine's", () => {
+    const dutch = shownUnder("nl", <ShownDate />);
+    const american = shownUnder("en-US", <ShownDate />);
+    expect(dutch).not.toBe(american);
+    expect(dutch).toBe(formatDate(WHEN, "nl"));
+    expect(american).toBe(formatDate(WHEN, "en-US"));
+  });
+
+  it("formats numbers through the same locale", () => {
+    const dutch = shownUnder("nl", <ShownNumber />);
+    const american = shownUnder("en-US", <ShownNumber />);
+    expect(dutch).not.toBe(american);
+    expect(american).toBe("1,234.5");
+  });
+
+  it("falls back to the runtime default outside a LocaleProvider", () => {
+    // `useLocale()` returns null with no provider, and that must mean "let Intl decide" rather
+    // than throw: `Field`, `DataView` and the admin screens all render fine without one.
+    render(<ShownDate />);
+    expect(screen.getByTestId("shown")).toHaveTextContent(formatDate(WHEN, undefined));
+  });
+});
+
+interface Dated {
+  id: string;
+  when: Date;
+}
+
+const DATED_COLUMNS: DataViewColumn<Dated>[] = [
+  { id: "when", header: "When", accessor: (row) => row.when, meta: { mobileSlot: "title" } },
+];
+
+function datedView(locale: string, when: Date) {
+  const repository = new InMemoryDataViewRepository([{ id: "1", when }], {
+    getRowId: (row) => row.id,
+    getValue: (row, column) => row[column as keyof Dated],
+  });
+  return (
+    <LocaleProvider locales={{ nl: NL, "en-US": EN }} defaultLocale={locale}>
+      <DataView<Dated> repository={repository} columns={DATED_COLUMNS} />
+    </LocaleProvider>
+  );
+}
+
+describe("a Date in a cell", () => {
+  // Rendered under BOTH locales, for the reason stated at the top of the hook block: the runner is
+  // nl-NL, so a single Dutch render would go green with `useCellFormatter` ignoring its locale
+  // entirely. That is what the first version of this test did — twenty lines under a comment
+  // explaining why not to. Two locales cannot both be right unless the locale is being read.
+  const when = new Date(WHEN);
+
+  it("guards its own premise: the two spellings differ", () => {
+    expect(formatDate(when, "nl")).not.toBe(formatDate(when, "en-US"));
+  });
+
+  it("is formatted for the app's locale instead of stringified — table view", async () => {
+    // `accessor` returns `unknown`, so a Date is type-legal, and `String(value)` renders
+    // "Tue Jul 07 2026 14:00:00 GMT+0200 (Central European Summer Time)" into a table cell.
+    render(datedView("en-US", when));
+    expect(await screen.findByText(formatDate(when, "en-US"))).toBeInTheDocument();
+    expect(screen.queryByText(formatDate(when, "nl"))).toBeNull();
+    expect(screen.queryByText(String(when))).toBeNull();
+    cleanup();
+
+    render(datedView("nl", when));
+    expect(await screen.findByText(formatDate(when, "nl"))).toBeInTheDocument();
+    expect(screen.queryByText(formatDate(when, "en-US"))).toBeNull();
+  });
+
+  it("is formatted for the app's locale instead of stringified — card view", async () => {
+    // The stated reason for extracting `useCellFormatter` was that the two renderers had drifted
+    // apart unnoticed, so pinning only the desktop one would reproduce the defect the extraction
+    // was for. `DataView` reads `matchMedia` to pick a layout and jsdom always says no, so the
+    // card list is only reachable through the explicit toggle.
+    render(datedView("en-US", when));
+    expect(await screen.findByRole("table")).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Card view" }));
+    expect(screen.queryByRole("table")).not.toBeInTheDocument();
+    expect(screen.getByText(formatDate(when, "en-US"))).toBeInTheDocument();
+    expect(screen.queryByText(formatDate(when, "nl"))).toBeNull();
+    expect(screen.queryByText(String(when))).toBeNull();
+  });
+});

package/src/format.ts

@@ -0,0 +1,150 @@
+import { useCallback } from "react";
+
+import { useLocale } from "./locale";
+
+/**
+ * Locale-aware date and number formatting.
+ *
+ * Seven places in this package formatted a date with `toLocaleDateString()` or
+ * `toLocaleString()` and no locale argument, which asks the *browser* what language to use. An app
+ * that ships Dutch through `LocaleProvider` therefore rendered its own admin tables in whatever
+ * the visitor's OS was set to, one row above a `DatePicker` that got it right — because the
+ * correct helper already existed, private, in a file about calendars.
+ *
+ * That helper is now here, unchanged, and `DatePicker` imports it back. Adopting its exact shape
+ * rather than inventing one is deliberate: it is the only date rendering in the package that was
+ * already locale-correct, so it is the one that defines the house shape, and moving it moves no
+ * pixels.
+ *
+ * Each formatter comes in two forms. The hook reads the app's locale from context and is what a
+ * component should use; the plain function takes the locale explicitly, for a caller that already
+ * has one or is not a component. The hooks are `useCallback`-stable so a column list built in a
+ * `useMemo` can depend on one without rebuilding every render.
+ */
+
+/** Anything a record's date field plausibly arrives as. */
+export type FormattableDate = Date | string | number | null | undefined;
+
+/**
+ * What an absent or unparseable date renders as.
+ *
+ * An em dash rather than an empty cell, because a blank reads as "still loading" in a table and as
+ * a layout bug in a detail list. This is the glyph the audit screen already used for the same job.
+ */
+const EMPTY = "—";
+
+/**
+ * Parse without throwing, and treat an unparseable value as absent.
+ *
+ * `new Date("not a date")` yields an Invalid Date whose `format` throws a RangeError, so a single
+ * malformed row from an API would take down the whole table rather than showing one dash.
+ */
+function toDate(value: FormattableDate): Date | null {
+  if (value === null || value === undefined) {
+    return null;
+  }
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+const DATE_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: "numeric",
+  month: "short",
+  day: "numeric",
+};
+
+const DATE_TIME_OPTIONS: Intl.DateTimeFormatOptions = {
+  ...DATE_OPTIONS,
+  hour: "2-digit",
+  minute: "2-digit",
+};
+
+/**
+ * Formatters, kept.
+ *
+ * Constructing an `Intl` formatter is expensive out of all proportion to using one — measured on
+ * this repository's Node, roughly 55x a cached instance and 69x the `toLocaleDateString()` these
+ * helpers replaced, because the built-in call is serviced from V8's own cache for the default
+ * locale and an explicit constructor is not. Every cell of every table goes through here, so
+ * building one per value turned a locale fix into a rendering cost: a 200-row table with three
+ * date columns is 600 constructions per render.
+ *
+ * The keys are a closed set in practice — an app declares its locales in `LocaleProvider` — so
+ * this is a cache with no eviction on purpose rather than by oversight.
+ */
+const DATE_FORMATTERS = new Map<string, Intl.DateTimeFormat>();
+const NUMBER_FORMATTERS = new Map<string, Intl.NumberFormat>();
+
+function dateFormatter(locale: string | undefined, withTime: boolean): Intl.DateTimeFormat {
+  const key = `${withTime ? "t" : "d"}|${locale ?? ""}`;
+  let formatter = DATE_FORMATTERS.get(key);
+  if (formatter === undefined) {
+    formatter = new Intl.DateTimeFormat(locale, withTime ? DATE_TIME_OPTIONS : DATE_OPTIONS);
+    DATE_FORMATTERS.set(key, formatter);
+  }
+  return formatter;
+}
+
+function numberFormatter(
+  locale: string | undefined,
+  options: Intl.NumberFormatOptions | undefined,
+): Intl.NumberFormat {
+  // Options are a caller's object rather than one of two constants, so they join the key. Two
+  // equivalent objects written in a different order miss each other, which costs one extra
+  // formatter and never a wrong answer.
+  const key = `${locale ?? ""}|${options === undefined ? "" : JSON.stringify(options)}`;
+  let formatter = NUMBER_FORMATTERS.get(key);
+  if (formatter === undefined) {
+    formatter = new Intl.NumberFormat(locale, options);
+    NUMBER_FORMATTERS.set(key, formatter);
+  }
+  return formatter;
+}
+
+/** Locale-explicit short date, e.g. `7 jul 2026` under `nl`. `EMPTY` for absent or unparseable. */
+export function formatDate(value: FormattableDate, locale: string | undefined): string {
+  const date = toDate(value);
+  return date === null ? EMPTY : dateFormatter(locale, false).format(date);
+}
+
+/** The same date with the time of day, for a column whose subject is *when* something happened. */
+export function formatDateTime(value: FormattableDate, locale: string | undefined): string {
+  const date = toDate(value);
+  return date === null ? EMPTY : dateFormatter(locale, true).format(date);
+}
+
+/** Locale-explicit number, with the grouping and decimal separators the locale expects. */
+export function formatNumber(
+  value: number | null | undefined,
+  locale: string | undefined,
+  options?: Intl.NumberFormatOptions,
+): string {
+  return value === null || value === undefined || Number.isNaN(value)
+    ? EMPTY
+    : numberFormatter(locale, options).format(value);
+}
+
+/** {@link formatDate} bound to the app's locale. */
+export function useFormatDate(): (value: FormattableDate) => string {
+  const locale = useLocale()?.locale;
+  return useCallback((value: FormattableDate) => formatDate(value, locale), [locale]);
+}
+
+/** {@link formatDateTime} bound to the app's locale. */
+export function useFormatDateTime(): (value: FormattableDate) => string {
+  const locale = useLocale()?.locale;
+  return useCallback((value: FormattableDate) => formatDateTime(value, locale), [locale]);
+}
+
+/** {@link formatNumber} bound to the app's locale. */
+export function useFormatNumber(): (
+  value: number | null | undefined,
+  options?: Intl.NumberFormatOptions,
+) => string {
+  const locale = useLocale()?.locale;
+  return useCallback(
+    (value: number | null | undefined, options?: Intl.NumberFormatOptions) =>
+      formatNumber(value, locale, options),
+    [locale],
+  );
+}