@keybindy/core/dist/ShortcutManager.d.ts

A lightweight and framework-agnostic keyboard shortcut manager for web apps. Define, register, and handle keybindings with ease.

import type { Keys, ShortcutHandler, ShortcutOptions, Shortcut, KeyBinding } from './types';
import { ScopeManager } from './ScopeManager';
/**
 * Manages keyboard shortcuts with support for scopes, enabling/disabling,
 * dynamic registration, and cheat sheet generation.
 */
export declare class ShortcutManager extends ScopeManager {
    private shortcuts;
    private pressedKeys;
    private typingEmitter;
    private activeSequences;
    private onShortcutFired;
    constructor(onShortcutFired?: (shortcut: Shortcut) => void);
    start(): void;
    /**
     * Disables all shortcuts in the specified scope or all scopes if no scope is provided.
     * @param scope - The scope to disable shortcuts in.
     */
    disableAll(scope?: string): void;
    /**
     * Enables all shortcuts in the specified scope or all scopes if no scope is provided.
     * @param scope - The scope to enable shortcuts in.
     */
    enableAll(scope?: string): void;
    /**
     * Registers a callback to be called when a key is typed.
     * @param callback - The callback function to be called.
     */
    onTyping(callback: (payload: {
        key: string;
        event: KeyboardEvent;
    }) => void): () => void;
    /**
     * Handles `keydown` events, checks for matching shortcuts,
     * and triggers the appropriate handler.
     * @param e - The keyboard event object.
     * @private
     */
    private handleKeyDown;
    /**
     * Clears a sequence of keys from active sequences.
     * @param keys - The key combination to clear.
     * @private
     */
    private clearSequence;
    /**
     * Handles `keyup` events by removing the released key from the pressed keys set.
     * @param e - The keyboard event object.
     * @private
     */
    private handleKeyUp;
    /**
     * Registers a keyboard shortcut with the provided handler and options.
     * Duplicate bindings in the same scope are overwritten.
     *
     * @param keys - A key combination or list of combinations.
     * @param handler - Callback function to execute when shortcut is triggered.
     * @param options - Optional configuration including scope, ID, and metadata.
     */
    register(keys: KeyBinding, handler: ShortcutHandler, options?: ShortcutOptions): void;
    /**
     * Unregisters a previously registered shortcut based on the key combination and scope.
     * @param keys - The key combination to remove.
     * @param scope - The scope in which the shortcut was registered (default: "global").
     */
    unregister(keys: Keys[], scope?: string): void;
    /**
     * Toggles the state (enabled/disabled) of a shortcut.
     * @param keys - The shortcut key combination.
     * @param scope - The scope to match against.
     * @param state - The new state (`true`, `false`, or `"toggle"`).
     * @private
     */
    private toggleState;
    /**
     * Enables a specific shortcut based on key combination and scope.
     * @param keys - The key combination to enable.
     * @param scope - The target scope (default: "global").
     */
    enable(keys: Keys[], scope?: string): void;
    /**
     * Disables a specific shortcut based on key combination and scope.
     * @param keys - The key combination to disable.
     * @param scope - The target scope (default: "global").
     */
    disable(keys: Keys[], scope?: string): void;
    /**
     * Toggles a specific shortcut's enabled state based on key combination and scope.
     * @param keys - The key combination to toggle.
     * @param scope - The target scope (default: "global").
     */
    toggle(keys: Keys[], scope?: string): void;
    /**
     * Clears the internal state, removing all pressed keys and event listeners.
     * This does not unregister shortcuts.
     */
    clear(): void;
    /**
     * Completely destroys the manager instance by clearing all listeners and shortcuts.
     * Prevents further registration of shortcuts.
     */
    destroy(): void;
    /**
     * Generates a simplified cheat sheet of registered shortcuts for the current scope.
     * Useful for displaying in a UI.
     *
     * @param scope - Optional scope filter (default is the currently active scope).
     * @returns An array of objects containing key combos and associated data.
     */
    getCheatSheet(scope?: string): {
        keys: string[];
    }[];
    /**
     * Returns detailed information about all shortcuts organized by scope.
     *
     * @param scope - Optional scope to filter by. If omitted, returns info for all scopes.
     * @returns A scope-specific breakdown of all registered shortcuts.
     */
    getScopesInfo(scope?: string): {
        shortcuts: {
            keys: string[];
            id: string;
            enabled: boolean;
            data?: Record<string, string>;
        }[];
        isActive?: boolean;
    } | Record<string, {
        shortcuts: {
            keys: string[];
            id: string;
            enabled: boolean;
            data?: Record<string, string>;
        }[];
        isActive?: boolean;
    }>;
}