@box-kite/react 1.0.0 → 2.0.1

package/react/popover/usePopoverLayer.d.ts

@@ -0,0 +1,87 @@
+import { ElementLike } from '../../utils/dom/domUtils';
+import { ChangeHandler, SetControllableState } from '../a11y/useControllableState';
+/** Why a layer opened or closed — every component built on this reports the same four. */
+export type PopoverReason = 'trigger' | 'escape' | 'outside-pointer' | 'imperative';
+/** What a trigger says it opens, which is the one thing the layers built on this disagree about. */
+export type PopoverHasPopup = 'dialog' | 'menu';
+/** The DOM attributes a trigger has to carry, whatever it opens. */
+export interface PopoverTriggerAttributes<THasPopup extends PopoverHasPopup = PopoverHasPopup> {
+    'aria-expanded': boolean;
+    'aria-haspopup': THasPopup;
+    'aria-controls'?: string;
+    /** Only where the browser has no Popover API. On the platform path `popovertarget` does the toggling. */
+    onClick?(event: React.MouseEvent): void;
+}
+/**
+ * What the trigger has to carry: spread it onto the control itself, not a wrapper. The `ref` is what the
+ * layer is anchored to, so it is not optional decoration.
+ *
+ * It must be a **button**: `popovertarget` is what the browser toggles on, and it only reads it off one.
+ */
+export interface PopoverTrigger<THasPopup extends PopoverHasPopup = PopoverHasPopup> {
+    ref: React.RefCallback<HTMLElement>;
+    props: PopoverTriggerAttributes<THasPopup>;
+}
+export interface PopoverLayerOptions<THasPopup extends PopoverHasPopup = PopoverHasPopup, TReason extends string = never> {
+    /** What the trigger says it opens. */
+    haspopup: THasPopup;
+    /** A consumer id wins over the generated one, and everything that names the layer follows it. */
+    id?: string;
+    /** What the generated id is prefixed with, so a debugger says which component it belongs to. */
+    idPrefix: string;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: ChangeHandler<boolean, PopoverReason | TReason>;
+    /**
+     * The layer is open *and* laid out — the only moment focus can be moved into it. On the platform path
+     * this is the `toggle` event rather than an effect on the open state, and the difference is not
+     * academic: `beforetoggle` fires before the panel opens and a discrete event is flushed synchronously,
+     * so an effect would run while `:popover-open` still does not match, which is `display: none` — and
+     * focusing a hidden element does nothing at all (measured).
+     */
+    onOpened?(panel: HTMLElement): void;
+    /**
+     * It is about to close, and `heldFocus` says whether it has focus. Fired from `beforetoggle`, while the
+     * panel is still shown, because that is the last moment focus can be moved without a flash: the platform
+     * returns focus to whatever had it before the **outermost** layer opened, and for a nested one it does
+     * nothing at all — focus drops to `<body>` (both measured in Chrome 152). A submenu puts focus back on
+     * its own item from here.
+     */
+    onClosing?(heldFocus: boolean, trigger: HTMLElement | null): void;
+    /**
+     * More elements a press inside counts as inside, for the portal path only: a nested layer is portalled
+     * out of the DOM it was declared in, so nothing about the tree says a press in it is a press in this
+     * one. The platform answers that question itself, by the popover nesting rules.
+     */
+    inside?: readonly ElementLike[];
+}
+export interface PopoverLayer<THasPopup extends PopoverHasPopup = PopoverHasPopup, TReason extends string = never> {
+    /** Whether the browser's Popover API is placing the layer in the top layer. `false` is the portal path. */
+    platform: boolean;
+    isOpen: boolean;
+    setOpen: SetControllableState<boolean, PopoverReason | TReason>;
+    id: string;
+    /** What the trigger render prop is handed. */
+    trigger: PopoverTrigger<THasPopup>;
+    triggerElement: HTMLElement | null;
+    /**
+     * The trigger's id — what names a layer after the control that opened it, which is what APG asks of a
+     * menu. One is written onto the trigger when it has none of its own.
+     */
+    triggerId?: string;
+    /** Goes on the panel, on both paths. */
+    setPanel: React.RefCallback<HTMLElement>;
+    panelElement: HTMLElement | null;
+}
+/**
+ * One conversation with the Popover API, for every component that opens a layer on it: the open state,
+ * the platform mirror, the dismissal reasons, and the two primitives that stand in where the browser has
+ * no popover at all. `Popover` is this plus a `role="dialog"` panel; `Menu` is this three times over —
+ * once for the menu and once per open submenu.
+ *
+ * What the platform owns, measured in Chrome 152: the top layer, light dismiss (Escape and an outside
+ * press), the toggle from a `popovertarget` trigger — including the press that closes an open layer from
+ * its own trigger, with no reopen — and focus return for the outermost layer. What it does not own is
+ * focus *into* the layer, focus return for a nested one, and any of the ARIA.
+ */
+export default function usePopoverLayer<THasPopup extends PopoverHasPopup, TReason extends string = never>(options: PopoverLayerOptions<THasPopup, TReason>): PopoverLayer<THasPopup, TReason>;

package/react-shared.cjs

@@ -1 +1 @@
-const e=require("./rolldown-runtime.cjs");let t=require("react");t=e.t(t,1);let n=require("@box-kite/core");function r({classNames:e,styleElements:t},r){return{className:(0,n.classNames)(e,r).join(` `),styles:t}}var i={selected:`aria-selected`},a;(function(e){function t(e,t,n){e!==void 0&&e!=null&&(n[i[t]??t]=Array.isArray(e)?e[0]:e)}e.assignBooleanProp=t})(a||={});var o=a;function s(e,t){let r=e,{props:i,className:a,disabled:s,required:c,checked:l,selected:u}=r,d={...i,className:(0,n.classNames)(t,a).join(` `)};return o.assignBooleanProp(s,`disabled`,d),o.assignBooleanProp(c,`required`,d),o.assignBooleanProp(l,`checked`,d),o.assignBooleanProp(u,`selected`,d),`style`in r&&(d.style=r.style),`id`in r&&(d.id=r.id),d}var c=parseInt(t.default.version,10)>=19,l=!1;function u(e){if(e?.length)return!c&&!l&&(l=!0,console.warn(`[box-kite] Box.configure({ sink: 'element' }) needs React 19 to hoist and dedupe its <style> elements; React ${t.default.version} will render them inline. Use the default sink instead.`)),e.map(({href:e,css:n,precedence:r})=>t.default.createElement(`style`,{key:e,href:e,precedence:r,dangerouslySetInnerHTML:{__html:n}}))}function d(e,t){let{classNames:r,signature:i,styleElements:a}=(0,n.getDefaultEngine)().resolveClassNames(e,t);return{classNames:r,signature:i,styleElements:u(a)}}var f=`__boxAttributesInProps`;function p(e){return e[f]=!0,e}function m(e){return typeof e==`function`||typeof e==`object`&&e?e[f]===!0:!1}var h=[`role`,`aria-label`,`aria-labelledby`,`aria-hidden`];function g(e,t){if(e!==void 0)return{role:`img`,"aria-label":e};if(!(t&&h.some(e=>e in t)))return{"aria-hidden":!0}}var _;(function(e){function t(e){return e.charAt(0).toUpperCase()+e.slice(1)}e.capitalize=t})(_||={});var v=_,y;(function(e){function t(e,t,n){let r={...e},i=r.props||{};return t.forEach(e=>{e in r&&(i[e]=r[e],delete r[e])}),n&&Object.entries(n).forEach(([e,t])=>{i[e]=t}),r.props=i,r}e.buildProps=t;function n(e){return!!e&&typeof e==`object`}e.isObject=n;function r(e,t){return e in t}e.isKeyOf=r})(y||={});var b=y;Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,"c",{enumerable:!0,get:function(){return s}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return m}}),Object.defineProperty(exports,"l",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return v}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return g}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return b}});
+const e=require("./rolldown-runtime.cjs");let t=require("react");t=e.t(t,1);let n=require("@box-kite/core");function r({classNames:e,styleElements:t},r){return{className:(0,n.classNames)(e,r).join(` `),styles:t}}var i={selected:`aria-selected`},a;(function(e){function t(e,t,n){e!==void 0&&e!=null&&(n[i[t]??t]=Array.isArray(e)?e[0]:e)}e.assignBooleanProp=t})(a||={});var o=a;function s(e,t){let r=e,{props:i,className:a,disabled:s,required:c,checked:l,selected:u}=r,d={...i,className:(0,n.classNames)(t,a).join(` `)};return o.assignBooleanProp(s,`disabled`,d),o.assignBooleanProp(c,`required`,d),o.assignBooleanProp(l,`checked`,d),o.assignBooleanProp(u,`selected`,d),`style`in r&&(d.style=r.style),`id`in r&&(d.id=r.id),d}var c=parseInt(t.default.version,10)>=19,l=!1;function u(e){if(e?.length)return!c&&!l&&(l=!0,console.warn(`[box-kite] Box.configure({ sink: 'element' }) needs React 19 to hoist and dedupe its <style> elements; React ${t.default.version} will render them inline. Use the default sink instead.`)),e.map(({href:e,css:n,precedence:r})=>t.default.createElement(`style`,{key:e,href:e,precedence:r,dangerouslySetInnerHTML:{__html:n}}))}function d(e,t){let{classNames:r,signature:i,styleElements:a}=(0,n.getDefaultEngine)().resolveClassNames(e,t);return{classNames:r,signature:i,styleElements:u(a)}}var f=`__boxAttributesInProps`;function p(e){return e[f]=!0,e}function m(e){return typeof e==`function`||typeof e==`object`&&e?e[f]===!0:!1}var h=[`role`,`aria-label`,`aria-labelledby`,`aria-hidden`];function g(e,t){if(e!==void 0)return{role:`img`,"aria-label":e};if(!(t&&h.some(e=>e in t)))return{"aria-hidden":!0}}var _;(function(e){function t(e){return e.charAt(0).toUpperCase()+e.slice(1)}e.capitalize=t})(_||={});var v=_,y;(function(e){function t(e,t,n){let r={...e},i=r.props||{};return t.forEach(e=>{e in r&&(i[e]=r[e],delete r[e])}),n&&Object.entries(n).forEach(([e,t])=>{i[e]=t}),r.props=i,r}e.buildProps=t;function n(e){return!!e&&typeof e==`object`}e.isObject=n;function r(e,t){return e in t}e.isKeyOf=r})(y||={});var b=y,x=[`sky-500`,`emerald-500`,`amber-500`,`violet-500`,`rose-500`,`cyan-500`],S=[`sky-400`,`emerald-400`,`amber-400`,`violet-400`,`rose-400`,`cyan-400`];function C(e){return e.reduce((e,t,n)=>(e[`chart-${n+1}`]=t,e),{})}Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return v}}),Object.defineProperty(exports,"c",{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,"d",{enumerable:!0,get:function(){return s}}),Object.defineProperty(exports,"f",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return b}}),Object.defineProperty(exports,"l",{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return x}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return g}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return C}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return m}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return S}}),Object.defineProperty(exports,"u",{enumerable:!0,get:function(){return u}});

package/react-shared.mjs

@@ -100,6 +100,23 @@ var v = _, y;
 	}
 	e.isKeyOf = r;
 })(y ||= {});
-var b = y;
+var b = y, x = [
+	"sky-500",
+	"emerald-500",
+	"amber-500",
+	"violet-500",
+	"rose-500",
+	"cyan-500"
+], S = [
+	"sky-400",
+	"emerald-400",
+	"amber-400",
+	"violet-400",
+	"rose-400",
+	"cyan-400"
+];
+function C(e) {
+	return e.reduce((e, t, n) => (e[`chart-${n + 1}`] = t, e), {});
+}
 //#endregion
-export { p as a, s as c, m as i, r as l, v as n, d as o, g as r, u as s, b as t };
+export { v as a, p as c, s as d, r as f, b as i, d as l, x as n, g as o, C as r, m as s, S as t, u };

package/rsc.cjs

@@ -1 +1 @@
-Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("./rolldown-runtime.cjs"),t=require("./react-shared.cjs");let n=require("react");n=e.t(n,1);let r=require("@box-kite/core");(0,r.getDefaultEngine)().configure({sink:`element`});function i(e){let{tag:r=`div`,children:i}=e;if(typeof i==`function`)throw Error(`[box-kite] Box children as a function track hover state, which needs the client Box — render it from a 'use client' module.`);let{classNames:a,styleElements:o}=t.o(e,r===`svg`);return n.default.createElement(n.default.Fragment,null,o,n.default.createElement(r,t.c(e,a),i))}var a=i;a.extend=r.BoxExtends.extend,a.components=r.BoxExtends.components,a.keyframes=r.BoxExtends.keyframes,a.spring=r.Springs.spring,a.getVariableValue=e=>(0,r.getDefaultEngine)().getVariableValue(e),a.configure=e=>(0,r.getDefaultEngine)().configure(e);function o(e,n){return t.l(t.o(e,n?.svg===!0),e.className)}exports.default=a,exports.useClassNames=o;
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("./rolldown-runtime.cjs"),t=require("./react-shared.cjs");let n=require("react");n=e.t(n,1);let r=require("@box-kite/core");(0,r.getDefaultEngine)().configure({sink:`element`});function i(e){let{tag:r=`div`,children:i}=e;if(typeof i==`function`)throw Error(`[box-kite] Box children as a function track hover state, which needs the client Box — render it from a 'use client' module.`);let{classNames:a,styleElements:o}=t.l(e,r===`svg`);return n.default.createElement(n.default.Fragment,null,o,n.default.createElement(r,t.d(e,a),i))}var a=i;a.extend=r.BoxExtends.extend,a.components=r.BoxExtends.components,a.keyframes=r.BoxExtends.keyframes,a.spring=r.Springs.spring,a.getVariableValue=e=>(0,r.getDefaultEngine)().getVariableValue(e),a.configure=e=>(0,r.getDefaultEngine)().configure(e);function o(e,n){return t.f(t.l(e,n?.svg===!0),e.className)}exports.default=a,exports.useClassNames=o;

package/rsc.mjs

@@ -1,4 +1,4 @@
-import { c as e, l as t, o as n } from "./react-shared.mjs";
+import { d as e, f as t, l as n } from "./react-shared.mjs";
 import r from "react";
 import { BoxExtends as i, Springs as a, getDefaultEngine as o } from "@box-kite/core";
 //#region src/rsc.ts

package/utils/accordion/accordionUtils.d.ts

@@ -0,0 +1,48 @@
+/** What a key means in an accordion: a step to the neighbouring header, or a jump to an end. */
+export interface AccordionMove {
+    kind: 'step' | 'edge';
+    /** `1` forward, `-1` back — and on an `edge` move, the first header or the last. */
+    delta: number;
+}
+/**
+ * Which header an accordion's keyboard lands on, and which panels stand open, read off the DOM rather
+ * than out of a registry — B4's and B5's precedent, for the same reason: a header a consumer wrapped,
+ * rendered from a list or put behind a condition is in the order it was written.
+ */
+declare namespace AccordionUtils {
+    /** The root marks itself so a header can say which accordion it belongs to. Neither attribute is ARIA: an accordion has no container role. */
+    const ROOT_ATTRIBUTE = "data-accordion";
+    const TRIGGER_ATTRIBUTE = "data-accordion-trigger";
+    const ROOT_SELECTOR = "[data-accordion]";
+    const TRIGGER_SELECTOR = "[data-accordion-trigger]";
+    /** Whether this accordion is the one a node belongs to, rather than one nested in a panel inside it. */
+    function owns(root: Element, node: EventTarget | null): boolean;
+    /** The headers an accordion owns, in DOM order. A nested accordion's headers belong to their own root. */
+    function triggers(root: Element | null | undefined): HTMLElement[];
+    /**
+     * A header nothing can open. Skipped by every movement, the way a disabled tab is: it is the `disabled`
+     * attribute here, so the browser has already taken it out of the tab sequence, and arrows that still
+     * stopped on it would be reaching what Tab cannot.
+     */
+    function isDisabled(trigger: Element): boolean;
+    /** The next enabled header in a direction, or `undefined` when there is none. */
+    function step(triggers: readonly HTMLElement[], from: number, delta: number, loop: boolean): HTMLElement | undefined;
+    /** The first (`delta: 1`) or last (`delta: -1`) enabled header. */
+    function edge(triggers: readonly HTMLElement[], delta: number): HTMLElement | undefined;
+    /** Where the header a move starts from sits, or `-1` when the node is not one of them. */
+    function indexOf(triggers: readonly HTMLElement[], node: EventTarget | null): number;
+    /**
+     * What a key does on an accordion header. An accordion stacks along the block axis whatever the reading
+     * order is, so unlike a tablist there is nothing here to mirror — and the sideways pair is left to the
+     * page, which is where APG leaves it.
+     */
+    function moveFor(key: string): AccordionMove | undefined;
+    /** The header a move arrives at, or `undefined` when there is nowhere to go. */
+    function target(triggers: readonly HTMLElement[], from: number, move: AccordionMove, loop: boolean): HTMLElement | undefined;
+    /**
+     * The panels standing open after one header is pressed. Closing the open one is always allowed, so a
+     * single-panel accordion needs no second prop to say whether it can stand empty.
+     */
+    function toggle(open: readonly string[], value: string, multiple: boolean): string[];
+}
+export default AccordionUtils;

package/utils/anchor/anchorUtils.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Where a floating layer goes, twice over: as the `position-area` the browser reads, and as the
+ * coordinates a browser without anchor positioning has to be given. One model rather than two, so the
+ * two paths cannot drift — the fallback is the CSS placement worked out by hand.
+ *
+ * Framework-free and layout-free: every function here takes rectangles and returns numbers, which is what
+ * makes the flip and the shift testable without a DOM (jsdom computes no layout at all).
+ */
+/** Which side of the anchor the layer sits on. `top`/`bottom` are the block axis, `start`/`end` the inline one. */
+export type AnchorSide = 'top' | 'bottom' | 'start' | 'end';
+/** Where along that side the layer lines up. */
+export type AnchorAlign = 'start' | 'center' | 'end';
+/** A box in viewport coordinates — what `getBoundingClientRect()` gives, narrowed to what placing needs. */
+export interface AnchorRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+export interface PlacementOptions {
+    side: AnchorSide;
+    align: AnchorAlign;
+    /** The gap between anchor and layer, in pixels. */
+    offset: number;
+    /** Whether a side that does not fit may be swapped for its opposite. */
+    flip: boolean;
+    /** Whether the inline axis runs right to left, which is what `start`/`end` mean. */
+    rtl: boolean;
+}
+/**
+ * The twelve `position-area` values a side and an alignment can name — spelled out rather than derived,
+ * so the compiler can see that each one is a value the `positionArea` prop takes.
+ */
+export type AnchorArea = 'block-start span-all' | 'block-start span-inline-start' | 'block-start span-inline-end' | 'block-end span-all' | 'block-end span-inline-start' | 'block-end span-inline-end' | 'span-all inline-start' | 'span-block-start inline-start' | 'span-block-end inline-start' | 'span-all inline-end' | 'span-block-start inline-end' | 'span-block-end inline-end';
+/** Where the fallback puts the layer: viewport coordinates, and the side it settled on after flipping. */
+export interface Placement {
+    top: number;
+    left: number;
+    side: AnchorSide;
+}
+/**
+ * The `position-area` for a side and an alignment — and the counter-intuitive half of the grammar, since
+ * an alignment is written as the span *away* from it: a layer whose start edge meets the anchor's start
+ * edge occupies the centre cell and the one after it, which is `span-inline-end`. Measured in Chrome 152.
+ *
+ * `center` is `span-all` rather than the `center` cell on purpose: the centre cell is only as wide as the
+ * anchor, so a layer wider than its anchor overflows it on the cross axis, and an overflow no flip can fix
+ * disqualifies every fallback position (the trap `positionTryFallbacks` documents).
+ */
+export declare function areaFor(side: AnchorSide, align: AnchorAlign): AnchorArea;
+/**
+ * The side a used `position-area` names — the browser's own answer to "did you flip?", since
+ * `getComputedStyle` reports the position it settled on rather than the one that was specified.
+ *
+ * It is not the value that went in: measured in Chrome 152, a used value is normalised twice over. A
+ * `span-all` half is dropped (`block-end span-all` reads back `block-end`), and a value naming both axes
+ * comes back in the `start`/`end` shorthand family, where **position** names the axis rather than a
+ * keyword — `block-end span-inline-end` reads back `end span-end`, and `start span-end` once it has
+ * flipped. So the block axis is the first keyword and the inline axis the second, and the side is
+ * whichever of them is not a span.
+ */
+export declare function sideOfArea(area: string): AnchorSide | null;
+/** The two candidate lists, spelled out so the compiler can see each is a value `positionTryFallbacks` takes. */
+export type AnchorFallbacks = 'flip-block, flip-inline, flip-block flip-inline' | 'flip-inline, flip-block, flip-inline flip-block';
+/**
+ * The `position-try-fallbacks` for a side: its own axis first, then the alignment's, then both. Three
+ * candidates rather than one because a candidate has to fit on **both** axes — so a single `flip-block`
+ * does nothing at all for a layer that overflows the *cross* axis, and the browser leaves it against the
+ * edge of the viewport (measured in Chrome 152, hand-written CSS). With the list, a menu aligned to its
+ * trigger's end mirrors to the other end rather than running off the page.
+ */
+export declare function fallbacksFor(side: AnchorSide): AnchorFallbacks;
+/**
+ * The fallback's whole answer: flip to the opposite side when the requested one has no room and the
+ * opposite has more, then shift along the cross axis to stay in the viewport. The two are the entire
+ * middleware stack a positioning library sells, and they are twelve lines because the browser is doing
+ * neither here — this runs only where `anchor-name` is not supported.
+ */
+export declare function place(anchor: AnchorRect, layer: AnchorRect, viewport: AnchorRect, options: PlacementOptions): Placement;

package/utils/array/lazyList.d.ts

@@ -0,0 +1,10 @@
+/**
+ * An array whose elements are computed when somebody asks for one. A server row model lays out a million
+ * rows and renders fifty of them, so allocating an object per row is the one thing it must not do — and
+ * every reader of these lists indexes, slices or binary-searches rather than iterating, which is exactly
+ * what a proxy can answer. `length` is reported without the target ever holding that many elements.
+ *
+ * Iterating one (`map`, `flatMap`, a spread) materializes every element, which is the cost this exists to
+ * avoid: do that only where the length is known to be small.
+ */
+export default function lazyList<T>(length: number, at: (index: number) => T): T[];

package/utils/chart/chartPalette.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The chart palette, on its own so that `boxComponents.ts` can declare it without dragging the rest of
+ * `ChartUtils` — the path builders and the trigonometry — into the bundle every Box already pays for.
+ * `ChartUtils` re-exports all three, so the public names are unchanged.
+ */
+/**
+ * The colours a chart uses when nobody names any. Tokens rather than raw colours, so they resolve
+ * through the palette; six, because that is as many series as a tile can be told apart in — a seventh
+ * wraps round rather than inventing a colour.
+ */
+export declare const PALETTE: readonly ["sky-500", "emerald-500", "amber-500", "violet-500", "rose-500", "cyan-500"];
+/** The same six for a dark background, where a 500 reads as muddy against near-black. */
+export declare const DARK_PALETTE: readonly ["sky-400", "emerald-400", "amber-400", "violet-400", "rose-400", "cyan-400"];
+/** The numbered palette as custom properties: `{ 'chart-1': 'sky-500', … }`. */
+export declare function paletteVariables(palette: readonly string[]): Record<string, string>;

package/utils/chart/chartUtils.d.ts

@@ -1,3 +1,4 @@
+import * as ChartPalette from './chartPalette';
 /**
  * The model behind the chart primitives: every number a `<Sparkline>`, `<ProgressRing>`, `<Gauge>` or
  * `<MiniDonut>` draws with, the palette a `<ChartContainer>` declares, and no React. Components render,
@@ -78,16 +79,9 @@ declare namespace ChartUtils {
      * no segments rather than a division by zero, and a negative value counts as none.
      */
     function donutSegments(data: readonly number[], length: number): Segment[];
-    /**
-     * The colours a chart uses when nobody names any. Tokens rather than raw colours, so they resolve
-     * through the palette; six, because that is as many series as a tile can be told apart in — a seventh
-     * wraps round rather than inventing a colour.
-     */
     const PALETTE: readonly ["sky-500", "emerald-500", "amber-500", "violet-500", "rose-500", "cyan-500"];
-    /** The same six for a dark background, where a 500 reads as muddy against near-black. */
     const DARK_PALETTE: readonly ["sky-400", "emerald-400", "amber-400", "violet-400", "rose-400", "cyan-400"];
-    /** The numbered palette as custom properties: `{ 'chart-1': 'sky-500', … }`. */
-    function paletteVariables(palette: readonly string[]): Record<string, string>;
+    const paletteVariables: typeof ChartPalette.paletteVariables;
     /**
      * The variables a chart's series read, named as the ecosystem names them: `{ 'color-revenue':
      * 'var(--chart-1)' }`. A list takes the palette in order, which is the whole case for the container — a

package/utils/combobox/comboboxUtils.d.ts

@@ -0,0 +1,89 @@
+/** How a row's text, its identity or its disabled state is read: a key of the row, or a function. */
+export type RowAccessor<TRow, TResult> = (keyof TRow & string) | ((row: TRow) => TResult);
+/**
+ * What the combobox needs to know about a row to search it, tell it from its neighbours and refuse it.
+ * Only `label` is required — it is the text, and without one nothing could be typed at or read out.
+ */
+export interface ComboboxRowDef<TRow> {
+    /** The row's text: displayed, searched, and what a screen reader announces. */
+    label: RowAccessor<TRow, string>;
+    /** What makes two rows the same row. Defaults to the label, which is what a list of strings has. */
+    key?: RowAccessor<TRow, string | number>;
+    /** A row that cannot be chosen: skipped by the arrows and inert to a press. */
+    disabled?: RowAccessor<TRow, boolean>;
+}
+/** A row of the open listbox. `create` is the offer to make a row out of what was typed. */
+export type ComboboxRow<TRow> = {
+    kind: 'option';
+    row: TRow;
+} | {
+    kind: 'create';
+    query: string;
+};
+/**
+ * Which rows a query leaves, in the order they will be shown. It takes the whole list rather than one row
+ * so that it can rank as well as reject, and it is handed the label reader so that composing it with the
+ * built-in one costs nothing.
+ */
+export type ComboboxFilter<TRow> = (rows: TRow[], query: string, labelOf: (row: TRow) => string) => TRow[];
+/**
+ * The combobox with no React in it: reading a row, filtering the list, and what the selection becomes when
+ * a row is chosen. All of it is a pure function of the data and the query, which is what lets the same
+ * answers be tested without a DOM and re-used by a virtualized listbox that renders fifty of ten thousand.
+ */
+declare namespace ComboboxUtils {
+    /** Resolve an accessor against a row. A key reads the property; a function is called. */
+    function read<TRow, TResult>(accessor: RowAccessor<TRow, TResult>, row: TRow): TResult;
+    /** A row's text. Coerced, so a numeric column is a legal label and a missing one is empty rather than `"undefined"`. */
+    function labelOf<TRow>(def: ComboboxRowDef<TRow>, row: TRow): string;
+    /** A row's identity. The label by default: a list of plain strings is its own set of keys. */
+    function keyOf<TRow>(def: ComboboxRowDef<TRow>, row: TRow): string | number;
+    function isDisabled<TRow>(def: ComboboxRowDef<TRow>, row: TRow): boolean;
+    /**
+     * The form a query and a label are compared in: case-folded and stripped of accents, so that `jose`
+     * finds `José`. NFD splits a letter from its accent and the mark range is what is then dropped.
+     */
+    function normalize(text: string): string;
+    /** Whether a label answers a query. A substring rather than a prefix: a surname is worth finding. */
+    function matches(label: string, query: string): boolean;
+    /**
+     * The filter a combobox uses when its caller names none, exported so that a caller who names one can
+     * still start from it — `(rows, query, labelOf) => filterRows(rows, query, labelOf).slice(0, 20)`.
+     */
+    function filterRows<TRow>(rows: TRow[], query: string, labelOf: (row: TRow) => string): TRow[];
+    /** The selection as a list, whichever shape it arrived in. `null` and `undefined` are "nothing chosen". */
+    function toArray<TRow>(value: TRow | TRow[] | null | undefined): TRow[];
+    function isSelected<TRow>(selection: TRow[], row: TRow, keyFor: (row: TRow) => string | number): boolean;
+    /**
+     * What the selection becomes when a row is chosen. Single-select replaces, and choosing what is already
+     * chosen keeps it — a combobox has no "unselect by reselecting", since its field would have nothing to
+     * show. Multi-select toggles, which is how a chip is removed from the listbox rather than from the chip.
+     */
+    function toggle<TRow>(selection: TRow[], row: TRow, multiple: boolean, keyFor: (row: TRow) => string | number): TRow[];
+    interface RowsOptions<TRow> {
+        data: TRow[];
+        def: ComboboxRowDef<TRow>;
+        /** What has been typed. Only filters once the caller says it was typed rather than displayed. */
+        query: string;
+        /** `false` when the data is already filtered — a server that searched, or a caller that did. */
+        filter: ComboboxFilter<TRow> | false;
+        /** Whether the query is the user's rather than the selection's text. A displayed value filters nothing. */
+        typed: boolean;
+        /** Turns a query into the row it would create, or `null` for one that should not be offered. */
+        createRow?: (query: string) => TRow | null;
+    }
+    /**
+     * Every row the listbox shows, in keyboard order. The create row is last and appears only for a query
+     * that no row already answers by name — offering "Create Apple" beside Apple is how a list grows twins.
+     */
+    function rowsFor<TRow>(options: RowsOptions<TRow>): ComboboxRow<TRow>[];
+    /** A row the arrows skip and a press does nothing to. The create row is always available. */
+    function isRowDisabled<TRow>(def: ComboboxRowDef<TRow>, row: ComboboxRow<TRow>): boolean;
+    /**
+     * Where the highlight goes when the listbox opens: the selected row whichever key opened it, so that
+     * Down or Up from a chosen value moves on from it rather than jumping to an end. With nothing chosen it
+     * falls back to the end the key implied. `-1` when nothing can be highlighted — no rows, or all disabled.
+     */
+    function activeIndexFor<TRow>(rows: ComboboxRow<TRow>[], selection: TRow[], def: ComboboxRowDef<TRow>, fallback?: 'first' | 'last'): number;
+}
+export default ComboboxUtils;

package/utils/dom/domUtils.d.ts

@@ -24,3 +24,9 @@ export declare function isEventInside(event: Event, elements: readonly ElementLi
  * 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

@@ -14,5 +14,15 @@ export declare function documentOrNull(): Document | null;
 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/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/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;