use-kbd 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,7 +1,16 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
-import { ReactNode, RefObject, CSSProperties, ComponentType } from 'react';
+import { ReactNode, ComponentType, RefObject, SVGProps, CSSProperties } from 'react';
 
+/**
+ * Modifier keys state
+ */
+interface Modifiers {
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+}
 /**
  * Represents a single key press (possibly with modifiers)
  */
@@ -9,19 +18,73 @@ interface KeyCombination {
     /** The main key (lowercase, e.g., 'k', 'enter', 'arrowup') */
     key: string;
     /** Modifier keys pressed */
-    modifiers: {
-        ctrl: boolean;
-        alt: boolean;
-        shift: boolean;
-        meta: boolean;
-    };
+    modifiers: Modifiers;
 }
 /**
  * Represents a hotkey - either a single key or a sequence of keys.
  * Single key: [{ key: 'k', modifiers: {...} }]
  * Sequence: [{ key: '2', ... }, { key: 'w', ... }]
+ * @deprecated Use KeySeq for new code
  */
 type HotkeySequence = KeyCombination[];
+/**
+ * A single element in a key sequence (sum type).
+ * - 'key': exact key match (with optional modifiers)
+ * - 'digit': matches any single digit 0-9 (\d)
+ * - 'digits': matches one or more digits (\d+)
+ */
+type SeqElem = {
+    type: 'key';
+    key: string;
+    modifiers: Modifiers;
+} | {
+    type: 'digit';
+} | {
+    type: 'digits';
+};
+/**
+ * A key sequence pattern (array of sequence elements)
+ */
+type KeySeq = SeqElem[];
+/**
+ * Sequence element with match state (for tracking during input).
+ * - 'key': has `matched` flag
+ * - 'digit': has captured `value`
+ * - 'digits': has captured `value` or in-progress `partial` string
+ */
+type SeqElemState = {
+    type: 'key';
+    key: string;
+    modifiers: Modifiers;
+    matched?: true;
+} | {
+    type: 'digit';
+    value?: number;
+} | {
+    type: 'digits';
+    value?: number;
+    partial?: string;
+};
+/**
+ * Sequence match state - tracks progress through a sequence with captures
+ */
+type SeqMatchState = SeqElemState[];
+/**
+ * Extract captured values from a completed sequence match
+ */
+declare function extractCaptures(state: SeqMatchState): number[];
+/**
+ * Check if a SeqElem is a digit placeholder
+ */
+declare function isDigitPlaceholder(elem: SeqElem): elem is {
+    type: 'digit';
+} | {
+    type: 'digits';
+};
+/**
+ * Count digit placeholders in a sequence
+ */
+declare function countPlaceholders(seq: KeySeq): number;
 /**
  * Platform-aware display format for a key combination or sequence
  */
@@ -53,6 +116,8 @@ interface RecordHotkeyResult {
     pendingKeys: HotkeySequence;
     /** The key currently being held (for live UI feedback during recording) */
     activeKeys: KeyCombination | null;
+    /** The timeout duration for sequences (ms) */
+    sequenceTimeout: number;
     /**
      * @deprecated Use `sequence` instead
      */
@@ -72,7 +137,9 @@ interface RecordHotkeyOptions {
     onShiftTab?: () => void;
     /** Prevent default on captured keys (default: true) */
     preventDefault?: boolean;
-    /** Timeout in ms before sequence is submitted (default: 1000) */
+    /** Timeout in ms before sequence is submitted (default: Infinity, no timeout).
+     * Set to 0 for immediate submit (no sequences - first key press is captured).
+     * Set to a finite number for auto-submit after that duration. */
     sequenceTimeout?: number;
     /** When true, pause the auto-submit timeout (useful for conflict warnings). Default: false */
     pauseTimeout?: boolean;
@@ -131,10 +198,14 @@ interface SequenceCompletion {
  * Hotkey definition - maps key combinations/sequences to action names
  */
 type HotkeyMap = Record<string, string | string[]>;
+/**
+ * Handler function type - can optionally receive captured values
+ */
+type HotkeyHandler = (e: KeyboardEvent, captures?: number[]) => void;
 /**
  * Handler map - maps action names to handler functions
  */
-type HandlerMap = Record<string, (e: KeyboardEvent) => void>;
+type HandlerMap = Record<string, HotkeyHandler>;
 interface UseHotkeysOptions {
     /** Whether hotkeys are enabled (default: true) */
     enabled?: boolean;
@@ -146,7 +217,7 @@ interface UseHotkeysOptions {
     stopPropagation?: boolean;
     /** Enable hotkeys even when focused on input/textarea/select (default: false) */
     enableOnFormTags?: boolean;
-    /** Timeout in ms for sequences (default: 1000) */
+    /** Timeout in ms for sequences (default: Infinity, no timeout) */
     sequenceTimeout?: number;
     /** What happens on timeout: 'submit' executes current sequence, 'cancel' resets (default: 'submit') */
     onTimeout?: 'submit' | 'cancel';
@@ -183,8 +254,7 @@ interface UseHotkeysResult {
  * // Sequences
  * const { pendingKeys, isAwaitingSequence } = useHotkeys(
  *   { '2 w': 'twoWeeks', '2 d': 'twoDays' },
- *   { twoWeeks: () => setRange('2w'), twoDays: () => setRange('2d') },
- *   { sequenceTimeout: 1000 }
+ *   { twoWeeks: () => setRange('2w'), twoDays: () => setRange('2d') }
  * )
  * ```
  */
@@ -399,6 +469,19 @@ interface BindingInfo {
  */
 declare function KeybindingEditor({ keymap, defaults, descriptions, onChange, onReset, className, children, }: KeybindingEditorProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Props for a tooltip wrapper component.
+ * Compatible with MUI Tooltip and similar libraries.
+ */
+interface TooltipProps {
+    title: string;
+    children: ReactNode;
+}
+/**
+ * A component that wraps children with a tooltip.
+ * Default uses native title attribute; can be replaced with MUI Tooltip etc.
+ */
+type TooltipComponent = ComponentType<TooltipProps>;
 interface ShortcutGroup {
     name: string;
     shortcuts: Array<{
@@ -474,13 +557,12 @@ interface ShortcutsModalProps {
      * If not provided, uses closeModal from HotkeysContext.
      */
     onClose?: () => void;
-    /** Hotkey to open modal (default: '?'). Set to empty string to disable. */
-    openKey?: string;
     /**
-     * Whether to auto-register the open hotkey (default: true).
-     * When using HotkeysContext, the provider already handles this, so set to false.
+     * Default keybinding to open shortcuts modal (default: '?').
+     * Users can override this in the shortcuts modal.
+     * Set to empty string to disable.
      */
-    autoRegisterOpen?: boolean;
+    defaultBinding?: string;
     /** Enable editing mode */
     editable?: boolean;
     /** Called when a binding changes (required if editable) */
@@ -503,6 +585,14 @@ interface ShortcutsModalProps {
     title?: string;
     /** Hint text shown below title (e.g., "Click any key to customize") */
     hint?: string;
+    /** Whether to show actions with no bindings (default: true in editable mode, false otherwise) */
+    showUnbound?: boolean;
+    /**
+     * Custom tooltip component for digit placeholders.
+     * Should accept { title: string, children: ReactNode } props.
+     * Default uses native title attribute. Can be MUI Tooltip, etc.
+     */
+    TooltipComponent?: TooltipComponent;
 }
 interface ShortcutsModalRenderProps {
     groups: ShortcutGroup[];
@@ -519,20 +609,31 @@ interface ShortcutsModalRenderProps {
     reset: () => void;
 }
 /**
- * Modal component for displaying and optionally editing keyboard shortcuts.
+ * Modal for displaying all keyboard shortcuts, organized by group.
+ *
+ * Opens by default with `?` key. Shows all registered actions and their bindings,
+ * grouped by category (e.g., "Navigation", "Edit", "Global").
+ *
+ * Features:
+ * - **Editable bindings**: Click any shortcut to rebind it (when `editable` is true)
+ * - **Conflict detection**: Warns when a binding conflicts with existing shortcuts
+ * - **Custom group renderers**: Use `groupRenderers` for custom layouts (e.g., two-column for fwd/back pairs)
+ * - **Persistence**: Integrates with HotkeysProvider's localStorage persistence
  *
- * Uses CSS classes from styles.css. Override via CSS custom properties:
- * --kbd-bg, --kbd-text, --kbd-kbd-bg, etc.
+ * Unlike Omnibar (search-first) or LookupModal (type keys to filter), ShortcutsModal
+ * shows everything at once in a browsable, organized view.
+ *
+ * Styled via CSS custom properties: --kbd-bg, --kbd-text, --kbd-kbd-bg, etc.
  *
  * @example
  * ```tsx
- * // Read-only display
- * <ShortcutsModal
- *   keymap={HOTKEYS}
- *   labels={{ 'metric:temp': 'Temperature' }}
- * />
+ * // Basic usage with HotkeysProvider (recommended)
+ * <HotkeysProvider>
+ *   <App />
+ *   <ShortcutsModal editable />
+ * </HotkeysProvider>
  *
- * // Editable with callbacks
+ * // Standalone with explicit props
  * <ShortcutsModal
  *   keymap={keymap}
  *   defaults={DEFAULT_KEYMAP}
@@ -543,7 +644,7 @@ interface ShortcutsModalRenderProps {
  * />
  * ```
  */
-declare function ShortcutsModal({ keymap: keymapProp, defaults: defaultsProp, labels: labelsProp, descriptions: descriptionsProp, groups: groupNamesProp, groupOrder, groupRenderers, isOpen: isOpenProp, onClose: onCloseProp, openKey, autoRegisterOpen, editable, onBindingChange, onBindingAdd, onBindingRemove, onReset, multipleBindings, children, backdropClassName, modalClassName, title, hint, }: ShortcutsModalProps): react_jsx_runtime.JSX.Element | null;
+declare function ShortcutsModal({ keymap: keymapProp, defaults: defaultsProp, labels: labelsProp, descriptions: descriptionsProp, groups: groupNamesProp, groupOrder, groupRenderers, isOpen: isOpenProp, onClose: onCloseProp, defaultBinding, editable, onBindingChange, onBindingAdd, onBindingRemove, onReset, multipleBindings, children, backdropClassName, modalClassName, title, hint, showUnbound, TooltipComponent: TooltipComponentProp, }: ShortcutsModalProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * Configuration for a row in a two-column table
@@ -613,13 +714,12 @@ interface OmnibarProps {
      * If not provided, uses keymap from HotkeysContext.
      */
     keymap?: HotkeyMap;
-    /** Hotkey to open omnibar (default: 'meta+k'). Set to empty string to disable. */
-    openKey?: string;
     /**
-     * Whether omnibar hotkey is enabled.
-     * When using HotkeysContext, defaults to false (provider handles it).
+     * Default keybinding to open omnibar (default: 'meta+k').
+     * Users can override this in the shortcuts modal.
+     * Set to empty string to disable.
      */
-    enabled?: boolean;
+    defaultBinding?: string;
     /**
      * Control visibility externally.
      * If not provided, uses isOmnibarOpen from HotkeysContext.
@@ -663,13 +763,31 @@ interface OmnibarRenderProps {
     inputRef: RefObject<HTMLInputElement | null>;
 }
 /**
- * Omnibar/command palette component for searching and executing actions.
+ * Command palette for searching and executing actions by name.
+ *
+ * Opens by default with `⌘K` (macOS) or `Ctrl+K` (Windows/Linux). Type to search
+ * across all registered actions by label, then press Enter to execute.
+ *
+ * Features:
+ * - **Fuzzy search**: Matches action labels (e.g., "nav tab" finds "Navigate to Table")
+ * - **Keyboard navigation**: Arrow keys to select, Enter to execute, Escape to close
+ * - **Binding display**: Shows keyboard shortcuts next to each result
+ * - **Sequence support**: Can also match and execute key sequences
+ *
+ * Unlike ShortcutsModal (shows all shortcuts organized by group) or LookupModal
+ * (type keys to filter by binding), Omnibar is search-first by action name/label.
  *
- * Uses CSS classes from styles.css. Override via CSS custom properties:
- * --kbd-bg, --kbd-text, --kbd-accent, etc.
+ * Styled via CSS custom properties: --kbd-bg, --kbd-text, --kbd-accent, etc.
  *
  * @example
  * ```tsx
+ * // Basic usage with HotkeysProvider (recommended)
+ * <HotkeysProvider>
+ *   <App />
+ *   <Omnibar />
+ * </HotkeysProvider>
+ *
+ * // Standalone with explicit props
  * <Omnibar
  *   actions={ACTIONS}
  *   handlers={HANDLERS}
@@ -678,8 +796,13 @@ interface OmnibarRenderProps {
  * />
  * ```
  */
-declare function Omnibar({ actions: actionsProp, handlers: handlersProp, keymap: keymapProp, openKey, enabled: enabledProp, isOpen: isOpenProp, onOpen: onOpenProp, onClose: onCloseProp, onExecute: onExecuteProp, maxResults, placeholder, children, backdropClassName, omnibarClassName, }: OmnibarProps): react_jsx_runtime.JSX.Element | null;
+declare function Omnibar({ actions: actionsProp, handlers: handlersProp, keymap: keymapProp, defaultBinding, isOpen: isOpenProp, onOpen: onOpenProp, onClose: onCloseProp, onExecute: onExecuteProp, maxResults, placeholder, children, backdropClassName, omnibarClassName, }: OmnibarProps): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Check if a key is a shifted symbol (requires Shift on US keyboard).
+ * For these keys, shift modifier should be implicit, not shown separately.
+ */
+declare function isShiftedSymbol(key: string): boolean;
 /**
  * Detect if running on macOS
  */
@@ -692,11 +815,32 @@ declare function normalizeKey(key: string): string;
  * Format a key for display (platform-aware)
  */
 declare function formatKeyForDisplay(key: string): string;
+/**
+ * Sentinel values for digit placeholders in KeyCombination.key
+ * These are used during recording to represent placeholder patterns.
+ */
+declare const DIGIT_PLACEHOLDER = "__DIGIT__";
+declare const DIGITS_PLACEHOLDER = "__DIGITS__";
+/**
+ * Check if a key string is a digit placeholder sentinel value.
+ * Used during recording to identify placeholder keys.
+ */
+declare function isPlaceholderSentinel(key: string): boolean;
 /**
  * Convert a KeyCombination or HotkeySequence to display format
  */
 declare function formatCombination(combo: KeyCombination): KeyCombinationDisplay;
 declare function formatCombination(sequence: HotkeySequence): KeyCombinationDisplay;
+/**
+ * Format a binding string for display.
+ * Takes a binding like "meta+k" or "2 w" and returns a display string like "⌘K" or "2 W".
+ *
+ * @example
+ * formatBinding('meta+k') // "⌘K" on Mac, "Ctrl+K" on Windows
+ * formatBinding('2 w')    // "2 W"
+ * formatBinding('?')      // "?"
+ */
+declare function formatBinding(binding: string): string;
 /**
  * Check if a key is a modifier key
  */
@@ -715,6 +859,34 @@ declare function parseHotkeyString(hotkeyStr: string): HotkeySequence;
  * @deprecated Use parseHotkeyString for sequence support
  */
 declare function parseCombinationId(id: string): KeyCombination;
+/**
+ * Parse a hotkey string to a KeySeq (new sequence type with digit placeholders).
+ * Handles both single keys ("ctrl+k") and sequences ("2 w", "\\d+ d")
+ *
+ * @example
+ * parseKeySeq('\\d+ d')  // [{ type: 'digits' }, { type: 'key', key: 'd', ... }]
+ * parseKeySeq('ctrl+k')  // [{ type: 'key', key: 'k', modifiers: { ctrl: true, ... } }]
+ */
+declare function parseKeySeq(hotkeyStr: string): KeySeq;
+/**
+ * Format a KeySeq to display format
+ */
+declare function formatKeySeq(seq: KeySeq): KeyCombinationDisplay;
+/**
+ * Check if a KeySeq contains any digit placeholders
+ */
+declare function hasDigitPlaceholders(seq: KeySeq): boolean;
+/**
+ * Convert a KeySeq to HotkeySequence (for backwards compatibility).
+ * Note: Digit placeholders become literal '\d' or '\d+' keys.
+ * This is only useful for legacy code paths.
+ */
+declare function keySeqToHotkeySequence(seq: KeySeq): HotkeySequence;
+/**
+ * Convert a HotkeySequence to KeySeq (for migration).
+ * Note: This does NOT detect digit patterns - use parseKeySeq for that.
+ */
+declare function hotkeySequenceToKeySeq(seq: HotkeySequence): KeySeq;
 /**
  * Conflict detection result
  */
@@ -730,6 +902,7 @@ interface KeyConflict {
  * Find conflicts in a keymap.
  * Detects:
  * - Duplicate: multiple actions bound to the exact same key/sequence
+ * - Pattern overlap: digit patterns that could match the same input (e.g., "\d d" and "5 d")
  * - Prefix: one hotkey is a prefix of another (e.g., "2" and "2 w")
  *
  * @param keymap - HotkeyMap to check for conflicts
@@ -797,6 +970,23 @@ declare function fuzzyMatch(pattern: string, text: string): FuzzyMatchResult;
  */
 declare function searchActions(query: string, actions: ActionRegistry, keymap?: Record<string, string | string[]>): ActionSearchResult[];
 
+/**
+ * Handler function for actions.
+ * Optionally receives captured values from digit placeholders in bindings.
+ *
+ * @example
+ * ```tsx
+ * // Simple handler (no captures)
+ * handler: () => setPage(1)
+ *
+ * // Handler with captures (e.g., for binding "\d+ j")
+ * handler: (e, captures) => {
+ *   const n = captures?.[0] ?? 1
+ *   setRow(row + n)
+ * }
+ * ```
+ */
+type ActionHandler = (e?: KeyboardEvent, captures?: number[]) => void;
 interface ActionConfig {
     /** Human-readable label for omnibar/modal */
     label: string;
@@ -806,8 +996,8 @@ interface ActionConfig {
     defaultBindings?: string[];
     /** Search keywords for omnibar */
     keywords?: string[];
-    /** The action handler */
-    handler: () => void;
+    /** The action handler (optionally receives KeyboardEvent and captured values) */
+    handler: ActionHandler;
     /** Whether action is currently enabled (default: true) */
     enabled?: boolean;
     /** Priority for conflict resolution (higher wins, default: 0) */
@@ -874,12 +1064,14 @@ interface ActionsRegistryValue {
     actionRegistry: ActionRegistry;
     /** Get all bindings for an action (defaults + overrides) */
     getBindingsForAction: (id: string) => string[];
+    /** Get the first binding for an action (convenience for display) */
+    getFirstBindingForAction: (id: string) => string | undefined;
     /** User's binding overrides */
     overrides: Record<string, string | string[]>;
     /** Set a user override for a binding */
     setBinding: (actionId: string, key: string) => void;
-    /** Remove a binding */
-    removeBinding: (key: string) => void;
+    /** Remove a binding for a specific action */
+    removeBinding: (actionId: string, key: string) => void;
     /** Reset all overrides */
     resetOverrides: () => void;
 }
@@ -900,7 +1092,7 @@ declare function useActionsRegistry(options?: UseActionsRegistryOptions): Action
 interface HotkeysConfig {
     /** Storage key for persisting user binding overrides */
     storageKey?: string;
-    /** Timeout in ms before a sequence auto-submits (default: 1000) */
+    /** Timeout in ms before a sequence auto-submits (default: Infinity, no timeout) */
     sequenceTimeout?: number;
     /** When true, keys with conflicts are disabled (default: true) */
     disableConflicts?: boolean;
@@ -908,10 +1100,6 @@ interface HotkeysConfig {
     minViewportWidth?: number | false;
     /** Whether to show hotkey UI on touch-only devices (default: false) */
     enableOnTouch?: boolean;
-    /** Key sequence to open shortcuts modal (false to disable) */
-    modalTrigger?: string | false;
-    /** Key sequence to open omnibar (false to disable) */
-    omnibarTrigger?: string | false;
 }
 /**
  * Context value for hotkeys.
@@ -937,6 +1125,18 @@ interface HotkeysContextValue {
     closeOmnibar: () => void;
     /** Toggle the omnibar */
     toggleOmnibar: () => void;
+    /** Whether currently editing a binding in ShortcutsModal */
+    isEditingBinding: boolean;
+    /** Set editing state (called by ShortcutsModal) */
+    setIsEditingBinding: (value: boolean) => void;
+    /** Lookup modal open state */
+    isLookupOpen: boolean;
+    /** Open the lookup modal */
+    openLookup: () => void;
+    /** Close the lookup modal */
+    closeLookup: () => void;
+    /** Toggle the lookup modal */
+    toggleLookup: () => void;
     /** Execute an action by ID */
     executeAction: (id: string) => void;
     /** Sequence state: pending key combinations */
@@ -955,6 +1155,8 @@ interface HotkeysContextValue {
     searchActions: (query: string) => ReturnType<typeof searchActions>;
     /** Get sequence completions for pending keys */
     getCompletions: (pendingKeys: HotkeySequence) => ReturnType<typeof getSequenceCompletions>;
+    /** Cancel the current sequence */
+    cancelSequence: () => void;
 }
 interface HotkeysProviderProps {
     config?: HotkeysConfig;
@@ -1020,7 +1222,7 @@ declare function useMaybeHotkeysContext(): HotkeysContextValue | null;
  *       console.log('Captured:', display.display) // "2 W" or "⌘K"
  *       saveKeybinding(display.id) // "2 w" or "meta+k"
  *     },
- *     sequenceTimeout: 1000,
+ *     sequenceTimeout: 800, // custom timeout
  *   })
  *
  *   return (
@@ -1037,28 +1239,175 @@ declare function useMaybeHotkeysContext(): HotkeysContextValue | null;
  */
 declare function useRecordHotkey(options?: RecordHotkeyOptions): RecordHotkeyResult;
 
+interface KbdProps {
+    /** Action ID to display binding(s) for */
+    action: string;
+    /** Separator between multiple bindings (default: " / ") */
+    separator?: string;
+    /** Show all bindings instead of just the first (default: false, shows only first) */
+    all?: boolean;
+    /** Fallback content when no bindings exist */
+    fallback?: React.ReactNode;
+    /** Additional className */
+    className?: string;
+    /** Make the kbd clickable to trigger the action */
+    clickable?: boolean;
+}
+/**
+ * Display the current binding(s) for an action (clickable by default).
+ *
+ * Automatically updates when users customize their bindings.
+ * Uses SVG icons for modifiers (⌘, ⌥, ⇧, ⌃) and special keys (arrows, enter, etc.)
+ *
+ * @example
+ * ```tsx
+ * // Clickable kbd that triggers the action (default)
+ * <p>Press <Kbd action="help" /> to see shortcuts</p>
+ *
+ * // Non-clickable for pure display (use Key alias or clickable={false})
+ * <p>Navigate with <Key action="next" /> to go to next item</p>
+ *
+ * // Show all bindings (not just the first)
+ * <p>Navigate with <Kbd action="next" all separator=" or " /></p>
+ *
+ * // With fallback when no binding exists
+ * <Kbd action="customAction" fallback="(unbound)" />
+ * ```
+ */
+declare function Kbd({ action, separator, all, fallback, className, clickable, }: KbdProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * Non-clickable variant of Kbd for pure display/documentation purposes.
+ * Alias for `<Kbd clickable={false} ... />`
+ */
+declare function Key(props: Omit<KbdProps, 'clickable'>): react_jsx_runtime.JSX.Element;
+/**
+ * Display all bindings for an action (shows multiple if they exist).
+ * Alias for `<Kbd all ... />`
+ *
+ * @example
+ * ```tsx
+ * <p>Navigate with <Kbds action="next" separator=" or " /></p>
+ * ```
+ */
+declare function Kbds(props: Omit<KbdProps, 'all'>): react_jsx_runtime.JSX.Element;
+type BuiltinKbdProps = Omit<KbdProps, 'action'>;
+/**
+ * Kbd for the ShortcutsModal trigger (default: `?`).
+ * @example <KbdModal /> // Shows "?" or user's custom binding
+ */
+declare function KbdModal(props: BuiltinKbdProps): react_jsx_runtime.JSX.Element;
+/**
+ * Kbd for the Omnibar trigger (default: `⌘K`).
+ * @example <KbdOmnibar /> // Shows "⌘K" or user's custom binding
+ */
+declare function KbdOmnibar(props: BuiltinKbdProps): react_jsx_runtime.JSX.Element;
+/**
+ * Kbd for the LookupModal trigger (default: `⌘⇧K`).
+ * @example <KbdLookup /> // Shows "⌘⇧K" or user's custom binding
+ */
+declare function KbdLookup(props: BuiltinKbdProps): react_jsx_runtime.JSX.Element;
+
+interface LookupModalProps {
+    /**
+     * Default keybinding to open lookup modal (default: 'meta+shift+k').
+     * Users can override this in the shortcuts modal.
+     * Set to empty string to disable.
+     */
+    defaultBinding?: string;
+}
+/**
+ * Modal for browsing and looking up keyboard shortcuts by typing key sequences.
+ *
+ * Unlike SequenceModal (which auto-executes when a complete sequence is entered),
+ * LookupModal lets you browse all available shortcuts and select one to execute.
+ *
+ * - Press keys to filter to matching sequences
+ * - Use arrow keys to navigate results
+ * - Press Enter to execute selected action
+ * - Press Escape to close or clear filter
+ * - Press Backspace to remove last key from filter
+ */
+declare function LookupModal({ defaultBinding }?: LookupModalProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Modal that appears during multi-key sequence input (e.g., `g t` for "go to table").
+ *
+ * When a user presses a key that starts a sequence, this modal appears showing:
+ * - The keys pressed so far
+ * - Available completions (what keys can come next)
+ * - A timeout indicator
+ *
+ * Unlike LookupModal (which requires explicit activation and lets you browse/search),
+ * SequenceModal appears automatically when you start typing a sequence and auto-executes
+ * when a complete sequence is entered.
+ *
+ * The modal auto-dismisses if no completion is pressed within the sequence timeout,
+ * or when the user presses Escape, or when a complete sequence is executed.
+ *
+ * @example
+ * ```tsx
+ * // Include in your app (no props needed - uses HotkeysContext)
+ * <HotkeysProvider>
+ *   <App />
+ *   <SequenceModal />
+ * </HotkeysProvider>
+ * ```
+ */
 declare function SequenceModal(): react_jsx_runtime.JSX.Element | null;
 
-interface ModifierIconProps {
+interface ModifierIconProps extends SVGProps<SVGSVGElement> {
     className?: string;
     style?: CSSProperties;
 }
 /** Command/Meta key icon (⌘) */
-declare function CommandIcon({ className, style }: ModifierIconProps): react_jsx_runtime.JSX.Element;
+declare const Command: react.ForwardRefExoticComponent<Omit<ModifierIconProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
 /** Control key icon (^) - chevron/caret */
-declare function CtrlIcon({ className, style }: ModifierIconProps): react_jsx_runtime.JSX.Element;
+declare const Ctrl: react.ForwardRefExoticComponent<Omit<ModifierIconProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
 /** Shift key icon (⇧) - hollow arrow */
-declare function ShiftIcon({ className, style }: ModifierIconProps): react_jsx_runtime.JSX.Element;
+declare const Shift: react.ForwardRefExoticComponent<Omit<ModifierIconProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
 /** Option key icon (⌥) - macOS style */
-declare function OptIcon({ className, style }: ModifierIconProps): react_jsx_runtime.JSX.Element;
+declare const Option: react.ForwardRefExoticComponent<Omit<ModifierIconProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
 /** Alt key icon (⎇) - Windows style, though "Alt" text is more common on Windows */
-declare function AltIcon({ className, style }: ModifierIconProps): react_jsx_runtime.JSX.Element;
+declare const Alt: react.ForwardRefExoticComponent<Omit<ModifierIconProps, "ref"> & react.RefAttributes<SVGSVGElement>>;
 type ModifierType = 'meta' | 'ctrl' | 'shift' | 'alt' | 'opt';
 /** Get the appropriate icon component for a modifier key */
-declare function getModifierIcon(modifier: ModifierType): ComponentType<ModifierIconProps>;
+declare function getModifierIcon(modifier: ModifierType): typeof Command;
 /** Render a modifier icon by name */
-declare function ModifierIcon({ modifier, ...props }: ModifierIconProps & {
+declare const ModifierIcon: react.ForwardRefExoticComponent<Omit<ModifierIconProps & {
     modifier: ModifierType;
-}): react_jsx_runtime.JSX.Element;
+}, "ref"> & react.RefAttributes<SVGSVGElement>>;
+
+interface KeyIconProps {
+    className?: string;
+    style?: CSSProperties;
+}
+/** Arrow Up icon (↑) */
+declare function Up({ className, style }: KeyIconProps): react_jsx_runtime.JSX.Element;
+/** Arrow Down icon (↓) */
+declare function Down({ className, style }: KeyIconProps): react_jsx_runtime.JSX.Element;
+/** Arrow Left icon (←) */
+declare function Left({ className, style }: KeyIconProps): react_jsx_runtime.JSX.Element;
+/** Arrow Right icon (→) */
+declare function Right({ className, style }: KeyIconProps): react_jsx_runtime.JSX.Element;
+/** Enter/Return icon (↵) */
+declare function Enter({ className, style }: KeyIconProps): react_jsx_runtime.JSX.Element;
+/** Backspace icon (⌫) */
+declare function Backspace({ className, style }: KeyIconProps): react_jsx_runtime.JSX.Element;
+type KeyIconType = 'arrowup' | 'arrowdown' | 'arrowleft' | 'arrowright' | 'enter' | 'backspace';
+/** Get the icon component for a key, or null if no icon exists */
+declare function getKeyIcon(key: string): React.ComponentType<KeyIconProps> | null;
+
+/**
+ * Default timeout for key sequences (no timeout).
+ * Set to a finite number (ms) to auto-submit sequences after that duration.
+ */
+declare const DEFAULT_SEQUENCE_TIMEOUT: number;
+/**
+ * Reserved action IDs for built-in UI components.
+ * These are registered automatically by their respective components.
+ */
+declare const ACTION_MODAL = "__hotkeys:modal";
+declare const ACTION_OMNIBAR = "__hotkeys:omnibar";
+declare const ACTION_LOOKUP = "__hotkeys:lookup";
 
-export { type ActionConfig, type ActionDefinition, type ActionRegistry, type ActionSearchResult, ActionsRegistryContext, type ActionsRegistryValue, AltIcon, type BindingInfo, CommandIcon, CtrlIcon, type FuzzyMatchResult, type GroupRenderer, type GroupRendererProps, type HandlerMap, type HotkeyMap, type HotkeySequence, type HotkeysConfig, type HotkeysContextValue, HotkeysProvider, type HotkeysProviderProps, type KeyCombination, type KeyCombinationDisplay, type KeyConflict, KeybindingEditor, type KeybindingEditorProps, type KeybindingEditorRenderProps, ModifierIcon, type ModifierIconProps, type ModifierType, Omnibar, type OmnibarProps, type OmnibarRenderProps, OptIcon, type RecordHotkeyOptions, type RecordHotkeyResult, type RegisteredAction, type SequenceCompletion, SequenceModal, ShiftIcon, type ShortcutGroup, ShortcutsModal, type ShortcutsModalProps, type ShortcutsModalRenderProps, type TwoColumnConfig, type TwoColumnRow, type UseEditableHotkeysOptions, type UseEditableHotkeysResult, type UseHotkeysOptions, type UseHotkeysResult, type UseOmnibarOptions, type UseOmnibarResult, createTwoColumnRenderer, findConflicts, formatCombination, formatKeyForDisplay, fuzzyMatch, getActionBindings, getConflictsArray, getModifierIcon, getSequenceCompletions, hasConflicts, isMac, isModifierKey, isSequence, normalizeKey, parseCombinationId, parseHotkeyString, searchActions, useAction, useActions, useActionsRegistry, useEditableHotkeys, useHotkeys, useHotkeysContext, useMaybeHotkeysContext, useOmnibar, useRecordHotkey };
+export { ACTION_LOOKUP, ACTION_MODAL, ACTION_OMNIBAR, type ActionConfig, type ActionDefinition, type ActionHandler, type ActionRegistry, type ActionSearchResult, ActionsRegistryContext, type ActionsRegistryValue, Alt, Backspace, type BindingInfo, Command, Ctrl, DEFAULT_SEQUENCE_TIMEOUT, DIGITS_PLACEHOLDER, DIGIT_PLACEHOLDER, Down, Enter, type FuzzyMatchResult, type GroupRenderer, type GroupRendererProps, type HandlerMap, type HotkeyHandler, type HotkeyMap, type HotkeySequence, type HotkeysConfig, type HotkeysContextValue, HotkeysProvider, type HotkeysProviderProps, Kbd, KbdLookup, KbdModal, KbdOmnibar, type KbdProps, Kbds, Key, type KeyCombination, type KeyCombinationDisplay, type KeyConflict, type KeyIconProps, type KeyIconType, type KeySeq, KeybindingEditor, type KeybindingEditorProps, type KeybindingEditorRenderProps, Left, LookupModal, ModifierIcon, type ModifierIconProps, type ModifierType, type Modifiers, Omnibar, type OmnibarProps, type OmnibarRenderProps, Option, type RecordHotkeyOptions, type RecordHotkeyResult, type RegisteredAction, Right, type SeqElem, type SeqElemState, type SeqMatchState, type SequenceCompletion, SequenceModal, Shift, type ShortcutGroup, ShortcutsModal, type ShortcutsModalProps, type ShortcutsModalRenderProps, type TooltipComponent, type TooltipProps, type TwoColumnConfig, type TwoColumnRow, Up, type UseEditableHotkeysOptions, type UseEditableHotkeysResult, type UseHotkeysOptions, type UseHotkeysResult, type UseOmnibarOptions, type UseOmnibarResult, countPlaceholders, createTwoColumnRenderer, extractCaptures, findConflicts, formatBinding, formatCombination, formatKeyForDisplay, formatKeySeq, fuzzyMatch, getActionBindings, getConflictsArray, getKeyIcon, getModifierIcon, getSequenceCompletions, hasConflicts, hasDigitPlaceholders, hotkeySequenceToKeySeq, isDigitPlaceholder, isMac, isModifierKey, isPlaceholderSentinel, isSequence, isShiftedSymbol, keySeqToHotkeySequence, normalizeKey, parseCombinationId, parseHotkeyString, parseKeySeq, searchActions, useAction, useActions, useActionsRegistry, useEditableHotkeys, useHotkeys, useHotkeysContext, useMaybeHotkeysContext, useOmnibar, useRecordHotkey };