modern-cmdk 1.0.2 → 1.1.1

package/dist/react/index.d.mts

@@ -1,4 +1,4 @@
-import { D as CommandItem$1, L as GroupId, O as CommandMachineOptions, R as ItemId, d as CommandMachine, k as CommandState } from "../index-C6g94P7V.mjs";
+
 import { Component, ComponentPropsWithRef, Context, ErrorInfo, ReactNode } from "react";
 
 //#region src/react/activity.d.ts
@@ -20,6 +20,330 @@ declare function CommandActivity({
   children
 }: CommandActivityProps): ReactNode;
 //#endregion
+//#region src/core/search/types.d.ts
+/** Result of scoring a single item against a query */
+interface SearchResult {
+  readonly id: ItemId;
+  readonly score: number;
+  /** Character ranges that matched (for highlighting) — [start, end] tuples */
+  readonly matches: ReadonlyArray<readonly [start: number, end: number]>;
+}
+/** Search engine interface — pluggable into the state machine */
+interface SearchEngine extends Disposable {
+  /** Index items for fast lookup (call on registration) */
+  index(items: readonly CommandItem$1[]): void;
+  /** Search items by query, return ordered results — uses Iterator pipeline */
+  search(query: string, items: readonly CommandItem$1[]): IteratorObject<SearchResult>;
+  /** Remove items from index — uses Set.difference for efficient bulk removal */
+  remove(ids: ReadonlySet<ItemId>): void;
+  /** Clear the entire index */
+  clear(): void;
+  /** Dispose resources */
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#region src/core/types.d.ts
+/**
+* Branded type for command item IDs.
+* Prevents accidental mixing with plain strings at the type level.
+*
+* @example
+* ```ts
+* const id = itemId('copy');
+* // id has type ItemId, not string — catches type errors at compile time
+* ```
+*/
+declare const __itemIdBrand: unique symbol;
+type ItemId = string & {
+  readonly [__itemIdBrand]: never;
+};
+/**
+* Branded type for group IDs.
+* Prevents accidental mixing with plain strings or ItemId at the type level.
+*/
+declare const __groupIdBrand: unique symbol;
+type GroupId = string & {
+  readonly [__groupIdBrand]: never;
+};
+/**
+* A registered command item in the palette.
+* All fields are readonly — state machine creates new items on update.
+*/
+interface CommandItem$1 {
+  /** Unique identifier (branded type) */
+  readonly id: ItemId;
+  /** Display text — also used as the primary search target */
+  readonly value: string;
+  /** Additional searchable terms (matched but not displayed) */
+  readonly keywords?: readonly string[] | undefined;
+  /** Group this item belongs to (items without groupId are ungrouped) */
+  readonly groupId?: GroupId | undefined;
+  /** Keyboard shortcut string (e.g., "Ctrl+C", "Mod+K") */
+  readonly shortcut?: string | undefined;
+  /** Whether this item is disabled (excluded from filtering and selection) */
+  readonly disabled?: boolean | undefined;
+  /** Callback fired when this item is selected */
+  readonly onSelect?: (() => void) | undefined;
+  /** Arbitrary metadata attached to the item */
+  readonly data?: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+* A command group for categorizing items.
+* Groups are rendered with headings and sorted by priority.
+*/
+interface CommandGroup$1 {
+  /** Unique identifier (branded type) */
+  readonly id: GroupId;
+  /** Display heading text (rendered above the group's items) */
+  readonly heading?: string | undefined;
+  /** Sort priority — lower values appear first (default: 0) */
+  readonly priority?: number | undefined;
+}
+/**
+* Immutable state snapshot of the command palette.
+* Consumed by React via `useSyncExternalStore` — each mutation
+* produces a new object reference for efficient re-render detection.
+*/
+interface CommandState {
+  /** Current search query string */
+  readonly search: string;
+  /** Currently active (highlighted) item ID, or null if none */
+  readonly activeId: ItemId | null;
+  /** Ordered list of item IDs that pass the current filter */
+  readonly filteredIds: readonly ItemId[];
+  /** Map of group IDs to their visible item IDs */
+  readonly groupedIds: ReadonlyMap<GroupId, readonly ItemId[]>;
+  /** Count of visible items (shortcut for `filteredIds.length`) */
+  readonly filteredCount: number;
+  /** Whether async items are currently loading */
+  readonly loading: boolean;
+  /** Current page identifier (for multi-page navigation) */
+  readonly page: string;
+  /** Stack of previous pages for back-navigation */
+  readonly pageStack: readonly string[];
+  /** Whether the command palette dialog is open */
+  readonly open: boolean;
+  /** Temporal.Instant of the last state mutation (ES2026) */
+  readonly lastUpdated: Temporal.Instant;
+}
+/** All possible events the state machine accepts */
+type CommandEvent = {
+  readonly type: "SEARCH_CHANGE";
+  readonly query: string;
+} | {
+  readonly type: "ITEM_SELECT";
+  readonly id: ItemId;
+} | {
+  readonly type: "ITEM_ACTIVATE";
+  readonly id: ItemId;
+} | {
+  readonly type: "NAVIGATE";
+  readonly direction: "next" | "prev" | "first" | "last";
+} | {
+  readonly type: "PAGE_PUSH";
+  readonly page: string;
+} | {
+  readonly type: "PAGE_POP";
+} | {
+  readonly type: "OPEN";
+} | {
+  readonly type: "CLOSE";
+} | {
+  readonly type: "TOGGLE";
+} | {
+  readonly type: "ITEMS_LOADED";
+  readonly items: readonly CommandItem$1[];
+} | {
+  readonly type: "REGISTER_ITEM";
+  readonly item: CommandItem$1;
+} | {
+  readonly type: "UNREGISTER_ITEM";
+  readonly id: ItemId;
+} | {
+  readonly type: "REGISTER_GROUP";
+  readonly group: CommandGroup$1;
+} | {
+  readonly type: "UNREGISTER_GROUP";
+  readonly id: GroupId;
+};
+/** Frecency record for a single item */
+interface FrecencyRecord {
+  readonly frequency: number;
+  readonly lastUsed: Temporal.Instant;
+}
+/** Complete frecency data for persistence */
+interface FrecencyData {
+  readonly records: ReadonlyMap<ItemId, FrecencyRecord>;
+}
+/** Pluggable frecency storage interface */
+interface FrecencyStorage extends Disposable {
+  load(namespace: string): FrecencyData | Promise<FrecencyData>;
+  save(namespace: string, data: FrecencyData): void | Promise<void>;
+}
+/** Frecency exponential decay bucket configuration */
+interface FrecencyDecayConfig {
+  readonly hourWeight?: number | undefined;
+  readonly dayWeight?: number | undefined;
+  readonly weekWeight?: number | undefined;
+  readonly monthWeight?: number | undefined;
+  readonly olderWeight?: number | undefined;
+}
+/** Frecency configuration options */
+interface FrecencyOptions {
+  readonly enabled: boolean;
+  readonly storage?: FrecencyStorage | undefined;
+  readonly namespace?: string | undefined;
+  readonly decayConfig?: FrecencyDecayConfig | undefined;
+}
+/** Options for creating a command machine — const type param for narrowed option inference */
+interface CommandMachineOptions {
+  /** Pre-registered items to populate on creation */
+  readonly items?: readonly CommandItem$1[] | undefined;
+  /** Pre-registered groups for item categorization */
+  readonly groups?: readonly CommandGroup$1[] | undefined;
+  /** Custom filter function, or `false` to disable filtering entirely */
+  readonly filter?: ((item: CommandItem$1, query: string) => number | false) | false | undefined;
+  /** Accessible label for the command palette */
+  readonly label?: string | undefined;
+  /** Initial open state */
+  readonly open?: boolean | undefined;
+  /** Frecency configuration for usage-aware ranking */
+  readonly frecency?: FrecencyOptions | undefined;
+  /** Pluggable search engine — drop-in replacement for the default scorer (e.g., WASM engine) */
+  readonly search?: SearchEngine | undefined;
+  /** Callback fired when an item is selected */
+  readonly onSelect?: ((id: ItemId) => void) | undefined;
+  /** Callback fired when the active (highlighted) item changes */
+  readonly onActiveChange?: ((id: ItemId | null) => void) | undefined;
+  /** Callback fired when the dialog open state changes */
+  readonly onOpenChange?: ((open: boolean) => void) | undefined;
+  /** Callback fired when the search query changes */
+  readonly onSearchChange?: ((query: string) => void) | undefined;
+  /** Whether keyboard navigation loops from last to first item (default: true) */
+  readonly loop?: boolean | undefined;
+  /** Item count threshold for automatic virtualization (default: 100) */
+  readonly virtualizeThreshold?: number | undefined;
+}
+//#endregion
+//#region src/core/keyboard/parser.d.ts
+/**
+* Structured representation of a keyboard shortcut after parsing.
+* The `normalized` field provides a deterministic string for dedup and comparison.
+*/
+interface ParsedShortcut {
+  readonly key: string;
+  readonly meta: boolean;
+  readonly ctrl: boolean;
+  readonly shift: boolean;
+  readonly alt: boolean;
+  readonly raw: string;
+  readonly normalized: string;
+}
+//#endregion
+//#region src/core/keyboard/index.d.ts
+interface ShortcutBinding {
+  readonly shortcut: ParsedShortcut;
+  readonly itemId: ItemId;
+  readonly handler: () => void;
+}
+/**
+* Manages keyboard shortcut bindings with global keydown listening.
+* Supports `using` for automatic cleanup of both individual bindings and the
+* global document listener. Detects conflicts via Map.groupBy (ES2026).
+*/
+declare class KeyboardShortcutRegistry implements Disposable {
+  #private;
+  constructor(options?: {
+    enabled?: boolean;
+  });
+  /** Register a shortcut binding — returns Disposable for `using` auto-deregister */
+  register(shortcutStr: string, itemId: ItemId, handler: () => void): Disposable;
+  /** Unregister a shortcut by its string representation */
+  unregister(shortcutStr: string): void;
+  /** Unregister all shortcuts for a given item — Map spec allows deletion during iteration */
+  unregisterByItem(itemId: ItemId): void;
+  /** Check for conflicting shortcuts */
+  getConflicts(): ReadonlyMap<string, readonly ParsedShortcut[]>;
+  /** Enable or disable global shortcut listening */
+  setEnabled(enabled: boolean): void;
+  /** Get all registered bindings */
+  getBindings(): ReadonlyMap<string, ShortcutBinding>;
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#region src/core/registry.d.ts
+/**
+* Manages registration and lookup of command items and groups.
+* Uses ES2026 Set methods (union/intersection/difference) for efficient ID operations.
+* All registration methods return Disposable for automatic cleanup via `using`.
+*/
+declare class CommandRegistry implements Disposable {
+  #private;
+  /** Register an item — returns Disposable for `using` auto-deregister */
+  registerItem(item: CommandItem$1): Disposable;
+  /** Register multiple items at once — single Disposable for batch cleanup. for...of for hot path. */
+  registerItems(items: readonly CommandItem$1[]): Disposable;
+  /** Unregister a single item — O(1) Map/Set delete, indexOf+toSpliced for order */
+  unregisterItem(id: ItemId): void;
+  /** Bulk unregister using Set.difference (ES2026) — for...of for hot path */
+  unregisterItems(ids: ReadonlySet<ItemId>): void;
+  /** Register a group */
+  registerGroup(group: CommandGroup$1): Disposable;
+  /** Unregister a group */
+  unregisterGroup(id: GroupId): void;
+  /** Get an item by ID — O(1) */
+  getItem(id: ItemId): CommandItem$1 | undefined;
+  /** Get a group by ID — O(1) */
+  getGroup(id: GroupId): CommandGroup$1 | undefined;
+  /** Get all registered items in insertion order — cached between mutations */
+  getItems(): readonly CommandItem$1[];
+  /** Get all registered groups sorted by priority — cached between group mutations */
+  getGroups(): readonly CommandGroup$1[];
+  /** Get items grouped by groupId using Map.groupBy (ES2026) — direct Map, no Object.entries conversion */
+  getGroupedItems(): ReadonlyMap<GroupId, readonly CommandItem$1[]>;
+  /** Get item IDs as a Set — returns internal set (O(1), no allocation) */
+  getItemIds(): ReadonlySet<ItemId>;
+  /** Find intersection of registered items with a candidate set (ES2026 Set.intersection) */
+  intersectWith(candidateIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
+  /** Find items registered but not in a given set (ES2026 Set.difference) */
+  differenceFrom(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
+  /** Union of registered IDs with another set (ES2026 Set.union) */
+  unionWith(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
+  /** Check if registered items are a subset of the given set (ES2026 Set.isSubsetOf) */
+  isSubsetOf(otherIds: ReadonlySet<ItemId>): boolean;
+  /** Check if registered items are a superset of the given set (ES2026 Set.isSupersetOf) */
+  isSupersetOf(otherIds: ReadonlySet<ItemId>): boolean;
+  /** Check if registered items share no IDs with the given set (ES2026 Set.isDisjointFrom) */
+  isDisjointFrom(otherIds: ReadonlySet<ItemId>): boolean;
+  /** Symmetric difference between registered IDs and another set (ES2026 Set.symmetricDifference) */
+  symmetricDifferenceWith(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
+  /** Total number of registered items */
+  get size(): number;
+  /** Total number of registered groups */
+  get groupCount(): number;
+  /** Clear all items and groups */
+  clear(): void;
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#region src/core/machine.d.ts
+/** Command machine — explicit resource management via `using` */
+interface CommandMachine extends Disposable {
+  getState(): CommandState;
+  send(event: CommandEvent): void;
+  /** Subscribe to state changes — useSyncExternalStore-compatible (returns cleanup function) */
+  subscribe(listener: () => void): () => void;
+  /** Subscribe to full state changes — returns Disposable for `using` pattern */
+  subscribeState(listener: (state: CommandState) => void): Disposable;
+  getRegistry(): CommandRegistry;
+  getKeyboardRegistry(): KeyboardShortcutRegistry;
+  /** Get the current set of filtered item IDs — O(1) membership checks */
+  getFilteredIdSet(): ReadonlySet<ItemId>;
+  /** Get the index map for filtered IDs — O(1) positional lookup */
+  getFilteredIdIndex(): ReadonlyMap<ItemId, number>;
+  [Symbol.dispose](): void;
+}
+//#endregion
 //#region src/react/async-items.d.ts
 interface CommandAsyncItemsProps {
   /** Promise that resolves to items */
@@ -29,6 +353,7 @@ interface CommandAsyncItemsProps {
   /** Render function for resolved items */
   readonly children: (items: readonly CommandItem$1[]) => ReactNode;
 }
+/** Suspense-based async item loader that resolves a promise of items using React 19 `use()`. */
 declare function CommandAsyncItems({
   items,
   fallback,
@@ -37,6 +362,7 @@ declare function CommandAsyncItems({
 //#endregion
 //#region src/react/badge.d.ts
 interface CommandBadgeProps extends ComponentPropsWithRef<"span"> {}
+/** Inline badge for categorization or status indicators on command items. */
 declare function CommandBadge({
   ref,
   children,
@@ -52,15 +378,19 @@ interface CommandDialogProps extends CommandMachineOptions {
   readonly label?: string;
   readonly open?: boolean;
   readonly onOpenChange?: (open: boolean) => void;
+  /** Accessible description for screen readers (default: 'Type a command or search...') */
+  readonly description?: string;
   /** Container element for the portal (default: document.body) */
   readonly container?: HTMLElement | null;
 }
+/** Dialog variant that wraps the command palette in a Radix UI Dialog with focus trap and overlay. */
 declare function CommandDialog({
   children,
   className,
   overlayClassName,
   contentClassName,
   label,
+  description,
   open: controlledOpen,
   onOpenChange,
   container,
@@ -69,6 +399,7 @@ declare function CommandDialog({
 //#endregion
 //#region src/react/empty.d.ts
 interface CommandEmptyProps extends ComponentPropsWithRef<"div"> {}
+/** Rendered when no items match the current search query. */
 declare function CommandEmpty({
   ref,
   children,
@@ -84,6 +415,7 @@ interface CommandGroupProps extends ComponentPropsWithRef<"div"> {
   /** Force a specific ID */
   readonly forceId?: string;
 }
+/** Visual grouping container with an optional heading that hides when no items match. */
 declare function CommandGroup({
   ref,
   children,
@@ -102,6 +434,7 @@ interface CommandHighlightProps {
   /** Custom className for highlighted segments */
   readonly highlightClassName?: string;
 }
+/** Renders search match highlighting by splitting text at scored match ranges. */
 declare function CommandHighlight({
   text,
   ranges,
@@ -112,6 +445,7 @@ declare function CommandHighlight({
 interface CommandInputProps extends Omit<ComponentPropsWithRef<"input">, "value" | "onChange" | "type" | "role"> {
   readonly onValueChange?: (value: string) => void;
 }
+/** Combobox input that drives the command palette search state. */
 declare function CommandInput({
   ref,
   placeholder,
@@ -128,6 +462,7 @@ interface CommandItemProps extends Omit<ComponentPropsWithRef<"div">, "onSelect"
   readonly shortcut?: string;
   readonly forceId?: string;
 }
+/** Individual selectable item in the command list with keyboard and pointer activation. */
 declare function CommandItem({
   ref,
   children,
@@ -148,13 +483,17 @@ interface CommandListProps extends ComponentPropsWithRef<"div"> {
   readonly estimateSize?: number;
   /** Overscan count for virtualization (default: 8) */
   readonly overscan?: number;
+  /** Custom aria-live announcement formatter for i18n (receives filtered count, returns announcement text) */
+  readonly announceResults?: (count: number) => string;
 }
+/** Scrollable list container with auto-virtualization and aria-live announcements. */
 declare function CommandList({
   ref,
   children,
   virtualize,
   estimateSize,
   overscan,
+  announceResults,
   style,
   ...props
 }: CommandListProps): ReactNode;
@@ -164,6 +503,7 @@ interface CommandLoadingProps extends ComponentPropsWithRef<"div"> {
   /** Override the loading state detection */
   readonly loading?: boolean;
 }
+/** Shown during async operations, with configurable loading state override. */
 declare function CommandLoading({
   ref,
   children,
@@ -181,6 +521,7 @@ interface CommandPageProps {
   readonly id: CommandPageId | string;
   readonly children?: ReactNode;
 }
+/** Page navigation container that only renders when its ID matches the active page. */
 declare function CommandPage({
   id,
   children
@@ -188,6 +529,7 @@ declare function CommandPage({
 //#endregion
 //#region src/react/separator.d.ts
 interface CommandSeparatorProps extends ComponentPropsWithRef<"div"> {}
+/** Visual divider between items or groups, rendered as a presentational element. */
 declare function CommandSeparator({
   ref,
   ...props
@@ -198,6 +540,7 @@ interface CommandShortcutProps extends ComponentPropsWithRef<"kbd"> {
   /** Shortcut string to display (e.g., "Mod+K"). If not provided, reads from nearest Command.Item. */
   readonly shortcut?: string;
 }
+/** Keyboard shortcut display with platform-aware formatting (e.g., Cmd vs Ctrl). */
 declare function CommandShortcut({
   ref,
   shortcut,
@@ -211,6 +554,7 @@ interface CommandRootProps extends CommandMachineOptions {
   readonly className?: string;
   readonly label?: string;
 }
+/** Root compound component that provides the command state machine context to all children. */
 declare function CommandRoot({
   children,
   className,
@@ -286,6 +630,7 @@ interface CommandErrorBoundaryProps {
 interface CommandErrorBoundaryState {
   readonly error: Error | null;
 }
+/** Error boundary for graceful failure recovery in command subtrees. */
 declare class CommandErrorBoundary extends Component<CommandErrorBoundaryProps, CommandErrorBoundaryState> {
   state: CommandErrorBoundaryState;
   static getDerivedStateFromError(error: Error): CommandErrorBoundaryState;
@@ -303,6 +648,7 @@ interface UseCommandReturn {
   readonly filteredIdSet: ReadonlySet<ItemId>;
   readonly id: CommandRootId;
 }
+/** Core hook that binds a CommandMachine to React via useSyncExternalStore, useTransition, and useOptimistic. */
 declare function useCommand(machine: CommandMachine): UseCommandReturn;
 //#endregion
 //#region src/react/hooks/use-command-state.d.ts
@@ -371,7 +717,7 @@ interface VirtualizerReturn {
   readonly scrollToIndex: (index: number) => void;
   readonly measureElement: (element: HTMLElement | null) => void;
 }
+/** Lightweight virtualizer for large item lists using ResizeObserver and scroll tracking. */
 declare function useVirtualizer(options: VirtualizerOptions): VirtualizerReturn;
 //#endregion
-export { type ActivityMode, Command, CommandActivity, type CommandActivityProps, CommandAsyncItems, type CommandAsyncItemsProps, CommandBadge, type CommandBadgeProps, type CommandContextValue, CommandDialog, type CommandDialogProps, CommandEmpty, type CommandEmptyProps, CommandErrorBoundary, type CommandErrorBoundaryProps, CommandGroup, type CommandGroupContextValue, type CommandGroupProps, CommandHighlight, type CommandHighlightProps, CommandInput, type CommandInputProps, CommandItem, type CommandItemProps, CommandList, type CommandListProps, CommandLoading, type CommandLoadingProps, CommandPage, type CommandPageId, type CommandPageProps, type CommandRootId, type CommandRootProps, CommandSeparator, type CommandSeparatorProps, CommandShortcut, type CommandShortcutProps, CommandStableContext, type CommandStableContextValue, CommandStateContext, type CommandStateContextValue, type RegisterGroupOptions, type RegisterItemOptions, type UseCommandReturn, type VirtualItem, type VirtualizerOptions, type VirtualizerReturn, createKeydownHandler, useCommand, useCommandDevtools, useCommandState, useRegisterGroup, useRegisterItem, useVirtualizer };
-//# sourceMappingURL=index.d.mts.map
+export { type ActivityMode, Command, CommandActivity, type CommandActivityProps, CommandAsyncItems, type CommandAsyncItemsProps, CommandBadge, type CommandBadgeProps, type CommandContextValue, CommandDialog, type CommandDialogProps, CommandEmpty, type CommandEmptyProps, CommandErrorBoundary, type CommandErrorBoundaryProps, CommandGroup, type CommandGroupContextValue, type CommandGroupProps, CommandHighlight, type CommandHighlightProps, CommandInput, type CommandInputProps, CommandItem, type CommandItemProps, CommandList, type CommandListProps, CommandLoading, type CommandLoadingProps, CommandPage, type CommandPageId, type CommandPageProps, type CommandRootId, type CommandRootProps, CommandSeparator, type CommandSeparatorProps, CommandShortcut, type CommandShortcutProps, CommandStableContext, type CommandStableContextValue, CommandStateContext, type CommandStateContextValue, type RegisterGroupOptions, type RegisterItemOptions, type UseCommandReturn, type VirtualItem, type VirtualizerOptions, type VirtualizerReturn, createKeydownHandler, useCommand, useCommandDevtools, useCommandState, useRegisterGroup, useRegisterItem, useVirtualizer };