@box-kite/react 0.0.1 → 2.0.0

package/components/chart.mjs

@@ -0,0 +1,236 @@
+import { n as e, r as t, t as n } from "../react-shared.mjs";
+import { Circle as r, Path as i, Svg as a } from "./svg.mjs";
+import { forwardRef as o } from "react";
+import { Fragment as s, jsx as c, jsxs as l } from "react/jsx-runtime";
+import u from "@box-kite/react";
+//#region src/utils/chart/chartUtils.ts
+var d;
+(function(r) {
+	let i = r.VIEW = 100, a = r.CENTRE = i / 2, o = r.FRACTION_STEP = .005;
+	function s(e) {
+		return Math.round(e * 100) / 100;
+	}
+	function c(e) {
+		return Math.round(Math.min(Math.max(e, 0), 1) / o) * o;
+	}
+	r.fraction = c;
+	function l(e, t = {}) {
+		if (e.length === 0) return [];
+		let n = t.min ?? Math.min(...e), r = (t.max ?? Math.max(...e)) - n, o = (e) => s(r === 0 ? a : i - (e - n) / r * i);
+		if (e.length === 1) return [{
+			x: 0,
+			y: o(e[0])
+		}, {
+			x: i,
+			y: o(e[0])
+		}];
+		let c = i / (e.length - 1);
+		return e.map((e, t) => ({
+			x: s(t * c),
+			y: o(e)
+		}));
+	}
+	r.points = l;
+	function u(e) {
+		return e.length === 0 ? "" : e.map((e, t) => `${t === 0 ? "M" : "L"}${e.x} ${e.y}`).join("");
+	}
+	r.linePath = u;
+	function d(e) {
+		if (e.length === 0) return "";
+		let t = e[e.length - 1];
+		return `${u(e)}L${t.x} ${i}L${e[0].x} ${i}Z`;
+	}
+	r.areaPath = d;
+	function f(e, t = {}, n = .25) {
+		if (e.length === 0) return "";
+		let r = i / e.length, a = s(r * (1 - n)), o = s((r - a) / 2);
+		return l(e, t).map((e, t) => {
+			let n = Math.min(e.y, i - 1);
+			return `M${s(t * r + o)} ${n}h${a}v${s(i - n)}h${-a}Z`;
+		}).join("");
+	}
+	r.barsPath = f;
+	function p(e) {
+		return s(a - e / 2);
+	}
+	r.radius = p;
+	function m(e) {
+		return s(2 * Math.PI * e);
+	}
+	r.circumference = m;
+	function h(e, t) {
+		return {
+			strokeDasharray: s(e),
+			strokeDashoffset: s(e * (1 - c(t)))
+		};
+	}
+	r.dash = h;
+	function g(e, t) {
+		let n = (t - 90) * Math.PI / 180;
+		return {
+			x: s(a + e * Math.cos(n)),
+			y: s(a + e * Math.sin(n))
+		};
+	}
+	function _(e, t) {
+		return s(m(e) * (Math.min(Math.abs(t), 360) / 360));
+	}
+	r.arcLength = _;
+	function v(e, t, n) {
+		if (Math.abs(n) >= 360) {
+			let n = g(e, t), r = g(e, t + 180);
+			return `M${n.x} ${n.y}A${e} ${e} 0 0 1 ${r.x} ${r.y}A${e} ${e} 0 0 1 ${n.x} ${n.y}`;
+		}
+		let r = g(e, t), i = g(e, t + n), a = +(Math.abs(n) > 180), o = n < 0 ? 0 : 1;
+		return `M${r.x} ${r.y}A${e} ${e} 0 ${a} ${o} ${i.x} ${i.y}`;
+	}
+	r.arcPath = v;
+	function y(e, t) {
+		let n = e.reduce((e, t) => e + Math.max(t, 0), 0);
+		if (n <= 0) return [];
+		let r = 0;
+		return e.map((e, i) => {
+			let a = c(Math.max(e, 0) / n), o = s(t * a), l = s(r * 360);
+			return r += a, {
+				strokeDasharray: `${o} ${s(t - o)}`,
+				rotate: l,
+				value: e,
+				index: i
+			};
+		});
+	}
+	r.donutSegments = y;
+	let b = r.PALETTE = e;
+	r.DARK_PALETTE = n, r.paletteVariables = t;
+	function x(e, t = b.length) {
+		return (Array.isArray(e) ? e.map((e, n) => [e, `var(--chart-${n % t + 1})`]) : Object.entries(e)).reduce((e, [t, n]) => (e[`color-${t}`] = n, e), {});
+	}
+	r.seriesVariables = x;
+})(d ||= {});
+var f = d, p = `0 0 ${f.VIEW} ${f.VIEW}`, m = f.PALETTE;
+function h(e, t) {
+	let { data: n, variant: r = "line", min: o, max: u, children: d, ...m } = e, h = {
+		min: o,
+		max: u
+	}, g = f.points(n, h);
+	return /* @__PURE__ */ l(a, {
+		viewBox: p,
+		component: "sparkline",
+		preserveAspectRatio: "none",
+		width: "100%",
+		height: "1.5rem",
+		ref: t,
+		...m,
+		children: [r === "bar" ? /* @__PURE__ */ c(i, {
+			component: "sparkline.bar",
+			d: f.barsPath(n, h)
+		}) : /* @__PURE__ */ l(s, { children: [r === "area" && /* @__PURE__ */ c(i, {
+			component: "sparkline.area",
+			d: f.areaPath(g)
+		}), /* @__PURE__ */ c(i, {
+			component: "sparkline.line",
+			d: f.linePath(g)
+		})] }), d]
+	});
+}
+var g = /* @__PURE__ */ o(h);
+g.displayName = "Sparkline";
+function _(e, t) {
+	let { value: n, thickness: i = 10, trackOpacity: o, children: s, ...u } = e, d = f.radius(i), m = f.circumference(d);
+	return /* @__PURE__ */ l(a, {
+		viewBox: p,
+		component: "progressRing",
+		width: "3rem",
+		height: "3rem",
+		strokeWidth: i,
+		ref: t,
+		...u,
+		children: [
+			/* @__PURE__ */ c(r, {
+				component: "progressRing.track",
+				cx: f.CENTRE,
+				cy: f.CENTRE,
+				r: d,
+				strokeOpacity: o
+			}),
+			/* @__PURE__ */ c(r, {
+				component: "progressRing.arc",
+				cx: f.CENTRE,
+				cy: f.CENTRE,
+				r: d,
+				transform: `rotate(-90 ${f.CENTRE} ${f.CENTRE})`,
+				...f.dash(m, n)
+			}),
+			s
+		]
+	});
+}
+var v = /* @__PURE__ */ o(_);
+v.displayName = "ProgressRing";
+function y(e, t) {
+	let { value: n, thickness: r = 10, trackOpacity: o, sweep: s = 270, start: u = 225, children: d, ...m } = e, h = f.radius(r), g = f.arcLength(h, s), _ = f.arcPath(h, u, s);
+	return /* @__PURE__ */ l(a, {
+		viewBox: p,
+		component: "gauge",
+		width: "4rem",
+		height: "4rem",
+		strokeWidth: r,
+		ref: t,
+		...m,
+		children: [
+			/* @__PURE__ */ c(i, {
+				component: "gauge.track",
+				d: _,
+				strokeOpacity: o
+			}),
+			/* @__PURE__ */ c(i, {
+				component: "gauge.arc",
+				d: _,
+				...f.dash(g, n)
+			}),
+			d
+		]
+	});
+}
+var b = /* @__PURE__ */ o(y);
+b.displayName = "Gauge";
+function x(e, t) {
+	let { data: n, colors: i = m, thickness: o = 20, children: s, ...u } = e, d = f.radius(o), h = f.circumference(d);
+	return /* @__PURE__ */ l(a, {
+		viewBox: p,
+		component: "miniDonut",
+		width: "3rem",
+		height: "3rem",
+		strokeWidth: o,
+		ref: t,
+		...u,
+		children: [f.donutSegments(n, h).map((e) => /* @__PURE__ */ c(r, {
+			component: "miniDonut.segment",
+			cx: f.CENTRE,
+			cy: f.CENTRE,
+			r: d,
+			stroke: i[e.index % i.length],
+			strokeDasharray: e.strokeDasharray,
+			transform: `rotate(${e.rotate - 90} ${f.CENTRE} ${f.CENTRE})`
+		}, e.index)), s]
+	});
+}
+var S = /* @__PURE__ */ o(x);
+S.displayName = "MiniDonut";
+function C(e, t) {
+	let { series: n, vars: r, ...i } = e, a = {
+		...n ? f.seriesVariables(n) : {},
+		...r
+	};
+	return /* @__PURE__ */ c(u, {
+		ref: t,
+		component: "chartContainer",
+		vars: a,
+		...i
+	});
+}
+var w = o(C);
+w.displayName = "ChartContainer";
+var T = w;
+//#endregion
+export { T as ChartContainer, b as Gauge, S as MiniDonut, v as ProgressRing, g as Sparkline };

package/components/checkbox.cjs

@@ -0,0 +1 @@
+"use client";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("../react-shared.cjs"),t=require("../box.cjs"),n=require("../forms.cjs");let r=require("react"),i=require("react/jsx-runtime");var a=[`name`,`onInput`,`onChange`,`autoFocus`,`readOnly`,`value`,`defaultChecked`];function o(o,s){let{label:c,labelProps:l,...u}=o,d=Array.isArray(o.indeterminate)?o.indeterminate[0]:o.indeterminate,f=typeof d==`boolean`&&d,p=e.i.buildProps(u,a,{type:`checkbox`,...f?{"aria-checked":`mixed`}:{}}),m=(0,r.useRef)(null);return(0,r.useImperativeHandle)(s,()=>m.current),(0,r.useEffect)(()=>{m.current&&(m.current.indeterminate=f)},[m,f]),(0,i.jsx)(n.n,{label:c,labelProps:l,children:(0,i.jsx)(t.default,{tag:`input`,ref:m,component:`checkbox`,...p})})}var s=(0,r.forwardRef)(o);s.displayName=`Checkbox`,exports.default=s;

package/components/checkbox.d.ts

@@ -0,0 +1,36 @@
+import { RefAttributes } from 'react';
+import { BoxTagProps, BoxProps } from '../box';
+import { OmitTagProps } from '../react/boxProps';
+import { ComponentsAndVariants } from '@box-kite/core/types';
+declare const tagProps: readonly ["name", "onInput", "onChange", "autoFocus", "readOnly", "value", "defaultChecked"];
+type TagPropsType = (typeof tagProps)[number];
+type CheckboxProps<TKey extends keyof ComponentsAndVariants> = Omit<BoxProps<'input', TKey>, 'tag' | 'props'>;
+type CheckboxTagProps = OmitTagProps<BoxTagProps<'input'>, TagPropsType | 'type'>;
+interface Props<TKey extends keyof ComponentsAndVariants> extends CheckboxProps<TKey> {
+    /** What the checkbox submits under. Needed for a form; a controlled checkbox can do without one. */
+    name?: string;
+    /** Attributes for the `<input>` itself — `type` is the component's, and so is `aria-checked`. */
+    props?: CheckboxTagProps;
+    /** Fires on every click or keystroke. On a checkbox this is the same moment as `onChange`. */
+    onInput?: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Fires when the box is ticked or cleared. `e.target.checked` is the new state. */
+    onChange?: (e: React.ChangeEvent<HTMLInputElement>) => void;
+    /** The value the form submits when it is checked. Defaults to `"on"`, as HTML does. */
+    value?: string | number;
+    /** Focus it on mount. One per page at most — a stolen focus is a lost place in the document. */
+    autoFocus?: boolean;
+    /** Rendered and read, but not toggleable. Unlike `disabled` it stays in the tab order and submits. */
+    readOnly?: boolean;
+    /** The state it starts in when the checkbox is uncontrolled. Pass `checked` instead to control it. */
+    defaultChecked?: boolean;
+    /**
+     * The text beside the checkbox — rendered inside a `<label>` that wraps the input, so the
+     * association is the component's job. Without it a consumer has to wire `htmlFor`/`id` by hand,
+     * and a checkbox with no label is the single most common accessibility failure there is.
+     */
+    label?: React.ReactNode;
+    /** Styles for the wrapping `<label>`: the row's layout, not the box's own appearance. */
+    labelProps?: BoxProps<'label'>;
+}
+declare const _default: <TKey extends keyof ComponentsAndVariants = "checkbox">(props: Props<TKey> & RefAttributes<HTMLInputElement>) => React.ReactNode;
+export default _default;

package/components/checkbox.mjs

@@ -0,0 +1,38 @@
+"use client";
+import { i as e } from "../react-shared.mjs";
+import t from "../box.mjs";
+import { n } from "../forms.mjs";
+import { forwardRef as r, useEffect as i, useImperativeHandle as a, useRef as o } from "react";
+import { jsx as s } from "react/jsx-runtime";
+//#region src/components/checkbox.tsx
+var c = [
+	"name",
+	"onInput",
+	"onChange",
+	"autoFocus",
+	"readOnly",
+	"value",
+	"defaultChecked"
+];
+function l(r, l) {
+	let { label: u, labelProps: d, ...f } = r, p = Array.isArray(r.indeterminate) ? r.indeterminate[0] : r.indeterminate, m = typeof p == "boolean" && p, h = e.buildProps(f, c, {
+		type: "checkbox",
+		...m ? { "aria-checked": "mixed" } : {}
+	}), g = o(null);
+	return a(l, () => g.current), i(() => {
+		g.current && (g.current.indeterminate = m);
+	}, [g, m]), /* @__PURE__ */ s(n, {
+		label: u,
+		labelProps: d,
+		children: /* @__PURE__ */ s(t, {
+			tag: "input",
+			ref: g,
+			component: "checkbox",
+			...h
+		})
+	});
+}
+var u = r(l);
+u.displayName = "Checkbox";
+//#endregion
+export { u as default };

package/components/combobox/comboboxChips.d.ts

@@ -0,0 +1,21 @@
+import { ClassNameType } from '@box-kite/core';
+import { ComboboxRowDef } from '../../utils/combobox/comboboxUtils';
+export interface ComboboxChipsProps<TRow> {
+    selection: TRow[];
+    def: ComboboxRowDef<TRow>;
+    /** Custom chip content. The label is still the accessible name of its remove button. */
+    display?: (row: TRow) => React.ReactNode;
+    /** The remove button's accessible name, given the row's label. */
+    removeLabel: (label: string) => string;
+    onRemove: (row: TRow, event: React.MouseEvent) => void;
+    disabled?: boolean;
+    variant: ClassNameType;
+}
+/**
+ * The selection, in front of the field, one chip each. The remove buttons are deliberately **not** tab
+ * stops: a control holding twenty selections would otherwise cost twenty presses to Tab past. Removal
+ * from the keyboard is Backspace on an empty field and toggling the row in the listbox, so the function
+ * is reachable without them — and each button still carries a name, so it can be found and pressed by
+ * anyone reading the control rather than tabbing through it.
+ */
+export default function ComboboxChips<TRow>(props: ComboboxChipsProps<TRow>): import("react").JSX.Element;

package/components/combobox/comboboxListbox.d.ts

@@ -0,0 +1,47 @@
+import { ClassNameType } from '@box-kite/core';
+import { BoxStyleProps } from '@box-kite/core/types';
+import { ComboboxRow, ComboboxRowDef } from '../../utils/combobox/comboboxUtils';
+import { ElementLike } from '../../utils/dom/domUtils';
+import { PresenceHandle } from '../presence';
+/** How a long list is windowed, or `false` to render every row of it however many there are. */
+export interface ComboboxVirtualize {
+    /** The pitch of a row, when it should be declared rather than measured off the rendered ones. */
+    itemHeight?: number;
+    /** Rows kept either side of what is visible. */
+    overscan?: number;
+    /** How many rows it takes before windowing starts. */
+    threshold?: number;
+}
+export interface ComboboxListboxProps<TRow> {
+    /** Which way the popup is going, from the `<Presence>` that owns its mount. */
+    presence: PresenceHandle;
+    /** Every row the listbox shows, already in keyboard order. */
+    rows: ComboboxRow<TRow>[];
+    def: ComboboxRowDef<TRow>;
+    /** Custom row rendering. The label is still what is searched and what the field shows. */
+    display?: (row: TRow) => React.ReactNode;
+    selection: TRow[];
+    multiple: boolean;
+    /** The row the keyboard is on, or `-1` when it is on none of them. */
+    activeIndex: number;
+    optionId: (index: number) => string;
+    rowRef: (index: number) => (element: HTMLElement | null) => void;
+    onSelect: (index: number, event: React.SyntheticEvent) => void;
+    /** The shell the popup hangs off: the field and its chips. */
+    anchorRef: ElementLike;
+    /** The layer element — what the dismissal hook treats as *inside* the popup. */
+    popupRef: React.Ref<HTMLDivElement>;
+    listboxId: string;
+    labelledBy: string;
+    /** Options are on their way. Says so rather than claiming the list is empty. */
+    loading?: boolean;
+    loadingText: React.ReactNode;
+    emptyText: React.ReactNode;
+    /** What the create row reads. Given the query, since the row it would make is not shown. */
+    createLabel: (query: string) => React.ReactNode;
+    /** Render only the rows on screen. On above the threshold by default; `false` never. */
+    virtualize?: boolean | ComboboxVirtualize;
+    variant: ClassNameType;
+    itemsProps?: BoxStyleProps;
+}
+export default function ComboboxListbox<TRow>(props: ComboboxListboxProps<TRow>): import("react").JSX.Element;

package/components/combobox.cjs

@@ -0,0 +1 @@
+"use client";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("../effects.cjs"),t=require("../box.cjs"),n=require("../behavior.cjs"),r=require("../identity.cjs"),i=require("./svg.cjs"),a=require("./flex.cjs"),o=require("./overlay.cjs"),s=require("./presence.cjs");let c=require("react"),l=require("react/jsx-runtime");var u;(function(e){function t(e,t){return typeof e==`function`?e(t):t[e]}e.read=t;function n(e,n){let r=t(e.label,n);return r==null?``:String(r)}e.labelOf=n;function r(e,r){return e.key===void 0?n(e,r):t(e.key,r)}e.keyOf=r;function i(e,n){return e.disabled!==void 0&&t(e.disabled,n)===!0}e.isDisabled=i;let a=/\p{M}/gu;function o(e){return e.normalize(`NFD`).replace(a,``).toLowerCase()}e.normalize=o;function s(e,t){return o(e).includes(o(t))}e.matches=s;function c(e,t,n){return t===``?e:e.filter(e=>s(n(e),t))}e.filterRows=c;function l(e){return e==null?[]:Array.isArray(e)?e:[e]}e.toArray=l;function u(e,t,n){let r=n(t);return e.some(e=>n(e)===r)}e.isSelected=u;function d(e,t,n,r){return n?u(e,t,r)?e.filter(e=>r(e)!==r(t)):[...e,t]:[t]}e.toggle=d;function f(e){let{data:t,def:r,query:i,filter:a,typed:s,createRow:c}=e,l=e=>n(r,e),u=(!s||a===!1?t:a(t,i,l)).map(e=>({kind:`option`,row:e}));return c&&i!==``&&!t.some(e=>o(l(e))===o(i))&&c(i)!==null&&u.push({kind:`create`,query:i}),u}e.rowsFor=f;function p(e,t){return t.kind===`option`&&i(e,t.row)}e.isRowDisabled=p;function m(e,t,n,i=`first`){let a=e=>r(n,e),o=e.findIndex(e=>e.kind===`option`&&u(t,e.row,a));if(o!==-1&&!p(n,e[o]))return o;let s=e.map((e,t)=>p(n,e)?-1:t).filter(e=>e!==-1);return(i===`last`?s[s.length-1]:s[0])??-1}e.activeIndexFor=m})(u||={});var d=u;function f(e){let{selection:t,def:n,display:r,removeLabel:o,onRemove:s,disabled:c,variant:u}=e;return(0,l.jsx)(l.Fragment,{children:t.map(e=>{let t=d.labelOf(n,e);return(0,l.jsxs)(a.default,{component:`combobox.chip`,variant:u,ai:`center`,gap:1,children:[r?.(e)??t,!c&&(0,l.jsx)(a.default,{tag:`button`,component:`combobox.remove`,variant:u,ai:`center`,jc:`center`,props:{type:`button`,tabIndex:-1,"aria-label":o(t),onMouseDown:e=>e.preventDefault(),onClick:t=>{t.stopPropagation(),s(e,t)}},children:(0,l.jsx)(i.Svg,{viewBox:`0 0 24 24`,width:`0.625rem`,props:{fill:`none`},children:(0,l.jsx)(i.Path,{d:`M6 6 18 18M18 6 6 18`,stroke:`currentColor`,strokeWidth:3,strokeLinecap:`round`})})})]},d.keyOf(n,e))})})}var p;(function(e){let t=e.DEFAULT_OVERSCAN=4,n=e.DEFAULT_THRESHOLD=100;e.DEFAULT_ITEM_HEIGHT=36,e.DEFAULT_VIEW_HEIGHT=248;function r(e,t,n){return Math.min(Math.max(e,t),n)}function i(e,t,r=n){return t??e>r}e.shouldVirtualize=i;function a(e){let{count:n,itemHeight:i,viewHeight:a,scrollTop:o,overscan:s=t,activeIndex:c=-1}=e;if(n<=0||i<=0)return{startIndex:0,endIndex:Math.max(0,n),offsetY:0,totalHeight:0};let l=Math.max(1,Math.ceil(a/i)),u=Math.min(n,l+s*2),d=n-u,f=r(Math.floor(o/i)-s,0,d);return c>=0&&c<n&&(c<f?f=r(c-s,0,d):c>=f+u&&(f=r(c+1+s-u,0,d))),{startIndex:f,endIndex:f+u,offsetY:f*i,totalHeight:n*i}}e.windowFor=a})(p||={});var m=p;function h(t){let{count:r,scrollerRef:i,itemHeight:a,viewHeight:o,overscan:s,threshold:l,enabled:u,activeIndex:d}=t,[f,p]=(0,c.useState)({top:0,at:-1}),[h,g]=(0,c.useState)({itemHeight:0,viewHeight:0}),_=(0,c.useRef)(null),v=(0,c.useCallback)(e=>{_.current=e},[]),y=m.shouldVirtualize(r,u,l),b=n.a(()=>{let e=i.current,t=_.current;if(!e||!t)return;let n=t.children,r=n[0],a=n[1],o=a?a.offsetTop-r.offsetTop:r?.offsetHeight??0,s=e.clientHeight;g(e=>e.itemHeight===o&&e.viewHeight===s?e:{itemHeight:o,viewHeight:s})});e.n(()=>{if(!y||(b(),typeof ResizeObserver>`u`))return;let e=i.current;if(!e)return;let t=new ResizeObserver(b);return t.observe(e),()=>t.disconnect()},[y,r,b,i]);let x=n.a(e=>{p({top:e.currentTarget.scrollTop,at:d??-1})}),S=m.windowFor({count:r,itemHeight:a??(h.itemHeight>0?h.itemHeight:m.DEFAULT_ITEM_HEIGHT),viewHeight:o??(h.viewHeight>0?h.viewHeight:m.DEFAULT_VIEW_HEIGHT),scrollTop:f.top,overscan:s,activeIndex:d===f.at?-1:d});return y?{...S,virtualized:y,contentRef:v,onScroll:x}:{startIndex:0,endIndex:r,offsetY:0,totalHeight:0,virtualized:y,contentRef:v,onScroll:x}}function g(e,t,n,r){return e?{role:`listbox`,"aria-labelledby":r,...t?{"aria-multiselectable":!0}:{},...n?{"aria-busy":!0}:{}}:{role:`status`}}function _(e){let{presence:n,rows:r,def:i,display:s,selection:u,multiple:f,activeIndex:p,optionId:m,rowRef:_,onSelect:v}=e,{anchorRef:y,popupRef:b,listboxId:x,labelledBy:S,loading:C,loadingText:ee,emptyText:w,createLabel:te,variant:T,itemsProps:ne}=e,{virtualize:E}=e,{present:D,ref:O,props:re}=n,k=e=>d.keyOf(i,e),[A,ie]=(0,c.useState)(!1),ae=(0,c.useCallback)(e=>ie(e===`top`),[]),j=(0,c.useRef)(null),oe=(0,c.useCallback)(e=>{j.current=e,O(e)},[O]),M=typeof E==`object`?E:{},{virtualized:N,startIndex:P,endIndex:se,offsetY:F,totalHeight:I,contentRef:L,onScroll:R}=h({count:r.length,scrollerRef:j,enabled:typeof E==`boolean`?E:void 0,activeIndex:p,...M}),z=N?r.slice(P,se):r,B=(e,t)=>{let n=N?P+t:t,o=e.kind===`option`&&d.isSelected(u,e.row,k),c=d.isRowDisabled(i,e);return(0,l.jsx)(a.default,{ref:_(n),component:`combobox.item`,variant:[T,{create:e.kind===`create`,highlighted:n===p}],selected:o,ai:`center`,gap:2,id:m(n),props:{role:`option`,...N?{"aria-setsize":r.length,"aria-posinset":n+1}:{},...c?{"aria-disabled":!0}:{},onMouseDown:e=>e.preventDefault(),onClick:e=>!c&&v(n,e)},children:e.kind===`create`?te(e.query):s?.(e.row)??d.labelOf(i,e.row)},e.kind===`option`?k(e.row):`create`)};return(0,l.jsx)(o.default,{ref:b,anchor:y,side:`bottom`,align:`start`,offset:.5,matchWidth:!0,onSideChange:ae,children:(0,l.jsxs)(t.default,{ref:oe,component:`combobox.items`,...ne,variant:[T,{closed:!D&&!A,closedUp:!D&&A}],id:x,props:{...g(r.length>0,f,C===!0,S),...re,...N?{onScroll:R}:{}},children:[N?(0,l.jsx)(t.default,{ref:L,component:`combobox.window`,variant:T,style:{height:I,paddingTop:F},children:z.map(B)}):z.map(B),r.length===0&&(0,l.jsx)(t.default,{component:`combobox.message`,variant:T,children:C?ee:w})]})})}var v=new Set([` `,`Home`,`End`,`ArrowLeft`,`ArrowRight`]);function y(o,u){let{data:p,def:m,label:h,labelProps:g,placeholder:y,name:b,disabled:x,props:S,itemsProps:C,hideIcon:ee,filter:w=d.filterRows,loading:te,loadingText:T=`Loading...`,emptyText:ne=`No results`,createRow:E,createLabel:D=e=>`Create "${e}"`,removeLabel:O=e=>`Remove ${e}`,virtualize:re,query:k,defaultQuery:A,onQueryChange:ie,open:ae,defaultOpen:j,onOpenChange:oe,multiple:M=!1,value:N,defaultValue:P,onValueChange:se,...F}=o,I=r.t(`combobox`),L=F.id??`${I}-field`,R=`${I}-listbox`,z=`${I}-label`,B=h!=null&&h!==!1,ce=(0,c.useCallback)(e=>`${I}-option-${e}`,[I]),V=(0,c.useRef)(null),le=(0,c.useRef)(null),H=(0,c.useRef)(null),ue=(0,c.useCallback)(e=>{H.current=e,typeof u==`function`?u(e):u&&(u.current=e)},[u]),de=n.a((e,t)=>{se?.(M?e:e[0]??null,t)}),fe=(0,c.useMemo)(()=>N===void 0?void 0:d.toArray(N),[N]),[U,pe]=n.i({value:fe,defaultValue:()=>d.toArray(P),onChange:de}),[W,G]=n.i({value:ae,defaultValue:j??!1,onChange:oe}),[me,K]=n.i({value:k,defaultValue:A??``,onChange:ie}),[q,J]=(0,c.useState)(!1),Y=(0,c.useCallback)(e=>d.keyOf(m,e),[m]),he=M||U[0]===void 0?``:d.labelOf(m,U[0]),X=q||me!==``?me:he,Z=(0,c.useMemo)(()=>d.rowsFor({data:p,def:m,query:X,filter:w,typed:q,createRow:E}),[p,m,X,w,q,E]),ge=(0,c.useCallback)(e=>Z[e]?d.isRowDisabled(m,Z[e]):!1,[Z,m]),_e=n.a((e,t)=>{G(!1,{reason:e,event:t}),e!==`escape`&&(J(!1),K(``,{reason:`close`,event:t}))}),Q=n.a((e,t)=>{let n=Z[e];if(!n||ge(e))return;let r=n.kind===`create`?E?.(n.query):n.row;if(r==null)return;let i=d.isSelected(U,r,Y),a=n.kind===`create`?`create`:i&&M?`deselect`:`select`;pe(d.toggle(U,r,M,Y),{reason:a,event:t}),J(!1),K(``,{reason:`select`,event:t}),M||G(!1,{reason:`select`,event:t})}),ve=n.t({count:Z.length,focusItems:!1,defaultActiveIndex:-1,isDisabled:ge,onSelect:Q}),{activeIndex:$,setActiveIndex:ye,activeItem:be}=ve;n.r({enabled:W,inside:[V,le],onDismiss:(e,t)=>_e(e===`escape`?`escape`:`outside-pointer`,t)}),e.n(()=>{!W||$===-1||be()?.scrollIntoView?.({block:`nearest`})},[W,$,be]);let xe=(e,t,n)=>{G(!0,{reason:n,event:t});let r=e===`none`?-1:d.activeIndexFor(Z,U,m,e);ye(r,{reason:`programmatic`,event:t})},Se=n.a(e=>{J(!0),K(e.target.value,{reason:`input`,event:e}),W||G(!0,{reason:`input`,event:e}),ye(-1,{reason:`programmatic`,event:e})}),Ce=n.a((e,t)=>{pe(U.filter(t=>Y(t)!==Y(e)),{reason:`remove`,event:t})}),we=e=>{let{key:t}=e;if(t===`ArrowDown`||t===`ArrowUp`){e.preventDefault(),xe(t===`ArrowUp`?`last`:e.altKey?`none`:`first`,e,`trigger`);return}t===`Escape`&&X!==``&&(J(!0),K(``,{reason:`clear`,event:e}))},Te=n.a(e=>{if(S?.onKeyDown?.(e),!(e.defaultPrevented||x)){if(e.key===`Backspace`&&M&&X===``&&U.length>0){Ce(U[U.length-1],e);return}if(!W){we(e);return}if(e.key===`Tab`){$!==-1&&Q($,e),_e(`tab`,e);return}if(e.altKey&&e.key===`ArrowUp`){e.preventDefault(),$===-1?_e(`trigger`,e):Q($,e);return}if(v.has(e.key)){ye(-1,{reason:`programmatic`,event:e});return}ve.onKeyDown(e)}}),Ee=n.a(e=>{!x&&!W&&xe(`first`,e,`trigger`)}),De=n.a(e=>{x||e.target===H.current||(e.preventDefault(),H.current?.focus(),W||xe(`first`,e,`trigger`))}),Oe=Z.length>0||te===!0||ne!==null,ke=W&&$!==-1&&Z.length>0?ce($):void 0,Ae=(0,l.jsx)(t.default,{tag:`input`,component:`combobox.field`,ref:ue,id:L,disabled:x,props:{...S,role:`combobox`,"aria-autocomplete":`list`,"aria-expanded":W,"aria-controls":W&&Oe?R:void 0,"aria-activedescendant":ke,"aria-labelledby":B?z:S?.[`aria-labelledby`],autoComplete:`off`,spellCheck:!1,type:`text`,value:X,placeholder:y,onChange:Se,onKeyDown:Te,onClick:Ee}}),je=!ee&&(0,l.jsx)(a.default,{component:`combobox.icon`,rotate:W?180:0,props:{"aria-hidden":!0},children:(0,l.jsx)(i.Svg,{viewBox:`0 0 10 6`,width:`0.6rem`,props:{fill:`none`},children:(0,l.jsx)(i.Path,{d:`m1 1 4 4 4-4`,stroke:`currentColor`,strokeWidth:2,strokeLinecap:`round`,strokeLinejoin:`round`})})}),Me=b===void 0?null:U.map(e=>(0,l.jsx)(t.default,{tag:`input`,props:{type:`hidden`,name:b,value:String(Y(e))}},Y(e))),Ne=Oe&&(0,l.jsx)(s.default,{present:W,children:e=>(0,l.jsx)(_,{presence:e,rows:Z,def:m,display:m.display,selection:U,multiple:M,activeIndex:$,optionId:ce,rowRef:e=>ve.itemProps(e).ref,onSelect:Q,anchorRef:V,popupRef:le,listboxId:R,labelledBy:B?z:L,loading:te,loadingText:T,emptyText:ne,createLabel:D,virtualize:re,variant:F.variant,itemsProps:C})}),Pe=(0,l.jsxs)(a.default,{ref:V,component:`combobox`,ai:`center`,gap:1,flexWrap:`wrap`,...F,props:{onPointerDown:De},children:[Me,M&&(0,l.jsx)(f,{selection:U,def:m,display:m.display,removeLabel:O,onRemove:Ce,disabled:x,variant:F.variant}),Ae,je]});return B?(0,l.jsxs)(a.default,{d:`column`,gap:1,width:`fit-content`,children:[(0,l.jsx)(t.default,{tag:`label`,component:`combobox.label`,id:z,...g,props:{htmlFor:L},children:h}),Pe,Ne]}):(0,l.jsxs)(l.Fragment,{children:[Pe,Ne]})}var b=(0,c.forwardRef)(y);b.displayName=`Combobox`,exports.ComboboxUtils=d,exports.default=b;

package/components/combobox.d.ts

@@ -0,0 +1,121 @@
+import { RefAttributes } from 'react';
+import { BoxProps } from '../box';
+import { ChangeHandler } from '../react/a11y/useControllableState';
+import { BoxStyleProps, ComponentsAndVariants } from '@box-kite/core/types';
+import { ComboboxFilter, ComboboxRow, ComboboxRowDef } from '../utils/combobox/comboboxUtils';
+import { ComboboxVirtualize } from './combobox/comboboxListbox';
+/** Why the listbox opened or closed. `select` is the transition worth telling apart from a dismissal. */
+export type ComboboxOpenReason = 'trigger' | 'input' | 'select' | 'escape' | 'outside-pointer' | 'tab' | 'imperative';
+/** Why the selection changed. `remove` is a chip's own button; `deselect` is toggling a row back off. */
+export type ComboboxValueReason = 'select' | 'deselect' | 'create' | 'remove';
+/** Why the typed text changed. Only `input` came from a keystroke; the rest are the component tidying up. */
+export type ComboboxQueryReason = 'input' | 'select' | 'clear' | 'close';
+/** How a row is read and how it is drawn. Only `label` is required — it is the text and the name. */
+export interface ComboboxDef<TRow> extends ComboboxRowDef<TRow> {
+    /** Custom row rendering. The label is still what is searched, what the field shows and what is read out. */
+    display?: (row: TRow) => React.ReactNode;
+}
+interface BaseProps<TRow, TKey extends keyof ComponentsAndVariants = 'combobox'> extends Omit<BoxProps<'div', TKey>, 'ref' | 'tag' | 'children' | 'defaultValue' | 'onChange' | 'disabled' | 'placeholder' | 'open'> {
+    /** Every row the combobox can offer. Filtered by the query unless `filter` is `false`. */
+    data: TRow[];
+    /**
+     * How to read a row: its `label` (the text, which is searched and read out), its `key` (what makes two
+     * rows the same row), and optionally `disabled` and `display`. A key of the row, or a function.
+     */
+    def: ComboboxDef<TRow>;
+    /**
+     * The combobox's name, rendered above it in a real `<label>`. A combobox is not named by what it
+     * contains, so without this (or an `aria-label` of your own in `props`) it has no accessible name.
+     */
+    label?: React.ReactNode;
+    /** Styles for the `<label>` itself — it sits above the control rather than wrapping it. */
+    labelProps?: BoxProps<'label'>;
+    /** The field's placeholder. Not a name — it is gone on the first keystroke. See `label`. */
+    placeholder?: string;
+    /** What the selection submits under: one hidden input per selected row, carrying its key. */
+    name?: string;
+    /** Not editable and not openable, but still read out. The real attribute, on the field itself. */
+    disabled?: boolean;
+    /** Attributes for the `<input>` that *is* the combobox — an `aria-label`, an `inputMode`, an `id`. */
+    props?: Record<string, unknown>;
+    /** Styles for the popup (`combobox.items`). */
+    itemsProps?: BoxStyleProps;
+    /** Drop the chevron. It is decoration either way: `aria-hidden` and never focusable. */
+    hideIcon?: boolean;
+    /**
+     * Which rows a query leaves, and in what order — it takes the whole list so it can rank as well as
+     * reject, and is handed the label reader so composing it with the built-in one costs nothing.
+     * `false` means the data is already filtered, which is what a server that searched needs.
+     */
+    filter?: ComboboxFilter<TRow> | false;
+    /** Rows are on their way. The popup says so rather than claiming there are none. */
+    loading?: boolean;
+    /** What the popup shows while `loading` and there is nothing to show yet. */
+    loadingText?: React.ReactNode;
+    /** What the popup shows when the query matched nothing. */
+    emptyText?: React.ReactNode;
+    /**
+     * Turns the query into the row it would create, or `null` to refuse it. Its presence is what offers a
+     * create row at all, and one is never offered for a query a row already answers by name.
+     */
+    createRow?: (query: string) => TRow | null;
+    /** What the create row reads. Given the query, since the row it would make is not the one shown. */
+    createLabel?: (query: string) => React.ReactNode;
+    /**
+     * Render only the rows on screen, which is what a list of thousands needs to open in one frame. On by
+     * default above a hundred rows; an object tunes it (`threshold` is what turns it on earlier),
+     * `false` never windows and `true` always does. Rows have to be a uniform height for it, which is
+     * measured rather than declared — a `display` that varies one wants `false`.
+     */
+    virtualize?: boolean | ComboboxVirtualize;
+    /** A chip's remove button's accessible name, given the row's label. */
+    removeLabel?: (label: string) => string;
+    /** The typed text. Controlled — pair it with `onQueryChange`, which is also the hook an async search uses. */
+    query?: string;
+    /** The text the field starts with when the combobox owns its own query. */
+    defaultQuery?: string;
+    /** Fires with the text and why it changed. Only `input` came from a keystroke. */
+    onQueryChange?: ChangeHandler<string, ComboboxQueryReason>;
+    /** Whether the listbox is showing. Controlled — pair it with `onOpenChange`. */
+    open?: boolean;
+    /** Whether it starts open, when the combobox owns that itself. */
+    defaultOpen?: boolean;
+    /** Fires with the new state and why: a press, a keystroke, a choice, Escape, or a press outside. */
+    onOpenChange?: ChangeHandler<boolean, ComboboxOpenReason>;
+}
+/**
+ * One row at a time, which is the default: the value is a row or `null`, and the field shows the selected
+ * row's label whenever nothing is being typed.
+ */
+interface SingleProps<TRow> {
+    /** Leave it off, or `false`. See the multiple half for the other shape. */
+    multiple?: false;
+    /** The selected row, or `null`. Controlled — pair it with `onValueChange`. */
+    value?: TRow | null;
+    /** What is selected to begin with, when the combobox owns its own value. */
+    defaultValue?: TRow | null;
+    /** Fires with the row itself — the object out of `data`, not a key dug out of it — and why. */
+    onValueChange?: ChangeHandler<TRow | null, ComboboxValueReason>;
+}
+/**
+ * Several rows, shown as chips in front of the field, and the value is an array. Choosing a row that is
+ * already chosen takes it off again, which is the keyboard's way to a chip its own button cannot reach.
+ */
+interface MultipleProps<TRow> {
+    /** `true` is what turns the value into an array — the one shape a combobox cannot read off its value. */
+    multiple: true;
+    /** The selected rows. Controlled — pair it with `onValueChange`. */
+    value?: TRow[];
+    /** What is selected to begin with, when the combobox owns its own value. */
+    defaultValue?: TRow[];
+    /** Fires with the whole selection, as rows, and why it changed. */
+    onValueChange?: ChangeHandler<TRow[], ComboboxValueReason>;
+}
+type Props<TRow, TKey extends keyof ComponentsAndVariants = 'combobox'> = BaseProps<TRow, TKey> & (SingleProps<TRow> | MultipleProps<TRow>);
+interface ComboboxType {
+    <TRow, TKey extends keyof ComponentsAndVariants = 'combobox'>(props: Props<TRow, TKey> & RefAttributes<HTMLInputElement>): React.ReactNode;
+}
+declare const Combobox: ComboboxType;
+export default Combobox;
+export { default as ComboboxUtils } from '../utils/combobox/comboboxUtils';
+export type { ComboboxFilter, ComboboxRow, ComboboxRowDef, ComboboxVirtualize };