@box-kite/react 0.0.1 → 2.0.0

package/components/dialog.cjs

@@ -0,0 +1 @@
+"use client";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("../platform.cjs"),t=require("../client.cjs"),n=require("../effects.cjs"),r=require("../box.cjs"),i=require("../behavior.cjs"),a=require("../identity.cjs"),o=require("./semantics.cjs");let s=require("react"),c=require("react/jsx-runtime");var l=0;function u(r){let{classNames:i,styleElements:a}=t.i({overflow:`hidden`},!1),o=i.slice(1).join(` `);return n.n(()=>{let t=e.n();if(!(!r||!t||!o))return l+=1,t.classList.add(o),()=>{--l,l===0&&t.classList.remove(o)}},[r,o]),a}var d=(0,s.createContext)(null);function f(e){let t=(0,s.useContext)(d);if(!t)throw Error(`<${e}> must be rendered inside a <Dialog>.`);return t}function p(e){return(0,c.jsx)(h,{role:`dialog`,...e})}function m(e){return(0,c.jsx)(h,{role:`alertdialog`,...e,modal:!0,dismissible:!1})}function h(t){let{role:o,trigger:l,children:f,open:p,defaultOpen:m=!1,onOpenChange:h,label:_,labelledBy:v,describedBy:y,modal:b=!0,dismissible:x=!0,lockScroll:S=b,initialFocus:C,props:w,...T}=t,E=a.t(`dialog`),D=T.id??E,[O,k]=i.i({value:p,defaultValue:m,onChange:h}),[A,j]=(0,s.useState)(null),[M,N]=(0,s.useState)(null),[P,F]=(0,s.useState)(!1),[I,L]=(0,s.useState)({title:0,description:0}),R=u(O&&S);i.n({enabled:O,returnTo:M});let z=(0,s.useCallback)(e=>(L(t=>({...t,[e]:t[e]+1})),()=>L(t=>({...t,[e]:t[e]-1}))),[]),B=(0,s.useMemo)(()=>({titleId:`${D}-title`,descriptionId:`${D}-description`,register:z}),[D,z]);g({dialog:A,isOpen:O,domOpen:P,setDomOpen:F,setOpen:k,modal:b,dismissible:x,triggerElement:M}),n.n(()=>{let t=e.c(C);!O||!t||t.focus()},[O,C]);let V=i.a(e=>{k(e=>!e,{reason:`trigger`,event:e})}),H=(0,s.useMemo)(()=>({ref:N,props:{"aria-expanded":O,"aria-haspopup":`dialog`,"aria-controls":O?D:void 0,onClick:V}}),[D,V,O]),U=T;return(0,c.jsxs)(c.Fragment,{children:[R,l?.(H),(0,c.jsx)(d.Provider,{value:B,children:(0,c.jsx)(r.default,{ref:j,tag:`dialog`,component:`dialog`,...U,id:D,props:{role:o,"aria-label":I.title||v?void 0:_,"aria-labelledby":v??(I.title?B.titleId:void 0),"aria-describedby":y??(I.description?B.descriptionId:void 0),...w},children:f})})]})}function g(t){let{dialog:r,isOpen:a,domOpen:o,setDomOpen:c,setOpen:l,modal:u,dismissible:d,triggerElement:f}=t,p=(0,s.useRef)(`imperative`),m=e.i(),h=d?`any`:`closerequest`;n.n(()=>{!r||a===o||(c(a),a?u?r.showModal():r.show():r.close())},[r,a,o,u,c]),n.n(()=>{if(!r)return;let e=new AbortController;return r.addEventListener(`close`,e=>{c(!1),l(!1,{reason:p.current,event:e}),p.current=`imperative`},{signal:e.signal}),()=>e.abort()},[r,c,l]),n.n(()=>{if(!(!r||!m))return r.setAttribute(`closedby`,h),()=>r.removeAttribute(`closedby`)},[r,m,h]),n.n(()=>{if(!a||!r)return;let t=new AbortController,n=(e,n)=>document.addEventListener(e,n,{signal:t.signal,capture:!0});return n(`keydown`,e=>{e.key===`Escape`&&(p.current=`escape`)}),n(`pointerdown`,t=>{e.l(t,[f])?p.current=`trigger`:!e.l(t,[r])||_(r,t)?p.current=`outside-pointer`:p.current=`imperative`}),()=>t.abort()},[a,r,f]),i.r({enabled:a&&!u&&!m,inside:[r],escapeKey:!0,outsidePointer:!1,onDismiss:(e,t)=>l(!1,{reason:`escape`,event:t})}),n.n(()=>{if(!r||!a||!d||m)return;let t=new AbortController;return document.addEventListener(`pointerdown`,t=>{e.l(t,[f])||e.l(t,[r])&&!_(r,t)||l(!1,{reason:`outside-pointer`,event:t})},{signal:t.signal,capture:!0}),()=>t.abort()},[r,a,d,m,f,l])}function _(e,t){let n=e.getBoundingClientRect();return t.clientX<n.left||t.clientX>n.right||t.clientY<n.top||t.clientY>n.bottom}function v(e){let t=f(`Dialog.Title`);return n.n(()=>t.register(`title`),[t]),(0,c.jsx)(o.H2,{id:t.titleId,component:`dialog.title`,...e})}function y(e){let t=f(`Dialog.Description`);return n.n(()=>t.register(`description`),[t]),(0,c.jsx)(o.P,{id:t.descriptionId,component:`dialog.description`,...e})}v.displayName=`Dialog.Title`,y.displayName=`Dialog.Description`;var b={Title:v,Description:y},x=Object.assign(p,b),S=Object.assign(m,b);p.displayName=`Dialog`,m.displayName=`AlertDialog`,exports.AlertDialog=S,exports.default=x;

package/components/dialog.d.ts

@@ -0,0 +1,151 @@
+import { BoxProps } from '../box';
+import { ChangeHandler } from '../react/a11y/useControllableState';
+import { ComponentsAndVariants } from '@box-kite/core/types';
+import { ElementLike } from '../utils/dom/domUtils';
+/** Why the dialog opened or closed — `onOpenChange` gets this alongside the event that did it. */
+export type DialogReason = 'trigger' | 'escape' | 'outside-pointer' | 'imperative';
+/** The DOM attributes the trigger has to carry. */
+export interface DialogTriggerAttributes {
+    'aria-expanded': boolean;
+    'aria-haspopup': 'dialog';
+    'aria-controls'?: string;
+    onClick(event: React.MouseEvent): void;
+}
+/**
+ * What the trigger has to carry: spread it onto the control itself, not a wrapper. The `ref` is what
+ * focus returns to when the dialog closes, so it is not optional decoration.
+ *
+ * ```tsx
+ * {(trigger) => <Button {...trigger}>Edit</Button>}          // a Box component
+ * {(trigger) => <button ref={trigger.ref} {...trigger.props}>}  // a plain element
+ * ```
+ */
+export interface DialogTrigger {
+    ref: React.RefCallback<HTMLElement>;
+    props: DialogTriggerAttributes;
+}
+type DialogBoxProps<TKey extends keyof ComponentsAndVariants> = Omit<BoxProps<'dialog', TKey>, 'open'>;
+export interface DialogProps<TKey extends keyof ComponentsAndVariants = 'dialog'> extends DialogBoxProps<TKey> {
+    /** The control that opens it, handed the ref and props that wire it up. Leave it out to open the dialog from anywhere else. */
+    trigger?: (trigger: DialogTrigger) => React.ReactNode;
+    /** The dialog's content — a `Dialog.Title`, usually a `Dialog.Description`, and the controls. */
+    children?: React.ReactNode;
+    /** Controlled open state. Leave it out and the dialog owns it. */
+    open?: boolean;
+    /** Whether it starts open, when the dialog owns its own state. */
+    defaultOpen?: boolean;
+    /**
+     * Fires with the new state and why it changed — `'trigger'`, `'escape'`, `'outside-pointer'` or
+     * `'imperative'`. A close cannot be refused: the browser has already done it by the time this runs.
+     */
+    onOpenChange?: ChangeHandler<boolean, DialogReason>;
+    /** The dialog's accessible name, when no `Dialog.Title` supplies one. A dialog without a name is unusable. */
+    label?: string;
+    /** Names the dialog after an element already on the page, instead of `label` or a `Dialog.Title`. */
+    labelledBy?: string;
+    /** Describes it from an element already on the page, instead of a `Dialog.Description`. */
+    describedBy?: string;
+    /**
+     * Whether the rest of the page is blocked while it is open. Default `true`, which is `showModal()`: the
+     * top layer, a `::backdrop`, an inert page, Escape and focus containment, all the browser's.
+     */
+    modal?: boolean;
+    /** Whether a press outside closes it. Default `true` — `false` is what makes a decision unavoidable. */
+    dismissible?: boolean;
+    /**
+     * Whether the page behind it stops scrolling. Default: whatever `modal` is, because a modal dialog that
+     * scrolls the page behind it is the commonest complaint about every library that blocks it unasked.
+     */
+    lockScroll?: boolean;
+    /**
+     * Where focus lands on open, instead of the first focusable thing inside. An **alert dialog owes this to
+     * its least destructive action** — APG's rule, so that a keyboard user cannot confirm a deletion by
+     * reflex. An `autofocus` attribute inside does the same job with no ref.
+     */
+    initialFocus?: ElementLike;
+}
+/** Everything an alert dialog does not get to choose: it is modal, and a decision cannot be dismissed. */
+export type AlertDialogProps<TKey extends keyof ComponentsAndVariants = 'dialog'> = Omit<DialogProps<TKey>, 'modal' | 'dismissible' | 'lockScroll'>;
+/** Every Box prop, on an `<h2>` — `tag` takes any of the six headings instead. */
+export type DialogTitleProps<TKey extends keyof ComponentsAndVariants = 'dialog.title'> = BoxProps<'h2', TKey>;
+/** Every Box prop, on a `<p>`. */
+export type DialogDescriptionProps<TKey extends keyof ComponentsAndVariants = 'dialog.description'> = BoxProps<'p', TKey>;
+/**
+ * A modal dialog on the platform's own `<dialog>`: `showModal()` supplies the top layer, the
+ * `::backdrop`, an inert page behind it, Escape, focus containment and focus return — so none of that is
+ * written here.
+ *
+ * ```tsx
+ * <Dialog trigger={(t) => <Button {...t}>Rename</Button>}>
+ *   <Dialog.Title>Rename this view</Dialog.Title>
+ *   <Textbox label="Name" />
+ * </Dialog>
+ * ```
+ *
+ * **The dialog is always rendered**, and closed means `display: none` — the same shape as `<Popover>`, and
+ * what lets the browser own show and hide. The exit is therefore a plain CSS transition rather than a
+ * `<Presence>`, since nothing unmounts; content that is expensive to render should be gated by the
+ * consumer with `{open && <Heavy />}`.
+ *
+ * **A close cannot be refused.** The `cancel` event is cancelable, but by the time `onOpenChange` runs the
+ * browser has closed the dialog, so a controlled `<Dialog open>` hears about a dismissal afterwards and
+ * keeping `open` true re-shows it. Say `dismissible={false}` to make a decision unavoidable instead, which
+ * is what `<AlertDialog>` does.
+ *
+ * **Nothing is portalled**, so the theme, the custom properties, the text direction and the tab order
+ * around the declaration all reach inside — a top-layer element inherits normally (measured in Chrome
+ * 152, with a local `Box.Theme` wrapper around the dialog).
+ *
+ * A non-modal dialog (`modal={false}`) is `show()`: no top layer, no backdrop, nothing inert, and the UA
+ * positions it against its containing block rather than the viewport. It is the right shape for a
+ * persistent panel; for one anchored to a trigger, reach for `<Popover>`.
+ *
+ * @a11y `role="dialog"` (`alertdialog` on `<AlertDialog>`), named by a `Dialog.Title`, `label` or
+ * `labelledBy`, and described by a `Dialog.Description` or `describedBy`.
+ * @a11y The trigger carries `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`.
+ * @a11y Focus is contained while a modal dialog is open and returns to the trigger when it closes, both
+ * from the platform. `initialFocus` is what an alert dialog needs to land on its least destructive action.
+ * @keyboard Escape — Closes it, from anywhere inside, and returns focus to the trigger.
+ * @keyboard Tab — Cycles focus inside a modal dialog and never leaves it; in a non-modal one it moves on.
+ * @keyboard Enter, Space — On the trigger, opens the dialog.
+ */
+declare function DialogImpl<TKey extends keyof ComponentsAndVariants = 'dialog'>(props: DialogProps<TKey>): import("react").JSX.Element;
+/**
+ * A dialog that interrupts to ask something: `role="alertdialog"`, always modal, and **never dismissed by
+ * a press outside**, because a decision that can be clicked away is one the user did not make.
+ *
+ * ```tsx
+ * <AlertDialog trigger={(t) => <Button {...t}>Delete</Button>} initialFocus={cancelRef}>
+ *   <AlertDialog.Title>Delete this view?</AlertDialog.Title>
+ *   <AlertDialog.Description>Nothing here can be undone.</AlertDialog.Description>
+ *   <Button ref={cancelRef}>Cancel</Button>
+ * </AlertDialog>
+ * ```
+ *
+ * Escape still closes it — a keyboard user must always have a way out (APG), and the platform's own close
+ * request is that way. `initialFocus` is what puts focus on the least destructive action.
+ *
+ * @a11y `role="alertdialog"`, which tells a screen reader the content is an alert rather than a panel, so
+ * the name and description are announced together on open.
+ * @a11y A press outside is ignored on purpose; Escape is not, so the dialog is never a trap.
+ * @keyboard Escape — Closes it and returns focus to the trigger.
+ * @keyboard Tab — Cycles focus inside it and never leaves.
+ */
+declare function AlertDialogImpl<TKey extends keyof ComponentsAndVariants = 'dialog'>(props: AlertDialogProps<TKey>): import("react").JSX.Element;
+/**
+ * The dialog's heading, and what names it: rendering one is what puts `aria-labelledby` on the dialog, so
+ * a name and a visible title cannot drift apart. An `<h2>` by default — `tag` takes any of the six.
+ */
+declare function DialogTitle<TKey extends keyof ComponentsAndVariants = 'dialog.title'>(props: DialogTitleProps<TKey>): import("react").JSX.Element;
+/** The dialog's supporting text, and what describes it: rendering one puts `aria-describedby` on the dialog. */
+declare function DialogDescription<TKey extends keyof ComponentsAndVariants = 'dialog.description'>(props: DialogDescriptionProps<TKey>): import("react").JSX.Element;
+declare const Dialog: typeof DialogImpl & {
+    Title: typeof DialogTitle;
+    Description: typeof DialogDescription;
+};
+declare const AlertDialog: typeof AlertDialogImpl & {
+    Title: typeof DialogTitle;
+    Description: typeof DialogDescription;
+};
+export { AlertDialog };
+export default Dialog;

package/components/dialog.mjs

@@ -0,0 +1,223 @@
+"use client";
+import { c as e, i as t, l as n, n as r } from "../platform.mjs";
+import { i } from "../client.mjs";
+import { n as a } from "../effects.mjs";
+import o from "../box.mjs";
+import { a as s, i as c, n as l, r as u } from "../behavior.mjs";
+import { t as d } from "../identity.mjs";
+import { H2 as f, P as p } from "./semantics.mjs";
+import { createContext as m, useCallback as h, useContext as g, useMemo as _, useRef as v, useState as y } from "react";
+import { Fragment as b, jsx as x, jsxs as S } from "react/jsx-runtime";
+//#region src/react/dialog/useScrollLock.ts
+var C = 0;
+function w(e) {
+	let { classNames: t, styleElements: n } = i({ overflow: "hidden" }, !1), o = t.slice(1).join(" ");
+	return a(() => {
+		let t = r();
+		if (!(!e || !t || !o)) return C += 1, t.classList.add(o), () => {
+			--C, C === 0 && t.classList.remove(o);
+		};
+	}, [e, o]), n;
+}
+//#endregion
+//#region src/components/dialog.tsx
+var T = m(null);
+function E(e) {
+	let t = g(T);
+	if (!t) throw Error(`<${e}> must be rendered inside a <Dialog>.`);
+	return t;
+}
+function D(e) {
+	return /* @__PURE__ */ x(k, {
+		role: "dialog",
+		...e
+	});
+}
+function O(e) {
+	return /* @__PURE__ */ x(k, {
+		role: "alertdialog",
+		...e,
+		modal: !0,
+		dismissible: !1
+	});
+}
+function k(t) {
+	let { role: n, trigger: r, children: i, open: u, defaultOpen: f = !1, onOpenChange: p, label: m, labelledBy: g, describedBy: v, modal: C = !0, dismissible: E = !0, lockScroll: D = C, initialFocus: O, props: k, ...j } = t, M = d("dialog"), N = j.id ?? M, [P, F] = c({
+		value: u,
+		defaultValue: f,
+		onChange: p
+	}), [I, L] = y(null), [R, z] = y(null), [B, V] = y(!1), [H, U] = y({
+		title: 0,
+		description: 0
+	}), W = w(P && D);
+	l({
+		enabled: P,
+		returnTo: R
+	});
+	let G = h((e) => (U((t) => ({
+		...t,
+		[e]: t[e] + 1
+	})), () => U((t) => ({
+		...t,
+		[e]: t[e] - 1
+	}))), []), K = _(() => ({
+		titleId: `${N}-title`,
+		descriptionId: `${N}-description`,
+		register: G
+	}), [N, G]);
+	A({
+		dialog: I,
+		isOpen: P,
+		domOpen: B,
+		setDomOpen: V,
+		setOpen: F,
+		modal: C,
+		dismissible: E,
+		triggerElement: R
+	}), a(() => {
+		let t = e(O);
+		!P || !t || t.focus();
+	}, [P, O]);
+	let q = s((e) => {
+		F((e) => !e, {
+			reason: "trigger",
+			event: e
+		});
+	}), J = _(() => ({
+		ref: z,
+		props: {
+			"aria-expanded": P,
+			"aria-haspopup": "dialog",
+			"aria-controls": P ? N : void 0,
+			onClick: q
+		}
+	}), [
+		N,
+		q,
+		P
+	]), Y = j;
+	return /* @__PURE__ */ S(b, { children: [
+		W,
+		r?.(J),
+		/* @__PURE__ */ x(T.Provider, {
+			value: K,
+			children: /* @__PURE__ */ x(o, {
+				ref: L,
+				tag: "dialog",
+				component: "dialog",
+				...Y,
+				id: N,
+				props: {
+					role: n,
+					"aria-label": H.title || g ? void 0 : m,
+					"aria-labelledby": g ?? (H.title ? K.titleId : void 0),
+					"aria-describedby": v ?? (H.description ? K.descriptionId : void 0),
+					...k
+				},
+				children: i
+			})
+		})
+	] });
+}
+function A(e) {
+	let { dialog: r, isOpen: i, domOpen: o, setDomOpen: s, setOpen: c, modal: l, dismissible: d, triggerElement: f } = e, p = v("imperative"), m = t(), h = d ? "any" : "closerequest";
+	a(() => {
+		!r || i === o || (s(i), i ? l ? r.showModal() : r.show() : r.close());
+	}, [
+		r,
+		i,
+		o,
+		l,
+		s
+	]), a(() => {
+		if (!r) return;
+		let e = new AbortController();
+		return r.addEventListener("close", (e) => {
+			s(!1), c(!1, {
+				reason: p.current,
+				event: e
+			}), p.current = "imperative";
+		}, { signal: e.signal }), () => e.abort();
+	}, [
+		r,
+		s,
+		c
+	]), a(() => {
+		if (!(!r || !m)) return r.setAttribute("closedby", h), () => r.removeAttribute("closedby");
+	}, [
+		r,
+		m,
+		h
+	]), a(() => {
+		if (!i || !r) return;
+		let e = new AbortController(), t = (t, n) => document.addEventListener(t, n, {
+			signal: e.signal,
+			capture: !0
+		});
+		return t("keydown", (e) => {
+			e.key === "Escape" && (p.current = "escape");
+		}), t("pointerdown", (e) => {
+			n(e, [f]) ? p.current = "trigger" : !n(e, [r]) || j(r, e) ? p.current = "outside-pointer" : p.current = "imperative";
+		}), () => e.abort();
+	}, [
+		i,
+		r,
+		f
+	]), u({
+		enabled: i && !l && !m,
+		inside: [r],
+		escapeKey: !0,
+		outsidePointer: !1,
+		onDismiss: (e, t) => c(!1, {
+			reason: "escape",
+			event: t
+		})
+	}), a(() => {
+		if (!r || !i || !d || m) return;
+		let e = new AbortController();
+		return document.addEventListener("pointerdown", (e) => {
+			n(e, [f]) || n(e, [r]) && !j(r, e) || c(!1, {
+				reason: "outside-pointer",
+				event: e
+			});
+		}, {
+			signal: e.signal,
+			capture: !0
+		}), () => e.abort();
+	}, [
+		r,
+		i,
+		d,
+		m,
+		f,
+		c
+	]);
+}
+function j(e, t) {
+	let n = e.getBoundingClientRect();
+	return t.clientX < n.left || t.clientX > n.right || t.clientY < n.top || t.clientY > n.bottom;
+}
+function M(e) {
+	let t = E("Dialog.Title");
+	return a(() => t.register("title"), [t]), /* @__PURE__ */ x(f, {
+		id: t.titleId,
+		component: "dialog.title",
+		...e
+	});
+}
+function N(e) {
+	let t = E("Dialog.Description");
+	return a(() => t.register("description"), [t]), /* @__PURE__ */ x(p, {
+		id: t.descriptionId,
+		component: "dialog.description",
+		...e
+	});
+}
+M.displayName = "Dialog.Title", N.displayName = "Dialog.Description";
+var P = {
+	Title: M,
+	Description: N
+}, F = Object.assign(D, P), I = Object.assign(O, P);
+D.displayName = "Dialog", O.displayName = "AlertDialog";
+//#endregion
+export { I as AlertDialog, F as default };

package/components/dropdown/dropdownContext.d.ts

@@ -0,0 +1,44 @@
+import { BoxProps } from '../../box';
+import { ClassNameType } from '@box-kite/core';
+export interface DropdownItemProps<TVal = unknown> extends BoxProps {
+    value: TVal;
+    onClick?(e: React.MouseEvent): void;
+}
+/**
+ * A row of the open listbox, in the order the keyboard walks them. "Clear" and "Select all" are rows
+ * rather than decorations beside the list, so they carry `role="option"` too. One array up front is what
+ * makes an index mean the same thing to the roving-focus hook, to `aria-activedescendant` and to the markup.
+ */
+export type DropdownRow<TVal = unknown> = {
+    kind: 'unselect';
+    element: React.ReactElement<{
+        props?: object;
+    }>;
+} | {
+    kind: 'selectAll';
+    element: React.ReactElement<{
+        props?: object;
+    }>;
+} | {
+    kind: 'item';
+    element: React.ReactElement<DropdownItemProps<TVal>>;
+};
+export interface DropdownContextValue<TVal = unknown> {
+    valueToUse: TVal[];
+    multiple: boolean;
+    variant: ClassNameType;
+    showCheckbox: boolean;
+    /** Choose the row at `index` — the one path a click and an Enter both take. */
+    selectRow: (index: number, event: React.SyntheticEvent) => void;
+    /** The id `aria-activedescendant` names when the keyboard is on the row at `index`. */
+    optionId: (index: number) => string;
+    /** The row the keyboard is on, or `-1` when it is on none of them. */
+    activeIndex: number;
+    /** Collects a row's element, so the active one can be named and scrolled to. */
+    rowRef: (index: number) => (element: HTMLElement | null) => void;
+    /** Whether a row is a disabled option: skipped by the arrows, and inert to a click. */
+    isRowDisabled: (index: number) => boolean;
+}
+declare const DropdownContext: import('react').Context<DropdownContextValue<any> | null>;
+export declare function useDropdownContext<TVal>(): DropdownContextValue<TVal>;
+export default DropdownContext;

package/components/dropdown/dropdownItems.d.ts

@@ -0,0 +1,22 @@
+import { Ref } from 'react';
+import { BoxStyleProps } from '@box-kite/core/types';
+import { PresenceHandle } from '../presence';
+import { DropdownRow } from './dropdownContext';
+interface Props<TVal> {
+    /** 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: DropdownRow<TVal>[];
+    emptyItem?: React.ReactElement;
+    /** The shell the popup hangs off: a button in select-only mode, the field's wrapper otherwise. */
+    triggerRef: React.RefObject<HTMLElement | null>;
+    /** The layer element — what the dismissal hook treats as *inside* the popup. */
+    popupRef: Ref<HTMLDivElement>;
+    /** `aria-controls` on the trigger names this. */
+    listboxId: string;
+    /** What names the listbox: the dropdown's own label when it has one, else its trigger. */
+    labelledBy: string;
+    itemsProps?: BoxStyleProps;
+}
+export default function DropdownItems<TVal>(props: Props<TVal>): import("react").JSX.Element;
+export {};

package/components/dropdown/dropdownRowRenderer.d.ts

@@ -0,0 +1,8 @@
+import { DropdownRow } from './dropdownContext';
+interface Props<TVal> {
+    row: DropdownRow<TVal>;
+    /** Position in the listbox — what `aria-activedescendant`, the arrow keys and the ref share. */
+    index: number;
+}
+declare const DropdownRowRenderer: <TVal>(props: Props<TVal>) => React.ReactNode;
+export default DropdownRowRenderer;

package/components/dropdown/dropdownSearch.d.ts

@@ -0,0 +1,21 @@
+interface Props {
+    /** The combobox's own id. `aria-labelledby` on the listbox falls back to it. */
+    id: string;
+    /** What the field shows: the query while one is being typed, the value the rest of the time. */
+    value: string;
+    onValueChange: (value: string) => void;
+    /** Only while the listbox is open — a closed field shows the value, not an invitation to type. */
+    placeholder?: string;
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    /** Everything that makes this input the combobox: the ARIA, the keys, the consumer's own props. */
+    comboboxProps: Record<string, unknown>;
+    /** A press on the field opens the listbox. It never closes it — the caret has to be placeable. */
+    onOpen: (event: React.MouseEvent) => void;
+}
+/**
+ * The textbox half of the APG editable combobox, and it *is* the combobox: the role, the ARIA and the
+ * consumer's props live on this input rather than on a wrapper, which is what stops one focusable element
+ * containing another (bug #47). Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ */
+export default function DropdownSearch({ id, value, onValueChange, placeholder, inputRef, comboboxProps, onOpen }: Props): import("react").JSX.Element;
+export {};

package/components/dropdown/utils.d.ts

@@ -0,0 +1 @@
+export declare function searchItemText(item: React.ReactElement): string;

package/components/dropdown.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("./baseSvg.cjs"),a=require("./button.cjs"),o=require("./flex.cjs"),s=require("./checkbox.cjs"),c=require("./overlay.cjs"),l=require("./presence.cjs"),u=require("./textbox.cjs");let d=require("react"),f=require("react/jsx-runtime");var p=(0,d.createContext)(null);function m(){let e=(0,d.useContext)(p);if(!e)throw Error(`Dropdown sub-components must be used within Dropdown`);return e}var h={item:`dropdown.item`,unselect:`dropdown.unselect`,selectAll:`dropdown.selectAll`};function g({row:e,index:n}){let{valueToUse:r,multiple:i,variant:a,showCheckbox:o,selectRow:c,optionId:l,activeIndex:u,rowRef:d,isRowDisabled:p}=m(),g=e.kind===`item`,_=p(n),v=g?r.includes(e.element.props.value):e.kind===`unselect`&&r.length===0,{value:ee,onClick:y,children:b,...x}=e.element.props,S=o&&i&&g;return(0,f.jsx)(t.default,{ref:d(n),component:h[e.kind],variant:[a,g?{multiple:i,highlighted:n===u}:{highlighted:n===u}],selected:v,...x,id:l(n),children:S?(0,f.jsxs)(f.Fragment,{children:[(0,f.jsx)(s.default,{readOnly:!0,checked:v,me:2,props:{tabIndex:-1,"aria-hidden":!0}}),b]}):b,props:{role:`option`,..._?{"aria-disabled":!0}:{},...x.props,onClick:_?void 0:e=>{y?.(e),c(n,e)}}})}var _=(0,d.memo)(g,(e,t)=>e.row.element===t.row.element&&e.index===t.index);function v(e,t,n){return e?{role:`listbox`,"aria-labelledby":n,...t?{"aria-multiselectable":!0}:{}}:{role:`status`}}function ee(e){let{presence:n,rows:r,emptyItem:i,triggerRef:a,popupRef:o,listboxId:s,labelledBy:l,itemsProps:u}=e,{present:p,ref:h,props:g}=n,{multiple:ee,variant:b}=m(),[x,S]=(0,d.useState)(!1),te=(0,d.useCallback)(e=>S(e===`top`),[]);return(0,f.jsx)(c.default,{ref:o,anchor:a,side:`bottom`,align:`start`,offset:.5,onSideChange:te,children:(0,f.jsxs)(t.default,{ref:h,component:`dropdown.items`,...u,variant:[b,{closed:!p&&!x,closedUp:!p&&x}],id:s,props:{...v(r.length>0,ee,l),...g},children:[r.map((e,t)=>(0,f.jsx)(_,{row:e,index:t},y(e,t))),r.length===0&&i&&(0,f.jsx)(t.default,{component:`dropdown.emptyItem`,variant:b,...i.props})]})})}function y(e,t){return e.kind===`item`?e.element.props.value:`${e.kind}-${t}`}ee.displayName=`DropdownItems`;function b({id:e,value:t,onValueChange:n,placeholder:r,inputRef:i,comboboxProps:a,onOpen:s}){let c=(0,d.useCallback)(e=>n(e.target.value),[n]),l=(0,d.useCallback)(e=>{e.stopPropagation(),s(e)},[s]);return(0,f.jsx)(o.default,{ai:`center`,position:`absolute`,inset:0,p:3,children:(0,f.jsx)(u.default,{clean:!0,id:e,value:t,placeholder:r,onChange:c,ref:i,color:`currentColor`,width:`fit`,props:{role:`combobox`,"aria-autocomplete":`list`,autoComplete:`off`,spellCheck:!1,...a,onClick:l}})})}function x(e){if(e==null)return``;if(typeof e==`object`){let t=e.props?.children;return t==null?``:typeof t==`object`?(Array.isArray(t)?t:[t]).map(e=>x(e)).join(``):t.toString()}return e.toString()}function S(e){return e==null?[]:Array.isArray(e)?e:[e]}function te(e){let t=e?.props?.disabled;return(Array.isArray(t)?t[0]:t)===!0}function ne(e){return e.key.length===1&&!e.ctrlKey&&!e.metaKey&&!e.altKey}var re=new Set([` `,`Home`,`End`,`ArrowLeft`,`ArrowRight`]);function ie(s,c){let{name:m,defaultValue:h,value:g,defaultOpen:_,multiple:v=!1,isSearchable:y,searchPlaceholder:ie,children:C,hideIcon:w,showCheckbox:ae=!1,label:oe,labelProps:se,itemsProps:ce,iconProps:le,onValueChange:ue,onChange:de,props:fe,...T}=s,E=(0,d.useRef)(void 0),pe=n.a((e,t)=>{ue?.(v?e:e[0],t),de?.(E.current,e)}),me=`value`in s,he=(0,d.useMemo)(()=>me?S(g):void 0,[me,g]),[D,O]=n.i({value:he,defaultValue:()=>S(h),onChange:pe}),[ge,_e]=(0,d.useState)(null),[k,A]=(0,d.useState)(!!_),j=(0,d.useRef)(null),ve=(0,d.useCallback)(e=>{j.current=e},[]),ye=(0,d.useRef)(null),M=(0,d.useRef)(null),N=r.t(`dropdown`),P=T.id??`${N}-trigger`,be=`${N}-listbox`,F=`${N}-label`,I=oe!=null&&oe!==!1,xe=(0,d.useCallback)(e=>`${N}-option-${e}`,[N]),L=n.a((e=!1)=>{A(!1),e||_e(null)}),R=(0,d.useMemo)(()=>(Array.isArray(C)?C:[C]).flatMap(e=>e).filter(Boolean),[C]),z=(0,d.useMemo)(()=>R.filter(e=>e.type?.displayName===`DropdownItem`),[R]),Se=(0,d.useMemo)(()=>{let e=new Map;for(let t of z)e.set(t,x(t));return e},[z]),B=(0,d.useCallback)(e=>Se.get(e)??x(e),[Se]),Ce=y?ge??``:``,V=(0,d.useMemo)(()=>Ce?z.filter(e=>B(e).toLowerCase().includes(Ce.toLowerCase())):z,[Ce,z,B]),H=(0,d.useMemo)(()=>R.find(e=>e.type?.displayName===`DropdownUnselect`),[R]),U=(0,d.useMemo)(()=>R.find(e=>e.type?.displayName===`DropdownSelectAll`),[R]),we=(0,d.useMemo)(()=>R.find(e=>e.type?.displayName===`DropdownEmptyItem`),[R]),W=(0,d.useMemo)(()=>R.find(e=>e.type?.displayName===`DropdownDisplay`),[R]),G=(0,d.useMemo)(()=>!y||W?``:z.filter(e=>D.includes(e.props.value)).map(e=>B(e)).join(`, `),[y,W,z,D,B]),Te=!!(U&&v&&V.length>D.length),Ee=!!(H&&V.length>0&&!Te),K=(0,d.useMemo)(()=>{let e=[];Ee&&H&&e.push({kind:`unselect`,element:H}),Te&&U&&e.push({kind:`selectAll`,element:U});for(let t of V)e.push({kind:`item`,element:t});return e},[Ee,H,Te,U,V]),q=(0,d.useCallback)(e=>te(K[e]?.element),[K]),De=(0,d.useCallback)(e=>{let t=K[e];return t?B(t.element):``},[K,B]),Oe=(0,d.useMemo)(()=>{if(y&&(k||G!==``))return null;if(W)return typeof W.props.children==`function`?W.props.children(D,k):W.props.children;let e=V.filter(e=>D.includes(e.props.value));if(v&&e.length>1)return e.map(e=>B(e)).join(`, `);let t=e.at(0);return t?.props.children??t?.props.value??(v?null:H?.props.children)},[v,V,D,H,k,y,G,W,B]),ke=(0,d.useCallback)((e,...t)=>{if(t.length===0)E.current=void 0,O([],{reason:`clear`,event:e});else if(v&&t.length>1)E.current=void 0,O(t.map(e=>e.props.value),{reason:`select-all`,event:e});else if(t.length===1){let n=t[0];if(E.current=n.props.value,v){let t=D.filter(e=>e!==n.props.value),r=t.length!==D.length;r||t.push(n.props.value),O(t,{reason:r?`deselect`:`select`,event:e})}else O([n.props.value],{reason:`select`,event:e})}e.stopPropagation(),v?y&&setTimeout(()=>M.current?.focus(),0):L()},[v,y,D,O,L]),J=n.a((e,t)=>{let n=K[e];!n||q(e)||(n.kind===`unselect`?ke(t):n.kind===`selectAll`?ke(t,...z):ke(t,n.element))}),Ae=e=>{let t=e===`first`?1:-1;for(let n=e===`first`?0:K.length-1;n>=0&&n<K.length;n+=t)if(!q(n))return n;return-1},Y=e=>{let t=K.findIndex(e=>e.kind===`item`&&D.includes(e.element.props.value));return t!==-1&&!q(t)?t:e===`none`?-1:Ae(e)},X=n.t({count:K.length,focusItems:!1,defaultActiveIndex:_?Y(`none`):-1,isDisabled:q,textOf:y?void 0:De,onSelect:J}),je=X.setActiveIndex,Me=(0,d.useCallback)(e=>je(-1,{reason:`programmatic`,event:e}),[je]);n.r({enabled:k,inside:[j,ye],onDismiss:e=>L(e===`escape`)}),n.n({enabled:k,returnTo:y?M:j}),(0,d.useEffect)(()=>{k&&M.current?.focus()},[k]);let Z=X.activeIndex,Ne=X.activeItem;e.n(()=>{!k||Z===-1||Ne()?.scrollIntoView?.({block:`nearest`})},[k,Z,Ne]);let Q=(e,t)=>{A(!0),X.setActiveIndex(e,{reason:`programmatic`,event:t})},Pe=n.a(e=>{k?L():Q(Y(`none`),e)}),Fe=n.a(e=>{k||Q(Y(`none`),e)}),Ie=n.a(e=>{_e(e),k||A(!0),Me()}),Le=e=>{let{key:t}=e;if(y){if(t===`ArrowDown`||t===`ArrowUp`){e.preventDefault(),Q(Y(t===`ArrowUp`?`last`:e.altKey?`none`:`first`),e);return}t===`Escape`&&_e(``);return}if(t===`ArrowDown`||t===`Enter`||t===` `){e.preventDefault(),Q(Y(e.altKey?`none`:`first`),e);return}if(t===`ArrowUp`){e.preventDefault(),Q(Y(`last`),e);return}if(t===`Home`||t===`End`){e.preventDefault(),Q(Ae(t===`Home`?`first`:`last`),e);return}ne(e)&&(A(!0),X.onKeyDown(e))},Re=n.a(e=>{if(fe?.onKeyDown?.(e),!e.defaultPrevented){if(!k){Le(e);return}if(e.key===`Tab`){!v&&X.activeIndex!==-1&&J(X.activeIndex,e),L();return}if(e.altKey&&e.key===`ArrowUp`){e.preventDefault(),X.activeIndex!==-1&&J(X.activeIndex,e),L();return}if(y&&re.has(e.key)){Me(e);return}X.onKeyDown(e)}}),$=K.length>0||!!we,ze=k&&Z!==-1&&$?xe(Z):void 0,Be=X.itemProps,Ve=(0,d.useMemo)(()=>({valueToUse:D,multiple:v,variant:T.variant,showCheckbox:ae,selectRow:J,optionId:xe,activeIndex:Z,rowRef:e=>Be(e).ref,isRowDisabled:q}),[D,v,T.variant,ae,J,xe,Z,Be,q]),He={"aria-expanded":k,"aria-controls":k&&$?be:void 0,"aria-activedescendant":ze,"aria-labelledby":I?F:void 0,...fe,onKeyDown:Re},Ue=D.map(e=>{let t=JSON.stringify(e);return(0,f.jsx)(u.default,{ref:c,name:m,type:`hidden`,value:t??``},t)}),We=!w&&(0,f.jsx)(o.default,{component:`dropdown.icon`,...le,children:(0,f.jsx)(i.default,{viewBox:`0 0 10 6`,width:`0.6rem`,rotate:k?180:0,children:(0,f.jsx)(`path`,{stroke:`currentColor`,strokeLinecap:`round`,strokeLinejoin:`round`,strokeWidth:`2`,d:`m1 1 4 4 4-4`})})}),Ge=$&&(0,f.jsx)(l.default,{present:k,children:e=>(0,f.jsx)(ee,{presence:e,rows:K,emptyItem:we,triggerRef:j,popupRef:ye,listboxId:be,labelledBy:I?F:P,itemsProps:ce})}),Ke=y?(0,f.jsxs)(t.default,{ref:ve,component:`dropdown`,props:{onClick:Pe},position:`relative`,pe:w?void 0:6,minWidth:k?36:void 0,width:`fit-content`,...T,id:void 0,children:[Ue,(0,f.jsx)(b,{id:P,value:ge??G,onValueChange:Ie,placeholder:k?ie:void 0,inputRef:M,comboboxProps:He,onOpen:Fe}),Oe??(0,f.jsx)(t.default,{tag:`span`,visibility:`hidden`,children:G||`\xA0`}),We]}):(0,f.jsxs)(a.default,{ref:ve,onClick:Pe,component:`dropdown`,type:`button`,props:{tabIndex:0,role:`combobox`,...He},position:`relative`,pe:w?void 0:6,width:`fit-content`,...T,id:P,children:[Ue,Oe??`\xA0`,We]});return(0,f.jsx)(p.Provider,{value:Ve,children:I?(0,f.jsxs)(o.default,{d:`column`,gap:1,width:`fit-content`,...se,children:[(0,f.jsx)(t.default,{tag:`span`,id:F,children:oe}),Ke,Ge]}):(0,f.jsxs)(f.Fragment,{children:[Ke,Ge]})})}function C(e){let t=e=>null;return t.displayName=e,t}var w=(0,d.forwardRef)(ie);w.Item=C(`DropdownItem`),w.Unselect=C(`DropdownUnselect`),w.SelectAll=C(`DropdownSelectAll`),w.EmptyItem=C(`DropdownEmptyItem`),w.Display=C(`DropdownDisplay`),w.displayName=`Dropdown`,exports.default=w;

package/components/dropdown.d.ts

@@ -0,0 +1,77 @@
+import { RefAttributes } from 'react';
+import { BoxProps } from '../box';
+import { ChangeHandler } from '../react/a11y/useControllableState';
+import { BoxStyleProps, ComponentsAndVariants } from '@box-kite/core/types';
+import { DropdownItemProps } from './dropdown/dropdownContext';
+/**
+ * Why the selection changed. `select-all` and `clear` are the two rows that act on the whole list —
+ * `Dropdown.SelectAll` and `Dropdown.Unselect` — rather than on the option under the pointer.
+ */
+export type DropdownValueReason = 'select' | 'deselect' | 'select-all' | 'clear';
+interface Props<TVal, TKey extends keyof ComponentsAndVariants = 'dropdown'> extends Omit<BoxProps<'button', TKey>, 'ref' | 'tag'> {
+    /** What the selection submits under: the component renders a hidden input carrying it. */
+    name?: string;
+    /** What is selected to begin with, when the dropdown owns its own value. An array in `multiple` mode. */
+    defaultValue?: TVal | TVal[];
+    /** Controlled selection. Pair it with `onValueChange`, or nothing the user picks sticks. */
+    value?: TVal | TVal[];
+    /**
+     * Open the listbox as soon as the dropdown mounts, highlighting the selected option the way a press on
+     * the trigger would. For a dropdown that only exists because the user asked to choose — a grid's cell
+     * editor — where a second press to open a list that is the whole control is a gesture nobody meant.
+     */
+    defaultOpen?: boolean;
+    /** Let more than one option be chosen. Enter and Space then toggle without closing the listbox. */
+    multiple?: boolean;
+    /**
+     * Turn the control into the APG *editable* combobox: a text field that filters the listbox, and a
+     * different pattern rather than a decoration — the field carries the role, the ARIA and your `props`.
+     * Printable keys type instead of jumping, Home/End and left/right move the caret, and Escape closes
+     * the listbox before it clears the field.
+     */
+    isSearchable?: boolean;
+    /** The placeholder for the `isSearchable` field. Not a name — see `label`. */
+    searchPlaceholder?: string;
+    /** Drop the chevron. It is decoration either way: it is `aria-hidden` and never focusable. */
+    hideIcon?: boolean;
+    /** Show checkbox for each item in multiple selection mode */
+    showCheckbox?: boolean;
+    /**
+     * The dropdown's name, rendered above it and pointed at by `aria-labelledby`. A combobox is not named by
+     * what it contains — accname does not read a combobox at all, and the trigger text is its *value* — so
+     * without this (or your own `aria-label`) it has no accessible name.
+     */
+    label?: React.ReactNode;
+    /** Styles for the wrapper the label and the trigger share. Only rendered when there is a label. */
+    labelProps?: BoxProps<'div'>;
+    /** BoxProps applied to the opened items container (dropdown.items) */
+    itemsProps?: BoxStyleProps;
+    /** BoxProps applied to the chevron icon container (dropdown.icon) */
+    iconProps?: BoxStyleProps;
+    /**
+     * Fires with the selection in whatever shape `value` takes — the whole array in `multiple` mode, the
+     * one chosen option otherwise, `undefined` for nothing — and why it changed.
+     */
+    onValueChange?: ChangeHandler<TVal | TVal[] | undefined, DropdownValueReason>;
+    /**
+     * The older callback, whose first argument is the option *acted on* rather than the selection. Both
+     * fire, so either one can be passed.
+     * @deprecated `onValueChange` is what every component reports a value change under, and it carries the
+     * reason — which is the thing a `(value, values)` pair cannot say. This spelling still works.
+     */
+    onChange?: (value: TVal | undefined, values: TVal[]) => void;
+}
+interface DropdownDisplayProps<TVal> extends Omit<BoxProps, 'children'> {
+    /** What the trigger shows: a node, or a function given the selected values and whether it is open. */
+    children: ((selectedValues: TVal[], isOpen: boolean) => React.ReactNode) | React.ReactNode;
+}
+interface DropdownType {
+    <TVal>(props: Props<TVal> & RefAttributes<HTMLInputElement>): React.ReactNode;
+    Item: <TVal>(props: DropdownItemProps<TVal>) => React.ReactNode;
+    Unselect: (props: BoxProps) => React.ReactNode;
+    SelectAll: (props: BoxProps) => React.ReactNode;
+    EmptyItem: (props: BoxProps) => React.ReactNode;
+    Display: <TVal>(props: DropdownDisplayProps<TVal>) => React.ReactNode;
+}
+declare const Dropdown: DropdownType;
+export default Dropdown;