@eifi1/ui-kit 0.11.0 → 0.12.0

package/src/hooks/use-hotkey.ts

@@ -0,0 +1,172 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * A key combination: modifiers and one key, joined by "+", case-insensitive —
+ * `"Ctrl+Shift+F"`, `"Mod+K"`, `"Alt+ArrowUp"`, `"Escape"`, `"?"`.
+ *
+ * Modifiers: `Ctrl` (`Control`), `Meta` (`Cmd`, `Command`), `Shift`, `Alt` (`Option`),
+ * and `Mod` — Cmd on Apple platforms, Ctrl everywhere else, the one to use for an
+ * app shortcut. The key is `KeyboardEvent.key` ("f", "Enter", "ArrowUp", "/"), or a
+ * `KeyboardEvent.code` ("KeyF", "Digit1") when the physical key is what matters.
+ * Several combos: pass an array.
+ */
+export type Hotkey = string;
+
+export interface UseHotkeyOptions {
+  /** Off while `false` (default `true`). */
+  enabled?: boolean;
+  /** Call `preventDefault()` on a match (default `true`): Ctrl+Shift+F must not also
+   *  open the browser's own dialog. */
+  preventDefault?: boolean;
+  /** Where to listen. Default `document`. A ref, an element, or `window`. */
+  target?: EventTarget | null | { current: EventTarget | null };
+  /**
+   * Fire while the focus is in a text field, select or contenteditable too. Default
+   * `false`: a shortcut must not steal the letters someone is typing. A combo with Ctrl,
+   * Meta or Alt is not typing — those still fire unless this is `"never"`.
+   */
+  allowInInputs?: boolean | "never";
+  /** `keydown` (default) or `keyup`. */
+  event?: "keydown" | "keyup";
+}
+
+export interface ParsedHotkey {
+  ctrl: boolean;
+  meta: boolean;
+  shift: boolean;
+  alt: boolean;
+  key: string;
+}
+
+/** Whether this is an Apple platform, where `Mod` means Cmd. */
+export function isApplePlatform(): boolean {
+  if (typeof navigator === "undefined") return false;
+  const nav = navigator as Navigator & { userAgentData?: { platform?: string } };
+  return /mac|iphone|ipad|ipod/i.test(nav.userAgentData?.platform || nav.platform || nav.userAgent);
+}
+
+/** Parse one combo. `apple` decides what `Mod` is. Throws on an empty key. */
+export function parseHotkey(combo: Hotkey, apple = isApplePlatform()): ParsedHotkey {
+  const parts = combo
+    .split("+")
+    .map((p) => p.trim())
+    // "Ctrl++" is Ctrl and "+": an empty part after a "+" is the plus key itself.
+    .map((p, i, all) => (p === "" && i === all.length - 1 ? "+" : p))
+    .filter((p) => p !== "");
+  const out: ParsedHotkey = { ctrl: false, meta: false, shift: false, alt: false, key: "" };
+  for (const part of parts) {
+    switch (part.toLowerCase()) {
+      case "ctrl":
+      case "control":
+        out.ctrl = true;
+        break;
+      case "meta":
+      case "cmd":
+      case "command":
+        out.meta = true;
+        break;
+      case "mod":
+        if (apple) out.meta = true;
+        else out.ctrl = true;
+        break;
+      case "shift":
+        out.shift = true;
+        break;
+      case "alt":
+      case "option":
+        out.alt = true;
+        break;
+      default:
+        out.key = part;
+    }
+  }
+  if (!out.key) throw new Error(`useHotkey: "${combo}" names no key`);
+  return out;
+}
+
+const KEY_ALIASES: Record<string, string> = {
+  esc: "escape",
+  space: " ",
+  del: "delete",
+  up: "arrowup",
+  down: "arrowdown",
+  left: "arrowleft",
+  right: "arrowright",
+};
+
+/** Whether `e` is `combo` — every modifier as named (no more, no fewer), and the key. */
+export function matchesHotkey(e: KeyboardEvent, combo: ParsedHotkey): boolean {
+  if (e.ctrlKey !== combo.ctrl || e.metaKey !== combo.meta || e.altKey !== combo.alt) return false;
+  const want = KEY_ALIASES[combo.key.toLowerCase()] ?? combo.key.toLowerCase();
+  const key = (e.key ?? "").toLowerCase();
+  const code = (e.code ?? "").toLowerCase();
+  const keyMatches = key === want || code === want;
+  if (!keyMatches) return false;
+  // Shift must match exactly for a letter or a named key; for a symbol it is how the
+  // symbol is typed ("?" is Shift+/ on a US layout, a plain key on others), so an
+  // unnamed Shift is not held against it.
+  const symbol = want.length === 1 && !/[a-z0-9]/.test(want);
+  return symbol && !combo.shift ? true : e.shiftKey === combo.shift;
+}
+
+/** Is the focus somewhere that takes typed characters? */
+function isTypingTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  if (target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) return true;
+  if (target instanceof HTMLInputElement) {
+    return !["button", "checkbox", "radio", "submit", "reset", "range", "color", "file", "image"].includes(target.type);
+  }
+  return false;
+}
+
+/**
+ * Call `handler` when `combo` is pressed — kastlan's feedback button (Ctrl+Shift+F,
+ * feedback-button:60) wired it by hand, and so will every next shortcut.
+ *
+ * - `Mod` is Cmd on a Mac and Ctrl elsewhere, read once per mount.
+ * - Modifiers match EXACTLY: `"Ctrl+K"` does not fire on Ctrl+Shift+K.
+ * - Typing in a field is left alone unless `allowInInputs`, except for a combo with
+ *   Ctrl / Meta / Alt, which no one types as text.
+ * - A key held down fires once, not on every repeat.
+ * - The newest `handler` is always called; changing it does not re-attach the listener.
+ *
+ * `useCommandKey` (the ⌘K palette hook) is unchanged; this is its general form.
+ */
+export function useHotkey(
+  combo: Hotkey | ReadonlyArray<Hotkey>,
+  handler: (event: KeyboardEvent) => void,
+  options: UseHotkeyOptions = {},
+): void {
+  const { enabled = true, preventDefault = true, target, allowInInputs = false, event = "keydown" } = options;
+  const handlerRef = useRef(handler);
+  useEffect(() => {
+    handlerRef.current = handler;
+  });
+  const key = typeof combo === "string" ? combo : combo.join("\u0000");
+  const targetEl = target && "current" in target ? undefined : target;
+  const targetRef = target && "current" in target ? target : undefined;
+
+  useEffect(() => {
+    if (!enabled) return;
+    const node: EventTarget | null =
+      targetRef?.current ?? targetEl ?? (typeof document === "undefined" ? null : document);
+    if (!node) return;
+    const apple = isApplePlatform();
+    const parsed = key.split("\u0000").map((c) => parseHotkey(c, apple));
+    const listener = (raw: Event) => {
+      const e = raw as KeyboardEvent;
+      if (e.repeat) return;
+      const hit = parsed.find((p) => matchesHotkey(e, p));
+      if (!hit) return;
+      if (allowInInputs !== true && isTypingTarget(e.target)) {
+        const chorded = hit.ctrl || hit.meta || hit.alt;
+        if (allowInInputs === "never" || !chorded) return;
+      }
+      if (preventDefault) e.preventDefault();
+      handlerRef.current(e);
+    };
+    node.addEventListener(event, listener);
+    return () => node.removeEventListener(event, listener);
+  }, [key, enabled, preventDefault, allowInInputs, event, targetEl, targetRef]);
+}

package/src/hooks/use-search-param-state.ts

@@ -0,0 +1,187 @@
+import { useLocation, useNavigate, useSearchParams } from "react-router";
+
+type Updater<T> = T | ((prev: T) => T);
+
+export interface SearchParamStateOptions<T> {
+  /**
+   * The value of a param that IS present. Return `undefined` (or throw) for a value
+   * that does not parse — a hand-edited or stale link — and the default is used.
+   * Default: the raw string.
+   */
+  parse?: (raw: string) => T | undefined;
+  /**
+   * The param for a value, or `null` to remove it. Default: `String(value)`, and
+   * `null` for `null` / `undefined`. A value that serialises the same as the default
+   * removes the param too, so the default is always the clean URL.
+   */
+  serialize?: (value: T) => string | null;
+  /** Shorthand for `history: "replace"`. */
+  replace?: boolean;
+  /**
+   * What a change does to the browser history:
+   *  - `"push"` (default): a new entry, so Back undoes the change.
+   *  - `"replace"`: the current entry is rewritten — a tab, a sort, a view toggle,
+   *    which are not steps anyone wants Back to walk through.
+   *  - `"replace-on-clear"`: push when a value is set, replace when it is cleared (the
+   *    "open a form, close it" pattern).
+   */
+  history?: "push" | "replace" | "replace-on-clear";
+}
+
+const defaultSerialize = (value: unknown): string | null =>
+  value === null || value === undefined ? null : String(value);
+
+/** The route state of the current entry, carried over a `replace` so a query rewrite
+ *  does not drop what a navigation put there (a dialog's opener mark, below). */
+function carriedState(state: unknown): Record<string, unknown> | undefined {
+  return state && typeof state === "object" ? (state as Record<string, unknown>) : undefined;
+}
+
+/**
+ * One URL search param as React state: `const [view, setView] = useSearchParamState("view", "list")`.
+ *
+ * Replaces the hand-rolled `setParams((prev) => { const p = new URLSearchParams(prev);
+ * …set/delete…; return p })` blocks that keksdose had in a dozen pages and kastlan ported
+ * as its own copy of this hook (shared/hooks/use-search-param-state.ts, both apps). The
+ * kit's version takes the DEFAULT as an argument rather than inside `parse`, so the
+ * two rules that follow from it cannot be forgotten at a call site:
+ *
+ * * an absent or unparseable param reads as the default, and
+ * * setting the default removes the param — the default view is the clean URL.
+ *
+ * Every other param in the query string is left as it is. Two updates in one tick do
+ * not compose — react-router resolves each against the params of the last render.
+ * Requires a react-router Router.
+ */
+export function useSearchParamState<T = string>(
+  key: string,
+  defaultValue: T,
+  options: SearchParamStateOptions<T> = {},
+): [T, (next: Updater<T>) => void] {
+  const { parse, serialize = defaultSerialize as (value: T) => string | null } = options;
+  const history = options.history ?? (options.replace ? "replace" : "push");
+  const [params, setParams] = useSearchParams();
+  const location = useLocation();
+
+  const read = (raw: string | null): T => {
+    if (raw === null) return defaultValue;
+    if (!parse) return raw as unknown as T;
+    try {
+      const parsed = parse(raw);
+      return parsed === undefined ? defaultValue : parsed;
+    } catch {
+      return defaultValue;
+    }
+  };
+  const value = read(params.get(key));
+  const defaultSerialized = serialize(defaultValue);
+  const toParam = (v: T): string | null => {
+    const s = serialize(v);
+    return s === defaultSerialized ? null : s;
+  };
+
+  const setValue = (next: Updater<T>) => {
+    // Resolved against the rendered value only to choose the history mode; the write
+    // resolves again inside react-router's updater, against the params it hands over.
+    const preview = typeof next === "function" ? (next as (prev: T) => T)(value) : next;
+    const replace = history === "replace" || (history === "replace-on-clear" && toParam(preview) === null);
+    setParams(
+      (prev) => {
+        const p = new URLSearchParams(prev);
+        const resolved = typeof next === "function" ? (next as (prev: T) => T)(read(p.get(key))) : next;
+        const serialized = toParam(resolved);
+        if (serialized === null) p.delete(key);
+        else p.set(key, serialized);
+        return p;
+      },
+      replace ? { replace, state: carriedState(location.state) } : undefined,
+    );
+  };
+
+  return [value, setValue];
+}
+
+/**
+ * The active tab in `?tab=` (or `key`), with the default tab as the clean URL, for the
+ * kit's `Tabs`:
+ *
+ *     const [tab, setTab] = useTabParam("overview", { tabs: ["overview", "history"] });
+ *     <Tabs tabs={…} active={tab} onChange={setTab} />
+ *
+ * Switching tabs REPLACES the history entry — a tab is a view of this page, not a
+ * place Back should step through. `tabs`, when given, turns a param naming no tab (a
+ * renamed tab, an old link) into the default rather than into a blank panel.
+ * kastlan's use-tab-param.ts, with the validation it did not have.
+ */
+export function useTabParam<T extends string>(
+  defaultTab: T,
+  options: { key?: string; tabs?: readonly T[] } = {},
+): [T, (tab: T) => void] {
+  const { key = "tab", tabs } = options;
+  return useSearchParamState<T>(key, defaultTab, {
+    parse: (raw) => (!tabs || (tabs as readonly string[]).includes(raw) ? (raw as T) : undefined),
+    history: "replace",
+  });
+}
+
+/** Where a dialog's open state lives: a param's presence (`"edit"` → `?edit=1`), or one
+ *  value of a shared param (`{ key: "dialog", value: "create-lease" }`). */
+export type DialogParam = string | { key: string; value: string };
+
+/** The route-state mark an opener leaves on the entry it pushes, so the close knows it
+ *  may go BACK over it rather than add a second entry. */
+const OPENED_BY_KIT = "__uiKitDialogParam";
+
+/**
+ * A dialog's open state in the URL, for `Modal`'s `urlParam` and anything else that
+ * opens one: `const [open, setOpen] = useDialogParam({ key: "dialog", value: "create" })`.
+ *
+ * * **Opening pushes** an entry, so the platform Back gesture closes the dialog — by
+ *   leaving the entry — and Forward opens it again, like any other step.
+ * * **Closing goes back** over that entry when this hook pushed it, so a closed dialog
+ *   leaves no dead entry behind. A dialog that arrived OPEN (a deep link, a reload, a
+ *   plain `<Link>` to it) has nothing of ours to go back over, and its close removes the
+ *   param in place instead — Back from there leaves the page, as it should.
+ *
+ * That is why it is not `useSearchParamState`: going back is the only close that
+ * leaves the history as it was before the dialog, and only the opener knows whether it
+ * may.
+ */
+export function useDialogParam(param: DialogParam): [boolean, (open: boolean) => void] {
+  const { key, value } = typeof param === "string" ? { key: param, value: "1" } : param;
+  const [params, setParams] = useSearchParams();
+  const location = useLocation();
+  const navigate = useNavigate();
+  const open = typeof param === "string" ? params.has(key) : params.get(key) === value;
+  const mark = `${key}=${value}`;
+
+  const setOpen = (next: boolean) => {
+    if (next === open) return;
+    const state = carriedState(location.state);
+    if (next) {
+      setParams(
+        (prev) => {
+          const p = new URLSearchParams(prev);
+          p.set(key, value);
+          return p;
+        },
+        { state: { ...state, [OPENED_BY_KIT]: mark } },
+      );
+      return;
+    }
+    if (state?.[OPENED_BY_KIT] === mark) {
+      void navigate(-1);
+      return;
+    }
+    setParams(
+      (prev) => {
+        const p = new URLSearchParams(prev);
+        p.delete(key);
+        return p;
+      },
+      { replace: true, state },
+    );
+  };
+
+  return [open, setOpen];
+}

package/src/i18n/defaults.ts

@@ -12,6 +12,7 @@ import { DEFAULT_TOUR_LABELS } from "../tour/tour";
 import { DEFAULT_COMMAND_PALETTE_LABELS } from "../search/command-palette";
 import { DEFAULT_GLOBAL_SEARCH_LABELS } from "../search/global-search";
 import { DEFAULT_SERIES_CHART_LABELS } from "../components/series-chart-labels";
+import { DEFAULT_PIE_CHART_LABELS } from "../components/pie-chart-labels";
 import { DEFAULT_SPARKLINE_LABELS } from "../components/sparkline";
 import { DEFAULT_STAT_TILE_LABELS } from "../components/stat-tile";
 import { DEFAULT_SIGNATURE_PAD_LABELS } from "../components/signature-pad";
@@ -25,11 +26,26 @@ import { DEFAULT_MEASURED_GRID_LABELS } from "../components/measured-grid";
 import { DEFAULT_CONFIRM_DIALOG_LABELS } from "../components/confirm-dialog";
 import { DEFAULT_FLOATING_PANEL_LABELS } from "../components/floating-panel";
 import { DEFAULT_FEEDBACK_ATTACHMENT_LABELS } from "../feedback/feedback-attachment";
+import { DEFAULT_FEEDBACK_DIALOG_LABELS } from "../feedback/feedback-dialog";
+import {
+  DEFAULT_FEEDBACK_COMPOSER_LABELS,
+  DEFAULT_FEEDBACK_THREAD_LABELS,
+} from "../feedback/feedback-thread";
+import { DEFAULT_ACCOUNT_SETTINGS_LABELS } from "../components/account-settings-labels";
 import { DEFAULT_COPY_BUTTON_LABELS } from "../components/copy-button";
 import { DEFAULT_BULK_ACTION_BAR_LABELS } from "../components/bulk-action-bar";
 import { DEFAULT_LIST_LABELS } from "../components/list";
 import { DEFAULT_BREADCRUMBS_LABELS } from "../components/breadcrumbs";
 import { DEFAULT_TOAST_LABELS } from "../components/toast";
+import { DEFAULT_FORM_ACTIONS_LABELS } from "../components/form-actions";
+import { DEFAULT_DESCRIPTION_LIST_LABELS } from "../components/description-list";
+import { DEFAULT_LINE_ITEMS_LABELS } from "../components/line-items";
+import { DEFAULT_PROGRESS_BAR_LABELS } from "../components/progress-bar";
+import { DEFAULT_SIGNED_AMOUNT_LABELS } from "../components/signed-amount";
+import { DEFAULT_ERROR_BOUNDARY_LABELS } from "../components/error-boundary";
+import { DEFAULT_AUTHED_IMAGE_LABELS } from "../components/authed-image";
+import { DEFAULT_IMAGE_GRID_LABELS } from "../components/image-grid";
+import { DEFAULT_LIGHTBOX_LABELS } from "../components/lightbox";
 import {
   DEFAULT_APP_SHELL_LABELS,
   DEFAULT_CALCULATOR_LABELS,
@@ -80,6 +96,7 @@ export const DEFAULT_UI_KIT_LABELS: UiKitLabels = {
   commandPalette: DEFAULT_COMMAND_PALETTE_LABELS,
   globalSearch: DEFAULT_GLOBAL_SEARCH_LABELS,
   seriesChart: DEFAULT_SERIES_CHART_LABELS,
+  pieChart: DEFAULT_PIE_CHART_LABELS,
   sparkline: DEFAULT_SPARKLINE_LABELS,
   statTile: DEFAULT_STAT_TILE_LABELS,
   signaturePad: DEFAULT_SIGNATURE_PAD_LABELS,
@@ -91,6 +108,10 @@ export const DEFAULT_UI_KIT_LABELS: UiKitLabels = {
   filePicker: DEFAULT_FILE_PICKER_LABELS,
   measuredGrid: DEFAULT_MEASURED_GRID_LABELS,
   feedbackAttachment: DEFAULT_FEEDBACK_ATTACHMENT_LABELS,
+  feedbackDialog: DEFAULT_FEEDBACK_DIALOG_LABELS,
+  feedbackThread: DEFAULT_FEEDBACK_THREAD_LABELS,
+  feedbackComposer: DEFAULT_FEEDBACK_COMPOSER_LABELS,
+  accountSettings: DEFAULT_ACCOUNT_SETTINGS_LABELS,
   confirmDialog: DEFAULT_CONFIRM_DIALOG_LABELS,
   floatingPanel: DEFAULT_FLOATING_PANEL_LABELS,
   copyButton: DEFAULT_COPY_BUTTON_LABELS,
@@ -98,4 +119,13 @@ export const DEFAULT_UI_KIT_LABELS: UiKitLabels = {
   list: DEFAULT_LIST_LABELS,
   breadcrumbs: DEFAULT_BREADCRUMBS_LABELS,
   toast: DEFAULT_TOAST_LABELS,
+  form: DEFAULT_FORM_ACTIONS_LABELS,
+  descriptionList: DEFAULT_DESCRIPTION_LIST_LABELS,
+  lineItems: DEFAULT_LINE_ITEMS_LABELS,
+  progressBar: DEFAULT_PROGRESS_BAR_LABELS,
+  signedAmount: DEFAULT_SIGNED_AMOUNT_LABELS,
+  errorBoundary: DEFAULT_ERROR_BOUNDARY_LABELS,
+  authedImage: DEFAULT_AUTHED_IMAGE_LABELS,
+  imageGrid: DEFAULT_IMAGE_GRID_LABELS,
+  lightbox: DEFAULT_LIGHTBOX_LABELS,
 };

package/src/i18n/kit-labels.tsx

@@ -1,4 +1,5 @@
 import { createContext, useContext, useMemo } from "react";
+import type { AnchorHTMLAttributes, ReactElement, Ref } from "react";
 import type { ReactNode } from "react";
 import type { DataTableLabels } from "../components/data-table-labels";
 import type { MiniCalendarLabels, WeekDay } from "../components/mini-calendar";
@@ -14,6 +15,7 @@ import type { GlobalSearchLabels } from "../search/global-search";
 import type { MonthPickerLabels } from "../components/month-picker";
 import type { PageContentsLabels } from "../components/page-contents";
 import type { SeriesChartLabels } from "../components/series-chart-labels";
+import type { PieChartLabels } from "../components/pie-chart-labels";
 import type { SparklineLabels } from "../components/sparkline";
 import type { StatTileLabels } from "../components/stat-tile";
 import type { SignaturePadLabels } from "../components/signature-pad";
@@ -25,6 +27,9 @@ import type { DialogFrameLabels } from "../components/dialog-frame";
 import type { FilePickerLabels } from "../components/file-button";
 import type { MeasuredGridLabels } from "../components/measured-grid";
 import type { FeedbackAttachmentFieldLabels } from "../feedback/feedback-attachment";
+import type { FeedbackDialogTextLabels } from "../feedback/feedback-dialog";
+import type { FeedbackComposerLabels, FeedbackThreadLabels } from "../feedback/feedback-thread";
+import type { AccountSettingsLabels } from "../components/account-settings-labels";
 import type { ConfirmDialogLabels } from "../components/confirm-dialog";
 import type { FloatingPanelLabels } from "../components/floating-panel";
 import type { CopyButtonLabels } from "../components/copy-button";
@@ -32,6 +37,15 @@ import type { BulkActionBarLabels } from "../components/bulk-action-bar";
 import type { ListLabels } from "../components/list";
 import type { BreadcrumbsLabels } from "../components/breadcrumbs";
 import type { ToastLabels } from "../components/toast";
+import type { FormActionsLabels } from "../components/form-actions";
+import type { DescriptionListLabels } from "../components/description-list";
+import type { LineItemsLabels } from "../components/line-items";
+import type { ProgressBarLabels } from "../components/progress-bar";
+import type { SignedAmountLabels } from "../components/signed-amount";
+import type { ErrorBoundaryLabels } from "../components/error-boundary";
+import type { AuthedImageLabels } from "../components/authed-image";
+import type { ImageGridLabels } from "../components/image-grid";
+import type { LightboxLabels } from "../components/lightbox";
 
 /**
  * EVERY string the kit renders, as one typed tree — and an optional provider that
@@ -84,6 +98,9 @@ export interface CommonLabels {
   /** The × that puts away a banner or a notice (`AlertBanner onDismiss`). Not `close`:
    *  nothing opened, and "Close" on a banner reads as closing the page it sits on. */
   dismiss: string;
+  /** Read after a link that opens a new tab (`<Button href external>`, TextLink):
+   *  nothing else tells a screen reader the page is about to change tabs. */
+  opensInNewTab: string;
 }
 
 /** `DatePicker` / `DateRangePicker` chrome. The calendar inside has its own
@@ -221,6 +238,7 @@ export interface UiKitLabels {
   commandPalette: CommandPaletteLabels;
   globalSearch: GlobalSearchLabels;
   seriesChart: SeriesChartLabels;
+  pieChart: PieChartLabels;
   sparkline: SparklineLabels;
   statTile: StatTileLabels;
   signaturePad: SignaturePadLabels;
@@ -232,6 +250,14 @@ export interface UiKitLabels {
   filePicker: FilePickerLabels;
   measuredGrid: MeasuredGridLabels;
   feedbackAttachment: FeedbackAttachmentFieldLabels;
+  /** 0.12.0: `FeedbackDialog`'s own strings; `FeedbackThread` / `FeedbackComposer`. */
+  feedbackDialog: FeedbackDialogTextLabels;
+  feedbackThread: FeedbackThreadLabels;
+  feedbackComposer: FeedbackComposerLabels;
+  /** 0.12.0: `ProfileSetting`, `PasswordSetting`, `TwoFactorSetting`, `PasskeysSetting`
+   *  — one record per section. The provider takes a whole section record; the
+   *  components merge it key by key, as a prop. */
+  accountSettings: AccountSettingsLabels;
   confirmDialog: ConfirmDialogLabels;
   floatingPanel: FloatingPanelLabels;
   copyButton: CopyButtonLabels;
@@ -239,11 +265,36 @@ export interface UiKitLabels {
   list: ListLabels;
   breadcrumbs: BreadcrumbsLabels;
   toast: ToastLabels;
+  form: FormActionsLabels;
+  descriptionList: DescriptionListLabels;
+  lineItems: LineItemsLabels;
+  progressBar: ProgressBarLabels;
+  signedAmount: SignedAmountLabels;
+  errorBoundary: ErrorBoundaryLabels;
+  authedImage: AuthedImageLabels;
+  imageGrid: ImageGridLabels;
+  lightbox: LightboxLabels;
 }
 
-/** Any subset of the tree, one level deep — each namespace may be partial, and a
- *  namespace that holds a record (`dataTable.presets`) is merged key by key. */
-export type UiKitLabelOverrides = { [K in keyof UiKitLabels]?: Partial<UiKitLabels[K]> };
+/**
+ * A label override, as deep as the labels go: an object of labels (a namespace, or a
+ * record inside one such as `accountSettings.passkeys` or `dataTable.presets`) may be
+ * partial at every level, because the provider merges it key by key at every level.
+ * A leaf stays as it is: a string, a function-valued label (`(n) => …`), and anything
+ * that is not purely an object (a `ReactNode` union) is given whole.
+ */
+export type LabelOverride<T> = [T] extends [(...args: never[]) => unknown]
+  ? T
+  : [T] extends [readonly unknown[]]
+    ? T
+    : [T] extends [object]
+      ? { [K in keyof T]?: LabelOverride<T[K]> }
+      : T;
+
+/** Any subset of the tree — each namespace may be partial, and so may any record
+ *  inside one (`accountSettings.passkeys`, `dataTable.presets`): they are merged key
+ *  by key, at every depth. */
+export type UiKitLabelOverrides = { [K in keyof UiKitLabels]?: LabelOverride<UiKitLabels[K]> };
 
 /* ── English defaults for the namespaces defined here ────────────────────── */
 
@@ -261,6 +312,7 @@ export const DEFAULT_COMMON_LABELS: CommonLabels = {
   noResults: "No results",
   fieldValue: (field, value) => `${field}: ${value}`,
   dismiss: "Dismiss",
+  opensInNewTab: "opens in a new tab",
 };
 
 export const DEFAULT_DATE_PICKER_LABELS: DatePickerLabels = {
@@ -364,8 +416,20 @@ interface KitI18n {
   labels?: UiKitLabelOverrides;
   locale?: string;
   weekStartsOn?: WeekDay;
+  linkComponent?: KitLinkComponent;
 }
 
+/**
+ * What every kit link receives: the anchor attributes the kit decided (href, class,
+ * aria-current, handlers, children, ref). An app's router link maps them —
+ * `({ href, ...p }) => <Link to={href} {...p} />` — ONCE, on the provider.
+ */
+export type KitLinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
+  href: string;
+  ref?: Ref<HTMLAnchorElement>;
+};
+export type KitLinkComponent = (props: KitLinkProps) => ReactElement;
+
 const KitI18nContext = createContext<KitI18n>({});
 
 export interface UiKitProviderProps {
@@ -387,6 +451,14 @@ export interface UiKitProviderProps {
    * and switching it to `en-GB` to get Monday changes every date and number format.
    */
   weekStartsOn?: WeekDay;
+  /**
+   * The app's router link, used by every kit component that renders an in-app link
+   * and was not handed its own `renderLink` — so `renderLink` stops being repeated on
+   * each ListItem, Breadcrumbs, StatTile, Chip… (kastlan). A component's own
+   * `renderLink` wins; external links and in-page `#anchor`s stay plain `<a>`, and a
+   * hash-router `#/path` is handed to it like `/path` (see `pickLinkRenderer`).
+   */
+  linkComponent?: KitLinkComponent;
   children: ReactNode;
 }
 
@@ -398,15 +470,22 @@ export interface UiKitProviderProps {
  * it names, so a page can re-label one table's `dataTable.table` without restating
  * the language.
  */
-export function UiKitProvider({ labels, locale, weekStartsOn, children }: UiKitProviderProps) {
+export function UiKitProvider({
+  labels,
+  locale,
+  weekStartsOn,
+  linkComponent,
+  children,
+}: UiKitProviderProps) {
   const outer = useContext(KitI18nContext);
   const value = useMemo<KitI18n>(
     () => ({
       locale: locale ?? outer.locale,
       weekStartsOn: weekStartsOn ?? outer.weekStartsOn,
       labels: mergeOverrides(outer.labels, labels),
+      linkComponent: linkComponent ?? outer.linkComponent,
     }),
-    [outer, labels, locale, weekStartsOn],
+    [outer, labels, locale, weekStartsOn, linkComponent],
   );
   return <KitI18nContext.Provider value={value}>{children}</KitI18nContext.Provider>;
 }
@@ -415,14 +494,23 @@ function isRecord(v: unknown): v is Record<string, unknown> {
   return typeof v === "object" && v !== null && !Array.isArray(v);
 }
 
-/** Two levels: namespaces, and inside a namespace a record-valued key (presets). */
-function mergeNamespace<T extends object>(base: T, over: Partial<T> | undefined): T {
+/** A record of labels to merge into — not a React element, which is an object too but
+ *  is a label given whole. */
+function isLabelRecord(v: unknown): v is Record<string, unknown> {
+  return isRecord(v) && !("$$typeof" in v);
+}
+
+/** Merged key by key at EVERY depth — a namespace, a record inside it
+ *  (`accountSettings.passkeys`, `dataTable.presets`), and so on down — to match
+ *  {@link LabelOverride}. An `undefined` is skipped at every depth, so it never blanks
+ *  out what is under it. */
+function mergeNamespace<T extends object>(base: T, over: LabelOverride<T> | Partial<T> | undefined): T {
   if (!over) return base;
   const out = { ...base } as Record<string, unknown>;
   for (const [k, v] of Object.entries(over)) {
     if (v === undefined) continue;
     const prev = out[k];
-    out[k] = isRecord(prev) && isRecord(v) ? { ...prev, ...v } : v;
+    out[k] = isLabelRecord(prev) && isLabelRecord(v) ? mergeNamespace(prev, v) : v;
   }
   return out as T;
 }
@@ -475,6 +563,12 @@ export function useKitLocale(prop?: string): string | undefined {
 /** The week start the nearest `<UiKitProvider weekStartsOn>` pins, else `undefined`
  *  (the caller then asks the locale). A component's own prop goes first:
  *  `prop ?? useKitWeekStart()`. */
+/** The provider's router link, or `undefined` — a component's own `renderLink` should
+ *  win over it: `const Link = renderLink ?? useKitLink()`. */
+export function useKitLink(): KitLinkComponent | undefined {
+  return useContext(KitI18nContext).linkComponent;
+}
+
 export function useKitWeekStart(): WeekDay | undefined {
   return useContext(KitI18nContext).weekStartsOn;
 }