@terpjs/react-core 0.8.0 → 0.10.0

package/src/download.test.tsx

@@ -0,0 +1,153 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { downloadUrl, saveBlob, useEndpointDownload } from "./download";
+import { TerpProvider } from "./TerpProvider";
+
+// Downloading a *generated* artifact (ADR 0096). The two things a hand-rolled version
+// gets wrong are what these tests pin: a raw `<a href>` carries no bearer token (so it
+// saves an error page under the intended filename), and a raw fetch leaks the object URL.
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  restoreObjectUrl();
+});
+
+// jsdom ships no object-URL implementation, so it is installed per test rather than
+// stubbed over the global `URL` — replacing that breaks the client's own URL building,
+// which is exactly the machinery these tests are here to exercise.
+type ObjectUrlHost = { createObjectURL?: (blob: Blob) => string; revokeObjectURL?: (url: string) => void };
+const objectUrlHost = URL as unknown as ObjectUrlHost;
+const originalCreate = objectUrlHost.createObjectURL;
+const originalRevoke = objectUrlHost.revokeObjectURL;
+
+function installObjectUrl(): { revoked: string[] } {
+  const revoked: string[] = [];
+  objectUrlHost.createObjectURL = () => "blob:x";
+  objectUrlHost.revokeObjectURL = (url: string) => void revoked.push(url);
+  return { revoked };
+}
+
+function restoreObjectUrl(): void {
+  objectUrlHost.createObjectURL = originalCreate;
+  objectUrlHost.revokeObjectURL = originalRevoke;
+}
+
+describe("downloadUrl", () => {
+  it("fills path placeholders and appends only the set query keys", () => {
+    expect(
+      downloadUrl({
+        path: "/api/v1/revisions/{revisionId}/evidence",
+        filename: "x.json",
+        params: { revisionId: "r-1" },
+        query: { format: "json", locale: undefined },
+      }),
+    ).toBe("/api/v1/revisions/r-1/evidence?format=json");
+  });
+
+  it("encodes a param rather than splicing it into the path raw", () => {
+    expect(downloadUrl({ path: "/api/v1/x/{id}", filename: "f", params: { id: "a/b" } })).toBe(
+      "/api/v1/x/a%2Fb",
+    );
+  });
+
+  it("refuses an unfilled placeholder instead of requesting a literal {id}", () => {
+    // Requesting `/revisions/{revisionId}/evidence` would 404 — or, on a permissive
+    // route, hand back somebody else's bytes.
+    expect(() =>
+      downloadUrl({ path: "/api/v1/revisions/{revisionId}/evidence", filename: "x" }),
+    ).toThrow(/still contains the placeholder "\{revisionId\}"/);
+  });
+});
+
+describe("saveBlob", () => {
+  it("offers the bytes under the given filename and revokes the object URL", () => {
+    const { revoked } = installObjectUrl();
+    const clicked: string[] = [];
+    const click = vi
+      .spyOn(HTMLAnchorElement.prototype, "click")
+      .mockImplementation(function (this: HTMLAnchorElement) {
+        clicked.push(this.download);
+      });
+
+    saveBlob(new Blob(["body"]), "evidence.json");
+
+    expect(clicked).toEqual(["evidence.json"]);
+    // Revoked in a `finally`, which is the leak every hand-rolled copy forgets.
+    expect(revoked).toEqual(["blob:x"]);
+    // ...and nothing is left in the document.
+    expect(document.querySelector("a")).toBeNull();
+    click.mockRestore();
+  });
+});
+
+describe("useEndpointDownload", () => {
+  function DownloadButton() {
+    const download = useEndpointDownload();
+    return (
+      <button
+        type="button"
+        onClick={() =>
+          void download({
+            path: "/api/v1/revisions/{revisionId}/evidence",
+            params: { revisionId: "r-1" },
+            filename: "evidence.json",
+          }).catch((error: unknown) => {
+            document.title = (error as Error).message;
+          })
+        }
+      >
+        download
+      </button>
+    );
+  }
+
+  it("fetches through the session client, so the request carries the session", async () => {
+    const fetchMock = vi.fn<typeof fetch>(
+      async () => new Response("bytes", { status: 200, headers: { "content-type": "application/octet-stream" } }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+    installObjectUrl();
+    const click = vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <DownloadButton />
+      </TerpProvider>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "download" }));
+
+    // The provider's own boot session-probe is also on this mock, so match the download
+    // rather than assuming it is the first request.
+    await waitFor(() =>
+      expect(
+        fetchMock.mock.calls.map((call) => (call[0] as Request).url),
+        // Resolved against the client's base URL — the thing a raw <a href> could not do.
+      ).toContain("https://api.test/api/v1/revisions/r-1/evidence"),
+    );
+    click.mockRestore();
+  });
+
+  it("rejects on a non-2xx instead of saving the error body under the filename", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn<typeof fetch>(async () => new Response("nope", { status: 403 })),
+    );
+    const click = vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+
+    render(
+      <TerpProvider baseUrl="https://api.test">
+        <DownloadButton />
+      </TerpProvider>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "download" }));
+
+    await waitFor(() => expect(document.title).toMatch(/failed with HTTP 403/));
+    // Nothing was handed to the browser: the failure surfaces instead of downloading.
+    expect(click).not.toHaveBeenCalled();
+    click.mockRestore();
+  });
+});

package/src/download.tsx

@@ -0,0 +1,132 @@
+/**
+ * Handing bytes to the browser as a named download (ADR 0096).
+ *
+ * `useFileDownload` covers the stored-file case: a `FileMeta` id, fetched from the files
+ * capability's content endpoint. What it does not cover is the other half of the same
+ * need — **an artifact the backend generates on demand** ("download this revision as
+ * proof", a CSV export, a signed evidence bundle). Those have no stored file id, and the
+ * only ways to reach them were a raw `fetch` (refused: one typed egress path) or a raw
+ * `<a href>` (which carries no bearer token, so it 401s or, worse, silently downloads an
+ * error page). The observed outcome was the feature being dropped rather than built.
+ *
+ * So the blob-to-anchor dance lives here once, and `useEndpointDownload` reaches any
+ * authorized GET through the session client. `path` is a plain string, deliberately and
+ * unusually: the generated client is keyed by the app's own schema, which this package
+ * cannot see, and a byte-stream route is app-specific by nature. Everything else that
+ * matters — the base URL, the bearer token, cookie credentials, the refusal on a non-2xx —
+ * still comes from the client, which is what the raw alternatives threw away.
+ */
+
+import { useCallback } from "react";
+
+import { useTerpClient } from "./TerpProvider";
+import type { TerpClient } from "@terpjs/contract";
+
+/** What to download: where the bytes come from, and what the file should be called. */
+export interface DownloadTarget {
+  /** API path, e.g. `/api/v1/revisions/{id}/evidence` with `params` filling `{id}`. */
+  path: string;
+  /** Filename offered to the browser (extension included). */
+  filename: string;
+  /** Path placeholders to substitute, e.g. `{ id: revision.id }`. */
+  params?: Record<string, string>;
+  /** Query string to append; `undefined` values are omitted. */
+  query?: Record<string, string | undefined>;
+}
+
+/**
+ * Save *blob* as a named download.
+ *
+ * Exported because it is the one piece a screen cannot avoid re-implementing when it
+ * already holds the bytes (a client-side CSV, a canvas export) — and every hand-rolled
+ * copy leaks the object URL, which is why the revoke is in a `finally` here.
+ */
+export function saveBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  try {
+    const anchor = document.createElement("a");
+    anchor.href = url;
+    anchor.download = filename;
+    document.body.appendChild(anchor);
+    anchor.click();
+    anchor.remove();
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+/** Fill `{placeholder}` segments and append the query string, dropping unset values. */
+export function downloadUrl(target: DownloadTarget): string {
+  let path = target.path;
+  for (const [name, value] of Object.entries(target.params ?? {})) {
+    path = path.replaceAll(`{${name}}`, encodeURIComponent(value));
+  }
+  const unfilled = /\{([A-Za-z_][A-Za-z0-9_]*)\}/.exec(path);
+  if (unfilled !== null) {
+    // Fail closed rather than requesting a literal `{id}`: the server would 404 or, on a
+    // permissive route, hand back somebody else's bytes.
+    throw new Error(
+      `Download path "${target.path}" still contains the placeholder "${unfilled[0]}" — ` +
+        `pass it in \`params\` (e.g. params: { ${unfilled[1]}: row.id }).`,
+    );
+  }
+  const query = new URLSearchParams();
+  for (const [name, value] of Object.entries(target.query ?? {})) {
+    if (value !== undefined) {
+      query.append(name, value);
+    }
+  }
+  const suffix = query.toString();
+  return suffix.length > 0 ? `${path}?${suffix}` : path;
+}
+
+/**
+ * Download a generated artifact from an authorized endpoint (ADR 0096).
+ *
+ * ```tsx
+ * const download = useEndpointDownload();
+ * void download({
+ *   path: "/api/v1/revisions/{revisionId}/evidence",
+ *   params: { revisionId: revision.id },
+ *   filename: `revision-${revision.number}.json`,
+ * });
+ * ```
+ *
+ * Rejects on a non-2xx response, so a caller can surface the failure — a raw anchor would
+ * have saved the error body under the intended filename instead.
+ */
+export function useEndpointDownload(): (target: DownloadTarget) => Promise<void> {
+  const client = useTerpClient();
+  return useCallback(
+    async (target: DownloadTarget) => {
+      const blob = await fetchDownload(client as unknown as TerpClient, target);
+      saveBlob(blob, target.filename);
+    },
+    [client],
+  );
+}
+
+/**
+ * Fetch a download target's bytes through the session client.
+ *
+ * Separate from the hook so a caller that wants the blob for something *other* than
+ * saving it (a preview, a checksum) does not have to save it first.
+ */
+export async function fetchDownload(client: TerpClient, target: DownloadTarget): Promise<Blob> {
+  const url = downloadUrl(target);
+  const { data, error, response } = await (
+    client as unknown as {
+      GET: (
+        path: string,
+        init: { parseAs: "blob" },
+      ) => Promise<{ data?: unknown; error?: unknown; response: Response }>;
+    }
+  ).GET(url, { parseAs: "blob" });
+  if (error !== undefined || !response.ok) {
+    throw new Error(
+      `Download of ${url} failed with HTTP ${response.status}. The endpoint must be a GET ` +
+        "the current session is authorized for.",
+    );
+  }
+  return data as Blob;
+}

package/src/files.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useRef, useState } from "react";
 import type { ChangeEvent } from "react";
 
+import { saveBlob } from "./download";
 import { useTerpClient } from "./TerpProvider";
 import { Button } from "./ui/Button";
 import { useStrings, useUiText, type UiText } from "./uiText";
@@ -91,17 +92,7 @@ export function useFileDownload(): (file: Pick<FileMeta, "id" | "filename">) =>
   return useCallback(
     async (file: Pick<FileMeta, "id" | "filename">) => {
       const blob = await fetchFileContent(client as unknown as TerpClient, file.id);
-      const url = URL.createObjectURL(blob);
-      try {
-        const anchor = document.createElement("a");
-        anchor.href = url;
-        anchor.download = file.filename;
-        document.body.appendChild(anchor);
-        anchor.click();
-        anchor.remove();
-      } finally {
-        URL.revokeObjectURL(url);
-      }
+      saveBlob(blob, file.filename);
     },
     [client],
   );

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],
+  );
+}