@enigmax/primitives 0.22.0 → 0.24.0

package/src/core/keys.ts

@@ -0,0 +1,264 @@
+/**
+ * Keyboard shortcuts as data: parsed from a string, matched against an event, and written
+ * back out the way the platform writes them.
+ *
+ * Two components need the same three things and would otherwise each get their own half of
+ * them - the context menu prints a shortcut beside an action, and the selection list matches
+ * one against a key press. A menu whose label says `Ctrl+A` while the list listens for
+ * `Meta+A` is the defect that shape produces, so both read this file.
+ *
+ * `Mod` is the whole point of the spec being a string. It means Command on an Apple keyboard
+ * and Control everywhere else, which is what every one of these shortcuts actually means -
+ * hardcoding either one is wrong on half the machines.
+ */
+
+/** One shortcut, normalized. `mod` and `ctrl`/`meta` are exclusive: `Mod` sets only `mod`. */
+export interface Shortcut {
+    /** The `KeyboardEvent.key` to match, lowercased for letters (`a`, `f2`, `delete`, ` `). */
+    key: string;
+    /** Command on an Apple platform, Control elsewhere. */
+    mod?: boolean;
+    ctrl?: boolean;
+    meta?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+}
+
+/** The parts of a key press a shortcut reads. A real KeyboardEvent satisfies it. */
+export interface ShortcutEvent {
+    key: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+}
+
+/**
+ * A shortcut as written: `"Mod+A"`, `"Shift+F10"`, `"Delete"`, `"Ctrl+Shift+N"`. A list means
+ * several presses do the same thing, and `false` means the command has no binding at all.
+ */
+export type ShortcutSpec = string | Shortcut | readonly (string | Shortcut)[] | false;
+
+const MODIFIERS = new Set(["mod", "ctrl", "control", "meta", "cmd", "command", "super", "win", "shift", "alt", "option", "opt"]);
+
+/** Names that are not one character but are one key. Written the way `KeyboardEvent.key` spells them. */
+const NAMED: Record<string, string> = {
+    esc: "escape",
+    escape: "escape",
+    del: "delete",
+    delete: "delete",
+    back: "backspace",
+    backspace: "backspace",
+    enter: "enter",
+    return: "enter",
+    space: " ",
+    spacebar: " ",
+    tab: "tab",
+    up: "arrowup",
+    down: "arrowdown",
+    left: "arrowleft",
+    right: "arrowright",
+    arrowup: "arrowup",
+    arrowdown: "arrowdown",
+    arrowleft: "arrowleft",
+    arrowright: "arrowright",
+    home: "home",
+    end: "end",
+    pageup: "pageup",
+    pagedown: "pagedown",
+    plus: "+"
+};
+
+/**
+ * Whether this is an Apple keyboard, and so whether `Mod` is Command.
+ *
+ * `navigator.platform` is deprecated and still the only reliable answer where it exists, so
+ * it is tried first and the user agent is the fallback. A server has neither and gets `false`,
+ * which is the right guess: a label rendered on the server is corrected on hydration, and a
+ * key press cannot happen there at all.
+ */
+export function isApplePlatform(): boolean {
+    if (typeof navigator === "undefined") return false;
+    const source = navigator.platform || navigator.userAgent || "";
+    return /mac|iphone|ipad|ipod/i.test(source);
+}
+
+/** `"Mod+Shift+A"` -> the shortcut it stands for. Unknown words are treated as the key. */
+export function parseShortcut(spec: string | Shortcut): Shortcut {
+    if (typeof spec !== "string") return { ...spec, key: normalizeKey(spec.key) };
+
+    const shortcut: Shortcut = { key: "" };
+    // Split on + and - so `Ctrl-A` reads the same as `Ctrl+A`, but never on a LONE separator:
+    // `Ctrl++` and `Ctrl+-` are real shortcuts whose key is the separator itself.
+    const parts = spec.split(/[+-](?!$)/).map((part) => part.trim()).filter(Boolean);
+    if (parts.length === 0) return { key: normalizeKey(spec.trim()) };
+
+    parts.forEach((part, index) => {
+        const word = part.toLowerCase();
+        const last = index === parts.length - 1;
+        // The last word is the KEY even when it names a modifier: `Shift` alone is a
+        // shortcut, and so is the `Alt` in `Ctrl+Alt`.
+        if (!last && MODIFIERS.has(word)) {
+            applyModifier(shortcut, word);
+            return;
+        }
+        if (last && MODIFIERS.has(word) && parts.length > 1) {
+            applyModifier(shortcut, word);
+            return;
+        }
+        shortcut.key = normalizeKey(part);
+    });
+
+    // `Ctrl+Alt` with no key left: the trailing modifier IS the key.
+    if (!shortcut.key) shortcut.key = normalizeKey(parts[parts.length - 1]);
+    return shortcut;
+}
+
+function applyModifier(shortcut: Shortcut, word: string): void {
+    if (word === "mod") shortcut.mod = true;
+    else if (word === "ctrl" || word === "control") shortcut.ctrl = true;
+    else if (word === "meta" || word === "cmd" || word === "command" || word === "super" || word === "win") shortcut.meta = true;
+    else if (word === "shift") shortcut.shift = true;
+    else shortcut.alt = true;
+}
+
+/**
+ * `KeyboardEvent.key` as this file compares it: lowercase, with the aliases resolved.
+ *
+ * NOT trimmed, and that is the whole comment: the space bar reports its key as `" "`, so
+ * trimming here turns Ctrl+Space into Ctrl+nothing and the binding silently never matches.
+ * The spec's own words are trimmed where they are split instead.
+ */
+function normalizeKey(key: string): string {
+    const lower = key.toLowerCase();
+    return NAMED[lower] ?? lower;
+}
+
+/** A spec as a list, so one binding and several read the same downstream. */
+export function shortcutList(spec: ShortcutSpec): Shortcut[] {
+    if (spec === false || spec == null) return [];
+    const entries = Array.isArray(spec) ? spec : [spec as string | Shortcut];
+    return entries.map(parseShortcut);
+}
+
+/**
+ * Whether a key press is this shortcut.
+ *
+ * Every modifier is checked, including the ones the shortcut does NOT ask for: `Delete` must
+ * not fire on `Ctrl+Delete`, which means something else in every file manager there is. Shift
+ * is the one exception the caller can waive, because a shifted letter arrives as a different
+ * `key` on some layouts.
+ */
+export function matchesShortcut(event: ShortcutEvent, spec: ShortcutSpec, apple = isApplePlatform()): boolean {
+    return shortcutList(spec).some((shortcut) => matchesOne(event, shortcut, apple));
+}
+
+function matchesOne(event: ShortcutEvent, shortcut: Shortcut, apple: boolean): boolean {
+    const key = normalizeKey(event.key);
+    // `Mod` resolves to exactly one physical modifier, so Ctrl+A on a Mac is NOT Cmd+A: it
+    // is the terminal's start-of-line, and a list that stole it would be the thing at fault.
+    const wantCtrl = Boolean(shortcut.ctrl || (shortcut.mod && !apple));
+    const wantMeta = Boolean(shortcut.meta || (shortcut.mod && apple));
+    return key === shortcut.key
+        && Boolean(event.ctrlKey) === wantCtrl
+        && Boolean(event.metaKey) === wantMeta
+        && Boolean(event.shiftKey) === Boolean(shortcut.shift)
+        && Boolean(event.altKey) === Boolean(shortcut.alt);
+}
+
+/**
+ * The shortcut written the way this platform writes it, as tokens.
+ *
+ * Tokens rather than a string because that is what a menu renders: one `<kbd>` per key, so
+ * `Ctrl` and `A` can be spaced and styled apart. `shortcutText` joins them for anything that
+ * only has room for a string.
+ */
+export function shortcutTokens(spec: string | Shortcut, apple = isApplePlatform()): string[] {
+    const shortcut = parseShortcut(spec);
+    const tokens: string[] = [];
+    // Apple's own order, which is also the order Windows uses for the modifiers it has:
+    // Control, Option/Alt, Shift, Command.
+    if (shortcut.ctrl || (shortcut.mod && !apple)) tokens.push(apple ? "⌃" : "Ctrl");
+    if (shortcut.alt) tokens.push(apple ? "⌥" : "Alt");
+    if (shortcut.shift) tokens.push(apple ? "⇧" : "Shift");
+    if (shortcut.meta || (shortcut.mod && apple)) tokens.push(apple ? "⌘" : "Win");
+    tokens.push(keyLabel(shortcut.key, apple));
+    return tokens;
+}
+
+/** One string, for a `title`, an `aria-keyshortcuts` neighbour, or a menu with no room. */
+export function shortcutText(spec: string | Shortcut, apple = isApplePlatform()): string {
+    return shortcutTokens(spec, apple).join(apple ? "" : "+");
+}
+
+const KEY_LABELS: Record<string, string> = {
+    " ": "Space",
+    escape: "Esc",
+    enter: "Enter",
+    backspace: "Backspace",
+    delete: "Del",
+    arrowup: "↑",
+    arrowdown: "↓",
+    arrowleft: "←",
+    arrowright: "→",
+    pageup: "PgUp",
+    pagedown: "PgDn"
+};
+
+/** The glyphs an Apple keyboard prints on its own keys, which is what its menus show. */
+const APPLE_KEY_LABELS: Record<string, string> = {
+    delete: "⌦",
+    backspace: "⌫",
+    enter: "↩",
+    escape: "esc"
+};
+
+function keyLabel(key: string, apple: boolean): string {
+    if (apple && APPLE_KEY_LABELS[key]) return APPLE_KEY_LABELS[key];
+    const named = KEY_LABELS[key];
+    if (named) return named;
+    // A function key is upper case whole (`F2`); a letter is one capital.
+    return key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1);
+}
+
+/**
+ * How long a typeahead buffer survives. Long enough to type a word, short enough to reset
+ * before the next thing you meant.
+ */
+export const TYPEAHEAD_MS = 600;
+
+/** The buffer between two presses: what has been typed, and when. */
+export interface TypeaheadState {
+    typed: string;
+    at: number;
+}
+
+export interface TypeaheadStep extends TypeaheadState {
+    /** What to look for. The buffer, or its one repeated character - see below. */
+    needle: string;
+    /**
+     * Whether this press CYCLES through the rows starting with the letter rather than refining
+     * what the last one found. True for a single letter and for the same letter pressed again,
+     * which is the rule every desktop list follows: "rrr" is not a word anybody is typing, it
+     * is someone walking through the Rs.
+     */
+    cycle: boolean;
+}
+
+/**
+ * Advance a typeahead buffer.
+ *
+ * Shared because two lists in this package do the same thing with it - a select with no filter
+ * and a menu - and a buffer that timed out differently in the two would be felt as one of them
+ * being broken.
+ */
+export function typeaheadStep(state: TypeaheadState, character: string, now = Date.now(), windowMs = TYPEAHEAD_MS): TypeaheadStep {
+    const typed = now - state.at > windowMs ? character : state.typed + character;
+    const repeated = typed.length > 1 && [...typed].every((letter) => letter === typed[0]);
+    return {
+        typed,
+        at: now,
+        needle: repeated ? typed[0] : typed,
+        cycle: typed.length === 1 || repeated
+    };
+}

package/src/core/search.ts

@@ -166,6 +166,25 @@ function subsequenceScore(query: string, text: string): number {
     return score;
 }
 
+/**
+ * A query, short enough to put back on the screen.
+ *
+ * Every empty state quotes what was typed - "Nothing matches ..." - and what was typed is
+ * arbitrary: paste sixty characters with no spaces in them and there is no break opportunity
+ * in the whole string, so the panel grows to fit it and keeps growing. Cut in the TEXT and
+ * not only in CSS, because `text-overflow` needs a bounded box and the box is what the
+ * string is stretching.
+ *
+ * The tail is what identifies a typo, so the start is what survives.
+ */
+export function shortenQuery(query: string, max = 32): string {
+    const trimmed = query.trim();
+    if (trimmed.length <= max) return trimmed;
+    // A real ellipsis, not three dots: one character, and a screen reader says "ellipsis"
+    // rather than reading three full stops.
+    return `${trimmed.slice(0, max - 1).trimEnd()}\u2026`;
+}
+
 export function createSearch<T>(options: SearchOptions<T> = {}): SearchInstance<T> {
     let opts: SearchOptions<T> = { ...options };
     let items: readonly T[] = opts.items ?? [];

package/src/core/select.ts

@@ -0,0 +1,404 @@
+/**
+ * The parts of a select that are not rendering: what is chosen, what is visible after the
+ * filter, and where the highlight goes when a key is pressed.
+ *
+ * Framework-agnostic on purpose - the React layer over this file is thin, and a renderer
+ * that is not React only has to draw. The two hard parts of a select live here: a selection
+ * that behaves the same whether one value or many are allowed, and a highlight that never
+ * lands on a disabled row.
+ *
+ * Filtering reuses the search core, so a select filters exactly like the search field does:
+ * accent-insensitive substring by default, Fuse.js when you hand over its constructor, or
+ * your own matcher. Fuse is never imported here - it is a peer the caller passes or not.
+ */
+
+import { typeaheadStep } from "@/core/keys";
+import { createSearch, type FuseConstructor, type SearchOptions, type SearchInstance } from "@/core/search";
+
+export interface SelectOption {
+    /** What ends up in `value`. Unique within the list. */
+    value: string;
+    /** What is read and what the filter searches. */
+    label: string;
+    /** A second line under the label. Searched as well. */
+    description?: string;
+    /**
+     * Anything the renderer can draw beside the label - a ReactNode, an URL, a name. Typed
+     * as `unknown` because a core shared by every adapter cannot know what a node is.
+     */
+    icon?: unknown;
+    /** Visible, listed, announced as unavailable, and never selectable or highlightable. */
+    disabled?: boolean;
+    /** Rows carrying the same group render together under its name. */
+    group?: string;
+    /** Extra words the filter should match - synonyms, an old name, a code. */
+    keywords?: string[];
+}
+
+/** The fields the filter reads when the caller does not say. */
+export const SELECT_SEARCH_KEYS = ["label", "description", "group", "keywords"];
+
+export interface SelectOptions {
+    options?: readonly SelectOption[];
+    /** A string, a list when `multiple`, or null for nothing chosen. */
+    value?: string | readonly string[] | null;
+    multiple?: boolean;
+    /** Filter the list from a field inside the panel. */
+    searchable?: boolean;
+    /** Fuse.js's constructor, for fuzzy filtering. Omit it for the built-in matcher. */
+    fuse?: FuseConstructor;
+    fuseOptions?: Record<string, unknown>;
+    matcher?: SearchOptions<SelectOption>["matcher"];
+    searchKeys?: string[];
+    /** Close after a choice. Default: true when one value is allowed, false when many are. */
+    closeOnSelect?: boolean;
+    /** Every state change. */
+    onChange?: (state: SelectState) => void;
+    /**
+     * Only the value, in the shape the caller asked for: a string, or a list when
+     * `multiple`. The React layer narrows this per mode, so a call site never has to
+     * widen it back by hand.
+     */
+    onValueChange?: (value: string | string[], options: SelectOption[]) => void;
+}
+
+export interface SelectState {
+    open: boolean;
+    query: string;
+    /** Index into `visible`. -1 when there is nothing to highlight. */
+    active: number;
+    /** What the panel shows: every option, or what survived the filter. */
+    visible: SelectOption[];
+    /** The chosen options, in the order they were chosen. */
+    selected: SelectOption[];
+    /** The chosen values, always as a list - `multiple` decides what is reported outwards. */
+    value: string[];
+    multiple: boolean;
+    /** True when a filter is running and matched nothing. */
+    empty: boolean;
+}
+
+export interface SelectInstance {
+    readonly state: SelectState;
+    setOpen(open: boolean): void;
+    toggleOpen(): void;
+    setQuery(query: string): void;
+    /** Move the highlight, skipping disabled rows. */
+    move(key: SelectMoveKey): void;
+    setActive(index: number): void;
+    /** Choose a row: replaces the value, or toggles it when many are allowed. */
+    select(value: string): void;
+    /** Choose whatever is highlighted. */
+    selectActive(): void;
+    /** Drop one value. The × on a tag. */
+    remove(value: string): void;
+    clear(): void;
+    /** Jump to the row starting with what was typed, the way a native select does. */
+    typeahead(character: string): void;
+    update(options: Partial<SelectOptions>): void;
+    subscribe(listener: (state: SelectState) => void): () => void;
+    destroy(): void;
+}
+
+export type SelectMoveKey = "ArrowDown" | "ArrowUp" | "Home" | "End" | "PageDown" | "PageUp";
+
+const PAGE = 5;
+
+/** "Perú" must be reachable by typing "peru" - here as in the search core. */
+function fold(value: string): string {
+    return value.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase();
+}
+
+function toList(value: SelectOptions["value"]): string[] {
+    if (value == null) return [];
+    const list = Array.isArray(value) ? [...value] : [value as string];
+    // The empty string is NOTHING CHOSEN, not a value. `value=""` is how React writes an
+    // empty controlled field and how HTML writes a placeholder option, so keeping it would
+    // leave a select that shows its placeholder while holding a value, offering a clear
+    // button for it and posting it with the form.
+    return list.filter((entry) => entry !== "");
+}
+
+function sameValues(left: readonly string[], right: readonly string[]): boolean {
+    return left.length === right.length && left.every((entry, index) => entry === right[index]);
+}
+
+/** By identity: the option objects are the caller's, and a rebuilt list holds the same ones. */
+function sameRows(left: readonly SelectOption[], right: readonly SelectOption[]): boolean {
+    return left.length === right.length && left.every((option, index) => option === right[index]);
+}
+
+function sameState(left: SelectState, right: SelectState): boolean {
+    return left.open === right.open
+        && left.query === right.query
+        && left.active === right.active
+        && left.multiple === right.multiple
+        && left.empty === right.empty
+        && sameValues(left.value, right.value)
+        && sameRows(left.visible, right.visible)
+        && sameRows(left.selected, right.selected);
+}
+
+export function createSelect(options: SelectOptions = {}): SelectInstance {
+    let opts: SelectOptions = { ...options };
+    let all: readonly SelectOption[] = opts.options ?? [];
+    let value = toList(opts.value);
+    let open = false;
+    let query = "";
+    let active = -1;
+    let visible: SelectOption[] = [...all];
+    let typed = "";
+    let typedAt = 0;
+    let destroyed = false;
+    const listeners = new Set<(state: SelectState) => void>();
+
+    // One engine, built once and updated: it indexes on construction, so rebuilding it per
+    // keystroke would re-index the whole list on every letter.
+    const engine: SearchInstance<SelectOption> = createSearch<SelectOption>({
+        items: all,
+        keys: opts.searchKeys ?? SELECT_SEARCH_KEYS,
+        fuse: opts.fuse,
+        fuseOptions: opts.fuseOptions,
+        matcher: opts.matcher,
+        // A select filters as you type. There is nothing to debounce: the data is already
+        // in memory, and a delay here is felt as the list lagging behind the field.
+        debounce: 0,
+        // An empty query in a select means "everything", not "nothing" - the opposite of a
+        // search field, where an empty query has nothing to show.
+        empty: "all"
+    });
+
+    function optionOf(candidate: string): SelectOption | undefined {
+        return all.find((option) => option.value === candidate);
+    }
+
+    function selectedOptions(): SelectOption[] {
+        // Mapped through the option list so a value with no option left (data reloaded,
+        // an id that no longer exists) simply disappears instead of rendering a blank tag.
+        return value.map(optionOf).filter((option): option is SelectOption => Boolean(option));
+    }
+
+    function snapshot(): SelectState {
+        return {
+            open,
+            query,
+            active,
+            visible,
+            selected: selectedOptions(),
+            value: [...value],
+            multiple: Boolean(opts.multiple),
+            empty: visible.length === 0
+        };
+    }
+
+    function emit(): void {
+        const state = snapshot();
+        opts.onChange?.(state);
+        for (const listener of listeners) listener(state);
+    }
+
+    /** Positive modulo: the walk goes backwards as often as forwards. */
+    function wrap(index: number): number {
+        const length = visible.length;
+        return ((index % length) + length) % length;
+    }
+
+    function enabledIndex(from: number, step: number): number {
+        if (visible.length === 0) return -1;
+        // Walks at most once around the list: a list whose rows are all disabled is a real
+        // list, and it has to leave the highlight nowhere rather than spin looking for one.
+        for (let attempt = 0; attempt < visible.length; attempt++) {
+            const index = wrap(from + step * attempt);
+            if (!visible[index]?.disabled) return index;
+        }
+        return -1;
+    }
+
+    /** The option the highlight is on, so a filter can put it back where it was. */
+    let lastActive: SelectOption | undefined;
+
+    function refilter(): void {
+        visible = opts.searchable && query.trim()
+            ? engine.searchNow(query).map((match) => match.item)
+            : [...all];
+
+        // The highlight follows the row it was on when that row survived the filter, so
+        // deleting a letter does not throw the selection back to the top of the list.
+        const current = active >= 0 ? visible.findIndex((option) => option === lastActive) : -1;
+        active = current >= 0 && !visible[current]?.disabled ? current : enabledIndex(0, 1);
+        lastActive = visible[active];
+    }
+
+    function reportValue(): void {
+        const chosen = selectedOptions();
+        opts.onValueChange?.((opts.multiple ? [...value] : value[0] ?? "") as never, chosen);
+    }
+
+    function closesOnSelect(): boolean {
+        return opts.closeOnSelect ?? !opts.multiple;
+    }
+
+    refilter();
+
+    return {
+        get state() { return snapshot(); },
+
+        setOpen(next: boolean) {
+            if (destroyed || open === next) return;
+            open = next;
+            if (open) {
+                // Opening starts clean and lands on what is already chosen: a select that
+                // reopens on the first row makes you find your own value again.
+                query = "";
+                refilter();
+                const chosen = value[0] ? visible.findIndex((option) => option.value === value[0]) : -1;
+                active = chosen >= 0 && !visible[chosen]?.disabled ? chosen : enabledIndex(0, 1);
+                lastActive = visible[active];
+            } else {
+                query = "";
+                typed = "";
+                refilter();
+            }
+            emit();
+        },
+
+        toggleOpen() { this.setOpen(!open); },
+
+        setQuery(next: string) {
+            if (destroyed) return;
+            query = next;
+            refilter();
+            emit();
+        },
+
+        move(key: SelectMoveKey) {
+            if (destroyed || visible.length === 0) return;
+            const from = active < 0 ? -1 : active;
+            switch (key) {
+                // Wrapping, because a select is a short list and the row after the last one
+                // is the first: clamping leaves the arrow key doing nothing, which reads as
+                // the panel having frozen.
+                case "ArrowDown": active = enabledIndex(from + 1, 1); break;
+                case "ArrowUp": active = enabledIndex(from - 1 + visible.length, -1); break;
+                case "Home": active = enabledIndex(0, 1); break;
+                case "End": active = enabledIndex(visible.length - 1, -1); break;
+                case "PageDown": active = enabledIndex(Math.min(visible.length - 1, from + PAGE), 1); break;
+                case "PageUp": active = enabledIndex(Math.max(0, from - PAGE), -1); break;
+            }
+            lastActive = visible[active];
+            emit();
+        },
+
+        setActive(index: number) {
+            // The row already highlighted is not a change: this arrives from `pointermove`,
+            // which fires on every pixel, and emitting there re-renders the whole panel
+            // sixty times a second - and the scroll it triggers moves the row under a
+            // stationary cursor, which fires it again.
+            if (destroyed || index === active || index < 0 || index >= visible.length || visible[index]?.disabled) return;
+            active = index;
+            lastActive = visible[active];
+            emit();
+        },
+
+        select(next: string) {
+            if (destroyed) return;
+            const option = optionOf(next);
+            // A disabled row is listed and announced, never chosen - including by a click
+            // that got through, which is the one path a renderer tends to forget.
+            if (!option || option.disabled) return;
+
+            if (opts.multiple) {
+                value = value.includes(next) ? value.filter((entry) => entry !== next) : [...value, next];
+            } else {
+                value = [next];
+            }
+
+            reportValue();
+            if (closesOnSelect()) {
+                open = false;
+                query = "";
+                refilter();
+            }
+            emit();
+        },
+
+        selectActive() {
+            const option = visible[active];
+            if (option) this.select(option.value);
+        },
+
+        remove(next: string) {
+            if (destroyed || !value.includes(next)) return;
+            value = value.filter((entry) => entry !== next);
+            reportValue();
+            emit();
+        },
+
+        clear() {
+            if (destroyed || value.length === 0) return;
+            value = [];
+            reportValue();
+            emit();
+        },
+
+        typeahead(character: string) {
+            if (destroyed || character.length !== 1) return;
+            const step = typeaheadStep({ typed, at: typedAt }, character);
+            typed = step.typed;
+            typedAt = step.at;
+
+            const needle = fold(step.needle);
+            // A cycling press searches from the row AFTER this one, so pressing the letter
+            // again walks through everything starting with it instead of sticking on the
+            // first match; a word searches from the current row, so refining it does not
+            // jump off the option it already found.
+            const from = step.cycle ? 1 : 0;
+            for (let step = from; step < visible.length + from; step++) {
+                const index = wrap(Math.max(active, 0) + step);
+                const option = visible[index];
+                if (!option || option.disabled) continue;
+                if (fold(option.label).startsWith(needle)) {
+                    active = index;
+                    lastActive = option;
+                    emit();
+                    return;
+                }
+            }
+        },
+
+        update(next: Partial<SelectOptions>) {
+            if (destroyed) return;
+            const before = snapshot();
+            const hadOptions = next.options !== undefined;
+            opts = { ...opts, ...next };
+            if (hadOptions) all = next.options ?? [];
+            if (next.value !== undefined) value = toList(next.value);
+            if (hadOptions || next.searchKeys || next.fuse || next.fuseOptions || next.matcher) {
+                engine.update({
+                    items: all,
+                    keys: opts.searchKeys ?? SELECT_SEARCH_KEYS,
+                    fuse: opts.fuse,
+                    fuseOptions: opts.fuseOptions,
+                    matcher: opts.matcher
+                });
+            }
+            refilter();
+            // An update that changed nothing must not emit. A renderer subscribes to this
+            // and pushes its props back in whenever it renders, so emitting regardless
+            // redraws the whole panel for a list, a filter and a value that are the ones it
+            // already had - and hands any renderer that rebuilds those props a render loop.
+            if (!sameState(before, snapshot())) emit();
+        },
+
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+
+        destroy() {
+            destroyed = true;
+            listeners.clear();
+            engine.destroy();
+        }
+    };
+}