@skdx/react 0.26.0 → 0.28.0

package/dist/combobox/types.d.ts

@@ -1,15 +1,72 @@
 import type * as React from 'react';
 import type { FormValidityHandle } from '../utils/formControl.js';
+import type { PassThroughProps } from '../utils/passThrough.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';
+/** Flat option for ComboboxProps.options recipe prop. */
+export interface ComboboxOption {
+    /** Value committed when option is chosen. */
+    value: string;
+    /**
+     * Text shown for option; matched by filter, written back on selection.
+     * @default undefined
+     */
+    label?: string;
+    /**
+     * Excludes option from selection and pointer highlight.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/** Labeled group of options for ComboboxProps.options. */
+export interface ComboboxOptionGroup {
+    /** Heading for the group. */
+    label: string;
+    /** Options in this group. */
+    options: ComboboxOption[];
+}
+/** One entry of {@link ComboboxProps.options}: a flat option, or a labeled group of them. */
+export type ComboboxOptionOrGroup = ComboboxOption | ComboboxOptionGroup;
+/**
+ * Filtering strategy: 'manual' for consumer control or predicate for component filtering; numbers rank.
+ */
+export type ComboboxFilter = 'manual' | ((itemText: string, inputValue: string) => boolean | number);
+/** What drove a {@link Combobox} value change — the shared three-value vocabulary from `@skdx/shared`'s `change-reason` contract. */
+export type ComboboxValueChangeReason = 'keyboard' | 'pointer' | 'programmatic';
+/**
+ * Payload for `onValueChange` event.
+ */
+export interface ComboboxValueChangeDetail {
+    /** New selection (always array). */
+    value: string[];
+    /** Previous selection, or null if none. */
+    previousValue: string[] | null;
+    /** What drove the change. */
+    reason: ComboboxValueChangeReason;
+    /** First selected value, or null when nothing is. */
+    selectedValue: string | null;
+}
+/**
+ * Gesture to open listbox: 'type', 'click', or 'focus'.
+ */
+export type ComboboxOpenOn = 'type' | 'click' | 'focus';
+/**
+ * What moved highlight: 'keyboard', 'pointer', or 'auto'.
+ */
+export type ComboboxHighlightReason = 'keyboard' | 'pointer' | 'auto';
 /**
- * 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.
+ * Payload for `onHighlightChange` event.
  */
-export type ComboboxFilter = 'manual' | ((itemText: string, inputValue: string) => boolean);
+export interface ComboboxHighlightChangeDetail {
+    /** Option value now highlighted, or null if none. */
+    value: string | null;
+    /** Previously highlighted option value, or null. */
+    previousValue: string | null;
+    /** What moved it. */
+    reason: ComboboxHighlightReason;
+}
 /** @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. */
@@ -20,6 +77,8 @@ export interface ComboboxItemEntry {
 /** @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>;
+    /** Optional trigger button ref for dismissal layer. */
+    triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
     /** Whether more than one option can be selected. */
@@ -28,248 +87,276 @@ export interface ComboboxContextValue {
     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;
+    /** Commits option: replaces selection or toggles in multi-select mode. */
+    selectItem: (value: string, text: string, reason: ComboboxValueChangeReason) => void;
+    /** Empties selection and draft text. */
+    clear: () => 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. */
+    /** Rank each currently-visible item's CSS `order` should carry when `filter` also scores it; `null` leaves order untouched. */
+    itemOrder: ReadonlyMap<string, number> | null;
+    /** Moves virtual highlight and tags with reason. */
+    setActiveId: (id: string | null, reason?: ComboboxHighlightReason) => void;
+    /** Opens listbox and highlights first or last option. */
     openWithHighlight: (edge: 'first' | 'last') => void;
+    /** Whether arrow navigation wraps around the ends of the option list. */
+    loop: boolean;
+    /** Which pointer/focus gesture opens the listbox, on top of the keyboard ones. */
+    openOn: ComboboxOpenOn;
+    /** Replaces draft text with selected option's text when focus lost and `allowCustomValue` is off. */
+    reconcileDraftText: () => 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. */
+    /** Gets registered entry for option id. */
     getItem: (id: string) => ComboboxItemEntry | undefined;
-    /** Whether an item with this text survives the current `filter` and draft text. */
+    /** Checks if item text matches filter and draft. */
     matchesFilter: (itemText: string) => boolean;
     invalid: boolean;
     readOnly: boolean;
+    disabled: 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)`.
+ * Forwarded ref for constraint-validation methods.
  */
 export type ComboboxHandle = FormValidityHandle;
-/** Props for the {@link Combobox} root. */
-export interface ComboboxProps {
+/**
+ * Props for the {@link Combobox} root. Standard attributes ({@link
+ * PassThroughProps}) land on the derived `ComboboxInput` (the `role="combobox"`).
+ */
+export interface ComboboxProps extends PassThroughProps {
     /**
-     * The `ComboboxInput`/`ComboboxPortal` parts, rendered as children — `Combobox` itself renders no DOM.
-     * @default undefined — renders nothing without children.
+     * The `ComboboxInput` and `ComboboxPortal` parts children to render.
+     * @default undefined
      */
     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.
+     * Selected value for controlled usage; pair with `onValueChange`.
+     * @default undefined
      */
     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.
+     * Initially selected value for uncontrolled usage.
+     * @default undefined
      */
     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.
+     * Fires when the selected value changes in the combobox.
+     * @default undefined
      */
-    onValueChange?: (value: string | string[]) => void;
+    onValueChange?: (detail: ComboboxValueChangeDetail) => 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.
+     * Allows multiple options selected; toggles instead of replacing.
      * @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.
+     * Lets Enter commit unmatched draft text as a value ("creatable").
      * @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.
+     * How items are filtered; 'manual' filters nothing, predicate filters and ranks.
      * @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.
+     * Keeps first option highlighted when list changes while open.
      * @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).
+     * Wraps arrow navigation around list ends.
+     * @default true
+     */
+    loop?: boolean;
+    /**
+     * Fires when virtual focus changes; read-only, no controlled counterpart.
+     * @default undefined
+     */
+    onHighlightChange?: (detail: ComboboxHighlightChangeDetail) => void;
+    /**
+     * Which pointer/focus gesture opens listbox on top of keyboard ones.
+     * @default 'type'
+     */
+    openOn?: ComboboxOpenOn;
+    /**
+     * Marks results as in flight: aria-busy and data-loading.
      * @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.
+     * Draft text for controlled usage; pair with `onInputValueChange`.
+     * @default undefined
      */
     inputValue?: string;
     /**
-     * Initial draft text, for uncontrolled usage.
+     * 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.
+     * Fires with new draft text on keystroke or when selection updates it.
+     * @default undefined
      */
     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.
+     * Whether listbox is open for controlled usage; pair with `onOpenChange`.
+     * @default undefined
      */
     open?: boolean;
     /**
-     * Initial open state, for uncontrolled usage.
+     * 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.
+     * Fires with the new open state when it changes.
+     * @default undefined
      */
     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.
+     * Fires once the open/close animation completes.
+     * @default undefined
      */
     onOpenChangeComplete?: (open: boolean) => void;
     /**
-     * Marks the combobox as invalid, exposed as `aria-invalid`/`data-invalid`
-     * on the `ComboboxInput`.
+     * Marks combobox invalid: aria-invalid and data-invalid.
      * @default false
      */
     invalid?: boolean;
     /**
-     * Makes the `ComboboxInput` read-only, exposed as the native `readOnly`
-     * attribute plus `aria-readonly`/`data-readonly`.
+     * Makes input read-only: aria-readonly and 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"`
+     * Disables combobox: disabled attribute and data-disabled.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Formats the match count announcement for screen readers.
+     * @default defaultGetResultCountLabel
      */
     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.
+     * Form field name; mirrors selected value for form submission.
+     * @default undefined
      */
     name?: string;
     /**
-     * Marks the combobox required: `aria-required` on `ComboboxInput`, and —
-     * with `name` — native `valueMissing` while nothing is selected, reported
-     * through `checkValidity()`/`reportValidity()`.
+     * Id of the form this combobox submits into.
+     * @default undefined
+     */
+    form?: string;
+    /**
+     * Marks combobox required; valueMissing when nothing selected.
      * @default false
      */
     required?: boolean;
+    /**
+     * Option data (flat or grouped) to render automatically.
+     * @default undefined
+     */
+    options?: ComboboxOptionOrGroup[];
+    /**
+     * Custom rendering function for each option in the options list.
+     * @default undefined
+     */
+    renderOption?: (option: ComboboxOption, state: {
+        selected: boolean;
+    }) => React.ReactNode;
+    /**
+     * Placeholder text shown in the input when no value is selected.
+     * @default undefined
+     */
+    placeholder?: string;
+    /**
+     * Accessible name for derived input and listbox.
+     * @default undefined
+     */
+    'aria-label'?: string;
 }
-/** Props for {@link ComboboxInput}, the text field that drives filtering and keeps real DOM focus while the listbox is open. */
+/** Props for {@link ComboboxInput}, the text field with real DOM focus. */
 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. */
+/** Props for ComboboxPortal, which teleports content to document.body. */
 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.
+     * Mounts listbox content to the DOM even when closed, enabling exit animations.
      * @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`).
+ * Props for ComboboxContent listbox popup.
  */
 export interface ComboboxContentProps extends PopperContentProps {
     /**
-     * Keep this listbox mounted even while closed, instead of unmounting it.
+     * Mounts the listbox DOM even when closed, enabling exit animations.
      * @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.
+     * Fires when the Escape key is pressed while the listbox is open.
+     * @default undefined
      */
     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.
+     * Fires on pointer-down outside listbox and input.
+     * @default undefined
      */
     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.
+     * Fires when focus moves outside listbox and input.
+     * @default undefined
      */
     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.
+     * Fires when any interaction occurs outside the listbox and input.
+     * @default undefined
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
 }
-/** Props for a single {@link ComboboxItem} option within `ComboboxContent`. */
+/** Props for single ComboboxItem option. */
 export interface ComboboxItemProps extends PrimitivePropsWithRef<'div'> {
-    /** Unique identifier committed to the combobox root's value when this option is chosen. */
+    /** Value committed when option is chosen. */
     value: string;
     /**
-     * Excludes this option from selection and pointer highlight.
+     * Excludes 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.
+     * Text for filter matching and selection write-back to input.
+     * @default undefined
      */
     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). */
+/** Props for ComboboxEmpty, shown when no items are rendered. */
 export interface ComboboxEmptyProps extends PrimitivePropsWithRef<'div'> {
 }
+/** Props for ComboboxTrigger, optional button that toggles listbox. */
+export interface ComboboxTriggerProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for ComboboxClear, optional button that empties selection. */
+export interface ComboboxClearProps extends PrimitivePropsWithRef<'button'> {
+}
+/** Props for ComboboxGroup, named section of related options. */
+export interface ComboboxGroupProps extends PrimitivePropsWithRef<'div'> {
+}
+/** Props for ComboboxGroupLabel, heading for enclosing ComboboxGroup. */
+export interface ComboboxGroupLabelProps extends PrimitivePropsWithRef<'div'> {
+}
+/** @internal What ComboboxGroup publishes to ComboboxGroupLabel inside it. */
+export interface ComboboxGroupContextValue {
+    /** Id group points aria-labelledby at. */
+    labelId: string;
+}

package/dist/command/Command.cjs

@@ -1 +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});
+"use strict";var $e=Object.create;var B=Object.defineProperty;var Ue=Object.getOwnPropertyDescriptor;var Je=Object.getOwnPropertyNames;var Qe=Object.getPrototypeOf,We=Object.prototype.hasOwnProperty;var Xe=(e,o)=>{for(var t in o)B(e,t,{get:o[t],enumerable:!0})},ae=(e,o,t,i)=>{if(o&&typeof o=="object"||typeof o=="function")for(let d of Je(o))!We.call(e,d)&&d!==t&&B(e,d,{get:()=>o[d],enumerable:!(i=Ue(o,d))||i.enumerable});return e};var g=(e,o,t)=>(t=e!=null?$e(Qe(e)):{},ae(o||!e||!e.__esModule?B(t,"default",{value:e,enumerable:!0}):t,e)),Ye=e=>ae(B({},"__esModule",{value:!0}),e);var Ze={};Xe(Ze,{Command:()=>Z,CommandEmpty:()=>V,CommandGroup:()=>K,CommandInput:()=>z,CommandItem:()=>_,CommandList:()=>$,CommandLoading:()=>U,CommandProvider:()=>Te,CommandSeparator:()=>Oe,OPTION_SELECTOR:()=>D,defaultCommandFilter:()=>H,useCommandContext:()=>u});module.exports=Ye(Ze);var l=g(require("react"),1),Me=require("../utils/createContext.cjs"),we=require("../utils/part.cjs"),De=require("../utils/primitive.cjs"),P=require("../utils/scoredFilter.cjs"),Y=require("../utils/useControllableState.cjs");var me=g(require("react"),1),ie=require("../utils/part.cjs"),se=require("../utils/primitive.cjs");var de=require("react/jsx-runtime"),V=me.forwardRef((e,o)=>{let t=u("CommandEmpty");return t.loading||t.itemCount>0?null:(0,de.jsx)(se.Primitive.div,{role:"presentation",...e,...(0,ie.skdxPart)("command","empty",e.className),ref:o})});V.displayName="CommandEmpty";var F=g(require("react"),1),le=require("../utils/part.cjs"),ce=require("../utils/primitive.cjs"),x=require("react/jsx-runtime"),K=F.forwardRef(({heading:e,children:o,...t},i)=>{let d=F.useId(),r=e!=null;return(0,x.jsx)(ce.Primitive.div,{role:"group","aria-labelledby":r?d:void 0,...t,...(0,le.skdxPart)("command","group",t.className),ref:i,children:r?(0,x.jsxs)(x.Fragment,{children:[(0,x.jsx)("div",{role:"presentation",id:d,children:e}),o]}):o})});K.displayName="CommandGroup";var fe=g(require("react"),1),ue=require("../utils/part.cjs"),w=require("../utils/primitive.cjs"),pe=require("../utils/scoredFilter.cjs");var Ce=require("react/jsx-runtime"),z=fe.forwardRef((e,o)=>{let t=u("CommandInput"),i=()=>{let r=t.listRef.current;return r?(0,pe.sortByOrder)(Array.from(r.querySelectorAll(D)),t.itemOrder):[]},d=r=>{let s=i();if(s.length===0)return;let n=s.findIndex(y=>y.id===t.activeId),f=n===-1?r===1?-1:0:n,h=t.loop?(f+r+s.length)%s.length:Math.min(s.length-1,Math.max(0,f+r)),R=s[h];t.setActiveId(R.id),R.scrollIntoView?.({block:"nearest"})};return(0,Ce.jsx)(w.Primitive.input,{type:"text","aria-controls":t.listId,"aria-activedescendant":t.activeId??void 0,autoComplete:"off",...e,...(0,ue.skdxPart)("command","input",e.className),ref:o,onChange:(0,w.composeEventHandlers)(e.onChange,r=>{t.setSearch(r.target.value)}),onKeyDown:(0,w.composeEventHandlers)(e.onKeyDown,r=>{if(r.key==="ArrowDown")r.preventDefault(),d(1);else if(r.key==="ArrowUp")r.preventDefault(),d(-1);else if(r.key==="Home"||r.key==="End"){let s=i();if(s.length===0)return;r.preventDefault();let n=r.key==="Home"?s[0]:s[s.length-1];t.setActiveId(n.id),n.scrollIntoView?.({block:"nearest"})}else if(r.key==="Enter"){if(!t.activeId)return;let s=t.itemMetaRef.current.get(t.activeId);s&&!s.disabled&&(r.preventDefault(),s.onSelect?.(s.value))}})})});z.displayName="CommandInput";var S=g(require("react"),1),ye=require("../utils/part.cjs"),T=require("../utils/primitive.cjs");var ge=require("react/jsx-runtime"),_=S.forwardRef(({value:e,disabled:o,onSelect:t,keywords:i,forceMount:d=!1,...r},s)=>{let n=u("CommandItem"),f=S.useId(),h=n.activeId===f,R=n.itemOrder?.get(f),y=d||n.matches(e,i);y&&n.itemMetaRef.current.set(f,{value:e,disabled:o,onSelect:t,keywords:i});let{registerItem:N,unregisterItem:E,itemMetaRef:A}=n;if(S.useEffect(()=>{if(!y)return;let O=A.current;return N(f),()=>{E(f),O.delete(f)}},[f,y,N,E,A]),!y)return null;let Q=()=>{o||(n.setActiveId(f),t?.(e))};return(0,ge.jsx)(T.Primitive.div,{role:"option",id:f,"data-value":e,"aria-selected":h,"data-highlighted":h?"":void 0,"aria-disabled":o||void 0,"data-disabled":o?"":void 0,...r,...(0,ye.skdxPart)("command","item",r.className),ref:s,onClick:(0,T.composeEventHandlers)(r.onClick,Q),onPointerEnter:(0,T.composeEventHandlers)(r.onPointerEnter,()=>{!o&&!n.disablePointerSelection&&n.setActiveId(f)}),style:R!==void 0?{order:R,...r.style}:r.style})});_.displayName="CommandItem";var Re=g(require("react"),1),Ie=require("../utils/composeRefs.cjs"),ve=require("../utils/part.cjs"),xe=require("../utils/primitive.cjs");var Pe=require("react/jsx-runtime"),$=Re.forwardRef((e,o)=>{let t=u("CommandList"),i=(0,Ie.useComposedRefs)(o,t.listRef);return(0,Pe.jsx)(xe.Primitive.div,{role:"listbox",id:t.listId,"aria-busy":t.loading||void 0,"data-loading":t.loading?"":void 0,...e,...(0,ve.skdxPart)("command","list",e.className),ref:i})});$.displayName="CommandList";var he=g(require("react"),1),Ee=require("../utils/part.cjs"),Le=require("../utils/primitive.cjs");var be=require("react/jsx-runtime"),U=he.forwardRef((e,o)=>u("CommandLoading").loading?(0,be.jsx)(Le.Primitive.div,{role:"status",...e,...(0,Ee.skdxPart)("command","loading",e.className),ref:o}):null);U.displayName="CommandLoading";var p=require("react/jsx-runtime"),Se=({groups:e=[],placeholder:o,emptyMessage:t,loadingMessage:i,onSelect:d,renderItem:r})=>{let s=n=>{let f=n.value??n.label;return(0,p.jsx)(_,{value:f,keywords:n.keywords,disabled:n.disabled,onSelect:()=>{n.onSelect?.(),d?.(n)},children:r?r(n):n.label},f)};return(0,p.jsxs)(p.Fragment,{children:[(0,p.jsx)(z,{placeholder:o}),(0,p.jsx)($,{"aria-label":o,children:e.map(n=>n.label?(0,p.jsx)(K,{heading:n.label,children:n.items.map(s)},n.label):n.items.map(s))}),i?(0,p.jsx)(U,{children:i}):null,t?(0,p.jsx)(V,{children:t}):null]})};var J=require("react/jsx-runtime"),D='[role="option"]:not([data-disabled])';function ke(e,o){if(!e.contains(o))return;let t=e.getBoundingClientRect(),i=o.getBoundingClientRect(),d=i.top-t.top,r=i.bottom-t.bottom;d<0?e.scrollTop+=d:r>0&&(e.scrollTop+=r)}function H(e,o,t){let i=o.toLowerCase();return e.toLowerCase().includes(i)?!0:t?.some(d=>d.toLowerCase().includes(i))??!1}var[Te,u]=(0,Me.createSafeContext)("Command"),Z=l.forwardRef(({children:e,groups:o,placeholder:t,emptyMessage:i,loadingMessage:d,onSelect:r,renderItem:s,value:n,defaultValue:f,onValueChange:h,search:R,defaultSearch:y="",onSearchChange:N,filter:E,loop:A=!1,disablePointerSelection:Q=!1,loading:O=!1,...j},qe)=>{let G=l.useRef(null),k=l.useRef(new Map),[I,W]=l.useState(null),[M,ee]=l.useState(()=>new Set),[v="",te]=(0,Y.useControllableState)({prop:n,defaultProp:f??"",onChange:h}),[C="",Be]=(0,Y.useControllableState)({prop:R,defaultProp:y,onChange:N}),q=l.useRef(E);q.current=E;let L=E==="manual",Ve=l.useCallback((a,m)=>{if(L||C==="")return!0;let c=q.current;return(0,P.filterKeeps)((typeof c=="function"?c:H)(a,C,m))},[L,C]),Fe=l.useMemo(()=>L||C===""?null:(0,P.rankByScore)([...M],a=>{let m=k.current.get(a);if(!m)return null;let c=q.current,b=(typeof c=="function"?c:H)(m.value,C,m.keywords);return typeof b=="number"?b:null}),[L,C,M]),oe=l.useCallback(()=>{if(L||C==="")return null;let a=G.current;if(!a)return null;let m=Array.from(a.querySelectorAll(D),c=>c.id);return(0,P.rankByScore)(m,c=>{let b=k.current.get(c);if(!b)return null;let re=q.current,ne=(typeof re=="function"?re:H)(b.value,C,b.keywords);return typeof ne=="number"?ne:null})},[L,C]),X=l.useCallback(a=>{W(a),te(a?k.current.get(a)?.value??"":"")},[te]);l.useEffect(()=>{if(I&&M.has(I))return;let a=G.current;if(v&&a?.querySelector(`[role="option"][data-value="${CSS.escape(v)}"]`))return;let m=a?Array.from(a.querySelectorAll(D)):[],c=(0,P.sortByOrder)(m,oe())[0];X(c?.id??null),a&&c&&ke(a,c)},[M,I,X,v,oe]),l.useEffect(()=>{if(!v||I&&k.current.get(I)?.value===v)return;let a=G.current,m=a?.querySelector(`[role="option"][data-value="${CSS.escape(v)}"]`);m&&(W(m.id),a&&ke(a,m))},[v,I]);let Ke=l.useCallback(a=>{ee(m=>{if(m.has(a))return m;let c=new Set(m);return c.add(a),c})},[]),ze=l.useCallback(a=>{ee(m=>{if(!m.has(a))return m;let c=new Set(m);return c.delete(a),c}),W(m=>m===a?null:m)},[]),_e=l.useId();return(0,J.jsx)(Te,{listRef:G,listId:_e,activeId:I,itemOrder:Fe,setActiveId:X,itemMetaRef:k,registerItem:Ke,unregisterItem:ze,itemCount:M.size,search:C,setSearch:Be,matches:Ve,loop:A,disablePointerSelection:Q,loading:O,children:(0,J.jsx)(De.Primitive.div,{"data-loading":O?"":void 0,...j,...(0,we.skdxPart)("command","root",j.className),ref:qe,children:e??(0,J.jsx)(Se,{groups:o,placeholder:t,emptyMessage:i,loadingMessage:d,onSelect:r,renderItem:s})})})});Z.displayName="Command";var He=g(require("react"),1),Ne=require("../utils/part.cjs"),Ae=require("../utils/primitive.cjs"),Ge=require("react/jsx-runtime"),Oe=He.forwardRef((e,o)=>(0,Ge.jsx)(Ae.Primitive.div,{role:"separator","aria-orientation":"horizontal",...e,...(0,Ne.skdxPart)("command","separator",e.className),ref:o}));Oe.displayName="CommandSeparator";0&&(module.exports={Command,CommandEmpty,CommandGroup,CommandInput,CommandItem,CommandList,CommandLoading,CommandProvider,CommandSeparator,OPTION_SELECTOR,defaultCommandFilter,useCommandContext});

package/dist/command/Command.d.cts

@@ -1,22 +1,22 @@
 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.
+ * Command palette: not Popper-anchored, meant for a Dialog or standalone.
+ * Owns search text, filters items, handles virtual focus via aria-activedescendant
+ * and keyboard nav. Real focus stays on CommandInput.
+ * onSelect callbacks are per-item closures kept in a mutable ref map.
  */
 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;
+/**
+ * The built-in matcher: case-insensitive substring on the item's `value`, or on
+ * any of its `keywords`.
+ *
+ * The keywords arm is what makes "Toggle theme" findable by typing "dark mode".
+ * Matched with the same rule as the value rather than a stricter one — an alias
+ * the author wrote down is a stronger signal of intent than the label, not a
+ * weaker one.
+ */
+export declare function defaultCommandFilter(itemValue: string, search: string, keywords?: readonly 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
@@ -60,7 +60,7 @@ export declare const CommandProvider: {
  *   return (
  *     <Command>
  *       <CommandInput placeholder="Search…" />
- *       <CommandList>
+ *       <CommandList aria-label="Commands">
  *         <CommandLoading>Searching…</CommandLoading>
  *         <CommandEmpty>No results found.</CommandEmpty>
  *         <CommandGroup heading="Pages">

package/dist/command/Command.d.ts

@@ -1,22 +1,22 @@
 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.
+ * Command palette: not Popper-anchored, meant for a Dialog or standalone.
+ * Owns search text, filters items, handles virtual focus via aria-activedescendant
+ * and keyboard nav. Real focus stays on CommandInput.
+ * onSelect callbacks are per-item closures kept in a mutable ref map.
  */
 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;
+/**
+ * The built-in matcher: case-insensitive substring on the item's `value`, or on
+ * any of its `keywords`.
+ *
+ * The keywords arm is what makes "Toggle theme" findable by typing "dark mode".
+ * Matched with the same rule as the value rather than a stricter one — an alias
+ * the author wrote down is a stronger signal of intent than the label, not a
+ * weaker one.
+ */
+export declare function defaultCommandFilter(itemValue: string, search: string, keywords?: readonly 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
@@ -60,7 +60,7 @@ export declare const CommandProvider: {
  *   return (
  *     <Command>
  *       <CommandInput placeholder="Search…" />
- *       <CommandList>
+ *       <CommandList aria-label="Commands">
  *         <CommandLoading>Searching…</CommandLoading>
  *         <CommandEmpty>No results found.</CommandEmpty>
  *         <CommandGroup heading="Pages">