@ultimat3/ui 29.4.0 → 30.1.0

package/src/components/line-chart-view.ts

@@ -1,6 +1,7 @@
 // The geometry of a LineChart / AreaChart, apart from its markup: the nice value scale over every
-// series, each point's position, the line through each unbroken run and the area under it. Pure,
-// so a server render and an island draw one chart; `null` is a gap, never a dive to zero.
+// series, each point's position — at its true x when the caller gives one — the line through each
+// unbroken run and the area under it, or over the series below when stacked. Pure, so a server
+// render and an island draw one chart; `null` is a gap, never a dive to zero.
 
 import type { ChartSeries } from './chart-frame-view';
 import { finiteOrNull } from './chart-frame-view';
@@ -54,6 +55,15 @@ export interface LineLayoutInput {
   /** Start the axis at zero (the honest default for counts) or fit it to the data. */
   readonly zero: boolean;
   readonly maxTicks: number;
+  /**
+   * True x positions, one per key, ascending — epoch ms for a time axis. Absent, keys are evenly
+   * spaced: six hours and one minute get one width, which is right only for regular samples.
+   */
+  readonly at?: readonly number[] | undefined;
+  /** Values the axis must reach — a reference line's. */
+  readonly also?: readonly number[] | undefined;
+  /** Each series sits on the ones before it; a gap counts as 0 underneath and draws nothing. */
+  readonly stacked?: boolean | undefined;
 }
 
 const round = (value: number): number => Math.round(value * 10) / 10;
@@ -63,27 +73,64 @@ const round = (value: number): number => Math.round(value * 10) / 10;
  * more thing a caller forgets, and the data already says it. One fraction anywhere turns it off.
  */
 function allIntegers(input: LineLayoutInput): boolean {
-  return input.series.every((series) =>
-    input.keys.every((_, i) => {
-      const value = finiteOrNull(series.values[i]);
-      return value === null || Number.isInteger(value);
-    }),
+  return (
+    input.series.every((series) =>
+      input.keys.every((_, i) => {
+        const value = finiteOrNull(series.values[i]);
+        return value === null || Number.isInteger(value);
+      }),
+    ) && (input.also ?? []).every((value) => Number.isInteger(value))
   );
 }
 
-function extent(input: LineLayoutInput): readonly [number, number] {
+/** `[series][key]`: what each drawn value sits on — 0 unstacked, the sum below it when stacked. */
+function basesOf(input: LineLayoutInput): readonly (readonly number[])[] {
+  const running = input.keys.map(() => 0);
+  return input.series.map((one) => {
+    const base = [...running];
+    if (input.stacked === true) {
+      input.keys.forEach((_, i) => {
+        running[i] = (running[i] ?? 0) + (finiteOrNull(one.values[i]) ?? 0);
+      });
+    }
+    return base;
+  });
+}
+
+function extent(
+  input: LineLayoutInput,
+  bases: readonly (readonly number[])[],
+): readonly [number, number] {
   let lo = Number.POSITIVE_INFINITY;
   let hi = Number.NEGATIVE_INFINITY;
-  for (const series of input.series) {
+  const seen = (value: number): void => {
+    lo = Math.min(lo, value);
+    hi = Math.max(hi, value);
+  };
+  input.series.forEach((series, s) => {
     for (let i = 0; i < input.keys.length; i += 1) {
       const value = finiteOrNull(series.values[i]);
-      if (value === null) continue;
-      lo = Math.min(lo, value);
-      hi = Math.max(hi, value);
+      if (value !== null) seen(value + (bases[s]?.[i] ?? 0));
     }
-  }
+  });
+  for (const value of input.also ?? []) if (Number.isFinite(value)) seen(value);
   if (lo > hi) return [0, 1];
-  return input.zero ? [Math.min(0, lo), Math.max(0, hi)] : [lo, hi];
+  return input.zero || input.stacked === true ? [Math.min(0, lo), Math.max(0, hi)] : [lo, hi];
+}
+
+/** Each key's x: its share of the `at` span when given, its index's share otherwise. */
+function xsOf(input: LineLayoutInput): readonly number[] {
+  const { width, pad } = LINE_CHART;
+  const count = input.keys.length;
+  if (count <= 1) return input.keys.map(() => width / 2);
+  const at = input.at;
+  if (at !== undefined && at.length === count) {
+    const first = at[0] as number;
+    const span = (at[count - 1] as number) - first;
+    if (span > 0)
+      return at.map((value) => round(pad + ((value - first) / span) * (width - pad * 2)));
+  }
+  return input.keys.map((_, index) => round(pad + (index * (width - pad * 2)) / (count - 1)));
 }
 
 function runsOf(points: readonly LinePoint[]): LinePoint[][] {
@@ -99,26 +146,34 @@ function runsOf(points: readonly LinePoint[]): LinePoint[][] {
 
 const at = (point: LinePoint): string => `${point.x},${point.y}`;
 
-export function lineLayout(input: LineLayoutInput): LineLayout {
-  const [lo, hi] = extent(input);
-  const scale = niceTicks(lo, hi, input.maxTicks, { integer: allIntegers(input) });
-  const { width, height, pad } = LINE_CHART;
+/** The y of `value` on `scale` — every point, tick and reference line reads this one rule. */
+export function lineY(scale: NiceScale, value: number): number {
+  const { height, pad } = LINE_CHART;
   // Halved on both sides, which leaves the ratio exact (a power-of-two scale commutes with
   // rounding): `max - min` over the full float64 range overflows to Infinity, and the bottom
   // tick's `Infinity / Infinity` drew `y="NaN"`.
   const half = scale.max / 2 - scale.min / 2;
-  const yOf = (value: number): number =>
-    round(pad + ((scale.max / 2 - value / 2) / half) * (height - pad * 2));
+  return round(pad + ((scale.max / 2 - value / 2) / half) * (height - pad * 2));
+}
+
+export function lineLayout(input: LineLayoutInput): LineLayout {
+  const bases = basesOf(input);
+  const [lo, hi] = extent(input, bases);
+  const scale = niceTicks(lo, hi, input.maxTicks, { integer: allIntegers(input) });
+  const { width } = LINE_CHART;
+  const yOf = (value: number): number => lineY(scale, value);
   const count = input.keys.length;
-  const xOf = (index: number): number =>
-    count <= 1 ? width / 2 : round(pad + (index * (width - pad * 2)) / (count - 1));
+  const xs = xsOf(input);
+  const xOf = (index: number): number => xs[index] ?? width / 2;
   const baselineY = yOf(Math.min(scale.max, Math.max(scale.min, 0)));
 
-  const series = input.series.map((one): LineSeriesGeometry => {
+  const series = input.series.map((one, s): LineSeriesGeometry => {
     const points: LinePoint[] = [];
+    const base = bases[s] ?? [];
     for (let index = 0; index < count; index += 1) {
       const value = finiteOrNull(one.values[index]);
-      if (value !== null) points.push({ index, x: xOf(index), y: yOf(value), value });
+      if (value === null) continue;
+      points.push({ index, x: xOf(index), y: yOf(value + (base[index] ?? 0)), value });
     }
     const runs = runsOf(points);
     const line = runs
@@ -130,7 +185,14 @@ export function lineLayout(input: LineLayoutInput): LineLayout {
         const first = run[0] as LinePoint;
         const last = run.at(-1) as LinePoint;
         const top = run.map((point) => `L${at(point)}`).join(' ');
-        return `M${first.x},${baselineY} ${top} L${last.x},${baselineY} Z`;
+        if (input.stacked !== true)
+          return `M${first.x},${baselineY} ${top} L${last.x},${baselineY} Z`;
+        // Stacked: closed back along the series below, not down to zero — a band, not a hill.
+        const under = [...run]
+          .reverse()
+          .map((point) => `L${point.x},${yOf(base[point.index] ?? 0)}`)
+          .join(' ');
+        return `M${first.x},${yOf(base[first.index] ?? 0)} ${top} ${under} Z`;
       })
       .join(' ');
     return { points, line, area };

package/src/components/log-viewer-view.ts

@@ -0,0 +1,51 @@
+// What a log viewer shows: the lines at or above a level, matching a filter, and only the newest
+// `cap` of them — a live log trims from the top as it grows, so a long run never holds every line.
+
+import { finiteCount } from '@ultimat3/core';
+
+export const LOG_VIEWER_LEVELS = ['debug', 'info', 'warn', 'error'] as const;
+export type LogViewerLevel = (typeof LOG_VIEWER_LEVELS)[number];
+
+/** The most lines a viewer keeps by default; older ones are dropped and counted. */
+export const LOG_VIEWER_CAP = 10_000;
+
+export interface LogLine {
+  /** Unique and stable: the row keeps its node under it as lines arrive. */
+  readonly id: string;
+  readonly text: string;
+  readonly level?: LogViewerLevel | undefined;
+  readonly at?: Date | string | number | undefined;
+  /** A line that names something elsewhere links to it. */
+  readonly href?: string | undefined;
+}
+
+export interface LogWindow {
+  readonly lines: readonly LogLine[];
+  /** Matching lines left out above the window by the cap. */
+  readonly dropped: number;
+}
+
+/**
+ * `minimum` keeps that level and every level above it; a line with no level passes any minimum.
+ * `query` matches case-insensitively in `locale`. The newest `cap` matches are kept.
+ */
+export function logWindow(
+  lines: readonly LogLine[],
+  options: {
+    readonly minimum?: LogViewerLevel | undefined;
+    readonly query?: string | undefined;
+    readonly cap?: number | undefined;
+    readonly locale: string;
+  },
+): LogWindow {
+  const cap = finiteCount('LogViewer', 'cap', options.cap ?? LOG_VIEWER_CAP, 1);
+  const floor = options.minimum === undefined ? 0 : LOG_VIEWER_LEVELS.indexOf(options.minimum);
+  const needle = (options.query ?? '').trim().toLocaleLowerCase(options.locale);
+  const matching = lines.filter(
+    (line) =>
+      (line.level === undefined || LOG_VIEWER_LEVELS.indexOf(line.level) >= floor) &&
+      (needle === '' || line.text.toLocaleLowerCase(options.locale).includes(needle)),
+  );
+  const dropped = Math.max(0, matching.length - cap);
+  return { lines: dropped === 0 ? matching : matching.slice(dropped), dropped };
+}

package/src/components/markdown-nodes.tsx

@@ -0,0 +1,150 @@
+// Markdown tree → elements. Every string is a JSX text node and every element is written out here,
+// so a body cannot name a tag or an attribute. Fences go through `CodeBlock`: one path for code.
+
+import type { JSX } from 'solid-js';
+import type { Language } from '../content/highlight';
+import type { MarkdownBlock, MarkdownInline } from '../content/markdown-tree';
+import { invalidValueError } from '../errors';
+import { CodeBlock } from './CodeBlock';
+import type { HeadingLevel } from './heading-level';
+import { headingTag } from './heading-level';
+import { headingNode } from './heading-node';
+import { Image } from './Image';
+import { Link } from './Link';
+import styles from './Markdown.module.scss';
+
+/** What `resolveImage` answers for a source it vouches for: a box reserved, so no reflow. */
+export interface ResolvedImage {
+  readonly src: string;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface MarkdownRender {
+  readonly baseLevel: number;
+  readonly resolveImage?: ((src: string) => ResolvedImage | null) | undefined;
+  readonly languages?: readonly Language[] | undefined;
+  /** A heading's anchor id, when the caller asked for them (`headingIds`). */
+  readonly ids?: ReadonlyMap<MarkdownBlock, string> | undefined;
+}
+
+const dimension = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value > 0;
+
+/** A remote image from model text is a tracking pixel: its alt, as a link, unless vouched for. */
+function image(
+  node: { readonly src: string; readonly alt: string },
+  render: MarkdownRender,
+): JSX.Element {
+  const resolved = render.resolveImage?.(node.src) ?? null;
+  if (resolved === null) {
+    return <Link href={node.src}>{node.alt === '' ? node.src : node.alt}</Link>;
+  }
+  if (
+    typeof resolved.src !== 'string' ||
+    !dimension(resolved.width) ||
+    !dimension(resolved.height)
+  ) {
+    throw invalidValueError(
+      'Markdown resolveImage',
+      resolved,
+      '{ src: string, width: number, height: number } or null',
+    );
+  }
+  return (
+    <Image src={resolved.src} alt={node.alt} width={resolved.width} height={resolved.height} />
+  );
+}
+
+export function inlineNodes(
+  nodes: readonly MarkdownInline[],
+  render: MarkdownRender,
+): JSX.Element[] {
+  return nodes.map((node) => inlineNode(node, render));
+}
+
+function inlineNode(node: MarkdownInline, render: MarkdownRender): JSX.Element {
+  switch (node.kind) {
+    case 'text':
+      return node.text;
+    case 'code':
+      return <code class={styles['code']}>{node.text}</code>;
+    case 'em':
+      return <em>{inlineNodes(node.children, render)}</em>;
+    case 'strong':
+      return <strong>{inlineNodes(node.children, render)}</strong>;
+    case 'del':
+      return <del>{inlineNodes(node.children, render)}</del>;
+    case 'link':
+      return <Link href={node.href}>{inlineNodes(node.children, render)}</Link>;
+    case 'image':
+      return image(node, render);
+    case 'break':
+      return <br />;
+  }
+}
+
+const level = (render: MarkdownRender, depth: number): HeadingLevel =>
+  Math.min(6, render.baseLevel + depth - 1) as HeadingLevel;
+
+export function blockNode(block: MarkdownBlock, render: MarkdownRender): JSX.Element {
+  switch (block.kind) {
+    case 'heading':
+      return headingNode(
+        headingTag(level(render, block.level)),
+        { id: render.ids?.get(block), class: styles['heading'] },
+        () => inlineNodes(block.children, render),
+      );
+    case 'paragraph':
+      return <p>{inlineNodes(block.children, render)}</p>;
+    case 'code':
+      return <CodeBlock code={block.text} language={block.info} languages={render.languages} />;
+    case 'quote':
+      return (
+        <blockquote class={styles['quote']}>
+          {block.children.map((child) => blockNode(child, render))}
+        </blockquote>
+      );
+    case 'list': {
+      const items = block.items.map((item) => (
+        <li class={item.checked === null ? undefined : styles['task']}>
+          {item.checked === null ? null : <input type="checkbox" checked={item.checked} disabled />}
+          {/* A tight item's one paragraph is its text, not a <p>. */}
+          {item.children.length === 1 && item.children[0]?.kind === 'paragraph'
+            ? inlineNodes(item.children[0].children, render)
+            : item.children.map((child) => blockNode(child, render))}
+        </li>
+      ));
+      return block.ordered ? <ol start={block.start}>{items}</ol> : <ul>{items}</ul>;
+    }
+    case 'table':
+      return (
+        <div class={styles['table']}>
+          <table>
+            <thead>
+              <tr>
+                {block.head.map((cell, c) => (
+                  <th scope="col" data-align={block.align[c] ?? undefined}>
+                    {inlineNodes(cell, render)}
+                  </th>
+                ))}
+              </tr>
+            </thead>
+            <tbody>
+              {block.rows.map((row) => (
+                <tr>
+                  {row.map((cell, c) => (
+                    <td data-align={block.align[c] ?? undefined}>{inlineNodes(cell, render)}</td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      );
+    case 'rule':
+      return <hr />;
+    case 'text':
+      return <p class={styles['rest']}>{block.text}</p>;
+  }
+}

package/src/components/nav-list-view.ts

@@ -0,0 +1,37 @@
+// Which link in a set is the current page — the one rule `NavList` and `BottomNav` share. The
+// longest href that is the current path or a whole-segment prefix of it wins, so `/runs/7` marks
+// `/runs` and not `/`; exactly one item wins or none does, decided by position on a tie.
+
+/** The path of an href, without its query or fragment and without a trailing slash. */
+function pathOf(href: string): string {
+  const cut = href.search(/[?#]/);
+  const path = cut === -1 ? href : href.slice(0, cut);
+  return path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : path;
+}
+
+/** `prefix` is `path` itself or an ancestor of it on a `/` boundary. */
+function covers(prefix: string, path: string): boolean {
+  if (prefix === path || prefix === '/') return true;
+  return path.startsWith(`${prefix}/`);
+}
+
+/**
+ * The index of the current item, or `-1` when no href covers `currentHref`. Two equal hrefs are a
+ * tie the FIRST wins — one `aria-current` per list, never two.
+ */
+export function currentOf(
+  items: readonly { readonly href: string }[],
+  currentHref: string,
+): number {
+  const path = pathOf(currentHref);
+  let best = -1;
+  let bestLength = -1;
+  items.forEach((item, index) => {
+    const candidate = pathOf(item.href);
+    if (covers(candidate, path) && candidate.length > bestLength) {
+      best = index;
+      bestLength = candidate.length;
+    }
+  });
+  return best;
+}

package/src/components/pull-refresh-view.ts

@@ -0,0 +1,93 @@
+// Pull-to-refresh as numbers and states: one resistance curve, a threshold that arms the release,
+// and a refresh that runs once however many pulls arrive while it does. No DOM and no clock, so
+// the component only forwards touches and the tests drive the same machine.
+
+/** The pulled distance, in px after resistance, at which a release refreshes. */
+export const PULL_THRESHOLD = 64;
+/** The distance the curve approaches and never reaches: the indicator's travel. */
+export const PULL_MAX = 112;
+
+/** The one curve: 1:1 at first, flattening towards `PULL_MAX`, so a long pull feels elastic. */
+export function pullDistance(raw: number): number {
+  if (!(raw > 0) || !Number.isFinite(raw)) return 0;
+  return PULL_MAX * (1 - Math.exp(-raw / PULL_MAX));
+}
+
+export type PullState =
+  | { readonly kind: 'idle' }
+  | { readonly kind: 'pulling'; readonly distance: number; readonly armed: boolean }
+  | { readonly kind: 'refreshing' };
+
+export type PullEvent =
+  /** A touch went down: only at the very top of the scroll, only a finger. */
+  | { readonly type: 'start'; readonly atTop: boolean; readonly touch: boolean }
+  /** The finger is `dy` px below where it went down. */
+  | { readonly type: 'move'; readonly dy: number }
+  | { readonly type: 'end' }
+  /** `onRefresh` settled, resolved or rejected alike. */
+  | { readonly type: 'settled' };
+
+export const PULL_IDLE: PullState = { kind: 'idle' };
+
+export function pullStep(state: PullState, event: PullEvent): PullState {
+  switch (event.type) {
+    case 'start':
+      // A second pull during a refresh does nothing; a pull mid-list is the page's scroll.
+      if (state.kind === 'refreshing' || !event.atTop || !event.touch) return state;
+      return { kind: 'pulling', distance: 0, armed: false };
+    case 'move': {
+      if (state.kind !== 'pulling') return state;
+      const distance = pullDistance(event.dy);
+      return { kind: 'pulling', distance, armed: distance >= PULL_THRESHOLD };
+    }
+    case 'end':
+      if (state.kind !== 'pulling') return state;
+      return state.armed ? { kind: 'refreshing' } : PULL_IDLE;
+    case 'settled':
+      return state.kind === 'refreshing' ? PULL_IDLE : state;
+  }
+}
+
+export interface PullController {
+  readonly state: () => PullState;
+  readonly send: (event: PullEvent) => void;
+}
+
+/**
+ * The machine with its one side effect: entering `refreshing` calls `onRefresh` once, and its
+ * settling — a rejection or a synchronous throw included — returns to idle. Either failure goes
+ * to `onError`, never swallowed: the caller's toolbar button and its error state show it.
+ */
+export function pullController(
+  onRefresh: () => Promise<void>,
+  onChange: (state: PullState) => void,
+  onError: (error: unknown) => void,
+): PullController {
+  let state: PullState = PULL_IDLE;
+  const set = (next: PullState): void => {
+    if (Object.is(next, state)) return;
+    state = next;
+    onChange(state);
+  };
+  const send = (event: PullEvent): void => {
+    const before = state;
+    set(pullStep(state, event));
+    if (before.kind === 'refreshing' || state.kind !== 'refreshing') return;
+    // A refresh that throws before it returns a promise fails like one that rejects after, instead
+    // of escaping `send` and pinning the state at `refreshing` with every later pull ignored.
+    let refresh: Promise<void>;
+    try {
+      refresh = onRefresh();
+    } catch (error: unknown) {
+      refresh = Promise.reject(error);
+    }
+    refresh.then(
+      () => set(pullStep(state, { type: 'settled' })),
+      (error: unknown) => {
+        set(pullStep(state, { type: 'settled' }));
+        onError(error);
+      },
+    );
+  };
+  return { state: () => state, send };
+}

package/src/components/rank-options.ts

@@ -0,0 +1,61 @@
+// Which of a long, closed list of options a query names, and in what order — a leaf over
+// `normalizeQuery`, so `SearchableSelect` and anything else ranking labels (`CommandPalette`) fold
+// case and accents by the one rule `Combobox` already uses, and retain no listbox to get it.
+
+import { finiteCount } from '@ultimat3/core';
+import { COMBOBOX_LIMIT, normalizeQuery } from './combobox-filter';
+
+/** The text a ranker reads: the visible label, its second line, and words the label never shows. */
+export interface RankableOption {
+  readonly label: string;
+  readonly description?: string | undefined;
+  /** Synonyms a reader may type — "GMT" for `Europe/London`. Never rendered. */
+  readonly keywords?: readonly string[] | undefined;
+}
+
+export interface RankedOptions<T> {
+  /** The first `limit` matches, best first; a rank keeps the caller's order. */
+  readonly matches: readonly T[];
+  /** Every match before the cap — "first 25 of 140" is spoken from this. */
+  readonly total: number;
+}
+
+const WORD_BREAK = /[\s/_\-.,()]+/u;
+
+/**
+ * 0: the label starts with the query. 1: any word of label, description or keywords does.
+ * 2: the query sits inside one of them. -1: no match. A label prefix outranks a word prefix
+ * because it is the row a reader typing the start of a name is looking at.
+ */
+export function optionRank(option: RankableOption, needle: string): number {
+  const label = normalizeQuery(option.label);
+  if (needle === '' || label.startsWith(needle)) return 0;
+  const texts = [label, ...[option.description, ...(option.keywords ?? [])].map(normal)];
+  if (texts.some((text) => text.split(WORD_BREAK).some((word) => word.startsWith(needle)))) {
+    return 1;
+  }
+  return texts.some((text) => text.includes(needle)) ? 2 : -1;
+}
+
+const normal = (text: string | undefined): string =>
+  text === undefined ? '' : normalizeQuery(text);
+
+/**
+ * `options` narrowed to `query` and ordered by `optionRank`, stable within a rank. An empty query
+ * is every option in the caller's order. `limit` counts rows, so it is held to a whole number.
+ */
+export function rankOptions<T extends RankableOption>(
+  options: readonly T[],
+  query: string,
+  limit: number = COMBOBOX_LIMIT,
+): RankedOptions<T> {
+  const cap = finiteCount('rankOptions', 'limit', limit, 0);
+  const needle = normalizeQuery(query);
+  const buckets: T[][] = [[], [], []];
+  for (const option of options) {
+    const rank = optionRank(option, needle);
+    if (rank >= 0) buckets[rank]?.push(option);
+  }
+  const all = buckets.flat();
+  return { matches: all.slice(0, cap), total: all.length };
+}

package/src/components/searchable-select-keys.ts

@@ -0,0 +1,118 @@
+// What a SearchableSelect's field does on a key, a keystroke, a click and a blur — over accessors
+// and setters it is handed, so the whole controller runs in a test with no DOM and no renderer.
+// Focus never leaves the field: the active row is `aria-activedescendant`, never a focus move.
+
+import type { SearchableView } from './searchable-select-view';
+import { dropLast, firstActive, pickValue, stepActive } from './searchable-select-view';
+
+export interface SearchableKeysState {
+  view(): SearchableView;
+  chosen(): readonly string[];
+  multiple(): boolean;
+  open(): boolean;
+  active(): number;
+  query(): string | null;
+  setOpen(open: boolean): void;
+  setActive(index: number): void;
+  setQuery(query: string | null): void;
+  commit(values: readonly string[]): void;
+}
+
+/** The slice of a `KeyboardEvent` the controller reads — a test builds one as a literal. */
+export interface SearchableKey {
+  readonly key: string;
+  readonly altKey?: boolean;
+  preventDefault(): void;
+}
+
+export interface SearchableKeys {
+  onKeyDown(event: SearchableKey): void;
+  typed(text: string): void;
+  pickRow(index: number): void;
+  toggle(): void;
+  /** Blur and Tab: the list closes, nothing is picked, typed text is dropped. */
+  close(): void;
+}
+
+const LIST_KEYS = new Set(['ArrowDown', 'ArrowUp', 'Home', 'End', 'PageDown', 'PageUp']);
+
+export function searchableKeys(state: SearchableKeysState): SearchableKeys {
+  const chosenRow = (): number => {
+    const rows = state.view().rows;
+    const index = rows.findIndex((row) => state.chosen().includes(row.option.value));
+    return index >= 0 && rows[index]?.option.disabled !== true ? index : firstActive(rows);
+  };
+  const openList = (): void => {
+    state.setOpen(true);
+    state.setActive(chosenRow());
+  };
+  const close = (): void => {
+    state.setOpen(false);
+    state.setActive(-1);
+    state.setQuery(null);
+  };
+  const pickRow = (index: number): void => {
+    const row = state.view().rows[index];
+    if (row === undefined || row.option.disabled === true) return;
+    state.commit(pickValue(state.chosen(), row.option.value, state.multiple()));
+    if (state.multiple()) {
+      // Clearing the query redraws the list, so the old INDEX names another option: find the
+      // picked one again by value, or the second Enter ticks a row the user never aimed at.
+      state.setQuery(null);
+      const rows = state.view().rows;
+      const again = rows.findIndex((r) => r.option.value === row.option.value);
+      state.setActive(again >= 0 ? again : firstActive(rows));
+    } else close();
+  };
+
+  const onKeyDown = (event: SearchableKey): void => {
+    const { key } = event;
+    if (!state.open()) {
+      // Home/End/PageUp/PageDown move the caret in a closed field; only the arrows open it.
+      if (key === 'ArrowDown' || key === 'ArrowUp') {
+        event.preventDefault();
+        openList();
+      } else if (key === 'Escape' && state.query() !== null) {
+        event.preventDefault();
+        close();
+      } else if (key === 'Backspace') removeLast();
+      return;
+    }
+    if (LIST_KEYS.has(key)) {
+      event.preventDefault();
+      if (key === 'ArrowUp' && event.altKey === true) {
+        close();
+        return;
+      }
+      const next = stepActive(state.view().rows, state.active(), key);
+      if (next !== undefined) state.setActive(next);
+      return;
+    }
+    if (key === 'Enter') {
+      // Open, Enter is a pick and never the form's submit.
+      event.preventDefault();
+      pickRow(state.active());
+    } else if (key === 'Escape') {
+      event.preventDefault();
+      close();
+    } else if (key === 'Tab') close();
+    else if (key === 'Backspace') removeLast();
+  };
+
+  const removeLast = (): void => {
+    if (!state.multiple() || (state.query() ?? '') !== '' || state.chosen().length === 0) return;
+    state.commit(dropLast(state.chosen()));
+  };
+
+  return {
+    onKeyDown,
+    typed: (text) => {
+      state.setQuery(text);
+      state.setOpen(true);
+      state.setActive(firstActive(state.view().rows));
+    },
+    pickRow,
+    toggle: () => (state.open() ? close() : openList()),
+    close,
+  };
+}