@keybindy/core
Version:
A lightweight and framework-agnostic keyboard shortcut manager for web apps. Define, register, and handle keybindings with ease.
250 lines (246 loc) • 9.77 kB
TypeScript
/**
* Represents a valid keyboard key for registering shortcuts in the ShortcutManager.
* This type includes all supported keys, covering modifiers (e.g., Ctrl, Shift),
* letters (A-Z), digits (0-9), numpad keys, symbols, control keys (e.g., Esc, Enter),
* navigation keys (e.g., Arrow Up), function keys (F1-F24), media keys, browser keys,
* application keys, language keys, system keys, and editing keys.
*/
type Keys = 'Ctrl' | 'Ctrl (Left)' | 'Ctrl (Right)' | 'Shift' | 'Shift (Left)' | 'Shift (Right)' | 'Alt' | 'Alt (Left)' | 'Alt (Right)' | 'Meta' | 'Meta (Left)' | 'Meta (Right)' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'Numpad 0' | 'Numpad 1' | 'Numpad 2' | 'Numpad 3' | 'Numpad 4' | 'Numpad 5' | 'Numpad 6' | 'Numpad 7' | 'Numpad 8' | 'Numpad 9' | 'Numpad +' | 'Numpad -' | 'Numpad *' | 'Numpad /' | 'Numpad Enter' | 'Numpad .' | 'Numpad =' | 'Numpad ,' | 'Numpad (' | 'Numpad )' | '-' | '=' | '[' | ']' | '\\' | ';' | "'" | ',' | '.' | '/' | '`' | 'Intl \\' | 'Intl Ro' | 'Intl Yen' | 'Esc' | 'Tab' | 'Caps Lock' | 'Enter' | 'Space' | 'Backspace' | 'Num Lock' | 'Scroll Lock' | 'Pause' | 'Context Menu' | 'Print Screen' | 'Insert' | 'Delete' | 'Home' | 'End' | 'Page Up' | 'Page Down' | 'Arrow Up' | 'Arrow Down' | 'Arrow Left' | 'Arrow Right' | 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12' | 'F13' | 'F14' | 'F15' | 'F16' | 'F17' | 'F18' | 'F19' | 'F20' | 'F21' | 'F22' | 'F23' | 'F24' | 'Volume Mute' | 'Volume Down' | 'Volume Up' | 'Media Next Track' | 'Media Previous Track' | 'Media Play/Pause' | 'Media Stop' | 'Media Select' | 'Browser Home' | 'Browser Search' | 'Browser Favorites' | 'Browser Refresh' | 'Browser Stop' | 'Browser Forward' | 'Browser Back' | 'Launch App 1' | 'Launch App 2' | 'Launch Mail' | 'Launch Media Player' | 'Launch Calculator' | 'Convert' | 'Non Convert' | 'Kana Mode' | 'Language 1' | 'Language 2' | 'Language 3' | 'Language 4' | 'Language 5' | 'Power' | 'Sleep' | 'Wake Up' | 'Eject' | 'Undo' | 'Redo' | 'Copy' | 'Cut' | 'Paste' | 'Select' | 'Again' | 'Find' | 'Open' | 'Properties' | 'Help' | 'Fn' | 'Brightness Up' | 'Brightness Down';
/**
* Function to handle a keyboard event triggered by a shortcut.
*/
type ShortcutHandler = (event: KeyboardEvent) => void;
/**
* Configuration options for a shortcut.
*/
interface ShortcutOptions {
/**
* Prevents the default action of the event.
*/
preventDefault?: boolean;
/**
* Specifies the scope of the shortcut ("global" or custom).
*/
scope?: 'global' | string;
/**
* Enables sequential key combinations.
*/
sequential?: boolean;
/**
* Maximum time (ms) between sequential key presses.
*/
sequenceDelay?: number;
/**
* Metadata for the shortcut.
*/
data?: Record<string, string>;
}
/**
* Defines a keyboard shortcut.
*/
interface Shortcut {
/**
* Unique identifier for the shortcut.
*/
id: string;
/**
* Array of keys to trigger the shortcut.
*/
keys: Keys[];
/**
* Function to call when the shortcut is triggered.
*/
handler: ShortcutHandler;
/**
* Optional configuration for the shortcut.
*/
options?: ShortcutOptions;
/**
* Whether the shortcut is active.
*/
enabled?: boolean;
}
/**
* Single or sequential key combinations for a shortcut.
*/
type KeyBinding = Keys[] | Keys[][];
declare class ScopeManager {
private scopeStack;
/**
* Pushes a new scope onto the scope stack.
* @param scope - The scope to push.
*/
pushScope(scope: string): void;
/**
* Pops the last scope from the scope stack.
*/
popScope(): void;
/**
* Swaps the active scope with the scope at the given index.
* @param scope - The scope to swap.
* @param index - The index of the scope to swap.
* @private
*/
private swap;
/**
* Activates the scope at the given index.
* @param scope - The scope to activate.
*/
setActiveScope(scope: string): void;
/**
* Resets the scope stack to the default state.
*/
resetScope(): void;
/**
* Returns the active scope.
* @returns The active scope.
*/
getActiveScope(): string;
/**
* Checks if the given scope is active.
* @param scope - The scope to check.
* @returns `true` if the scope is active, `false` otherwise.
*/
isScopeActive(scope?: string): boolean;
/**
* Returns all scopes in the stack.
* @returns An array of scopes.
*/
getScopes(): string[];
}
/**
* Manages keyboard shortcuts with support for scopes, enabling/disabling,
* dynamic registration, and cheat sheet generation.
*/
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;
}>;
}
export { ShortcutManager as default };
export type { KeyBinding, Keys, Shortcut, ShortcutHandler, ShortcutOptions };