rx-hotkeys 1.0.0

package/README.md

@@ -0,0 +1,205 @@
+# rx-hotkeys: Advanced Keyboard Shortcut Management using rxjs
+
+rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard shortcuts in web applications. It leverages RxJS to handle keyboard events, allowing for the registration of simple key combinations (e.g., `Ctrl+S`) and complex key sequences (e.g., `g` -> `i` for "go to inbox"). It supports contexts for enabling/disabling shortcuts based on application state, and provides a type-safe way to define keys using standard `KeyboardEvent.key` values.
+
+## Features
+
+* **Key Combinations:** Define shortcuts that trigger when a specific key and modifier keys (Ctrl, Alt, Shift, Meta) are pressed simultaneously.
+* **Key Sequences:** Define shortcuts that trigger when a series of keys are pressed in a specific order.
+* **Sequence Timeouts:** Optional timeout between key presses in a sequence to prevent accidental triggers or indefinite waiting.
+* **Context Management:** Activate or deactivate groups of shortcuts based on the application's current state (e.g., "editor", "modal", "global").
+* **Type-Safe Key Definitions:** Uses an exported `Keys` object based on standard `KeyboardEvent.key` values for improved developer experience and fewer errors.
+* **RxJS Powered:** Built on RxJS for robust and efficient event handling.
+* **Prevent Default:** Option to prevent the default browser action for a triggered shortcut.
+* **Debug Mode:** Optional logging for easier development and troubleshooting.
+* **Clean API:** Simple and intuitive methods for adding, removing, and managing shortcuts.
+
+## Installation
+
+```bash
+npm install rxjs rx-hotkeys
+```
+
+
+## Basic Usage
+
+First, ensure you have the `rx-hotkeys` library and its helper Keys imported:
+
+```typescript
+import { HotKeys, Keys, KeyCombinationConfig, KeySequenceConfig } from 'rx-hotkeys';
+```
+
+1. Initialize HotKeys
+
+Create an instance of the `Hotkeys` class. You can optionally provide an initial context and enable debug mode.
+
+```typescript
+const keyManager = new HotKeys(); // No initial context, debug mode off
+
+// With an initial context and debug mode enabled:
+// const keyManager = new HotKeys('editor', true);
+```
+
+2. Add a Key Combination
+
+Register a shortcut for a key combination, like Ctrl+S.
+
+```typescript
+const saveConfig: KeyCombinationConfig = {
+  id: "saveFile", // Unique ID for this shortcut
+  keys: { key: Keys.S, ctrlKey: true }, // Use Keys.S for 's' key
+  callback: () => {
+    console.log("Ctrl+S pressed: Save file action triggered!");
+  },
+  preventDefault: true, // Prevent browser's default save action
+  description: "Save the current file."
+};
+
+keyManager.addCombination(saveConfig);
+```
+
+3. Add a Key SequenceRegister a shortcut for a sequence of keys, like the Konami code.
+
+```typescript
+const konamiConfig: KeySequenceConfig = {
+  id: "konamiCode",
+  sequence: [
+    Keys.ArrowUp, Keys.ArrowUp,
+    Keys.ArrowDown, Keys.ArrowDown,
+    Keys.ArrowLeft, Keys.ArrowRight,
+    Keys.ArrowLeft, Keys.ArrowRight,
+    Keys.B, Keys.A // 'B' and 'A' from Keys
+  ],
+  callback: (event) => { // The last KeyboardEvent of the sequence is passed
+    console.log("Konami code entered!");
+    // event.preventDefault(); // Can also be done here if not set in config
+  },
+  sequenceTimeoutMs: 3000, // User has 3 seconds between each key press
+  description: "Unlock special features."
+};
+
+keyManager.addSequence(konamiConfig);
+```
+
+4. Manage ContextsControl which shortcuts are active by setting the context.
+
+```typescript
+// Assuming some shortcuts are configured with context: "editor"
+keyManager.setContext("editor"); // Activates "editor" shortcuts and global shortcuts
+
+// To activate only global shortcuts (those with no context or context: null)
+keyManager.setContext(null);
+```
+
+5. Clean Up
+
+When the HotKeys instance is no longer needed (e.g., component unmount), call `destroy()` to clean up subscriptions and prevent memory leaks.
+
+```typescript
+// In a component lifecycle cleanup method or similar:
+keyManager.destroy();
+```
+
+
+## API Reference
+
+### `Keys` Object & `StandardKey` Type
+
+* `Keys`: An exported constant object containing standard KeyboardEvent.key string values (e.g., Keys.Enter, Keys.ArrowUp, Keys.A). It's highly recommended to use these when defining key in `KeyCombinationConfig` or keys in the sequence array of `KeySequenceConfig`.
+* `StandardKey`: A TypeScript type representing any valid key string from the Keys object.
+
+### `HotKeys` Class
+
+`constructor(initialContext?: string | null, debugMode?: boolean)`
+
+Creates a new HotKeys instance.
+
+`addCombination(config: KeyCombinationConfig): string | undefined`
+
+Registers a key combination shortcut.
+
+* `config`: The KeyCombinationConfig object.
+* Returns the shortcut ID if successful, undefined otherwise.
+
+`addSequence(config: KeySequenceConfig): string | undefined`
+
+Registers a key sequence shortcut.
+
+* `config`: The KeySequenceConfig object.
+* Returns the shortcut ID if successful, undefined otherwise.
+
+`setContext(contextName: string | null): void`
+
+Sets the active context. Only shortcuts matching this context or global shortcuts (no context) will trigger.
+
+`getContext(): string | null`
+
+Returns the current active context name, or null.
+
+`remove(id: string): boolean`
+
+Removes a registered shortcut by its ID.
+
+* Returns true if found and removed, false otherwise.
+
+`hasShortcut(id: string): boolean`
+
+Checks if a shortcut with the given ID is registered.
+
+* Returns true if it exists, false otherwise.
+
+`getActiveShortcuts(): { id: string; description?: string; context?: string | null; type: "combination" | "sequence" }[]`
+
+Returns an array of all currently registered shortcuts with their basic information.
+
+`setDebugMode(enable: boolean): void`
+
+Enables or disables console logging for debug purposes.
+
+`destroy(): void`
+
+Cleans up all subscriptions and resources. Essential to call to prevent memory leaks.
+
+### Configuration Interfaces
+
+`KeyCombinationConfig`
+
+* `id: string` (required): Unique identifier for the shortcut.
+* `keys: { key: StandardKey; ctrlKey?: boolean; altKey?: boolean; shiftKey?: boolean; metaKey?: boolean; }` (required): Defines the main key (from Keys) and optional modifier keys.
+* `callback: (event?: KeyboardEvent) => void` (required): Function to execute when the shortcut is triggered. The triggering `KeyboardEvent` is passed as an argument.
+* `context?: string | null`: Specifies the context in which this shortcut is active. If `null` or `undefined`, it's a global shortcut.
+* `preventDefault?: boolean`: If true, `event.preventDefault()` will be called when the shortcut triggers. Defaults to `false`.
+* `description?: string`: An optional description for the shortcut (e.g., for help menus).
+
+`KeySequenceConfig`
+
+* `id: string` (required): Unique identifier.
+* `sequence: StandardKey[]` (required): An array of `StandardKey` values (from `Keys`) representing the key sequence.
+* `callback: (event?: KeyboardEvent) => void` (required): Function to execute. The last `KeyboardEvent` of the sequence is passed.
+* `context?: string | null`: Context for activation.
+* `preventDefault?: boolean`: If true, `event.preventDefault()` is called for the last event in the sequence. Defaults to `false`.
+* `description?: string`: Optional description.
+* `sequenceTimeoutMs?: number`: Optional. Maximum time (in milliseconds) allowed between consecutive key presses in the sequence. If exceeded, the sequence resets. If `0` or `undefined`, no inter-key timeout is applied (uses simpler buffer-based matching).
+
+
+## Key Matching Logic
+
+* Single Character Keys (e.g., `Keys.A`, `Keys.Digit7`): When you configure a shortcut with a single character key from `Keys`, the library matches it case-insensitively against the `event.key` from the browser. For example, if you configure `Keys.A`, it will trigger for both "a" and "A" key presses (assuming Shift isn't a required modifier).
+* Special Keys (e.g., `Keys.Enter`, `Keys.ArrowUp`, `Keys.Escape`): These are multi-character `event.key` values. The library matches these case-sensitively against the `event.key`. Using the `Keys` object ensures you provide the correct, standard case-sensitive string.
+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues, fork the repository, and create pull requests.
+
+## Development Setup
+
+1. Clone the repository.
+2. Install dependencies: `npm install`.
+3. Run tests: `npm test`.
+
+# License
+
+This project is licensed under the MIT License.
+
+Powered by AI

package/dist/hotkeys.d.ts

@@ -0,0 +1,163 @@
+import { StandardKey } from "./keys.js";
+interface ShortcutConfigBase {
+    id: string;
+    callback: (event?: KeyboardEvent) => void;
+    context?: string | null;
+    preventDefault?: boolean;
+    description?: string;
+}
+export interface KeyCombinationConfig extends ShortcutConfigBase {
+    keys: {
+        /**
+         * The main key for the combination.
+         * This MUST be a value from the exported `Keys` object
+         * (e.g., `Keys.A`, `Keys.Enter`, `Keys.Escape`).
+         * The library handles case-insensitivity for single character keys (like A-Z, 0-9)
+         * automatically when comparing with the actual browser event's `event.key`.
+         * For special, multi-character keys (e.g. "ArrowUp", "Escape"), the value from
+         * `Keys` ensures the correct case-sensitive string is used.
+         * Refer to: https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values
+         */
+        key: StandardKey;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        shiftKey?: boolean;
+        metaKey?: boolean;
+    };
+}
+export interface KeySequenceConfig extends ShortcutConfigBase {
+    /**
+     * An array of keys that form the sequence.
+     * Each key in the sequence MUST be a value from the exported `Keys` object
+     * (e.g., `Keys.ArrowUp`, `Keys.G`, `Keys.Digit1`).
+     * The library handles case-insensitivity for single character keys automatically
+     * when comparing with the actual browser event's `event.key`.
+     * Refer to: https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values
+     * Example: [Keys.Control, Keys.Alt, Keys.Delete] or [Keys.G, Keys.I]
+     */
+    sequence: StandardKey[];
+    /**
+     * Optional: Timeout in milliseconds between consecutive key presses in the sequence.
+     * If the time between two keys in the sequence exceeds this value, the sequence attempt is reset.
+     * Set to 0 or undefined to disable inter-key timeout behavior (uses simpler buffer-based matching).
+     */
+    sequenceTimeoutMs?: number;
+}
+/**
+ * Manages keyboard shortcuts for web applications.
+ * Allows registration of single key combinations (e.g., Ctrl+S) and key sequences (e.g., g -> i).
+ * Supports contexts to enable/disable shortcuts based on application state.
+ */
+export declare class HotKeys {
+    private static readonly KEYDOWN_EVENT;
+    private static readonly LOG_PREFIX;
+    private keydown$;
+    private activeContext$;
+    private activeShortcuts;
+    private debugMode;
+    /**
+     * Creates an instance of Hotkeys.
+     * @param initialContext - Optional initial context name. Shortcuts will only trigger if their context matches this, or if they have no context defined.
+     * @param debugMode - Optional. If true, debug messages will be logged to the console. Defaults to false.
+     * @throws Error if not in a browser environment (i.e., `document` or `performance` is undefined).
+     */
+    constructor(initialContext?: string | null, debugMode?: boolean);
+    /**
+     * Sets the active context for shortcuts.
+     * Only shortcuts matching this context (or shortcuts with no specific context defined)
+     * will be active and can be triggered.
+     * @param contextName - The name of the context (e.g., "modal", "editor", "global").
+     * Pass `null` to activate shortcuts with no context or to deactivate context-specific shortcuts.
+     */
+    setContext(contextName: string | null): void;
+    /**
+     * Gets the current active context.
+     * @returns The current context name as a string, or `null` if no context is set.
+     */
+    getContext(): string | null;
+    /**
+     * Enables or disables debug logging for the Hotkeys instance.
+     * When enabled, various internal actions and shortcut triggers will be logged to the console.
+     * @param enable - True to enable debug logs, false to disable.
+     */
+    setDebugMode(enable: boolean): void;
+    /**
+     * Checks if a shortcut with the given ID is currently registered and active.
+     * @param id - The unique ID of the shortcut to check.
+     * @returns True if a shortcut with the specified ID exists, false otherwise.
+     */
+    hasShortcut(id: string): boolean;
+    private filterByContext;
+    private _registerShortcut;
+    /**
+     * Registers a key combination shortcut (e.g., Ctrl+S, Shift+Enter).
+     * The callback is triggered when the specified key and modifier keys are pressed simultaneously.
+     * @param config - Configuration object for the key combination.
+     * See {@link KeyCombinationConfig} for details.
+     * The `key` property within `config.keys` must be a value from the `Keys` object.
+     * @returns The ID of the registered shortcut if successful, or `undefined` if the configuration is invalid (e.g., empty key).
+     * A warning is logged to the console if the configuration is invalid or if a shortcut with the same ID is overwritten.
+     * @example
+     * ```typescript
+     * import { Keys } from './keys';
+     * keyManager.addCombination({
+     * id: "saveFile",
+     * keys: { key: Keys.S, ctrlKey: true },
+     * callback: () => console.log("File saved!"),
+     * context: "editor"
+     * });
+     * ```
+     */
+    addCombination(config: KeyCombinationConfig): string | undefined;
+    /**
+     * Registers a key sequence shortcut (e.g., g -> i, or ArrowUp -> ArrowUp -> ArrowDown).
+     * The callback is triggered when the specified keys are pressed in order.
+     * An optional timeout can be specified for the time allowed between key presses in the sequence.
+     * @param config - Configuration object for the key sequence.
+     * See {@link KeySequenceConfig} for details.
+     * Each key in the `sequence` array must be a value from the `Keys` object.
+     * @returns The ID of the registered shortcut if successful, or `undefined` if the configuration is invalid (e.g., empty sequence or invalid keys).
+     * A warning is logged to the console if the configuration is invalid or if a shortcut with the same ID is overwritten.
+     * @example
+     * ```typescript
+     * import { Keys } from './keys';
+     * keyManager.addSequence({
+     * id: "konamiCode",
+     * sequence: [Keys.ArrowUp, Keys.ArrowUp, Keys.ArrowDown, Keys.ArrowDown, Keys.A, Keys.B],
+     * callback: () => console.log("Konami!"),
+     * sequenceTimeoutMs: 2000 // 2 seconds between keys
+     * });
+     * ```
+     */
+    addSequence(config: KeySequenceConfig): string | undefined;
+    /**
+     * Removes a registered shortcut by its ID.
+     * This will unsubscribe from the underlying keyboard event stream for that shortcut.
+     * @param id - The unique ID of the shortcut to remove.
+     * @returns True if the shortcut was found and removed, false otherwise.
+     * A warning is logged to the console if no shortcut with the given ID is found.
+     */
+    remove(id: string): boolean;
+    /**
+     * Retrieves a list of all currently active (registered) shortcut configurations.
+     * This can be useful for displaying available shortcuts to the user or for debugging.
+     * @returns An array of objects, where each object represents an active shortcut
+     * and includes its `id`, `description` (if provided), `context` (if any),
+     * and `type` ("combination" or "sequence").
+     */
+    getActiveShortcuts(): {
+        id: string;
+        description?: string;
+        context?: string | null;
+        type: "combination" | "sequence";
+    }[];
+    /**
+     * Cleans up all active subscriptions and resources used by the Hotkeys instance.
+     * This method should be called when the Hotkeys instance is no longer needed
+     * (e.g., when a component unmounts or the application is shutting down) to prevent memory leaks.
+     * After calling `destroy()`, the instance should not be used further.
+     */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=hotkeys.d.ts.map

package/dist/hotkeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../src/hotkeys.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAIxC,UAAU,kBAAkB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;IAC1C,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC5D,IAAI,EAAE;QACF;;;;;;;;;WASG;QACH,GAAG,EAAE,WAAW,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACL;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IACzD;;;;;;;;OAQG;IACH,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B;AA6BD;;;;GAIG;AACH,qBAAa,OAAO;IAChB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAa;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAc;IAEhD,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,cAAc,CAAiC;IACvD,OAAO,CAAC,eAAe,CAA8B;IACrD,OAAO,CAAC,SAAS,CAAU;IAE3B;;;;;OAKG;gBACS,cAAc,GAAE,MAAM,GAAG,IAAW,EAAE,SAAS,GAAE,OAAe;IAe5E;;;;;;OAMG;IACI,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAOnD;;;OAGG;IACI,UAAU,IAAI,MAAM,GAAG,IAAI;IAIlC;;;;OAIG;IACI,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAO1C;;;;OAIG;IACI,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIvC,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,iBAAiB;IAkBzB;;;;;;;;;;;;;;;;;;OAkBG;IACI,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS;IA+CvE;;;;;;;;;;;;;;;;;;;OAmBG;IACI,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS;IAkHjE;;;;;;OAMG;IACI,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAYlC;;;;;;OAMG;IACI,kBAAkB,IAAI;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAAA;KAAC,EAAE;IAa5H;;;;;OAKG;IACI,OAAO,IAAI,IAAI;CAOzB"}