@skdx/react 0.26.0

package/dist/combobox/types.d.ts

@@ -0,0 +1,275 @@
+import type * as React from 'react';
+import type { FormValidityHandle } from '../utils/formControl.js';
+import type { PopperContentProps } from '../utils/popper.js';
+import type { PortalProps } from '../utils/portal.js';
+import type { PrimitivePropsWithRef } from '../utils/primitive.js';
+import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.js';
+/**
+ * How a {@link Combobox} decides which Items to show. `'manual'` filters
+ * nothing — the consumer renders only the matches, which is what async or
+ * server-side search needs. A predicate moves filtering inside the component.
+ */
+export type ComboboxFilter = 'manual' | ((itemText: string, inputValue: string) => boolean);
+/** @internal What one registered {@link ComboboxItem} contributes to the root's collection. */
+export interface ComboboxItemEntry {
+    /** Identifier committed to the root's value when this option is chosen. */
+    value: string;
+    /** The item's `textValue`, or its rendered text — matched by `filter` and written back into the input. */
+    text: string;
+}
+/** @internal Shared state distributed from {@link Combobox} to its parts via context. Not part of the public API. */
+export interface ComboboxContextValue {
+    inputRef: React.RefObject<HTMLInputElement | null>;
+    contentRef: React.RefObject<HTMLDivElement | null>;
+    contentId: string;
+    /** Whether more than one option can be selected. */
+    multiple: boolean;
+    /** Every selected value, normalised to an array whether or not `multiple`. */
+    selectedValues: string[];
+    /** Whether one option value is currently selected. */
+    isSelected: (value: string) => boolean;
+    /**
+     * Commits an option: replaces the selection, writes `text` into the input
+     * and closes — or, when `multiple`, toggles it within the selection, clears
+     * the draft text, and leaves the listbox open.
+     */
+    selectItem: (value: string, text: string) => void;
+    inputValue: string;
+    onInputValueChange: (value: string) => void;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    activeId: string | null;
+    setActiveId: (id: string | null) => void;
+    /** Opens the listbox and, once its items are mounted, highlights the first (or last) one. */
+    openWithHighlight: (edge: 'first' | 'last') => void;
+    itemCount: number;
+    registerItem: (id: string, entry: ComboboxItemEntry) => void;
+    unregisterItem: (id: string) => void;
+    /** The registered entry behind an option id, for committing the virtually-focused option. */
+    getItem: (id: string) => ComboboxItemEntry | undefined;
+    /** Whether an item with this text survives the current `filter` and draft text. */
+    matchesFilter: (itemText: string) => boolean;
+    invalid: boolean;
+    readOnly: boolean;
+    loading: boolean;
+    allowCustomValue: boolean;
+    required: boolean;
+}
+/**
+ * What {@link Combobox}'s forwarded ref carries. The root renders no DOM of
+ * its own, so the ref is these two constraint-validation methods and nothing
+ * else — `React.useRef<ComboboxHandle>(null)`.
+ */
+export type ComboboxHandle = FormValidityHandle;
+/** Props for the {@link Combobox} root. */
+export interface ComboboxProps {
+    /**
+     * The `ComboboxInput`/`ComboboxPortal` parts, rendered as children — `Combobox` itself renders no DOM.
+     * @default undefined — renders nothing without children.
+     */
+    children?: React.ReactNode;
+    /**
+     * Selected option's value, for controlled usage — a `string[]` when
+     * `multiple`, a `string` otherwise. Pair with `onValueChange`.
+     * @default undefined — uncontrolled, tracks its own selected value internally.
+     */
+    value?: string | string[];
+    /**
+     * Initially selected option's value, for uncontrolled usage. Same shape as
+     * `value`: a `string[]` when `multiple`.
+     * @default undefined — no option selected initially.
+     */
+    defaultValue?: string | string[];
+    /**
+     * Fires with the new value whenever an option is chosen, controlled or not —
+     * the whole `string[]` when `multiple`, not the toggled option.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string | string[]) => void;
+    /**
+     * Allows more than one option to be selected: `value` becomes a `string[]`,
+     * the listbox gets `aria-multiselectable`, and committing an option toggles
+     * it, clears the draft text, and leaves the listbox open.
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * Lets Enter commit the draft text itself when no option is highlighted, so
+     * the combobox can create values that aren't in the list. Off by default —
+     * a combobox that silently accepts unmatched text is the wrong control for a
+     * closed set of options.
+     * @default false
+     */
+    allowCustomValue?: boolean;
+    /**
+     * How `ComboboxItem`s are filtered against the draft text. `'manual'` filters
+     * nothing: the consumer renders only the matching items, which is what async
+     * or server-side search needs. A predicate moves filtering inside the
+     * component — every item is measured (its `textValue`, or its rendered text)
+     * and the rejected ones render nothing at all, so they leave the option
+     * count, the highlight order, and `ComboboxEmpty` exactly as if the consumer
+     * had removed them.
+     * @default 'manual'
+     */
+    filter?: ComboboxFilter;
+    /**
+     * Keeps the first option highlighted whenever the (filtered) list changes
+     * while open, so Enter always has an obvious target. Off by default: it
+     * makes Enter commit something the user never pointed at, which is wrong
+     * when the draft text is itself a valid answer.
+     * @default false
+     */
+    autoHighlight?: boolean;
+    /**
+     * Marks results as in flight: `aria-busy`/`data-loading` on `ComboboxInput`
+     * and `ComboboxContent`, and no result-count announcement (a count measured
+     * mid-fetch would announce "0 results available" for every request).
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * The text field's draft text, for controlled usage. Pair with
+     * `onInputValueChange` — typically used to drive filtering of the
+     * `ComboboxItem` list, since filtering itself is left to the consumer.
+     * @default undefined — uncontrolled, tracks its own draft text internally.
+     */
+    inputValue?: string;
+    /**
+     * Initial draft text, for uncontrolled usage.
+     * @default ''
+     */
+    defaultInputValue?: string;
+    /**
+     * Fires with the new draft text as the user types, or when a selection updates it, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onInputValueChange?: (value: string) => void;
+    /**
+     * Whether the listbox popup is open, for controlled usage. Pair with `onOpenChange`.
+     * @default undefined — uncontrolled, tracks its own open state internally.
+     */
+    open?: boolean;
+    /**
+     * Initial open state, for uncontrolled usage.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * Fires with the new open state whenever it changes, controlled or not.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Fires with the new open state once the change has finished on screen —
+     * after `ComboboxContent`'s enter or exit animation ends, or as soon as it
+     * has settled when the listbox declares no animation. Use it for work that
+     * must not race the transition (measuring the panel, tearing down an
+     * expensive child); use `onOpenChange` for work that must not wait for it.
+     * @default undefined — no-op if omitted.
+     */
+    onOpenChangeComplete?: (open: boolean) => void;
+    /**
+     * Marks the combobox as invalid, exposed as `aria-invalid`/`data-invalid`
+     * on the `ComboboxInput`.
+     * @default false
+     */
+    invalid?: boolean;
+    /**
+     * Makes the `ComboboxInput` read-only, exposed as the native `readOnly`
+     * attribute plus `aria-readonly`/`data-readonly`.
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * Formats the message announced (through the shared `LiveAnnouncer`) each
+     * time the number of rendered `ComboboxItem`s changes while the listbox is
+     * open — filtering is silent for screen-reader users otherwise. Return an
+     * empty string to announce nothing.
+     * @default defaultGetResultCountLabel — e.g. `"3 results available"`
+     */
+    getResultCountLabel?: (count: number) => string;
+    /**
+     * Form field name. With it, visually-hidden native inputs mirror the
+     * *selected* value — never the draft `inputValue` — so the combobox
+     * participates in native form submission, reset and validation. A `multiple`
+     * combobox mirrors one control per selected value under the same `name`, the
+     * way a native `<select multiple>` submits repeated entries.
+     * @default undefined — submits nothing.
+     */
+    name?: string;
+    /**
+     * Marks the combobox required: `aria-required` on `ComboboxInput`, and —
+     * with `name` — native `valueMissing` while nothing is selected, reported
+     * through `checkValidity()`/`reportValidity()`.
+     * @default false
+     */
+    required?: boolean;
+}
+/** Props for {@link ComboboxInput}, the text field that drives filtering and keeps real DOM focus while the listbox is open. */
+export interface ComboboxInputProps extends Omit<PrimitivePropsWithRef<'input'>, 'value' | 'defaultValue'> {
+}
+/** Props for {@link ComboboxPortal}, which teleports its content to `document.body` while the listbox is open. */
+export interface ComboboxPortalProps extends PortalProps {
+    /**
+     * Render (and mount `ComboboxContent`) even while closed, instead of
+     * unmounting. Useful for animation libraries that need the outgoing
+     * content present in the DOM during an exit transition.
+     * @default false
+     */
+    forceMount?: boolean;
+}
+/**
+ * Props for {@link ComboboxContent}, the listbox popup. Extends
+ * {@link PopperContentProps} (`side`, `align`, `sideOffset`, `alignOffset`,
+ * `avoidCollisions`, `collisionPadding`) for floating-ui positioning relative
+ * to the input — note `ComboboxContent` defaults `side` to `'bottom'`,
+ * `align` to `'start'`, and `sideOffset` to `4`, instead of the popper base
+ * defaults (`'bottom'` / `'center'` / `0`).
+ */
+export interface ComboboxContentProps extends PopperContentProps {
+    /**
+     * Keep this listbox mounted even while closed, instead of unmounting it.
+     * @default false
+     */
+    forceMount?: boolean;
+    /**
+     * Fires when Escape is pressed while the listbox is open. Call `event.preventDefault()` to stop it from closing.
+     * @default undefined — no-op if omitted.
+     */
+    onEscapeKeyDown?: (event: KeyboardEvent) => void;
+    /**
+     * Fires on pointer-down outside the listbox and the input. Call `event.preventDefault()` to stop the listbox from closing.
+     * @default undefined — no-op if omitted.
+     */
+    onPointerDownOutside?: (event: PointerEvent) => void;
+    /**
+     * Fires when focus moves to an element outside the listbox and the input. Call `event.preventDefault()` to stop the listbox from closing. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
+     * @default undefined — no-op if omitted.
+     */
+    onFocusOutside?: (event: FocusOutsideEvent) => void;
+    /**
+     * Fires for either kind of outside interaction — pointer-down or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
+     * @default undefined — no-op if omitted.
+     */
+    onInteractOutside?: (event: InteractOutsideEvent) => void;
+}
+/** Props for a single {@link ComboboxItem} option within `ComboboxContent`. */
+export interface ComboboxItemProps extends PrimitivePropsWithRef<'div'> {
+    /** Unique identifier committed to the combobox root's value when this option is chosen. */
+    value: string;
+    /**
+     * Excludes this option from selection and pointer highlight.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text the root's `filter` predicate matches against, and the text a
+     * selection writes back into `ComboboxInput`. Only needed when the item
+     * renders more than its label (an icon, a secondary line).
+     * @default undefined — falls back to the item's rendered text content.
+     */
+    textValue?: string;
+}
+/** Props for {@link ComboboxEmpty}, shown in place of the item list when no `ComboboxItem`s are rendered (because the consumer, or `filter`, removed them all). */
+export interface ComboboxEmptyProps extends PrimitivePropsWithRef<'div'> {
+}

package/dist/command/Command.cjs

@@ -0,0 +1 @@
+"use strict";var ht=Object.create;var E=Object.defineProperty;var St=Object.getOwnPropertyDescriptor;var Mt=Object.getOwnPropertyNames;var wt=Object.getPrototypeOf,Nt=Object.prototype.hasOwnProperty;var Tt=(t,o)=>{for(var e in o)E(t,e,{get:o[e],enumerable:!0})},$=(t,o,e,s)=>{if(o&&typeof o=="object"||typeof o=="function")for(let r of Mt(o))!Nt.call(t,r)&&r!==e&&E(t,r,{get:()=>o[r],enumerable:!(s=St(o,r))||s.enumerable});return t};var f=(t,o,e)=>(e=t!=null?ht(wt(t)):{},$(o||!t||!t.__esModule?E(e,"default",{value:t,enumerable:!0}):e,t)),kt=t=>$(E({},"__esModule",{value:!0}),t);var Ht={};Tt(Ht,{Command:()=>H,CommandEmpty:()=>A,CommandGroup:()=>b,CommandInput:()=>O,CommandItem:()=>G,CommandList:()=>q,CommandLoading:()=>F,CommandSeparator:()=>V,OPTION_SELECTOR:()=>I,defaultCommandFilter:()=>D});module.exports=kt(Ht);var n=f(require("react"),1),B=require("../utils/createContext.cjs"),J=require("../utils/part.cjs"),Q=require("../utils/primitive.cjs"),T=require("../utils/useControllableState.cjs"),k=require("react/jsx-runtime"),I='[role="option"]:not([data-disabled])';function D(t,o){return t.toLowerCase().includes(o.toLowerCase())}var[Dt,p]=(0,B.createSafeContext)("Command"),H=n.forwardRef(({value:t,defaultValue:o,onValueChange:e,search:s,defaultSearch:r="",onSearchChange:a,filter:m,loading:u=!1,...d},R)=>{let h=n.useRef(null),S=n.useRef(new Map),[l,M]=n.useState(null),[w,_]=n.useState(()=>new Set),[v="",z]=(0,T.useControllableState)({prop:t,defaultProp:o??"",onChange:e}),[x="",gt]=(0,T.useControllableState)({prop:s,defaultProp:r,onChange:a}),K=n.useRef(m);K.current=m;let U=m==="manual",vt=n.useCallback(i=>{if(U||x==="")return!0;let c=K.current;return(typeof c=="function"?c:D)(i,x)},[U,x]),N=n.useCallback(i=>{M(i),z(i?S.current.get(i)?.value??"":"")},[z]);n.useEffect(()=>{if(l&&w.has(l))return;let i=h.current?.querySelector(I);N(i?.id??null)},[w,l,N]),n.useEffect(()=>{if(!v||l&&S.current.get(l)?.value===v)return;let i=h.current?.querySelector(`[role="option"][data-value="${CSS.escape(v)}"]`);i&&M(i.id)},[v,l]);let xt=n.useCallback(i=>{_(c=>{if(c.has(i))return c;let y=new Set(c);return y.add(i),y})},[]),Et=n.useCallback(i=>{_(c=>{if(!c.has(i))return c;let y=new Set(c);return y.delete(i),y}),M(c=>c===i?null:c)},[]),Lt=n.useId();return(0,k.jsx)(Dt,{listRef:h,listId:Lt,activeId:l,setActiveId:N,itemMetaRef:S,registerItem:xt,unregisterItem:Et,itemCount:w.size,search:x,setSearch:gt,matches:vt,loading:u,children:(0,k.jsx)(Q.Primitive.div,{"data-loading":u?"":void 0,...d,...(0,J.skdxPart)("command","root",d.className),ref:R})})});H.displayName="Command";var W=f(require("react"),1),X=require("../utils/part.cjs"),Y=require("../utils/primitive.cjs");var Z=require("react/jsx-runtime"),A=W.forwardRef((t,o)=>{let e=p("CommandEmpty");return e.loading||e.itemCount>0?null:(0,Z.jsx)(Y.Primitive.div,{role:"presentation",...t,...(0,X.skdxPart)("command","empty",t.className),ref:o})});A.displayName="CommandEmpty";var j=f(require("react"),1),tt=require("../utils/part.cjs"),et=require("../utils/primitive.cjs"),L=require("react/jsx-runtime"),b=j.forwardRef(({heading:t,children:o,...e},s)=>(0,L.jsxs)(et.Primitive.div,{role:"group",...e,...(0,tt.skdxPart)("command","group",e.className),ref:s,children:[t!=null?(0,L.jsx)("div",{role:"presentation",children:t}):null,o]}));b.displayName="CommandGroup";var ot=f(require("react"),1),rt=require("../utils/part.cjs"),P=require("../utils/primitive.cjs");var mt=require("react/jsx-runtime"),O=ot.forwardRef((t,o)=>{let e=p("CommandInput"),s=r=>{let a=e.listRef.current;if(!a)return;let m=Array.from(a.querySelectorAll(I));if(m.length===0)return;let d=m.findIndex(R=>R.id===e.activeId)+r;d<0&&(d=0),d>=m.length&&(d=m.length-1),e.setActiveId(m[d].id)};return(0,mt.jsx)(P.Primitive.input,{type:"text","aria-controls":e.listId,"aria-activedescendant":e.activeId??void 0,autoComplete:"off",...t,...(0,rt.skdxPart)("command","input",t.className),ref:o,onChange:(0,P.composeEventHandlers)(t.onChange,r=>{e.setSearch(r.target.value)}),onKeyDown:(0,P.composeEventHandlers)(t.onKeyDown,r=>{if(r.key==="ArrowDown")r.preventDefault(),s(1);else if(r.key==="ArrowUp")r.preventDefault(),s(-1);else if(r.key==="Enter"){if(!e.activeId)return;let a=e.itemMetaRef.current.get(e.activeId);a&&!a.disabled&&(r.preventDefault(),a.onSelect?.(a.value))}})})});O.displayName="CommandInput";var C=f(require("react"),1),nt=require("../utils/part.cjs"),g=require("../utils/primitive.cjs");var at=require("react/jsx-runtime"),G=C.forwardRef(({value:t,disabled:o,onSelect:e,...s},r)=>{let a=p("CommandItem"),m=C.useId(),u=a.activeId===m,d=a.matches(t);if(d&&a.itemMetaRef.current.set(m,{value:t,disabled:o,onSelect:e}),C.useEffect(()=>{if(d)return a.registerItem(m),()=>{a.unregisterItem(m),a.itemMetaRef.current.delete(m)}},[m,d]),!d)return null;let R=()=>{o||(a.setActiveId(m),e?.(t))};return(0,at.jsx)(g.Primitive.div,{role:"option",id:m,"data-value":t,"aria-selected":u,"data-highlighted":u?"":void 0,"data-disabled":o?"":void 0,...s,...(0,nt.skdxPart)("command","item",s.className),ref:r,onClick:(0,g.composeEventHandlers)(s.onClick,R),onPointerEnter:(0,g.composeEventHandlers)(s.onPointerEnter,()=>{o||a.setActiveId(m)})})});G.displayName="CommandItem";var it=f(require("react"),1),st=require("../utils/composeRefs.cjs"),dt=require("../utils/part.cjs"),ct=require("../utils/primitive.cjs");var pt=require("react/jsx-runtime"),q=it.forwardRef((t,o)=>{let e=p("CommandList"),s=(0,st.useComposedRefs)(o,e.listRef);return(0,pt.jsx)(ct.Primitive.div,{role:"listbox",id:e.listId,"aria-busy":e.loading||void 0,"data-loading":e.loading?"":void 0,...t,...(0,dt.skdxPart)("command","list",t.className),ref:s})});q.displayName="CommandList";var ft=f(require("react"),1),lt=require("../utils/part.cjs"),ut=require("../utils/primitive.cjs");var Ct=require("react/jsx-runtime"),F=ft.forwardRef((t,o)=>p("CommandLoading").loading?(0,Ct.jsx)(ut.Primitive.div,{role:"status",...t,...(0,lt.skdxPart)("command","loading",t.className),ref:o}):null);F.displayName="CommandLoading";var Rt=f(require("react"),1),yt=require("../utils/part.cjs"),It=require("../utils/primitive.cjs"),Pt=require("react/jsx-runtime"),V=Rt.forwardRef((t,o)=>(0,Pt.jsx)(It.Primitive.div,{role:"separator","aria-orientation":"horizontal",...t,...(0,yt.skdxPart)("command","separator",t.className),ref:o}));V.displayName="CommandSeparator";0&&(module.exports={Command,CommandEmpty,CommandGroup,CommandInput,CommandItem,CommandList,CommandLoading,CommandSeparator,OPTION_SELECTOR,defaultCommandFilter});

package/dist/command/Command.d.cts

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import type { CommandContextValue, CommandProps } from './types.cjs';
+/**
+ * cmdk-style command palette. Not Popper-anchored — it's meant to sit inside
+ * a Dialog or render standalone. The root owns the search text and filters its
+ * own items (`filter="manual"` hands that back to the consumer, matching
+ * Combobox), and handles virtual focus (`aria-activedescendant`) and keyboard
+ * nav across whatever is currently mounted. Real DOM focus always stays on
+ * `CommandInput`.
+ *
+ * `onSelect` callbacks are per-item closures, so unlike Combobox (which
+ * reads a `data-value` DOM attribute at commit time) Command keeps a plain
+ * mutable ref map of id -> {value, disabled, onSelect}, updated on every
+ * render with no extra effect/state churn; a separate id-only Set (mirroring
+ * Combobox's registerItem/unregisterItem) drives `itemCount` for CommandEmpty.
+ */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
+/** The built-in matcher: case-insensitive substring on the item's `value`. */
+export declare function defaultCommandFilter(itemValue: string, search: string): boolean;
+/**
+ * Reads the palette state a {@link Command} root publishes to its
+ * parts: the search string and the `matches` filter derived from it, the active
+ * item id that `CommandInput` points `aria-activedescendant` at, the list
+ * element and its id, the item registry behind `itemCount`, and `loading`.
+ *
+ * `CommandList`, `CommandItem`, `CommandInput`, `CommandEmpty` and
+ * `CommandLoading` each read it under their own name, which is the name the
+ * hook puts in the error it throws when one of them is rendered outside a
+ * `Command` — an unfiltered, unregistered item is worse than a hard failure.
+ * Not part of the public API.
+ *
+ * @internal
+ */
+export declare const CommandProvider: {
+    (props: CommandContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useCommandContext: (consumerName: string) => CommandContextValue;
+/**
+ * Root of a cmdk-style command palette: owns virtual focus
+ * (`aria-activedescendant`-based, so real DOM focus always stays on
+ * `CommandInput`) and item bookkeeping, and hands both down to
+ * `CommandInput` / `CommandList` / `CommandEmpty` / `CommandGroup` /
+ * `CommandItem` / `CommandSeparator` via context. Renders a plain `<div>`.
+ *
+ * Not popper-anchored — mount it inside a `Dialog` for a classic ⌘K palette,
+ * or render it standalone.
+ *
+ * `CommandInput` writes what the user types into the root's `search`, and the
+ * root filters its own items with a case-insensitive substring match on each
+ * item's `value`. Pass `filter` to replace the matcher, or `filter="manual"`
+ * to go back to mounting only the matching items yourself. `value` names the
+ * highlighted item and is controllable, and `loading` mounts `CommandLoading`
+ * while keeping `CommandEmpty` hidden.
+ *
+ * @example
+ * ```tsx
+ * function CommandPalette() {
+ *   return (
+ *     <Command>
+ *       <CommandInput placeholder="Search…" />
+ *       <CommandList>
+ *         <CommandLoading>Searching…</CommandLoading>
+ *         <CommandEmpty>No results found.</CommandEmpty>
+ *         <CommandGroup heading="Pages">
+ *           {['Profile', 'Settings', 'Billing'].map((item) => (
+ *             <CommandItem key={item} value={item} onSelect={(v) => console.log('go to', v)}>
+ *               {item}
+ *             </CommandItem>
+ *           ))}
+ *         </CommandGroup>
+ *       </CommandList>
+ *     </Command>
+ *   );
+ * }
+ * ```
+ */
+export declare const Command: React.ForwardRefExoticComponent<Omit<CommandProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/command/Command.d.ts

@@ -0,0 +1,79 @@
+import * as React from 'react';
+import type { CommandContextValue, CommandProps } from './types.js';
+/**
+ * cmdk-style command palette. Not Popper-anchored — it's meant to sit inside
+ * a Dialog or render standalone. The root owns the search text and filters its
+ * own items (`filter="manual"` hands that back to the consumer, matching
+ * Combobox), and handles virtual focus (`aria-activedescendant`) and keyboard
+ * nav across whatever is currently mounted. Real DOM focus always stays on
+ * `CommandInput`.
+ *
+ * `onSelect` callbacks are per-item closures, so unlike Combobox (which
+ * reads a `data-value` DOM attribute at commit time) Command keeps a plain
+ * mutable ref map of id -> {value, disabled, onSelect}, updated on every
+ * render with no extra effect/state churn; a separate id-only Set (mirroring
+ * Combobox's registerItem/unregisterItem) drives `itemCount` for CommandEmpty.
+ */
+export declare const OPTION_SELECTOR = "[role=\"option\"]:not([data-disabled])";
+/** The built-in matcher: case-insensitive substring on the item's `value`. */
+export declare function defaultCommandFilter(itemValue: string, search: string): boolean;
+/**
+ * Reads the palette state a {@link Command} root publishes to its
+ * parts: the search string and the `matches` filter derived from it, the active
+ * item id that `CommandInput` points `aria-activedescendant` at, the list
+ * element and its id, the item registry behind `itemCount`, and `loading`.
+ *
+ * `CommandList`, `CommandItem`, `CommandInput`, `CommandEmpty` and
+ * `CommandLoading` each read it under their own name, which is the name the
+ * hook puts in the error it throws when one of them is rendered outside a
+ * `Command` — an unfiltered, unregistered item is worse than a hard failure.
+ * Not part of the public API.
+ *
+ * @internal
+ */
+export declare const CommandProvider: {
+    (props: CommandContextValue & {
+        children: React.ReactNode;
+    }): React.JSX.Element;
+    displayName: string;
+}, useCommandContext: (consumerName: string) => CommandContextValue;
+/**
+ * Root of a cmdk-style command palette: owns virtual focus
+ * (`aria-activedescendant`-based, so real DOM focus always stays on
+ * `CommandInput`) and item bookkeeping, and hands both down to
+ * `CommandInput` / `CommandList` / `CommandEmpty` / `CommandGroup` /
+ * `CommandItem` / `CommandSeparator` via context. Renders a plain `<div>`.
+ *
+ * Not popper-anchored — mount it inside a `Dialog` for a classic ⌘K palette,
+ * or render it standalone.
+ *
+ * `CommandInput` writes what the user types into the root's `search`, and the
+ * root filters its own items with a case-insensitive substring match on each
+ * item's `value`. Pass `filter` to replace the matcher, or `filter="manual"`
+ * to go back to mounting only the matching items yourself. `value` names the
+ * highlighted item and is controllable, and `loading` mounts `CommandLoading`
+ * while keeping `CommandEmpty` hidden.
+ *
+ * @example
+ * ```tsx
+ * function CommandPalette() {
+ *   return (
+ *     <Command>
+ *       <CommandInput placeholder="Search…" />
+ *       <CommandList>
+ *         <CommandLoading>Searching…</CommandLoading>
+ *         <CommandEmpty>No results found.</CommandEmpty>
+ *         <CommandGroup heading="Pages">
+ *           {['Profile', 'Settings', 'Billing'].map((item) => (
+ *             <CommandItem key={item} value={item} onSelect={(v) => console.log('go to', v)}>
+ *               {item}
+ *             </CommandItem>
+ *           ))}
+ *         </CommandGroup>
+ *       </CommandList>
+ *     </Command>
+ *   );
+ * }
+ * ```
+ */
+export declare const Command: React.ForwardRefExoticComponent<Omit<CommandProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/command/Command.js

@@ -0,0 +1 @@
+import*as m from"react";import{createSafeContext as j}from"../utils/createContext.js";import{skdxPart as tt}from"../utils/part.js";import{Primitive as et}from"../utils/primitive.js";import{useControllableState as N}from"../utils/useControllableState.js";import{jsx as T}from"react/jsx-runtime";var P='[role="option"]:not([data-disabled])';function k(t,o){return t.toLowerCase().includes(o.toLowerCase())}var[ot,p]=j("Command"),D=m.forwardRef(({value:t,defaultValue:o,onValueChange:e,search:s,defaultSearch:i="",onSearchChange:n,filter:r,loading:l=!1,...d},C)=>{let g=m.useRef(null),v=m.useRef(new Map),[f,x]=m.useState(null),[E,h]=m.useState(()=>new Set),[y="",S]=N({prop:t,defaultProp:o??"",onChange:e}),[I="",Q]=N({prop:s,defaultProp:i,onChange:n}),M=m.useRef(r);M.current=r;let w=r==="manual",W=m.useCallback(a=>{if(w||I==="")return!0;let c=M.current;return(typeof c=="function"?c:k)(a,I)},[w,I]),L=m.useCallback(a=>{x(a),S(a?v.current.get(a)?.value??"":"")},[S]);m.useEffect(()=>{if(f&&E.has(f))return;let a=g.current?.querySelector(P);L(a?.id??null)},[E,f,L]),m.useEffect(()=>{if(!y||f&&v.current.get(f)?.value===y)return;let a=g.current?.querySelector(`[role="option"][data-value="${CSS.escape(y)}"]`);a&&x(a.id)},[y,f]);let X=m.useCallback(a=>{h(c=>{if(c.has(a))return c;let R=new Set(c);return R.add(a),R})},[]),Y=m.useCallback(a=>{h(c=>{if(!c.has(a))return c;let R=new Set(c);return R.delete(a),R}),x(c=>c===a?null:c)},[]),Z=m.useId();return T(ot,{listRef:g,listId:Z,activeId:f,setActiveId:L,itemMetaRef:v,registerItem:X,unregisterItem:Y,itemCount:E.size,search:I,setSearch:Q,matches:W,loading:l,children:T(et.div,{"data-loading":l?"":void 0,...d,...tt("command","root",d.className),ref:C})})});D.displayName="Command";import*as H from"react";import{skdxPart as rt}from"../utils/part.js";import{Primitive as mt}from"../utils/primitive.js";import{jsx as nt}from"react/jsx-runtime";var A=H.forwardRef((t,o)=>{let e=p("CommandEmpty");return e.loading||e.itemCount>0?null:nt(mt.div,{role:"presentation",...t,...rt("command","empty",t.className),ref:o})});A.displayName="CommandEmpty";import*as b from"react";import{skdxPart as at}from"../utils/part.js";import{Primitive as it}from"../utils/primitive.js";import{jsx as st,jsxs as dt}from"react/jsx-runtime";var O=b.forwardRef(({heading:t,children:o,...e},s)=>dt(it.div,{role:"group",...e,...at("command","group",e.className),ref:s,children:[t!=null?st("div",{role:"presentation",children:t}):null,o]}));O.displayName="CommandGroup";import*as q from"react";import{skdxPart as ct}from"../utils/part.js";import{composeEventHandlers as G,Primitive as pt}from"../utils/primitive.js";import{jsx as ft}from"react/jsx-runtime";var F=q.forwardRef((t,o)=>{let e=p("CommandInput"),s=i=>{let n=e.listRef.current;if(!n)return;let r=Array.from(n.querySelectorAll(P));if(r.length===0)return;let d=r.findIndex(C=>C.id===e.activeId)+i;d<0&&(d=0),d>=r.length&&(d=r.length-1),e.setActiveId(r[d].id)};return ft(pt.input,{type:"text","aria-controls":e.listId,"aria-activedescendant":e.activeId??void 0,autoComplete:"off",...t,...ct("command","input",t.className),ref:o,onChange:G(t.onChange,i=>{e.setSearch(i.target.value)}),onKeyDown:G(t.onKeyDown,i=>{if(i.key==="ArrowDown")i.preventDefault(),s(1);else if(i.key==="ArrowUp")i.preventDefault(),s(-1);else if(i.key==="Enter"){if(!e.activeId)return;let n=e.itemMetaRef.current.get(e.activeId);n&&!n.disabled&&(i.preventDefault(),n.onSelect?.(n.value))}})})});F.displayName="CommandInput";import*as u from"react";import{skdxPart as lt}from"../utils/part.js";import{composeEventHandlers as V,Primitive as ut}from"../utils/primitive.js";import{jsx as Ct}from"react/jsx-runtime";var _=u.forwardRef(({value:t,disabled:o,onSelect:e,...s},i)=>{let n=p("CommandItem"),r=u.useId(),l=n.activeId===r,d=n.matches(t);if(d&&n.itemMetaRef.current.set(r,{value:t,disabled:o,onSelect:e}),u.useEffect(()=>{if(d)return n.registerItem(r),()=>{n.unregisterItem(r),n.itemMetaRef.current.delete(r)}},[r,d]),!d)return null;let C=()=>{o||(n.setActiveId(r),e?.(t))};return Ct(ut.div,{role:"option",id:r,"data-value":t,"aria-selected":l,"data-highlighted":l?"":void 0,"data-disabled":o?"":void 0,...s,...lt("command","item",s.className),ref:i,onClick:V(s.onClick,C),onPointerEnter:V(s.onPointerEnter,()=>{o||n.setActiveId(r)})})});_.displayName="CommandItem";import*as z from"react";import{useComposedRefs as Rt}from"../utils/composeRefs.js";import{skdxPart as yt}from"../utils/part.js";import{Primitive as It}from"../utils/primitive.js";import{jsx as Pt}from"react/jsx-runtime";var K=z.forwardRef((t,o)=>{let e=p("CommandList"),s=Rt(o,e.listRef);return Pt(It.div,{role:"listbox",id:e.listId,"aria-busy":e.loading||void 0,"data-loading":e.loading?"":void 0,...t,...yt("command","list",t.className),ref:s})});K.displayName="CommandList";import*as U from"react";import{skdxPart as gt}from"../utils/part.js";import{Primitive as vt}from"../utils/primitive.js";import{jsx as xt}from"react/jsx-runtime";var $=U.forwardRef((t,o)=>p("CommandLoading").loading?xt(vt.div,{role:"status",...t,...gt("command","loading",t.className),ref:o}):null);$.displayName="CommandLoading";import*as B from"react";import{skdxPart as Et}from"../utils/part.js";import{Primitive as Lt}from"../utils/primitive.js";import{jsx as ht}from"react/jsx-runtime";var J=B.forwardRef((t,o)=>ht(Lt.div,{role:"separator","aria-orientation":"horizontal",...t,...Et("command","separator",t.className),ref:o}));J.displayName="CommandSeparator";export{D as Command,A as CommandEmpty,O as CommandGroup,F as CommandInput,_ as CommandItem,K as CommandList,$ as CommandLoading,J as CommandSeparator,P as OPTION_SELECTOR,k as defaultCommandFilter};

package/dist/command/CommandEmpty.d.cts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { CommandEmptyProps } from './types.cjs';
+/**
+ * Renders its children (typically "No results found") only when zero
+ * `CommandItem`s are currently mounted inside `CommandList` — i.e. when the
+ * search (or the consumer's own filtering) leaves nothing to show, and never
+ * while the root is `loading`. Renders `role="presentation"`.
+ *
+ * @example
+ * ```tsx
+ * <CommandList>
+ *   <CommandEmpty>No results found.</CommandEmpty>
+ *   {filteredItems.map((item) => <CommandItem key={item} value={item}>{item}</CommandItem>)}
+ * </CommandList>
+ * ```
+ */
+export declare const CommandEmpty: React.ForwardRefExoticComponent<Omit<CommandEmptyProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/command/CommandEmpty.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import type { CommandEmptyProps } from './types.js';
+/**
+ * Renders its children (typically "No results found") only when zero
+ * `CommandItem`s are currently mounted inside `CommandList` — i.e. when the
+ * search (or the consumer's own filtering) leaves nothing to show, and never
+ * while the root is `loading`. Renders `role="presentation"`.
+ *
+ * @example
+ * ```tsx
+ * <CommandList>
+ *   <CommandEmpty>No results found.</CommandEmpty>
+ *   {filteredItems.map((item) => <CommandItem key={item} value={item}>{item}</CommandItem>)}
+ * </CommandList>
+ * ```
+ */
+export declare const CommandEmpty: React.ForwardRefExoticComponent<Omit<CommandEmptyProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/command/CommandGroup.d.cts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import type { CommandGroupProps } from './types.cjs';
+/**
+ * Labelled cluster of `CommandItem`s: renders a `<div role="group">` with an
+ * optional non-interactive `heading` above the items.
+ *
+ * @example
+ * ```tsx
+ * <CommandGroup heading="Pages">
+ *   <CommandItem value="profile">Profile</CommandItem>
+ *   <CommandItem value="settings">Settings</CommandItem>
+ * </CommandGroup>
+ * ```
+ */
+export declare const CommandGroup: React.ForwardRefExoticComponent<Omit<CommandGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/command/CommandGroup.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import type { CommandGroupProps } from './types.js';
+/**
+ * Labelled cluster of `CommandItem`s: renders a `<div role="group">` with an
+ * optional non-interactive `heading` above the items.
+ *
+ * @example
+ * ```tsx
+ * <CommandGroup heading="Pages">
+ *   <CommandItem value="profile">Profile</CommandItem>
+ *   <CommandItem value="settings">Settings</CommandItem>
+ * </CommandGroup>
+ * ```
+ */
+export declare const CommandGroup: React.ForwardRefExoticComponent<Omit<CommandGroupProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/command/CommandInput.d.cts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import type { CommandInputProps } from './types.cjs';
+/**
+ * The palette's search/filter field: a plain `<input type="text">` wired to
+ * `CommandList` via `aria-controls` and to the currently highlighted item
+ * via `aria-activedescendant`. Handles Arrow Up/Down to move the virtual
+ * highlight across whichever `CommandItem`s are currently mounted, and
+ * Enter to invoke the highlighted item's `onSelect`. Real DOM focus stays
+ * here at all times — filtering the item list as the user types does not need
+ * to move focus.
+ *
+ * Every keystroke also writes into the root's `search`, which is what drives
+ * the root's own filtering. Passing `value`/`onChange` here still works: the
+ * consumer's handler runs alongside, not instead of, that.
+ *
+ * @example
+ * ```tsx
+ * <CommandInput
+ *   value={query}
+ *   onChange={(e) => setQuery(e.target.value)}
+ *   placeholder="Search…"
+ * />
+ * ```
+ */
+export declare const CommandInput: React.ForwardRefExoticComponent<Omit<CommandInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/command/CommandInput.d.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import type { CommandInputProps } from './types.js';
+/**
+ * The palette's search/filter field: a plain `<input type="text">` wired to
+ * `CommandList` via `aria-controls` and to the currently highlighted item
+ * via `aria-activedescendant`. Handles Arrow Up/Down to move the virtual
+ * highlight across whichever `CommandItem`s are currently mounted, and
+ * Enter to invoke the highlighted item's `onSelect`. Real DOM focus stays
+ * here at all times — filtering the item list as the user types does not need
+ * to move focus.
+ *
+ * Every keystroke also writes into the root's `search`, which is what drives
+ * the root's own filtering. Passing `value`/`onChange` here still works: the
+ * consumer's handler runs alongside, not instead of, that.
+ *
+ * @example
+ * ```tsx
+ * <CommandInput
+ *   value={query}
+ *   onChange={(e) => setQuery(e.target.value)}
+ *   placeholder="Search…"
+ * />
+ * ```
+ */
+export declare const CommandInput: React.ForwardRefExoticComponent<Omit<CommandInputProps, "ref"> & React.RefAttributes<HTMLInputElement>>;

package/dist/command/CommandItem.d.cts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import type { CommandItemProps } from './types.cjs';
+/**
+ * A single selectable result: `role="option"` with `aria-selected` and
+ * `data-highlighted`/`data-disabled` reflecting virtual-focus state.
+ * Registers itself with the parent `Command` on mount (and unregisters on
+ * unmount, so filtering items in/out keeps navigation and `CommandEmpty`
+ * accurate). Pointer-enter moves the highlight here; click or Enter (while
+ * highlighted) fires `onSelect` with `value`. Set `disabled` to exclude it
+ * from navigation and selection. Renders nothing while the root's search
+ * filters it out — `data-value` carries its `value` so the root can move the
+ * highlight to it by value.
+ *
+ * @example
+ * ```tsx
+ * <CommandItem value="profile" onSelect={(value) => console.log('go to', value)}>
+ *   Profile
+ * </CommandItem>
+ * ```
+ */
+export declare const CommandItem: React.ForwardRefExoticComponent<Omit<CommandItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/command/CommandItem.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import type { CommandItemProps } from './types.js';
+/**
+ * A single selectable result: `role="option"` with `aria-selected` and
+ * `data-highlighted`/`data-disabled` reflecting virtual-focus state.
+ * Registers itself with the parent `Command` on mount (and unregisters on
+ * unmount, so filtering items in/out keeps navigation and `CommandEmpty`
+ * accurate). Pointer-enter moves the highlight here; click or Enter (while
+ * highlighted) fires `onSelect` with `value`. Set `disabled` to exclude it
+ * from navigation and selection. Renders nothing while the root's search
+ * filters it out — `data-value` carries its `value` so the root can move the
+ * highlight to it by value.
+ *
+ * @example
+ * ```tsx
+ * <CommandItem value="profile" onSelect={(value) => console.log('go to', value)}>
+ *   Profile
+ * </CommandItem>
+ * ```
+ */
+export declare const CommandItem: React.ForwardRefExoticComponent<Omit<CommandItemProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/command/CommandList.d.cts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import type { CommandListProps } from './types.cjs';
+/**
+ * Container for `CommandItem`s and `CommandGroup`s: renders
+ * `<div role="listbox">`, wired to `CommandInput` via `aria-controls`/
+ * `aria-activedescendant`, and carrying `aria-busy`/`data-loading` while the
+ * root's `loading` is set.
+ *
+ * @example
+ * ```tsx
+ * <CommandList>
+ *   <CommandEmpty>No results found.</CommandEmpty>
+ *   <CommandGroup heading="Pages">
+ *     <CommandItem value="profile">Profile</CommandItem>
+ *   </CommandGroup>
+ * </CommandList>
+ * ```
+ */
+export declare const CommandList: React.ForwardRefExoticComponent<Omit<CommandListProps, "ref"> & React.RefAttributes<HTMLDivElement>>;