@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/components/combobox.js

@@ -0,0 +1,294 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Command as Cmdk } from "cmdk";
+import { Check, ChevronsUpDown, Plus, Search, X } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { FieldContextReset, useFieldContext, useFieldControl } from "../lib/field-context.js";
+import { useLabels } from "../lib/labels.js";
+import { useLocale } from "../lib/locale.js";
+import { cmdkFilter, foldText, highlightParts } from "../lib/text.js";
+import { useAsyncList } from "../lib/use-async-list.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { controlVariants, itemSlots, itemVariants } from "../lib/variants.js";
+import { Badge } from "./badge.js";
+import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from "./popover.js";
+import { Spinner } from "./spinner.js";
+const comboboxLabels = {
+    placeholder: "Select…",
+    placeholderMultiple: "Add…",
+    search: "Search…",
+    empty: "No results",
+    create: "Create “{query}”",
+    results: "{count, plural, =0 {No results} one {# result} other {# results}}",
+    error: "Couldn't load results.",
+    retry: "Try again",
+    loading: "Loading…",
+    loadMore: "Show more results",
+    clear: "Clear selection",
+    selected: "Selected",
+    selectedCount: "{count, plural, one {# selected} other {# selected}}",
+    remove: "Remove {label}",
+    more: "+{count}",
+    moreLabel: "{count, plural, one {# more selected} other {# more selected}}",
+};
+const asOption = (item) => item;
+const defaultGetValue = (item) => String(asOption(item).value ?? "");
+const defaultGetLabel = (item) => String(asOption(item).label ?? asOption(item).value ?? "");
+const CREATE_VALUE = "\u0000create";
+const MORE_VALUE = "\u0000more";
+function Highlight({ text, query, locale }) {
+    if (!query.trim())
+        return _jsx(_Fragment, { children: text });
+    return (_jsx(_Fragment, { children: highlightParts(text, query, locale).map((p, i) => p.match ? (_jsx("span", { "data-match": "", className: "font-semibold text-fg", children: p.text }, i)) : (_jsx(React.Fragment, { children: p.text }, i))) }));
+}
+function ComboboxInner(props, ref) {
+    const { items: staticItems, loadItems, debounce, getValue = defaultGetValue, getLabel = defaultGetLabel, getKeywords = (item) => asOption(item).keywords, getDisabled = (item) => Boolean(asOption(item).disabled), getGroup = (item) => asOption(item).group, renderItem, onCreate, selectedItems, placeholder, searchPlaceholder, emptyMessage, size = "md", variant = "default", mode = "popover", loading: staticLoading, name: nameProp, disabled: disabledProp, invalid, readOnly: readOnlyProp, required, open: openProp, defaultOpen, onOpenChange, closeOnSelect, id, className, contentClassName, listClassName, labels, multiple, clearable, maxVisibleChips, } = props;
+    const t = useLabels("combobox", comboboxLabels, labels);
+    const { locale } = useLocale();
+    const field = useFieldContext();
+    const control = useFieldControl({
+        id,
+        disabled: disabledProp,
+        readOnly: readOnlyProp,
+        required,
+        "aria-invalid": invalid ? true : undefined,
+        "aria-label": props["aria-label"],
+        "aria-labelledby": props["aria-labelledby"],
+        "aria-describedby": props["aria-describedby"],
+    });
+    const disabled = Boolean(control.disabled);
+    const readOnly = Boolean(control.readOnly);
+    const name = nameProp ?? field?.name;
+    const inert = disabled || readOnly;
+    /* ---------------------------------------------------------------- value */
+    const toArray = (v) => v === undefined ? undefined : Array.isArray(v) ? v : v === null ? [] : [v];
+    const known = React.useRef(new Map());
+    for (const item of selectedItems ?? [])
+        known.current.set(getValue(item), item);
+    for (const item of staticItems ?? [])
+        known.current.set(getValue(item), item);
+    const [values, setValues] = useControllableState({
+        value: toArray(props.value),
+        defaultValue: () => toArray(props.defaultValue) ?? [],
+        onChange: (next) => {
+            const resolved = next.map((v) => known.current.get(v)).filter((x) => x !== undefined);
+            if (multiple)
+                props.onValueChange?.(next, resolved);
+            else
+                props.onValueChange?.(next[0] ?? null, resolved[0] ?? null);
+        },
+        name: "Combobox",
+    });
+    const [open, setOpenState] = useControllableState({ value: openProp, defaultValue: defaultOpen ?? false, onChange: onOpenChange, name: "Combobox" });
+    const setOpen = (next) => {
+        if (next && inert)
+            return;
+        setOpenState(next);
+        if (!next)
+            setQuery("");
+    };
+    const [query, setQuery] = React.useState("");
+    const [creating, setCreating] = React.useState(false);
+    /* ---------------------------------------------------------------- items */
+    const async = useAsyncList({ load: loadItems, query, debounce, enabled: mode === "inline" || open });
+    for (const item of async.items)
+        known.current.set(getValue(item), item);
+    const visible = React.useMemo(() => {
+        if (loadItems)
+            return async.items;
+        const list = staticItems ?? [];
+        const q = query.trim();
+        if (!q)
+            return list;
+        const score = cmdkFilter(locale);
+        return list
+            .map((item, index) => ({ item, index, s: score(getLabel(item), q, getKeywords(item)) }))
+            .filter((x) => x.s > 0)
+            .sort((a, b) => b.s - a.s || a.index - b.index)
+            .map((x) => x.item);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [loadItems, async.items, staticItems, query, locale]);
+    const groups = React.useMemo(() => {
+        const out = [];
+        const byKey = new Map();
+        for (const item of visible) {
+            const g = getGroup(item);
+            const key = g ?? "";
+            let entry = byKey.get(key);
+            if (!entry) {
+                entry = { label: g, items: [] };
+                byKey.set(key, entry);
+                out.push(entry);
+            }
+            entry.items.push(item);
+        }
+        return out;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [visible]);
+    const loading = loadItems ? async.loading : Boolean(staticLoading);
+    const trimmed = query.trim();
+    const folded = foldText(trimmed, locale);
+    const exactMatch = trimmed !== "" && [...visible, ...known.current.values()].some((item) => foldText(getLabel(item), locale) === folded);
+    const showCreate = Boolean(onCreate) && trimmed !== "" && !exactMatch && !loading;
+    /* ---------------------------------------------------------------- actions */
+    const shouldClose = closeOnSelect ?? !multiple;
+    const triggerRef = React.useRef(null);
+    const chipsRef = React.useRef(null);
+    const select = (value) => {
+        if (inert)
+            return;
+        if (multiple)
+            setValues((prev) => (prev.includes(value) ? prev.filter((v) => v !== value) : [...prev, value]));
+        else
+            setValues([value]);
+        if (multiple)
+            setQuery("");
+        if (shouldClose && mode === "popover")
+            setOpen(false);
+    };
+    const removeAt = (index, refocus = true) => {
+        if (inert)
+            return;
+        setValues((prev) => prev.filter((_, i) => i !== index));
+        if (!refocus)
+            return;
+        requestAnimationFrame(() => {
+            // Focus the previous chip (or the first one), else the trigger.
+            const buttons = chipsRef.current?.querySelectorAll('[data-slot="chip-remove"]');
+            (buttons?.[Math.max(0, index - 1)] ?? triggerRef.current)?.focus();
+        });
+    };
+    const create = async () => {
+        if (!onCreate || creating)
+            return;
+        setCreating(true);
+        try {
+            const created = await onCreate(trimmed);
+            if (created !== undefined && created !== null) {
+                known.current.set(getValue(created), created);
+                select(getValue(created));
+            }
+            setQuery("");
+        }
+        finally {
+            setCreating(false);
+        }
+    };
+    /* ---------------------------------------------------------------- panel */
+    const itemSize = size === "sm" ? "sm" : "md";
+    const showCount = trimmed !== "" || Boolean(loadItems);
+    // cmdk names its input with its own <label>; in inline mode reuse the Field's label text.
+    const [fieldLabelText, setFieldLabelText] = React.useState();
+    const fieldLabelId = field?.labelId;
+    React.useEffect(() => {
+        if (!fieldLabelId)
+            return;
+        setFieldLabelText(document.getElementById(fieldLabelId)?.textContent?.replace(/\*$/, "").trim() || undefined);
+    }, [fieldLabelId]);
+    const panelName = props["aria-label"] ?? fieldLabelText ?? t("search");
+    const inputName = mode === "inline"
+        ? (props["aria-label"] ?? fieldLabelText ?? searchPlaceholder ?? t("search"))
+        : (searchPlaceholder ?? t("search"));
+    const panel = (_jsxs(Cmdk, { shouldFilter: false, loop: true, label: inputName, "data-slot": "combobox-panel", className: "flex min-h-0 flex-col", children: [_jsxs("div", { className: "flex items-center gap-2 border-b border-line px-3", "data-slot": "combobox-search", children: [_jsx(Search, { "aria-hidden": true, className: "size-4 shrink-0 text-fg-subtle" }), _jsx(Cmdk.Input, { value: query, onValueChange: setQuery, placeholder: searchPlaceholder ?? t("search"), ...(mode === "inline" ? { "aria-describedby": control["aria-describedby"], "aria-invalid": control["aria-invalid"] } : {}), disabled: disabled, readOnly: readOnly, onKeyDown: (e) => {
+                            if (e.key === "Backspace" && query === "" && multiple && values.length > 0) {
+                                e.preventDefault();
+                                removeAt(values.length - 1, false);
+                            }
+                        }, className: cn("h-(--control-h) min-w-0 flex-1 bg-transparent text-sm text-fg outline-none placeholder:text-fg-subtle disabled:cursor-not-allowed", size === "sm" && "h-[calc(var(--control-h)-0.25rem)] text-[13px]") }), loading || creating ? _jsx(Spinner, { size: "xs", tone: "muted" }) : null] }), _jsxs(Cmdk.List, { label: inputName, "aria-busy": loading || undefined, 
+                // Keep focus in the search box when an option is clicked.
+                onMouseDown: (e) => {
+                    if (!e.target.closest("button"))
+                        e.preventDefault();
+                }, className: cn("max-h-72 overflow-y-auto overscroll-contain p-1 scroll-py-1", listClassName), onScroll: (e) => {
+                    const el = e.currentTarget;
+                    if (async.hasMore && el.scrollTop + el.clientHeight >= el.scrollHeight - 48)
+                        async.loadMore();
+                }, children: [async.error && !loading ? (_jsxs("div", { role: "alert", className: "flex items-center justify-between gap-3 px-2 py-2 text-[13px] text-danger", children: [_jsx("span", { children: t("error") }), _jsx("button", { type: "button", onClick: async.reload, className: "rounded-ui-sm px-1.5 py-0.5 font-medium text-fg underline-offset-2 hover:underline focus-ring", children: t("retry") })] })) : null, loading && visible.length === 0 ? (_jsxs(Cmdk.Loading, { label: t("loading"), className: "flex items-center gap-2 px-2 py-2 text-[13px] text-fg-muted", children: [_jsx(Spinner, { size: "xs", tone: "muted" }), t("loading")] })) : null, groups.map((group, gi) => {
+                        const rows = group.items.map((item) => {
+                            const value = getValue(item);
+                            const label = getLabel(item);
+                            const selected = values.includes(value);
+                            const highlight = _jsx(Highlight, { text: label, query: trimmed, locale: locale });
+                            const opt = asOption(item);
+                            return (_jsxs(Cmdk.Item, { value: value, disabled: getDisabled(item), onSelect: () => select(value), "data-checked": selected ? "" : undefined, className: cn(itemVariants({ size: itemSize }), multiple ? "ps-2" : "pe-8"), children: [multiple ? (_jsx("span", { "aria-hidden": true, className: cn("flex size-4 shrink-0 items-center justify-center rounded-[4px] border transition-colors", selected ? "border-transparent bg-accent text-accent-fg" : "border-field-border-hover"), children: selected ? _jsx(Check, { strokeWidth: 3, className: "size-3!" }) : null })) : null, renderItem ? (_jsx("span", { className: "flex min-w-0 flex-1 items-center gap-2", children: renderItem(item, { selected, query: trimmed, highlight }) })) : (_jsxs(_Fragment, { children: [opt.icon ? _jsx("span", { className: cn(itemSlots.icon, "flex items-center justify-center"), children: opt.icon }) : null, _jsxs("span", { className: "grid min-w-0 flex-1", children: [_jsx("span", { className: "truncate", children: highlight }), opt.description ? _jsx("span", { className: cn(itemSlots.description, "truncate"), children: opt.description }) : null] })] })), !multiple ? (_jsx("span", { className: "absolute end-2 flex size-4 items-center justify-center text-accent-ink", children: selected ? _jsx(Check, { "aria-hidden": true, strokeWidth: 2.5, className: "size-4" }) : null })) : null, selected ? _jsxs("span", { className: "sr-only", children: [", ", t("selected")] }) : null] }, value));
+                        });
+                        return group.label ? (_jsx(Cmdk.Group, { heading: group.label, className: cn(gi > 0 && "mt-1 border-t border-line pt-1", "[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:pt-2 [&_[cmdk-group-heading]]:pb-1 [&_[cmdk-group-heading]]:text-[11px] [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:tracking-[0.04em] [&_[cmdk-group-heading]]:text-fg-subtle"), children: rows }, group.label)) : (_jsx(React.Fragment, { children: rows }, `_${gi}`));
+                    }), showCreate ? (_jsxs(Cmdk.Item, { value: CREATE_VALUE, onSelect: create, disabled: creating, className: cn(itemVariants({ size: itemSize }), "text-fg"), children: [_jsx(Plus, { "aria-hidden": true, className: "text-fg-muted" }), _jsx("span", { className: "truncate", children: t("create", { query: trimmed }) })] })) : null, async.hasMore ? (_jsxs(Cmdk.Item, { value: MORE_VALUE, onSelect: async.loadMore, className: cn(itemVariants({ size: itemSize }), "justify-center text-fg-muted"), children: [async.loadingMore ? _jsx(Spinner, { size: "xs", tone: "muted" }) : null, t("loadMore")] })) : null, !loading && visible.length === 0 && !showCreate && !async.error ? (_jsx("div", { "data-slot": "combobox-empty", className: "px-2 py-6 text-center text-[13px] text-fg-subtle", children: emptyMessage ?? t("empty") })) : null] }), _jsx("span", { "aria-live": "polite", className: "sr-only", children: showCount && !loading ? t("results", { count: visible.length }) : "" })] }));
+    const hidden = name ? (multiple ? (values.map((v) => _jsx("input", { type: "hidden", name: name, value: v }, v))) : (_jsx("input", { type: "hidden", name: name, value: values[0] ?? "" }))) : null;
+    /* ---------------------------------------------------------------- inline */
+    if (mode === "inline") {
+        return (_jsxs("div", { "data-slot": "combobox", "data-mode": "inline", "aria-disabled": disabled || undefined, className: cn("flex w-full min-w-0 flex-col overflow-hidden rounded-ui border border-field-border bg-field", "has-[input:focus-visible]:border-ring has-[input:focus-visible]:shadow-[0_0_0_3px_var(--accent-soft)]", control["aria-invalid"] && "border-danger", disabled && "opacity-50", className), children: [_jsx(FieldContextReset, { children: panel }), multiple && values.length > 0 ? (_jsxs("div", { className: "flex items-center justify-between gap-2 border-t border-line px-3 py-1.5 text-xs text-fg-muted", children: [_jsx("span", { className: "tabular", children: t("selectedCount", { count: values.length }) }), clearable && !inert ? (_jsx("button", { type: "button", onClick: () => setValues([]), className: "rounded-ui-sm px-1 font-medium text-fg hover:underline focus-ring", children: t("clear") })) : null] })) : null, hidden] }));
+    }
+    /* ---------------------------------------------------------------- popover */
+    const selectedEntries = values.map((v) => ({ value: v, item: known.current.get(v) }));
+    const labelOf = (e) => (e.item ? getLabel(e.item) : e.value);
+    const shown = multiple && maxVisibleChips !== undefined ? selectedEntries.slice(0, maxVisibleChips) : selectedEntries;
+    const overflow = selectedEntries.length - shown.length;
+    const { readOnly: _ro, required: req, ...buttonA11y } = control;
+    void _ro;
+    const triggerButton = (_jsx(PopoverTrigger, { asChild: true, children: _jsxs("button", { ref: (node) => {
+                triggerRef.current = node;
+                if (typeof ref === "function")
+                    ref(node);
+                else if (ref)
+                    ref.current = node;
+            }, type: "button", role: "combobox", "aria-expanded": open, "aria-required": req || undefined, "aria-readonly": readOnly || undefined, "aria-busy": loading || undefined, "data-placeholder": values.length === 0 ? "" : undefined, ...buttonA11y, onKeyDown: (e) => {
+                if (!multiple || inert || open)
+                    return;
+                if ((e.key === "Backspace" || e.key === "ArrowLeft") && values.length > 0) {
+                    e.preventDefault();
+                    const buttons = chipsRef.current?.querySelectorAll('[data-slot="chip-remove"]');
+                    buttons?.[buttons.length - 1]?.focus();
+                }
+            }, className: cn(multiple
+                ? "flex h-[calc(var(--control-h)-0.5rem)] min-w-24 flex-1 items-center rounded-ui-sm px-1.5 text-start text-fg-subtle outline-none focus-visible:outline-none"
+                : cn(controlVariants({ size, variant: variant === "pill" ? "default" : variant, pill: variant === "pill" }), "justify-between text-start data-placeholder:text-fg-subtle", clearable && values.length > 0 && !inert && (size === "sm" ? "pe-12" : "pe-14"), readOnly && "border-dashed", className), inert && "cursor-not-allowed"), children: [multiple ? (_jsx("span", { className: "truncate", children: values.length === 0 ? (placeholder ?? t("placeholder")) : readOnly ? "" : (placeholder ?? t("placeholderMultiple")) })) : (_jsx("span", { className: "min-w-0 truncate", children: selectedEntries[0] ? labelOf(selectedEntries[0]) : (placeholder ?? t("placeholder")) })), !multiple ? (loading && !open ? (_jsx(Spinner, { size: "sm", tone: "muted" })) : readOnly ? null : (_jsx(ChevronsUpDown, { "aria-hidden": true, className: "shrink-0 text-fg-subtle" }))) : null] }) }));
+    return (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [multiple ? (_jsx(PopoverAnchor, { asChild: true, children: _jsxs("div", { "data-slot": "combobox", "data-multiple": "", "data-readonly": readOnly ? "" : undefined, "aria-invalid": control["aria-invalid"] || undefined, onPointerDown: (e) => {
+                        if (e.target === e.currentTarget && !inert) {
+                            e.preventDefault();
+                            triggerRef.current?.focus();
+                            setOpen(!open);
+                        }
+                    }, className: cn(controlVariants({ size, variant: variant === "pill" ? "default" : variant, pill: variant === "pill", multiline: true }), "min-h-(--control-h) flex-wrap gap-1 py-1 ps-1.5 pe-2", size === "sm" && "min-h-[calc(var(--control-h)-0.5rem)] py-0.5", disabled && "opacity-50", className), children: [shown.length > 0 ? (_jsxs("ul", { ref: chipsRef, "aria-label": t("selected"), className: "contents", onKeyDown: (e) => {
+                                const buttons = [...(chipsRef.current?.querySelectorAll('[data-slot="chip-remove"]') ?? [])];
+                                const i = buttons.indexOf(document.activeElement);
+                                if (i < 0)
+                                    return;
+                                const rtl = getComputedStyle(e.currentTarget).direction === "rtl";
+                                const prev = rtl ? "ArrowRight" : "ArrowLeft";
+                                const next = rtl ? "ArrowLeft" : "ArrowRight";
+                                if (e.key === prev && i > 0) {
+                                    e.preventDefault();
+                                    buttons[i - 1].focus();
+                                }
+                                else if (e.key === next) {
+                                    e.preventDefault();
+                                    (buttons[i + 1] ?? triggerRef.current)?.focus();
+                                }
+                            }, children: [shown.map((entry, i) => (_jsx("li", { className: "flex min-w-0", children: _jsx(Badge, { size: size === "lg" ? "lg" : "md", shape: "square", className: "max-w-56 min-w-0", onRemove: inert ? undefined : () => removeAt(i), removeLabel: t("remove", { label: labelOf(entry) }), children: _jsx("span", { className: "truncate", children: labelOf(entry) }) }) }, entry.value))), overflow > 0 ? (_jsx("li", { className: "flex", children: _jsxs(Badge, { size: size === "lg" ? "lg" : "md", shape: "square", tone: "outline", className: "tabular", children: [_jsx("span", { "aria-hidden": true, children: t("more", { count: overflow }) }), _jsx("span", { className: "sr-only", children: t("moreLabel", { count: overflow }) })] }) })) : null] })) : null, triggerButton, clearable && values.length > 0 && !inert ? (_jsx("button", { type: "button", "aria-label": t("clear"), onClick: () => {
+                                setValues([]);
+                                triggerRef.current?.focus();
+                            }, className: "inline-flex size-6 shrink-0 items-center justify-center rounded-full text-fg-subtle hover:bg-hover hover:text-fg focus-ring [&_svg]:size-3.5", children: _jsx(X, { "aria-hidden": true }) })) : null, readOnly ? null : (_jsx("span", { "aria-hidden": true, className: "pointer-events-none inline-flex size-6 shrink-0 items-center justify-center text-fg-subtle [&_svg]:size-4", children: _jsx(ChevronsUpDown, {}) })), hidden] }) })) : (_jsxs("div", { "data-slot": "combobox", className: "relative w-full min-w-0", children: [triggerButton, clearable && values.length > 0 && !inert ? (_jsx("button", { type: "button", "aria-label": t("clear"), onClick: () => {
+                            setValues([]);
+                            triggerRef.current?.focus();
+                        }, className: cn("absolute top-1/2 inline-flex -translate-y-1/2 items-center justify-center rounded-full text-fg-subtle transition-colors hover:bg-hover hover:text-fg focus-ring", size === "sm" ? "end-7 size-5 [&_svg]:size-3" : "end-8 size-6 [&_svg]:size-3.5"), children: _jsx(X, { "aria-hidden": true }) })) : null, hidden] })), _jsx(PopoverContent, { size: "trigger", padded: false, align: "start", "aria-label": panelName, className: cn("min-w-60 overflow-hidden", contentClassName), onOpenAutoFocus: (e) => {
+                    // Focus the search box, not the first focusable in the panel.
+                    e.preventDefault();
+                    e.currentTarget?.querySelector("[cmdk-input]")?.focus();
+                }, children: _jsx(FieldContextReset, { children: panel }) })] }));
+}
+/**
+ * Searchable selection — single or multiple, static or server-backed, optionally creatable:
+ * city, assignee, category, country, tags. WAI-ARIA combobox + listbox in a popover (or inline).
+ * Search folds locale characters, so "istanbul" finds "İstanbul" and "cagri" finds "Çağrı";
+ * matches are highlighted by weight, not colour (readable on glass).
+ *
+ * ```tsx
+ * <Field label="City"><Combobox name="city" items={cities} /></Field>
+ * <Combobox multiple items={labels} defaultValue={["urgent"]} maxVisibleChips={3} />
+ * <Combobox loadItems={(q, signal) => fetch(`/api/people?q=${q}`, { signal }).then((r) => r.json())} />
+ * <Combobox items={categories} onCreate={async (name) => api.createCategory(name)} />
+ * ```
+ */
+export const Combobox = React.forwardRef(ComboboxInner);

package/dist/components/command.d.ts

@@ -0,0 +1,275 @@
+import * as React from "react";
+import { Command as Cmdk } from "cmdk";
+import { type DialogProps } from "./dialog.js";
+declare const commandLabels: {
+    label: string;
+    placeholder: string;
+    empty: string;
+    noResultsFor: string;
+    results: string;
+    recent: string;
+    navigate: string;
+    select: string;
+    back: string;
+    close: string;
+    sourceError: string;
+    loading: string;
+};
+export type CommandLabels = typeof commandLabels;
+export interface CommandProps extends React.ComponentPropsWithoutRef<typeof Cmdk> {
+    labels?: Partial<CommandLabels>;
+}
+/**
+ * A searchable list of actions (WAI-ARIA combobox + listbox). Filtering folds text for the
+ * current locale, so "istanbul" finds "İstanbul" and "isik" finds "ışık".
+ *
+ * ```tsx
+ * <Command>
+ *   <CommandInput />
+ *   <CommandList>
+ *     <CommandEmpty />
+ *     <CommandGroup heading="Actions">
+ *       <CommandItem icon={<FilePlus2 />} shortcut="mod+shift+n" onSelect={newPost}>New post</CommandItem>
+ *     </CommandGroup>
+ *   </CommandList>
+ * </Command>
+ * ```
+ */
+export declare const Command: React.ForwardRefExoticComponent<CommandProps & React.RefAttributes<HTMLDivElement>>;
+export interface CommandInputProps extends React.ComponentPropsWithoutRef<typeof Cmdk.Input> {
+    /** Breadcrumb chip before the input (the current sub-page). */
+    chip?: React.ReactNode;
+    /** Trailing slot (a spinner, a filter, a close hint). */
+    end?: React.ReactNode;
+    labels?: Partial<CommandLabels>;
+}
+/** The search field. Placeholder from the dictionary (`command.placeholder`). */
+export declare const CommandInput: React.ForwardRefExoticComponent<CommandInputProps & React.RefAttributes<HTMLInputElement>>;
+/** The scrolling listbox. */
+export declare const CommandList: React.ForwardRefExoticComponent<Omit<{
+    children?: React.ReactNode;
+} & Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, keyof React.HTMLAttributes<HTMLDivElement> | "key"> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, keyof React.HTMLAttributes<HTMLDivElement> | "asChild" | "key"> & {
+    label?: string;
+} & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/** Shown when nothing matches. Default text from the dictionary (`command.empty`). */
+export declare const CommandEmpty: React.ForwardRefExoticComponent<Omit<{
+    children?: React.ReactNode;
+} & Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, keyof React.HTMLAttributes<HTMLDivElement> | "key"> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, keyof React.HTMLAttributes<HTMLDivElement> | "asChild" | "key"> & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    labels?: Partial<CommandLabels>;
+} & React.RefAttributes<HTMLDivElement>>;
+/** A loading row (async results). */
+export declare const CommandLoading: React.ForwardRefExoticComponent<Omit<{
+    children?: React.ReactNode;
+} & Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, keyof React.HTMLAttributes<HTMLDivElement> | "key"> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, keyof React.HTMLAttributes<HTMLDivElement> | "asChild" | "key"> & {
+    progress?: number;
+    label?: string;
+} & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    labels?: Partial<CommandLabels>;
+} & React.RefAttributes<HTMLDivElement>>;
+/** A titled group of items. */
+export declare const CommandGroup: React.ForwardRefExoticComponent<Omit<{
+    children?: React.ReactNode;
+} & Omit<Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, keyof React.HTMLAttributes<HTMLDivElement> | "key"> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, keyof React.HTMLAttributes<HTMLDivElement> | "asChild" | "key">, "value" | "heading"> & {
+    heading?: React.ReactNode;
+    value?: string;
+    forceMount?: boolean;
+} & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/** A hairline between groups. */
+export declare const CommandSeparator: React.ForwardRefExoticComponent<Omit<Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, keyof React.HTMLAttributes<HTMLDivElement> | "key"> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, keyof React.HTMLAttributes<HTMLDivElement> | "asChild" | "key"> & {
+    alwaysRender?: boolean;
+} & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export interface CommandItemProps extends React.ComponentPropsWithoutRef<typeof Cmdk.Item> {
+    icon?: React.ReactNode;
+    /** Second line under the label. */
+    description?: React.ReactNode;
+    /** `"mod+shift+n"` or `["mod","shift","n"]` — display only. */
+    shortcut?: string | string[];
+    /** Trailing meta (an app badge, a count). */
+    badge?: React.ReactNode;
+    /** Trailing chevron (opens a sub-page). */
+    chevron?: boolean;
+    /** Spinner in place of the icon while the action runs. */
+    loading?: boolean;
+}
+/** One selectable row. Highlighted with the arrow keys; Enter or click runs `onSelect`. */
+export declare const CommandItem: React.ForwardRefExoticComponent<CommandItemProps & React.RefAttributes<HTMLDivElement>>;
+/** Shortcut keycaps at the end of an item. */
+export declare function CommandShortcut({ keys, className }: {
+    keys: string | string[];
+    className?: string;
+}): React.JSX.Element;
+export interface CommandDialogProps extends DialogProps {
+    /** `md` 560px, `lg` 680px. Default `"lg"`. */
+    size?: "md" | "lg";
+    /** Hidden dialog title. Default "Command palette" (`command.label`). */
+    title?: string;
+    /** Props for the inner `Command` (filter, shouldFilter, value…). */
+    commandProps?: Omit<CommandProps, "children">;
+    className?: string;
+    labels?: Partial<CommandLabels>;
+}
+/**
+ * Command inside a top-anchored dialog (fullscreen on phones). Focus goes to the input; Esc closes
+ * and returns focus to whatever opened it.
+ *
+ * ```tsx
+ * const [open, setOpen] = React.useState(false);
+ * useHotkeys("mod+k", () => setOpen((o) => !o));
+ * <CommandDialog open={open} onOpenChange={setOpen}>
+ *   <CommandInput />
+ *   <CommandList>…</CommandList>
+ * </CommandDialog>
+ * ```
+ */
+export declare function CommandDialog({ size, title, commandProps, className, labels, children, ...dialogProps }: CommandDialogProps): React.JSX.Element;
+export interface CommandContext {
+    /** Navigate through the app router (absolute URLs do a full navigation). */
+    navigate: (href: string) => void;
+    /** Close the palette. */
+    close: () => void;
+    /** The query the action was picked with. */
+    query: string;
+    can: (permission: string) => boolean;
+}
+export interface CommandAction {
+    /** Module-prefixed and unique: `"cms.post.new"`. */
+    id: string;
+    title: string;
+    subtitle?: string;
+    /** Group heading: "Actions", "Go to", "Posts"… Default "Actions". */
+    group?: string;
+    icon?: React.ComponentType<{
+        className?: string;
+    }> | React.ReactNode;
+    /** Synonyms: `["article", "entry"]`. */
+    keywords?: string[];
+    /** `"mod+shift+n"` or `["mod","shift","n"]`. With `global: true` it also works while the palette is closed. */
+    shortcut?: string | string[];
+    global?: boolean;
+    /** Navigates via the app router. */
+    href?: string;
+    /** Runs the action. Return a promise to keep the palette open with a spinner until it settles. */
+    perform?: (ctx: CommandContext) => unknown;
+    /** Opens a sub-page with these commands (or loads them). */
+    children?: CommandAction[] | (() => Promise<CommandAction[]>);
+    /** Hidden unless `can(permission)` (all of them for an array). */
+    permission?: string | string[];
+    /** Contextual: only listed while this returns true. */
+    when?: (ctx: CommandContext) => boolean;
+    /** Higher ranks first among equal matches. */
+    priority?: number;
+    /** App badge in multi-app shells ("CRM"). */
+    app?: string;
+}
+export interface CommandSource {
+    id: string;
+    /** Group heading for the results ("Contacts"). */
+    group: string;
+    /** Minimum query length. Default 2. */
+    minQuery?: number;
+    /** ms. Default 200. */
+    debounce?: number;
+    /** Return matching commands. Abort when `signal` fires (the query changed). */
+    search: (query: string, options: {
+        signal: AbortSignal;
+    }) => Promise<CommandAction[]>;
+}
+export interface CommandRegistry {
+    /** Adds commands; returns the remove function. Later registrations win for the same id. */
+    register: (actions: CommandAction[]) => () => void;
+    registerSource: (source: CommandSource) => () => void;
+    getActions: () => CommandAction[];
+    getSources: () => CommandSource[];
+    subscribe: (listener: () => void) => () => void;
+}
+/**
+ * A command store (`useSyncExternalStore`). App shells create one from their app definitions;
+ * pages add to it with `useRegisterCommands`.
+ */
+export declare function createCommandRegistry(init?: {
+    actions?: CommandAction[];
+    sources?: CommandSource[];
+}): CommandRegistry;
+export interface CommandProviderProps {
+    /** Use an existing registry (e.g. one built from app definitions). Default: a new one. */
+    registry?: CommandRegistry;
+    /** Static commands added for the provider's lifetime. */
+    actions?: CommandAction[];
+    sources?: CommandSource[];
+    /** Toggle shortcut. Default `"mod+k"`; `false` disables it. */
+    shortcut?: string | false;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    children: React.ReactNode;
+}
+/**
+ * Holds the command registry, the palette's open state and the single global `keydown` listener
+ * (`mod+k` plus commands marked `global`). Inside inputs only shortcuts with `mod` fire. App shell
+ * mounts one; mount it yourself for a standalone palette.
+ */
+export declare function CommandProvider({ registry: registryProp, actions, sources, shortcut, open: openProp, defaultOpen, onOpenChange, children }: CommandProviderProps): React.JSX.Element;
+/** The registry of the nearest `CommandProvider` (or `null`). */
+export declare function useCommandRegistry(): CommandRegistry | null;
+/**
+ * Adds commands while the calling component is mounted (page-scoped: "Publish" only exists in the
+ * editor). `perform` always calls the latest closure. Re-registers when ids / titles change or `deps` change.
+ *
+ * ```tsx
+ * useRegisterCommands([{ id: "cms.post.publish", title: "Publish post", group: "This post", perform: publish }]);
+ * ```
+ */
+export declare function useRegisterCommands(actions: CommandAction[], deps?: React.DependencyList): void;
+/** Adds an async search source (record search) while mounted. */
+export declare function useCommandSource(source: CommandSource | null | undefined): void;
+export interface CommandPaletteControls {
+    /** Open the palette, optionally on the sub-page of a command with `children`. */
+    open: (pageId?: string) => void;
+    close: () => void;
+    toggle: () => void;
+    isOpen: boolean;
+    /** `false` when there is no `CommandProvider` above (calls are no-ops). */
+    available: boolean;
+}
+/** Open / close the palette from anywhere (a search button, an empty state). */
+export declare function useCommandPalette(): CommandPaletteControls;
+export interface CommandPaletteProps {
+    /** Default `"lg"`. */
+    size?: "md" | "lg";
+    placeholder?: string;
+    /** Show recently used commands first when the query is empty. Default `true`. */
+    recents?: boolean;
+    /** Footer hint bar (↑↓ navigate · ↵ select · ⌫ back · esc close). Default `true`. */
+    footer?: boolean;
+    /** Group order; unlisted groups follow in first-seen order. */
+    groupOrder?: string[];
+    labels?: Partial<CommandLabels>;
+}
+/**
+ * The ready-made ⌘K palette wired to the nearest `CommandProvider`: ranked local commands,
+ * recents, async sources (debounced, aborted on every keystroke), sub-pages with a breadcrumb chip
+ * (Backspace on an empty input goes back), a spinner while an action runs, and a polite result count.
+ * App shell mounts one for you.
+ */
+export declare function CommandPalette({ size, placeholder, recents: showRecents, footer, groupOrder, labels }: CommandPaletteProps): React.JSX.Element;
+export {};