@box-kite/react 1.0.0 → 2.0.0

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/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;