rx-hotkeys 2.5.0 → 2.6.1

package/README.md

@@ -8,6 +8,7 @@ rx-hotkeys is a powerful and flexible TypeScript library for managing keyboard s
 * **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.
@@ -29,7 +30,7 @@ First, ensure you have the `rx-hotkeys` library and its helper Keys imported:
 import { Hotkeys, Keys, KeyCombinationConfig, KeySequenceConfig } from 'rx-hotkeys';
 ```
 
-1. Initialize Hotkeys
+### 1. Initialize Hotkeys
 
 Create an instance of the `Hotkeys` class. You can optionally provide an initial context and enable debug mode.
 
@@ -40,7 +41,7 @@ const keyManager = new Hotkeys(); // No initial context, debug mode off
 // const keyManager = new Hotkeys('editor', true);
 ```
 
-2. Add a Key Combination
+### 2. Add a Key Combination
 
 Register a shortcut for a key combination, like Ctrl+S.
 
@@ -58,7 +59,9 @@ const saveConfig: KeyCombinationConfig = {
 keyManager.addCombination(saveConfig);
 ```
 
-3. Add a Key SequenceRegister a shortcut for a sequence of keys, like the Konami code.
+### 3. Add a Key Sequence
+
+Register a shortcut for a sequence of keys, like the Konami code.
 
 ```typescript
 const konamiConfig: KeySequenceConfig = {
@@ -81,7 +84,9 @@ const konamiConfig: KeySequenceConfig = {
 keyManager.addSequence(konamiConfig);
 ```
 
-4. Manage ContextsControl which shortcuts are active by setting the context.
+### 4. Manage Contexts
+
+Control which shortcuts are active by setting the context.
 
 ```typescript
 // Assuming some shortcuts are configured with context: "editor"
@@ -91,7 +96,25 @@ keyManager.setContext("editor"); // Activates "editor" shortcuts and global shor
 keyManager.setContext(null);
 ```
 
-5. Clean Up
+#### 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 });
+    ```
+
+### 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.
 
@@ -170,6 +193,7 @@ Cleans up all subscriptions and resources. Essential to call to prevent memory l
 * `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).
+* `strict?: boolean` (optional): If `true` and the shortcut has no `context`, it will only fire when no other context is active. Defaults to `false`.
 
 `KeySequenceConfig`
 
@@ -180,13 +204,13 @@ Cleans up all subscriptions and resources. Essential to call to prevent memory l
 * `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`.
 
 
 ## 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.
-
+* **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
 

package/dist/hotkeys.d.ts

@@ -10,6 +10,15 @@ interface ShortcutConfigBase {
     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")

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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"}

package/dist/hotkeys.js

@@ -197,8 +197,20 @@ export class Hotkeys {
         }
         return false;
     }
-    filterByContext(source$, context) {
-        return source$.pipe(withLatestFrom(this.activeContext$), filter(([/* event */ , activeCtx]) => context == null || context === activeCtx), map(([event, /* _activeCtx */]) => event));
+    filterByContext(source$, context, strict) {
+        return source$.pipe(withLatestFrom(this.activeContext$), filter(([/* event */ , activeCtx]) => {
+            if (context == null) {
+                if (strict) {
+                    return activeCtx == null;
+                }
+                else {
+                    return true;
+                }
+            }
+            else {
+                return context === activeCtx;
+            }
+        }), map(([event, /* _activeCtx */]) => event));
     }
     _registerShortcut(config, subscription, type, detailsForLog) {
         const existingShortcut = this.activeShortcuts.get(config.id);
@@ -281,9 +293,10 @@ export class Hotkeys {
      * ```
      */
     addCombination(config) {
-        const { keys, callback, context, preventDefault = false, id } = config;
-        let finalShortcut$;
-        let overallLogDetails = "";
+        const { keys, callback, context, preventDefault = false, id, strict = false } = config;
+        if (context != null && strict) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" has both a context(${context}) and the 'strict' flag. The 'strict' flag will be ignored.`);
+        }
         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.`);
@@ -299,7 +312,7 @@ export class Hotkeys {
             }
             const { configuredMainKey, ctrlKeyConfig, altKeyConfig, shiftKeyConfig, metaKeyConfig, logDetails } = parsedTrigger;
             logParts.push(`{ ${logDetails} }`);
-            const stream = this.filterByContext(this.keydown$, context).pipe(filter(event => {
+            const stream = this.filterByContext(this.keydown$, context, strict).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);
@@ -308,7 +321,7 @@ export class Hotkeys {
             }), filter(event => compareKey(event.key, configuredMainKey)), 
             // New filter for priority: Specific context > Global context
             filter(event => {
-                if (config.context != null) { // This shortcut is NOT global
+                if (context != null || strict) { // This shortcut is NOT global or strict
                     return true;
                 }
                 // This shortcut IS global. Check for specific overrides.
@@ -317,12 +330,12 @@ export class Hotkeys {
                     return true;
                 }
                 for (const [, otherAS] of this.activeShortcuts) {
-                    if (otherAS.config.id !== config.id &&
+                    if (otherAS.config.id !== id &&
                         'keys' in otherAS.config &&
                         otherAS.config.context === currentSpecificContext &&
                         this._shortcutMatchesEvent(otherAS.config, event)) {
                         if (this.debugMode) {
-                            console.log(`${Hotkeys.LOG_PREFIX} Global shortcut "${config.id}" (key: "${event.key}") suppressed by specific context shortcut "${otherAS.config.id}".`);
+                            console.log(`${Hotkeys.LOG_PREFIX} Global shortcut "${id}" (key: "${event.key}") suppressed by specific context shortcut "${otherAS.config.id}".`);
                         }
                         return false; // Suppress global
                     }
@@ -336,8 +349,8 @@ export class Hotkeys {
             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 finalShortcut$ = merge(...observables);
+        const overallLogDetails = Array.isArray(keys) ? `Triggers: [ ${logParts.join(", ")} ]` : logParts[0];
         const subscription = finalShortcut$.pipe(tap(event => {
             if (this.debugMode) {
                 const preventAction = preventDefault ? ", preventing default" : "";
@@ -379,7 +392,7 @@ export class Hotkeys {
      * ```
      */
     addSequence(config) {
-        const { sequence, callback, context, preventDefault = false, id, sequenceTimeoutMs } = config;
+        const { sequence, callback, context, preventDefault = false, id, sequenceTimeoutMs, strict = false } = config;
         if (!Array.isArray(sequence) || sequence.length === 0) {
             console.warn(`${Hotkeys.LOG_PREFIX} Sequence for shortcut "${id}" is empty or invalid. Shortcut not added.`);
             return undefined;
@@ -389,10 +402,13 @@ export class Hotkeys {
             console.warn(`${Hotkeys.LOG_PREFIX} Invalid key in sequence for shortcut "${id}". All keys must be non-empty string values from Keys. Shortcut not added.`);
             return undefined;
         }
+        if (context && strict) {
+            console.warn(`${Hotkeys.LOG_PREFIX} Shortcut "${id}" has both a context and the 'strict' flag. The 'strict' flag will be ignored.`);
+        }
         const configuredSequence = sequence;
         const sequenceLength = configuredSequence.length;
         let shortcut$;
-        const baseKeydownStream$ = this.filterByContext(this.keydown$, context);
+        const baseKeydownStream$ = this.filterByContext(this.keydown$, context, strict);
         if (sequenceTimeoutMs && sequenceTimeoutMs > 0) {
             shortcut$ = baseKeydownStream$.pipe(scan((acc, event) => {
                 let { matchedEvents, lastEventTime } = acc;
@@ -450,7 +466,7 @@ export class Hotkeys {
             }));
         }
         const finalShortcutWithPriority$ = shortcut$.pipe(filter((completedEvents) => {
-            if (config.context != null) { // This sequence is NOT global
+            if (context != null || strict) { // This sequence is NOT global or strict
                 return true;
             }
             // This sequence IS global. Check for specific overrides.
@@ -459,12 +475,12 @@ export class Hotkeys {
                 return true;
             }
             for (const [, otherAS] of this.activeShortcuts) {
-                if (otherAS.config.id !== config.id &&
+                if (otherAS.config.id !== id &&
                     "sequence" in otherAS.config &&
                     otherAS.config.context === currentSpecificContext &&
-                    this._areSequencesIdentical(config.sequence, otherAS.config.sequence)) {
+                    this._areSequencesIdentical(sequence, otherAS.config.sequence)) {
                     if (this.debugMode) {
-                        console.log(`${Hotkeys.LOG_PREFIX} Global sequence shortcut "${config.id}" suppressed by identical specific-context shortcut "${otherAS.config.id}".`);
+                        console.log(`${Hotkeys.LOG_PREFIX} Global sequence shortcut "${id}" suppressed by identical specific-context shortcut "${otherAS.config.id}".`);
                     }
                     return false; // Suppress global
                 }

package/dist/hotkeys.test.js

@@ -520,6 +520,100 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             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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"}