@weasel-js/ui-logic 0.0.0-stage → 1.15.0

package/dist/index.d.ts

@@ -0,0 +1,562 @@
+import { Rect } from '@weasel-js/geom';
+export { COARSE_STEPS } from '@weasel-js/quantity';
+
+/** How a list that folds is read: which items are branches, which are open, and which item is whose child. */
+interface TreeShape<T> {
+    /** Whether `item` can open, its children shown or not. */
+    isBranch(item: T): boolean;
+    isOpen(item: T): boolean;
+    /** Whether `child` is one of `parent`'s own children. */
+    isChildOf(child: T, parent: T): boolean;
+    /** Whether a branch can open or close now. A disabled one can't. Default: every branch. */
+    canToggle?(item: T): boolean;
+    /** The inline direction the rows read in. Under `'rtl'` Left opens and Right closes. Default `'ltr'`. */
+    dir?: 'ltr' | 'rtl';
+}
+/** What Right or Left does on one item of a tree: open or close it, move the highlight, or nothing (`handled` false).
+ *  `at` null is a key the tree takes without moving. */
+type TreeKeyResult = {
+    handled: false;
+} | {
+    handled: true;
+    toggle: number;
+} | {
+    handled: true;
+    at: number | null;
+};
+/**
+ * Right and Left on the item at `at`, the WAI-ARIA tree way: Right opens a closed branch, else steps to its first
+ * child; Left closes an open branch, else steps to the parent. Mirrored under `dir: 'rtl'`. `items` are the rows
+ * shown, in drawn order.
+ */
+declare function treeKey<T>(items: readonly T[], at: number, key: string, shape: TreeShape<T>): TreeKeyResult;
+
+/** How a list's items are read: which ones the highlight can land on, and which way its arrows run. */
+interface ListShape<T> {
+    /** Whether the highlight can land on `item`. A separator or a heading can't. Default: every item. */
+    canStop?(item: T): boolean;
+    /** Which arrow keys move the highlight. `'both'` answers to all four, the way a radio group does. Default `'vertical'`. */
+    orientation?: 'vertical' | 'horizontal' | 'both';
+    /** The inline direction the items are laid out in. Under `'rtl'` Left steps forward and Right back. Default `'ltr'`. */
+    dir?: 'ltr' | 'rtl';
+    /** An arrow past either end comes round to the other. Default true. */
+    wrap?: boolean;
+}
+/** Index of the first item the highlight can land on, or null for a list with none. */
+declare function firstStop<T>(items: readonly T[], shape?: ListShape<T>): number | null;
+/** The next item the highlight can land on from `from` in direction `dir`; from `null`, the first or last.
+ *  Without wrap, an end stays where it is. Null for a list with no such item. */
+declare function stepStop<T>(items: readonly T[], from: number | null, dir: 1 | -1, shape?: ListShape<T>): number | null;
+/** What one key does to a list's highlight. `handled` false for a key that is not the list's to move. */
+type RovingResult = {
+    handled: false;
+} | {
+    handled: true;
+    at: number | null;
+};
+/** Move the highlight `at` by one key: the arrows along the list's orientation, Home and End. */
+declare function rovingKey<T>(items: readonly T[], at: number | null, key: string, shape?: ListShape<T>): RovingResult;
+/** A key as {@link rowKey} reads it: the key and the modifiers held. */
+interface KeyPress {
+    key: string;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}
+/** A list of rows, and which of the keys past the arrows its caller answers. */
+interface RowKeysShape<T> extends ListShape<T> {
+    /** Set for a list that folds: Right and Left open, close, and walk it ({@link treeKey}). */
+    tree?: TreeShape<T>;
+    /** Cmd/Ctrl+A selects every row. */
+    selectAll?: boolean;
+    /** Enter and Space activate a row. */
+    activate?: boolean;
+    /** Typing a character searches the rows' text. */
+    typeahead?: boolean;
+}
+/** What one key on a row asks for, for the caller to carry out. */
+type RowKeyAction = 
+/** Select every row. */
+{
+    kind: 'selectAll';
+}
+/** Move to row `at`, extending a range from the anchor when `extend`. `at` null takes the key without moving. */
+ | {
+    kind: 'move';
+    at: number | null;
+    extend: boolean;
+}
+/** Open or close the branch at `at`. */
+ | {
+    kind: 'toggle';
+    at: number;
+} | {
+    kind: 'activate';
+}
+/** Hand the key to typeahead. `held` when the key is the list's whether or not the search finds a row. */
+ | {
+    kind: 'type';
+    held: boolean;
+};
+/**
+ * What a key on row `at` of a list of rows does, in the order the keys are tried: Cmd/Ctrl+A, the arrows with Home
+ * and End (Shift to extend), a tree's Right and Left, a space typed mid-search, Enter or Space to activate, then any
+ * other character to search. `searching` says a typeahead search is under way. Null for a key that is not the list's.
+ */
+declare function rowKey<T>(items: readonly T[], at: number, press: KeyPress, shape?: RowKeysShape<T>, searching?: boolean): RowKeyAction | null;
+
+/** How typeahead reads a list: its shape, and the text each item is found by. */
+interface TypeaheadShape<T> extends Pick<ListShape<T>, 'canStop'> {
+    label(item: T): string;
+}
+/** How long typing can pause before the typeahead buffer starts over, in milliseconds. */
+declare const TYPEAHEAD_RESET_MS = 500;
+/** What has been typed so far, and when the last key came. */
+interface TypeaheadBuffer {
+    text: string;
+    at: number;
+}
+/** A buffer nothing has been typed into. */
+declare const EMPTY_TYPEAHEAD: TypeaheadBuffer;
+/** The item a typed `query` lands on, searching forward from `from` with
+ *  wrap. A one-letter query starts after the highlight so repeating a letter
+ *  cycles; a longer one starts at it so typing on keeps the match. */
+declare function typeaheadMatch<T>(items: readonly T[], from: number | null, query: string, shape: TypeaheadShape<T>): number | null;
+/** One typed character: the new buffer and the item it lands on. A key that
+ *  repeats the whole buffer searches that one letter, so it cycles. */
+declare function typeaheadStep<T>(items: readonly T[], from: number | null, buffer: TypeaheadBuffer, key: string, now: number, shape: TypeaheadShape<T>, resetMs?: number): {
+    buffer: TypeaheadBuffer;
+    hit: number | null;
+};
+
+/** How a focus change came about. */
+interface FocusScopeOptions {
+    /** Whether the target shows its focus ring: the scope's `:focus-visible`. Keyboard moves show one, a press does
+     *  not. Default `false` for {@link FocusScope.focus}, `true` for {@link FocusScope.moveFocus}. */
+    readonly visible?: boolean;
+}
+/**
+ * Keyboard focus over a set of targets, whatever draws them: a HUD's widgets and a DOM subtree's elements both
+ * answer it, so code that moves or reads focus is written once for either.
+ */
+interface FocusScope<T> {
+    /** The target holding keyboard focus, or null. One per scope. */
+    readonly focused: T | null;
+    /** Whether the focused target shows its focus ring. */
+    readonly focusVisible: boolean;
+    /** Focus `target`, or blur with `null`. Returns whether `target` now holds focus: false when it is not in this
+     *  scope or cannot take focus, and focus is then unchanged. */
+    focus(target: T | null, options?: FocusScopeOptions): boolean;
+    /** Move focus one step through {@link tabOrder}. From nothing, `'next'` lands on the first target and `'prev'` on
+     *  the last; past either end the scope blurs and returns null, which is where focus leaves it. */
+    moveFocus(direction: 'next' | 'prev', options?: FocusScopeOptions): T | null;
+    /** The targets Tab visits, in order. */
+    tabOrder(): T[];
+    /** Run `fn` whenever the focused target changes. Returns an unsubscribe. */
+    subscribeFocus(fn: (focused: T | null) => void): () => void;
+}
+/** Tab order: targets that declare a place come first, ascending, then the rest in the order given. In the DOM a
+ *  positive `tabindex` declares one and `0` does not. */
+declare function tabSort<T>(targets: readonly T[], declared: (target: T) => number | undefined): T[];
+/** The target one Tab step from `from` through `order`, or null past either end. From nothing, `'next'` is the
+ *  first and `'prev'` the last. A `from` that is out of the order (hidden since it took focus, say) steps from where
+ *  it sits, which `isBefore` says; without it, such a `from` steps as nothing does. */
+declare function tabStep<T>(order: readonly T[], from: T | null, direction: 'next' | 'prev', isBefore?: (a: T, b: T) => boolean): T | null;
+
+/** Steps an arrow key asks for along one axis: one, or {@link COARSE_STEPS} with Shift, positive
+ *  toward ArrowRight and ArrowUp. Under `'rtl'` ArrowLeft and ArrowRight swap, as a native range
+ *  input's do. `null` for any other key. A caller multiplies by its own step. */
+declare function arrowSteps(key: string, shift: boolean, dir?: 'ltr' | 'rtl'): number | null;
+/** Steps an arrow key asks for on a plane, in screen axes: `dy` is positive toward ArrowDown.
+ *  One step, or {@link COARSE_STEPS} with Shift; `null` for any other key. */
+declare function arrowMove(key: string, shift: boolean): {
+    dx: number;
+    dy: number;
+} | null;
+/** What a key does along a range: {@link arrowSteps}, the Page keys ({@link COARSE_STEPS} steps),
+ *  or Home and End (an end of the range). `null` for any other key. */
+declare function rangeKey(key: string, shift: boolean, dir?: 'ltr' | 'rtl'): number | 'home' | 'end' | null;
+
+/** A value on a slider's track the thumb can come to rest on, with whatever label draws under it. */
+interface SliderStop<L = unknown> {
+    value: number;
+    label?: L;
+}
+/** The stops that are actually reachable: inside the range, deduped, ascending.
+ *  A duplicate keeps the first label given for its value. */
+declare function usableStops<L>(stops: readonly (number | SliderStop<L>)[] | undefined, min: number, max: number): SliderStop<L>[];
+/** The stop nearest `v` along the track, or `v` itself when none lies within
+ *  `tolerance` (a track fraction). Measured on the track rather than in value
+ *  units so evenly spaced stops attract over the same distance. */
+declare function attract(v: number, stops: readonly number[], tolerance: number, toFraction: (v: number) => number): number;
+/** Keep thumb `index` strictly between its neighbors: a step apart, or a thousandth of the span without one. */
+declare function clampOrdered(v: number, thumbs: readonly {
+    value: number;
+}[], index: number, min: number, max: number, step: number | undefined): number;
+/** What a key press on one thumb of a slider reads. */
+interface SliderKeyShape {
+    thumbs: readonly {
+        value: number;
+    }[];
+    /** The thumb the key went to. */
+    index: number;
+    /** The ends of the track. */
+    min: number;
+    max: number;
+    step?: number;
+    /** Usable stops, ascending. With any, a keystroke moves by whole stops rather than by value. */
+    stops?: readonly number[];
+    /** Keep the thumb between its neighbors. */
+    ordered?: boolean;
+    /** The finite range, where the track runs past it to an endless end's stop. Default the track. */
+    range?: readonly [number, number];
+    /** Under `'rtl'` the horizontal arrows are mirrored, as the values run from the right end. */
+    dir?: 'ltr' | 'rtl';
+    /** This thumb's own limits inside the track. Read only for a key the slider answers to. */
+    bounds?(): readonly [number, number];
+    /** Where the thumb lands `steps` presses away, for a track whose values aren't what the user counts in. */
+    keyStep?(steps: number): number;
+}
+/** The value one key moves thumb `index` to: arrows by a step (ten with Shift), the Page keys by ten,
+ *  Home and End to the thumb's ends. `null` for a key the slider does not answer to. */
+declare function sliderKey(key: string, shift: boolean, shape: SliderKeyShape): number | null;
+
+/** How a text field's edit ends: `'commit'` writes what was typed, `'cancel'` drops it and puts back what was there. */
+type EditEnd = 'commit' | 'cancel';
+/** What a field varies in how its edit ends: what Escape does (`'cancel'` by default), and whether the field holds
+ *  more than one line, which leaves Shift+Enter to type a line break rather than commit. */
+interface EditEndShape {
+    escape?: EditEnd;
+    multiline?: boolean;
+}
+/** What may end an edit: a key, with whether Shift is held, or the field losing focus. A key {@link imeKey} claims is
+ *  the caller's to hold back. */
+type EditCause = 'blur' | {
+    key: string;
+    shift?: boolean;
+};
+/** How `cause` ends a text field's edit, or null when it leaves the edit open. Enter and blur commit, Escape cancels
+ *  unless `shape` says otherwise. */
+declare function editEnd(cause: EditCause, shape?: EditEndShape): EditEnd | null;
+/** A keydown as the platform reports it, enough to tell whether an input method owns it. */
+interface KeySource {
+    key: string;
+    isComposing?: boolean;
+    keyCode?: number;
+}
+/** Whether a keydown belongs to an input method, which a field must leave alone: Enter there confirms a candidate and
+ *  Escape dismisses them. Safari sends the Enter that ends a composition with `isComposing` already false, but with
+ *  `keyCode` 229. */
+declare function imeKey(e: KeySource): boolean;
+
+/**
+ * Moving items within an ordered list. A destination is a gap, counted before anything is taken out: 0 before the
+ * first item, `length` after the last, and `i` between `items[i - 1]` and `items[i]` — the gap a UI marks while it
+ * carries something. The items moved are named by their indices, so a selection of several moves in one go.
+ */
+/** `items` with the items at indices `at` taken out and put back, in their order, in gap `to`. */
+declare function moveItems<T>(items: readonly T[], at: readonly number[], to: number): T[];
+/** The index the first of the items at `at` holds once {@link moveItems} has put them in gap `to`. */
+declare function movedIndex(at: readonly number[], to: number): number;
+/** Whether putting the items at `at` in gap `to` leaves them where they are: a contiguous run dropped in a gap at
+ *  either of its ends or inside it. False for no items. */
+declare function isNoopDrop(at: readonly number[], to: number): boolean;
+/** The gap a one-place move sends the items at `at` to: before the item ahead of the first (`by` -1), or after the
+ *  item past the last (`by` 1). Null where that runs off either end of a list `length` long, or for no items. */
+declare function nudgeGap(at: readonly number[], by: -1 | 1, length: number): number | null;
+/**
+ * The gap a point `p` along a line of items falls in, where each item splits at its middle: how many of the
+ * middles `mids`, given in item order, `p` has reached. A line whose middles run backward, as a right-to-left row
+ * does along x, counts the other way. For items that sit side by side — rows, tabs, chips.
+ */
+declare function gapByMidpoint(mids: readonly number[], p: number): number;
+/** Which of the gaps at positions `gaps` along a line is nearest `p`, as an index into `gaps`; -1 for none. For
+ *  gaps drawn at places of their own, between items set apart however the layout put them: picking the nearest
+ *  keeps the gap chosen the one whose mark is drawn closest. */
+declare function nearestGap(gaps: readonly number[], p: number): number;
+/** The keys and modifiers a nudge chord reads off a keystroke. */
+interface NudgeKey {
+    key: string;
+    altKey: boolean;
+    ctrlKey: boolean;
+    metaKey: boolean;
+}
+/** Alt with neither Ctrl nor Cmd held: the chord that moves an item instead of moving focus. */
+declare function isNudgeChord(e: NudgeKey): boolean;
+/** Which way the nudge chord moves an item: `-1` for Alt+`back`, `1` for Alt+`on`, `null` for any other key.
+ *  The keys are Up and Down unless named. */
+declare function nudgeOf(e: NudgeKey, back?: string, on?: string): -1 | 1 | null;
+
+/** Clock and timer, injected so tests and hosts control time. */
+interface Scheduler {
+    now(): number;
+    /** Run `fn` after `ms`; returns a cancel. */
+    set(fn: () => void, ms: number): () => void;
+}
+/** The real-time scheduler: `Date.now` and `setTimeout`. */
+declare const timerScheduler: Scheduler;
+
+/** How long a held stepper waits before it repeats, in milliseconds. */
+declare const REPEAT_DELAY_MS = 400;
+/** How often a held stepper steps once it repeats, in milliseconds. */
+declare const REPEAT_EVERY_MS = 60;
+/** The timing of a {@link createStepRepeat}. Each is read when it is next used, so a getter can change it mid-hold. */
+interface StepRepeatOptions {
+    /** Default {@link REPEAT_DELAY_MS}. */
+    delayMs?: number;
+    /** Default {@link REPEAT_EVERY_MS}. */
+    everyMs?: number;
+    /** Default {@link timerScheduler}. */
+    scheduler?: Pick<Scheduler, 'set'>;
+}
+/** A held stepper: {@link createStepRepeat}. */
+interface StepRepeat<K> {
+    /** Step `key` once now, then after the delay once every interval until {@link stop}. Replaces any hold. */
+    start(key: K): void;
+    stop(): void;
+    /** The key being held, or null. */
+    held(): K | null;
+}
+/**
+ * Hold-to-repeat stepping, whatever draws the stepper: `step` moves the value by `key`, and `spent` says `key`
+ * has nowhere left to go, which ends the hold. Both are called at the moment of each step.
+ */
+declare function createStepRepeat<K>(step: (key: K) => void, spent: (key: K) => boolean, opts?: StepRepeatOptions): StepRepeat<K>;
+
+/** The sizes a box may take, in CSS px. `Infinity` for a max leaves that axis free. */
+interface Constraints {
+    readonly minWidth: number;
+    readonly maxWidth: number;
+    readonly minHeight: number;
+    readonly maxHeight: number;
+}
+/** No bound on either axis: a box at its own size. */
+declare const UNBOUNDED: Constraints;
+/** Exactly `width` by `height`: a box placed into a fixed rectangle. */
+declare function exactly(width: number, height: number): Constraints;
+/** Exactly `width` wide and as tall as the box likes: a box filling its column. */
+declare function fixedWidth(width: number): Constraints;
+/** `size` clamped to `[min, max]`. A max below its min yields the min, as CSS does. */
+declare function clampTo(size: number, min: number, max: number): number;
+/** The font a run of text is measured in. `family` is a CSS font-family list; a target that draws with
+ *  fonts of its own maps it onto one. */
+interface FontSpec {
+    readonly family?: string;
+    readonly size: number;
+    readonly weight?: number;
+}
+/** A run of text's advance width and the ascent and descent its line is set with, in px. */
+interface TextExtent {
+    readonly width: number;
+    readonly ascent: number;
+    readonly descent: number;
+}
+/**
+ * What measuring reads from where the component is drawn: its theme's tokens and its text metrics. A DOM element's
+ * computed style answers it, and so does a HUD's resolved theme and font atlas, which is what lets one `measure`
+ * serve both.
+ */
+interface MeasureEnv {
+    /** A token's value (`'28px'`, `'500'`), or undefined where nothing sets it. */
+    token(name: string): string | undefined;
+    text(text: string, font: FontSpec): TextExtent;
+}
+/** A px token as a number: `name`, else `fallback`. Throws where neither is a px length, since silently reading
+ *  0 collapses whatever the token sizes. */
+declare function envPx(env: MeasureEnv, name: string, fallback?: number | string): number;
+/** A unitless numeric token, else `fallback`. */
+declare function envNumber(env: MeasureEnv, name: string, fallback: number): number;
+/** A box's size, its first baseline, and where its parts sit inside it. */
+interface Measured<L> {
+    readonly width: number;
+    readonly height: number;
+    /** From the box's top to its first line of text's alphabetic baseline, as CSS `align-items: baseline` reads
+     *  it; the bottom edge for a box with no text. */
+    readonly baseline: number;
+    /** Where each part sits, relative to the box's top left. Its shape is the component's own. */
+    readonly layout: L;
+}
+/**
+ * The baseline of a line of text `lineHeight` tall centered in a box `boxHeight` tall, from the box's top: CSS's
+ * half-leading model, the line's ascent and descent centered inside its line height.
+ */
+declare function centeredBaseline(boxHeight: number, lineHeight: number, extent: TextExtent): number;
+/** `r` moved by `(dx, dy)`. */
+declare function offsetRect(r: Rect, dx: number, dy: number): Rect;
+/**
+ * The one contract a control implements on every target it is drawn on: measure, then draw.
+ *
+ * - `measure` is shared code. It reads only `state` and the target's {@link MeasureEnv}, so a DOM component and a HUD
+ *   widget measuring the same state in the same theme answer the same box, and a host can lay either out before it
+ *   exists.
+ * - `draw` is per target, and its output is the target's own: a React element for the DOM, draw commands for a
+ *   HUD. It is not handed the measured box. A target that positions by coordinates (a HUD) calls `measure` itself
+ *   with its bounds as {@link exactly}; a DOM target lays its parts out with CSS from the same tokens `measure`
+ *   reads, which a measure-to-DOM test holds it to. A paint sink shared by both was the alternative, and it would
+ *   make the DOM rebuild by hand what its stylesheet already says.
+ *
+ * Both halves read which parts `state` shows from one function the component exports (`buttonParts`,
+ * `listMode`), so neither target can show a part the other lacks.
+ */
+interface HeadlessComponent<S, L, T, O> {
+    measure(state: S, constraints: Constraints, env: MeasureEnv): Measured<L>;
+    draw(state: S, target: T): O;
+}
+
+/** A button's height and type scale. */
+type ButtonSize = 'sm' | 'md';
+/**
+ * What a button shows, as every target reads it. `I` is how a target names an icon (a React node, a glyph name);
+ * measuring only asks whether one is there.
+ */
+interface ButtonFace<I = unknown> {
+    /** The text measured for the label. A label that is not text passes its text content, or `''`. Absent, the
+     *  button has no label part. */
+    readonly label?: string;
+    /** Default `'md'`. */
+    readonly size?: ButtonSize;
+    /** The button is its icon alone, `icon`, in a square box. */
+    readonly iconOnly?: boolean;
+    readonly icon?: I;
+    readonly leadingIcon?: I;
+    readonly trailingIcon?: I;
+    /** A spinner stands in for the leading icon (the icon, when `iconOnly`). */
+    readonly loading?: boolean;
+}
+/** One piece of a button, in the order it is laid out. */
+type ButtonPart = 'spinner' | 'icon' | 'leading' | 'label' | 'trailing';
+/** Which parts `face` shows, left to right. Both targets draw exactly these. */
+declare function buttonParts(face: ButtonFace): ButtonPart[];
+/** A button's sizes in px, read from its theme. */
+interface ButtonMetrics {
+    readonly height: number;
+    /** Inset of the content from each side. 0 on an icon-only button, which is square. */
+    readonly padX: number;
+    /** Between adjacent parts. */
+    readonly gap: number;
+    readonly iconSize: number;
+    readonly spinnerSize: number;
+    readonly font: FontSpec;
+}
+/** The spinner's drawn size at either button size. */
+declare const BUTTON_SPINNER_SIZE = 14;
+/** The tokens a button of `size` is sized by: the same ones ui's `Button.module.css` lays it out with, so the DOM
+ *  button and the HUD one agree in any theme. */
+declare function buttonMetrics(env: MeasureEnv, size?: ButtonSize, iconOnly?: boolean): ButtonMetrics;
+/** Where each of a button's parts sits. */
+interface ButtonLayout {
+    readonly parts: readonly {
+        readonly part: ButtonPart;
+        readonly rect: Rect;
+    }[];
+    readonly metrics: ButtonMetrics;
+}
+/**
+ * A button's box: its control height, and its parts' widths plus gaps plus side padding (square when icon-only),
+ * held to `c`. The parts are centered in the box, as flex centers them. In a box too narrow for them, the label
+ * gives up width first, down to none.
+ */
+declare function measureButton(face: ButtonFace, c: Constraints, env: MeasureEnv): Measured<ButtonLayout>;
+/** Where a press stands: the pointer over the control, and a press held on it. */
+interface PressState {
+    readonly hovered: boolean;
+    readonly held: boolean;
+}
+/** Nothing over the control and nothing held. */
+declare const IDLE_PRESS: PressState;
+/** One pointer event as a press reads it. `inside` says whether the point is over the control. */
+type PressInput = {
+    type: 'down';
+} | {
+    type: 'move' | 'up';
+    inside: boolean;
+} | {
+    type: 'cancel' | 'enter' | 'leave';
+};
+/** What a pointer event does to a press: the new state, and whether it completed one (released over the control
+ *  it went down on). A drag off the control lets go of the hold and a drag back on takes it again, as a native
+ *  button's `:active` does. */
+declare function pressStep(s: PressState, input: PressInput): {
+    state: PressState;
+    pressed: boolean;
+};
+/** Whether a key presses a focused button: Enter or Space, as a native `<button>` takes them. */
+declare function isPressKey(key: string): boolean;
+
+/** What a row list can do, which decides its semantics: nothing (`list`), select (`listbox`), or hold controls in
+ *  its rows (`grid`, since an option may not contain interactive content). */
+type ListMode = 'list' | 'listbox' | 'grid';
+/** What decides a row list's {@link ListMode}. */
+interface ListModeInput {
+    /** Rows are selectable, one or many at once. */
+    readonly selection?: 'single' | 'multi';
+    /** Rows answer a press. */
+    readonly activatable?: boolean;
+    /** Some row holds controls of its own. */
+    readonly controls?: boolean;
+}
+/** A row list's mode: `grid` when a row holds controls or rows activate without selecting, else `listbox` when
+ *  they select, else `list`. */
+declare function listMode(o: ListModeInput): ListMode;
+/** The ARIA roles of a row list's container and its rows, by mode. */
+declare const LIST_ROLES: Readonly<Record<ListMode, {
+    readonly container: string;
+    readonly row: string;
+}>>;
+/** Which edge of row `i` of `count` carries the seam for a drop at gap `dropIndex`, if either. */
+declare function dropSide(dropIndex: number | null | undefined, i: number, count: number): 'before' | 'after' | undefined;
+/** One row as measuring reads it. The leading decoration and the trailing controls are measured by their width. */
+interface RowFace {
+    readonly id: string;
+    readonly label: string;
+    readonly leadingWidth?: number;
+    readonly trailingWidth?: number;
+}
+/** A row list as measuring reads it. */
+interface RowListFace {
+    readonly rows: readonly RowFace[];
+    /** Shown in place of the rows when there are none. Default an em dash, as ui's `ItemList` shows. */
+    readonly empty?: string;
+}
+/** Space between adjacent rows: ui's `ItemList.module.css` `.list { gap: 1px }`. */
+declare const ROW_GAP = 1;
+/** A row list's sizes in px, read from its theme. */
+interface RowListMetrics {
+    readonly rowHeight: number;
+    readonly padX: number;
+    /** Between a row's leading decoration, its label, and its controls. */
+    readonly gap: number;
+    /** The empty state's inset from top and bottom. */
+    readonly emptyPadY: number;
+    readonly font: FontSpec;
+    /** A line of text's height: the font size times `--wzl-leading-snug`, which `.list` sets. */
+    readonly lineHeight: number;
+}
+/** The tokens a row list is sized by: the ones `ItemList.module.css` lays it out with. */
+declare function rowListMetrics(env: MeasureEnv): RowListMetrics;
+/** Where one row and its parts sit, relative to the list's top left. The label fills what the leading
+ *  decoration and the controls leave. */
+interface RowBox {
+    readonly id: string;
+    readonly rect: Rect;
+    readonly leading?: Rect;
+    readonly label: Rect;
+    readonly trailing?: Rect;
+}
+/** Where a row list's rows sit, or its empty state when it has none. */
+interface RowListLayout {
+    readonly rows: readonly RowBox[];
+    readonly empty?: Rect;
+    readonly metrics: RowListMetrics;
+}
+/**
+ * A row list's box: rows a control height tall, {@link ROW_GAP} apart, as wide as the widest row's leading, label
+ * and controls with their gaps and padding, held to `c`. A list stretched to its column passes that width as both
+ * bounds. With no rows it is the empty state's line, padded.
+ */
+declare function measureRowList(face: RowListFace, c: Constraints, env: MeasureEnv): Measured<RowListLayout>;
+/** Index of the row under list-local `y`, or null between rows and past either end. */
+declare function rowAtY(layout: RowListLayout, y: number): number | null;
+
+export { BUTTON_SPINNER_SIZE, type ButtonFace, type ButtonLayout, type ButtonMetrics, type ButtonPart, type ButtonSize, type Constraints, EMPTY_TYPEAHEAD, type EditCause, type EditEnd, type EditEndShape, type FocusScope, type FocusScopeOptions, type FontSpec, type HeadlessComponent, IDLE_PRESS, type KeyPress, type KeySource, LIST_ROLES, type ListMode, type ListModeInput, type ListShape, type MeasureEnv, type Measured, type NudgeKey, type PressInput, type PressState, REPEAT_DELAY_MS, REPEAT_EVERY_MS, ROW_GAP, type RovingResult, type RowBox, type RowFace, type RowKeyAction, type RowKeysShape, type RowListFace, type RowListLayout, type RowListMetrics, type Scheduler, type SliderKeyShape, type SliderStop, type StepRepeat, type StepRepeatOptions, TYPEAHEAD_RESET_MS, type TextExtent, type TreeKeyResult, type TreeShape, type TypeaheadBuffer, type TypeaheadShape, UNBOUNDED, arrowMove, arrowSteps, attract, buttonMetrics, buttonParts, centeredBaseline, clampOrdered, clampTo, createStepRepeat, dropSide, editEnd, envNumber, envPx, exactly, firstStop, fixedWidth, gapByMidpoint, imeKey, isNoopDrop, isNudgeChord, isPressKey, listMode, measureButton, measureRowList, moveItems, movedIndex, nearestGap, nudgeGap, nudgeOf, offsetRect, pressStep, rangeKey, rovingKey, rowAtY, rowKey, rowListMetrics, sliderKey, stepStop, tabSort, tabStep, timerScheduler, treeKey, typeaheadMatch, typeaheadStep, usableStops };