rx-hotkeys 2.6.1 → 3.1.1

package/dist/{hotkeys.d.ts → core/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/core/hotkeys.d.ts.map

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