@bw-ui/command-palette/src/index.d.ts

Beautiful, accessible command palette for the web. Zero dependencies.

/**
 * ============================================================================
 * BW Command Palette - Type Definitions
 * ============================================================================
 */

export interface BWCommand {
  id: string;
  label: string;
  icon?: string | HTMLElement;
  shortcut?: string;
  keywords?: string[];
  group?: string;
  description?: string;
  disabled?: boolean;
  hidden?: boolean;
  children?: BWCommand[];
  action?: (command: BWCommand) => void | Promise<void>;
  meta?: Record<string, unknown>;
}

export type CommandProvider =
  | BWCommand[]
  | ((query: string) => BWCommand[] | Promise<BWCommand[]>);

export interface BWCommandPaletteOptions {
  trigger?: string | false;
  commands?: CommandProvider;
  placeholder?: string;
  emptyMessage?: string;
  loadingMessage?: string;
  closeOnSelect?: boolean;
  closeOnClickOutside?: boolean;
  closeOnEscape?: boolean;
  maxResults?: number;
  debounceMs?: number;
  rememberRecent?: boolean;
  maxRecent?: number;
  theme?: 'light' | 'dark' | 'system';
  width?: string;
  maxHeight?: string;
  zIndex?: number;
  animationDuration?: number;
  onOpen?: () => void;
  onClose?: () => void;
  onSelect?: (command: BWCommand) => void;
  onQueryChange?: (query: string) => void;
}

export interface BWFuzzyMatch {
  command: BWCommand;
  score: number;
  matches: number[];
}

export declare class BWCommandPalette {
  constructor(options?: BWCommandPaletteOptions);

  mount(target: string | HTMLElement): this;
  open(): this;
  close(): this;
  toggle(): this;

  setCommands(commands: BWCommand[]): this;
  addCommand(command: BWCommand): this;
  removeCommand(id: string): this;

  on(event: 'open', callback: () => void): this;
  on(event: 'close', callback: () => void): this;
  on(event: 'select', callback: (command: BWCommand) => void): this;
  on(event: 'query', callback: (query: string) => void): this;
  on(
    event: 'navigate',
    callback: (data: { index: number; command: BWCommand | null }) => void
  ): this;

  off(event: string, callback: Function): this;

  destroy(): void;
}

export declare function fuzzyMatch(
  query: string,
  text: string
): { score: number; matches: number[] } | null;

export declare function searchCommands(
  query: string,
  commands: BWCommand[],
  maxResults?: number
): BWFuzzyMatch[];

export declare function highlightMatches(
  text: string,
  matches: number[]
): string;

export declare function parseHotkey(hotkey: string): {
  key: string;
  ctrl: boolean;
  meta: boolean;
  alt: boolean;
  shift: boolean;
  mod: boolean;
};

export declare function matchesHotkey(
  event: KeyboardEvent,
  hotkey: ReturnType<typeof parseHotkey>
): boolean;

export declare function formatHotkey(hotkey: string): string;

export declare function createRecentHistory(options?: {
  maxRecent?: number;
  storageKey?: string;
  persist?: boolean;
}): {
  add: (commandId: string) => void;
  get: () => string[];
  clear: () => void;
  getScore: (commandId: string) => number;
};