@eifi1/ui-kit 0.51.7 → 0.53.0

package/src/lib/direction.ts

@@ -33,3 +33,42 @@ export function horizontalStep(key: string, el: Element | null | undefined): 1 |
   const forward = (key === "ArrowRight") !== isRtl(el);
   return forward ? 1 : -1;
 }
+
+/**
+ * Where a key moves the focus in a list with ONE tab stop (a roving tabindex): the index
+ * to focus from `at` among `count` items, or `undefined` for a key that moves nothing.
+ * ←/→ along `dir` — → is next in `ltr` and previous in `rtl` — ↓/↑ as next and previous,
+ * Home and End to the ends. With `wrap`, past the last is the first and before the first
+ * the last (a ring: PieChart's slices); without, the ends hold (a plane: Treemap's tiles).
+ *
+ * The charts each mapped the keys themselves, and differently at the ends (0.52 code
+ * review of treemap.tsx, finding 9); the end rule is now a word at the call.
+ *
+ * `dir` and not an element to read it off (0.52 code review, deep, charts, findings 1 and
+ * 14): a list in the page's flow takes the page's (`dirOf(el)`), but a plot is laid out
+ * left to right in any page (see `ChartContainer`) and passes `"ltr"` — read off the
+ * element, Treemap's → walked an RTL page's tiles backwards, against the picture.
+ */
+export function rovingTarget(
+  key: string,
+  dir: Direction,
+  at: number,
+  count: number,
+  wrap: boolean,
+): number | undefined {
+  const physical = key === "ArrowRight" ? 1 : key === "ArrowLeft" ? -1 : 0;
+  const step = dir === "rtl" ? -physical : physical;
+  const to = step
+    ? at + step
+    : key === "ArrowDown"
+      ? at + 1
+      : key === "ArrowUp"
+        ? at - 1
+        : key === "Home"
+          ? 0
+          : key === "End"
+            ? count - 1
+            : undefined;
+  if (to === undefined || count <= 0) return undefined;
+  return wrap ? ((to % count) + count) % count : Math.max(0, Math.min(count - 1, to));
+}

package/src/lib/focus-left.ts

@@ -0,0 +1,156 @@
+// "The focused node left" (refactor audit 2026-10-30, Wave 1: DSP-4, DSP-15). When the
+// element holding the keyboard's focus is removed — a table row deleted, filtered out or
+// approved; a bulk bar gone with its Clear; a banner its × took away — the browser puts
+// focus on <body> and says nothing: no blur in Chromium, none in jsdom. A keyboard or
+// screen-reader user then starts again from the top of the page. The overlays give focus
+// back to their opener (use-focus-trap); these helpers are for the controls that leave
+// the page while the focus is IN them, and decide where it goes instead.
+
+/**
+ * Candidate tab stops, in DOM order — narrowed by {@link isTabStop} to the ones a Tab
+ * really reaches. The kit's one copy of the rule (0.52 code review, lib/focus-left.ts):
+ * this file and use-focus-trap each had it, with an exported `firstTabStop` apiece that
+ * disagreed about the element itself, and a combobox panel's toolbar had a third
+ * selector. The trap, the focus a removed node drops (below), the tour's field ring and
+ * the toolbar all read it here, so "the next stop" is the same stop everywhere.
+ *
+ * The selector is the one `Modal` used. On its own it was not enough (round 0.34
+ * BUG-4): only the bare `[tabindex]` clause excluded `-1`, so a `button`, an `input` or
+ * a link taken out of the tab order still counted. A panel that ends in a roving grid —
+ * the calendar's days, the month grid, the picker sheet's rows, every one of them `-1`
+ * but the active cell — then had a "last" stop no Tab ever reaches: Tab from the real
+ * last stop was not wrapped and walked out of the open panel, and Shift+Tab from the
+ * first landed on a cell that is not a stop at all.
+ */
+// `input[type=hidden]` is no stop: a Tab never lands on it and focus() on it does nothing,
+// but its tabIndex reads 0, so a trap could take a form's hidden field for its first or last
+// stop and Shift+Tab left the dialog (0.52 code review).
+const TAB_STOP =
+  'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]):not([type="hidden"]),select:not([disabled]),[tabindex]:not([tabindex="-1"])';
+
+/**
+ * A stop the browser's own Tab would land on: in the tab order (`tabIndex` ≥ 0) and not
+ * inside something `hidden` or `inert`. Removes only elements a native Tab never
+ * reaches, so no correct order changes. `visibility: hidden` and closed `<details>` are
+ * still not walked — they need layout, which this rule has never read.
+ */
+function isTabStop(el: HTMLElement): boolean {
+  return el.tabIndex >= 0 && !el.closest("[hidden],[inert]");
+}
+
+export interface TabStopOptions {
+  /** Whether `el` itself counts, first, when it is a stop. Default true: the tour's
+   *  target may BE the field (refactor audit 2026-10-30, DUP-9). False for "a control
+   *  inside it" — a row, a drawer, a trap's container, a toolbar. */
+  includeSelf?: boolean;
+}
+
+/** The tab stops in `el`, in DOM order — `el` itself first when it is one, unless
+ *  `includeSelf: false`. */
+export function tabStops(el: Element, { includeSelf = true }: TabStopOptions = {}): HTMLElement[] {
+  const inside = Array.from(el.querySelectorAll<HTMLElement>(TAB_STOP)).filter(isTabStop);
+  const own = includeSelf && el instanceof HTMLElement && el.matches(TAB_STOP) && isTabStop(el);
+  return own ? [el, ...inside] : inside;
+}
+
+/** The first of {@link tabStops} — the control a person types into or presses — or null. */
+export function firstTabStop(el: Element, options?: TabStopOptions): HTMLElement | null {
+  return tabStops(el, options)[0] ?? null;
+}
+
+/**
+ * Whether the focus has fallen out of the page: onto `<body>`, onto nothing, or onto a
+ * node no longer in the document. False on the server, where nothing has focus to lose.
+ * A recovery asks this first: focus that went somewhere real (a dialog, the next field,
+ * an app's own `focus()`) is the user's or the app's, and is left where it is.
+ */
+export function focusIsLost(): boolean {
+  if (typeof document === "undefined") return false;
+  const el = document.activeElement;
+  return !el || el === document.body || !el.isConnected;
+}
+
+/**
+ * Calls `then` when a `blur`/`focusout` was the user's own move to nothing — a click on
+ * the page's background, or a click Safari answers by focusing nothing (it focuses no
+ * button or link on a click, and blurs what had the focus) — after which a note of where
+ * the focus was is stale (0.52 code review: DataTable's row, BulkActionBar's and
+ * AlertBanner's notes outlived it, and a removal much later pulled the focus, and the
+ * scroll, back to them).
+ *
+ * No element took the focus, the document holds none, and the node that lost it could
+ * still hold it. Not when it was removed, hidden, made inert or disabled: that is the page
+ * taking the focus away — the very case those notes are kept for. Not a window losing the
+ * focus either, which leaves the node the document's active element. Decided a microtask
+ * later, once the event's own work is done: a browser that blurs a node it is removing
+ * (or hiding) may do it while the node is still in place, and only after it is gone is
+ * that told apart from a click.
+ */
+export function whenFocusLeftForNothing(
+  e: { target: EventTarget | null; relatedTarget: EventTarget | null },
+  then: () => void,
+): void {
+  const el = e.target;
+  if (e.relatedTarget !== null || !(el instanceof Element)) return;
+  queueMicrotask(() => {
+    if (!el.isConnected || el.matches(":disabled") || el.closest("[hidden],[inert]")) return;
+    // `display: none`, where the browser can say (jsdom cannot).
+    if (typeof el.checkVisibility === "function" && !el.checkVisibility()) return;
+    if (focusIsLost()) then();
+  });
+}
+
+/**
+ * The tab stops around `frame`, outside it, nearest first on each side — where focus
+ * goes once `frame` is gone. Read BEFORE it goes: a removed node has no place in the
+ * document to measure from. `limit` per side keeps a long page's stops out of memory.
+ *
+ * Walked outwards from the frame, `limit` stops each way (0.52 code review,
+ * lib/focus-left.ts): read from every stop in the page, a banner under a 2000-row table
+ * read all 2000 to keep the nearest five before it.
+ */
+export function tabStopsAround(frame: Element, limit = 5): { after: HTMLElement[]; before: HTMLElement[] } {
+  const doc = frame.ownerDocument;
+  const walker = doc.createTreeWalker(doc.documentElement, NodeFilter.SHOW_ELEMENT);
+  const isStop = (node: Node): node is HTMLElement =>
+    node instanceof HTMLElement && node.matches(TAB_STOP) && isTabStop(node);
+  // After: from the first element past the frame's own subtree, in document order.
+  const after: HTMLElement[] = [];
+  walker.currentNode = frame;
+  let node: Node | null = walker.nextSibling();
+  while (!node && walker.parentNode()) node = walker.nextSibling();
+  for (; node && after.length < limit; node = walker.nextNode()) if (isStop(node)) after.push(node);
+  // Before: back from the frame, nearest first (its ancestors among them, as before).
+  const before: HTMLElement[] = [];
+  walker.currentNode = frame;
+  for (node = walker.previousNode(); node && before.length < limit; node = walker.previousNode())
+    if (isStop(node)) before.push(node);
+  return { after, before };
+}
+
+/**
+ * Focus the first of `candidates` that is still in the page and takes the focus; true
+ * when one did. Each is tried and checked, since `focus()` on a node that cannot hold it
+ * (detached, `display: none`, disabled since) fails without a word.
+ */
+export function focusFirst(candidates: Iterable<Element | null | undefined>): boolean {
+  for (const el of candidates) {
+    if (!(el instanceof HTMLElement) || !el.isConnected) continue;
+    el.focus();
+    if (document.activeElement === el) return true;
+  }
+  return false;
+}
+
+/**
+ * Focus a container that is not a tab stop of its own — a table, a list — as the place
+ * the user is in, without making it one: `tabindex="-1"` for as long as it holds the
+ * focus, unless it already carries a `tabindex` of its own.
+ */
+export function focusContainer(el: HTMLElement): void {
+  if (!el.hasAttribute("tabindex")) {
+    el.setAttribute("tabindex", "-1");
+    el.addEventListener("blur", () => el.removeAttribute("tabindex"), { once: true });
+  }
+  el.focus();
+}

package/src/lib/format.ts

@@ -1,6 +1,8 @@
 import { useMemo } from "react";
 import { useKitLocale, useKitTimeZone } from "../i18n/kit-labels";
 import { parseIsoDate } from "./dates";
+import { dateFormatter } from "./intl-cache";
+import { isBareIsoDay } from "./iso-day";
 import { formatWithMinus, type MinusStyle } from "./minus";
 import { roundHalfAway } from "./round";
 
@@ -278,9 +280,6 @@ export interface FormatDateOptions extends BaseOptions {
   timeZone?: string;
 }
 
-/** A bare ISO calendar day, `"YYYY-MM-DD"`. */
-const BARE_ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
-
 /** What {@link formatDate} and {@link formatRelativeTime} accept. */
 export type DateInput = string | number | Date | null | undefined;
 
@@ -292,22 +291,11 @@ export type DateInput = string | number | Date | null | undefined;
  */
 export function toDate(value: DateInput): Date | null {
   if (value === null || value === undefined || value === "") return null;
-  if (typeof value === "string" && BARE_ISO_DAY.test(value)) return parseIsoDate(value);
+  if (isBareIsoDay(value)) return parseIsoDate(value);
   const d = value instanceof Date ? value : new Date(value);
   return Number.isNaN(d.getTime()) ? null : d;
 }
 
-const dateFormatters = new Map<string, Intl.DateTimeFormat>();
-function dateFormatter(locale: string | undefined, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
-  const key = `${locale ?? ""}|${JSON.stringify(options)}`;
-  let f = dateFormatters.get(key);
-  if (!f) {
-    f = new Intl.DateTimeFormat(locale, options);
-    dateFormatters.set(key, f);
-  }
-  return f;
-}
-
 /**
  * A date or timestamp in `locale`. Takes an ISO date ("2026-07-08", read on the local
  * calendar), an ISO timestamp ("2026-07-08T14:05:00Z"), epoch milliseconds or a Date.
@@ -327,7 +315,7 @@ export function formatDate(
   // A bare "YYYY-MM-DD" is a calendar day, which has no zone: it is the day it names
   // wherever it is read, so a `timeZone` (in `options` or the style) never moves it — the
   // device's local midnight shown in a zone west of it was the day before (round 0.45, N9).
-  if (typeof value === "string" && BARE_ISO_DAY.test(value)) {
+  if (isBareIsoDay(value)) {
     const day = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
     return dateFormatter(options.locale, { ...base, timeZone: "UTC" }).format(day);
   }
@@ -425,7 +413,7 @@ export function formatRelativeTime(value: DateInput, options: FormatRelativeTime
     // tooltip) that said otherwise. Counted in `timeZone`, the zone that date is printed
     // in; a bare "YYYY-MM-DD" is the day it names wherever it is read, as in formatDate.
     // Still the same day (22 hours and more since just after midnight): in hours.
-    const bareDay = typeof value === "string" && BARE_ISO_DAY.test(value);
+    const bareDay = isBareIsoDay(value);
     const days = dayNumber(d, bareDay ? undefined : options.timeZone) - dayNumber(now, options.timeZone);
     return days === 0 ? rtf.format(Math.round(diff / HOUR), "hour") : rtf.format(days, "day");
   }

package/src/lib/http-status.ts

@@ -0,0 +1,38 @@
+/**
+ * The HTTP status of a thrown error, as one probe (DUP-11, refactor audit 2026-10: the
+ * session refresh carried its own copy).
+ *
+ * It lived in `auth/auth-errors.ts` until 0.52, which made `lib/session-refresh` and
+ * `/sync`'s engine import the auth folder — and put auth's English error words in the
+ * `/sync` entry's closure — for a three-line reader of `status` (refactor audit
+ * 2026-10-30, MOD-6). `auth-errors.ts` re-exports it, so nothing that imported it there
+ * moved.
+ *
+ * @internal Package-private — not re-exported from the barrel.
+ */
+
+type Bag = Record<string, unknown>;
+
+const isBag = (value: unknown): value is Bag => typeof value === "object" && value !== null;
+
+/** An HTTP status as a number, or undefined. */
+function statusOf(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isInteger(value) ? value : undefined;
+}
+
+/**
+ * The HTTP status a thrown error carries, wherever the apps' HTTP clients put it —
+ * without depending on any of them:
+ *
+ *  1. `err.response.status` — axios (all three apps' clients);
+ *  2. `err.status` — ofetch's `FetchError`, the generated OpenAPI clients' `ApiError`, and
+ *     a `Response` thrown as it came;
+ *  3. `err.statusCode` — ofetch's alias, and Node-style errors.
+ *
+ * `undefined` when none is a whole number.
+ */
+export function httpStatusOf(err: unknown): number | undefined {
+  if (!isBag(err)) return undefined;
+  const response = err.response;
+  return (isBag(response) ? statusOf(response.status) : undefined) ?? statusOf(err.status) ?? statusOf(err.statusCode);
+}

package/src/lib/intl-cache.ts

@@ -0,0 +1,25 @@
+/**
+ * One `Intl.DateTimeFormat` per locale and option set, for every date the kit prints.
+ *
+ * Constructing the formatter is the expensive part: keksdose measured 392 ms per click on
+ * a 270-row register when each cell built its own (dev#632), and kept its own renderer of
+ * the date-format preference because the kit's built one per call (refactor audit
+ * 2026-10-30, DUP-2). `lib/format` and `lib/date-format` both format through this one.
+ *
+ * @internal Not part of the barrel — `lib/format` is re-exported whole, so the cache
+ * lives apart from it.
+ */
+
+const dateFormatters = new Map<string, Intl.DateTimeFormat>();
+
+/** The cached formatter for `locale` and `options`. Throws as `Intl.DateTimeFormat` does
+ *  for a tag it refuses — and caches nothing then. */
+export function dateFormatter(locale: string | undefined, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  const key = `${locale ?? ""}|${JSON.stringify(options)}`;
+  let f = dateFormatters.get(key);
+  if (!f) {
+    f = new Intl.DateTimeFormat(locale, options);
+    dateFormatters.set(key, f);
+  }
+  return f;
+}

package/src/lib/iso-day.ts

@@ -0,0 +1,13 @@
+/**
+ * The bare ISO calendar day, `"YYYY-MM-DD"` — no time, no zone: the day it names in every
+ * zone. `toDate` and `formatDate` (lib/format), the kit's day ladder (`useDayFormatter`,
+ * lib/day-format) and the preference's renderers (lib/date-format) each kept a copy of this
+ * pattern (0.52 code review, lib/day-format.ts). Were one to learn a new shape (say
+ * `YYYY-MM-DDT00:00`) alone, the ladder would ask the provider for a different day than the
+ * kit prints. One rule.
+ *
+ * @internal Not part of the barrel: `lib/format` is re-exported whole, so it lives apart.
+ */
+export function isBareIsoDay(value: unknown): value is string {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value);
+}

package/src/lib/lazy-with-fallback.ts

@@ -0,0 +1,82 @@
+import { createContext, createElement, lazy, useCallback, useContext, useLayoutEffect, useState } from "react";
+import type { ComponentType, LazyExoticComponent } from "react";
+
+/** What a {@link lazyWithFallback} fallback is given besides the component's own props. */
+export interface LazyFallbackProps {
+  /** What the import rejected with. Already on `console.error`. */
+  error: unknown;
+  /** Fetch the module again and draw it here if it comes (back online, the deploy's
+   *  new chunk). Call it on the person's next attempt, never at once: offline, a retry
+   *  on mount would fetch in a loop. */
+  retry: () => void;
+}
+
+interface Attempt<P> {
+  Component: LazyExoticComponent<ComponentType<P>>;
+  /** Its import failed and its fallback was drawn: the next mount, or `retry`, takes a
+   *  fresh attempt. Marked when the fallback COMMITS, not when the import rejects: a
+   *  first mount that suspended is thrown away and rendered anew, and an attempt marked
+   *  at the rejection would hand that re-render a fresh import — which fails, and so on. */
+  spent: boolean;
+}
+
+const RetryContext = createContext<() => void>(() => {});
+
+/**
+ * `React.lazy` for a module the kit loads late (refactor audit 2026-10, MOD-1: the tour
+ * overlay, the search palette, the feedback dialog), where an import that fails — a tab
+ * left open across a deploy, a local-first app offline — draws `Fallback` instead of
+ * throwing.
+ *
+ * `React.lazy` keeps what its import settled to, so one failed fetch threw on every render
+ * for as long as the component stayed mounted, to the nearest error boundary. All three
+ * sit above the routes — in the provider every app mounts, in the top bar — where that
+ * boundary is the whole app's: a white page because somebody pressed ⌘K or "Take the
+ * tour" (0.52 code review, tour.tsx: the tour's own fix, written by hand with a module-level
+ * `let`, made shared here).
+ *
+ * A failure is logged and the next mount (or the fallback's `retry`) fetches again; a
+ * re-render of a mounted fallback does not. `load` resolves to the component itself,
+ * through a LITERAL relative dynamic import of its module (as feedback-submit's), so an
+ * app's bundler can split it off. Render the result under a `Suspense`, as a lazy
+ * component. (No import call is spelled out here: the build's fix-esm-extensions step
+ * reads specifiers in the .d.ts comments too, and would try to resolve an example.)
+ */
+export function lazyWithFallback<P extends object>(
+  load: () => Promise<ComponentType<P>>,
+  Fallback: ComponentType<P & LazyFallbackProps>,
+): ComponentType<P> {
+  const attempt = (): Attempt<P> => {
+    const made: Attempt<P> = {
+      spent: false,
+      Component: lazy<ComponentType<P>>(() =>
+        load().then(
+          (Loaded) => ({ default: Loaded }),
+          (error: unknown) => {
+            console.error(error);
+            function Failed(props: P) {
+              const retry = useContext(RetryContext);
+              useLayoutEffect(() => {
+                made.spent = true;
+              }, []);
+              return createElement(Fallback, { ...props, error, retry });
+            }
+            return { default: Failed };
+          },
+        ),
+      ),
+    };
+    return made;
+  };
+  let latest = attempt();
+  /** The attempt a new mount takes: the latest, or a fresh one once that has failed. */
+  const take = () => (latest.spent ? (latest = attempt()) : latest);
+
+  function LazyWithFallback(props: P) {
+    // Fixed per mount, so a re-render of a mounted fallback fetches nothing.
+    const [current, setCurrent] = useState(take);
+    const retry = useCallback(() => setCurrent(take), []);
+    return createElement(RetryContext.Provider, { value: retry }, createElement(current.Component, props));
+  }
+  return LazyWithFallback;
+}

package/src/lib/path-pattern.ts

@@ -0,0 +1,55 @@
+/**
+ * Whether a pathname is one a `PathPattern` names — the rule `useLastVisitedPage`'s
+ * `exclude` reads (landing/routing.tsx) and the feedback guard's one-shot routes
+ * (refactor audit 2026-10-30, FLW-7), here without the router: `landing/routing` imports
+ * react-router, which `/feedback` must not drag in. The one copy: routing kept a private
+ * one, and the two had drifted within the round (0.52 code review, this file).
+ *
+ * A string is that path and everything under it (`/join` is `/join` and `/join/abc`, not
+ * `/joined`; `/` is only `/`); a RegExp is tested on the pathname (a `g` flag dropped, so
+ * `lastIndex` never carries over between calls).
+ *
+ * Case-INSENSITIVE, as React Router matches a route unless it sets `caseSensitive` (0.52
+ * code review, feedback/feedback-page-link.ts): the FLW-7 guard compared case-sensitively,
+ * and `/Join?token=` went out as a link the router still rendered as `/join`. A RegExp
+ * gets the `i` flag for the same reason. Matching more than a case-sensitive route would
+ * only turns a link into text, or leaves a page unrecorded as a resume target: both
+ * callers' safe side.
+ *
+ * @internal Package-private — not re-exported from the barrel.
+ */
+export function matchesPathPattern(pathname: string, pattern: string | RegExp): boolean {
+  if (typeof pattern !== "string") {
+    return new RegExp(pattern.source, `${pattern.flags.replace(/[gi]/g, "")}i`).test(pathname);
+  }
+  const path = pathname.toLowerCase();
+  if (pattern === "/") return path === "/";
+  const base = (pattern.endsWith("/") ? pattern.slice(0, -1) : pattern).toLowerCase();
+  return path === base || path.startsWith(`${base}/`);
+}
+
+/**
+ * The pathname of `href` (a path with its query and hash) as React Router matches it:
+ * each segment percent-decoded, an encoded `/` kept as `%2F` so it never splits a segment
+ * (react-router 8, `decodePath` in `matchRoutesImpl`). The 0.52 code review
+ * (feedback/feedback-page-link.ts) found `/j%6Fin?token=` passing the FLW-7 guard as a
+ * link that the router decoded to `/join`.
+ *
+ * A malformed escape leaves its own segment as written, where the router gives up on the
+ * whole path: the rest still decodes, so the answer is never less than the router's.
+ *
+ * @internal Package-private — not re-exported from the barrel.
+ */
+export function routerPathname(href: string): string {
+  return href
+    .replace(/[?#].*$/, "")
+    .split("/")
+    .map((segment) => {
+      try {
+        return decodeURIComponent(segment).replace(/\//g, "%2F");
+      } catch {
+        return segment;
+      }
+    })
+    .join("/");
+}

package/src/lib/reduced-motion.ts

@@ -13,7 +13,8 @@
  * screen only delays its `onClose` — every test suite, the kit's and the apps', reads a
  * closed overlay as gone at once.
  *
- * Package-private — not re-exported from the barrel.
+ * Public since 0.52 (DUP-8, refactor audit 2026-10-30): Kurvenschmiede's chain animation
+ * carried a copy of its own.
  */
 export function prefersReducedMotion(whereUnknown = false): boolean {
   if (typeof window === "undefined" || typeof window.matchMedia !== "function") return whereUnknown;

package/src/lib/round.ts

@@ -25,14 +25,19 @@ function shiftDecimal(value: number, by: number): number {
  * `n` rounded to `digits` decimals, half away from zero, in decimal arithmetic:
  * 1.005 → 1.01, -2.5 at 0 → -3. Never NaN for a finite `n`, and never -0 — `formatMoney`
  * prints -0 as "-0,00 €", so a negative that rounds away comes back as 0. A non-finite
- * `n` comes back unchanged.
+ * `n` comes back unchanged. `digits` counts in whole decimals, as `toFixed` takes it: 2.5
+ * is 2, and NaN is 0.
  */
 export function roundHalfAway(n: number, digits: number): number {
   if (!Number.isFinite(n)) return n;
+  // "1.2345e2.5" is NaN, and `|| 0` below made it 0: MeasuredGrid's `digits`, which went to
+  // `toFixed` before DUP-14 brought it here, wrote every computed cell of a table with a
+  // fractional one as "0" (0.52 code review, deep, charts, finding 5).
+  const places = Math.trunc(digits) || 0;
   const abs = Math.abs(n);
   // Every double from 2^53 up is a whole number already, and scaling one near
   // Number.MAX_VALUE up would overflow to Infinity.
-  const magnitude = abs >= 2 ** 53 ? abs : shiftDecimal(Math.round(shiftDecimal(abs, digits)), -digits);
+  const magnitude = abs >= 2 ** 53 ? abs : shiftDecimal(Math.round(shiftDecimal(abs, places)), -places);
   // The sign goes back on after rounding, so `|| 0` must see the signed result.
   return (n < 0 ? -magnitude : magnitude) || 0;
 }

package/src/lib/safe-storage.ts

@@ -16,8 +16,13 @@
  *
  * Since 0.34 (DUP-11, refactor audit 2026-10) it also removes, and guards
  * `sessionStorage` the same way: `landing/routing`, `billing/checkout-processing` and
- * the demo banner each wrote that guard again by hand. `removeStored` and the session
- * pair are package-private — the barrel exports `readStored` / `writeStored` only.
+ * the demo banner each wrote that guard again by hand.
+ *
+ * Since 0.52 all of it but {@link storedKeys} is public, with a JSON pair beside it
+ * (DUP-8, refactor audit 2026-10-30). Kept package-private, the guard was written again
+ * four times in the kit's showcase and in 16 files across the three apps, some of them
+ * without it: a token read that throws where storage is blocked takes every request
+ * down with it. (The kit's own DevMenu, 0.51, wrote the session pair a second time too.)
  */
 
 /** `access` on the storage area, or `fallback` where there is none (SSR) or it throws. */
@@ -37,9 +42,13 @@ export function readStored(key: string): string | null {
 }
 
 /** Store `value` under `key`, silently doing nothing when storage is unavailable
- *  or full. A preference that cannot be persisted is not worth an exception. */
-export function writeStored(key: string, value: string): void {
-  guarded("localStorage", undefined, (storage) => storage.setItem(key, value));
+ *  or full. A preference that cannot be persisted is not worth an exception. `null`
+ *  removes the key, as {@link writeSessionStored}'s does (0.52; the two pairs wrote
+ *  differently, and `null` past the types stored the string "null" — 0.52 code review). */
+export function writeStored(key: string, value: string | null): void {
+  guarded("localStorage", undefined, (storage) =>
+    value === null ? storage.removeItem(key) : storage.setItem(key, value),
+  );
 }
 
 /** Forget `key`, silently doing nothing when storage is blocked — there is nothing to
@@ -60,10 +69,43 @@ export function writeSessionStored(key: string, value: string | null): void {
   );
 }
 
+/**
+ * The JSON stored under `key`, when it parses and `isShape` accepts it; else `null`. Absent,
+ * blocked, malformed and another shape all read as "never set" — the caller's default —
+ * which is what the six hand-written `JSON.parse(readStored(key))` reads in the kit each
+ * answered in their own try/catch (DUP-8). `isShape` gets the parsed value as `unknown`:
+ * the shape check is the one part that is the caller's. A shape check that throws reads
+ * as another shape: null.
+ */
+export function readStoredJson<T>(key: string, isShape: (value: unknown) => value is T): T | null {
+  const text = readStored(key);
+  if (text === null) return null;
+  try {
+    const value: unknown = JSON.parse(text);
+    return isShape(value) ? value : null;
+  } catch {
+    // not JSON, or a shape check that read past what is there
+    return null;
+  }
+}
+
+/** Store `value` as JSON under `key`, silently doing nothing when storage is unavailable
+ *  or full, or the value has no JSON form (a cycle, a BigInt) — {@link writeStored}'s rule. */
+export function writeStoredJson(key: string, value: unknown): void {
+  let text: string | undefined;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    return;
+  }
+  // `undefined` (and a function) has no JSON form either: stringify answers undefined.
+  if (text !== undefined) writeStored(key, text);
+}
+
 /**
  * Every key in `area` that starts with `prefix`, or `[]` where storage refuses — for the
  * reset of this device's settings, which removes a table's views by their prefix
- * (docs/settings-harmonization.md §11.4). Package-private, like {@link removeStored}.
+ * (docs/settings-harmonization.md §11.4). Package-private: the reset's alone.
  */
 export function storedKeys(prefix: string, area: "local" | "session" = "local"): string[] {
   return guarded(area === "session" ? "sessionStorage" : "localStorage", [], (storage) => {

package/src/lib/session-refresh.ts

@@ -36,7 +36,7 @@
  */
 
 import type { AxiosLikeInstance, ServerWakeAxiosConfig } from "./server-wake";
-import { httpStatusOf } from "../auth/auth-errors";
+import { httpStatusOf } from "./http-status";
 
 /** What the app's `refresh` resolves: the new access token, plus whatever its `store`
  *  needs (its refresh token, the user). */

package/src/lib/share-format.ts

@@ -0,0 +1,18 @@
+/**
+ * How a chart says a share of its whole — PieChart's slices and centre, Treemap's tiles
+ * and groups. Internal, not exported from the barrel.
+ *
+ * Each chart held a copy of the same two `Intl` formats and the same switch between them
+ * (0.52 code review of treemap.tsx, finding 9); one copy is the rule both say.
+ */
+
+/**
+ * A formatter for shares (0–1) in `locale`, as a percent: one decimal under 10 %, where
+ * rounding to whole percents starts to lie — a slice of 0.4 % said as "0%" says it is not
+ * there — and whole percents above. Make it once per locale (it builds two `Intl` formats).
+ */
+export function shareFormat(locale: string | undefined): (share: number) => string {
+  const whole = new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 0 });
+  const fine = new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 1 });
+  return (share) => (share < 0.1 ? fine : whole).format(share);
+}

package/src/lib/text-case.ts

@@ -0,0 +1,19 @@
+/**
+ * Upper-case the first letter only, in `locale` — the one copy of the rule (refactor audit
+ * 2026-10-30, DUP-11: MonthPicker and JumpCalendar each had it, and MiniCalendar's caption
+ * still used the CSS `capitalize` it was written against).
+ *
+ * Several locales (fr, es, it, pt, …) write month names in lower case, which at the head
+ * of a field or a panel reads as a typo. But only the FIRST letter is ours to change:
+ * `capitalize` upper-cases every word, so Spanish read "Septiembre De 2026", and a
+ * caption that does not start with the month kept its wrong capital — Hungarian read
+ * "2026. Szeptember". This gives "Septiembre de 2026" and "2026. szeptember".
+ *
+ * In `locale` because the case mapping is the language's: Turkish upper-cases "i" to "İ".
+ * `undefined` is the runtime's default, as everywhere `Intl` takes one.
+ *
+ * Package-private — not re-exported from the barrel.
+ */
+export function upperFirst(text: string, locale: string | undefined): string {
+  return text.charAt(0).toLocaleUpperCase(locale) + text.slice(1);
+}