@box-kite/react 0.0.1 → 2.0.0

package/utils/dom/domUtils.d.ts

@@ -0,0 +1,32 @@
+/**
+ * "Did this happen inside that?" — the question behind every popup that closes when you click away, asked
+ * identically by `useVisibility` and `useDismiss`. `ElementLike` is structural rather than
+ * `React.RefObject`, which keeps the file framework-free. Named exports rather than a namespace, for the
+ * reason in `environmentUtils.ts`: a namespace object cannot be tree-shaken a function at a time.
+ */
+export type ElementLike = {
+    readonly current: Element | null;
+} | Element | null | undefined;
+/** The element behind a ref or an element, whichever the caller happens to be holding. */
+export declare function elementOf(value: ElementLike): Element | null;
+/** The same, narrowed to an `HTMLElement` — for callers that need `focus()` or `style`. */
+export declare function htmlElementOf(value: ElementLike): HTMLElement | null;
+/**
+ * Whether an event happened inside any of these elements. `composedPath()` first, so an event from a
+ * shadow root counts as inside its host; `contains()` as the fallback, since the path is populated only
+ * while the event is being dispatched.
+ */
+export declare function isEventInside(event: Event, elements: readonly ElementLike[]): boolean;
+/**
+ * Whether this element reads right to left — the direction the browser *resolved*, which is the only
+ * form of the answer that accounts for a `dir="auto"` or a `<bdi>` above it. Nothing but
+ * `getComputedStyle` knows it, and jsdom computes no direction at all, so a test environment reads as
+ * left to right — which is the initial value anyway.
+ */
+export declare function isRtl(value: ElementLike): boolean;
+/**
+ * Drop whatever the document has selected. A double press selects the word under it before any handler
+ * runs, so a widget that *replaces* what was pressed leaves a range over content that no longer exists —
+ * which the browser repairs to the nearest boundary and then paints over whatever is rendered inside it.
+ */
+export declare function clearSelection(element: ElementLike): void;

package/utils/environment/environmentUtils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * "Is there a DOM, and what may I touch?" — asked in seven places and once answered with a hand-written
+ * `typeof` in each. The answers are not interchangeable: a server render has no `document`, a `document`
+ * may have no `<head>`, and `matchMedia` is missing from environments that look like browsers. Named
+ * exports rather than a namespace, which compiles to an IIFE that ships whole, and every chunk imports this.
+ */
+/** A browser: a window with a document. What an effect that touches layout needs to exist. */
+export declare function isBrowser(): boolean;
+/** Whether there is a document at all — false during a server render. */
+export declare function hasDocument(): boolean;
+/** The document, or null when there is none, so a caller can `?.` instead of branching. */
+export declare function documentOrNull(): Document | null;
+/** The document root (`<html>`), or null when there is no DOM. */
+export declare function documentRoot(): Element | null;
+/** The `<head>` to write a stylesheet into, or null when there is nothing to write to. */
+export declare function documentHead(): HTMLHeadElement | null;
+/**
+ * Whether the browser has the Popover API, which is what puts a floating layer in the top layer. Asked
+ * per mount rather than cached, so a test can install the contract and answer for the browser.
+ */
+export declare function supportsPopover(): boolean;
+/**
+ * Whether the browser owns a `<dialog>`'s light dismiss: `closedby="any"` closes it on a press outside,
+ * and `closedby="closerequest"` gives a non-modal one Escape. Asked per mount, like `supportsPopover`.
+ */
+export declare function supportsDialogClosedBy(): boolean;
+/** A media query, or null where `matchMedia` does not exist — a server, or a bare jsdom. */
+export declare function matchMedia(query: string): MediaQueryList | null;

package/utils/export/csvUtils.d.ts

@@ -0,0 +1,23 @@
+/**
+ * CSV, to RFC 4180, plus the two things a spreadsheet adds to it: a byte-order mark, without which Excel
+ * reads UTF-8 as the local code page and mangles every accented name, and the leading characters that
+ * make a *value* into a formula.
+ */
+declare namespace CsvUtils {
+    interface Options {
+        /** The field separator. A semicolon is what a spreadsheet expects in a locale using a decimal comma. */
+        delimiter?: string;
+        /**
+         * Prefix a value beginning `=`, `+`, `-` or `@` with a quote, so a spreadsheet reads it as text.
+         * On by default: a cell somebody typed is data, and a downloaded file that runs it is CSV injection.
+         */
+        escapeFormulas?: boolean;
+    }
+    /** What Excel needs at the top of the file to read the rest of it as UTF-8. */
+    const BOM = "\uFEFF";
+    /** One value as a field: quoted when it holds a delimiter, a quote or a newline, and never otherwise. */
+    function field(value: unknown, options?: Options): string;
+    /** The whole file. Rows are joined with CRLF, which is what the RFC specifies and what Excel writes. */
+    function csv(rows: unknown[][], options?: Options): string;
+}
+export default CsvUtils;

package/utils/export/downloadUtils.d.ts

@@ -0,0 +1,12 @@
+/** Handing a file the page generated to the person looking at it. */
+declare namespace DownloadUtils {
+    /**
+     * A file the browser saves. There is no API for "save this" — an anchor with a `download` attribute is
+     * the mechanism, so the link is created, clicked and removed within the call.
+     *
+     * The object URL is revoked on the next task rather than immediately: Safari reads it *after* the click
+     * handler returns, and a revoke in the same turn leaves the file empty.
+     */
+    function download(data: BlobPart, fileName: string, type: string): void;
+}
+export default DownloadUtils;

package/utils/export/xlsxUtils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A spreadsheet, written out. An `.xlsx` is a ZIP of XML parts (ECMA-376), so the whole format is a
+ * handful of strings and `ZipUtils` — which is why this library exports Excel with no dependency to
+ * install and nothing added to the grid's bundle until somebody presses the button.
+ *
+ * What is here is the part a table needs: values that keep their type, a number format, a bold header on
+ * a fill, column widths, a frozen header row, an auto-filter, and outline levels so a grouped grid opens
+ * in Excel grouped. What is not here is everything else a workbook can hold — formulas, several sheets,
+ * images, charts, conditional formats. This is a writer for one table, not an Excel implementation.
+ */
+declare namespace XlsxUtils {
+    /** What a cell can hold. A `Date` is written as Excel's own serial number, with a date format on it. */
+    type Value = string | number | boolean | Date | null | undefined;
+    /** One cell's appearance. Each distinct combination becomes one entry in the workbook's style table. */
+    interface Style {
+        bold?: boolean;
+        /** `RRGGBB`, the only colour spelling a workbook has — it carries no theme and no palette. */
+        color?: string;
+        fill?: string;
+        /** An Excel number format, `'#,##0.00'` or `'yyyy-mm-dd'`. */
+        format?: string;
+        align?: 'left' | 'center' | 'right';
+        /** Indent steps, which is how a grouped row is stepped in beside its outline level. */
+        indent?: number;
+    }
+    interface Cell {
+        value: Value;
+        style?: Style;
+    }
+    interface Row {
+        cells: Cell[];
+        /** Outline level: 0 is top level, and a row one deeper is a child of the last row above it. */
+        level?: number;
+        /** Collapsed out of sight, which is how a collapsed group in the grid opens collapsed in Excel. */
+        hidden?: boolean;
+        /** On the summary row of a collapsed group — the row carrying the outline's own toggle. */
+        collapsed?: boolean;
+    }
+    interface Sheet {
+        name: string;
+        /** Column widths in characters, one per column; `undefined` leaves Excel's default. */
+        widths: (number | undefined)[];
+        rows: Row[];
+        /** How many rows stay on screen when the sheet is scrolled. */
+        freeze?: number;
+        /** Whether the header row gets Excel's filter buttons. A grouped sheet is given none. */
+        autoFilter?: boolean;
+    }
+    /** Text as XML content. The control characters XML 1.0 has no spelling for are dropped rather than escaped. */
+    function escape(text: string): string;
+    /** A column's letters, the way a spreadsheet names one: 0 is `A`, 26 is `AA`. */
+    function columnName(index: number): string;
+    /** The six parts of a one-sheet workbook, zipped. */
+    function workbook(sheet: Sheet): Uint8Array<ArrayBuffer>;
+}
+export default XlsxUtils;

package/utils/export/zipUtils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The half of the ZIP format a spreadsheet needs. An `.xlsx` is a ZIP of XML parts, and the format allows
+ * an entry to be *stored* rather than deflated — so a workbook can be written with no compressor and no
+ * dependency at all. Excel reads a stored archive exactly as it reads a compressed one; the file is
+ * larger, and it is XML, so a gzipped download is the same size either way.
+ *
+ * Every entry carries the same DOS timestamp (1980-01-01, the epoch the format starts at), which is what
+ * makes the same table export byte-for-byte the same file twice.
+ */
+declare namespace ZipUtils {
+    /** One file in the archive: the path it is stored under, and its bytes. */
+    interface Entry {
+        name: string;
+        data: Uint8Array;
+    }
+    /** The checksum every ZIP entry carries, in both of its headers. */
+    function crc32(data: Uint8Array): number;
+    /** A part's text as the bytes it is stored as. Every part of a workbook is UTF-8 XML. */
+    function utf8(text: string): Uint8Array;
+    /**
+     * The archive, as one buffer: every entry's local header and bytes, then a central directory repeating
+     * those headers with each entry's offset, then the record saying where the directory starts.
+     */
+    function zip(entries: Entry[]): Uint8Array<ArrayBuffer>;
+}
+export default ZipUtils;

package/utils/fn/fnUtils.d.ts

@@ -0,0 +1,4 @@
+declare namespace FnUtils {
+    function throttle<T extends unknown[]>(callback: (...args: T) => void, wait?: number): (...args: T) => void;
+}
+export default FnUtils;

package/utils/form/formUtils.d.ts

@@ -0,0 +1,8 @@
+type FormValue = string | string[] | number | number[] | boolean;
+interface FormObject {
+    [index: string]: FormValue | FormObject;
+}
+declare namespace FormUtils {
+    function getFormEntries(form: HTMLFormElement): FormObject;
+}
+export default FormUtils;

package/utils/keyboard/typeaheadUtils.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Type-to-find over a list, which every APG list pattern asks for and all of them the same way: a
+ * listbox, a menu, a tree. Framework-free, so the buffer is a plain object the caller keeps.
+ */
+declare namespace TypeaheadUtils {
+    /** How long a buffer stays open, per APG. */
+    const TIMEOUT = 1000;
+    /** What a caller keeps between keystrokes: what has been typed, and when the last key arrived. */
+    interface Buffer {
+        query: string;
+        at: number;
+    }
+    /** A key that types a character, rather than one that commands something. */
+    function isPrintable(event: {
+        key: string;
+        ctrlKey?: boolean;
+        metaKey?: boolean;
+        altKey?: boolean;
+    }): boolean;
+    /** Whether the buffer is still the one the user is typing into. */
+    function isOpen(buffer: Buffer, timeStamp: number): boolean;
+    /** Adds a keystroke, starting a fresh buffer when the last one has expired, and returns what to search for. */
+    function push(buffer: Buffer, key: string, timeStamp: number): string;
+    /**
+     * The item a query points at, or `-1`. One character — or the same one repeated, which is how a user
+     * cycles through a letter — searches from *after* the current item; a longer buffer is a real prefix
+     * and searches from it, so further letters narrow instead of skipping.
+     */
+    function target(query: string, from: number, count: number, textOf: (index: number) => string, isDisabled?: (index: number) => boolean): number;
+}
+export default TypeaheadUtils;

package/utils/memo.d.ts

@@ -0,0 +1,10 @@
+export interface Memo<T> {
+    value: T;
+    clear(): void;
+}
+/**
+ * Lazily-computed cached value with explicit dependency edges. Upstream memos go in `deps` as a thunk, so
+ * they can reference siblings whatever the declaration order; clearing a dep cascades, so a mutation only
+ * has to clear the root that changed.
+ */
+export default function memo<T>(action: () => T, deps?: () => Memo<unknown>[]): Memo<T>;

package/utils/menu/menuUtils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which item a menu's keyboard lands on, read off the DOM rather than out of a registry: a menu's items
+ * are real focusable elements, and their order is the order they are written in — including the ones a
+ * consumer wrapped in a group, put behind a condition, or declared in a submenu of its own.
+ */
+declare namespace MenuUtils {
+    /** The three roles an item can carry. A separator, a group and a label are not items. */
+    const ITEM_SELECTOR = "[role=\"menuitem\"],[role=\"menuitemcheckbox\"],[role=\"menuitemradio\"]";
+    /** Whether this panel is the menu a node belongs to, rather than one nested inside it. */
+    function owns(panel: Element, node: EventTarget | null): boolean;
+    /** The items a panel owns, in DOM order. A submenu's items belong to the submenu, however deep it sits. */
+    function items(panel: Element): HTMLElement[];
+    /**
+     * A disabled item, which is `aria-disabled` and never the `disabled` attribute: APG asks that a
+     * disabled menu item stay focusable, so that a keyboard user can find out it is there at all.
+     */
+    function isDisabled(item: Element): boolean;
+    /** An item that opens a submenu. */
+    function isSubTrigger(item: Element): boolean;
+    /** The next item in a direction, wrapping at the ends the way a menu does. Nothing is skipped — see `isDisabled`. */
+    function step(items: readonly HTMLElement[], from: number, delta: number): HTMLElement | undefined;
+    /** The item a typed prefix points at, on the shared APG rules. */
+    function typeaheadTarget(items: readonly HTMLElement[], query: string, from: number): HTMLElement | undefined;
+}
+export default MenuUtils;

package/utils/object/objectUtils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Object helpers that know nothing about the prop registry — which is what lets both packages import
+ * this file. `mergeDeep` used to live here and does not any more: it reads `pseudo2`, so it belongs in
+ * `src/core/mergeDeep.ts` (see the note there).
+ */
+declare namespace ObjectUtils {
+    function buildProps<T extends {
+        props?: object;
+    }, TKey extends keyof T>(props: T, keys: Readonly<TKey[]>, extraTagProps?: object): T;
+    function isObject(value: unknown): value is object;
+    function isKeyOf<T extends object>(key: any, obj: T): key is keyof T;
+}
+export default ObjectUtils;

package/utils/slider/sliderUtils.d.ts

@@ -0,0 +1,67 @@
+/** Which axis the thumbs run along. Horizontal is the reading axis, so its arrows mirror in a right-to-left page. */
+export type SliderOrientation = 'horizontal' | 'vertical';
+/** What a key means on a thumb: one step, one page, or a jump to an end of the range. */
+export interface SliderMove {
+    kind: 'step' | 'page' | 'edge';
+    /** `1` towards the maximum, `-1` towards the minimum. */
+    delta: number;
+}
+/** The scale a slider measures on. `step` is the grid every value but `min` and `max` lands on. */
+export interface SliderScale {
+    min: number;
+    max: number;
+    step: number;
+}
+/**
+ * Where a thumb sits and what a pointer means, with no DOM and no React in it. The geometry is
+ * deliberately physical — a rectangle has no reading order — and the one place direction enters is
+ * `moveFor`, which is the half of a right-to-left slider no logical property can fix.
+ */
+declare namespace SliderUtils {
+    /**
+     * How many decimals a step carries, so a value snapped onto its grid does not come back as
+     * `0.30000000000000004`. An exponent-form step (`1e-7`) has no readable decimals, so it snaps at the
+     * float's own precision instead.
+     */
+    function decimals(step: number): number;
+    /** Inside the scale, nothing else. */
+    function clamp(value: number, min: number, max: number): number;
+    /**
+     * The nearest value on the step grid, counted from `min`. A `max` that is not itself on the grid stays
+     * out of reach here — End is what puts a thumb on it, the way a native range input does.
+     */
+    function snap(value: number, scale: SliderScale): number;
+    /** Where a value sits on the scale, 0–100. A scale with no width puts everything at its start. */
+    function percent(value: number, min: number, max: number): number;
+    /** The same as a CSS length, rounded to a hundredth of a percent — finer than any screen, and short enough to compare. */
+    function percentage(value: number, min: number, max: number): string;
+    /** Whatever shape the consumer gave, as the array the component works in. */
+    function thumbs(value: number | readonly number[]): number[];
+    /** And back out again, in the shape it arrived as: a number in, a number out. */
+    function shaped<T extends number | number[]>(sample: T, values: readonly number[]): T;
+    /**
+     * One thumb moved, held between its neighbours. A thumb may meet the one beside it and never pass it:
+     * crossing would renumber the thumbs under the focus that is on one of them.
+     */
+    function move(values: readonly number[], index: number, next: number, scale: SliderScale): number[];
+    /** Whether two sets of thumbs say the same thing, so a drag that moved nothing costs no render. */
+    function same(left: readonly number[], right: readonly number[]): boolean;
+    /**
+     * Which thumb a press belongs to: the nearest, and the *last* of two equally near ones, so a pair
+     * sitting on top of each other at the minimum can still be pulled apart.
+     */
+    function nearest(values: readonly number[], target: number): number;
+    /**
+     * The value a pointer is over. Physical coordinates against a physical rectangle: a vertical slider
+     * counts up from its bottom edge, and a right-to-left one from its right.
+     */
+    function valueAt(rect: DOMRect, clientX: number, clientY: number, orientation: SliderOrientation, rtl: boolean): number;
+    /**
+     * What a key does on a thumb. Both arrow pairs work on both orientations, which is APG's rule — and
+     * only the sideways pair mirrors, because the block axis has no reading order to follow.
+     */
+    function moveFor(key: string, rtl?: boolean): SliderMove | undefined;
+    /** Where a move lands, before the neighbours have their say. An edge move ignores the grid: End is `max` itself. */
+    function moved(current: number, key: SliderMove, scale: SliderScale, largeStep: number): number;
+}
+export default SliderUtils;

package/utils/string/fuzzySearch.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Fuzzy search implementation for text matching.
+ * Matches characters in order but not necessarily consecutively.
+ */
+export interface FuzzyMatch {
+    score: number;
+    matches: [number, number][];
+}
+/**
+ * Performs fuzzy matching of a pattern against a target string.
+ * Returns a match object with score and matched ranges, or null if no match.
+ */
+export declare function fuzzyMatch(pattern: string, target: string): FuzzyMatch | null;
+/**
+ * Simple fuzzy search that returns true if the pattern matches the target.
+ */
+export declare function fuzzySearch(pattern: string, target: string): boolean;
+/**
+ * Fuzzy search across multiple fields of an object.
+ * Returns true if the pattern matches any of the specified fields.
+ */
+export declare function fuzzySearchObject<T extends object>(pattern: string, obj: T, fields?: (keyof T)[]): boolean;
+/**
+ * Get the best fuzzy match score across multiple fields.
+ * Returns the highest score found, or 0 if no match.
+ */
+export declare function fuzzySearchObjectScore<T extends object>(pattern: string, obj: T, fields?: (keyof T)[]): number;

package/utils/string/stringUtils.d.ts

@@ -0,0 +1,4 @@
+declare namespace StringUtils {
+    function capitalize(str: string): string;
+}
+export default StringUtils;

package/utils/tabs/tabsUtils.d.ts

@@ -0,0 +1,75 @@
+/** Which way a tablist runs. Horizontal is the reading axis, so its arrows mirror in a right-to-left page. */
+export type TabsOrientation = 'horizontal' | 'vertical';
+/** What a key means in a tablist: a step to the neighbouring tab, or a jump to an end. */
+export interface TabsMove {
+    kind: 'step' | 'edge';
+    /** `1` forward, `-1` back — and on an `edge` move, the first tab or the last. */
+    delta: number;
+}
+/** Where a tab sits inside its list, along the axis the tabs run on. Physical pixels: a measured length has no reading order. */
+export interface TabsBounds {
+    /** From the list's own start edge — its left horizontally, its top vertically. */
+    start: number;
+    /** The tab's own length on that axis. */
+    size: number;
+}
+/**
+ * Which tab a tablist's keyboard lands on, read off the DOM rather than out of a registry: a tab is a real
+ * focusable element and its position is where it was written — including one a consumer wrapped, put
+ * behind a condition, or rendered from a list. The measurements the travelling indicator and the resizing
+ * panel container need are here for the same reason: what is on screen is the only thing that knows.
+ */
+declare namespace TabsUtils {
+    const TAB_SELECTOR = "[role=\"tab\"]";
+    const LIST_SELECTOR = "[role=\"tablist\"]";
+    const PANEL_SELECTOR = "[role=\"tabpanel\"]";
+    /** Whether this tablist is the one a node belongs to, rather than one nested inside it. */
+    function owns(list: Element, node: EventTarget | null): boolean;
+    /** The tabs a tablist owns, in DOM order. A nested set of tabs belongs to its own list. */
+    function tabs(list: Element | null | undefined): HTMLElement[];
+    /**
+     * A tab no selection can land on. Skipped by every movement, unlike a disabled menu item, which APG asks
+     * stay reachable: selection follows focus here, so a tab focus could reach and selection could not would
+     * leave the pattern with no state to be in.
+     */
+    function isDisabled(tab: Element): boolean;
+    /** What a tab stands for. The one thing the markup has to carry for the model to work. */
+    function valueOf(tab: HTMLElement): string | undefined;
+    /**
+     * A value turned into an id fragment. `aria-controls` is a space-separated list and the id has to survive
+     * a CSS selector, so everything but a letter, a digit and a hyphen is escaped by code point rather than
+     * dropped — two values differing only in punctuation must not come out naming one element. The `_` that
+     * delimits an escape is escaped along with the rest, which is what keeps the mapping one-to-one.
+     */
+    function token(value: string): string;
+    /** The next selectable tab in a direction, or `undefined` when there is none. Disabled tabs are stepped over. */
+    function step(tabs: readonly HTMLElement[], from: number, delta: number, loop: boolean): HTMLElement | undefined;
+    /** The first (`delta: 1`) or last (`delta: -1`) selectable tab. */
+    function edge(tabs: readonly HTMLElement[], delta: number): HTMLElement | undefined;
+    /** Where a tab a move should start from sits, or `-1` when the node is not one of these tabs. */
+    function indexOf(tabs: readonly HTMLElement[], node: EventTarget | null): number;
+    /**
+     * What a key does in a tablist of this orientation. The off-axis arrows deliberately mean nothing — APG
+     * leaves them to the page, so a horizontal tablist does not eat Up and Down.
+     */
+    function moveFor(key: string, orientation: TabsOrientation, rtl?: boolean): TabsMove | undefined;
+    /** The tab a move arrives at, or `undefined` when there is nowhere to go. */
+    function target(tabs: readonly HTMLElement[], from: number, move: TabsMove, loop: boolean): HTMLElement | undefined;
+    /** The tab whose panel is showing, read off the attribute the component writes rather than matched on a value. */
+    function selectedTab(list: Element | null | undefined): HTMLElement | undefined;
+    /**
+     * Where the travelling indicator has to be, measured off the two rectangles rather than `offsetLeft` —
+     * whose origin is the nearest positioned ancestor, which need not be the list. The scroll offset is
+     * added back because scrolling a list that outgrows its container is the consumer's to set up (#140),
+     * so a list that does scroll must not drag the indicator off its tab.
+     */
+    function bounds(list: Element, tab: Element, orientation: TabsOrientation): TabsBounds;
+    /** Whether a fresh measurement says anything new, so a reflow that moved nothing costs no render. */
+    function sameBounds(left: TabsBounds | undefined, right: TabsBounds | undefined): boolean;
+    /**
+     * The panel a container is showing: the one that is not hidden, so `keepMounted` measures the panel on
+     * screen rather than the first one written.
+     */
+    function visiblePanel(container: Element | null | undefined): HTMLElement | undefined;
+}
+export default TabsUtils;

package/utils/toast/toastStore.d.ts

@@ -0,0 +1,73 @@
+/** What a toast is saying, which is the only thing that changes its colour and its urgency. */
+export type ToastKind = 'default' | 'success' | 'error' | 'warning' | 'info' | 'loading';
+/** Why a toast went away — the four every dismissal reports, on the shape the rest of the library uses. */
+export type ToastDismissReason = 'timeout' | 'close' | 'action' | 'imperative';
+export interface ToastAction<TContent> {
+    label: TContent;
+    onClick(): void;
+    /** Whether pressing it also dismisses the toast. Default `true` — an action is an answer to it. */
+    closeOnClick?: boolean;
+}
+export interface ToastOptions<TContent> {
+    /** Reuse an id and the toast already carrying it is updated in place, which is what `toast.promise` does. */
+    id?: string;
+    kind?: ToastKind;
+    description?: TContent;
+    /** Milliseconds on screen. `Infinity` stays until something dismisses it, which is what `loading` uses. */
+    duration?: number;
+    action?: ToastAction<TContent>;
+    /** Whether the close button is drawn and Escape reaches it. Default `true`. */
+    dismissible?: boolean;
+    onDismiss?(reason: ToastDismissReason): void;
+}
+export interface Toast<TContent> {
+    id: string;
+    kind: ToastKind;
+    message: TContent;
+    description?: TContent;
+    duration: number;
+    action?: ToastAction<TContent>;
+    dismissible: boolean;
+    onDismiss?(reason: ToastDismissReason): void;
+    /** False from the moment it is dismissed: the entry is still rendered, because the exit is running. */
+    open: boolean;
+    /** On screen rather than waiting behind the limit. A queued toast runs no timer — see `syncTimers`. */
+    visible: boolean;
+}
+export interface ToastState<TContent> {
+    toasts: readonly Toast<TContent>[];
+    /** How many open toasts the limit is holding back, which is what the viewport's counter says. */
+    overflow: number;
+}
+export interface ToastStore<TContent> {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): ToastState<TContent>;
+    /** The empty state, always: nothing has been announced on a server. */
+    getServerSnapshot(): ToastState<TContent>;
+    add(message: TContent, options?: ToastOptions<TContent>): string;
+    /** Changes a toast already on screen. An unknown id is ignored rather than added — see `toast.promise`. */
+    update(id: string, message: TContent, options?: ToastOptions<TContent>): void;
+    /** Starts the exit. The entry stays until `remove`, which is what gives `<Presence>` something to hold. */
+    dismiss(id?: string, reason?: ToastDismissReason): void;
+    /** Drops the entry for good — what the viewport calls once the exit has finished. */
+    remove(id: string): void;
+    setLimit(limit: number): void;
+    setDefaultDuration(duration: number): void;
+    /** Every timer holds where it got to. WCAG 2.2.1: hovering or focusing the stack must stop the clock. */
+    pause(): void;
+    resume(): void;
+    /** Everything gone with no exit and no handler called — for a test, or a route change. */
+    reset(): void;
+}
+/**
+ * The queue, the timers and the subscription behind `toast()` — with no React in it, because none of that
+ * is a rendering question. The component reads a snapshot and draws it; every decision about what is on
+ * screen, what is waiting and when something leaves is made here.
+ *
+ * A toast past the limit is **queued, not dropped, and its timer has not started** — so a message cannot
+ * expire while it was never on screen, which is the whole reason the limit is a queue rather than a cap.
+ */
+export default function createToastStore<TContent>(options?: {
+    limit?: number;
+    duration?: number;
+}): ToastStore<TContent>;

package/utils/virtual/virtualUtils.d.ts

@@ -0,0 +1,47 @@
+/** The slice of a long list that is actually rendered, and where it sits in the scroll space. */
+export interface VirtualWindow {
+    /** First row to render. */
+    startIndex: number;
+    /** One past the last row to render. */
+    endIndex: number;
+    /** How far down the slice starts, in pixels. */
+    offsetY: number;
+    /** What the whole list measures — what gives the scrollbar its range. */
+    totalHeight: number;
+}
+export interface VirtualWindowOptions {
+    count: number;
+    /** The *pitch* of a row: its height plus whatever sits between two of them. */
+    itemHeight: number;
+    /** What the scrolling element shows at once. */
+    viewHeight: number;
+    scrollTop: number;
+    /** Rows kept either side of what is visible, so a scroll has something to reveal. */
+    overscan?: number;
+    /** The row the keyboard is on, or `-1`. The window moves to hold it whatever the scroll says. */
+    activeIndex?: number;
+}
+/**
+ * Windowing with no React and no DOM in it: which rows of a long list to render for a given scroll
+ * position, and where to put them. Pure arithmetic, so the answers are testable in an environment that
+ * computes no layout — which is every environment this repo's tests run in.
+ */
+declare namespace VirtualUtils {
+    /** Rows either side of the viewport. Four is about a frame of fast scrolling at this row height. */
+    const DEFAULT_OVERSCAN = 4;
+    /** Below this a window costs more than it saves: the arithmetic, the wrapper and the scroll state. */
+    const DEFAULT_THRESHOLD = 100;
+    /** What a row is taken to measure before anything has been measured — this library's own option height. */
+    const DEFAULT_ITEM_HEIGHT = 36;
+    /** What the scroller is taken to show before anything has been measured — `combobox.items`' own height. */
+    const DEFAULT_VIEW_HEIGHT = 248;
+    /** Whether a list is long enough to be worth windowing. `enabled` is the caller overruling the count. */
+    function shouldVirtualize(count: number, enabled?: boolean, threshold?: number): boolean;
+    /**
+     * The rows to render for a scroll position. The window is a fixed number of rows that *moves*, rather
+     * than one that stretches to reach the active row: Home on a ten-thousand-row list would otherwise
+     * render all ten thousand, which is the cost the window exists to avoid.
+     */
+    function windowFor(options: VirtualWindowOptions): VirtualWindow;
+}
+export default VirtualUtils;