@nanisoft/prism-ui 0.13.0 → 0.15.0

package/dist/components/ui/creatable-combobox.d.ts

@@ -0,0 +1,153 @@
+import type { ComboboxItem } from './combobox.js';
+/** The props the Creatable combobox accepts. */
+export interface CreatableComboboxProps {
+    /**
+     * The accessible name of the search field.
+     *
+     * Required, and it names the search field rather than the whole control, because
+     * this control has two fields inside one popover and the reader has to be told
+     * which one they are in.
+     */
+    label: string;
+    /** The options the reader may choose from. */
+    items: readonly ComboboxItem[];
+    /** The chosen value, when the field is controlled. */
+    value?: string | null;
+    /** The value chosen initially, for an uncontrolled field. */
+    defaultValue?: string | null;
+    /** Called with the chosen option's value, or `null` when the reader clears it. */
+    onValueChange?: (value: string | null) => void;
+    /**
+     * Called with the trimmed draft when the reader commits a value that is not in
+     * the list.
+     *
+     * Required, because a creatable combobox whose create path does nothing is a
+     * combobox with an extra field in it. It is the only call a created value makes:
+     * `onValueChange` is not fired for it, because whether a newly typed string
+     * becomes the selection is the caller's decision and not this Component's. A
+     * caller who wants it selected sets `value` from here, and a caller whose records
+     * reject the duplicate has already been told about it by their own `validate`.
+     */
+    onCreate: (draft: string) => void;
+    /**
+     * The accessible name of the control that commits the draft.
+     *
+     * A string and not a function of the draft, because the draft is data and a
+     * control's name is a sentence the caller writes. The draft is attached to the
+     * control as its description rather than interpolated into its name, so a
+     * caller who localises the sentence gets a localised name and a value they did
+     * not have to translate.
+     */
+    createLabel: string;
+    /**
+     * The accessible name of the create field, the second editable control in the
+     * popover.
+     *
+     * Separate from `createLabel` because the field and the control that reads it are
+     * two controls with two jobs, and one name over both is a reader who is told they
+     * are somewhere they are not.
+     */
+    draftLabel: string;
+    /**
+     * Judges the draft, returning the message to show or `null` when it is fine.
+     *
+     * Optional, and the Component ships no rule of its own: what may be created is the
+     * caller's fact about their own data, so Prism holds no length limit, no pattern
+     * and no uniqueness check. It must be pure, because it is read on every render of
+     * the draft rather than on a keystroke, so the Component never has to guess when
+     * the answer changed.
+     */
+    validate?: (draft: string) => string | null;
+    /** What a reader is told when the query matches nothing. */
+    empty: {
+        message: (query: string) => string;
+        hint?: string;
+    };
+    /** The placeholder in the search field. The caller's word. */
+    placeholder?: string;
+    /** Whether the list is open, when the field is controlled. */
+    open?: boolean;
+    /** Whether the list starts open, for an uncontrolled field. */
+    defaultOpen?: boolean;
+    /** Called when the list opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /** Whether the field ignores interaction. */
+    disabled?: boolean;
+    /** Whether a value must be chosen or created before the form submits. */
+    required?: boolean;
+    /** The form field name. The chosen or created value is submitted under it. */
+    name?: string;
+    /** Identifies the form that owns the hidden input. */
+    form?: string;
+    /** The field's own id, so a label elsewhere can point at it. */
+    id?: string;
+    /** Identifies the element that describes the field. */
+    'aria-describedby'?: string;
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * A text field that filters a list of options and lets the reader commit a value
+ * that is not in it, from inside the same popover.
+ *
+ * **The second editable control is the reason this is not `Combobox` with a prop.**
+ * Creating a value needs somewhere to type it, and the honest place for that
+ * somewhere is inside the surface the reader is already looking at. Everything
+ * downstream of that decision is different from a single-select combobox and none of
+ * it is reachable from a boolean:
+ *
+ *  - **The focus order gains a stop inside the popover.** Tab out of the search
+ *    field enters the create field and the list stays open, because closing on Tab
+ *    and reopening is the two-acts-for-one-keystroke cost the sibling is built to
+ *    avoid. Arrow Up from the create field goes back into the list with the
+ *    highlight on the first option, so the path is reversible. Escape in the create
+ *    field returns to the search field with the list still open; only Escape in the
+ *    search field closes.
+ *  - **The create row is not an option, and is kept out of the listbox element.**
+ *    `aria-activedescendant` names an element inside the element `aria-controls`
+ *    points at, and a screen reader announces the node it lands on as a choice from
+ *    that list. A create row carried inside the listbox would therefore be announced
+ *    as an option, and it would be counted by the index that names options, so
+ *    pressing Enter could commit a row the reader never highlighted. Here the row
+ *    is a sibling of the listbox, the highlight index runs over matched options
+ *    only, and `aria-activedescendant` is never written with the create row's id.
+ *  - **The validation is the create field's own, and it is the caller's rule.** The
+ *    message renders as a `FieldError`, so it carries `role="alert"` and is announced
+ *    as it appears, and while a message is showing the create control is not drawn
+ *    at all. A control that commits an invalid draft and then complains is a control
+ *    a reader learns to press anyway.
+ *
+ * **Typing never discards a choice, and this is the same commitment `Combobox`
+ * makes.** The value changes when the reader chooses an option or empties the
+ * field, both of which are acts, and a keystroke into the create field is a draft
+ * rather than an answer. Closing the list restores the chosen label into the search
+ * field, so a reader who typed a near miss and changed their mind gets their answer
+ * back rather than a stray string.
+ *
+ * **The draft is seeded from the query and then runs on its own.** Focusing the
+ * create field copies the query into it, because the reader's typed words are what
+ * they want to create. After that the two are deliberately not wired together: the
+ * list filters on the query and the create control commits the draft, and editing
+ * the draft does not narrow the list. Wiring them would mean a half-typed new value
+ * filtering the list to nothing on every keystroke, which reads as a broken search
+ * rather than as a new entry being written.
+ *
+ * **The row disappears when the draft is already an option.** A create row offering
+ * to create something that is already in the list is an offer to make a duplicate,
+ * so the row is drawn for a draft that is non-empty, has no complaint from
+ * `validate`, and matches no option's label or value exactly. A caller who wants the
+ * duplicate behaviour anyway is answering a question about their own data, and
+ * `onCreate` is where they answer it.
+ *
+ * **The list is ranked by the scorer imported from `lib/rank`**, so a query that
+ * floats one option to the top floats it in the command palette and in
+ * `MultiCombobox` too. A second scorer would be a second answer to the same
+ * question and the two surfaces would disagree within a release.
+ *
+ * The list is anchored to the field rather than portalled, for the trade
+ * `Combobox` states: put the field near the top of any scroll container it lives
+ * in.
+ */
+declare function CreatableCombobox({ label, items, value, defaultValue, onValueChange, onCreate, createLabel, draftLabel, validate, empty, placeholder, open, defaultOpen, onOpenChange, disabled, required, name, form, id, 'aria-describedby': describedBy, className, }: CreatableComboboxProps): import("react").JSX.Element;
+export { CreatableCombobox };
+//# sourceMappingURL=creatable-combobox.d.ts.map

package/dist/components/ui/creatable-combobox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creatable-combobox.d.ts","sourceRoot":"","sources":["../../../src/components/ui/creatable-combobox.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAM9C,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,kFAAkF;IAClF,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC9C;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;;;OAOG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAA;IAC3C,4DAA4D;IAC5D,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5D,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,+DAA+D;IAC/D,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,4CAA4C;IAC5C,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gEAAgE;IAChE,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,uDAAuD;IACvD,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,iBAAS,iBAAiB,CAAC,EACzB,KAAK,EACL,KAAK,EACL,KAAK,EACL,YAAmB,EACnB,aAAa,EACb,QAAQ,EACR,WAAW,EACX,UAAU,EACV,QAAQ,EACR,KAAK,EACL,WAAW,EACX,IAAI,EACJ,WAAmB,EACnB,YAAY,EACZ,QAAgB,EAChB,QAAgB,EAChB,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,kBAAkB,EAAE,WAAW,EAC/B,SAAS,GACV,EAAE,sBAAsB,+BAqZxB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/components/ui/creatable-combobox.js

@@ -0,0 +1,285 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { FieldError } from './field.js';
+import { Input } from './input.js';
+import { RANKS, locate } from '../../lib/rank.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A text field that filters a list of options and lets the reader commit a value
+ * that is not in it, from inside the same popover.
+ *
+ * **The second editable control is the reason this is not `Combobox` with a prop.**
+ * Creating a value needs somewhere to type it, and the honest place for that
+ * somewhere is inside the surface the reader is already looking at. Everything
+ * downstream of that decision is different from a single-select combobox and none of
+ * it is reachable from a boolean:
+ *
+ *  - **The focus order gains a stop inside the popover.** Tab out of the search
+ *    field enters the create field and the list stays open, because closing on Tab
+ *    and reopening is the two-acts-for-one-keystroke cost the sibling is built to
+ *    avoid. Arrow Up from the create field goes back into the list with the
+ *    highlight on the first option, so the path is reversible. Escape in the create
+ *    field returns to the search field with the list still open; only Escape in the
+ *    search field closes.
+ *  - **The create row is not an option, and is kept out of the listbox element.**
+ *    `aria-activedescendant` names an element inside the element `aria-controls`
+ *    points at, and a screen reader announces the node it lands on as a choice from
+ *    that list. A create row carried inside the listbox would therefore be announced
+ *    as an option, and it would be counted by the index that names options, so
+ *    pressing Enter could commit a row the reader never highlighted. Here the row
+ *    is a sibling of the listbox, the highlight index runs over matched options
+ *    only, and `aria-activedescendant` is never written with the create row's id.
+ *  - **The validation is the create field's own, and it is the caller's rule.** The
+ *    message renders as a `FieldError`, so it carries `role="alert"` and is announced
+ *    as it appears, and while a message is showing the create control is not drawn
+ *    at all. A control that commits an invalid draft and then complains is a control
+ *    a reader learns to press anyway.
+ *
+ * **Typing never discards a choice, and this is the same commitment `Combobox`
+ * makes.** The value changes when the reader chooses an option or empties the
+ * field, both of which are acts, and a keystroke into the create field is a draft
+ * rather than an answer. Closing the list restores the chosen label into the search
+ * field, so a reader who typed a near miss and changed their mind gets their answer
+ * back rather than a stray string.
+ *
+ * **The draft is seeded from the query and then runs on its own.** Focusing the
+ * create field copies the query into it, because the reader's typed words are what
+ * they want to create. After that the two are deliberately not wired together: the
+ * list filters on the query and the create control commits the draft, and editing
+ * the draft does not narrow the list. Wiring them would mean a half-typed new value
+ * filtering the list to nothing on every keystroke, which reads as a broken search
+ * rather than as a new entry being written.
+ *
+ * **The row disappears when the draft is already an option.** A create row offering
+ * to create something that is already in the list is an offer to make a duplicate,
+ * so the row is drawn for a draft that is non-empty, has no complaint from
+ * `validate`, and matches no option's label or value exactly. A caller who wants the
+ * duplicate behaviour anyway is answering a question about their own data, and
+ * `onCreate` is where they answer it.
+ *
+ * **The list is ranked by the scorer imported from `lib/rank`**, so a query that
+ * floats one option to the top floats it in the command palette and in
+ * `MultiCombobox` too. A second scorer would be a second answer to the same
+ * question and the two surfaces would disagree within a release.
+ *
+ * The list is anchored to the field rather than portalled, for the trade
+ * `Combobox` states: put the field near the top of any scroll container it lives
+ * in.
+ */
+function CreatableCombobox({ label, items, value, defaultValue = null, onValueChange, onCreate, createLabel, draftLabel, validate, empty, placeholder, open, defaultOpen = false, onOpenChange, disabled = false, required = false, name, form, id, 'aria-describedby': describedBy, className, }) {
+    const [ownValue, setOwnValue] = useState(defaultValue);
+    const [ownOpen, setOwnOpen] = useState(defaultOpen);
+    const [query, setQuery] = useState('');
+    const [draft, setDraft] = useState('');
+    const [active, setActive] = useState(0);
+    const listRef = useRef(null);
+    const draftRef = useRef(null);
+    const searchRef = useRef(null);
+    const generated = useId();
+    const inputId = id ?? generated;
+    const listId = `${generated}-list`;
+    // The popup the field controls. Separate from the listbox id because the listbox is
+    // not rendered at all when nothing matched, and `aria-controls` is a required
+    // attribute on an expanded combobox.
+    const popupId = `${generated}-popup`;
+    const draftId = `${generated}-draft`;
+    const draftErrorId = `${generated}-draft-error`;
+    const chosen = value === undefined ? ownValue : value;
+    const isOpen = (open ?? ownOpen) && !disabled;
+    const setOpen = useCallback((next) => {
+        if (open === undefined)
+            setOwnOpen(next);
+        onOpenChange?.(next);
+    }, [onOpenChange, open]);
+    const choose = useCallback((next) => {
+        if (value === undefined)
+            setOwnValue(next);
+        onValueChange?.(next);
+    }, [onValueChange, value]);
+    /**
+     * The field text follows the chosen value, and only the chosen value, so this
+     * effect does not run while a reader is typing. That is what lets the field hold
+     * a query that is not yet an answer.
+     */
+    const chosenLabel = useMemo(() => items.find((item) => item.value === chosen)?.label ?? '', [items, chosen]);
+    useEffect(() => {
+        setQuery(chosenLabel);
+    }, [chosenLabel]);
+    // A field showing exactly what is chosen is not narrowing anything, so the
+    // narrowing is read off the difference between the two rather than off a flag.
+    const narrowing = query !== chosenLabel;
+    const trimmed = narrowing ? query.trim() : '';
+    const ranked = useMemo(() => {
+        if (trimmed === '')
+            return items.map((item) => ({ item, rank: RANKS.prefix }));
+        return items
+            .map((item) => {
+            const inLabel = locate(item.label, trimmed);
+            if (inLabel.rank < RANKS.keyword)
+                return { item, rank: inLabel.rank, range: inLabel.range };
+            const keywordHit = (item.keywords ?? []).some((word) => word.toLowerCase().includes(trimmed.toLowerCase()));
+            return keywordHit ? { item, rank: RANKS.keyword } : null;
+        })
+            .filter((hit) => hit !== null)
+            .sort((a, b) => a.rank - b.rank);
+    }, [items, trimmed]);
+    const activeIndex = Math.min(active, Math.max(ranked.length - 1, 0));
+    const step = (from, delta) => {
+        if (ranked.length === 0)
+            return 0;
+        let next = from;
+        for (let moved = 0; moved < ranked.length; moved += 1) {
+            next += delta;
+            if (next >= ranked.length)
+                next = 0;
+            if (next < 0)
+                next = ranked.length - 1;
+            if (!ranked[next]?.item.disabled)
+                return next;
+        }
+        return from;
+    };
+    const draftValue = draft.trim();
+    // Read on every render rather than on a keystroke, so the answer cannot go stale
+    // against a draft the reader has already moved on from.
+    const draftError = draftValue === '' ? null : (validate?.(draftValue) ?? null);
+    const alreadyListed = items.some((item) => item.label.toLowerCase() === draftValue.toLowerCase() ||
+        item.value.toLowerCase() === draftValue.toLowerCase());
+    const canCreate = draftValue !== '' && draftError === null && !alreadyListed;
+    /** Commits an option and closes, which is the sibling's contract unchanged. */
+    const run = (item) => {
+        if (item.disabled)
+            return;
+        choose(item.value);
+        setDraft('');
+        setOpen(false);
+    };
+    const create = () => {
+        if (!canCreate)
+            return;
+        onCreate(draftValue);
+        setDraft('');
+        setOpen(false);
+    };
+    const onSearchKeyDown = (event) => {
+        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+            event.preventDefault();
+            if (!isOpen) {
+                setOpen(true);
+                setActive(0);
+                return;
+            }
+            setActive((index) => step(Math.min(index, Math.max(ranked.length - 1, 0)), event.key === 'ArrowDown' ? 1 : -1));
+            return;
+        }
+        if (event.key === 'Enter') {
+            const hit = ranked[activeIndex];
+            // Enter commits the highlighted option and nothing else. It never creates:
+            // creating is a separate act made in a separate field, and a key that both
+            // commits a choice and writes a new record is a key a reader cannot aim.
+            if (hit === undefined || hit.item.disabled)
+                return;
+            event.preventDefault();
+            run(hit.item);
+            return;
+        }
+        if (event.key === 'Escape') {
+            // Escape abandons the query and keeps the answer. A reader who pressed it to
+            // get the list out of the way did not mean to discard what they had chosen.
+            if (!isOpen)
+                return;
+            event.preventDefault();
+            setOpen(false);
+            setQuery(chosenLabel);
+            return;
+        }
+        if (event.key === 'Tab' && !event.shiftKey && canCreate) {
+            // The focus move into the create field, and the reason the list stays open.
+            // Tab closes a single-select field because the answer is finished; here the
+            // answer may not be, and closing would make creating a value two acts.
+            event.preventDefault();
+            draftRef.current?.focus();
+        }
+    };
+    const onDraftKeyDown = (event) => {
+        if (event.key === 'Enter') {
+            if (!canCreate)
+                return;
+            event.preventDefault();
+            create();
+            searchRef.current?.focus();
+            return;
+        }
+        if (event.key === 'Escape') {
+            // Escape in the create field abandons the draft and goes back to the search
+            // field rather than closing the list, so a reader who mistyped has not thrown
+            // away the list they were reading.
+            event.preventDefault();
+            setDraft('');
+            searchRef.current?.focus();
+            return;
+        }
+        if (event.key === 'ArrowUp' || event.key === 'ArrowDown') {
+            // The way back into the list. Reversible is the point: a one-way focus order
+            // into a popover is a trap a keyboard reader cannot see.
+            event.preventDefault();
+            setActive(event.key === 'ArrowUp' ? 0 : Math.max(ranked.length - 1, 0));
+            searchRef.current?.focus();
+            return;
+        }
+        if (event.key === 'Tab') {
+            setOpen(false);
+        }
+    };
+    useEffect(() => {
+        const list = listRef.current;
+        if (list === null)
+            return;
+        list.querySelector('[data-active="true"]')?.scrollIntoView({ block: 'nearest' });
+    }, [activeIndex, isOpen]);
+    const activeRow = isOpen ? ranked[activeIndex] : undefined;
+    return (_jsxs("div", { "data-slot": "creatable-combobox", className: cn('relative w-full', className), children: [_jsx(Input, { ref: searchRef, "data-slot": "creatable-combobox-search", id: inputId, type: "text", role: "combobox", autoComplete: "off", "aria-expanded": isOpen, "aria-controls": isOpen ? popupId : undefined, "aria-haspopup": "listbox", "aria-autocomplete": "list", "aria-label": label, "aria-required": required || undefined, "aria-activedescendant": activeRow === undefined ? undefined : `${listId}-option-${activeIndex}`, ...(describedBy === undefined ? null : { 'aria-describedby': describedBy }), ...(placeholder === undefined ? null : { placeholder }), value: query, disabled: disabled, onChange: (event) => {
+                    const next = event.target.value;
+                    setQuery(next);
+                    setActive(0);
+                    if (!isOpen)
+                        setOpen(true);
+                    // Emptying the field is the one edit that changes the answer, because it
+                    // is the only way a reader can say "not that one".
+                    if (next === '')
+                        choose(null);
+                }, onFocus: () => {
+                    setOpen(true);
+                    setActive(0);
+                }, onClick: () => {
+                    if (!isOpen)
+                        setOpen(true);
+                }, onBlur: (event) => {
+                    // Only when the caret leaves the whole control. Moving into the create
+                    // field is inside it, and closing on that would be closing on the focus
+                    // move the popover exists to support.
+                    const next = event.relatedTarget;
+                    if (next instanceof Node && event.currentTarget.parentElement?.contains(next)) {
+                        return;
+                    }
+                    setOpen(false);
+                    setQuery(chosenLabel);
+                }, onKeyDown: onSearchKeyDown }), name === undefined ? null : (_jsx("input", { type: "hidden", name: name, ...(form === undefined ? null : { form }), value: chosen ?? '', readOnly: true })), isOpen ? (_jsxs("div", { id: popupId, "data-slot": "creatable-combobox-popup", className: "bg-popover text-popover-foreground absolute z-50 mt-1 w-full min-w-(--anchor-width) rounded-md border p-1 shadow-md", children: [ranked.length === 0 ? (_jsxs("p", { "data-slot": "creatable-combobox-empty", role: "status", className: "text-muted-foreground px-3 py-6 text-center text-sm", children: [empty.message(trimmed), empty.hint === undefined ? null : (_jsx("span", { className: "mt-1 block text-xs", children: empty.hint }))] })) : (_jsx("div", { "data-slot": "creatable-combobox-list", id: listId, ref: listRef, role: "listbox", "aria-label": label, className: "max-h-72 overflow-y-auto", children: ranked.map((hit, index) => {
+                            const isActive = index === activeIndex;
+                            return (_jsxs("div", { id: `${listId}-option-${index}`, "data-slot": "creatable-combobox-option", "data-active": isActive, role: "option", "aria-selected": hit.item.value === chosen, "aria-disabled": hit.item.disabled || undefined, onMouseEnter: () => {
+                                    if (!hit.item.disabled)
+                                        setActive(index);
+                                }, onMouseDown: (event) => event.preventDefault(), onClick: () => {
+                                    run(hit.item);
+                                }, className: cn('flex cursor-pointer items-baseline justify-between gap-3 rounded-sm px-3 py-2 text-sm', 'focus-visible:ring-ring focus-visible:ring-[3px]', hit.item.disabled && 'text-muted-foreground cursor-not-allowed opacity-50', !hit.item.disabled && isActive && 'bg-accent text-accent-foreground', !hit.item.disabled && !isActive && 'text-muted-foreground hover:text-foreground'), children: [_jsx("span", { className: "min-w-0 truncate", children: hit.range === undefined ? (hit.item.label) : (_jsxs(_Fragment, { children: [hit.item.label.slice(0, hit.range[0]), _jsx("strong", { className: "font-semibold", children: hit.item.label.slice(hit.range[0], hit.range[1]) }), hit.item.label.slice(hit.range[1])] })) }), hit.item.hint === undefined ? null : (_jsx("span", { className: "shrink-0 text-xs", children: hit.item.hint }))] }, hit.item.value));
+                        }) })), _jsxs("div", { "data-slot": "creatable-combobox-create", className: "border-border flex flex-col gap-2 border-t p-2", children: [_jsx(Input, { ref: draftRef, "data-slot": "creatable-combobox-draft", id: draftId, type: "text", autoComplete: "off", "aria-label": draftLabel, "aria-invalid": draftError === null ? undefined : true, ...(draftError === null ? null : { 'aria-describedby': draftErrorId }), value: draft, disabled: disabled, onFocus: () => {
+                                    // Seeded from the query, because the reader's typed words are what
+                                    // they want to create. The copy is one way: after this the draft is
+                                    // its own value, so editing it does not move the list.
+                                    setDraft(query);
+                                }, onChange: (event) => {
+                                    setDraft(event.target.value);
+                                }, onKeyDown: onDraftKeyDown, className: "h-8" }), draftError === null ? null : (_jsx("div", { id: draftErrorId, children: _jsx(FieldError, { children: draftError }) })), canCreate ? (_jsx("button", { type: "button", "data-slot": "creatable-combobox-create-button", "aria-label": createLabel, "aria-describedby": draftId, onClick: create, className: cn('border-input bg-secondary text-secondary-foreground hover:bg-accent hover:text-accent-foreground inline-flex items-center justify-between gap-2 rounded-md border px-2 py-1 text-left text-sm outline-none', 'transition-[color,background-color] duration-fast ease-out', 'focus-visible:ring-ring focus-visible:ring-[3px]'), children: _jsx("span", { className: "min-w-0 truncate", children: draftValue }) })) : null] })] })) : null] }));
+}
+export { CreatableCombobox };

package/dist/components/ui/data-toolbar.d.ts

@@ -0,0 +1,133 @@
+import type { ComponentProps, ReactNode } from 'react';
+/** The props a `DataToolbarGroup` takes. */
+export interface DataToolbarGroupProps extends ComponentProps<'div'> {
+    /**
+     * The controls in one group.
+     *
+     * A slot and not a named control, because which controls a row has is the
+     * consumer's fact. A toolbar that drew a search box and a sort would be a
+     * toolbar that assumed the list below it is searchable and sortable.
+     */
+    children?: ReactNode;
+    /** Layout only. */
+    className?: string;
+}
+/** The props a `DataToolbar` takes. */
+export interface DataToolbarProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /**
+     * The row's accessible name, when the row is given a `role`.
+     *
+     * A `string` and not a `ReactNode`, because this one is written into
+     * `aria-label` and an accessible name is a string. A node here would render as
+     * nothing a reader hears. Pass no name for a row that is an unnamed `div`,
+     * which is the default and the ordinary case.
+     */
+    label?: string;
+    /**
+     * The search slot, at the leading end.
+     *
+     * Leading because it is the control a reader reaches for first, and because a
+     * search box at the trailing end of a row of small controls is a control the
+     * reader has to find before they can use it. The field itself is the caller's,
+     * so a caller who wants a search dialog trigger rather than a field passes
+     * their own control and the row does not change.
+     */
+    search?: ReactNode;
+    /**
+     * The filter slot, after the search.
+     *
+     * A single slot rather than a set of named filter controls, because which
+     * facets a set has is the consumer's data. A caller with three filters and a
+     * caller with one both pass one node.
+     */
+    filters?: ReactNode;
+    /**
+     * The view switcher slot, after the filters.
+     *
+     * Last of the three because it is the control a reader changes least often: it
+     * says how the same rows are drawn, not which rows are shown, so putting it
+     * beside the filters would let a reader change the question before they have
+     * asked it.
+     */
+    view?: ReactNode;
+    /**
+     * The trailing slot: the count, and whatever else belongs at the far end.
+     *
+     * Trailing and pushed to the end of the row, so the count and the row's
+     * secondary controls line up on the right and the reading order stays search,
+     * then what narrows the set, then how it is drawn, then what the reader has.
+     */
+    actions?: ReactNode;
+    /**
+     * Any further groups, in the order the caller wants them.
+     *
+     * Between the named slots and the trailing one, and composed out of
+     * `DataToolbarGroup` so a group is a group by construction rather than by a
+     * `gap` the caller remembered to add.
+     */
+    children?: ReactNode;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}
+/**
+ * The row above a table or a list: search, filters, a view switcher, and a count.
+ *
+ * **The default is a plain `div` and not a `role="toolbar"`, and that is the one
+ * decision worth making carefully.** A toolbar role changes every reader's
+ * interaction model for the row. It tells assistive technology that the whole row
+ * is one control, that the arrow keys move between the things inside it, and that
+ * Tab should step over the row rather than into it. That is exactly right for a
+ * set of controls a reader is expected to sweep through with the arrow keys, and
+ * it is exactly wrong for a row that is mostly a search box: a reader who Tabs
+ * onto the row and presses an arrow key expects to land in the search field, and a
+ * role that skips it has made the row's primary control the one control the row
+ * cannot reach by the key the role taught them. So the role is a prop and the
+ * default is nothing, and a caller who knows their row is a set of peer controls
+ * passes `role="toolbar"` and takes the model with the responsibility.
+ *
+ * **No arrow-key handling here, and deliberately.** Prism owns that keyboard model
+ * in exactly two Components, `button-group.tsx` and `toggle-group.tsx`, both of
+ * which already implement it over their own children: a roving tab stop and the
+ * arrows walking the pressed set. A third implementation in a layout row would be
+ * a third place for the same rule, and three places disagree within a release.
+ * A caller who wants the arrows puts the controls in one of those two and passes
+ * the group into this row's `children` or into a named slot.
+ *
+ * **The row wraps rather than scrolls, and a toolbar that scrolls sideways hides
+ * its own controls.** A `flex-wrap` row reflows onto a second line on a narrow
+ * screen, so the filter that a reader did not see is still on the page and still
+ * reachable. The alternative, one line with a horizontal scroller, puts a control
+ * the reader needs behind a gesture they have to discover, and the scrollbar that
+ * offers the gesture is the operating system's rather than the design system's,
+ * which is the one control this package took over precisely because it cannot be
+ * restyled into anything the design system recognises. A row that runs out of
+ * room has to reflow; there is no third option that keeps every control on screen
+ * and reachable.
+ *
+ * **The ends are held by search and by the trailing slot, and the middle is the
+ * caller's.** Search leads because it answers the question a reader arrived with;
+ * the trailing slot ends the row because a count reads as a conclusion and a
+ * conclusion is the last thing on a line. Everything between them is narrow, is
+ * the same height, and is a control about the shape of the set rather than about
+ * one row of it, so it groups tightly and the two ends stay apart.
+ *
+ * It is a server Component. It holds no state, reads no context and attaches no
+ * handler: the row is a frame, and every control in it is a control the caller
+ * brought. A table with a filter row above it costs no JavaScript from this.
+ */
+declare function DataToolbar({ label, search, filters, view, actions, children, className, ...props }: DataToolbarProps): import("react").JSX.Element;
+/**
+ * One group of controls inside a `DataToolbar`, or a group of the caller's own.
+ *
+ * A `div` with no role, and that is the whole point. A group is a spacing
+ * relationship and nothing else: it says these controls are one idea, and it
+ * gives them a single gap between them that is tighter than the gap between
+ * ideas. A `group` role on it would name a set of controls a reader could
+ * navigate, which is a claim about a keyboard model this row deliberately does
+ * not have. A caller who wants a named, navigable set of controls passes
+ * `role="toolbar"` on the row, or composes `button-group.tsx` or
+ * `toggle-group.tsx`, which is where the arrow keys live.
+ */
+declare function DataToolbarGroup({ className, ...props }: DataToolbarGroupProps): import("react").JSX.Element;
+export { DataToolbar, DataToolbarGroup };
+//# sourceMappingURL=data-toolbar.d.ts.map

package/dist/components/ui/data-toolbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-toolbar.d.ts","sourceRoot":"","sources":["../../../src/components/ui/data-toolbar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD,4CAA4C;AAC5C,MAAM,WAAW,qBAAsB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAClE;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC/E;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,iBAAS,WAAW,CAAC,EACnB,KAAK,EACL,MAAM,EACN,OAAO,EACP,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,SAAS,EACT,GAAG,KAAK,EACT,EAAE,gBAAgB,+BA4BlB;AAED;;;;;;;;;;;GAWG;AACH,iBAAS,gBAAgB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,qBAAqB,+BAQvE;AAED,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAA"}

package/dist/components/ui/data-toolbar.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+/**
+ * The row above a table or a list: search, filters, a view switcher, and a count.
+ *
+ * **The default is a plain `div` and not a `role="toolbar"`, and that is the one
+ * decision worth making carefully.** A toolbar role changes every reader's
+ * interaction model for the row. It tells assistive technology that the whole row
+ * is one control, that the arrow keys move between the things inside it, and that
+ * Tab should step over the row rather than into it. That is exactly right for a
+ * set of controls a reader is expected to sweep through with the arrow keys, and
+ * it is exactly wrong for a row that is mostly a search box: a reader who Tabs
+ * onto the row and presses an arrow key expects to land in the search field, and a
+ * role that skips it has made the row's primary control the one control the row
+ * cannot reach by the key the role taught them. So the role is a prop and the
+ * default is nothing, and a caller who knows their row is a set of peer controls
+ * passes `role="toolbar"` and takes the model with the responsibility.
+ *
+ * **No arrow-key handling here, and deliberately.** Prism owns that keyboard model
+ * in exactly two Components, `button-group.tsx` and `toggle-group.tsx`, both of
+ * which already implement it over their own children: a roving tab stop and the
+ * arrows walking the pressed set. A third implementation in a layout row would be
+ * a third place for the same rule, and three places disagree within a release.
+ * A caller who wants the arrows puts the controls in one of those two and passes
+ * the group into this row's `children` or into a named slot.
+ *
+ * **The row wraps rather than scrolls, and a toolbar that scrolls sideways hides
+ * its own controls.** A `flex-wrap` row reflows onto a second line on a narrow
+ * screen, so the filter that a reader did not see is still on the page and still
+ * reachable. The alternative, one line with a horizontal scroller, puts a control
+ * the reader needs behind a gesture they have to discover, and the scrollbar that
+ * offers the gesture is the operating system's rather than the design system's,
+ * which is the one control this package took over precisely because it cannot be
+ * restyled into anything the design system recognises. A row that runs out of
+ * room has to reflow; there is no third option that keeps every control on screen
+ * and reachable.
+ *
+ * **The ends are held by search and by the trailing slot, and the middle is the
+ * caller's.** Search leads because it answers the question a reader arrived with;
+ * the trailing slot ends the row because a count reads as a conclusion and a
+ * conclusion is the last thing on a line. Everything between them is narrow, is
+ * the same height, and is a control about the shape of the set rather than about
+ * one row of it, so it groups tightly and the two ends stay apart.
+ *
+ * It is a server Component. It holds no state, reads no context and attaches no
+ * handler: the row is a frame, and every control in it is a control the caller
+ * brought. A table with a filter row above it costs no JavaScript from this.
+ */
+function DataToolbar({ label, search, filters, view, actions, children, className, ...props }) {
+    return (_jsxs("div", { "data-slot": "data-toolbar", "aria-label": label, className: cn('flex flex-wrap items-center gap-2', className), ...props, children: [search === undefined ? null : _jsx(DataToolbarGroup, { children: search }), filters === undefined ? null : _jsx(DataToolbarGroup, { children: filters }), view === undefined ? null : _jsx(DataToolbarGroup, { children: view }), children, actions === undefined ? null : (_jsx(DataToolbarGroup, { className: "ms-auto", children: actions }))] }));
+}
+/**
+ * One group of controls inside a `DataToolbar`, or a group of the caller's own.
+ *
+ * A `div` with no role, and that is the whole point. A group is a spacing
+ * relationship and nothing else: it says these controls are one idea, and it
+ * gives them a single gap between them that is tighter than the gap between
+ * ideas. A `group` role on it would name a set of controls a reader could
+ * navigate, which is a claim about a keyboard model this row deliberately does
+ * not have. A caller who wants a named, navigable set of controls passes
+ * `role="toolbar"` on the row, or composes `button-group.tsx` or
+ * `toggle-group.tsx`, which is where the arrow keys live.
+ */
+function DataToolbarGroup({ className, ...props }) {
+    return (_jsx("div", { "data-slot": "data-toolbar-group", className: cn('flex min-w-0 items-center gap-2', className), ...props }));
+}
+export { DataToolbar, DataToolbarGroup };