@nanisoft/prism-ui 0.10.2 → 0.15.0

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

@@ -0,0 +1,181 @@
+import type { ComboboxItem } from './combobox.js';
+/** The props the Multi combobox accepts. */
+export interface MultiComboboxProps {
+    /**
+     * The accessible name of the field.
+     *
+     * Required, and required as a name rather than as a placeholder, for the reason
+     * `Combobox` requires it: a placeholder disappears the moment the reader types,
+     * which leaves a field holding a row of chips with no name at exactly the moment
+     * the reader most needs to know what they are filtering.
+     */
+    label: string;
+    /**
+     * The options.
+     *
+     * `ComboboxItem` rather than a second option type, because the shape is one fact
+     * about an option and not one fact about the number of options it appears in. A
+     * copy would drift the first time a field grew a `keywords` member.
+     */
+    items: readonly ComboboxItem[];
+    /** The chosen values, when the field is controlled. */
+    value?: readonly string[];
+    /** The values chosen initially, for an uncontrolled field. */
+    defaultValue?: readonly string[];
+    /**
+     * Called with every chosen value, in the order they were chosen.
+     *
+     * The whole set rather than the one value that changed, because there is no one
+     * value: a toggle is an edit of a set and the caller is the only party that can
+     * decide whether the form submits an array or a joined string.
+     */
+    onValueChange?: (value: readonly string[]) => void;
+    /**
+     * The accessible name of one chip's remove control, given that chip's label.
+     *
+     * Required rather than optional, which is the one place this Component is less
+     * forgiving than `TagGroup`. A multi combobox that cannot deselect is not a
+     * multi combobox, so the remove control is always drawn, so its name is always
+     * needed, and an optional prop would be a prop whose absence is always a mistake.
+     */
+    removeLabel: (label: string) => string;
+    /** What a reader is told when the query matches nothing. */
+    empty: {
+        message: (query: string) => string;
+        hint?: string;
+    };
+    /**
+     * The most values that may be chosen at once.
+     *
+     * Omit it and the set is unbounded. Given one, an option that is not yet chosen
+     * becomes `aria-disabled` and the arrows step over it once the cap is reached,
+     * and the select-all control announces itself as unavailable rather than
+     * quietly choosing fewer than it says it will.
+     */
+    max?: number;
+    /**
+     * Draws a control that chooses every option the query currently matches, and
+     * returns its accessible name given how many match.
+     *
+     * A function of a count rather than a string because the count is the whole
+     * content of the name, and it is a count of the caller's options rather than one
+     * this Component holds.
+     */
+    selectAll?: (matching: number) => string;
+    /**
+     * Draws a control that drops every chosen value, and returns its accessible name
+     * given how many are chosen.
+     */
+    clearAll?: (chosen: number) => string;
+    /**
+     * Whether the trigger shows how many values are chosen.
+     *
+     * A number and not a sentence, and it is hidden from assistive technology. The
+     * chosen values are already announced, one chip at a time, through the field's
+     * description, so a bare number adds a figure with no noun to read out loud.
+     */
+    showCount?: boolean;
+    /** 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 at least one value must be chosen before the form submits. */
+    required?: boolean;
+    /**
+     * The form field name each chosen value is submitted under.
+     *
+     * One hidden input per value, all carrying this name, because a form has no way
+     * to submit an array and a joined string is a decision the caller makes.
+     */
+    name?: string;
+    /** Identifies the form that owns the hidden inputs. */
+    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 field that searches one list and toggles as many of its options as the reader
+ * wants, with the chosen ones visible as chips in the trigger.
+ *
+ * **The value is an array, and that is not a prop combination.** Every sibling in
+ * this family commits one value: `Combobox` closes on a choice, `Select` closes on
+ * a choice, `NativeSelect` submits one value. Turning one of those into this one
+ * is not a boolean. A single-value control closes on commit because the answer is
+ * finished; here the answer is a set that keeps growing after every commit, so
+ * closing on commit makes the second choice a re-open, and a reader choosing six
+ * regions opens the field six times and retypes the query five of them. The state
+ * machine is different, not configured differently, which is the test
+ * `DESIGN.md` states: a member of a family that differs from its siblings only by a
+ * prop every one of them already takes is a call site.
+ *
+ * **Space and Enter toggle, and the list stays open.** This inverts the commit
+ * contract the single-select siblings are built on, and the inversion is the whole
+ * reason the two surfaces feel nothing alike. In a combobox, Enter ends the
+ * interaction; here it is one more toggle, and closing the list on it would make
+ * choosing a second value a two-keystroke act for no reason a reader can see. So
+ * the keys that close a single-select field are the keys that add to the set, and
+ * Escape, a blur and Tab are the ways out. The honest cost is on the typeahead:
+ * **a query cannot contain a space typed with the Space key**, because Space is
+ * spoken for. An option is found by the words in its label and in its keywords, so
+ * the space in a query buys nothing a reader would miss, and the alternative is a
+ * control where the primary key for selecting cannot also type.
+ *
+ * **Backspace in the trigger removes the last chip, and only then edits text.**
+ * Backspace with a caret in the search field is a text edit like any other. Backspace
+ * in an empty one is a gesture at the set, and it takes the last chip chosen, which
+ * is the one nearest where the caret was. This is the second gesture every token
+ * field has and the one a hand-rolled multi select gets wrong by having no second
+ * path out of the chips at all.
+ *
+ * **The chips are `TagGroup` and the frame is `InputGroup`, not a reimplementation
+ * of either.** A chip is a thing the reader chose and can un-pick, which is the
+ * definition `TagGroup` already states and the reason its remove control exists.
+ * Drawing a second chip here would be a second answer to what a chip is, and it
+ * would be the one that quietly diverges on the coarse-pointer target size. The
+ * frame is borrowed for the same reason: a bordered group with one border and one
+ * focus colour is the thing a row of chips inside a search field has to be, and
+ * `InputGroup` already turns its border to the ring token when anything inside it
+ * has focus.
+ *
+ * **The listbox is `aria-multiselectable`, because a reader who cannot see that
+ * many of its rows may be chosen does not know what Space will do.** The attribute
+ * is the whole announcement difference between this list and a single-select one,
+ * and omitting it leaves a reader guessing whether the next Space replaces or adds.
+ *
+ * **A cap is visible rather than silent.** With `max`, an unchosen option past the
+ * cap is drawn and announced as unavailable and the arrows step over it, so the
+ * limit is discoverable before the reader hits it. The select-all control is the
+ * case where silence would be worst: it says it will choose everything and then
+ * chooses fewer, so it announces itself as unavailable instead, at the cost of a
+ * reader who wanted all of it having to add the rest one at a time.
+ *
+ * **Ordering is the reader's.** Values are appended in the order they were chosen
+ * and a removal closes the gap rather than re-sorting, because a chip row that
+ * reorders under the pointer is a chip row a reader cannot aim at. The list itself
+ * 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 too.
+ *
+ * **The chosen values are announced through the field's description, not through
+ * the query.** The search field holds a query and nothing else, so a screen reader
+ * focused on it hears the query and the chosen values are silent. Pointing
+ * `aria-describedby` at the chip row costs one generated id and makes every chosen
+ * label read out after the value. `showCount` is deliberately outside that: a bare
+ * figure has no noun, so it is drawn and not announced.
+ *
+ * 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 MultiCombobox({ label, items, value, defaultValue, onValueChange, removeLabel, empty, max, selectAll, clearAll, showCount, placeholder, open, defaultOpen, onOpenChange, disabled, required, name, form, id, 'aria-describedby': describedBy, className, }: MultiComboboxProps): import("react").JSX.Element;
+export { MultiCombobox };
+//# sourceMappingURL=multi-combobox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"multi-combobox.d.ts","sourceRoot":"","sources":["../../../src/components/ui/multi-combobox.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAM9C,4CAA4C;AAC5C,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B,uDAAuD;IACvD,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACzB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAA;IAClD;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IACtC,4DAA4D;IAC5D,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5D;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,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;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,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;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,iBAAS,aAAa,CAAC,EACrB,KAAK,EACL,KAAK,EACL,KAAK,EACL,YAAiB,EACjB,aAAa,EACb,WAAW,EACX,KAAK,EACL,GAAG,EACH,SAAS,EACT,QAAQ,EACR,SAAiB,EACjB,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,kBAAkB,+BA6ZpB;AAED,OAAO,EAAE,aAAa,EAAE,CAAA"}

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

@@ -0,0 +1,297 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { CheckIcon } from 'lucide-react';
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { InputGroup, InputGroupInput } from './input-group.js';
+import { TagGroup } from './tag-group.js';
+import { RANKS, locate } from '../../lib/rank.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * The whole-list control in the popup's toolbar.
+ *
+ * `aria-disabled` rather than `disabled`, because a control that vanishes when it
+ * stops applying moves the other control under the reader's pointer. Kept out of an
+ * object map of class strings because this gate's own readers treat a `bg-` fill
+ * with no ink of its own as a variant that inherits its colour from whatever
+ * surface it lands on, and this string states both.
+ */
+const ACTION = 'text-muted-foreground hover:bg-accent hover:text-accent-foreground aria-disabled:pointer-events-none aria-disabled:opacity-50 inline-flex items-center rounded-sm px-2 py-1 text-xs outline-none transition-[color,background-color] duration-fast ease-out focus-visible:ring-ring focus-visible:ring-[3px]';
+/**
+ * A field that searches one list and toggles as many of its options as the reader
+ * wants, with the chosen ones visible as chips in the trigger.
+ *
+ * **The value is an array, and that is not a prop combination.** Every sibling in
+ * this family commits one value: `Combobox` closes on a choice, `Select` closes on
+ * a choice, `NativeSelect` submits one value. Turning one of those into this one
+ * is not a boolean. A single-value control closes on commit because the answer is
+ * finished; here the answer is a set that keeps growing after every commit, so
+ * closing on commit makes the second choice a re-open, and a reader choosing six
+ * regions opens the field six times and retypes the query five of them. The state
+ * machine is different, not configured differently, which is the test
+ * `DESIGN.md` states: a member of a family that differs from its siblings only by a
+ * prop every one of them already takes is a call site.
+ *
+ * **Space and Enter toggle, and the list stays open.** This inverts the commit
+ * contract the single-select siblings are built on, and the inversion is the whole
+ * reason the two surfaces feel nothing alike. In a combobox, Enter ends the
+ * interaction; here it is one more toggle, and closing the list on it would make
+ * choosing a second value a two-keystroke act for no reason a reader can see. So
+ * the keys that close a single-select field are the keys that add to the set, and
+ * Escape, a blur and Tab are the ways out. The honest cost is on the typeahead:
+ * **a query cannot contain a space typed with the Space key**, because Space is
+ * spoken for. An option is found by the words in its label and in its keywords, so
+ * the space in a query buys nothing a reader would miss, and the alternative is a
+ * control where the primary key for selecting cannot also type.
+ *
+ * **Backspace in the trigger removes the last chip, and only then edits text.**
+ * Backspace with a caret in the search field is a text edit like any other. Backspace
+ * in an empty one is a gesture at the set, and it takes the last chip chosen, which
+ * is the one nearest where the caret was. This is the second gesture every token
+ * field has and the one a hand-rolled multi select gets wrong by having no second
+ * path out of the chips at all.
+ *
+ * **The chips are `TagGroup` and the frame is `InputGroup`, not a reimplementation
+ * of either.** A chip is a thing the reader chose and can un-pick, which is the
+ * definition `TagGroup` already states and the reason its remove control exists.
+ * Drawing a second chip here would be a second answer to what a chip is, and it
+ * would be the one that quietly diverges on the coarse-pointer target size. The
+ * frame is borrowed for the same reason: a bordered group with one border and one
+ * focus colour is the thing a row of chips inside a search field has to be, and
+ * `InputGroup` already turns its border to the ring token when anything inside it
+ * has focus.
+ *
+ * **The listbox is `aria-multiselectable`, because a reader who cannot see that
+ * many of its rows may be chosen does not know what Space will do.** The attribute
+ * is the whole announcement difference between this list and a single-select one,
+ * and omitting it leaves a reader guessing whether the next Space replaces or adds.
+ *
+ * **A cap is visible rather than silent.** With `max`, an unchosen option past the
+ * cap is drawn and announced as unavailable and the arrows step over it, so the
+ * limit is discoverable before the reader hits it. The select-all control is the
+ * case where silence would be worst: it says it will choose everything and then
+ * chooses fewer, so it announces itself as unavailable instead, at the cost of a
+ * reader who wanted all of it having to add the rest one at a time.
+ *
+ * **Ordering is the reader's.** Values are appended in the order they were chosen
+ * and a removal closes the gap rather than re-sorting, because a chip row that
+ * reorders under the pointer is a chip row a reader cannot aim at. The list itself
+ * 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 too.
+ *
+ * **The chosen values are announced through the field's description, not through
+ * the query.** The search field holds a query and nothing else, so a screen reader
+ * focused on it hears the query and the chosen values are silent. Pointing
+ * `aria-describedby` at the chip row costs one generated id and makes every chosen
+ * label read out after the value. `showCount` is deliberately outside that: a bare
+ * figure has no noun, so it is drawn and not announced.
+ *
+ * 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 MultiCombobox({ label, items, value, defaultValue = [], onValueChange, removeLabel, empty, max, selectAll, clearAll, showCount = false, 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 [active, setActive] = useState(0);
+    const listRef = useRef(null);
+    const inputRef = 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 chipsId = `${generated}-chips`;
+    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 commit = useCallback((next) => {
+        if (value === undefined)
+            setOwnValue(next);
+        onValueChange?.(next);
+    }, [onValueChange, value]);
+    const chosenSet = useMemo(() => new Set(chosen), [chosen]);
+    const atCap = max !== undefined && chosen.length >= max;
+    const labelOf = useCallback((v) => items.find((item) => item.value === v)?.label ?? v, [items]);
+    const ranked = useMemo(() => {
+        const trimmed = query.trim();
+        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, query]);
+    // Clamped rather than reset on every keystroke, for the reason `Combobox` states:
+    // a reader who moved the highlight and then typed is choosing from a list that
+    // just changed under them.
+    const activeIndex = Math.min(active, Math.max(ranked.length - 1, 0));
+    /** Whether an option may be added right now. */
+    const locked = useCallback((item) => item.disabled === true || (atCap && !chosenSet.has(item.value)), [atCap, chosenSet]);
+    /**
+     * Moves the highlight by `delta` rows, stepping over options that cannot be
+     * added. It stops on the row it started from rather than spinning, so a list of
+     * nothing but unavailable options cannot cycle.
+     */
+    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;
+            const hit = ranked[next];
+            if (hit !== undefined && !locked(hit.item))
+                return next;
+        }
+        return from;
+    };
+    const toggle = (item) => {
+        if (chosenSet.has(item.value)) {
+            commit(chosen.filter((v) => v !== item.value));
+            return;
+        }
+        if (locked(item))
+            return;
+        commit([...chosen, item.value]);
+    };
+    const openAt = (from) => {
+        setOpen(true);
+        setActive(from);
+    };
+    const onKeyDown = (event) => {
+        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+            event.preventDefault();
+            if (!isOpen) {
+                openAt(0);
+                return;
+            }
+            setActive((index) => step(Math.min(index, Math.max(ranked.length - 1, 0)), event.key === 'ArrowDown' ? 1 : -1));
+            return;
+        }
+        if (event.key === 'Enter' || event.code === 'Space') {
+            const hit = ranked[activeIndex];
+            // Both keys do nothing with nothing to toggle, which is the same refusal
+            // `Combobox` makes: an action the reader did not point at is not one they
+            // asked for.
+            if (hit === undefined || locked(hit.item))
+                return;
+            // The caret never moves and the list never closes. Both keys are consumed so
+            // Space does not type a space and Enter does not submit the form mid-choice.
+            event.preventDefault();
+            toggle(hit.item);
+            return;
+        }
+        if (event.key === 'Escape') {
+            // Escape gets the list out of the way and touches nothing else. Every chosen
+            // value is an act, so discarding them here would take back work the reader
+            // did, and a field that emptied itself on Escape submits nothing they asked
+            // for.
+            if (!isOpen)
+                return;
+            event.preventDefault();
+            setOpen(false);
+            return;
+        }
+        if (event.key === 'Backspace' && query === '' && chosen.length > 0) {
+            event.preventDefault();
+            commit(chosen.slice(0, -1));
+            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 chips = useMemo(() => chosen.map((v) => ({ id: v, label: labelOf(v) })), [chosen, labelOf]);
+    const activeRow = isOpen ? ranked[activeIndex] : undefined;
+    // Two possible referrers, one attribute. Assembled from a template rather than a
+    // join so the separator is never a bare string literal, which is the shape a copy
+    // scan reads as a space somebody typed.
+    const describedByIds = chips.length === 0
+        ? describedBy
+        : describedBy === undefined
+            ? chipsId
+            : `${chipsId} ${describedBy}`;
+    const room = max === undefined ? ranked.length : max - chosen.length;
+    return (_jsxs("div", { "data-slot": "multi-combobox", className: cn('relative w-full', className), children: [_jsxs(InputGroup, { "data-slot": "multi-combobox-trigger", disabled: disabled, className: "flex-wrap gap-x-1.5 gap-y-1 py-1", children: [chips.length === 0 ? null : (_jsx("div", { id: chipsId, "data-slot": "multi-combobox-chips", onMouseDown: (event) => {
+                            // Two gestures, one handler, both about where the caret ends up. A
+                            // press on a chip's remove control must not blur the search field,
+                            // because the blur is the path that closes the list, so the press is
+                            // swallowed and the click still lands. A press on the chip itself
+                            // brings the caret to the field, which is also what opens the list.
+                            if (event.target.closest('[data-slot="tag-remove"]') !== null) {
+                                event.preventDefault();
+                                return;
+                            }
+                            inputRef.current?.focus();
+                        }, className: "flex w-full shrink-0 flex-wrap items-center", children: _jsx(TagGroup, { tags: chips, onRemove: (removed) => {
+                                commit(chosen.filter((v) => v !== removed));
+                            }, 
+                            // `TagGroup` types a tag label as a node because a tag is often an
+                            // avatar and a word. Every chip drawn here is a string taken from the
+                            // caller's own option, so the node it hands back is that string and
+                            // the coercion is total rather than a guess.
+                            removeLabel: (chip) => removeLabel(String(chip)) }) })), _jsx(InputGroupInput, { ref: inputRef, 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}`, ...(describedByIds === '' ? null : { 'aria-describedby': describedByIds }), ...(placeholder === undefined ? null : { placeholder }), value: query, disabled: disabled, onChange: (event) => {
+                            const next = event.target.value;
+                            setQuery(next);
+                            setActive(0);
+                            if (!isOpen)
+                                setOpen(true);
+                        }, onFocus: () => {
+                            openAt(0);
+                        }, onClick: () => {
+                            if (!isOpen)
+                                openAt(0);
+                        }, onBlur: () => {
+                            setOpen(false);
+                        }, onKeyDown: onKeyDown }), showCount ? (_jsx("span", { "data-slot": "multi-combobox-count", "aria-hidden": "true", className: "text-muted-foreground shrink-0 self-center pr-1 text-xs tabular-nums", children: chosen.length })) : null] }), name === undefined
+                ? null
+                : chosen.map((v) => (_jsx("input", { type: "hidden", name: name, ...(form === undefined ? null : { form }), value: v, readOnly: true }, v))), isOpen ? (_jsxs("div", { id: popupId, "data-slot": "multi-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: [selectAll === undefined && clearAll === undefined ? null : (_jsxs("div", { "data-slot": "multi-combobox-actions", className: "border-border flex items-center gap-1 border-b p-1 pb-2", children: [selectAll === undefined ? null : (_jsx("button", { type: "button", "data-slot": "multi-combobox-select-all", "aria-disabled": atCap || undefined, onClick: () => {
+                                    if (atCap)
+                                        return;
+                                    const added = ranked
+                                        .filter((hit) => !chosenSet.has(hit.item.value))
+                                        .slice(0, room)
+                                        .map((hit) => hit.item.value);
+                                    commit([...chosen, ...added]);
+                                }, className: ACTION, children: selectAll(ranked.length) })), clearAll === undefined ? null : (_jsx("button", { type: "button", "data-slot": "multi-combobox-clear-all", "aria-disabled": chosen.length === 0 || undefined, onClick: () => {
+                                    if (chosen.length === 0)
+                                        return;
+                                    commit([]);
+                                }, className: ACTION, children: clearAll(chosen.length) }))] })), ranked.length === 0 ? (_jsxs("p", { "data-slot": "multi-combobox-empty", role: "status", className: "text-muted-foreground px-3 py-6 text-center text-sm", children: [empty.message(query.trim()), empty.hint === undefined ? null : (_jsx("span", { className: "mt-1 block text-xs", children: empty.hint }))] })) : (_jsx("div", { "data-slot": "multi-combobox-list", id: listId, ref: listRef, role: "listbox", "aria-label": label, "aria-multiselectable": "true", className: "max-h-72 overflow-y-auto", children: ranked.map((hit, index) => {
+                            const isActive = index === activeIndex;
+                            const isChosen = chosenSet.has(hit.item.value);
+                            const isLocked = locked(hit.item);
+                            return (_jsxs("div", { id: `${listId}-option-${index}`, "data-slot": "multi-combobox-option", "data-active": isActive, "data-selected": isChosen || undefined, role: "option", "aria-selected": isChosen, "aria-disabled": isLocked || undefined, onMouseEnter: () => {
+                                    if (!isLocked)
+                                        setActive(index);
+                                }, 
+                                // Swallowed for the reason `Combobox` swallows it: without it a
+                                // pointer choice is a blur, and the blur is the path that closes
+                                // the list under the reader's own click.
+                                onMouseDown: (event) => event.preventDefault(), onClick: () => {
+                                    toggle(hit.item);
+                                }, className: cn('flex cursor-pointer items-center gap-2 rounded-sm px-3 py-2 text-sm', isLocked && 'text-muted-foreground cursor-not-allowed opacity-50', !isLocked && isActive && 'bg-accent text-accent-foreground', !isLocked && !isActive && 'text-muted-foreground hover:text-foreground'), children: [_jsx("span", { "data-slot": "multi-combobox-option-mark", className: "w-4 shrink-0", children: isChosen ? _jsx(CheckIcon, { className: "size-4", "aria-hidden": "true" }) : null }), _jsx("span", { className: "min-w-0 flex-1 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));
+                        }) }))] })) : null] }));
+}
+export { MultiCombobox };

package/dist/components/ui/native-select.d.ts

@@ -0,0 +1,72 @@
+import type { ComponentProps, ReactNode } from 'react';
+/** The props the NativeSelect accepts. */
+/**
+ * The props the NativeSelect accepts.
+ *
+ * `size` is this Component's own height in the package's scale, which is why the
+ * native `size` attribute is omitted from the props it forwards. The two mean
+ * different things: the native one is how many rows of the list the platform shows
+ * at once, which on a single-selection select is a way of drawing a taller control,
+ * and a single prop cannot be both without lying about which one a caller is
+ * setting. A list box several rows tall is `Select`, or a `NativeSelect` inside a
+ * `ScrollArea`.
+ */
+export interface NativeSelectProps extends Omit<ComponentProps<'select'>, 'children' | 'size'> {
+    /** The options, as `option` or `optgroup` elements. */
+    children?: ReactNode;
+    /**
+     * The control's accessible name, when no visible label is used.
+     *
+     * A native select takes its name from an associated `label` like any other form
+     * control, and Prism's `Field` puts one there. This is for the case where there
+     * is no `Field` around it, and it is a prop for the reason every accessible name
+     * in this package is one.
+     */
+    'aria-label'?: string;
+    /** The control's height. @defaultValue 'default' */
+    size?: 'sm' | 'default';
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * A native `<select>`, styled to match the rest of this package.
+ *
+ * **This is not a second Select, and the difference is which element is on the
+ * page.** The `Select` in this package is Base UI's: a `<button>` carrying
+ * `role="combobox"` and a popup list Base UI positions, types into and manages the
+ * keyboard for. It is a custom control, and everything it offers over the platform
+ * is the price of being one: it needs JavaScript to open, it cannot be operated by
+ * the mobile picker a reader expects when they tap a select on a phone, it is
+ * invisible to a right-click menu that offers "Save as", and it is a set of `div`s
+ * where the browser's own is one element with thirty years of platform behaviour
+ * behind it.
+ *
+ * So this Component renders the platform element. Everything the browser does with
+ * a `<select>` it still does: the wheel on Windows, the wheel on macOS and iOS,
+ * type-ahead on the first letter, the mobile picker, the form submission, and the
+ * context menu. The styling is the package's, so the control looks like its
+ * neighbours, and the appearance is suppressed so the drawn chevron is Prism's
+ * rather than the platform's.
+ *
+ * **When this is the right answer rather than the compromise it sounds like.** A
+ * native select is right when the platform's picker is better than anything this
+ * package could draw: a long list of plain strings on a phone, a form that must
+ * submit without JavaScript, a control inside a page that is already a form and
+ * gains nothing from a popup that is portalled and dismissed. It is wrong when the
+ * option needs to be more than a string, because an `<option>` holds text and
+ * nothing else: no description, no count, no state, no nested markup. That is the
+ * line, and the `Select` is on the other side of it.
+ *
+ * **The chevron is decoration and says so.** It is `aria-hidden` and it is not
+ * focusable, because the value is already announced by the platform control and a
+ * reader hearing "graphic" after every option set is a reader being told something
+ * about the drawing rather than about the value. The control is one tab stop and
+ * the browser owns its key handling entirely, which is the point.
+ *
+ * It is a server Component. A native select holds no state, runs no effect and
+ * attaches no handler, so a form of twenty of them costs no JavaScript at all,
+ * which is a real answer to the argument above rather than a footnote to it.
+ */
+declare function NativeSelect({ className, size, children, ...props }: NativeSelectProps): import("react").JSX.Element;
+export { NativeSelect };
+//# sourceMappingURL=native-select.d.ts.map

package/dist/components/ui/native-select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-select.d.ts","sourceRoot":"","sources":["../../../src/components/ui/native-select.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItD,0CAA0C;AAC1C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAC5F,uDAAuD;IACvD,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAA;IACvB,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,iBAAS,YAAY,CAAC,EACpB,SAAS,EACT,IAAgB,EAChB,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,iBAAiB,+BAuDnB;AAED,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/components/ui/native-select.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronDownIcon } from 'lucide-react';
+import { cn } from '../../lib/utils.js';
+/**
+ * A native `<select>`, styled to match the rest of this package.
+ *
+ * **This is not a second Select, and the difference is which element is on the
+ * page.** The `Select` in this package is Base UI's: a `<button>` carrying
+ * `role="combobox"` and a popup list Base UI positions, types into and manages the
+ * keyboard for. It is a custom control, and everything it offers over the platform
+ * is the price of being one: it needs JavaScript to open, it cannot be operated by
+ * the mobile picker a reader expects when they tap a select on a phone, it is
+ * invisible to a right-click menu that offers "Save as", and it is a set of `div`s
+ * where the browser's own is one element with thirty years of platform behaviour
+ * behind it.
+ *
+ * So this Component renders the platform element. Everything the browser does with
+ * a `<select>` it still does: the wheel on Windows, the wheel on macOS and iOS,
+ * type-ahead on the first letter, the mobile picker, the form submission, and the
+ * context menu. The styling is the package's, so the control looks like its
+ * neighbours, and the appearance is suppressed so the drawn chevron is Prism's
+ * rather than the platform's.
+ *
+ * **When this is the right answer rather than the compromise it sounds like.** A
+ * native select is right when the platform's picker is better than anything this
+ * package could draw: a long list of plain strings on a phone, a form that must
+ * submit without JavaScript, a control inside a page that is already a form and
+ * gains nothing from a popup that is portalled and dismissed. It is wrong when the
+ * option needs to be more than a string, because an `<option>` holds text and
+ * nothing else: no description, no count, no state, no nested markup. That is the
+ * line, and the `Select` is on the other side of it.
+ *
+ * **The chevron is decoration and says so.** It is `aria-hidden` and it is not
+ * focusable, because the value is already announced by the platform control and a
+ * reader hearing "graphic" after every option set is a reader being told something
+ * about the drawing rather than about the value. The control is one tab stop and
+ * the browser owns its key handling entirely, which is the point.
+ *
+ * It is a server Component. A native select holds no state, runs no effect and
+ * attaches no handler, so a form of twenty of them costs no JavaScript at all,
+ * which is a real answer to the argument above rather than a footnote to it.
+ */
+function NativeSelect({ className, size = 'default', children, ...props }) {
+    return (_jsxs("div", { "data-slot": "native-select", className: "relative w-full", children: [_jsx("select", { "data-slot": "native-select-control", className: cn(
+                // `appearance-none` is what lets the chevron be drawn rather than
+                // inherited: the platform's own arrow is the one piece of this control
+                // that would otherwise belong to no design system, and the whole reason
+                // this Component exists is to take that over.
+                'border-input bg-background text-foreground w-full appearance-none rounded-md border ps-3 pe-9 text-sm outline-none', 'transition-[color,box-shadow,border-color] duration-fast ease-out', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'aria-invalid:border-destructive aria-invalid:ring-destructive/20', 'disabled:cursor-not-allowed disabled:opacity-50', 
+                // The font is inherited explicitly, because a `<select>` does not
+                // inherit one in every engine and a control in the platform's face
+                // beside text in Inter is a control nobody designed.
+                'font-inherit', 
+                // The coarse-pointer floor, as a step, and the same string `select.tsx` puts on
+                // its trigger. This Component exists to take over the platform's own arrow, so
+                // its metrics are Prism's to state rather than the browser's, and the argument
+                // is the trigger's: a select is a control a finger presses to open a list, not a
+                // field a finger types into, so its height belongs on the floor. It is `w-full`,
+                // so only the height was short. See DESIGN.md, The coarse-pointer floor.
+                'pointer-coarse:h-11', size === 'sm' ? 'h-8' : 'h-9', className), ...props, children: children }), _jsx("span", { "data-slot": "native-select-icon", "aria-hidden": "true", className: "text-muted-foreground pointer-events-none absolute top-1/2 right-3 flex size-4 -translate-y-1/2 items-center justify-center", children: _jsx(ChevronDownIcon, { className: "size-4" }) })] }));
+}
+export { NativeSelect };