modern-cmdk 1.2.3 → 1.4.0

package/dist/react/index.d.mts

@@ -1,5 +1,7 @@
 
+import { CommandDialog, CommandDialogProps } from "./dialog.mjs";
 import { Component, ComponentPropsWithRef, Context, ErrorInfo, ReactNode } from "react";
+import { CommandItem as CommandItem$1, CommandMachine, CommandMachineOptions, CommandState, GroupId, ItemId } from "modern-cmdk";
 /** Activity mode — maps directly to React's Activity API */
 type ActivityMode = "visible" | "hidden";
 /** Props for the CommandActivity wrapper that controls visibility via React's Activity API. */
@@ -14,319 +16,6 @@ interface CommandActivityProps {
  * Falls back to conditional rendering if Activity is unavailable.
  */
 export declare function CommandActivity({ mode, children }: CommandActivityProps): ReactNode;
-/** 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;
-}
-/**
- * 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;
-  /** Epoch-millisecond timestamp of the last state mutation */
-  readonly lastUpdated: number;
-}
-/** 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;
-  /** Epoch-millisecond timestamp of last usage */
-  readonly lastUsed: number;
-}
-/** 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;
-}
-/**
- * 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;
-}
-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;
-}
-/**
- * Manages registration and lookup of command items and groups.
- * Uses set operation helpers (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 — 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 — 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 */
-  intersectWith(candidateIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
-  /** Find items registered but not in a given set */
-  differenceFrom(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
-  /** Union of registered IDs with another set */
-  unionWith(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
-  /** Check if registered items are a subset of the given set */
-  isSubsetOf(otherIds: ReadonlySet<ItemId>): boolean;
-  /** Check if registered items are a superset of the given set */
-  isSupersetOf(otherIds: ReadonlySet<ItemId>): boolean;
-  /** Check if registered items share no IDs with the given set */
-  isDisjointFrom(otherIds: ReadonlySet<ItemId>): boolean;
-  /** Symmetric difference between registered IDs and another set */
-  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;
-}
-/** 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;
-}
 interface CommandAsyncItemsProps {
   /** Promise that resolves to items */
   readonly items: Promise<readonly CommandItem$1[]>;
@@ -340,21 +29,6 @@ export declare function CommandAsyncItems({ items, fallback, children }: Command
 interface CommandBadgeProps extends ComponentPropsWithRef<"span"> {}
 /** Inline badge for categorization or status indicators on command items. */
 export declare function CommandBadge({ ref, children, ...props }: CommandBadgeProps): ReactNode;
-interface CommandDialogProps extends CommandMachineOptions {
-  readonly children?: ReactNode;
-  readonly className?: string;
-  readonly overlayClassName?: string;
-  readonly contentClassName?: string;
-  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. */
-export declare function CommandDialog({ children, className, overlayClassName, contentClassName, label, description, open: controlledOpen, onOpenChange, container, ...machineOptions }: CommandDialogProps): ReactNode;
 interface CommandEmptyProps extends ComponentPropsWithRef<"div"> {}
 /** Rendered when no items match the current search query. */
 export declare function CommandEmpty({ ref, children, ...props }: CommandEmptyProps): ReactNode;
@@ -371,7 +45,7 @@ export declare function CommandGroup({ ref, children, heading, priority, forceId
 interface CommandHighlightProps {
   /** The full text to display */
   readonly text: string;
-  /** Match ranges from search scorer — [start, end] tuples */
+  /** Match ranges from the search scorer — half-open [start, end) tuples, end exclusive */
   readonly ranges: ReadonlyArray<readonly [start: number, end: number]>;
   /** Custom className for highlighted segments */
   readonly highlightClassName?: string;
@@ -463,6 +137,7 @@ type CommandRootId = string & {
 interface CommandContextValue {
   readonly machine: CommandMachine;
   readonly state: CommandState;
+  /** True while an optimistic active-item transition is in flight (search updates never set it). */
   readonly isPending: boolean;
   readonly updateSearch: (query: string) => void;
   readonly setOptimisticActiveId: (id: ItemId | null) => void;
@@ -470,7 +145,7 @@ interface CommandContextValue {
   readonly filteredIdSet: ReadonlySet<ItemId>;
   /** IDs currently visible in virtual viewport + overscan. null = not virtualizing (render all filtered). */
   readonly visibleIdSet: ReadonlySet<ItemId> | null;
-  /** Map of visible item IDs to their translateY pixel offsets. null = not virtualizing. */
+  /** Map of visible item IDs to their translate offsets in px. null = not virtualizing. */
   readonly virtualPositionMap: ReadonlyMap<ItemId, number> | null;
   readonly rootId: CommandRootId;
   readonly listId: string;
@@ -490,11 +165,12 @@ interface CommandStableContextValue {
 /** State context — values that change on every search/navigation */
 interface CommandStateContextValue {
   readonly state: CommandState;
+  /** True while an optimistic active-item transition is in flight (search updates never set it). */
   readonly isPending: boolean;
   readonly filteredIdSet: ReadonlySet<ItemId>;
   /** IDs currently visible in virtual viewport + overscan. null = not virtualizing (render all filtered). */
   readonly visibleIdSet: ReadonlySet<ItemId> | null;
-  /** Map of visible item IDs to their translateY pixel offsets. null = not virtualizing. */
+  /** Map of visible item IDs to their translate offsets in px. null = not virtualizing. */
   readonly virtualPositionMap: ReadonlyMap<ItemId, number> | null;
 }
 export declare const CommandStableContext: Context<CommandStableContextValue | null>;
@@ -520,14 +196,16 @@ export declare class CommandErrorBoundary extends Component<CommandErrorBoundary
 }
 interface UseCommandReturn {
   readonly state: CommandState;
+  /** True while an optimistic active-item transition is in flight. Search updates never set it: the machine applies them on its own scheduler tick, outside React. */
   readonly isPending: boolean;
+  /** Queue a search query on the machine. Not a React update: Command.Input owns the urgent input value. */
   readonly updateSearch: (query: string) => void;
   readonly setOptimisticActiveId: (id: ItemId | null) => void;
   /** O(1) membership set for filtered items — used by Item component */
   readonly filteredIdSet: ReadonlySet<ItemId>;
   readonly id: CommandRootId;
 }
-/** Core hook that binds a CommandMachine to React via useSyncExternalStore, useTransition, and useOptimistic. */
+/** Core hook that binds a CommandMachine to React via useSyncExternalStore, useOptimistic, and a transition for optimistic active-item updates. */
 export declare function useCommand(machine: CommandMachine): UseCommandReturn;
 /** Get the full command state with proper subscription */
 export declare function useCommandState(): CommandState;
@@ -590,4 +268,4 @@ interface VirtualizerReturn {
 }
 /** Lightweight virtualizer for large item lists using ResizeObserver and scroll tracking. */
 export declare function useVirtualizer(options: VirtualizerOptions): VirtualizerReturn;
-export type { ActivityMode, CommandActivityProps, CommandAsyncItemsProps, CommandBadgeProps, CommandContextValue, CommandDialogProps, CommandEmptyProps, CommandErrorBoundaryProps, CommandGroupContextValue, CommandGroupProps, CommandHighlightProps, CommandInputProps, CommandItemProps, CommandListProps, CommandLoadingProps, CommandPageId, CommandPageProps, CommandRootId, CommandRootProps, CommandSeparatorProps, CommandShortcutProps, CommandStableContextValue, CommandStateContextValue, RegisterGroupOptions, RegisterItemOptions, UseCommandReturn, VirtualItem, VirtualizerOptions, VirtualizerReturn };
+export { type ActivityMode, type CommandActivityProps, type CommandAsyncItemsProps, type CommandBadgeProps, type CommandContextValue, CommandDialog, type CommandDialogProps, type CommandEmptyProps, type CommandErrorBoundaryProps, type CommandGroupContextValue, type CommandGroupProps, type CommandHighlightProps, type CommandInputProps, type CommandItemProps, type CommandListProps, type CommandLoadingProps, type CommandPageId, type CommandPageProps, type CommandRootId, type CommandRootProps, type CommandSeparatorProps, type CommandShortcutProps, type CommandStableContextValue, type CommandStateContextValue, type RegisterGroupOptions, type RegisterItemOptions, type UseCommandReturn, type VirtualItem, type VirtualizerOptions, type VirtualizerReturn };