rx-hotkeys 2.6.1 → 3.0.0

package/README.md

@@ -1,19 +1,19 @@
-# rx-hotkeys: Advanced Keyboard Shortcut Management using rxjs
+# rx-hotkeys: Advanced Keyboard Shortcut Management with 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.
+rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard shortcuts in web applications. It leverages the full power of RxJS to handle keyboard events, allowing for the registration of simple key combinations (e.g., `Ctrl+S`), complex key sequences (e.g., `g` -> `i` for "go to inbox"), and much more. It supports contexts for enabling/disabling shortcuts based on application state, element-scoped listeners, and provides a type-safe API for defining shortcuts.
 
-## Features
+## ✨ 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").
-* **Strict Global Shortcuts:** Option to register global shortcuts that *only* fire when no other context is active, preventing them from triggering unintentionally.
-* **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.
+* **Fully Observable API**: Returns an RxJS `Observable` for each shortcut, allowing for powerful stream manipulation like chaining, filtering, debouncing, and merging with other streams.
+* **Flexible Shortcut Definitions**: Define shortcuts using simple, intuitive strings (e.g., `"ctrl+s"` or `"g -> i"`) in addition to the classic object-based configuration.
+* **Element-Scoped Listeners**: Attach shortcuts to specific DOM elements, so they are only active within a certain component or area, not just on the global `document`.
+* **`keyup` Event Support**: Trigger actions on key release (`keyup`) in addition to the default key press (`keydown`).
+* **Key Combinations & Sequences**: Supports both simultaneous key presses (`Ctrl+S`) and ordered key sequences (`g` -> `c`).
+* **Context Management**: Activate or deactivate groups of shortcuts based on the application's current state (e.g., "editor", "modal", "global").
+* **Strict Global Shortcuts**: Option to register global shortcuts that *only* fire when no other context is active.
+* **Type-Safe Key Definitions**: Uses an exported `Keys` object based on standard `KeyboardEvent.key` values for a superior developer experience and fewer errors.
+* **Sequence Timeouts**: Optional timeout between key presses in a sequence to prevent accidental triggers.
+* **Debug Mode**: Optional, detailed console logging for easier development and troubleshooting.
 
 ## Installation
 
@@ -21,13 +21,47 @@ rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard s
 npm install rxjs rx-hotkeys
 ```
 
+## ⚠️ Breaking Changes (v3.0+)
+
+Starting with v3.0, the API has been significantly updated for a more powerful and idiomatic RxJS experience. This is a major breaking change.
+
+* `addCombination` and `addSequence` no longer accept a `callback` property in their configuration.
+* They now return an **`Observable<KeyboardEvent>`**.
+* You **must** now call `.subscribe()` on the returned Observable to execute your action.
+
+**Migration Example:**
+
+**Old (v1.x):**
+```typescript
+// The old way
+keyManager.addCombination({
+  id: "save",
+  keys: { key: Keys.S, ctrlKey: true },
+  callback: () => console.log("File saved!"),
+});
+```
+
+**New (v3.0+):**
+```typescript
+// The new, observable-based way
+const save$ = keyManager.addCombination({
+  id: "save",
+  keys: { key: Keys.S, ctrlKey: true }
+});
+
+const subscription = save$.subscribe(() => console.log("File saved!"));
+
+// Don't forget to unsubscribe when your component is destroyed!
+// The stream will also complete automatically if the shortcut is removed or keyManager.destroy() is called.
+// subscription.unsubscribe();
+```
 
 ## Basic Usage
 
-First, ensure you have the `rx-hotkeys` library and its helper Keys imported:
+First, ensure you have the `Hotkeys` class and its helper `Keys` object imported:
 
 ```typescript
-import { Hotkeys, Keys, KeyCombinationConfig, KeySequenceConfig } from 'rx-hotkeys';
+import { Hotkeys, Keys } from "rx-hotkeys";
 ```
 
 ### 1. Initialize Hotkeys
@@ -37,54 +71,78 @@ Create an instance of the `Hotkeys` class. You can optionally provide an initial
 ```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);
+// Or 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.
+Register a shortcut for a key combination, like `Ctrl+S`, by subscribing to the returned Observable.
 
 ```typescript
-const saveConfig: KeyCombinationConfig = {
+const save$ = keyManager.addCombination({
   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!");
-  },
+  keys: { key: Keys.S, ctrlKey: true }, // Use Keys.S for "s" key
   preventDefault: true, // Prevent browser's default save action
   description: "Save the current file."
-};
+});
 
-keyManager.addCombination(saveConfig);
+const saveSubscription = save$.subscribe((event) => {
+  console.log("Ctrl+S pressed: Save file action triggered!", event);
+});
 ```
 
-### 3. Add a Key Sequence
+### 3. Define Shortcuts with Strings (New)
+
+You can also use more concise strings to define shortcuts.
+
+```typescript
+// Combination
+const open$ = keyManager.addCombination({ id: "openFile", keys: "ctrl+o" });
+open$.subscribe(() => console.log("Opening file..."));
+
+// Sequence
+const command$ = keyManager.addSequence({ id: "showCommandPalette", sequence: "cmd+k" }); // Note: "cmd+k" is a combination, not a sequence. Let's fix this example.
+const command$ = keyManager.addSequence({ id: "goToInbox", sequence: "g -> i" });
+command$.subscribe(() => console.log("Navigating to Inbox..."));
+```
+
+### 4. Add a Key Sequence
 
 Register a shortcut for a sequence of keys, like the Konami code.
 
 ```typescript
-const konamiConfig: KeySequenceConfig = {
+const konami$ = keyManager.addSequence({
   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
-  },
+  sequence: "up -> up -> down -> down -> left -> right -> left -> right -> b -> a",
   sequenceTimeoutMs: 3000, // User has 3 seconds between each key press
   description: "Unlock special features."
-};
+});
 
-keyManager.addSequence(konamiConfig);
+konami$.subscribe((event) => { // The last KeyboardEvent of the sequence is emitted
+  console.log("Konami code entered!");
+});
 ```
 
-### 4. Manage Contexts
+### 5. Advanced Usage: Scopes and `keyup`
+
+You can scope a shortcut to a specific element and trigger it on `keyup`.
+
+```typescript
+const myInputField = document.getElementById("my-input");
+
+const submit$ = keyManager.addCombination({
+    id: "submitOnEnter",
+    keys: Keys.Enter,
+    target: myInputField, // Only active on this element
+    event: "keyup", // Trigger on key release
+    preventDefault: true
+});
+
+submit$.subscribe(() => console.log("Form submitted on Enter keyup!"));
+```
+
+### 6. Manage Contexts
 
 Control which shortcuts are active by setting the context.
 
@@ -96,27 +154,9 @@ keyManager.setContext("editor"); // Activates "editor" shortcuts and global shor
 keyManager.setContext(null);
 ```
 
-#### Global vs. Strict Global Shortcuts
-
-Global shortcuts (those without a `context` property) have two behaviors:
-
-* **Default Global**: By default, a global shortcut will fire in *any* context, unless a more specific shortcut for the same key combination exists for that context.
-
-    ```typescript
-    // This shortcut for Ctrl+P will fire in the "editor" context, "modal" context, or any other,
-    // unless a specific "editor" shortcut for Ctrl+P exists.
-    keyManager.addCombination({ id: 'globalPrint', keys: { key: Keys.P, ctrlKey: true }, callback: myCallback });
-    ```
-* **Strict Global**: By passing `true` as the second argument to `addCombination` or `addSequence`, you can register a "strict" global shortcut. This shortcut will **only** fire when no context is active (`keyManager.getContext()` returns `null`).
-
-    ```typescript
-    // This help shortcut for "?" will ONLY fire when no other context is active.
-    keyManager.addCombination({ id: 'strictHelp', keys: Keys.QuestionMark, callback: openHelpModal, strict: true });
-    ```
+### 7. Clean Up
 
-### 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.
+When the Hotkeys instance is no longer needed (e.g., component unmount), call `destroy()` to clean up all internal streams and listeners, preventing memory leaks. This will also `complete` all active shortcut Observables.
 
 ```typescript
 // In a component lifecycle cleanup method or similar:
@@ -128,8 +168,8 @@ keyManager.destroy();
 
 ### `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.
+* `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 for type safety and to avoid typos.
+* `StandardKey`: A TypeScript type representing any valid key string from the `Keys` object.
 
 ### `Hotkeys` Class
 
@@ -137,39 +177,35 @@ keyManager.destroy();
 
 Creates a new Hotkeys instance.
 
-`addCombination(config: KeyCombinationConfig): string | undefined`
+`addCombination(config: KeyCombinationConfig): Observable<KeyboardEvent>`
 
 Registers a key combination shortcut.
+* `config`: The `KeyCombinationConfig` object.
+* Returns an `Observable<KeyboardEvent>` that emits when the shortcut is triggered.
 
-* `config`: The KeyCombinationConfig object.
-* Returns the shortcut ID if successful, undefined otherwise.
-
-`addSequence(config: KeySequenceConfig): string | undefined`
+`addSequence(config: KeySequenceConfig): Observable<KeyboardEvent>`
 
 Registers a key sequence shortcut.
-
-* `config`: The KeySequenceConfig object.
-* Returns the shortcut ID if successful, undefined otherwise.
+* `config`: The `KeySequenceConfig` object.
+* Returns an `Observable<KeyboardEvent>` that emits the final `KeyboardEvent` when the sequence is completed.
 
 `setContext(contextName: string | null): boolean`
 
-Sets the active context. Only shortcuts matching this context or global shortcuts (no context) will trigger.
+Sets the active context. Only shortcuts matching this context or global shortcuts will trigger.
 
 `getContext(): string | null`
 
-Returns the current active context name, or 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.
+Removes a registered shortcut by its ID. This will cause the corresponding Observable to complete.
+* 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.
+* Returns `true` if it exists, `false` otherwise.
 
 `getActiveShortcuts(): { id: string; description?: string; context?: string | null; type: "combination" | "sequence" }[]`
 
@@ -185,32 +221,36 @@ Cleans up all subscriptions and resources. Essential to call to prevent memory l
 
 ### Configuration Interfaces
 
-`KeyCombinationConfig`
+#### `KeyCombinationConfig`
 
 * `id: string` (required): Unique identifier for the shortcut.
-* `keys: { key: StandardKey; ctrlKey?: boolean; altKey?: boolean; shiftKey?: boolean; metaKey?: boolean; } | StandardKey | Array<{ key: StandardKey; ctrlKey?: boolean; altKey?: boolean; shiftKey?: boolean; metaKey?: boolean; } | StandardKey>` (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.
+* `keys: string | KeyCombinationTrigger | KeyCombinationTrigger[]` (required): Defines the key(s). Can be a string (`"ctrl+s"`), a shorthand `StandardKey` (`Keys.Escape`), an object (`{ key: Keys.S, ctrlKey: true }`), or an array of these.
 * `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`.
+* `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).
 * `strict?: boolean` (optional): If `true` and the shortcut has no `context`, it will only fire when no other context is active. Defaults to `false`.
+* `target?: HTMLElement` (optional): The DOM element to attach the listener to. Defaults to `document`.
+* `event?: "keydown" | "keyup"` (optional): The keyboard event to listen for. Defaults to `"keydown"`.
+* `callback?: (event: KeyboardEvent) => void` (**@deprecated**): This property is deprecated. Subscribe to the `Observable` returned by `addCombination` instead.
 
-`KeySequenceConfig`
+#### `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.
+* `sequence: string | StandardKey[]` (required): An array of `StandardKey` values or a string representation (e.g., `"g -> i"`).
 * `context?: string | null`: Context for activation.
-* `preventDefault?: boolean`: If true, `event.preventDefault()` is called for the last event in the sequence. Defaults to `false`.
+* `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).
-* `strict?: boolean` (optional): If `true` and the shortcut has no `context`, it will only fire when no other context is active. Defaults to `false`.
+* `sequenceTimeoutMs?: number`: Optional. Maximum time (in milliseconds) allowed between consecutive key presses in the sequence.
+* `strict?: boolean` (optional): If `true` and the shortcut has no `context`, it will only fire when no other context is active.
+* `target?: HTMLElement` (optional): The DOM element to attach the listener to. Defaults to `document`.
+* `event?: "keydown" | "keyup"` (optional): The keyboard event to listen for. Defaults to `"keydown"`.
+* `callback?: (event: KeyboardEvent) => void` (**@deprecated**): This property is deprecated. Subscribe to the `Observable` returned by `addSequence` instead.
 
+## Key Matching & Normalization
 
-## 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.
+* **Case Insensitivity**: The library automatically handles case for you. `keys: "a"` will match both "a" and "A" presses. `keys: "escape"` will match an event where `event.key` is `"Escape"`.
+* **Aliases**: Common aliases are supported in string definitions, such as `cmd` for `Meta`, `option` for `Alt`, and `esc` for `Escape`.
+* **Special Keys**: For full type-safety, it is recommended to use the exported `Keys` object (e.g., `Keys.Enter`, `Keys.ArrowUp`).
 
 ## Contributing
 
@@ -218,12 +258,10 @@ Contributions are welcome! Please feel free to submit issues, fork the repositor
 
 ## Development Setup
 
-1. Clone the repository.
-2. Install dependencies: `npm install`.
-3. Run tests: `npm test`.
+1.  Clone the repository.
+2.  Install dependencies: `npm install`.
+3.  Run tests: `npm test`.
 
-# License
+## License
 
 This project is licensed under the MIT License.
-
-Powered by AI

package/dist/hotkeys.d.ts

@@ -1,4 +1,4 @@
-import { Subscription, Observable } from "rxjs";
+import { Observable, Subject } from "rxjs";
 import { type StandardKey } from "./keys.js";
 export declare enum ShortcutTypes {
     Combination = "combination",
@@ -6,7 +6,10 @@ export declare enum ShortcutTypes {
 }
 interface ShortcutConfigBase {
     id: string;
-    callback: (event: KeyboardEvent) => void;
+    /**
+     * @deprecated The callback property is deprecated. `addCombination` and `addSequence` now return an Observable. Please subscribe to it instead.
+     */
+    callback?: (event: KeyboardEvent) => void;
     context?: string | null;
     preventDefault?: boolean;
     description?: string;
@@ -19,6 +22,20 @@ interface ShortcutConfigBase {
      * @default false
      */
     strict?: boolean;
+    /**
+     * The DOM element to which the event listener for this shortcut will be attached.
+     * If not provided, the listener will be attached to the `document`.
+     * Useful for creating shortcuts that are only active within a specific component or area.
+     * @default document
+     */
+    target?: HTMLElement;
+    /**
+     * The type of keyboard event to listen for.
+     * Use "keydown" for actions that should happen immediately upon pressing a key.
+     * Use "keyup" for actions that should happen upon releasing a key.
+     * @default "keydown"
+     */
+    event?: "keydown" | "keyup";
 }
 /**
  * Defines a single key trigger, which can be a StandardKey (for simple presses like "Escape")
@@ -44,32 +61,34 @@ type KeyCombinationTrigger = {
 export interface KeyCombinationConfig extends ShortcutConfigBase {
     /**
      * Defines the key or key combination(s) that trigger the shortcut.
-     * Can be a single trigger or an array of triggers.
-     * Each trigger can be an object specifying the main `key` (from `StandardKey`) and optional
+     * Can be a single trigger, an array of triggers, or a string representation.
+     *
+     * **Object/Array:** Each trigger can be an object specifying the main `key` (from `StandardKey`) and optional
      * modifiers (`ctrlKey`, `altKey`, `shiftKey`, `metaKey`).
      * Example: `{ key: Keys.S, ctrlKey: true }` for Ctrl+S.
      *
-     * Alternatively, for a simple key press without any modifiers, a trigger can be
-     * a `StandardKey` directly.
-     * Example: `Keys.Escape` for the Escape key. When using this shorthand,
-     * it implies that no modifier keys (Ctrl, Alt, Shift, Meta) should be active.
+     * **Shorthand:** For a simple key press without modifiers, a trigger can be a `StandardKey` directly.
+     * Example: `Keys.Escape` for the Escape key.
+     *
+     * **String:** A human-readable string like `"ctrl+s"` or `"shift+alt+k"`. Modifiers are joined by `+`.
+     * Example: `"meta+k"`, `"ctrl+shift+?"`
      *
      * To define multiple triggers for the same action:
      * Example: `keys: [Keys.Enter, { key: Keys.Space, ctrlKey: true }]`
      */
-    keys: KeyCombinationTrigger | KeyCombinationTrigger[];
+    keys: KeyCombinationTrigger | KeyCombinationTrigger[] | string;
 }
 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]
+     * An array of keys or a string defining the sequence.
+     *
+     * **Array:** Each key in the sequence MUST be a value from `Keys`.
+     * Example: `[Keys.G, Keys.I]`
+     *
+     * **String:** A string where keys are separated by `->`.
+     * Example: `"g -> i"`, `"up -> up -> down -> down"`
      */
-    sequence: StandardKey[];
+    sequence: StandardKey[] | string;
     /**
      * 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.
@@ -81,7 +100,7 @@ type ShortcutConfig = KeyCombinationConfig | KeySequenceConfig;
 export interface ActiveShortcut {
     id: string;
     config: ShortcutConfig;
-    subscription: Subscription;
+    terminator$: Subject<void>;
 }
 /**
  * Manages keyboard shortcuts for web applications.
@@ -90,8 +109,10 @@ export interface ActiveShortcut {
  */
 export declare class Hotkeys {
     private static readonly KEYDOWN_EVENT;
+    private static readonly KEYUP_EVENT;
     private static readonly LOG_PREFIX;
-    private keydown$;
+    private keydownStreams;
+    private keyupStreams;
     private activeContext$;
     private activeShortcuts;
     private debugMode;
@@ -102,6 +123,13 @@ export declare class Hotkeys {
      * @throws Error if not in a browser environment (i.e., `document` or `performance` is undefined).
      */
     constructor(initialContext?: string | null, debugMode?: boolean);
+    /**
+     * Gets or creates a shared event stream for a given event type and target.
+     * @param eventType The type of event ("keydown" or "keyup").
+     * @param target The DOM element to attach the listener to.
+     * @returns A shared Observable for the specified event.
+     */
+    private _getEventStream;
     /**
      * Sets the active context for shortcuts.
      * Only shortcuts matching this context (or shortcuts with no specific context defined)
@@ -172,57 +200,80 @@ export declare class Hotkeys {
      * @returns An object containing configuredMainKey and modifier states, or null if parsing fails.
      */
     private _parseKeyTrigger;
+    private _parseCombinationString;
+    private _parseSequenceString;
     /**
-     * Registers a key combination shortcut (e.g., Ctrl+S, Shift+Enter, or a single key like Escape).
-     * The callback is triggered when the specified key and modifier keys (if any) are pressed.
+     * Registers a key combination shortcut (e.g., Ctrl+S, Shift+Enter, or a single key like Escape)
+     * and returns an Observable that emits the `KeyboardEvent` when the combination is triggered.
      * @param config - Configuration object for the key combination.
      * See {@link KeyCombinationConfig} for details.
-     * The `key` property (or the direct `StandardKey` if using shorthand) must be a value from the `Keys` object.
-     * @returns The ID of the registered shortcut if successful, or `undefined` if the configuration is invalid.
-     * A warning is logged to the console if the configuration is invalid or if a shortcut with the same ID is overwritten.
+     * @returns An `Observable<KeyboardEvent>` that you can subscribe to. The stream will be automatically
+     * completed if the shortcut is removed via `remove(id)` or `destroy()`, or if it's overwritten.
+     * If the configuration is invalid, an empty Observable is returned and a warning is logged.
      * @example
      * ```typescript
      * import { Keys } from "./keys";
      * // For Ctrl+S
-     * keyManager.addCombination({
+     * const save$ = keyManager.addCombination({
      * id: "saveFile",
      * keys: { key: Keys.S, ctrlKey: true },
-     * callback: () => console.log("File saved!"),
      * context: "editor"
      * });
+     * save$.subscribe(event => console.log("File saved!", event));
+     *
+     * // For Ctrl+S using a string
+     * const save$ = keyManager.addCombination({ id: "saveFile", keys: "ctrl+s" });
+     * save$.subscribe(event => console.log("File saved!", event));
+     *
      * // For just the Escape key, or Ctrl+Space
-     * keyManager.addCombination({
+     * const close$ = keyManager.addCombination({
      * id: "closeModal",
      * keys: [Keys.Escape, {key: Keys.Space, ctrlKey: true}],
-     * callback: () => console.log("Modal closed!")
      * });
+     * close$.subscribe(() => console.log("Modal closed!"));
+     *
+     * // For the Escape key on a specific element
+     * const myModal = document.getElementById("my-modal");
+     * const close$ = keyManager.addCombination({ id: "closeModal", keys: Keys.Escape, target: myModal });
+     * close$.subscribe(() => console.log("Modal closed!"));
      * ```
      */
-    addCombination(config: KeyCombinationConfig): string | undefined;
+    addCombination(config: KeyCombinationConfig): Observable<KeyboardEvent>;
     /**
-     * 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.
+     * Registers a key sequence shortcut (e.g., g -> i, or ArrowUp -> ArrowUp -> ArrowDown)
+     * and returns an Observable that emits the final `KeyboardEvent` of the sequence when it's completed.
      * 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.
+     * Or using string for `sequence`.
+     * @returns An `Observable<KeyboardEvent>` that you can subscribe to. The stream will be automatically
+     * completed if the shortcut is removed via `remove(id)` or `destroy()`, or if it's overwritten.
+     * If the configuration is invalid, an empty Observable is returned and a warning is logged.
      * @example
      * ```typescript
      * import { Keys } from "./keys";
-     * keyManager.addSequence({
+     * const konami$ = 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
      * });
+     * konami$.subscribe(event => console.log("Konami!", event));
+     * ```
+     * ```typescript
+     * // Using a string for the sequence
+     * const konami$ = keyManager.addSequence({
+     * id: "konamiCode",
+     * sequence: "up -> up -> down -> down -> a -> b",
+     * sequenceTimeoutMs: 2000
+     * });
+     * konami$.subscribe(event => console.log("Konami!", event));
      * ```
      */
-    addSequence(config: KeySequenceConfig): string | undefined;
+    addSequence(config: KeySequenceConfig): Observable<KeyboardEvent>;
     /**
      * Removes a registered shortcut by its ID.
-     * This will unsubscribe from the underlying keyboard event stream for that shortcut.
+     * This will complete the corresponding Observable stream for any subscribers.
      * @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.

package/dist/hotkeys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../src/hotkeys.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../src/hotkeys.ts"],"names":[],"mappings":"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"}