rx-hotkeys 2.4.1 → 2.6.0

package/dist/hotkeys.test.js

@@ -257,7 +257,7 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             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 "key" property in shortcut "nullKey". Key must be a non-empty value from Keys.`));
+            assert.ok(consoleWarnMock.mock.calls[0].arguments[0].includes(`Invalid "key" property in shortcut "nullKey". Key must be a non-empty string value from Keys.`));
         });
         it("should pass the KeyboardEvent to the callback", () => {
             const config = { id: "eventPass", keys: { key: Keys.E }, callback: mockCallback };
@@ -442,6 +442,178 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             });
         });
     });
+    describe("Context Priority (Specific > Global)", () => {
+        let globalCallback;
+        let specificCallback;
+        beforeEach(() => {
+            globalCallback = createMockFn();
+            specificCallback = createMockFn();
+            // Global shortcut: Ctrl+G
+            keyManager.addCombination({
+                id: "globalCtrlG",
+                keys: { key: Keys.G, ctrlKey: true },
+                callback: globalCallback,
+                context: null // Explicitly global
+            });
+            // Specific context shortcut: Ctrl+G in "editor" context
+            keyManager.addCombination({
+                id: "editorCtrlG",
+                keys: { key: Keys.G, ctrlKey: true },
+                callback: specificCallback,
+                context: "editor"
+            });
+        });
+        it("should only trigger specific context callback when specific context is active", () => {
+            keyManager.setContext("editor");
+            dispatchKeyEvent(Keys.G, { ctrlKey: true });
+            assert.strictEqual(specificCallback.calledCount, 1, "Specific callback should have been called");
+            assert.strictEqual(globalCallback.calledCount, 0, "Global callback should NOT have been called");
+        });
+        it("should only trigger global callback when no specific context is active (or context doesn't match)", () => {
+            keyManager.setContext(null); // No specific context
+            dispatchKeyEvent(Keys.G, { ctrlKey: true });
+            assert.strictEqual(specificCallback.calledCount, 0, "Specific callback should NOT have been called");
+            assert.strictEqual(globalCallback.calledCount, 1, "Global callback should have been called");
+            globalCallback.mockClear();
+            keyManager.setContext("anotherContext"); // Different specific context
+            dispatchKeyEvent(Keys.G, { ctrlKey: true });
+            assert.strictEqual(specificCallback.calledCount, 0, `Specific callback should NOT have been called for "anotherContext"`);
+            assert.strictEqual(globalCallback.calledCount, 1, `Global callback should have been called when in "anotherContext"`);
+        });
+    });
+    describe("Sequence Context Priority (Specific > Global)", () => {
+        let globalSeqCallback;
+        let specificSeqCallback;
+        const testSequence = [Keys.G, Keys.I];
+        beforeEach(() => {
+            globalSeqCallback = createMockFn();
+            specificSeqCallback = createMockFn();
+            keyManager.addSequence({
+                id: "globalGI",
+                sequence: testSequence,
+                callback: globalSeqCallback,
+                context: null // Global
+            });
+            keyManager.addSequence({
+                id: "editorGI",
+                sequence: testSequence,
+                callback: specificSeqCallback,
+                context: "editor" // Specific
+            });
+        });
+        it("should only trigger specific context sequence callback when specific context is active", () => {
+            keyManager.setContext("editor");
+            testSequence.forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(specificSeqCallback.calledCount, 1, "Specific sequence callback should have been called");
+            assert.strictEqual(globalSeqCallback.calledCount, 0, "Global sequence callback should NOT have been called");
+        });
+        it("should only trigger global sequence callback when no specific context is active (or context doesn't match)", () => {
+            keyManager.setContext(null); // No specific context
+            testSequence.forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(specificSeqCallback.calledCount, 0, "Specific sequence callback should NOT have been called");
+            assert.strictEqual(globalSeqCallback.calledCount, 1, "Global sequence callback should have been called");
+            globalSeqCallback.mockClear();
+            specificSeqCallback.mockClear(); // Clear for next part of test
+            keyManager.setContext("anotherContext"); // Different specific context
+            testSequence.forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(specificSeqCallback.calledCount, 0, `Specific sequence callback should NOT have been called for "anotherContext"`);
+            assert.strictEqual(globalSeqCallback.calledCount, 1, `Global sequence callback should have been called when in "anotherContext"`);
+        });
+    });
+    describe("Global Shortcut Context Behavior (`strict` flag)", () => {
+        let strictGlobalCallback;
+        let defaultGlobalCallback;
+        let specificContextCallback;
+        beforeEach(() => {
+            strictGlobalCallback = createMockFn();
+            defaultGlobalCallback = createMockFn();
+            specificContextCallback = createMockFn();
+            // 1. A specific shortcut for the "editor" context
+            keyManager.addCombination({
+                id: "editorSave",
+                keys: { key: Keys.S, ctrlKey: true },
+                callback: specificContextCallback,
+                context: "editor"
+            });
+            // 2. A "strictly global" shortcut, which only runs when context is null
+            keyManager.addCombination({
+                id: "strictGlobalOpen",
+                keys: { key: Keys.O, ctrlKey: true }, // Using shorthand is now possible!
+                callback: strictGlobalCallback,
+                strict: true, // `strict` is at the top level
+            });
+            // 3. A default global shortcut, which runs in any context unless overridden
+            keyManager.addCombination({
+                id: "defaultGlobalSave",
+                keys: { key: Keys.S, ctrlKey: true },
+                callback: defaultGlobalCallback,
+                // No `strict` flag here
+            });
+        });
+        it("should trigger both strict and default global shortcuts when context is null", () => {
+            keyManager.setContext(null);
+            dispatchKeyEvent(Keys.O, { ctrlKey: true });
+            assert.strictEqual(strictGlobalCallback.calledCount, 1, "Strictly global (Ctrl+O) should fire");
+            dispatchKeyEvent(Keys.S, { ctrlKey: true });
+            assert.strictEqual(defaultGlobalCallback.calledCount, 1, "Default global (Ctrl+S) should fire");
+            assert.strictEqual(specificContextCallback.calledCount, 0, "Specific context callback should not fire");
+        });
+        it("should suppress strict global but allow default global (which is then suppressed by priority)", () => {
+            keyManager.setContext("editor");
+            dispatchKeyEvent(Keys.O, { ctrlKey: true });
+            assert.strictEqual(strictGlobalCallback.calledCount, 0, "Strictly global (Ctrl+O) should NOT fire in 'editor' context");
+            dispatchKeyEvent(Keys.S, { ctrlKey: true });
+            assert.strictEqual(defaultGlobalCallback.calledCount, 0, "Default global (Ctrl+S) should be suppressed by the specific one");
+            assert.strictEqual(specificContextCallback.calledCount, 1, "Specific 'editor' callback (Ctrl+S) should fire and take priority");
+        });
+        it("should suppress strict global but trigger default global in a non-conflicting context", () => {
+            keyManager.setContext("someOtherContext");
+            dispatchKeyEvent(Keys.O, { ctrlKey: true });
+            assert.strictEqual(strictGlobalCallback.calledCount, 0, "Strictly global (Ctrl+O) should NOT fire in 'someOtherContext'");
+            dispatchKeyEvent(Keys.S, { ctrlKey: true });
+            assert.strictEqual(defaultGlobalCallback.calledCount, 1, "Default global (Ctrl+S) should fire since no override exists for this context");
+            assert.strictEqual(specificContextCallback.calledCount, 0, "Specific 'editor' callback should not fire");
+        });
+    });
+    describe("Sequence Context Behavior (`strict` flag)", () => {
+        // This test suite remains valid as `addSequence` already had the correct structure.
+        let strictSeqCallback;
+        let defaultSeqCallback;
+        let specificSeqCallback;
+        const testSequence = [Keys.M, Keys.A, Keys.P];
+        beforeEach(() => {
+            strictSeqCallback = createMockFn();
+            defaultSeqCallback = createMockFn();
+            specificSeqCallback = createMockFn();
+            keyManager.addSequence({ id: "strictSeq", sequence: [Keys.G, Keys.O], callback: strictSeqCallback, strict: true });
+            keyManager.addSequence({ id: "defaultSeq", sequence: testSequence, callback: defaultSeqCallback });
+            keyManager.addSequence({ id: "specificSeq", sequence: testSequence, callback: specificSeqCallback, context: "editor" });
+        });
+        it("should trigger both strict and default global sequences when context is null", () => {
+            keyManager.setContext(null);
+            [Keys.G, Keys.O].forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(strictSeqCallback.calledCount, 1, "Strict sequence should fire");
+            testSequence.forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(defaultSeqCallback.calledCount, 1, "Default sequence should fire");
+            assert.strictEqual(specificSeqCallback.calledCount, 0, "Specific sequence should not fire");
+        });
+        it("should suppress strict sequence and prioritize specific sequence in a matching context", () => {
+            keyManager.setContext("editor");
+            [Keys.G, Keys.O].forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(strictSeqCallback.calledCount, 0, "Strict sequence should NOT fire in 'editor' context");
+            testSequence.forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(defaultSeqCallback.calledCount, 0, "Default global sequence should be suppressed");
+            assert.strictEqual(specificSeqCallback.calledCount, 1, "Specific 'editor' sequence should fire");
+        });
+        it("should suppress strict sequence but trigger default global sequence in a non-conflicting context", () => {
+            keyManager.setContext("someOtherContext");
+            [Keys.G, Keys.O].forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(strictSeqCallback.calledCount, 0, "Strict sequence should NOT fire");
+            testSequence.forEach(key => dispatchKeyEvent(key));
+            assert.strictEqual(defaultSeqCallback.calledCount, 1, "Default global sequence should fire");
+            assert.strictEqual(specificSeqCallback.calledCount, 0, "Specific 'editor' sequence should not fire");
+        });
+    });
     describe("addSequence", () => {
         it("should trigger callback for a simple key sequence", () => {
             const config = { id: "seqGI", sequence: [Keys.G, Keys.I], callback: mockCallback };

package/dist/tt.d.ts

@@ -0,0 +1,125 @@
+import { Subscription, Observable } from "rxjs";
+import { type StandardKey } from "./keys.js";
+export declare enum ShortcutTypes {
+    Combination = "combination",
+    Sequence = "sequence"
+}
+interface ShortcutConfigBase {
+    id: string;
+    callback: (event: KeyboardEvent) => void;
+    context?: string | null;
+    preventDefault?: boolean;
+    description?: string;
+    /**
+     * **Only applicable if the shortcut has no top-level `context` defined.**
+     * If `true`, this shortcut is **strictly global** and will only fire when the active
+     * hotkey context is `null`.
+     * If `false` or `undefined` (the default), the shortcut can fire in *any* context,
+     * but will be suppressed by an identical shortcut that belongs to the active context.
+     * @default false
+     */
+    strict?: boolean;
+}
+/**
+ * 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`).
+     */
+    key: StandardKey;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    shiftKey?: boolean;
+    metaKey?: boolean;
+} | StandardKey;
+export interface KeyCombinationConfig extends ShortcutConfigBase {
+    /**
+     * Defines the key or key combination(s) that trigger the shortcut.
+     */
+    keys: KeyCombinationTrigger | KeyCombinationTrigger[];
+}
+export interface KeySequenceConfig extends ShortcutConfigBase {
+    /**
+     * An array of keys that form the sequence.
+     */
+    sequence: StandardKey[];
+    /**
+     * Optional: Timeout in milliseconds between consecutive key presses in the sequence.
+     * @default undefined
+     */
+    sequenceTimeoutMs?: number;
+}
+type ShortcutConfig = KeyCombinationConfig | KeySequenceConfig;
+export interface ActiveShortcut {
+    id: string;
+    config: ShortcutConfig;
+    subscription: Subscription;
+}
+/**
+ * Manages keyboard shortcuts for web applications.
+ */
+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.
+     * @param debugMode - Optional. If true, debug messages will be logged to the console.
+     */
+    constructor(initialContext?: string | null, debugMode?: boolean);
+    /**
+     * Sets the active context for shortcuts.
+     * @param contextName - The name of the context (e.g., "editor"). Pass `null` to clear the context.
+     * @returns `true` if the context was changed, `false` otherwise.
+     */
+    setContext(contextName: string | null): boolean;
+    /**
+     * Gets the current active context.
+     */
+    getContext(): string | null;
+    /**
+     * Enables or disables debug logging.
+     */
+    setDebugMode(enable: boolean): void;
+    /**
+     * Checks if a shortcut with the given ID is registered.
+     */
+    hasShortcut(id: string): boolean;
+    /**
+     * An Observable that emits the new context name whenever it changes.
+     */
+    get onContextChange$(): Observable<string | null>;
+    private _areSequencesIdentical;
+    private _shortcutMatchesEvent;
+    private _registerShortcut;
+    private _parseKeyTrigger;
+    addCombination(config: KeyCombinationConfig): string | undefined;
+    addSequence(config: KeySequenceConfig): string | undefined;
+    /**
+     * Removes a registered shortcut by its ID.
+     */
+    remove(id: string): boolean;
+    /**
+     * Retrieves a list of all currently active shortcuts.
+     */
+    getActiveShortcuts(): {
+        id: string;
+        description?: string;
+        context?: string | null;
+        type: ShortcutTypes;
+    }[];
+    /**
+     * Cleans up all active subscriptions.
+     */
+    destroy(): void;
+}
+export {};
+//# sourceMappingURL=tt.d.ts.map

package/dist/tt.d.ts.map

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