modern-cmdk 1.3.0 → 1.5.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,347 +16,24 @@ 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) — half-open [start, end) tuples, end exclusive */
-  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 by id */
-  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 step-weight configuration per recency bucket (hour/day/week/month/older) */
-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 */
-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;
-  /** Accepted but not read yet: Command.List uses fixed thresholds (on above 100 matches, off at 50 or fewer) (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 with the local mapGroupBy helper (core/utils/group-by.ts).
- */
-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 */
+  /** Promise that resolves to items; keep it stable across renders (state, a ref, or `useMemo`) or the boundary re-suspends on every render */
   readonly items: Promise<readonly CommandItem$1[]>;
   /** Fallback content while loading */
   readonly fallback?: ReactNode;
   /** 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()`. */
+/**
+ * Suspense-based async item loader that resolves a promise of items using React 19 `use()`.
+ *
+ * The `items` promise must be kept stable across renders (held in state, a ref, or `useMemo`):
+ * a new promise on every render, such as `items={fetchItems()}`, suspends again on every render.
+ */
 export declare function CommandAsyncItems({ items, fallback, children }: CommandAsyncItemsProps): ReactNode;
 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;
@@ -386,6 +65,7 @@ export declare function CommandInput({ ref, placeholder, onValueChange, ...props
 interface CommandItemProps extends Omit<ComponentPropsWithRef<"div">, "onSelect" | "value"> {
   readonly value: string;
   readonly keywords?: readonly string[];
+  /** Called when the item is selected by click, Enter or shortcut (no argument in 1.x; the value arrives in 2.0) */
   readonly onSelect?: () => void;
   readonly disabled?: boolean;
   readonly shortcut?: string;
@@ -471,7 +151,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;
@@ -496,7 +176,7 @@ interface CommandStateContextValue {
   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>;
@@ -507,7 +187,16 @@ interface CommandGroupContextValue {
 }
 interface CommandErrorBoundaryProps {
   readonly children: ReactNode;
-  readonly fallback?: ReactNode | ((error: Error) => ReactNode);
+  /**
+   * Rendered in place of the children after an error. A function receives the error and a `reset`
+   * callback that clears it, so the children render again (a retry button, for example).
+   */
+  readonly fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+  /**
+   * While the boundary shows its fallback, a change in these values (compared entry by entry with
+   * `Object.is`; a different length counts as a change) clears the error and renders the children again.
+   */
+  readonly resetKeys?: readonly unknown[];
   readonly onError?: (error: Error, errorInfo: ErrorInfo) => void;
 }
 interface CommandErrorBoundaryState {
@@ -518,6 +207,9 @@ export declare class CommandErrorBoundary extends Component<CommandErrorBoundary
   override state: CommandErrorBoundaryState;
   static getDerivedStateFromError(error: Error): CommandErrorBoundaryState;
   override componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+  override componentDidUpdate(prevProps: CommandErrorBoundaryProps, prevState: CommandErrorBoundaryState): void;
+  /** Clears the captured error so the children render again. */
+  reset: () => void;
   override render(): ReactNode;
 }
 interface UseCommandReturn {
@@ -594,4 +286,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 };