@box-kite/react 0.0.1 → 2.0.0

package/react-shared.cjs

@@ -0,0 +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,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

@@ -0,0 +1,122 @@
+import e from "react";
+import { classNames as t, getDefaultEngine as n } from "@box-kite/core";
+//#region src/react/boxClassNames.ts
+function r({ classNames: e, styleElements: n }, r) {
+	return {
+		className: t(e, r).join(" "),
+		styles: n
+	};
+}
+//#endregion
+//#region src/utils/box/boxUtils.ts
+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;
+//#endregion
+//#region src/react/boxTagProps.ts
+function s(e, n) {
+	let r = e, { props: i, className: a, disabled: s, required: c, checked: l, selected: u } = r, d = {
+		...i,
+		className: t(n, 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;
+}
+//#endregion
+//#region src/react/styleElements.ts
+var c = parseInt(e.version, 10) >= 19, l = !1;
+function u(t) {
+	if (t?.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 ${e.version} will render them inline. Use the default sink instead.`)), t.map(({ href: t, css: n, precedence: r }) => e.createElement("style", {
+		key: t,
+		href: t,
+		precedence: r,
+		dangerouslySetInnerHTML: { __html: n }
+	}));
+}
+//#endregion
+//#region src/react/resolveStyles.ts
+function d(e, t) {
+	let { classNames: r, signature: i, styleElements: a } = n().resolveClassNames(e, t);
+	return {
+		classNames: r,
+		signature: i,
+		styleElements: u(a)
+	};
+}
+//#endregion
+//#region src/react/svg/attributesInProps.ts
+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;
+}
+//#endregion
+//#region src/react/svg/svgNaming.ts
+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 };
+}
+//#endregion
+//#region src/utils/string/stringUtils.ts
+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), {});
+}
+//#endregion
+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/rolldown-runtime.cjs

@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,s)=>(s=n==null?{}:e(i(n)),o(r||!n||!n.__esModule||!a.call(n,`default`)?t(s,`default`,{value:n,enumerable:!0}):s,n));Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return s}});

package/rsc.cjs

@@ -0,0 +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.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.d.ts

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+import { BoxExtends, Springs, StylesConfiguration } from '@box-kite/core';
+import { BoxClassNames } from './react/boxClassNames';
+import { BoxClassNameProps, BoxCoreProps } from './react/boxProps';
+import { ComponentsAndVariants } from '@box-kite/core/types';
+interface RscBoxType {
+    <TTag extends keyof React.JSX.IntrinsicElements = 'div', TKey extends keyof ComponentsAndVariants = never>(props: BoxCoreProps<TTag, TKey>): React.ReactNode;
+    extend: typeof BoxExtends.extend;
+    components: typeof BoxExtends.components;
+    keyframes: typeof BoxExtends.keyframes;
+    /** A spring of your own, sampled into `{ easing, duration }`. Pure arithmetic, so a Server Component can call it. */
+    spring: typeof Springs.spring;
+    getVariableValue: (name: string) => string;
+    /** Explicit engine configuration. Element mode is already on; this is for the rest of it. */
+    configure: (config: StylesConfiguration) => void;
+}
+declare const RscBox: RscBoxType;
+/**
+ * The Server-Component half of `useClassNames` — see the client entry for what it is for. Not a hook
+ * here and it does not need to be, since resolving in element mode produces the `<style>` elements
+ * themselves. The `use` prefix stays so a component can move between the two entries unchanged.
+ */
+export declare function useClassNames<TKey extends keyof ComponentsAndVariants = never>(props: BoxClassNameProps<TKey>, options?: {
+    svg?: boolean;
+}): BoxClassNames;
+export default RscBox;
+export type { BoxClassNames, BoxClassNameProps };

package/rsc.mjs

@@ -0,0 +1,18 @@
+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
+o().configure({ sink: "element" });
+function s(t) {
+	let { tag: i = "div", children: a } = t;
+	if (typeof a == "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: o, styleElements: s } = n(t, i === "svg");
+	return r.createElement(r.Fragment, null, s, r.createElement(i, e(t, o), a));
+}
+var c = s;
+c.extend = i.extend, c.components = i.components, c.keyframes = i.keyframes, c.spring = a.spring, c.getVariableValue = (e) => o().getVariableValue(e), c.configure = (e) => o().configure(e);
+function l(e, r) {
+	return t(n(e, r?.svg === !0), e.className);
+}
+//#endregion
+export { c as default, l as useClassNames };

package/ssg.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./rolldown-runtime.cjs"),t=require("./client.cjs");let n=require("react-dom/server");n=e.t(n,1);function r(){return t.r.getStyles()}function i(){t.r.clear()}function a(e,a=!0){let o=n.default.renderToStaticMarkup(e),s=r();if(a){let e=o.indexOf(`<head>`);if(e>-1){let n=e+6;o=o.substring(0,n)+`<style id="${t.r.styleElementId()}">${s}</style>`+o.substring(n)}}return i(),{html:o,styles:s}}exports.getStyles=r,exports.renderToStaticMarkup=a,exports.resetStyles=i;

package/ssg.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+/**
+ * Server rendering. There is no DOM here and the engine does not pretend there is one: with no
+ * `document` in the process it writes to an in-memory string sink, and `getStyles()` reads it back.
+ */
+/**
+ * The CSS for everything rendered since the last reset. Flushes first, so it is safe straight after
+ * `renderToString` — no effects have run at that point. Goes in a `<style id="box-kite-styles">` in the head.
+ */
+export declare function getStyles(): string;
+/**
+ * Drop every rule, class name and variable the engine has emitted, so the next request starts blank.
+ * Registration (`Box.extend()`, `Box.components()`) survives. Call it once per request, after `getStyles()`.
+ */
+export declare function resetStyles(): void;
+/**
+ * Render `element` to static HTML together with its CSS. With `addStylesToHead` (the default) and a
+ * `<head>` in the tree the styles go there; otherwise use the returned `styles`. The engine is reset
+ * before returning, so sequential calls are independent.
+ */
+export declare function renderToStaticMarkup(element: React.ReactElement, addStylesToHead?: boolean): {
+    html: string;
+    styles: string;
+};

package/ssg.mjs

@@ -0,0 +1,25 @@
+import { r as e } from "./client.mjs";
+import t from "react-dom/server";
+//#region src/ssg.ts
+function n() {
+	return e.getStyles();
+}
+function r() {
+	e.clear();
+}
+function i(i, a = !0) {
+	let o = t.renderToStaticMarkup(i), s = n();
+	if (a) {
+		let t = o.indexOf("<head>");
+		if (t > -1) {
+			let n = t + 6;
+			o = o.substring(0, n) + `<style id="${e.styleElementId()}">${s}</style>` + o.substring(n);
+		}
+	}
+	return r(), {
+		html: o,
+		styles: s
+	};
+}
+//#endregion
+export { n as getStyles, i as renderToStaticMarkup, r as resetStyles };

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/animation/animationUtils.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The model behind `<Presence>`: how long the CSS already on an element says its current transition or
+ * animation lasts. No React and no DOM — it reads a `CSSStyleDeclaration`-shaped record, so CSS's
+ * list-cycling rules are testable without a browser, which is the only place they are ever exercised.
+ */
+declare namespace AnimationUtils {
+    /** The computed timing properties `activeDuration` reads. A `CSSStyleDeclaration` satisfies it. */
+    interface Timing {
+        transitionDuration: string;
+        transitionDelay: string;
+        animationName: string;
+        animationDuration: string;
+        animationDelay: string;
+        animationIterationCount: string;
+    }
+    /**
+     * One frame of head-room on a measured wait. The timer starts in the commit that applies the leaving
+     * styles, and the browser only creates the transition on the style recalculation after it — so the
+     * exit really ends a frame later than the duration alone says.
+     */
+    const SETTLE_FRAME = 16;
+    /**
+     * How long the element's own CSS says it has left to move, in ms. `0` means nothing is set up to run —
+     * which is also what `prefers-reduced-motion` produces, since every Box transition rides
+     * `--transitionTime` and that media query sets it to `0s`.
+     */
+    function activeDuration(timing: Timing): number;
+}
+export default AnimationUtils;

package/utils/array/arrayUtils.d.ts

@@ -0,0 +1,15 @@
+export type SortDirection = 'ASC' | 'DESC';
+export interface GroupItem<TKey, T> {
+    key: TKey;
+    values: T[];
+}
+declare namespace ArrayUtils {
+    function take<T>(items: readonly T[], count: number, skip?: number): T[];
+    function sumBy<T>(items: readonly T[], fn: (value: T, index: number) => number, initialValue?: number): number;
+    function sortBy<T, TVal>(items: readonly T[], fn: (value: T) => TVal, direction?: SortDirection): T[];
+    function maxBy<T>(items: readonly T[], fn: (value: T) => number): number;
+    function findOrThrow<T>(items: readonly T[], predicate: (value: T) => boolean): T;
+    function toRecord<T, K extends string | number | symbol, V>(items: readonly T[], fn: (value: T) => [K, V] | undefined): Record<K, V>;
+    function groupBy<T, TKey extends string | number | symbol>(items: readonly T[], keySelector: (item: T, index: number) => TKey): GroupItem<TKey, T>[];
+}
+export default ArrayUtils;

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/box/boxUtils.d.ts

@@ -0,0 +1,5 @@
+import { BoxStylesWithPseudoClasses } from '@box-kite/core/types';
+declare namespace BoxUtils {
+    function assignBooleanProp<TProps>(prop: boolean | [boolean, BoxStylesWithPseudoClasses] | undefined, name: string, props: TProps): void;
+}
+export default BoxUtils;

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

@@ -0,0 +1,92 @@
+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,
+ * models decide — which is also what makes a path string testable with no DOM. Everything is measured
+ * in one square of `VIEW` user units.
+ */
+declare namespace ChartUtils {
+    /** The side of the square every primitive draws inside. */
+    const VIEW = 100;
+    /** The centre of that square, where a ring or a donut is centred. */
+    const CENTRE: number;
+    /**
+     * The step a ring fraction is rounded to. A dash length lands in a *class name*, so an unrounded
+     * fraction would mean a rule per value; half a percent of a 96px ring is a third of a pixel, and the
+     * arc can still transition. Data-driven *paths* need none of this — a `d` attribute generates no CSS.
+     */
+    const FRACTION_STEP = 0.005;
+    interface Point {
+        x: number;
+        y: number;
+    }
+    /** The ends of the value axis. Either can be fixed, so many rows can share one scale. */
+    interface Domain {
+        min?: number;
+        max?: number;
+    }
+    /** Rounded to `FRACTION_STEP` and clamped to the path: a ring cannot be more than full. */
+    function fraction(value: number): number;
+    /**
+     * The data as points in the view box, `y` already flipped for SVG's downward axis. Two decisions rather
+     * than guards: one datum is a flat line across the box, and data that never changes sits in the middle
+     * (`max === min` has no scale) instead of collapsing onto the floor.
+     */
+    function points(data: readonly number[], domain?: Domain): Point[];
+    /** The points as a polyline: `M x y L x y …`. */
+    function linePath(points: readonly Point[]): string;
+    /** The same line, closed down both sides to the floor of the box so it can be filled. */
+    function areaPath(points: readonly Point[]): string;
+    /**
+     * The data as bars in **one** path, because these are drawn fifty rows at a time inside a scrolling
+     * grid. `gap` is the share of each slot left empty; every bar keeps a floor of one unit, so a
+     * bottom-of-the-scale value reads as a mark on the axis rather than as missing data.
+     */
+    function barsPath(data: readonly number[], domain?: Domain, gap?: number): string;
+    /** The radius that fits a stroke of `thickness` inside the box, without clipping either edge. */
+    function radius(thickness: number): number;
+    /** The length of a full circle of that radius. */
+    function circumference(radius: number): number;
+    /**
+     * The dash pair that reveals `value` (0–1) of a path `length` long: one dash as long as the whole path,
+     * offset backwards, so the arc grows from its own beginning. Both are Box props, so it transitions.
+     */
+    function dash(length: number, value: number): {
+        strokeDasharray: number;
+        strokeDashoffset: number;
+    };
+    /** How long an arc of `sweep` degrees is — the path length a `dash` is measured against. */
+    function arcLength(radius: number, sweep: number): number;
+    /**
+     * An arc as a path, from `start` degrees clockwise through `sweep`. Only constants of the shape reach
+     * this, so it is the same string for every gauge alike and belongs in the `d` attribute. A full turn is
+     * split in half — one arc whose ends coincide draws nothing at all.
+     */
+    function arcPath(radius: number, start: number, sweep: number): string;
+    /** One segment of a donut: the dash that draws it, and how far round the circle it starts. */
+    interface Segment {
+        /** The visible run and the gap that follows it, as a `strokeDasharray` value. */
+        strokeDasharray: string;
+        /** Degrees clockwise from twelve o'clock — written as the `transform` attribute. */
+        rotate: number;
+        /** The datum this segment was drawn from, and its position in the data. */
+        value: number;
+        index: number;
+    }
+    /**
+     * One segment per value, each the share of the circle it is worth: the same circle dashed to its own
+     * length and turned by an *attribute*, so the angles generate no rules. Values summing to nothing give
+     * no segments rather than a division by zero, and a negative value counts as none.
+     */
+    function donutSegments(data: readonly number[], length: number): Segment[];
+    const PALETTE: readonly ["sky-500", "emerald-500", "amber-500", "violet-500", "rose-500", "cyan-500"];
+    const DARK_PALETTE: readonly ["sky-400", "emerald-400", "amber-400", "violet-400", "rose-400", "cyan-400"];
+    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
+     * chart naming no colour has its dark mode decided by the page. A record names its own paint per series.
+     */
+    function seriesVariables(series: readonly string[] | Readonly<Record<string, string>>, slots?: number): Record<string, string>;
+}
+export default ChartUtils;

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;