rx-hotkeys 2.3.0 → 2.4.0

package/README.md

@@ -165,7 +165,7 @@ Cleans up all subscriptions and resources. Essential to call to prevent memory l
 `KeyCombinationConfig`
 
 * `id: string` (required): Unique identifier for the shortcut.
-* `keys: { key: StandardKey; ctrlKey?: boolean; altKey?: boolean; shiftKey?: boolean; metaKey?: boolean; } | StandardKey` (required): Defines the main key (from Keys) and optional modifier keys.
+* `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.
 * `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`.

package/dist/hotkeys.d.ts

@@ -1,5 +1,5 @@
-import { Observable } from "rxjs";
-import { StandardKey } from "./keys.js";
+import { Subscription, Observable } from "rxjs";
+import { type StandardKey } from "./keys.js";
 export declare enum ShortcutTypes {
     Combination = "combination",
     Sequence = "sequence"
@@ -11,6 +11,27 @@ interface ShortcutConfigBase {
     preventDefault?: boolean;
     description?: string;
 }
+/**
+ * Defines a single key trigger, which can be a StandardKey (for simple presses like "Escape")
+ * or an object specifying the main key and its modifiers (e.g., { key: Keys.S, ctrlKey: true }).
+ */
+type KeyCombinationTrigger = {
+    /**
+     * 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;
+} | StandardKey;
 export interface KeyCombinationConfig extends ShortcutConfigBase {
     /**
      * Defines the key or key combination.
@@ -23,23 +44,7 @@ export interface KeyCombinationConfig extends ShortcutConfigBase {
      * Example: `Keys.Escape` for the Escape key. When using this shorthand,
      * it implies that no modifier keys (Ctrl, Alt, Shift, Meta) should be active.
      */
-    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;
-    } | StandardKey;
+    keys: KeyCombinationTrigger | KeyCombinationTrigger[];
 }
 export interface KeySequenceConfig extends ShortcutConfigBase {
     /**
@@ -59,6 +64,12 @@ export interface KeySequenceConfig extends ShortcutConfigBase {
      */
     sequenceTimeoutMs?: number;
 }
+type ShortcutConfig = KeyCombinationConfig | KeySequenceConfig;
+export interface ActiveShortcut {
+    id: string;
+    config: ShortcutConfig;
+    subscription: Subscription;
+}
 /**
  * Manages keyboard shortcuts for web applications.
  * Allows registration of single key combinations (e.g., Ctrl+S) and key sequences (e.g., g -> i).
@@ -125,6 +136,14 @@ export declare class Hotkeys {
     hasShortcut(id: string): boolean;
     private filterByContext;
     private _registerShortcut;
+    /**
+     * Parses a single key trigger definition (either shorthand StandardKey or an object with modifiers)
+     * into its constituent parts: main key and modifier states.
+     * @param keyInput - The KeyCombinationTrigger to parse.
+     * @param shortcutId - The ID of the shortcut this key trigger belongs to (for logging).
+     * @returns An object containing configuredMainKey and modifier states, or null if parsing fails.
+     */
+    private _parseKeyTrigger;
     /**
      * 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.

package/dist/hotkeys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../src/hotkeys.ts"],"names":[],"mappings":"AAAA,OAAO,EACuC,UAAU,EAEvD,MAAM,MAAM,CAAC;AACd,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAIxC,oBAAY,aAAa;IACrB,WAAW,gBAAgB;IAC3B,QAAQ,aAAa;CACxB;AAED,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;;;;;;;;;;OAUG;IACH,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,GAAG,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IACzD;;;;;;;;OAQG;IACH,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAyCD;;;;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;;;;;;;OAOG;IACI,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAkBtD;;;OAGG;IACI,UAAU,IAAI,MAAM,GAAG,IAAI;IAIlC;;;;OAIG;IACI,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAa1C;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAW,gBAAgB,IAAI,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,CAEvD;IAED;;;;OAIG;IACI,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIvC,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,iBAAiB;IAkBzB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS;IAgFvE;;;;;;;;;;;;;;;;;;;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,CAAA;KAAC,EAAE;IAa/G;;;;;OAKG;IACI,OAAO,IAAI,IAAI;CAOzB"}
+{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../src/hotkeys.ts"],"names":[],"mappings":"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"}

package/dist/hotkeys.js

@@ -1,4 +1,4 @@
-import { fromEvent, BehaviorSubject, EMPTY, filter, map, bufferCount, withLatestFrom, tap, catchError, scan, } from "rxjs";
+import { fromEvent, BehaviorSubject, EMPTY, filter, map, bufferCount, withLatestFrom, tap, catchError, scan, merge, } from "rxjs";
 // --- Enums, Interfaces and Types ---
 export var ShortcutTypes;
 (function (ShortcutTypes) {
@@ -150,6 +150,34 @@ export class Hotkeys {
         }
         return config.id;
     }
+    /**
+     * Parses a single key trigger definition (either shorthand StandardKey or an object with modifiers)
+     * into its constituent parts: main key and modifier states.
+     * @param keyInput - The KeyCombinationTrigger to parse.
+     * @param shortcutId - The ID of the shortcut this key trigger belongs to (for logging).
+     * @returns An object containing configuredMainKey and modifier states, or null if parsing fails.
+     */
+    _parseKeyTrigger(keyInput, shortcutId) {
+        if (typeof keyInput === "string") {
+            if (keyInput === "") {
+                console.warn(`${Hotkeys.LOG_PREFIX} Invalid key (shorthand) in shortcut "${shortcutId}". Key string must not be empty.`);
+                return null;
+            }
+            return { configuredMainKey: keyInput, ctrlKeyConfig: false, altKeyConfig: false, shiftKeyConfig: false, metaKeyConfig: false, logDetails: `key: "${keyInput}" (no mods)` };
+        }
+        else {
+            if (!keyInput.key || keyInput.key === "") {
+                console.warn(`${Hotkeys.LOG_PREFIX} Invalid "key" property in shortcut "${shortcutId}". Key must be a non-empty value from Keys.`);
+                return null;
+            }
+            const logDetails = `key: "${keyInput.key}"` +
+                (keyInput.ctrlKey !== undefined ? `, ctrl: ${keyInput.ctrlKey}` : "") +
+                (keyInput.altKey !== undefined ? `, alt: ${keyInput.altKey}` : "") +
+                (keyInput.shiftKey !== undefined ? `, shift: ${keyInput.shiftKey}` : "") +
+                (keyInput.metaKey !== undefined ? `, meta: ${keyInput.metaKey}` : "");
+            return { configuredMainKey: keyInput.key, ctrlKeyConfig: keyInput.ctrlKey, altKeyConfig: keyInput.altKey, shiftKeyConfig: keyInput.shiftKey, metaKeyConfig: keyInput.metaKey, logDetails };
+        }
+    }
     /**
      * 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.
@@ -178,67 +206,50 @@ export class Hotkeys {
      */
     addCombination(config) {
         const { keys, callback, context, preventDefault = false, id } = config;
-        let configuredMainKey;
-        let ctrlKeyConfig;
-        let altKeyConfig;
-        let shiftKeyConfig;
-        let metaKeyConfig;
-        let keyDetailsForLog;
-        if (typeof keys === "string") {
-            // Shorthand: keys is StandardKey, implying no modifiers should be active
-            // Corrected validation: Check for actual empty string, not a string that trims to empty.
-            if (keys === "") { // StandardKey type should prevent this, but check for robustness.
-                console.warn(`${Hotkeys.LOG_PREFIX} Invalid "keys" (shorthand) for combination shortcut "${id}". Key must not be an empty string. Shortcut not added.`);
-                return undefined;
-            }
-            configuredMainKey = keys;
-            ctrlKeyConfig = false; // Shorthand implies no modifiers
-            altKeyConfig = false;
-            shiftKeyConfig = false;
-            metaKeyConfig = false;
-            keyDetailsForLog = `key: "${keys}" (no modifiers implied)`;
+        let finalShortcut$;
+        let overallLogDetails = "";
+        const keyTriggers = Array.isArray(keys) ? keys : [keys];
+        if (keyTriggers.length === 0) {
+            console.warn(`${Hotkeys.LOG_PREFIX} "keys" array for combination shortcut "${id}" is empty. Shortcut not added.`);
+            return undefined;
         }
-        else {
-            // Object form
-            // Corrected validation for keys.key
-            if (!keys || !keys.key || typeof keys.key !== "string" || keys.key === "") { // StandardKey type should prevent empty string for key.key
-                console.warn(`${Hotkeys.LOG_PREFIX} Invalid "keys.key" for combination shortcut "${id}". Key must be a non-empty string value from Keys. Shortcut not added.`);
+        const observables = [];
+        const logParts = [];
+        for (const keyInput of keyTriggers) {
+            const parsedTrigger = this._parseKeyTrigger(keyInput, id);
+            if (!parsedTrigger) {
+                // Error already logged by _parseKeyTrigger
                 return undefined;
             }
-            configuredMainKey = keys.key;
-            ctrlKeyConfig = keys.ctrlKey;
-            altKeyConfig = keys.altKey;
-            shiftKeyConfig = keys.shiftKey;
-            metaKeyConfig = keys.metaKey;
-            keyDetailsForLog = `key: "${keys.key}"` +
-                (keys.ctrlKey !== undefined ? `, ctrlKey: ${keys.ctrlKey}` : "") +
-                (keys.altKey !== undefined ? `, altKey: ${keys.altKey}` : "") +
-                (keys.shiftKey !== undefined ? `, shiftKey: ${keys.shiftKey}` : "") +
-                (keys.metaKey !== undefined ? `, metaKey: ${keys.metaKey}` : "");
+            const { configuredMainKey, ctrlKeyConfig, altKeyConfig, shiftKeyConfig, metaKeyConfig, logDetails } = parsedTrigger;
+            logParts.push(`{ ${logDetails} }`);
+            const stream = this.filterByContext(this.keydown$, context).pipe(filter(event => {
+                const ctrlMatch = (ctrlKeyConfig === undefined) ? true : (event.ctrlKey === ctrlKeyConfig);
+                const altMatch = (altKeyConfig === undefined) ? true : (event.altKey === altKeyConfig);
+                const shiftMatch = (shiftKeyConfig === undefined) ? true : (event.shiftKey === shiftKeyConfig);
+                const metaMatch = (metaKeyConfig === undefined) ? true : (event.metaKey === metaKeyConfig);
+                return ctrlMatch && altMatch && shiftMatch && metaMatch;
+            }), filter(event => compareKey(event.key, configuredMainKey)));
+            observables.push(stream);
         }
-        const shortcut$ = this.filterByContext(this.keydown$, context).pipe(filter(event => {
-            // For shorthand (where modifiers are explicitly false), we want an exact match.
-            // For object form:
-            // - if modifier is true, event.modifier must be true.
-            // - if modifier is false, event.modifier must be false.
-            // - if modifier is undefined, we don't care about event.modifier.
-            const ctrlMatch = (ctrlKeyConfig === undefined) ? true : (event.ctrlKey === ctrlKeyConfig);
-            const altMatch = (altKeyConfig === undefined) ? true : (event.altKey === altKeyConfig);
-            const shiftMatch = (shiftKeyConfig === undefined) ? true : (event.shiftKey === shiftKeyConfig);
-            const metaMatch = (metaKeyConfig === undefined) ? true : (event.metaKey === metaKeyConfig);
-            return ctrlMatch && altMatch && shiftMatch && metaMatch;
-        }), filter(event => compareKey(event.key, configuredMainKey)), tap(event => {
+        if (observables.length === 0) {
+            // Should be caught by keyTriggers.length === 0, but as a safeguard.
+            console.warn(`${Hotkeys.LOG_PREFIX} No valid key triggers for combination shortcut "${id}". Shortcut not added.`);
+            return undefined;
+        }
+        finalShortcut$ = merge(...observables);
+        overallLogDetails = Array.isArray(keys) ? `Triggers: [ ${logParts.join(", ")} ]` : logParts[0];
+        const subscription = finalShortcut$.pipe(tap(event => {
             if (this.debugMode) {
                 const preventAction = preventDefault ? ", preventing default" : "";
-                console.log(`${Hotkeys.LOG_PREFIX} Combination "${id}" triggered${preventAction}.`);
+                console.log(`${Hotkeys.LOG_PREFIX} Combination "${id}" triggered by key "${event.key}" ${preventAction}.`);
             }
             if (preventDefault)
                 event.preventDefault();
         }), catchError(err => {
             console.error(`${Hotkeys.LOG_PREFIX} Error in combination stream for shortcut "${id}":`, err);
             return EMPTY;
-        }));
-        const subscription = shortcut$.subscribe(event => {
+        })).subscribe(event => {
             try {
                 callback(event);
             }
@@ -246,7 +257,7 @@ export class Hotkeys {
                 console.error(`${Hotkeys.LOG_PREFIX} Error in user callback for combination shortcut "${id}":`, e);
             }
         });
-        return this._registerShortcut(config, subscription, ShortcutTypes.Combination, `Keys: { ${keyDetailsForLog} }`); // Use Enum
+        return this._registerShortcut(config, subscription, ShortcutTypes.Combination, overallLogDetails);
     }
     /**
      * Registers a key sequence shortcut (e.g., g -> i, or ArrowUp -> ArrowUp -> ArrowDown).

package/dist/hotkeys.test.js

@@ -242,22 +242,22 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
         });
     });
     describe("addCombination", () => {
-        it("should trigger callback for a simple key combination (e.g., 'A')", () => {
+        it(`should trigger callback for a simple key combination (e.g., "A")`, () => {
             const config = { id: "simpleA", keys: { key: Keys.A }, callback: mockCallback };
             const result = keyManager.addCombination(config);
             assert.strictEqual(result, "simpleA");
             dispatchKeyEvent("a");
-            assert.strictEqual(mockCallback.calledCount, 1, "Callback for 'a' not called");
+            assert.strictEqual(mockCallback.calledCount, 1, `Callback for "a" not called`);
             mockCallback.mockClear();
             dispatchKeyEvent("A");
-            assert.strictEqual(mockCallback.calledCount, 1, "Callback for 'A' not called");
+            assert.strictEqual(mockCallback.calledCount, 1, `Callback for "A" not called`);
         });
         it("should return undefined and warn if keys.key is null or undefined (runtime check in object form)", () => {
             const config = { id: "nullKey", keys: { key: null }, callback: mockCallback };
             const result = keyManager.addCombination(config);
             assert.strictEqual(result, undefined, "Should return undefined for null key");
             assert.strictEqual(consoleWarnMock.mock.calls.length, 1);
-            assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid "keys.key" for combination shortcut "nullKey"`));
+            assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid "key" property in shortcut "nullKey". Key must be a non-empty value from Keys.`));
         });
         it("should pass the KeyboardEvent to the callback", () => {
             const config = { id: "eventPass", keys: { key: Keys.E }, callback: mockCallback };
@@ -317,30 +317,75 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             dispatchKeyEvent("w");
             assert.strictEqual(workingCallback.calledCount, 1);
         });
+        it("should trigger callback if any of multiple key combinations are pressed", () => {
+            const config = {
+                id: "multiCombo",
+                keys: [
+                    { key: Keys.A, ctrlKey: true }, // Ctrl+A
+                    Keys.Escape, // Escape
+                    { key: Keys.B, shiftKey: true, altKey: true } // Shift+Alt+B
+                ],
+                callback: mockCallback
+            };
+            keyManager.addCombination(config);
+            dispatchKeyEvent("A", { ctrlKey: true });
+            assert.strictEqual(mockCallback.calledCount, 1, "Ctrl+A did not trigger");
+            dispatchKeyEvent("Escape");
+            assert.strictEqual(mockCallback.calledCount, 2, "Escape did not trigger");
+            dispatchKeyEvent("B", { shiftKey: true, altKey: true });
+            assert.strictEqual(mockCallback.calledCount, 3, "Shift+Alt+B did not trigger");
+            dispatchKeyEvent("C"); // Should not trigger
+            assert.strictEqual(mockCallback.calledCount, 3, "Unrelated key C triggered");
+        });
+        it(`should return undefined and warn if "keys" array is empty`, () => {
+            const config = { id: "emptyKeysArray", keys: [], callback: mockCallback };
+            const result = keyManager.addCombination(config);
+            assert.strictEqual(result, undefined);
+            assert.ok(consoleWarnMock.mock.calls.some(call => call.arguments[0].includes(`"keys" array for combination shortcut "emptyKeysArray" is empty`)));
+        });
+        it(`should return undefined and warn if a key in "keys" array is invalid (shorthand)`, () => {
+            const config = { id: "invalidInArrayShorthand", keys: [Keys.A, ""], callback: mockCallback };
+            const result = keyManager.addCombination(config);
+            assert.strictEqual(result, undefined);
+            assert.ok(consoleWarnMock.mock.calls.some(call => call.arguments[0].includes(`Invalid key (shorthand) in shortcut "invalidInArrayShorthand"`)));
+        });
+        it(`should return undefined and warn if a key in "keys" array is invalid (object)`, () => {
+            const config = { id: "invalidInArrayObject", keys: [Keys.A, { key: "" }], callback: mockCallback };
+            const result = keyManager.addCombination(config);
+            assert.strictEqual(result, undefined);
+            assert.ok(consoleWarnMock.mock.calls.some(call => call.arguments[0].includes(`Invalid "key" property in shortcut "invalidInArrayObject"`)));
+        });
+        it("should correctly log multiple key triggers in debug mode", () => {
+            const consoleLogMock = mock.method(console, "log");
+            keyManager.setDebugMode(true);
+            keyManager.addCombination({ id: "multiLog", keys: [Keys.F1, { key: Keys.F2, ctrlKey: true }], callback: mockCallback });
+            assert.ok(consoleLogMock.mock.calls.some(call => call.arguments[0].includes(`Triggers: [ { key: "F1" (no mods) }, { key: "F2", ctrl: true } ]`)), "Multi-trigger log format incorrect");
+            consoleLogMock.mock.restore();
+        });
         describe("addCombination - Shorthand Syntax", () => {
             it("should trigger callback for a simple key using shorthand (e.g., Keys.X)", () => {
                 const config = { id: "shorthandX", keys: Keys.X, callback: mockCallback };
                 keyManager.addCombination(config);
                 dispatchKeyEvent(Keys.X.toLowerCase());
-                assert.strictEqual(mockCallback.calledCount, 1, "Callback for 'x' (shorthand) not called");
+                assert.strictEqual(mockCallback.calledCount, 1, `Callback for "x" (shorthand) not called`);
                 mockCallback.mockClear();
                 dispatchKeyEvent(Keys.X);
-                assert.strictEqual(mockCallback.calledCount, 1, "Callback for 'X' (shorthand) not called");
+                assert.strictEqual(mockCallback.calledCount, 1, `Callback for "X" (shorthand) not called`);
             });
             it("should NOT trigger callback for shorthand if modifier is pressed", () => {
                 const config = { id: "shorthandY", keys: Keys.Y, callback: mockCallback };
                 keyManager.addCombination(config);
                 dispatchKeyEvent(Keys.Y, { ctrlKey: true });
-                assert.strictEqual(mockCallback.calledCount, 0, "Callback for 'y' (shorthand) should not be called with Ctrl");
+                assert.strictEqual(mockCallback.calledCount, 0, `Callback for "y" (shorthand) should not be called with Ctrl`);
                 mockCallback.mockClear();
                 dispatchKeyEvent(Keys.Y, { altKey: true });
-                assert.strictEqual(mockCallback.calledCount, 0, "Callback for 'y' (shorthand) should not be called with Alt");
+                assert.strictEqual(mockCallback.calledCount, 0, `Callback for "y" (shorthand) should not be called with Alt`);
                 mockCallback.mockClear();
                 dispatchKeyEvent(Keys.Y, { shiftKey: true });
-                assert.strictEqual(mockCallback.calledCount, 0, "Callback for 'y' (shorthand) should not be called with Shift");
+                assert.strictEqual(mockCallback.calledCount, 0, `Callback for "y" (shorthand) should not be called with Shift`);
                 mockCallback.mockClear();
                 dispatchKeyEvent(Keys.Y, { metaKey: true });
-                assert.strictEqual(mockCallback.calledCount, 0, "Callback for 'y' (shorthand) should not be called with Meta");
+                assert.strictEqual(mockCallback.calledCount, 0, `Callback for "y" (shorthand) should not be called with Meta`);
             });
             it("should trigger callback for shorthand if ONLY the key is pressed (no modifiers)", () => {
                 const config = { id: "shorthandZ", keys: Keys.Z, callback: mockCallback };
@@ -370,16 +415,16 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
                 const result = keyManager.addCombination(config);
                 assert.strictEqual(result, undefined);
                 assert.strictEqual(consoleWarnMock.mock.calls.length, 1);
-                assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid "keys" (shorthand) for combination shortcut "emptyShorthand"`));
+                assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid key (shorthand) in shortcut "emptyShorthand". Key string must not be empty.`));
             });
             it("should correctly log shorthand key details in debug mode", () => {
                 const consoleLogMock = mock.method(console, "log");
                 keyManager.setDebugMode(true);
                 const config = { id: "debugShorthand", keys: Keys.D, callback: mockCallback };
                 keyManager.addCombination(config);
-                const logMessage = consoleLogMock.mock.calls.find(call => call.arguments[0].includes(`combination shortcut "debugShorthand" added`));
+                const logMessage = consoleLogMock.mock.calls.find(call => call.arguments[0].includes(`combination shortcut "debugShorthand" added.`));
                 assert.ok(logMessage, "Debug log for adding shortcut not found");
-                assert.ok(logMessage.arguments[0].includes(`Keys: { key: "D" (no modifiers implied) }`), `Log message content mismatch: ${logMessage.arguments[0]}`);
+                assert.ok(logMessage.arguments[0].includes(`{ key: "D" (no mods) }`), `Log message content mismatch: ${logMessage.arguments[0]}`);
                 consoleLogMock.mock.restore();
                 keyManager.setDebugMode(false);
             });
@@ -425,7 +470,7 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             assert.strictEqual(consoleWarnMock.mock.calls.length, 1);
             assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Sequence for shortcut "emptySeq" is empty`));
         });
-        it("should return undefined and warn if sequence contains an invalid key (runtime check with 'as any')", () => {
+        it(`should return undefined and warn if sequence contains an invalid key (runtime check with "as any")`, () => {
             // This test checks runtime robustness if `any` is used to bypass StandardKey[]
             const config = { id: "invalidKeyInSeq", sequence: [Keys.A, "", Keys.C], callback: mockCallback };
             const result = keyManager.addSequence(config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rx-hotkeys",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "type": "module",
   "scripts": {
     "build": "tsc",