@ultimat3/ui 29.4.0 → 30.1.0

package/src/components/sparkline-view.ts

@@ -1,36 +1,96 @@
 // The path of a Sparkline, apart from its markup. A sparkline has no axes and no scale to read —
-// the shape of the trend is the entire point — so this is one `M`/`L` path through every point,
-// scaled into the box. Pure, so two renders draw one line.
-
-import type { ChartPoint } from './bar-chart-view';
-import { maxOf } from './bar-chart-view';
+// the shape of the trend is the entire point — so this is one `M`/`L` path per run of known
+// points, scaled into the box through zero: a loss sits below it. `null` is a gap, never a zero.
 
 /** 600 × 72: stretched to a content column, 240 × 48 came out ~220px tall — a chart, not a sparkline. */
 export const SPARKLINE = { width: 600, height: 72, pad: 4 } as const;
 
+/** One value of the series; `null` is unknown — a gap in the line, not a zero. */
+export interface SparklinePoint {
+  readonly key: string;
+  readonly value: number | null;
+}
+
 export interface SparkPoint {
   readonly x: number;
   readonly y: number;
 }
 
-/** Every point's position in the box, oldest first; a single point sits at the start. */
-export function sparkPoints(points: readonly ChartPoint[]): readonly SparkPoint[] {
-  const max = maxOf(points);
+const known = (value: number | null): number | null =>
+  value === null || !Number.isFinite(value) ? null : value;
+
+/** The known range, always through zero and never empty: an all-zero series sits on the floor. */
+function extentKnown(points: readonly SparklinePoint[]): readonly [number, number] {
+  let lo = 0;
+  let hi = 0;
+  for (const point of points) {
+    const value = known(point.value);
+    if (value === null) continue;
+    lo = Math.min(lo, value);
+    hi = Math.max(hi, value);
+  }
+  return hi === lo ? [lo, lo + 1] : [lo, hi];
+}
+
+const innerHeight = SPARKLINE.height - SPARKLINE.pad * 2;
+
+function yOf(value: number, [lo, hi]: readonly [number, number]): number {
+  return SPARKLINE.pad + ((hi - value) / (hi - lo)) * innerHeight;
+}
+
+/** The y of zero: the floor of an all-positive series, a line through a signed one. */
+export function sparkZeroY(points: readonly SparklinePoint[]): number {
+  return yOf(0, extentKnown(points));
+}
+
+/**
+ * Every point's position in the box, oldest first and index for index; `null` where the value is
+ * unknown. A single point sits at the start.
+ */
+export function sparkPoints(points: readonly SparklinePoint[]): readonly (SparkPoint | null)[] {
+  const extent = extentKnown(points);
   const innerWidth = SPARKLINE.width - SPARKLINE.pad * 2;
-  const innerHeight = SPARKLINE.height - SPARKLINE.pad * 2;
   const step = points.length > 1 ? innerWidth / (points.length - 1) : 0;
   return points.map((point, index) => {
-    const value = Number.isFinite(point.value) ? Math.max(0, point.value) : 0;
+    const value = known(point.value);
+    if (value === null) return null;
     return {
       x: SPARKLINE.pad + step * index,
-      y: SPARKLINE.pad + innerHeight - (value / max) * innerHeight,
+      y: yOf(value, extent),
     };
   });
 }
 
 /** The `d` attribute, one decimal per coordinate — stable across renders. Empty for no points. */
-export function sparklinePath(points: readonly ChartPoint[]): string {
-  return sparkPoints(points)
-    .map((p, index) => `${index === 0 ? 'M' : 'L'}${p.x.toFixed(1)},${p.y.toFixed(1)}`)
+export function sparklinePath(points: readonly SparklinePoint[]): string {
+  let fresh = true;
+  const parts: string[] = [];
+  for (const p of sparkPoints(points)) {
+    if (p === null) {
+      fresh = true;
+      continue;
+    }
+    parts.push(`${fresh ? 'M' : 'L'}${p.x.toFixed(1)},${p.y.toFixed(1)}`);
+    fresh = false;
+  }
+  return parts.join(' ');
+}
+
+/** Each run of two or more known points closed down to zero — the area's `d`; `''` for none. */
+export function sparkAreaPath(points: readonly SparklinePoint[]): string {
+  const zero = sparkZeroY(points).toFixed(1);
+  const runs: SparkPoint[][] = [[]];
+  for (const p of sparkPoints(points)) {
+    if (p === null) runs.push([]);
+    else runs.at(-1)?.push(p);
+  }
+  return runs
+    .filter((run) => run.length > 1)
+    .map((run) => {
+      const top = run.map((p) => `L${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(' ');
+      const first = run[0] as SparkPoint;
+      const last = run.at(-1) as SparkPoint;
+      return `M${first.x.toFixed(1)},${zero} ${top} L${last.x.toFixed(1)},${zero} Z`;
+    })
     .join(' ');
 }

package/src/components/split-pane-view.ts

@@ -0,0 +1,69 @@
+// The pure rules of a two-pane split: bounds checked once, a value clamped into them, the key a
+// separator answers, and a pointer read as a percentage from the inline START — mirrored under
+// `rtl`, where the start pane is on the right.
+
+import type { Direction } from '@ultimat3/core';
+import type { AxisSpan } from '../drag/sort-view';
+import { invalidValueError } from '../errors';
+
+/** What one arrow press moves the separator by, in percent. */
+export const PANE_KEY_STEP = 5;
+
+export interface PaneBounds {
+  readonly min: number;
+  readonly max: number;
+}
+
+const isPercent = (value: number): boolean => Number.isFinite(value) && value >= 0 && value <= 100;
+
+/** `min` and `max` as given, refused when either is not a percentage or `min` is over `max`. */
+export function paneBounds(min = 0, max = 100): PaneBounds {
+  if (!isPercent(min)) throw invalidValueError('SplitPane', min, 'a min from 0 to 100');
+  if (!isPercent(max)) throw invalidValueError('SplitPane', max, 'a max from 0 to 100');
+  if (min > max) throw invalidValueError('SplitPane', `min ${min} > max ${max}`, 'min <= max');
+  return { min, max };
+}
+
+/** A caller's `value` or `defaultValue`: a value outside the bounds is a bug, never clamped away. */
+export function paneValue(value: number, bounds: PaneBounds): number {
+  if (!Number.isFinite(value) || value < bounds.min || value > bounds.max) {
+    throw invalidValueError('SplitPane', value, `a value from ${bounds.min} to ${bounds.max}`);
+  }
+  return value;
+}
+
+export function clampPane(value: number, bounds: PaneBounds): number {
+  return Math.max(bounds.min, Math.min(bounds.max, value));
+}
+
+/**
+ * The value a key asks for, or null when the key is not the separator's. The inline arrows grow
+ * the START pane toward the end of the line, so under `rtl` ArrowLeft grows it.
+ */
+export function paneKey(
+  key: string,
+  value: number,
+  bounds: PaneBounds,
+  dir: Direction,
+): number | null {
+  const toward = dir === 'rtl' ? -1 : 1;
+  if (key === 'ArrowRight') return clampPane(value + PANE_KEY_STEP * toward, bounds);
+  if (key === 'ArrowLeft') return clampPane(value - PANE_KEY_STEP * toward, bounds);
+  if (key === 'ArrowUp') return clampPane(value + PANE_KEY_STEP, bounds);
+  if (key === 'ArrowDown') return clampPane(value - PANE_KEY_STEP, bounds);
+  if (key === 'Home') return bounds.min;
+  if (key === 'End') return bounds.max;
+  return null;
+}
+
+/** The start pane's share for a pointer at `x` across the pane box, rounded to a tenth. */
+export function panePercentAt(
+  x: number,
+  box: AxisSpan,
+  bounds: PaneBounds,
+  dir: Direction,
+): number {
+  if (box.size <= 0) return bounds.min;
+  const fromStart = dir === 'rtl' ? box.start + box.size - x : x - box.start;
+  return clampPane(Math.round((fromStart / box.size) * 1000) / 10, bounds);
+}

package/src/components/stat-delta.ts

@@ -1,25 +1,68 @@
-// The trend chip on a StatTile, as a pure rule: a percentage against a baseline, or nothing at
-// all when the baseline is zero — a percentage of nothing is a number that means nothing.
+// The trend chip on a StatTile, as a pure rule: a percentage against a baseline — or the signed
+// difference, from zero or under a baseline too small for a percentage to mean anything — and
+// whether that direction is good, which is the caller's to say: an error rate rising is not green.
 
 export type StatTrend = 'up' | 'down' | 'flat';
 
+/** Which direction is good news. `none`: neither — the arrow says which way, no colour says how. */
+export type StatGoodWhen = 'up' | 'down' | 'none';
+
+/** What colour a chip earns: `good`, `bad`, or `neutral` when no direction was called good. */
+export type StatMood = 'good' | 'bad' | 'neutral';
+
 export interface StatDelta {
-  /** Already formatted: "+12%", "−4%", "0%". */
+  /** Already formatted: "+12%", "−4%", "0%", or a difference: "+5". */
   readonly text: string;
   readonly trend: StatTrend;
 }
 
+export interface DeltaOptions {
+  /**
+   * Below this baseline (absolute), the chip is the signed difference, not a percentage: 2 → 5 is
+   * "+3", never "+150%". A zero baseline always gives the difference.
+   */
+  readonly absoluteBelow?: number | undefined;
+  /** Formats a difference's magnitude. Default: up to two decimals, no grouping. */
+  readonly format?: ((magnitude: number) => string) | undefined;
+}
+
+/** U+2212, the real minus: it is the width of `+`, so the chip does not jump between states. */
+const MINUS = '−';
+
+const plain = (magnitude: number): string => String(Math.round(magnitude * 100) / 100);
+
+function signed(diff: number, text: string): StatDelta {
+  if (diff === 0) return { text, trend: 'flat' };
+  return diff > 0 ? { text: `+${text}`, trend: 'up' } : { text: `${MINUS}${text}`, trend: 'down' };
+}
+
 /**
- * U+2212, the real minus: it is the width of `+`, so the chip does not jump between states.
- * Rounded to a whole percent — a tile is a glance, not a ledger.
+ * The chip for `current` against `baseline`. A percentage, rounded to a whole percent — a tile is a
+ * glance, not a ledger — unless the baseline is zero, negative or under `absoluteBelow`, where a
+ * percentage is a number that means nothing and the signed difference is said instead.
  */
-export function deltaOf(current: number, baseline: number): StatDelta | undefined {
-  if (!Number.isFinite(current) || !Number.isFinite(baseline) || baseline <= 0) return undefined;
+export function deltaOf(
+  current: number,
+  baseline: number,
+  options: DeltaOptions = {},
+): StatDelta | undefined {
+  if (!Number.isFinite(current) || !Number.isFinite(baseline)) return undefined;
+  const below = options.absoluteBelow;
+  const absolute =
+    baseline <= 0 || (below !== undefined && Number.isFinite(below) && Math.abs(baseline) < below);
+  if (absolute) {
+    const diff = current - baseline;
+    const text = (options.format ?? plain)(Math.abs(diff));
+    return diff === 0 ? { text: '0', trend: 'flat' } : signed(diff, text);
+  }
   const pct = Math.round(((current - baseline) / baseline) * 100);
-  if (pct === 0) return { text: '0%', trend: 'flat' };
-  return pct > 0
-    ? { text: `+${pct}%`, trend: 'up' }
-    : { text: `−${Math.abs(pct)}%`, trend: 'down' };
+  return pct === 0 ? { text: '0%', trend: 'flat' } : signed(pct, `${Math.abs(pct)}%`);
+}
+
+/** Whether a trend is good news, by the caller's word for it. Flat is never coloured. */
+export function deltaMood(trend: StatTrend, goodWhen: StatGoodWhen): StatMood {
+  if (trend === 'flat' || goodWhen === 'none') return 'neutral';
+  return trend === goodWhen ? 'good' : 'bad';
 }
 
 /** Drawn, not typed: an arrow character inherits the font's metrics and sits off-centre in a pill. */

package/src/components/stepper-view.ts

@@ -0,0 +1,38 @@
+// A stepper's rule: exactly one step is current, and the count the compact form reads ("Step 2 of
+// 4") is that step's POSITION — never a number the caller restates, which drifts the day a step
+// is inserted.
+
+import { invalidValueError } from '../errors';
+
+export type StepState = 'done' | 'current' | 'upcoming';
+
+export interface StepperStep {
+  /** Stable — the id `onSelect` answers. */
+  readonly id: string;
+  /** Already translated. */
+  readonly label: string;
+  /** A passed step's page; a `done` step with one renders as a link. */
+  readonly href?: string | undefined;
+  readonly state: StepState;
+}
+
+export interface StepperModel {
+  /** Zero-based index of the current step. */
+  readonly current: number;
+  readonly total: number;
+}
+
+/** Where the current step is, or `X_UI_INVALID_VALUE` naming the ids when not exactly one is. */
+export function stepperModel(steps: readonly StepperStep[]): StepperModel {
+  const current = steps.filter((step) => step.state === 'current');
+  if (current.length !== 1) {
+    throw invalidValueError(
+      'Stepper',
+      current.length === 0
+        ? 'no current step'
+        : `current steps ${current.map((s) => s.id).join(', ')}`,
+      'exactly one step with state "current"',
+    );
+  }
+  return { current: steps.findIndex((step) => step.state === 'current'), total: steps.length };
+}

package/src/components/thunk.ts

@@ -0,0 +1,9 @@
+// A function child, typed. Solid's compiler makes every JSX expression one anyway; written as a
+// function so a test that walks the tree after a tick (render-nodes calls thunks) reads it as it
+// is NOW. Solid's `jsx.d.ts` types no function child (its `jsx-h.d.ts` does), hence the one cast.
+
+import type { JSX } from 'solid-js';
+
+export function thunk(fn: () => JSX.Element): JSX.Element {
+  return fn as unknown as JSX.Element;
+}

package/src/components/timeline-view.ts

@@ -0,0 +1,29 @@
+// A timeline's day headers: consecutive items under one label, in the order given. Pure, so the
+// grouping is testable with no renderer. Labels arrive formatted — the zone a "day" is read in is
+// the caller's by the date rule, and this module never sees an instant.
+
+export interface TimelineGroup<T> {
+  /** The header above the run; `undefined` when the caller groups nothing. */
+  readonly label: string | undefined;
+  readonly items: readonly T[];
+}
+
+/**
+ * Runs of items whose `groupBy` answers the same label. Consecutive, never sorted: a timeline is
+ * already in the order it is read, and a label seen again after another is a second header — the
+ * honest answer for a list the caller ordered by something other than the day.
+ */
+export function timelineGroups<T>(
+  items: readonly T[],
+  groupBy?: ((item: T) => string) | undefined,
+): readonly TimelineGroup<T>[] {
+  if (groupBy === undefined) return items.length === 0 ? [] : [{ label: undefined, items }];
+  const groups: { label: string; items: T[] }[] = [];
+  for (const item of items) {
+    const label = groupBy(item);
+    const last = groups[groups.length - 1];
+    if (last !== undefined && last.label === label) last.items.push(item);
+    else groups.push({ label, items: [item] });
+  }
+  return groups;
+}

package/src/components/tree-node.tsx

@@ -0,0 +1,133 @@
+// One node of a `Tree`, in either of its two renderings. Link mode is the platform's: a branch is a
+// `<details>` whose `<summary>` opens it, a leaf is a link — no script at all. Select mode is the
+// APG tree item, which only an island drives; its state arrives as accessors from `Tree`.
+
+import type { JSX } from 'solid-js';
+import { ariaBool } from '../a11y';
+import { UI_KEYS } from '../i18n-keys';
+import { useUi } from '../theme/context';
+import styles from './Tree.module.scss';
+import type { TreeNode } from './tree-view';
+
+export interface TreeLinkNodeProps {
+  node: TreeNode;
+  hrefFor: (node: TreeNode) => string;
+  selected: string | undefined;
+  open: ReadonlySet<string>;
+}
+
+/** Link mode: a `<details>` per branch, a link per leaf, `aria-current` on the selected one alone. */
+export function TreeLinkNode(props: TreeLinkNodeProps): JSX.Element {
+  const children = props.node.children ?? [];
+  if (children.length === 0) {
+    return (
+      <li class={styles['item']}>
+        <a
+          class={styles['link']}
+          href={props.hrefFor(props.node)}
+          aria-current={props.selected === props.node.id ? 'page' : undefined}
+        >
+          {props.node.label}
+        </a>
+      </li>
+    );
+  }
+  return (
+    <li class={styles['item']}>
+      <details class={styles['branch']} open={props.open.has(props.node.id)}>
+        <summary class={styles['summary']}>{props.node.label}</summary>
+        <ul class={styles['group']}>
+          {children.map((child) => (
+            <TreeLinkNode
+              node={child}
+              hrefFor={props.hrefFor}
+              selected={props.selected}
+              open={props.open}
+            />
+          ))}
+        </ul>
+      </details>
+    </li>
+  );
+}
+
+export interface TreeItemState {
+  readonly level: number;
+  readonly setsize: number;
+  readonly posinset: number;
+  readonly branch: boolean;
+}
+
+export interface TreeSelectNodeProps {
+  node: TreeNode;
+  /** Level and position, read from the flattened tree. */
+  state: (id: string) => TreeItemState | undefined;
+  isOpen: (id: string) => boolean;
+  isLoading: (id: string) => boolean;
+  /** The node holding the group's one tab stop. */
+  isStop: (id: string) => boolean;
+  selected: string | undefined;
+  /** Loaded children: the node's own, or what `onExpand` answered for it. */
+  childrenOf: (node: TreeNode) => readonly TreeNode[];
+  onActivate: (id: string) => void;
+}
+
+/** Select mode: `role="treeitem"`, roving tab stop, `aria-expanded` only on a branch. */
+export function TreeSelectNode(props: TreeSelectNodeProps): JSX.Element {
+  const ui = useUi();
+  const id = props.node.id;
+  const branch = (): boolean => props.state(id)?.branch === true;
+  return (
+    // biome-ignore lint/a11y/useKeyWithClickEvents: the tree's one keydown handler sits on `Tree`'s root
+    <li
+      class={styles['item']}
+      role="treeitem"
+      data-tree-id={id}
+      aria-level={props.state(id)?.level}
+      aria-setsize={props.state(id)?.setsize}
+      aria-posinset={props.state(id)?.posinset}
+      aria-expanded={branch() ? ariaBool(props.isOpen(id)) : undefined}
+      aria-selected={ariaBool(props.selected === id)}
+      aria-disabled={props.node.disabled === true ? 'true' : undefined}
+      aria-busy={ariaBool(props.isLoading(id) ? true : undefined)}
+      tabIndex={props.isStop(id) ? 0 : -1}
+      onClick={(event: MouseEvent) => {
+        // The click lands on the innermost item only: a parent hearing its child's click would
+        // toggle itself shut under the reader's pointer.
+        event.stopPropagation();
+        if (props.node.disabled !== true) props.onActivate(id);
+      }}
+    >
+      <span class={styles['row']}>
+        <span
+          class={styles['twisty']}
+          aria-hidden="true"
+          data-open={props.isOpen(id) ? '' : undefined}
+        >
+          {branch() ? '▸' : ''}
+        </span>
+        <span class={styles['label']}>{props.node.label}</span>
+        {props.isLoading(id) ? (
+          <span class={styles['loading']}>{ui.t(UI_KEYS.treeLoading)}</span>
+        ) : null}
+      </span>
+      {branch() && props.isOpen(id) ? (
+        // biome-ignore lint/a11y/useSemanticElements: APG nests a tree item's children in a `group`
+        <ul class={styles['group']} role="group">
+          {props.childrenOf(props.node).map((child) => (
+            <TreeSelectNode
+              node={child}
+              state={props.state}
+              isOpen={props.isOpen}
+              isLoading={props.isLoading}
+              isStop={props.isStop}
+              selected={props.selected}
+              childrenOf={props.childrenOf}
+              onActivate={props.onActivate}
+            />
+          ))}
+        </ul>
+      ) : null}
+    </li>
+  );
+}

package/src/components/tree-view.ts

@@ -0,0 +1,185 @@
+// A tree's rules over plain data: flatten with level and position, the order arrows walk (a closed
+// subtree is skipped), what a key does — left and right follow `dir` — and type-ahead. Pure, so
+// `Tree` is markup over these and every keyboard rule is tested without a renderer.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { UI_ERROR_CODES, UiError } from '../errors';
+
+export interface TreeNode {
+  id: string;
+  /** Already-translated. */
+  label: string;
+  children?: readonly TreeNode[] | undefined;
+  /** Children exist but are not loaded: an island's `onExpand(id)` fetches them. */
+  lazy?: boolean | undefined;
+  disabled?: boolean | undefined;
+}
+
+export interface FlatTreeNode {
+  readonly node: TreeNode;
+  readonly parent: string | undefined;
+  /** 1-based, as `aria-level` wants it. */
+  readonly level: number;
+  readonly setsize: number;
+  readonly posinset: number;
+  /** Has children, loaded or not: it can be opened. */
+  readonly branch: boolean;
+}
+
+function invalidTree(cause: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.invalidValue,
+    cause: `<Tree> ${cause}`,
+    fix: 'nodes: rows.map((row) => ({ id: row.id, label: row.name, children: [...] }))   # on <Tree>: one id per node, and no node inside its own subtree',
+  });
+}
+
+/** Depth first, in document order. A repeated id, or a node inside its own subtree, throws. */
+export function flattenTree(nodes: readonly TreeNode[]): readonly FlatTreeNode[] {
+  const flat: FlatTreeNode[] = [];
+  const seen = new Set<string>();
+  const walk = (
+    level: readonly TreeNode[],
+    parent: string | undefined,
+    depth: number,
+    ancestors: ReadonlySet<string>,
+  ): void => {
+    level.forEach((node, index) => {
+      if (ancestors.has(node.id)) {
+        throw invalidTree(`node ${renderCauseValue(node.id)} is its own ancestor`);
+      }
+      if (seen.has(node.id)) throw invalidTree(`id ${renderCauseValue(node.id)} repeats`);
+      seen.add(node.id);
+      const children = node.children ?? [];
+      flat.push({
+        node,
+        parent,
+        level: depth,
+        setsize: level.length,
+        posinset: index + 1,
+        branch: children.length > 0 || node.lazy === true,
+      });
+      walk(children, node.id, depth + 1, new Set([...ancestors, node.id]));
+    });
+  };
+  walk(nodes, undefined, 1, new Set());
+  return flat;
+}
+
+/** The ids a reader can reach: every node whose ancestors are all open. Disabled ones are skipped. */
+export function visibleTreeIds(
+  flat: readonly FlatTreeNode[],
+  open: ReadonlySet<string>,
+): readonly string[] {
+  const shown = new Set<string>();
+  const ids: string[] = [];
+  for (const entry of flat) {
+    if (entry.parent !== undefined && !(open.has(entry.parent) && shown.has(entry.parent)))
+      continue;
+    shown.add(entry.node.id);
+    if (entry.node.disabled !== true) ids.push(entry.node.id);
+  }
+  return ids;
+}
+
+export type TreeMove =
+  | { readonly kind: 'focus'; readonly id: string }
+  | { readonly kind: 'open'; readonly id: string }
+  | { readonly kind: 'close'; readonly id: string };
+
+/**
+ * What a key does from `current`, per the APG tree pattern. Right opens a closed branch and enters
+ * an open one; Left closes an open branch and climbs from anything else. Under `dir="rtl"` the
+ * two swap, because "inward" points the other way. `undefined` is a key the tree does not take.
+ */
+export function treeMove(
+  flat: readonly FlatTreeNode[],
+  open: ReadonlySet<string>,
+  current: string,
+  key: string,
+  dir: 'ltr' | 'rtl',
+): TreeMove | undefined {
+  const visible = visibleTreeIds(flat, open);
+  const index = visible.indexOf(current);
+  const entry = flat.find((candidate) => candidate.node.id === current);
+  if (entry === undefined) return undefined;
+  const focus = (id: string | undefined): TreeMove | undefined =>
+    id === undefined || id === current ? undefined : { kind: 'focus', id };
+  const inward = dir === 'rtl' ? 'ArrowLeft' : 'ArrowRight';
+  const outward = dir === 'rtl' ? 'ArrowRight' : 'ArrowLeft';
+  switch (key) {
+    case 'ArrowDown':
+      return focus(visible[index + 1]);
+    case 'ArrowUp':
+      return index <= 0 ? undefined : focus(visible[index - 1]);
+    case 'Home':
+      return focus(visible[0]);
+    case 'End':
+      return focus(visible[visible.length - 1]);
+    case inward:
+      if (!entry.branch) return undefined;
+      if (!open.has(current)) return { kind: 'open', id: current };
+      return focus(
+        flat.find((child) => child.parent === current && child.node.disabled !== true)?.node.id,
+      );
+    case outward:
+      if (entry.branch && open.has(current)) return { kind: 'close', id: current };
+      return focus(entry.parent);
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Type-ahead: the next visible node after `current` whose label starts with `typed`, wrapping.
+ * Compared in `locale`, never the runtime's default, so a Turkish `i` matches its own capital.
+ */
+export function treeTypeahead(
+  flat: readonly FlatTreeNode[],
+  open: ReadonlySet<string>,
+  current: string,
+  typed: string,
+  locale: string,
+): string | undefined {
+  const needle = typed.toLocaleLowerCase(locale);
+  if (needle === '') return undefined;
+  const visible = visibleTreeIds(flat, open);
+  const labels = new Map(flat.map((entry) => [entry.node.id, entry.node.label]));
+  const start = visible.indexOf(current);
+  for (let step = 1; step <= visible.length; step += 1) {
+    const id = visible[(start + step) % visible.length];
+    if (id !== undefined && (labels.get(id) ?? '').toLocaleLowerCase(locale).startsWith(needle)) {
+      return id;
+    }
+  }
+  return undefined;
+}
+
+/** The ids to open so `id` is on screen: every ancestor of it. */
+export function treeAncestors(
+  flat: readonly FlatTreeNode[],
+  id: string | undefined,
+): readonly string[] {
+  const parents = new Map(flat.map((entry) => [entry.node.id, entry.parent]));
+  const ancestors: string[] = [];
+  let at = id === undefined ? undefined : parents.get(id);
+  while (at !== undefined) {
+    ancestors.push(at);
+    at = parents.get(at);
+  }
+  return ancestors;
+}
+
+/** The tree with each lazily fetched node's children in place. Unchanged nodes stay the same objects. */
+export function withLoadedChildren(
+  nodes: readonly TreeNode[],
+  loaded: ReadonlyMap<string, readonly TreeNode[]>,
+): readonly TreeNode[] {
+  if (loaded.size === 0) return nodes;
+  return nodes.map((node) => {
+    const fetched = loaded.get(node.id);
+    const children = fetched ?? node.children;
+    if (children === undefined) return node;
+    return { ...node, children: withLoadedChildren(children, loaded) };
+  });
+}