@weasel-js/ui-input 0.0.0-stage → 1.19.0

package/dist/index.d.ts

@@ -0,0 +1,619 @@
+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 `at` in direction `dir`; from `null`, or an index that names no
+ *  item, 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[], at: 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;
+};
+/** Which way an arrow key steps a list of `shape`: 1, -1, or 0 for a key that is not one of its arrows. */
+declare function arrowDir(key: string, shape: ListShape<unknown>): 1 | -1 | 0;
+/** 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: Mod+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. `apple` says `mod` is Command, as
+ * `isApplePlatform` from `@weasel-js/gestures` reads it; otherwise it is Ctrl. 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, apple?: 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;
+/** Whether `text` is one typed character, counted by code point: an emoji is one, though it takes two UTF-16 units. */
+declare function isOneChar(text: string): boolean;
+/** 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 `at` 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. An index
+ *  that names no item searches from the start. */
+declare function typeaheadMatch<T>(items: readonly T[], at: 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;
+};
+
+/** 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 two-way map between a value and its place along a track, as a fraction: 0 at one end, 1 at the other. */
+interface TrackMap {
+    toFraction(v: number): number;
+    toValue(f: number): number;
+}
+/** The stop nearest `v`, or `v` itself when none lies within `tolerance`. With `toFraction` the distance is
+ *  measured along the track and `tolerance` is a track fraction, so evenly spaced stops attract over the same
+ *  distance; without it both are in `v`'s own units. */
+declare function attract(v: number, stops: readonly number[], tolerance: number, toFraction?: (v: number) => number): number;
+/** The map for a track its stops divide evenly, whatever their values: each gap between two stops takes the
+ *  same length, and a value sits between its neighbors in proportion. Needs two stops, ascending. */
+declare function evenMap(stops: readonly number[]): TrackMap;
+/** What a pointer on a slider's track reads: how the track maps to values, and what has a say in the value picked. */
+interface SliderAtShape extends TrackMap {
+    /** The least and greatest value a pointer can pick. Either may be infinite. */
+    min: number;
+    max: number;
+    step?: number;
+    /** Where the step grid starts. Default `min`. */
+    origin?: number;
+    /** Values the pointer is pulled onto. */
+    stops?: readonly number[];
+    /** How near a stop pulls, as a track fraction. Default 0: only a pointer exactly on a stop lands on it. */
+    pull?: number;
+    /** Only a stop can be picked: the nearest, however far. */
+    strict?: boolean;
+    /** Pass the stops by. Not read under `strict`. */
+    free?: boolean;
+}
+/** The value a pointer at track fraction `f` picks: the track's value there, on the step grid and inside
+ *  `min` to `max`, then pulled onto a stop within reach. */
+declare function sliderAt(f: number, shape: SliderAtShape): number;
+/** Keep thumb `index` strictly between its neighbors: a step apart, or a thousandth of the span without one, and
+ *  inside `min` to `max`. Neighbors too close for that hold it between them, or failing that inside `min` to `max`. */
+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;
+
+/** A stretch of values: a track's whole range, or the part of it a track shows. */
+interface Span {
+    from: number;
+    to: number;
+}
+/** Where `v` sits along `span`, as a fraction: 0 at `from`, 1 at `to`, and outside that past either end.
+ *  0 for an empty span. */
+declare function spanPlace(span: Span, v: number): number;
+/** The value at fraction `f` of `span`. */
+declare function spanValue(span: Span, f: number): number;
+/** A length as a fraction of `span`'s. Unlike {@link spanPlace} it measures no position, so `span.from` has no say. */
+declare function spanShare(span: Span, length: number): number;
+/** `span` laid linearly along a track: the map {@link sliderAt} and {@link attract} read. Unclamped, so a
+ *  place off either end of the track maps to a value outside the span. */
+declare function spanMap(span: Span): TrackMap;
+/** `span` moved inside `bounds`, keeping its length, or shortened to `bounds` where it is the longer. */
+declare function spanHold(span: Span, bounds: Span): Span;
+/** `span` shifted by `by` inside `bounds`, keeping its length. */
+declare function spanPan(span: Span, by: number, bounds: Span): Span;
+/** `span` scaled by `factor` about `at`, which keeps its place along the track unless `bounds` push it.
+ *  A `factor` below 1 narrows. The result is no shorter than `minLength` and no longer than `bounds`. */
+declare function spanZoom(span: Span, at: number, factor: number, bounds: Span, minLength?: number): Span;
+
+/** 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`. An index outside
+ *  `items`, or not a whole number, names nothing and is ignored; a gap past either end is that end. */
+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;
+/**
+ * Which part of an item a pointer at fraction `f` along it is over: the leading `band` of it drops before, the
+ * trailing `band` after, and what lies between drops into it. The default `band` of a half leaves no middle, which
+ * is an item that cannot take a drop into it, split at its midpoint.
+ */
+declare function dropBand(f: number, band?: number): 'before' | 'into' | 'after';
+/** 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;
+
+/** A box on a surface, by its top-left corner and size. */
+interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+/** How near an edge a dragged pointer starts a scroll, in px, unless a caller says otherwise. */
+declare const EDGE_SCROLL_MARGIN = 48;
+/**
+ * How hard a pointer at `p` pushes `span` to scroll, from -1 toward `from` to 1 toward `to`: 0 while `p` is
+ * `margin` or more inside both ends, rising linearly to full strength at an end and holding it past there, so
+ * overshooting does not reverse the scroll. A span narrower than two margins scrolls toward the nearer end.
+ */
+declare function edgePush(span: Span, p: number, margin?: number): number;
+/** {@link edgePush} on both axes of a scrolling box: multiply by a top speed for how far to scroll. */
+declare function edgeScroll(bounds: Box, point: {
+    x: number;
+    y: number;
+}, margin?: number): {
+    x: number;
+    y: number;
+};
+
+/** A way to move across a surface, in its own x and y: y grows downward. */
+type Heading = 'left' | 'right' | 'up' | 'down';
+/** How much a unit of drift across a heading costs against a unit of travel along it. */
+declare const HEADING_DRIFT = 2;
+/** The heading an arrow key asks for, or null for any other key. */
+declare function headingOf(key: string): Heading | null;
+/**
+ * What it costs to go from `from` to `to` on `heading`, center to center: the travel along the heading plus
+ * `drift` times the distance across it, so a target straight ahead beats a nearer one off to the side. Null for
+ * a target that is not ahead at all.
+ */
+declare function headingCost(from: Box, to: Box, heading: Heading, drift?: number): number | null;
+/** Which of `targets` focus moves to from `from` on `heading`: the index of the cheapest by {@link headingCost},
+ *  the earlier of two that tie, or -1 when none is ahead. A target with no box is passed over. */
+declare function nearestToward(from: Box, targets: readonly (Box | null | undefined)[], heading: Heading, drift?: number): number;
+
+/** 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>;
+
+/**
+ * A parameter's domain, apart from how it is walked. A scrubber reads it
+ * continuously, one value at a time (`at`); a stepped sequence reads every
+ * step at once (`walk`). Time is one domain among others (`frames`).
+ */
+interface Sweep<V> {
+    /** The value `u` of the way along, 0 to 1, clamped: a scrubber's reading. A
+     *  domain of discrete steps answers its nearest step. */
+    at(u: number): V;
+    /** Every step in order: a sequence's reading. May never end; `stepsOf` caps it. */
+    walk(): Iterable<V>;
+    /** How a value reads in a caption or a readout. */
+    label(value: V): string;
+}
+/** How many steps `stepsOf` takes from a sweep that has not ended by then. */
+declare const SWEEP_CAP = 256;
+/** The first `cap` steps of `sweep`, and whether it had more. `cap` is a whole number, 0 or more. */
+declare function stepsOf<V>(sweep: Sweep<V>, cap?: number): {
+    steps: V[];
+    capped: boolean;
+};
+/** What {@link range} walks: its ends, and either a `step` or a `count`. */
+type RangeSpec = {
+    from: number;
+    /** May be `Infinity`, for a walk that only `until` or a cap ends. */
+    to: number;
+    label?: (value: number) => string;
+} & ({
+    step: number;
+    count?: never;
+} | {
+    count: number;
+    step?: never;
+});
+/**
+ * Numbers from `from` to `to`, either `step` apart (the last step at or before
+ * `to`) or `count` of them evenly spaced, both ends included. With `step`, `at`
+ * snaps to a step; with `count` it is continuous, as the steps are only samples.
+ */
+declare function range(spec: RangeSpec): Sweep<number>;
+/** The values of a list, in its order; `at` snaps to the nearest. */
+declare function values<V>(list: readonly V[], label?: (value: V) => string): Sweep<V>;
+/** What `frames` reads of a clock's declaration; a `ClockSpec` is one. */
+interface FrameSpan {
+    /** ms per pass; omitted, the run never ends. */
+    duration?: number;
+    /** Passes: `true` endless, `false` one, `n` that many. */
+    loop?: boolean | number;
+    /** The time elapsed 0 is shown as, for the labels. */
+    origin?: number;
+}
+/** How {@link frames} walks a clock's run. */
+interface FrameOptions {
+    /** ms between frames. */
+    every: number;
+    /** `'first'`, the default, walks one pass; `'all'` walks the whole run, which
+     *  for an endless loop never ends. */
+    passes?: 'first' | 'all';
+    label?: (elapsed: number) => string;
+}
+/**
+ * The frames of a clock's run, as elapsed ms, `every` apart from 0. A run that
+ * ends shows its last frame; a pass that loops back stops short of its end,
+ * which is the next pass's start. `at` is continuous over the span walked.
+ */
+declare function frames(span: FrameSpan, options: FrameOptions): Sweep<number>;
+/** `sweep` walked only as far as the step before the first one `done` accepts:
+ *  "every frame until it repeats". `at` is the inner sweep's. */
+declare function until<V>(sweep: Sweep<V>, done: (value: V, index: number) => boolean): Sweep<V>;
+
+/** Where a last row shorter than the rest sits: at the start, centered, at the end, or with its items stretched
+ *  across the whole row. */
+type LastRow = 'start' | 'center' | 'end' | 'fill';
+/** How a run of items tiles. */
+interface Tiling {
+    /** Items per row: a whole number, one for anything below one, and at most 2^24. */
+    columns: number;
+    /** Where a last row shorter than `columns` sits. Default `'start'`. */
+    lastRow?: LastRow;
+}
+/** How far in, in columns, a row of `length` items sits in a grid `columns` across, aligned `align`. A
+ *  stretched (`'fill'`) row starts at the start. */
+declare function rowOffset(length: number, columns: number, align?: LastRow): number;
+/** Where a tiling's items sit on its tracks. */
+interface TileGrid {
+    /** Tracks across: twice `columns`, so a short row can sit a half column in, or enough for both a full row and a
+     *  stretched one to divide evenly. */
+    tracks: number;
+    /** Tracks a full row's item spans. */
+    span: number;
+    /** Tracks a stretched last row's item spans. */
+    fillSpan: number;
+    /** How far an offset last row sits from the start, in tracks; 0 for one at the start, stretched, or none. */
+    lead: number;
+    /** Index of the last row's first item. */
+    lastStart: number;
+    /** Whether item `i` is in a stretched last row. */
+    stretched(i: number): boolean;
+    /** The grid's outer corners item `i` sits on: `ss` top-left, `se` top-right, `es` bottom-left, `ee` bottom-right,
+     *  in the inline direction. */
+    corners(i: number): ('ss' | 'se' | 'es' | 'ee')[];
+}
+/** How `count` items tile under `spec`. */
+declare function tileGrid(count: number, spec: Tiling): TileGrid;
+/** How a grid's rows sit for {@link rovingGridTarget}. */
+interface GridLayout {
+    dir?: 'ltr' | 'rtl';
+    /** How many columns in each row's first item sits, by row: a short row centered in an even gap sits a half
+     *  column in. Omitted rows start at column 0. */
+    offsets?: readonly number[];
+    /** How many columns wide each row's items are, by row: a stretched last row's are wider than one. Omitted
+     *  rows' items are one column wide. */
+    widths?: readonly number[];
+}
+/** The rows of `count` items `columns` across, as item indices in reading order. */
+declare function tileRows(count: number, across: number): number[][];
+/** Where `key` takes focus from `current` among `count` items tiled by `spec`, by {@link rovingGridTarget}: null
+ *  if it does not move it. Every item is enabled unless `enabled` says otherwise. */
+declare function tileKey(current: number, key: string, count: number, spec: Tiling, opts?: {
+    dir?: 'ltr' | 'rtl';
+    enabled?: readonly boolean[];
+}): number | null;
+/** The layout of `rows` in a grid `columns` across whose short rows sit as `lastRow` says. */
+declare function gridLayout(rows: readonly (readonly number[])[], across: number, lastRow?: LastRow): GridLayout;
+/** Where `key` takes focus from `current` in a grid whose `rows` list item indices in reading order, or null if
+ *  it does not move it. Left and Right step through the enabled items in reading order (swapped under `'rtl'`),
+ *  wrapping, and Home and End go to the first and last. Up and Down move to the item under this one in the next
+ *  row, by where each row sits, or to that row's nearest end when none is under it; they pass over rows where that
+ *  item is disabled, and stop at the first and last rows. */
+declare function rovingGridTarget(current: number, key: string, enabled: readonly boolean[], rows: readonly (readonly number[])[], layout?: GridLayout): number | null;
+
+/**
+ * Selection: which of a run of items are on. One spec answers what each item
+ * shows, what a click on it does, what the arrow keys do, and how a sweep
+ * sets several at once, so a component taking it cannot get one of them
+ * wrong. Build a model with {@link selection} (one value, or a list of them)
+ * or {@link selectionOfEach} (items that each own a boolean); {@link selectionKeys}
+ * says what the keyboard does with it.
+ */
+/** An item's state: on, off, or mixed, where the sources it aggregates disagree. */
+type SelectState = 'off' | 'on' | 'mixed';
+/** At most one item on, held as its value or `null`. */
+interface SingleSelection<V> {
+    mode?: 'single';
+    value: V | null;
+    onChange: (next: V | null) => void;
+    /** A click on the item that is on turns it off. Default false. */
+    allowDeselect?: boolean;
+    /** Values drawn mixed, where `value` holds none of them. A click on one chooses it. */
+    mixedValues?: readonly V[];
+    /** The arrow keys choose the item they land on, as a radio group's do. Default true; false moves focus only,
+     *  and Space or Enter chooses. */
+    followsFocus?: boolean;
+}
+/** Any number of items on, held as a list of their values. */
+interface MultipleSelection<V> {
+    mode: 'multiple';
+    value: readonly V[];
+    onChange: (next: V[]) => void;
+    /**
+     * Values that are neither on nor off: the sources this aggregates disagree (a text range bold in part of it, a
+     * multi-selection whose nodes differ). `value` wins where the two lists overlap. A click on one turns it on.
+     */
+    mixedValues?: readonly V[];
+}
+/** One spec for a run of items whose selection is one value or a list of them. */
+type SelectionSpec<V> = SingleSelection<V> | MultipleSelection<V>;
+/** One item that owns its own on/off state. */
+interface OwnSelection {
+    selected: boolean;
+    onChange: (next: boolean) => void;
+}
+/** A run of changes to a selection, each from where the last left it: a sweep's. */
+interface SelectionEdit {
+    /** Set item `index` on or off. */
+    set(index: number, on: boolean): void;
+    /** Put back what the edit started from. */
+    revert(): void;
+}
+/** A selection over items by index. */
+interface SelectionModel {
+    /** At most one item on, or any number. */
+    readonly mode: 'single' | 'multiple';
+    stateOf(index: number): SelectState;
+    /** What a click on item `index` does: choose it, or flip it. */
+    press(index: number): void;
+    /** Start a run of changes. Each `set` reports as it happens, from the edit's own copy, so a run faster than
+     *  the component re-renders loses none of them. */
+    edit(): SelectionEdit;
+    /** The arrow keys choose as they move. */
+    readonly followsFocus: boolean;
+}
+/** `spec`'s selection over `values`, one per item in order. */
+declare function selection<V>(spec: SelectionSpec<V>, values: readonly V[]): SelectionModel;
+/** The selection of items that each own their state: any number on, and nothing mixed. */
+declare function selectionOfEach(items: readonly OwnSelection[]): SelectionModel;
+/** A sweep over `model` from a press on item `from`: each item it `reach`es is set to the opposite of whether the
+ *  pressed one was on, so a drag from an off or mixed item turns on everything it crosses and one from an on item
+ *  turns it off. `revert` puts back what the sweep started from. */
+declare function sweepFrom(model: SelectionModel, from: number): {
+    reach(index: number): void;
+    revert(): void;
+};
+/** What the keyboard does with `model`'s items. Where a single selection follows focus, the tab stop sits on the
+ *  chosen item and an arrow landing on one chooses it; otherwise the arrows only move focus, and Space or Enter
+ *  presses. `enabled(i)` is false for an item nothing may choose. */
+declare function selectionKeys(model: SelectionModel, count: number, enabled?: (index: number) => boolean): {
+    tabStop?: number;
+    landed?: (index: number) => void;
+    activate?: (index: number) => void;
+};
+
+export { EDGE_SCROLL_MARGIN, EMPTY_TYPEAHEAD, HEADING_DRIFT, REPEAT_DELAY_MS, REPEAT_EVERY_MS, SWEEP_CAP, TYPEAHEAD_RESET_MS, arrowDir, arrowMove, arrowSteps, attract, clampOrdered, createStepRepeat, dropBand, edgePush, edgeScroll, editEnd, evenMap, firstStop, frames, gapByMidpoint, gridLayout, headingCost, headingOf, imeKey, isNoopDrop, isNudgeChord, isOneChar, moveItems, movedIndex, nearestGap, nearestToward, nudgeGap, nudgeOf, range, rangeKey, rovingGridTarget, rovingKey, rowKey, rowOffset, selection, selectionKeys, selectionOfEach, sliderAt, sliderKey, spanHold, spanMap, spanPan, spanPlace, spanShare, spanValue, spanZoom, stepStop, stepsOf, sweepFrom, tabSort, tabStep, tileGrid, tileKey, tileRows, timerScheduler, treeKey, typeaheadMatch, typeaheadStep, until, usableStops, values };
+export type { Box, EditCause, EditEnd, EditEndShape, FrameOptions, FrameSpan, GridLayout, Heading, KeyPress, KeySource, LastRow, ListShape, MultipleSelection, NudgeKey, OwnSelection, RangeSpec, RovingResult, RowKeyAction, RowKeysShape, Scheduler, SelectState, SelectionEdit, SelectionModel, SelectionSpec, SingleSelection, SliderAtShape, SliderKeyShape, SliderStop, Span, StepRepeat, StepRepeatOptions, Sweep, TileGrid, Tiling, TrackMap, TreeKeyResult, TreeShape, TypeaheadBuffer, TypeaheadShape };