modern-cmdk 1.2.2 → 1.3.0

package/dist/react/index.d.mts

@@ -1,6 +1,5 @@
 
 import { Component, ComponentPropsWithRef, Context, ErrorInfo, ReactNode } from "react";
-//#region src/react/activity.d.ts
 /** 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. */
@@ -10,18 +9,16 @@ interface CommandActivityProps {
   readonly children: ReactNode;
 }
 /**
- * Wraps content in React 19.3.0-canary Activity API.
+ * Wraps content in React's <Activity> API (React 19.2+).
  * When mode="hidden", the component tree is preserved in memory but not rendered.
  * Falls back to conditional rendering if Activity is unavailable.
  */
 export declare function CommandActivity({ mode, 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 */
+  /** 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 */
@@ -30,15 +27,13 @@ interface SearchEngine extends Disposable {
   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 items from index by id */
   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.
@@ -177,7 +172,7 @@ interface FrecencyStorage extends Disposable {
   load(namespace: string): FrecencyData | Promise<FrecencyData>;
   save(namespace: string, data: FrecencyData): void | Promise<void>;
 }
-/** Frecency exponential decay bucket configuration */
+/** Frecency step-weight configuration per recency bucket (hour/day/week/month/older) */
 interface FrecencyDecayConfig {
   readonly hourWeight?: number | undefined;
   readonly dayWeight?: number | undefined;
@@ -192,7 +187,7 @@ interface FrecencyOptions {
   readonly namespace?: string | undefined;
   readonly decayConfig?: FrecencyDecayConfig | undefined;
 }
-/** Options for creating a command machine — const type param for narrowed option inference */
+/** Options for creating a command machine */
 interface CommandMachineOptions {
   /** Pre-registered items to populate on creation */
   readonly items?: readonly CommandItem$1[] | undefined;
@@ -218,11 +213,9 @@ interface CommandMachineOptions {
   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) */
+  /** 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;
 }
-//#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.
@@ -236,8 +229,6 @@ interface ParsedShortcut {
   readonly raw: string;
   readonly normalized: string;
 }
-//#endregion
-//#region src/core/keyboard/index.d.ts
 interface ShortcutBinding {
   readonly shortcut: ParsedShortcut;
   readonly itemId: ItemId;
@@ -246,7 +237,7 @@ interface ShortcutBinding {
 /**
  * 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).
+ * global document listener. Detects conflicts with the local mapGroupBy helper (core/utils/group-by.ts).
  */
 declare class KeyboardShortcutRegistry implements Disposable {
   #private;
@@ -267,8 +258,6 @@ declare class KeyboardShortcutRegistry implements Disposable {
   getBindings(): ReadonlyMap<string, ShortcutBinding>;
   [Symbol.dispose](): void;
 }
-//#endregion
-//#region src/core/registry.d.ts
 /**
  * Manages registration and lookup of command items and groups.
  * Uses set operation helpers (union/intersection/difference) for efficient ID operations.
@@ -322,8 +311,6 @@ declare class CommandRegistry implements Disposable {
   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;
@@ -340,8 +327,6 @@ interface CommandMachine extends Disposable {
   getFilteredIdIndex(): ReadonlyMap<ItemId, number>;
   [Symbol.dispose](): void;
 }
-//#endregion
-//#region src/react/async-items.d.ts
 interface CommandAsyncItemsProps {
   /** Promise that resolves to items */
   readonly items: Promise<readonly CommandItem$1[]>;
@@ -352,13 +337,9 @@ interface CommandAsyncItemsProps {
 }
 /** Suspense-based async item loader that resolves a promise of items using React 19 `use()`. */
 export declare function CommandAsyncItems({ items, fallback, children }: CommandAsyncItemsProps): ReactNode;
-//#endregion
-//#region src/react/badge.d.ts
 interface CommandBadgeProps extends ComponentPropsWithRef<"span"> {}
 /** Inline badge for categorization or status indicators on command items. */
 export declare function CommandBadge({ ref, children, ...props }: CommandBadgeProps): ReactNode;
-//#endregion
-//#region src/react/dialog.d.ts
 interface CommandDialogProps extends CommandMachineOptions {
   readonly children?: ReactNode;
   readonly className?: string;
@@ -374,13 +355,9 @@ interface CommandDialogProps extends CommandMachineOptions {
 }
 /** 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;
-//#endregion
-//#region src/react/empty.d.ts
 interface CommandEmptyProps extends ComponentPropsWithRef<"div"> {}
 /** Rendered when no items match the current search query. */
 export declare function CommandEmpty({ ref, children, ...props }: CommandEmptyProps): ReactNode;
-//#endregion
-//#region src/react/group.d.ts
 interface CommandGroupProps extends ComponentPropsWithRef<"div"> {
   /** Heading text displayed above the group */
   readonly heading?: string;
@@ -391,27 +368,21 @@ interface CommandGroupProps extends ComponentPropsWithRef<"div"> {
 }
 /** Visual grouping container with an optional heading that hides when no items match. */
 export declare function CommandGroup({ ref, children, heading, priority, forceId, ...props }: CommandGroupProps): ReactNode;
-//#endregion
-//#region src/react/highlight.d.ts
 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;
 }
 /** Renders search match highlighting by splitting text at scored match ranges. */
 export declare function CommandHighlight({ text, ranges, highlightClassName }: CommandHighlightProps): ReactNode;
-//#endregion
-//#region src/react/input.d.ts
 interface CommandInputProps extends Omit<ComponentPropsWithRef<"input">, "value" | "onChange" | "type" | "role"> {
   readonly onValueChange?: (value: string) => void;
 }
 /** Combobox input that drives the command palette search state. */
 export declare function CommandInput({ ref, placeholder, onValueChange, ...props }: CommandInputProps): ReactNode;
-//#endregion
-//#region src/react/item.d.ts
 interface CommandItemProps extends Omit<ComponentPropsWithRef<"div">, "onSelect" | "value"> {
   readonly value: string;
   readonly keywords?: readonly string[];
@@ -422,8 +393,6 @@ interface CommandItemProps extends Omit<ComponentPropsWithRef<"div">, "onSelect"
 }
 /** Individual selectable item in the command list with keyboard and pointer activation. */
 export declare function CommandItem({ ref, children, value, keywords, onSelect, disabled, shortcut, forceId, ...props }: CommandItemProps): ReactNode;
-//#endregion
-//#region src/react/list.d.ts
 interface CommandListProps extends ComponentPropsWithRef<"div"> {
   /** Override automatic virtualization (default: auto at >100 items, false to opt-out) */
   readonly virtualize?: boolean;
@@ -436,16 +405,12 @@ interface CommandListProps extends ComponentPropsWithRef<"div"> {
 }
 /** Scrollable list container with auto-virtualization and aria-live announcements. */
 export declare function CommandList({ ref, children, virtualize, estimateSize, overscan, announceResults, style, ...props }: CommandListProps): ReactNode;
-//#endregion
-//#region src/react/loading.d.ts
 interface CommandLoadingProps extends ComponentPropsWithRef<"div"> {
   /** Override the loading state detection */
   readonly loading?: boolean;
 }
 /** Shown during async operations, with configurable loading state override. */
 export declare function CommandLoading({ ref, children, loading: loadingOverride, ...props }: CommandLoadingProps): ReactNode;
-//#endregion
-//#region src/react/page.d.ts
 /** Branded page identifier */
 type CommandPageId = string & {
   readonly __brand: "CommandPageId";
@@ -457,21 +422,15 @@ interface CommandPageProps {
 }
 /** Page navigation container that only renders when its ID matches the active page. */
 export declare function CommandPage({ id, children }: CommandPageProps): ReactNode;
-//#endregion
-//#region src/react/separator.d.ts
 interface CommandSeparatorProps extends ComponentPropsWithRef<"div"> {}
 /** Visual divider between items or groups, rendered as a presentational element. */
 export declare function CommandSeparator({ ref, ...props }: CommandSeparatorProps): ReactNode;
-//#endregion
-//#region src/react/shortcut.d.ts
 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). */
 export declare function CommandShortcut({ ref, shortcut, children, ...props }: CommandShortcutProps): ReactNode;
-//#endregion
-//#region src/react/command.d.ts
 interface CommandRootProps extends CommandMachineOptions {
   readonly children?: ReactNode;
   readonly className?: string;
@@ -496,8 +455,6 @@ export declare const Command: typeof CommandRoot & {
   readonly AsyncItems: typeof CommandAsyncItems;
   readonly Activity: typeof CommandActivity;
 };
-//#endregion
-//#region src/react/context.d.ts
 /** Branded newtype for the root instance ID */
 type CommandRootId = string & {
   readonly __brand: "CommandRootId";
@@ -506,6 +463,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;
@@ -533,6 +491,7 @@ 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). */
@@ -546,8 +505,6 @@ interface CommandGroupContextValue {
   readonly groupId: string;
   readonly headingId: string;
 }
-//#endregion
-//#region src/react/error-boundary.d.ts
 interface CommandErrorBoundaryProps {
   readonly children: ReactNode;
   readonly fallback?: ReactNode | ((error: Error) => ReactNode);
@@ -563,46 +520,40 @@ export declare class CommandErrorBoundary extends Component<CommandErrorBoundary
   override componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
   override render(): ReactNode;
 }
-//#endregion
-//#region src/react/hooks/use-command.d.ts
 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;
-//#endregion
-//#region src/react/hooks/use-command-state.d.ts
 /** Get the full command state with proper subscription */
 export declare function useCommandState(): CommandState;
 /** Get a selected slice of command state — only re-renders when selected value changes */
 export declare function useCommandState<T>(selector: (state: CommandState) => T): T;
-//#endregion
-//#region src/react/hooks/use-devtools.d.ts
 /**
  * Exposes command palette internals to browser devtools.
- * Only active in development — completely tree-shaken in production builds.
+ * Development only: the effect is gated on `process.env.NODE_ENV` and returns early in
+ * production builds (the hook itself still ships). Call it from a component rendered inside
+ * `<Command>`: outside one there is no machine to inspect and the hook does nothing.
  *
  * @example
  * ```tsx
- * function MyPalette() {
+ * function DevtoolsBridge() {
  *   useCommandDevtools('main');
- *   return <Command>...</Command>;
+ *   return null;
  * }
  * ```
  */
 export declare function useCommandDevtools(label?: string): void;
-//#endregion
-//#region src/react/hooks/use-keyboard.d.ts
 /** Create a keydown handler for command palette keyboard navigation */
 export declare function createKeydownHandler(machine: CommandMachine, getState: () => CommandState): (event: KeyboardEvent) => void;
-//#endregion
-//#region src/react/hooks/use-register.d.ts
 /** Options for item registration */
 interface RegisterItemOptions {
   readonly keywords?: readonly string[];
@@ -622,8 +573,6 @@ interface RegisterGroupOptions {
 }
 /** Register a command group with the machine — auto-deregisters on unmount */
 export declare function useRegisterGroup(heading?: string, options?: RegisterGroupOptions): GroupId;
-//#endregion
-//#region src/react/hooks/use-virtualizer.d.ts
 interface VirtualizerOptions {
   readonly count: number;
   readonly estimateSize: number;
@@ -645,5 +594,4 @@ interface VirtualizerReturn {
 }
 /** Lightweight virtualizer for large item lists using ResizeObserver and scroll tracking. */
 export declare function useVirtualizer(options: VirtualizerOptions): VirtualizerReturn;
-//#endregion
 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 };