@nanisoft/prism-ui 0.10.2 → 0.13.0

package/dist/components/ui/collapsible.js

@@ -0,0 +1,54 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Collapsible as CollapsiblePrimitive } from '@base-ui/react/collapsible';
+import { ChevronRightIcon } from 'lucide-react';
+import { cn } from '../../lib/utils.js';
+/**
+ * A section that shows and hides, in place.
+ *
+ * **A Collapsible is one section; an Accordion is a stack of them.** The
+ * difference is what a reader can do with the result. An accordion lets one
+ * section open by closing another, which is right for a set of peers and wrong
+ * for a page that needs two things visible at once. A collapsible keeps its own
+ * state and touches nothing else, so a reader can have three open, which is
+ * usually what a page of settings wants and an accordion forbids.
+ *
+ * **The trigger and the region are wired by the library, not by the caller.**
+ * A consumer who writes the two as siblings with their own `aria-expanded` gets a
+ * button that says "collapsed" while the panel is open, or a panel no button
+ * controls, and the failure is invisible until a reader meets it. Here the
+ * trigger is a real button carrying the expanded state and pointing at the
+ * panel, so Enter and Space open it and the announcement is right without the
+ * caller writing a line of it. The chevron turns on that same state rather than
+ * on a timer: something happened and the reader can see that it did.
+ *
+ * **A reader who collapses something must be able to find it again.** The
+ * trigger is always in the document and always carries its own words, so the way
+ * back never depends on the panel that was just closed, and a collapsed section
+ * never leaves a heading with nothing under it. Pass `hiddenUntilFound` on the
+ * content when the closed section holds text the reader may be searching for.
+ */
+function Collapsible({ className, ...props }) {
+    return (_jsx(CollapsiblePrimitive.Root, { "data-slot": "collapsible", className: cn('flex flex-col', className), ...props }));
+}
+/**
+ * The button that shows and hides the panel.
+ *
+ * It is the way back, so it keeps its own words when the panel is closed, and it
+ * is a real button so Enter and Space work and so the reader can find it again
+ * with the keyboard after closing the section without their hands.
+ */
+function CollapsibleTrigger({ className, children, ...props }) {
+    return (_jsxs(CollapsiblePrimitive.Trigger, { "data-slot": "collapsible-trigger", className: cn('text-foreground group flex w-full items-center justify-between gap-3 rounded-md py-3 text-left text-sm font-medium outline-none', 'transition-[color,background-color,box-shadow] duration-fast ease-out', 'hover:bg-accent/60 hover:text-accent-foreground focus-visible:ring-ring focus-visible:ring-[3px]', 'data-[disabled]:pointer-events-none data-[disabled]:opacity-50', className), ...props, children: [children, _jsx(ChevronRightIcon, { className: "text-muted-foreground pointer-events-none size-4 shrink-0 transition-transform duration-base ease-out group-data-[panel-open]:rotate-90" })] }));
+}
+/**
+ * The region the trigger shows and hides.
+ *
+ * The height transition is state feedback rather than decoration: the panel is
+ * opening or closing and the reader can watch it happen, which is the one motion
+ * this system allows on a surface like this.
+ */
+function CollapsibleContent({ className, ...props }) {
+    return (_jsx(CollapsiblePrimitive.Panel, { "data-slot": "collapsible-content", className: cn('h-(--collapsible-panel-height) overflow-hidden text-sm', 'transition-[height] duration-base ease-out', 'data-[starting-style]:h-0 data-[ending-style]:h-0', '[&[hidden]:not([hidden="until-found"])]:hidden', className), ...props }));
+}
+export { Collapsible, CollapsibleTrigger, CollapsibleContent };

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

@@ -0,0 +1,141 @@
+/**
+ * One option the reader can choose.
+ *
+ * A single type rather than a union of "an option with a value" and "an option
+ * that is disabled", because a disabled option is still an option and still has
+ * to be rendered: a reader who cannot see what they cannot choose cannot tell a
+ * sold-out flight from a flight that was never offered.
+ */
+export interface ComboboxItem {
+    /** What the form submits. It is a machine value, never a sentence. */
+    value: string;
+    /** The words on the row, and the words the query is matched against. */
+    label: string;
+    /** A short run at the far end of the row, usually a region or a stock count. */
+    hint?: string;
+    /**
+     * Words that should also find this option.
+     *
+     * The same argument the command row makes. An option is findable by what it is
+     * for as well as by what it is called, and only the caller knows the other words
+     * for it.
+     */
+    keywords?: readonly string[];
+    /** Whether the option is shown but cannot be chosen. */
+    disabled?: boolean;
+}
+/** The props the Combobox accepts. */
+export interface ComboboxProps {
+    /**
+     * The accessible name of the field.
+     *
+     * Required, and required as a name rather than as a placeholder: a placeholder
+     * disappears the moment a reader types, which leaves the field with no name at
+     * exactly the moment the reader most needs to know what they are filling in.
+     */
+    label: string;
+    /** The options. */
+    items: readonly ComboboxItem[];
+    /**
+     * The chosen value, when the field is controlled.
+     *
+     * Pass `null` for nothing chosen. Omit it for an uncontrolled field, which
+     * starts at `defaultValue`.
+     */
+    value?: string | null;
+    /** The value chosen initially, for an uncontrolled field. */
+    defaultValue?: string | null;
+    /** Called with the chosen value, or `null` when the reader clears the field. */
+    onValueChange?: (value: string | null) => void;
+    /**
+     * What a reader is told when nothing matches.
+     *
+     * `message` receives the query, so a caller can put it in their own sentence. A
+     * field that filtered to nothing and said nothing is the state that reads as a
+     * broken control rather than as a search that found nothing.
+     */
+    empty: {
+        message: (query: string) => string;
+        hint?: string;
+    };
+    /** The placeholder in the field. The caller's word, and it disappears on typing. */
+    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 before the form submits. */
+    required?: boolean;
+    /** The form field name. The chosen `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 commits one of them.
+ *
+ * **It ranks, and the ranking is not written here.** `locate` and `RANKS` are
+ * imported from the command palette rather than reimplemented, because a combobox
+ * that filters without ordering shows every option containing the query in the
+ * order the options happened to be fetched, so the one the reader meant sits below
+ * one that merely mentions what they typed. That is the defect this Component
+ * exists to avoid, and a second scorer would be a second answer to it. The rank
+ * table is imported, not copied, so the two surfaces cannot drift apart.
+ *
+ * **Typing never discards a choice.** The submitted value changes only when the
+ * reader chooses an option or empties the field, both of which are acts. Filtering
+ * the list under a chosen value is a question about the list, not about the
+ * answer, and a combobox that cleared the selection because the reader typed one
+ * more character would silently change what the form submits. The field's own
+ * text is restored to the chosen label when the list closes, so a reader who typed
+ * a query and changed their mind gets their answer back rather than a stray
+ * string.
+ *
+ * **A query is the difference between the text and the choice.** A field showing
+ * exactly the chosen label is not narrowing anything, so opening a filled field
+ * shows every option with the chosen one selected rather than the one option whose
+ * name matches what is already in the box. That is the same fact the previous
+ * paragraph describes, read the other way round, and it means "chosen and
+ * filtered out" cannot happen: there is no state in which the answer is a value
+ * the reader cannot see.
+ *
+ * **Nothing matching says so in words, and keeps the list open.** The field stays
+ * open and explains that the query found nothing, because a combobox that closed
+ * itself on a non-match tells the reader their keystroke broke the control. The
+ * explanation is a prop, since the sentence is the caller's and the query is put
+ * into it.
+ *
+ * **The field keeps the caret for the whole interaction.** The arrows move a
+ * highlight through the list and leave focus where it is, so a reader can keep
+ * typing while they choose. Enter commits the highlighted option and nothing else:
+ * an empty result with Enter does nothing rather than committing the first row,
+ * because committing a value a reader did not point at is the one outcome this
+ * Component must never produce.
+ *
+ * **The arrows wrap, exactly as the palette's do.** One interaction, one
+ * behaviour: a reader who learned one of these surfaces has learned both, and a
+ * list that stops at its end makes an overshoot cost a second keypress.
+ *
+ * **A disabled option is shown and skipped.** It is in the list, so a reader can
+ * see that it exists, and the arrows step over it, so a reader cannot land on
+ * something they cannot choose. Explain why it is unavailable in text beside the
+ * field; a greyed row on its own says only that it is not available.
+ *
+ * The list is anchored to the field rather than portalled, so it scrolls with the
+ * page and is clipped by an ancestor with `overflow: hidden`. That is the trade
+ * for a list that is always the right width and never flips over the field: put
+ * the field near the top of any scroll container it lives in.
+ */
+declare function Combobox({ label, items, value, defaultValue, onValueChange, empty, placeholder, open, defaultOpen, onOpenChange, disabled, required, name, form, id, 'aria-describedby': describedBy, className, }: ComboboxProps): import("react").JSX.Element;
+export { Combobox };
+//# sourceMappingURL=combobox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"combobox.d.ts","sourceRoot":"","sources":["../../../src/components/ui/combobox.tsx"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAA;IACb,gFAAgF;IAChF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,mBAAmB;IACnB,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IAC9B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,gFAAgF;IAChF,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC9C;;;;;;OAMG;IACH,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5D,oFAAoF;IACpF,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,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,qEAAqE;IACrE,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,iBAAS,QAAQ,CAAC,EAChB,KAAK,EACL,KAAK,EACL,KAAK,EACL,YAAmB,EACnB,aAAa,EACb,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,aAAa,+BAyTf;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/ui/combobox.js

@@ -0,0 +1,243 @@
+'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 { RANKS, locate } from '../../lib/rank.js';
+import { cn } from '../../lib/utils.js';
+/**
+ * A text field that filters a list of options and commits one of them.
+ *
+ * **It ranks, and the ranking is not written here.** `locate` and `RANKS` are
+ * imported from the command palette rather than reimplemented, because a combobox
+ * that filters without ordering shows every option containing the query in the
+ * order the options happened to be fetched, so the one the reader meant sits below
+ * one that merely mentions what they typed. That is the defect this Component
+ * exists to avoid, and a second scorer would be a second answer to it. The rank
+ * table is imported, not copied, so the two surfaces cannot drift apart.
+ *
+ * **Typing never discards a choice.** The submitted value changes only when the
+ * reader chooses an option or empties the field, both of which are acts. Filtering
+ * the list under a chosen value is a question about the list, not about the
+ * answer, and a combobox that cleared the selection because the reader typed one
+ * more character would silently change what the form submits. The field's own
+ * text is restored to the chosen label when the list closes, so a reader who typed
+ * a query and changed their mind gets their answer back rather than a stray
+ * string.
+ *
+ * **A query is the difference between the text and the choice.** A field showing
+ * exactly the chosen label is not narrowing anything, so opening a filled field
+ * shows every option with the chosen one selected rather than the one option whose
+ * name matches what is already in the box. That is the same fact the previous
+ * paragraph describes, read the other way round, and it means "chosen and
+ * filtered out" cannot happen: there is no state in which the answer is a value
+ * the reader cannot see.
+ *
+ * **Nothing matching says so in words, and keeps the list open.** The field stays
+ * open and explains that the query found nothing, because a combobox that closed
+ * itself on a non-match tells the reader their keystroke broke the control. The
+ * explanation is a prop, since the sentence is the caller's and the query is put
+ * into it.
+ *
+ * **The field keeps the caret for the whole interaction.** The arrows move a
+ * highlight through the list and leave focus where it is, so a reader can keep
+ * typing while they choose. Enter commits the highlighted option and nothing else:
+ * an empty result with Enter does nothing rather than committing the first row,
+ * because committing a value a reader did not point at is the one outcome this
+ * Component must never produce.
+ *
+ * **The arrows wrap, exactly as the palette's do.** One interaction, one
+ * behaviour: a reader who learned one of these surfaces has learned both, and a
+ * list that stops at its end makes an overshoot cost a second keypress.
+ *
+ * **A disabled option is shown and skipped.** It is in the list, so a reader can
+ * see that it exists, and the arrows step over it, so a reader cannot land on
+ * something they cannot choose. Explain why it is unavailable in text beside the
+ * field; a greyed row on its own says only that it is not available.
+ *
+ * The list is anchored to the field rather than portalled, so it scrolls with the
+ * page and is clipped by an ancestor with `overflow: hidden`. That is the trade
+ * for a list that is always the right width and never flips over the field: put
+ * the field near the top of any scroll container it lives in.
+ */
+function Combobox({ label, items, value, defaultValue = null, onValueChange, 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 [active, setActive] = useState(0);
+    const listRef = useRef(null);
+    const generated = useId();
+    const inputId = id ?? generated;
+    const listId = `${generated}-list`;
+    const chosen = value === undefined ? ownValue : value;
+    /** The chosen option, resolved against the option set the caller passed. */
+    const chosenItem = useMemo(() => items.find((item) => item.value === chosen) ?? null, [items, chosen]);
+    const chosenLabel = chosenItem?.label ?? '';
+    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. Typing
+     * does not change the choice, so this effect does not run while a reader is
+     * typing, which is what lets the field hold a query that is not yet an answer.
+     */
+    useEffect(() => {
+        setQuery(chosenLabel);
+    }, [chosenLabel]);
+    // A field showing exactly what is chosen is not narrowing the list. Reading the
+    // narrowing off the difference between the two rather than off a flag is what
+    // makes "chosen and filtered out" impossible: there is no sequence of keystrokes
+    // that produces a query equal to the chosen label and still filters.
+    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 };
+            // Keywords are read only after the label misses, so a keyword can never
+            // outrank a name that matched. Same rule, same scorer, same reason.
+            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]);
+    // Clamped rather than reset on every keystroke. A reader who has moved the
+    // highlight and then types one more character is choosing from a list that just
+    // changed under them, and putting the highlight back at the top discards where
+    // they were.
+    const activeIndex = Math.min(active, Math.max(ranked.length - 1, 0));
+    /**
+     * Moves the highlight by `delta` rows, stepping over the options that cannot be
+     * chosen. It stops on the row it started from if every option in that direction
+     * is disabled, so a list of nothing but unavailable options cannot spin.
+     */
+    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;
+    };
+    /** Opens the list with the chosen option under the highlight, or the first one. */
+    const openAt = useCallback((from) => {
+        setOpen(true);
+        setActive(from);
+    }, [setOpen]);
+    const openWithHighlight = () => {
+        const at = ranked.findIndex((hit) => hit.item.value === chosen && !hit.item.disabled);
+        openAt(at === -1 ? 0 : at);
+    };
+    /** Puts the chosen label back, for the paths that abandon a query. */
+    const restore = () => {
+        setQuery(chosenLabel);
+        setActive(0);
+    };
+    const run = (item) => {
+        if (item.disabled)
+            return;
+        choose(item.value);
+        setOpen(false);
+        restore();
+    };
+    const onKeyDown = (event) => {
+        if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+            event.preventDefault();
+            if (!isOpen) {
+                openWithHighlight();
+                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 with nothing selectable highlighted does nothing. Committing the
+            // first row because the reader pressed Enter is the one outcome a combobox
+            // must never produce.
+            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 their choice, and a
+            // field that emptied itself here would submit nothing they asked for.
+            if (!isOpen)
+                return;
+            event.preventDefault();
+            setOpen(false);
+            restore();
+            return;
+        }
+        if (event.key === 'Tab') {
+            // Tab commits the highlighted option and leaves, rather than dropping the
+            // highlight on the floor. A reader tabbing past a field they just narrowed
+            // was on their way to submitting it.
+            const hit = ranked[activeIndex];
+            if (isOpen && hit !== undefined && !hit.item.disabled)
+                choose(hit.item.value);
+            setOpen(false);
+        }
+    };
+    /** Keeps the highlighted row in view when the arrows move it. */
+    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": "combobox", className: cn('relative w-full', className), children: [_jsx("input", { "data-slot": "combobox-input", id: inputId, type: "text", role: "combobox", autoComplete: "off", "aria-expanded": isOpen && ranked.length > 0, "aria-controls": listId, "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". Any other keystroke
+                    // is a query, and a query is not a submission.
+                    if (next === '')
+                        choose(null);
+                }, onFocus: () => {
+                    openWithHighlight();
+                }, onClick: () => {
+                    if (!isOpen)
+                        openWithHighlight();
+                }, onBlur: () => {
+                    setOpen(false);
+                    restore();
+                }, onKeyDown: onKeyDown, className: cn('border-input bg-background text-foreground placeholder:text-muted-foreground flex h-9 w-full min-w-0 rounded-md border px-3 py-1 text-base shadow-xs transition-[color,box-shadow] duration-fast ease-out outline-none md:text-sm', 'focus-visible:border-ring focus-visible:ring-ring focus-visible:ring-[3px]', 'disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50') }), name === undefined ? null : (_jsx("input", { type: "hidden", name: name, ...(form === undefined ? null : { form }), value: chosen ?? '', readOnly: true })), isOpen ? (ranked.length === 0 ? (_jsx("div", { "data-slot": "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: _jsxs("p", { "data-slot": "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": "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: _jsx("div", { "data-slot": "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": "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);
+                            }, 
+                            // The mousedown is swallowed so the field does not blur and
+                            // restore the query before the click lands. Without it a
+                            // pointer choice is a blur, and the blur is the path that puts
+                            // the old answer back into the field.
+                            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 outline-none', '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));
+                    }) }) }))) : null] }));
+}
+export { Combobox };

package/dist/components/ui/command-palette.d.ts

@@ -0,0 +1,106 @@
+/**
+ * One thing a reader can do from the palette.
+ *
+ * `keywords` is what makes the palette good rather than merely present. A command
+ * called "Toggle theme" is findable by "theme" and not by "dark" or "colour", and
+ * a caller who has to name a command exactly has to already know it exists, which
+ * defeats the surface. Keywords are how a command is found by what it does rather
+ * than by what it is called, and they are the caller's because only the caller
+ * knows the other words for it.
+ */
+export type CommandItem = {
+    /** A stable key. */
+    id: string;
+    /** The words on the row. */
+    label: string;
+    /** A second line, usually the shortcut. The caller's word. */
+    hint?: string;
+    /** Words that should also find this command. */
+    keywords?: readonly string[];
+    /** What happens when it is chosen. */
+    onSelect: () => void;
+};
+/** A named set of commands, kept together in the list. */
+export type CommandGroup = {
+    id: string;
+    /** The words on the group heading. */
+    label: string;
+    items: readonly CommandItem[];
+};
+/** The props the Command palette accepts. */
+export interface CommandPaletteProps {
+    /** Whether the palette is open. */
+    open: boolean;
+    /** Called when it should open or close. */
+    onOpenChange: (open: boolean) => void;
+    /**
+     * The accessible name of the palette.
+     *
+     * Required, because a palette is announced as a dialog and a reader who opened
+     * one needs to know what they opened. The name is the caller's word.
+     */
+    label: string;
+    /** The accessible name of the search field. */
+    inputLabel: string;
+    /** The placeholder in the search field. The caller's word. */
+    placeholder?: string;
+    /** The commands, grouped. */
+    groups: readonly CommandGroup[];
+    /**
+     * The commands shown before anything is typed.
+     *
+     * A palette that opens onto an empty list makes a reader type before they know
+     * what is available, which inverts the point of a surface whose whole purpose is
+     * to be faster than the menu it replaces. This is where recent and suggested
+     * commands go, and it is the caller's data.
+     */
+    suggest?: {
+        label: string;
+        items: readonly CommandItem[];
+    };
+    /**
+     * What a reader is told when nothing matches.
+     *
+     * `message` receives the query, so a caller can put it in their own sentence. An
+     * empty result with no words is the one state a palette must never show, because
+     * it reads as a broken surface rather than as a search that found nothing.
+     */
+    empty: {
+        message: (query: string) => string;
+        hint?: string;
+    };
+    /** Layout only. */
+    className?: string;
+}
+/**
+ * A searchable list of commands, over the Dialog this system already has.
+ *
+ * **It ranks, and that is the difference between this and a filtered menu.** A
+ * palette that filters without ordering shows every command containing the query
+ * in whatever order the groups happened to be declared, so the command you meant
+ * sits below one that merely mentions your query. Ranking by where the match falls
+ * puts it first, and the whole premise of a palette is that typing three letters
+ * is faster than navigating to it.
+ *
+ * **It is composed on the Dialog rather than beside it.** Focus trapping, Escape,
+ * the portal, the scroll lock and the return of focus to the trigger are five
+ * behaviours that are correct in the Dialog and would be five chances to get one
+ * wrong here. A palette that rolled its own overlay would be a second answer to
+ * all five questions, and the second answer is the one that ships the bug.
+ *
+ * **The matched run is emphasised by weight, not by a background.** A Mark is the
+ * right treatment in a list of results, where the match is the reason the row is
+ * there and a full background is the point. In a palette the match is a hint while
+ * the row's label is what the reader is reading, and a saturated background on
+ * every matched character fights the text it is inside. So the palette uses the
+ * quieter of the two, and the two surfaces are not the same surface. See the Mark
+ * documentation for the other half of that decision.
+ *
+ * **The search field keeps focus for the whole interaction.** Arrows move a
+ * highlight through the list rather than moving focus into it, so a reader can keep
+ * typing while they choose, and the highlighted row carries the state. That is the
+ * combobox pattern and it is the reason the arrows do not steal the caret.
+ */
+declare function CommandPalette({ open, onOpenChange, label, inputLabel, placeholder, groups, suggest, empty, className, }: CommandPaletteProps): import("react").JSX.Element;
+export { CommandPalette };
+//# sourceMappingURL=command-palette.d.ts.map

package/dist/components/ui/command-palette.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-palette.d.ts","sourceRoot":"","sources":["../../../src/components/ui/command-palette.tsx"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC5B,sCAAsC;IACtC,QAAQ,EAAE,MAAM,IAAI,CAAA;CACrB,CAAA;AAED,0DAA0D;AAC1D,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAA;IACV,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;CAC9B,CAAA;AAED,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,2CAA2C;IAC3C,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC;;;;;OAKG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAA;IAClB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6BAA6B;IAC7B,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;KAAE,CAAA;IAC1D;;;;;;OAMG;IACH,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5D,mBAAmB;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iBAAS,cAAc,CAAC,EACtB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,OAAO,EACP,KAAK,EACL,SAAS,GACV,EAAE,mBAAmB,+BAqPrB;AAED,OAAO,EAAE,cAAc,EAAE,CAAA"}