@adecore/ui 0.14.0

package/src/clipboard.ts

@@ -0,0 +1,17 @@
+/*
+ * The clipboard, as the app uses it. A browser hands text over only to a document that is focused
+ * and allowed, and there is nothing a person can do about a refusal, so both sides stay quiet.
+ */
+
+export const copyText = (text: string): void => {
+    void navigator.clipboard?.writeText(text).catch(() => undefined);
+};
+
+/* What is on the clipboard, or nothing at all when the browser will not say. */
+export const readClipboardText = async (): Promise<string> => {
+    try {
+        return (await navigator.clipboard?.readText()) ?? '';
+    } catch {
+        return '';
+    }
+};

package/src/context-menu/index.parts.ts

@@ -0,0 +1,21 @@
+/* A context menu is a menu that opens at the pointer; every part inside it is the menu's own. */
+export {
+    MenuCheck as Check,
+    MenuCheckboxItem as CheckboxItem,
+    MenuGroup as Group,
+    MenuGroupLabel as GroupLabel,
+    MenuHint as Hint,
+    MenuItem as Item,
+    MenuLabel as Label,
+    MenuPopup as Popup,
+    MenuRadioGroup as RadioGroup,
+    MenuRadioItem as RadioItem,
+    ContextMenuRoot as Root,
+    MenuRow as Row,
+    MenuRowAction as RowAction,
+    MenuRowSubmenuTrigger as RowSubmenuTrigger,
+    MenuSeparator as Separator,
+    MenuSubmenuRoot as SubmenuRoot,
+    MenuSubmenuTrigger as SubmenuTrigger,
+    ContextMenuTrigger as Trigger
+} from '../menu/parts.tsx';

package/src/dialog/index.parts.ts

@@ -0,0 +1,10 @@
+export {
+    DialogClose as Close,
+    DialogDescription as Description,
+    DialogFooter as Footer,
+    DialogPopup as Popup,
+    DialogRoot as Root,
+    DialogText as Text,
+    DialogTitle as Title,
+    DialogTrigger as Trigger
+} from './parts.tsx';

package/src/dialog/parts.tsx

@@ -0,0 +1,112 @@
+import { createContext, useContext, useState, type ComponentProps } from 'react';
+import clsx from 'clsx';
+import { Dialog as BaseDialog } from '@base-ui-components/react/dialog';
+import { useRender } from '@base-ui-components/react/use-render';
+import { withClass } from '../class-name.ts';
+import { useDialogLayer } from '../dialog-layer.ts';
+
+/* Whether the dialog is open, for its popup to decide whether it stacks over another one. */
+const DialogOpenContext = createContext(false);
+
+/* A question or a form of a few fields. Every one is as wide as the others, whatever it asks. */
+const SIZE = {
+    sm: 'w-[420px] p-5'
+} as const;
+
+export function DialogRoot({ open, defaultOpen, onOpenChange, ...props }: ComponentProps<typeof BaseDialog.Root>) {
+    // Followed rather than taken over, so a dialog that keeps its own state still does.
+    const [seen, setSeen] = useState(defaultOpen ?? false);
+    return (
+        <DialogOpenContext value={open ?? seen}>
+            <BaseDialog.Root
+                open={open}
+                defaultOpen={defaultOpen}
+                onOpenChange={(next, details) => {
+                    onOpenChange?.(next, details);
+                    if (!details.isCanceled) {
+                        setSeen(next);
+                    }
+                }}
+                {...props}
+            />
+        </DialogOpenContext>
+    );
+}
+
+export const DialogTrigger = BaseDialog.Trigger;
+
+export const DialogClose = BaseDialog.Close;
+
+export type DialogPopupProps = ComponentProps<typeof BaseDialog.Popup> & {
+    /* `sm` is the dialog of a question or a few fields. Without a size the popup is as wide as its `className` says. */
+    size?: keyof typeof SIZE;
+    /* Always over another dialog. A dialog that opens while another one is up stacks by itself. */
+    nested?: boolean;
+    /* The dim behind the dialog. Off for a dialog that leaves what is under it as it is. */
+    backdrop?: boolean;
+    /* Extra on the backdrop, such as the heavier dim a picture needs. */
+    backdropClassName?: string;
+    /* Keeps the popup in the document while it is closed. */
+    keepMounted?: boolean;
+};
+
+/*
+ * The portal, the backdrop and the popup of a dialog in one part. A dialog that opens while another
+ * one is up, such as one from the menu bar over a settings dialog, takes the nested steps and a
+ * backdrop of its own, or the one underneath stays on top and keeps taking clicks.
+ */
+export function DialogPopup({ size, nested = false, backdrop = true, backdropClassName, keepMounted, className, ...props }: DialogPopupProps) {
+    const stacked = useDialogLayer(useContext(DialogOpenContext)) || nested;
+    return (
+        <BaseDialog.Portal keepMounted={keepMounted}>
+            {backdrop && (
+                <BaseDialog.Backdrop className={clsx('dialog-backdrop', stacked && 'dialog-backdrop-nested', backdropClassName)} forceRender={stacked} />
+            )}
+            <BaseDialog.Popup
+                className={withClass(clsx('dialog-popup', size !== undefined && SIZE[size], stacked && 'dialog-popup-nested'), className)}
+                {...props}
+            />
+        </BaseDialog.Portal>
+    );
+}
+
+export type DialogTitleProps = ComponentProps<typeof BaseDialog.Title> & {
+    /* `lg` for a dialog with a header of its own rather than a question. */
+    size?: 'base' | 'lg';
+};
+
+export function DialogTitle({ size = 'base', className, ...props }: DialogTitleProps) {
+    return <BaseDialog.Title className={withClass(clsx(size === 'lg' ? 'text-lg' : 'text-base', 'font-semibold text-text'), className)} {...props} />;
+}
+
+const DESCRIPTION = { sm: 'text-sm text-text-muted', xs: 'text-xs text-text-muted' } as const;
+
+export type DialogDescriptionProps = ComponentProps<typeof BaseDialog.Description> & {
+    size?: keyof typeof DESCRIPTION;
+};
+
+/* The sentence under the title, which is also what a screen reader reads as the dialog's description. It carries no margin. */
+export function DialogDescription({ size = 'sm', className, ...props }: DialogDescriptionProps) {
+    return <BaseDialog.Description className={withClass(DESCRIPTION[size], className)} {...props} />;
+}
+
+export type DialogTextProps = useRender.ComponentProps<'p'> & {
+    size?: keyof typeof DESCRIPTION;
+};
+
+/* A further line in the style of the description that is not the dialog's description: a warning, a note under a choice. */
+export function DialogText({ size = 'sm', render, className, ref, ...props }: DialogTextProps) {
+    return useRender({ render, ref, defaultTagName: 'p', props: { ...props, className: clsx(DESCRIPTION[size], className) } });
+}
+
+export type DialogFooterProps = useRender.ComponentProps<'div'>;
+
+/* The buttons at the foot of a dialog, the main action last and so on the right. */
+export function DialogFooter({ render, className, ref, ...props }: DialogFooterProps) {
+    return useRender({
+        render,
+        ref,
+        defaultTagName: 'div',
+        props: { ...props, className: clsx('mt-4 flex flex-wrap items-center justify-end gap-2', className) }
+    });
+}

package/src/dialog-layer.ts

@@ -0,0 +1,31 @@
+import { useLayoutEffect, useRef, useState } from 'react';
+
+// The app-level dialogs open right now. Each one is its own root, so Base UI does not see them as nested.
+const open = new Set<symbol>();
+
+/*
+ * Whether a dialog opened while another app-level dialog was already up, such as one opened from the
+ * menu bar over a settings dialog. Such a dialog takes the nested steps (`dialog-backdrop-nested`,
+ * `dialog-popup-nested`, a forced backdrop), or the one underneath stays on top and keeps taking clicks.
+ */
+export function useDialogLayer(isOpen: boolean): boolean {
+    const id = useRef(Symbol('dialog'));
+    // Decided in render at the moment the dialog opens, so its first frame is already on the right step.
+    const [seen, setSeen] = useState({ open: false, stacked: false });
+    if (seen.open !== isOpen) {
+        setSeen({ open: isOpen, stacked: isOpen && open.size > 0 });
+    }
+
+    useLayoutEffect(() => {
+        if (!isOpen) {
+            return;
+        }
+        const self = id.current;
+        open.add(self);
+        return () => {
+            open.delete(self);
+        };
+    }, [isOpen]);
+
+    return isOpen && seen.stacked;
+}

package/src/error-boundary.ts

@@ -0,0 +1,40 @@
+/*
+ * The pure half of `ErrorBoundary`: when a failed subtree gets another try, and what a person copies
+ * out of the message. Kept apart so it can be tested without a DOM.
+ */
+
+/* Anything the subtree draws from. A change in any of them means the data may be whole again. */
+export type ResetKeys = readonly unknown[];
+
+/*
+ * Whether a boundary that holds an error should draw its children again. Only a boundary that
+ * failed resets. Comparing keys while the children are fine would remount a terminal or an embedded
+ * page every time the data under it changes.
+ */
+export const shouldReset = (failed: boolean, previous: ResetKeys, next: ResetKeys): boolean => {
+    if (!failed) {
+        return false;
+    }
+    if (previous.length !== next.length) {
+        return true;
+    }
+    return previous.some((key, i) => !Object.is(key, next[i]));
+};
+
+/* A thrown value is not always an Error, and the message has to say something either way. */
+export const errorMessageOf = (error: unknown): string => {
+    if (error instanceof Error) {
+        return error.message || error.name;
+    }
+    return typeof error === 'string' ? error : String(error);
+};
+
+/* The text behind the copy button: what a bug report needs, the component stack included. */
+export const errorReport = (label: string, error: unknown, componentStack: string | null): string => {
+    const stack = error instanceof Error && error.stack ? error.stack : errorMessageOf(error);
+    const parts = [label, stack];
+    if (componentStack) {
+        parts.push(`Component stack:${componentStack}`);
+    }
+    return parts.join('\n\n');
+};

package/src/error-message.ts

@@ -0,0 +1,5 @@
+/* The sentence of an error, for a person to read. One that crossed an Electron bridge (`ipcRenderer.invoke`)
+   carries Electron's own prefix, which says nothing to a person. A throw that is not an Error has no
+   sentence in it, so a caller that knows the step names it. */
+export const messageOf = (e: unknown, fallback?: string): string =>
+    (e instanceof Error ? e.message : (fallback ?? String(e))).replace(/^Error invoking remote method '[^']+': (?:[A-Za-z]*Error: )?/, '');

package/src/field-context.ts

@@ -0,0 +1,12 @@
+import { createContext, useContext } from 'react';
+
+export interface FieldControl {
+    id: string;
+    describedBy: string | undefined;
+    invalid: boolean;
+}
+
+export const FieldContext = createContext<FieldControl | null>(null);
+
+/* What an `Input` or a `TextArea` inside a `Field` takes over: the id its label points at, the hint and the error it is described by. */
+export const useFieldControl = (): FieldControl | null => useContext(FieldContext);

package/src/file-icon.ts

@@ -0,0 +1,52 @@
+import { createFileTreeIconResolver, type FileTreeIconConfig } from '@pierre/trees';
+import { SETI_BY_FILE_EXTENSION, SETI_BY_FILE_NAME, SETI_BY_FILE_NAME_CONTAINS, SETI_DEFAULT_SYMBOL, SETI_SPRITE_SHEET } from './seti-icons.ts';
+
+const SPRITE_ELEMENT_ID = 'adecore-ui-file-icon-sprite';
+
+/* The glyphs are Seti's (`seti-icons.ts`), which knows far more file types than the sets the tree
+   ships with. The tree only colors its own sets, so every symbol carries its hue in its id and the
+   sprite brings the rules that color it. A tree takes all of it as configuration where everything
+   drawn beside it calls `fileIconFor`, so a tab, a picker row and a tree row never disagree about
+   what a file is. Hand this to the tree. */
+export const FILE_TREE_ICONS: FileTreeIconConfig = {
+    set: 'none',
+    spriteSheet: SETI_SPRITE_SHEET,
+    remap: { 'file-tree-icon-file': SETI_DEFAULT_SYMBOL },
+    byFileName: SETI_BY_FILE_NAME,
+    byFileExtension: SETI_BY_FILE_EXTENSION,
+    byFileNameContains: SETI_BY_FILE_NAME_CONTAINS
+};
+
+let resolver: ReturnType<typeof createFileTreeIconResolver> | null = null;
+
+/* Built on the first icon rather than on import, so a bundle that never draws one never builds it. */
+const resolveIcon: ReturnType<typeof createFileTreeIconResolver>['resolveIcon'] = (...args) => {
+    resolver ??= createFileTreeIconResolver(FILE_TREE_ICONS);
+    return resolver.resolveIcon(...args);
+};
+
+/*
+ * The id of the `<symbol>` the set gives a file, in the sprite `mountFileIconSprite` puts in the
+ * document. The path may be absolute or relative. Only the last segment decides, first by exact
+ * name (`package.json`, `.gitignore`), then by a part of the name (`Dockerfile.dev`), then by the
+ * longest extension that matches (`spec.ts` before `ts`). Anything the set does not know falls back
+ * to its generic file icon, and so does a directory. The tree marks a folder with the chevron that
+ * turns as it opens, not with a glyph of its own.
+ */
+export const fileIconFor = (path: string): string => resolveIcon('file-tree-icon-file', path).name;
+
+/* The tree carries the sprite into its own shadow root, out of reach of anything that draws an
+   icon next to it, so the document gets a copy of the same sheet to point `<use>` at. */
+export const mountFileIconSprite = (): void => {
+    if (document.getElementById(SPRITE_ELEMENT_ID) !== null) {
+        return;
+    }
+    const holder = document.createElement('div');
+    holder.innerHTML = SETI_SPRITE_SHEET;
+    const sprite = holder.firstElementChild;
+    if (sprite === null) {
+        return;
+    }
+    sprite.id = SPRITE_ELEMENT_ID;
+    (document.body ?? document.documentElement).append(sprite);
+};

package/src/floating.ts

@@ -0,0 +1,9 @@
+// Every popup, menu, tooltip and dialog of the library is portaled; these are the layers it draws them on.
+const FLOATING_LAYERS = '[data-base-ui-portal], .tooltip-popup, .dialog-popup, .dialog-backdrop';
+
+/* Whether an event landed in a popup rather than on the surface under it, which a canvas-like surface must not take as a click of its own. */
+export const isInFloatingLayer = (target: EventTarget | null): boolean => target instanceof Element && target.closest(FLOATING_LAYERS) !== null;
+
+/* A popup is portaled out of its trigger's element but not out of React's tree, so its events still bubble to that trigger. */
+export const cameThroughPortal = (event: { currentTarget: Element; target: EventTarget }): boolean =>
+    !(event.target instanceof Node && event.currentTarget.contains(event.target));

package/src/format/datetime.ts

@@ -0,0 +1,63 @@
+import { dateFormatter, wordFormatter } from './locale.ts';
+
+/* The parts that are a word rather than a number, and so come from the language and not the region. */
+const WORD_PARTS = new Set<Intl.DateTimeFormatPartTypes>(['month', 'weekday', 'dayPeriod', 'era']);
+
+/*
+ * A date written the way the region writes one, with its words in the language the interface is in.
+ * Both formatters get the same options and the same instant, so every part the region asks for has
+ * one to lift the word from, whatever order the two put them in: `19 Sep` in English against a Dutch
+ * region, `19 sep` once the interface is Dutch too, and a clock that reads `08:05` wherever the
+ * region does not say AM.
+ */
+export const formatDateTime = (at: Date | number, options: Intl.DateTimeFormatOptions): string => {
+    const date = typeof at === 'number' ? new Date(at) : at;
+    const parts = dateFormatter(options).formatToParts(date);
+    if (!parts.some((part) => WORD_PARTS.has(part.type))) {
+        return parts.map((part) => part.value).join('');
+    }
+    const english = wordFormatter(options).formatToParts(date);
+    return parts.map((part) => (WORD_PARTS.has(part.type) ? (english.find((word) => word.type === part.type)?.value ?? part.value) : part.value)).join('');
+};
+
+const CLOCK: Intl.DateTimeFormatOptions = { hour: '2-digit', minute: '2-digit' };
+const WEEKDAY_CLOCK: Intl.DateTimeFormatOptions = { weekday: 'short', hour: '2-digit', minute: '2-digit' };
+const HOUR: Intl.DateTimeFormatOptions = { hour: 'numeric' };
+const DAY: Intl.DateTimeFormatOptions = { month: 'short', day: 'numeric' };
+const DAY_WITH_YEAR: Intl.DateTimeFormatOptions = { month: 'short', day: 'numeric', year: 'numeric' };
+const WEEKDAY_DAY: Intl.DateTimeFormatOptions = { weekday: 'short', month: 'short', day: 'numeric' };
+const DAY_CLOCK: Intl.DateTimeFormatOptions = { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' };
+const NUMERIC_DATE: Intl.DateTimeFormatOptions = { year: 'numeric', month: 'numeric', day: 'numeric' };
+
+/* `08:05`, or `08:05 AM` in a region that counts to twelve. */
+export const formatClock = (at: Date | number): string => formatDateTime(at, CLOCK);
+
+/* A time far enough off that its day is part of the answer: `Sat 08:05`. */
+export const formatWeekdayClock = (at: Date | number): string => formatDateTime(at, WEEKDAY_CLOCK);
+
+/* An hour of the day on its own, for the foot of a chart: `08`, or `8 AM` where that is the clock. */
+export const formatHour = (at: Date | number): string => formatDateTime(at, HOUR);
+
+/* `19 Sep`, the short date a row falls back to once "days ago" stops meaning anything. */
+export const formatDay = (at: Date | number): string => formatDateTime(at, DAY);
+
+/* The same date with the year, for anything older than the one we are in. */
+export const formatDayWithYear = (at: Date | number): string => formatDateTime(at, DAY_WITH_YEAR);
+
+/* `Sat 19 Sep`. */
+export const formatWeekdayDay = (at: Date | number): string => formatDateTime(at, WEEKDAY_DAY);
+
+/* `19 Sep, 08:05`: a moment that is not today, to the minute. */
+export const formatDayClock = (at: Date | number): string => formatDateTime(at, DAY_CLOCK);
+
+/* All numbers, as a form would print it: `19-9-2026` here, `9/19/2026` in the United States. */
+export const formatNumericDate = (at: Date | number): string => formatDateTime(at, NUMERIC_DATE);
+
+/* Whether two instants fall on the same day of the same year, in the zone of whoever is reading. */
+export const isSameDay = (a: Date | number, b: Date | number): boolean => {
+    const left = typeof a === 'number' ? new Date(a) : a;
+    const right = typeof b === 'number' ? new Date(b) : b;
+    return left.getFullYear() === right.getFullYear() && left.getMonth() === right.getMonth() && left.getDate() === right.getDate();
+};
+
+export const formatMoment = (at: Date | number, now: Date | number = Date.now()): string => (isSameDay(at, now) ? formatClock(at) : formatDayClock(at));

package/src/format/duration.ts

@@ -0,0 +1,83 @@
+import { relativeFormatter } from './locale.ts';
+import { formatDecimal, formatNumber } from './number.ts';
+
+const SECOND = 1000;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+/*
+ * How long something took, at the coarsest unit that still says something. The units are English
+ * abbreviations, the way the rest of the interface is written; only the number bends to the region,
+ * which is what `1,5 h` against `1.5 h` is about.
+ */
+export const formatDuration = (ms: number): string => {
+    const seconds = Math.max(0, Math.round(ms / SECOND));
+    if (seconds < 60) {
+        return `${formatNumber(seconds)} s`;
+    }
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60) {
+        return `${formatNumber(minutes)} min`;
+    }
+    return `${formatDecimal(minutes / 60)} h`;
+};
+
+/* How long a window still has, tight enough for the end of a bar: `4d 3h`, `12h 8m`, `9m`. */
+export const formatCountdown = (ms: number): string => {
+    const left = Math.max(0, ms);
+    if (left >= DAY) {
+        return `${formatNumber(Math.floor(left / DAY))}d ${formatNumber(Math.round((left % DAY) / HOUR))}h`;
+    }
+    if (left >= HOUR) {
+        return `${formatNumber(Math.floor(left / HOUR))}h ${formatNumber(Math.round((left % HOUR) / MINUTE))}m`;
+    }
+    return `${formatNumber(Math.max(1, Math.round(left / MINUTE)))}m`;
+};
+
+/*
+ * How long something has been running, to two units and no space to spare: `12s`, `2m 5s`, `3h 20m`.
+ * A call that took a fraction of a second still took some, so anything above zero reads as at least
+ * `1s`; only a clock that runs ahead of the start comes out as `0s`.
+ */
+export const formatElapsedShort = (ms: number): string => {
+    const seconds = ms <= 0 ? 0 : Math.max(1, Math.round(ms / SECOND));
+    if (seconds < 60) {
+        return `${formatNumber(seconds)}s`;
+    }
+    if (seconds < 3600) {
+        const rest = seconds % 60;
+        const minutes = Math.floor(seconds / 60);
+        return rest === 0 ? `${formatNumber(minutes)}m` : `${formatNumber(minutes)}m ${formatNumber(rest)}s`;
+    }
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    return minutes === 0 ? `${formatNumber(hours)}h` : `${formatNumber(hours)}h ${formatNumber(minutes)}m`;
+};
+
+/* A stopwatch that is watched while it runs: `00:14`, and `1:02:03` once it passes an hour. */
+export const formatClockDuration = (ms: number): string => {
+    const seconds = Math.max(0, Math.floor(ms / SECOND));
+    const pad = (value: number): string => String(value).padStart(2, '0');
+    const clock = `${pad(Math.floor((seconds % 3600) / 60))}:${pad(seconds % 60)}`;
+    const hours = Math.floor(seconds / 3600);
+    return hours > 0 ? `${formatNumber(hours)}:${clock}` : clock;
+};
+
+const AGO: Intl.RelativeTimeFormatOptions = { style: 'narrow', numeric: 'always' };
+const NOW: Intl.RelativeTimeFormatOptions = { style: 'narrow', numeric: 'auto' };
+
+/* How long ago something was, short enough for the right edge of a row: `3m ago`, `3 min. geleden`. */
+export const formatAgo = (ms: number): string => {
+    const past = Math.max(0, ms);
+    if (past < MINUTE) {
+        return relativeFormatter(NOW).format(0, 'second');
+    }
+    if (past < HOUR) {
+        return relativeFormatter(AGO).format(-Math.floor(past / MINUTE), 'minute');
+    }
+    if (past < DAY) {
+        return relativeFormatter(AGO).format(-Math.floor(past / HOUR), 'hour');
+    }
+    return relativeFormatter(AGO).format(-Math.floor(past / DAY), 'day');
+};

package/src/format/index.ts

@@ -0,0 +1,20 @@
+/* Every number, date, time and duration a person reads, written the way the language and the region they set ask for. */
+
+export {
+    formatClock,
+    formatDateTime,
+    formatDay,
+    formatDayClock,
+    formatDayWithYear,
+    formatHour,
+    formatMoment,
+    formatNumericDate,
+    formatWeekdayClock,
+    formatWeekdayDay,
+    isSameDay
+} from './datetime.ts';
+export { formatAgo, formatClockDuration, formatCountdown, formatDuration, formatElapsedShort } from './duration.ts';
+export { FALLBACK_LOCALE, formatLocale, labelCollator, setFormatSource, systemLocale, useFormatLocale, type FormatSource } from './locale.ts';
+export { formatBytes, formatDecimal, formatMoney, formatNumber, formatPercent, formatTokens, formatUsdSignificant } from './number.ts';
+export { FORMAT_LANGUAGE, FORMAT_REGIONS, FORMAT_REGION_CHOICES, FORMAT_SYSTEM, formatRegionFrom, regionName } from './regions.ts';
+export { localTimeZone } from './time-zone.ts';

package/src/format/locale.ts

@@ -0,0 +1,153 @@
+import { useSyncExternalStore } from 'react';
+import { FORMAT_LANGUAGE, FORMAT_SYSTEM } from './regions.ts';
+
+/*
+ * Where the formatters read what a person set. The app owns both settings and hands them over once,
+ * before the first render; the language writes the words and the region writes the notation.
+ */
+export interface FormatSource {
+    /* The language the interface is written in right now, such as `en` or `nl`. */
+    language(): string;
+    /* A region tag such as `nl-NL`, or `FORMAT_LANGUAGE` or `FORMAT_SYSTEM`. */
+    region(): string;
+    /* The system's own locale when a shell can read it; a browser tab falls back on `navigator`. */
+    systemLocale?(): string | undefined;
+    /* Calls back whenever the language or the region may have changed. */
+    subscribe(onChange: () => void): () => void;
+}
+
+let source: FormatSource = { language: () => 'en', region: () => FORMAT_LANGUAGE, subscribe: () => () => {} };
+
+/* Answers the source it replaced, so a test can put that one back. */
+export const setFormatSource = (next: FormatSource): FormatSource => {
+    const previous = source;
+    source = next;
+    return previous;
+};
+
+/* Where a language comes from when nothing else says: the country most of its speakers are in. */
+const LANGUAGE_REGIONS: Record<string, string> = { en: 'en-US', nl: 'nl-NL' };
+
+/* The one locale to fall back on, so a format never depends on which machine ran the test. */
+export const FALLBACK_LOCALE = 'en-US';
+
+/* A month and a weekday are words, so they come from the language the interface is in, while the
+   order, the separators and the clock come from the region. English words in a Dutch notation is
+   what a Dutch Mac running an English app should read like, and both halves are a person's to set. */
+export const wordLocale = (): string => source.language();
+
+/* A tag `Intl` will take, or nothing. macOS hands out locales with overrides attached, and a
+   formatter built on one it does not know throws where a number was meant to go. */
+const usable = (tag: string | undefined): string | null => {
+    if (tag === undefined || tag === '') {
+        return null;
+    }
+    try {
+        return Intl.DateTimeFormat.supportedLocalesOf([tag]).length > 0 ? tag : null;
+    } catch {
+        return null;
+    }
+};
+
+/*
+ * What the operating system was set to read numbers and dates in. In a desktop shell Chromium's own
+ * locale is the language of the app bundle, so an English bundle on a Dutch Mac would still hand back
+ * `en-US` and write `08:00 AM`; the shell reads the system's region instead and passes it in
+ * (`systemLocale`). A browser has no such thing, so there the language is the best there is.
+ */
+export const systemLocale = (): string => {
+    const fromShell = usable(source.systemLocale?.());
+    if (fromShell !== null) {
+        return fromShell;
+    }
+    if (typeof navigator === 'undefined') {
+        return FALLBACK_LOCALE;
+    }
+    return usable(navigator.languages?.[0] ?? navigator.language) ?? FALLBACK_LOCALE;
+};
+
+/*
+ * The region a language brings with it. The system's own when it already speaks that language, so
+ * Dutch in Belgium keeps writing dates the Belgian way, and the country the language is most spoken
+ * in when it does not.
+ */
+const regionOfLanguage = (): string => {
+    const language = source.language();
+    const system = systemLocale();
+    return system.toLowerCase().startsWith(language) ? system : (LANGUAGE_REGIONS[language] ?? language);
+};
+
+const resolve = (region: string): string => {
+    if (region === FORMAT_LANGUAGE) {
+        return regionOfLanguage();
+    }
+    return region === FORMAT_SYSTEM ? systemLocale() : region;
+};
+
+/* The locale every formatter in this folder is built on. Read outside React as well, so it is a
+   plain function over the source rather than a hook. */
+export const formatLocale = (): string => resolve(source.region());
+
+/* What a component calls to draw again once the region changes. The value is the locale, which a
+   caller may use or ignore; subscribing is the point. */
+const subscribe = (onChange: () => void): (() => void) => source.subscribe(onChange);
+
+export const useFormatLocale = (): string => useSyncExternalStore(subscribe, formatLocale, formatLocale);
+
+/*
+ * A formatter per options object, keyed on the object itself, so a module-level spec builds its
+ * formatter once and a list of a thousand rows constructs nothing. A region change throws the entry
+ * away, since the locale is part of what was cached.
+ */
+interface Cached<T> {
+    locale: string;
+    formatter: T;
+}
+
+const cacheFor = <O extends object, T>(store: WeakMap<O, Cached<T>>, options: O, locale: string, build: (locale: string, options: O) => T): T => {
+    const hit = store.get(options);
+    if (hit !== undefined && hit.locale === locale) {
+        return hit.formatter;
+    }
+    const formatter = build(locale, options);
+    store.set(options, { locale, formatter });
+    return formatter;
+};
+
+const numbers = new WeakMap<Intl.NumberFormatOptions, Cached<Intl.NumberFormat>>();
+const dates = new WeakMap<Intl.DateTimeFormatOptions, Cached<Intl.DateTimeFormat>>();
+const words = new WeakMap<Intl.DateTimeFormatOptions, Cached<Intl.DateTimeFormat>>();
+const relatives = new WeakMap<Intl.RelativeTimeFormatOptions, Cached<Intl.RelativeTimeFormat>>();
+
+export const numberFormatter = (options: Intl.NumberFormatOptions): Intl.NumberFormat =>
+    cacheFor(numbers, options, formatLocale(), (locale, spec) => new Intl.NumberFormat(locale, spec));
+
+export const dateFormatter = (options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat =>
+    cacheFor(dates, options, formatLocale(), (locale, spec) => new Intl.DateTimeFormat(locale, spec));
+
+/* The same date, written in the language the words come from. Never shown whole: only its month,
+   weekday, era and day period are lifted out of it. */
+export const wordFormatter = (options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat =>
+    cacheFor(words, options, wordLocale(), (locale, spec) => new Intl.DateTimeFormat(locale, spec));
+
+/* `3 min. geleden` is words as much as a number, so the language writes it, the way it writes a month. */
+export const relativeFormatter = (options: Intl.RelativeTimeFormatOptions): Intl.RelativeTimeFormat =>
+    cacheFor(relatives, options, wordLocale(), (locale, spec) => new Intl.RelativeTimeFormat(locale, spec));
+
+const collators = new Map<string, Intl.Collator>();
+
+/*
+ * How two labels a person reads are put in order. Labels are words, so the language writes them and
+ * the language sorts them: Dutch puts Tekening after Terminal where English puts Drawing before it.
+ * Keyed on the locale rather than on an options object, since there are no options to key on.
+ */
+export const labelCollator = (): Intl.Collator => {
+    const locale = wordLocale();
+    const held = collators.get(locale);
+    if (held !== undefined) {
+        return held;
+    }
+    const collator = new Intl.Collator(locale, { sensitivity: 'base', numeric: true });
+    collators.set(locale, collator);
+    return collator;
+};