modern-cmdk 1.4.0 → 1.6.0

package/dist/core/index.d.mts

@@ -2,14 +2,23 @@
 interface SearchResult {
   readonly id: ItemId;
   readonly score: number;
-  /** Character ranges that matched (for highlighting) — half-open [start, end) tuples, end exclusive */
+  /**
+   * Character ranges that matched (for highlighting) — half-open [start, end) tuples, end exclusive. The
+   * ranges index the original `item.value`, not its lowercased copy. A match on keywords only reports
+   * `matches: []`: there is nothing in the value to highlight.
+   */
   readonly matches: ReadonlyArray<readonly [start: number, end: number]>;
 }
 /** A scoring function that evaluates a single item against a query */
 type ScorerFn = (query: string, item: CommandItem) => SearchResult | null;
 /** Search engine interface — pluggable into the state machine */
 interface SearchEngine extends Disposable {
-  /** Index items for fast lookup (call on registration) */
+  /**
+   * Index items for fast lookup. The machine calls it on registration (the initial items, ITEMS_LOADED,
+   * REGISTER_ITEM) and again on UPDATE_ITEM with the updated item, so an id that is already indexed must
+   * be replaced by the new item, not appended to the index. Indexing is incremental: ids not in `items`
+   * stay indexed.
+   */
   index(items: readonly CommandItem[]): void;
   /** Search items by query, return ordered results — uses Iterator pipeline */
   search(query: string, items: readonly CommandItem[]): IteratorObject<SearchResult>;
@@ -42,6 +51,12 @@ declare const __groupIdBrand: unique symbol;
 type GroupId = string & {
   readonly [__groupIdBrand]: never;
 };
+/**
+ * The `groupedIds` key of items that have no group. The value is an observable key of
+ * `CommandState.groupedIds` and stays `'__ungrouped'`. A group registered under this id shares the
+ * bucket: its items are listed with the ungrouped ones and the bucket takes its priority.
+ */
+export declare const UNGROUPED_GROUP_ID: GroupId;
 /** Create a branded {@link ItemId} from a plain string. Ensures well-formed Unicode. */
 export declare function itemId(id: string): ItemId;
 /** Create a branded {@link GroupId} from a plain string. Ensures well-formed Unicode. */
@@ -61,7 +76,7 @@ interface CommandItem {
   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) */
+  /** Whether this item is disabled: excluded from navigation and selection; rendered unless `disabledItems: 'hide'` */
   readonly disabled?: boolean | undefined;
   /** Callback fired when this item is selected */
   readonly onSelect?: (() => void) | undefined;
@@ -92,7 +107,12 @@ interface CommandState {
   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 */
+  /**
+   * Map of group IDs to their visible item IDs. The keys are in group priority order (lower first; ungrouped
+   * items and unregistered group ids count as 0, in first-appearance order), while `filteredIds` and
+   * `NAVIGATE` keep the search order: a renderer that draws by `groupedIds` shows the groups in this order,
+   * so arrow-key order and display order can differ when group priorities differ.
+   */
   readonly groupedIds: ReadonlyMap<GroupId, readonly ItemId[]>;
   /** Count of visible items (shortcut for `filteredIds.length`) */
   readonly filteredCount: number;
@@ -134,9 +154,16 @@ type CommandEvent = {
 } | {
   readonly type: "ITEMS_LOADED";
   readonly items: readonly CommandItem[];
+} | {
+  readonly type: "LOADING";
+  readonly source: string;
+  readonly pending: boolean;
 } | {
   readonly type: "REGISTER_ITEM";
   readonly item: CommandItem;
+} | {
+  readonly type: "UPDATE_ITEM";
+  readonly item: CommandItem;
 } | {
   readonly type: "UNREGISTER_ITEM";
   readonly id: ItemId;
@@ -172,7 +199,9 @@ interface FrecencyDecayConfig {
 }
 /** Frecency configuration options */
 interface FrecencyOptions {
-  readonly enabled: boolean;
+  /** Turns frecency tracking and re-ranking on. Default false. */
+  readonly enabled?: boolean | undefined;
+  /** Where the history persists; a storage you pass is yours to dispose, the engine disposes only the in-memory one it creates when you pass none. */
   readonly storage?: FrecencyStorage | undefined;
   readonly namespace?: string | undefined;
   readonly decayConfig?: FrecencyDecayConfig | undefined;
@@ -185,7 +214,10 @@ interface CommandMachineOptions {
   readonly items?: readonly CommandItem[] | undefined;
   /** Pre-registered groups for item categorization */
   readonly groups?: readonly CommandGroup[] | undefined;
-  /** Custom filter function, or `false` to disable filtering entirely */
+  /**
+   * Custom filter function, or `false` to disable filtering entirely. It returns a score: above 0 keeps the item
+   * (higher ranks first); 0, a negative score or `false` excludes it.
+   */
   readonly filter?: ((item: CommandItem, query: string) => number | false) | false | undefined;
   /** Accessible label for the command palette */
   readonly label?: string | undefined;
@@ -205,15 +237,31 @@ interface CommandMachineOptions {
   readonly onSearchChange?: ((query: string) => void) | undefined;
   /** Whether keyboard navigation loops from last to first item (default: true) */
   readonly loop?: boolean | undefined;
+  /**
+   * How disabled items are listed: `'show'` keeps them in `filteredIds` under every query (rendered with
+   * `aria-disabled`, never active, skipped by navigation and activation, not selectable); `'hide'` drops them
+   * from `filteredIds` in every branch (default: `'show'`)
+   */
+  readonly disabledItems?: "hide" | "show" | undefined;
+  /**
+   * What an item's keyboard shortcut does. `'direct'` (the default through 1.x) calls the item's `onSelect`
+   * and binds only items that have one; `'select'` dispatches `ITEM_SELECT` for the item, so the disabled guard,
+   * frecency, the select event and `options.onSelect` apply, and binds every enabled item with a shortcut. 2.0 flips
+   * the default to `'select'`. Under both, a disabled item is not bound: its shortcut does nothing and leaves the key to the page.
+   */
+  readonly shortcutAction?: "select" | "direct" | 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;
 }
-/** Default machine options */
+/**
+ * Default machine options. The machine reads `loop` and `open` from here when its options leave them out
+ * (the other options are opt-ins whose absence is their default); `virtualizeThreshold` is not read yet.
+ */
 export declare const DEFAULT_MACHINE_OPTIONS: Partial<CommandMachineOptions>;
 /** Initial state factory */
 export declare function createInitialState(options?: CommandMachineOptions): CommandState;
 /**
- * IndexedDB-backed frecency storage using idb-keyval.
+ * IndexedDB-backed frecency storage using idb-keyval's get, set and del.
  *
  * Persists frecency data across browser sessions. Implements both
  * `Disposable` and `AsyncDisposable` for use with `using` and `await using`.
@@ -255,15 +303,27 @@ export declare class IdbFrecencyStorage implements FrecencyStorage, AsyncDisposa
 export declare function computeFrecencyBonus(history: FrecencyRecord, now?: number, config?: FrecencyDecayConfig): number;
 /**
  * Stateful frecency engine that tracks item selection history and provides
- * ranking boosts for search results. Supports pluggable storage backends
- * and automatic flush on dispose. Uses Date.now() for timestamps.
+ * ranking boosts for search results. Supports pluggable storage backends.
+ * Dirty data is saved 1000 ms after the last `recordSelection`, when the page
+ * becomes hidden or is hidden for good (`visibilitychange`, `pagehide`), on
+ * `flush()` and on dispose; a save waits for a `load()` in flight, so it writes the merged
+ * history. Dispose disposes the storage only when the engine created it (no `storage`
+ * option): a storage the caller passes is the caller's to dispose. Uses Date.now() for
+ * timestamps.
  */
 export declare class FrecencyEngine implements Disposable, AsyncDisposable {
   #private;
   constructor(options: FrecencyOptions);
-  /** Load frecency data from storage */
+  /**
+   * Merge the data in storage into the engine: frequencies add, `lastUsed` takes the later
+   * time, and selections recorded before the load resolves are kept. Call it once per
+   * engine; a second load would add the persisted frequencies again. A save started while
+   * the load is in flight waits for it, so the history it writes is the merged one, and a load
+   * that never settles holds every save, and `await using`, forever. A failed load rejects here
+   * and turns persistence off for this engine: saving would replace a history it could not read.
+   */
   load(): Promise<void>;
-  /** Record a selection event for an item */
+  /** Record a selection event for an item and schedule a save 1000 ms after the last one */
   recordSelection(itemId: ItemId): void;
   /** Get frecency bonus for an item */
   getBonus(itemId: ItemId, now?: number): number;
@@ -273,12 +333,20 @@ export declare class FrecencyEngine implements Disposable, AsyncDisposable {
   getConfig(): FrecencyDecayConfig;
   /** Update decay configuration at runtime */
   setConfig(config: FrecencyDecayConfig): void;
-  /** Flush dirty data to storage */
+  /**
+   * Flush dirty data to storage and wait for every save in flight; saves run one after
+   * another, each after the load in flight (one that never settles holds them all), none after a
+   * rejected load, and a rejected save leaves the data dirty and rethrows to the flush that started it
+   */
   flush(): Promise<void>;
   /** Get the raw frecency data */
   getData(): FrecencyData;
-  /** Async dispose — flushes dirty data before cleanup. Use with `await using`. */
+  /**
+   * Async dispose — flushes dirty data, then disposes the storage the engine created, even
+   * when the save rejects (the rejection propagates). Use with `await using`.
+   */
   [Symbol.asyncDispose](): Promise<void>;
+  /** Sync dispose — starts the flush without awaiting it and disposes the storage the engine created once it settles */
   [Symbol.dispose](): void;
 }
 /**
@@ -340,7 +408,9 @@ 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 with the local mapGroupBy helper (core/utils/group-by.ts).
+ * global document listener. Every normalized shortcut keeps a stack of bindings, one per item: the later
+ * binding wins the keydown, disposing it restores the earlier one, and `getConflicts()` reports the keys with
+ * two or more bindings (through `detectConflicts`, which groups with the local mapGroupBy helper).
  */
 export declare class KeyboardShortcutRegistry implements Disposable {
   #private;
@@ -349,15 +419,18 @@ export declare class KeyboardShortcutRegistry implements Disposable {
   });
   /** 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 a shortcut by its string representation — every binding of that key */
   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 */
+  /**
+   * Unregister all shortcuts for a given item — only the stacks of the keys it is bound under are touched.
+   * `keep` names one shortcut whose binding stays (a re-bind then replaces it in place, see register).
+   */
+  unregisterByItem(itemId: ItemId, keep?: string): void;
+  /** Keys bound by two or more items (normalized shortcut -> the parsed shortcuts, earliest first) */
   getConflicts(): ReadonlyMap<string, readonly ParsedShortcut[]>;
   /** Enable or disable global shortcut listening */
   setEnabled(enabled: boolean): void;
-  /** Get all registered bindings */
+  /** The winning binding of every key (a snapshot: the later of the bindings that share a key) */
   getBindings(): ReadonlyMap<string, ShortcutBinding>;
   [Symbol.dispose](): void;
 }
@@ -372,7 +445,7 @@ export declare class CommandRegistry implements Disposable {
   registerItem(item: CommandItem): Disposable;
   /** Register multiple items at once — single Disposable for batch cleanup. for...of for hot path. */
   registerItems(items: readonly CommandItem[]): Disposable;
-  /** Unregister a single item — O(1) Map/Set delete, indexOf+toSpliced for order */
+  /** Unregister a single item — O(1) Map/Set delete */
   unregisterItem(id: ItemId): void;
   /** Bulk unregister — for...of for hot path */
   unregisterItems(ids: ReadonlySet<ItemId>): void;
@@ -432,20 +505,31 @@ interface CommandMachine extends Disposable {
 }
 /**
  * Creates a headless command palette state machine with search, frecency,
- * and keyboard shortcut support. Implements Disposable for `using` cleanup.
+ * and keyboard shortcut support. Implements Disposable and AsyncDisposable for
+ * `using` and `await using` cleanup (the latter awaits the pending frecency save).
  *
  * @example
  * ```ts
- * using machine = createCommandMachine({ items, loop: true });
- * machine.subscribe(() => console.log(machine.getState()));
+ * const machine = createCommandMachine({ items, loop: true });
+ * const unsubscribe = machine.subscribe(() => console.log(machine.getState()));
+ * machine.send({ type: 'SEARCH_CHANGE', query: 'app' }); // handled in the next frame
+ *
+ * // on teardown
+ * unsubscribe();
+ * machine[Symbol.dispose]();
  * ```
  */
-export declare function createCommandMachine(options?: CommandMachineOptions): CommandMachine;
+export declare function createCommandMachine(options?: CommandMachineOptions): CommandMachine & AsyncDisposable;
 /**
  * Public API: scores a command item against a search query.
  * Multi-strategy: exact → prefix → substring → word-boundary → fuzzy.
  * Returns null if no match. For batch use, prefer the search engine
  * which pre-caches lowercase and normalizes query once.
+ *
+ * `matches` are half-open ranges into `item.value` itself (UTF-16 indices of the original
+ * string, even where lowercasing changes its length, as 'İ' → 'i̇' does). A keyword has no
+ * position in the label: when a keyword outscores the value, `matches` keeps the value's own
+ * ranges if the value matched and is `[]` otherwise.
  */
 export declare function scoreItem(query: string, item: CommandItem): SearchResult | null;
 /**
@@ -463,9 +547,10 @@ interface SearchEngineOptions {
   readonly scorer?: ScorerFn | undefined;
 }
 /**
- * Creates a search engine with pluggable scorer and incremental filtering.
- * When the query extends the previous one, only prior matches are re-scored.
- * Pre-caches lowercase at index time — zero toLowerCase() calls during search.
+ * Creates a search engine with pluggable scorer.
+ * With the default scorer, a query that extends the previous one (compared lowercased) re-scores
+ * only the prior matches; a custom scorer is called for every item on every non-empty query.
+ * Pre-caches lowercase at index time; indexed items are not re-lowered during search.
  * Uses Iterator Helpers (ES2025) for result pipelines.
  */
 export declare function createSearchEngine(options?: SearchEngineOptions): SearchEngine;
@@ -499,18 +584,19 @@ interface TelemetryMiddleware {
  * ```
  */
 export declare function createTelemetryMiddleware(hooks: CommandTelemetryHooks): TelemetryMiddleware;
-type EventMap = {
-  [key: string]: unknown;
-};
 /**
  * Type-safe event emitter with strong references and Disposable subscriptions.
+ * `T` maps event names to payload types; an interface or a type alias both work (`object`, not an index signature, which an interface lacks).
  * Returns Disposable from `on()` for automatic unsubscription via `using`.
  */
-export declare class TypedEmitter<T extends EventMap> implements Disposable {
+export declare class TypedEmitter<T extends object> implements Disposable {
   #private;
   /** Subscribe to an event. Returns a Disposable that removes the listener when disposed. */
   on<K extends keyof T>(event: K, listener: (data: T[K]) => void): Disposable;
-  /** Emit an event to all listeners. Snapshots the set to prevent live-iteration issues. */
+  /**
+   * Emit an event to all listeners. Snapshots the set to prevent live-iteration issues.
+   * A throwing listener does not stop the later ones: its error is rethrown from a microtask, as the scheduler does.
+   */
   emit<K extends keyof T>(event: K, data: T[K]): void;
   /** Check if any listeners exist for an event */
   has<K extends keyof T>(event: K): boolean;
@@ -522,7 +608,8 @@ export declare class TypedEmitter<T extends EventMap> implements Disposable {
 }
 /**
  * Batched update scheduler that coalesces state updates into a single tick.
- * Uses requestAnimationFrame in browsers, queueMicrotask in Node.js/tests.
+ * Uses requestAnimationFrame in browsers, queueMicrotask where requestAnimationFrame is absent (Node.js, SSR).
+ * flush() synchronously applies the updates pending when it is called, in the order scheduled; one scheduled during the flush runs on the next frame or microtask.
  */
 interface Scheduler extends Disposable {
   schedule(update: () => void): void;
@@ -531,7 +618,7 @@ interface Scheduler extends Disposable {
 }
 /**
  * Creates a batched update scheduler. Coalesces rapid state updates into a single
- * execution pass using rAF (browser) or queueMicrotask (Node.js).
+ * execution pass using rAF (browser) or queueMicrotask (where rAF is absent: Node.js, SSR).
  */
 export declare function createScheduler(): Scheduler;
 export type { CommandEvent, CommandGroup, CommandItem, CommandMachine, CommandMachineOptions, CommandState, CommandTelemetryHooks, FrecencyData, FrecencyDecayConfig, FrecencyOptions, FrecencyRecord, FrecencyStorage, GroupId, ItemId, ParsedShortcut, Scheduler, ScorerFn, SearchEngine, SearchResult, TelemetryMiddleware };