rx-hotkeys 2.0.0 → 2.1.1

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; }` (required): Defines the main key (from Keys) and optional modifier keys.
+* `keys: { 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,4 +1,8 @@
 import { StandardKey } from "./keys.js";
+export declare enum ShortcutTypes {
+    Combination = "combination",
+    Sequence = "sequence"
+}
 interface ShortcutConfigBase {
     id: string;
     callback: (event?: KeyboardEvent) => void;
@@ -7,6 +11,17 @@ interface ShortcutConfigBase {
     description?: string;
 }
 export interface KeyCombinationConfig extends ShortcutConfigBase {
+    /**
+     * Defines the key or key combination.
+     * 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, this 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.
+     */
     keys: {
         /**
          * The main key for the combination.
@@ -23,7 +38,7 @@ export interface KeyCombinationConfig extends ShortcutConfigBase {
         altKey?: boolean;
         shiftKey?: boolean;
         metaKey?: boolean;
-    };
+    } | StandardKey;
 }
 export interface KeySequenceConfig extends ShortcutConfigBase {
     /**
@@ -90,22 +105,29 @@ export declare class Hotkeys {
     private filterByContext;
     private _registerShortcut;
     /**
-     * Registers a key combination shortcut (e.g., Ctrl+S, Shift+Enter).
-     * The callback is triggered when the specified key and modifier keys are pressed simultaneously.
+     * 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.
      * @param config - Configuration object for the key combination.
      * See {@link KeyCombinationConfig} for details.
-     * The `key` property within `config.keys` 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 key).
+     * 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.
      * @example
      * ```typescript
-     * import { Keys } from './keys';
+     * import { Keys } from "./keys";
+     * // For Ctrl+S
      * keyManager.addCombination({
      * id: "saveFile",
      * keys: { key: Keys.S, ctrlKey: true },
      * callback: () => console.log("File saved!"),
      * context: "editor"
      * });
+     * // For just the Escape key
+     * keyManager.addCombination({
+     * id: "closeModal",
+     * keys: Keys.Escape, // Shorthand syntax
+     * callback: () => console.log("Modal closed!")
+     * });
      * ```
      */
     addCombination(config: KeyCombinationConfig): string | undefined;
@@ -120,7 +142,7 @@ export declare class Hotkeys {
      * A warning is logged to the console if the configuration is invalid or if a shortcut with the same ID is overwritten.
      * @example
      * ```typescript
-     * import { Keys } from './keys';
+     * import { Keys } from "./keys";
      * keyManager.addSequence({
      * id: "konamiCode",
      * sequence: [Keys.ArrowUp, Keys.ArrowUp, Keys.ArrowDown, Keys.ArrowDown, Keys.A, Keys.B],
@@ -149,7 +171,7 @@ export declare class Hotkeys {
         id: string;
         description?: string;
         context?: string | null;
-        type: "combination" | "sequence";
+        type: ShortcutTypes;
     }[];
     /**
      * Cleans up all active subscriptions and resources used by the Hotkeys instance.

package/dist/hotkeys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../src/hotkeys.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAIxC,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,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,CAAC;CACL;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IACzD;;;;;;;;OAQG;IACH,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B;AA6BD;;;;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;;;;;;OAMG;IACI,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAOnD;;;OAGG;IACI,UAAU,IAAI,MAAM,GAAG,IAAI;IAIlC;;;;OAIG;IACI,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAO1C;;;;OAIG;IACI,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIvC,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,iBAAiB;IAkBzB;;;;;;;;;;;;;;;;;;OAkBG;IACI,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS;IA+CvE;;;;;;;;;;;;;;;;;;;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,GAAG,UAAU,CAAA;KAAC,EAAE;IAa5H;;;;;OAKG;IACI,OAAO,IAAI,IAAI;CAOzB"}
+{"version":3,"file":"hotkeys.d.ts","sourceRoot":"","sources":["../src/hotkeys.ts"],"names":[],"mappings":"AAIA,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;;;;;;OAMG;IACI,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAOnD;;;OAGG;IACI,UAAU,IAAI,MAAM,GAAG,IAAI;IAIlC;;;;OAIG;IACI,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAO1C;;;;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;IA6EvE;;;;;;;;;;;;;;;;;;;OAmBG;IACI,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS;IAiHjE;;;;;;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"}

package/dist/hotkeys.js

@@ -1,4 +1,10 @@
 import { fromEvent, BehaviorSubject, EMPTY, filter, map, bufferCount, withLatestFrom, tap, catchError, scan, } from "rxjs";
+// --- Enums, Interfaces and Types ---
+export var ShortcutTypes;
+(function (ShortcutTypes) {
+    ShortcutTypes["Combination"] = "combination";
+    ShortcutTypes["Sequence"] = "sequence";
+})(ShortcutTypes || (ShortcutTypes = {}));
 // --- Helper function to compare keys ---
 /**
  * Compares a browser event's key with a configured key.
@@ -15,6 +21,12 @@ function compareKey(eventKey, configuredKey) {
     return eventKey === configuredKey;
 }
 // --- Hotkeys Library ---
+var EmitStates;
+(function (EmitStates) {
+    EmitStates[EmitStates["Emit"] = 0] = "Emit";
+    EmitStates[EmitStates["Ignore"] = 1] = "Ignore";
+    EmitStates[EmitStates["InProgress"] = 2] = "InProgress";
+})(EmitStates || (EmitStates = {}));
 /**
  * Manages keyboard shortcuts for web applications.
  * Allows registration of single key combinations (e.g., Ctrl+S) and key sequences (e.g., g -> i).
@@ -36,7 +48,7 @@ export class Hotkeys {
     constructor(initialContext = null, debugMode = false) {
         this.debugMode = debugMode;
         if (typeof document === "undefined" || typeof performance === "undefined") {
-            throw new Error(`${Hotkeys.LOG_PREFIX} Hotkeys can only be used in a browser environment with global 'document' and 'performance' objects.`);
+            throw new Error(`${Hotkeys.LOG_PREFIX} Hotkeys can only be used in a browser environment with global "document" and "performance" objects.`);
         }
         this.keydown$ = fromEvent(document, Hotkeys.KEYDOWN_EVENT);
         this.activeContext$ = new BehaviorSubject(initialContext);
@@ -73,7 +85,7 @@ export class Hotkeys {
     setDebugMode(enable) {
         this.debugMode = enable;
         if (this.debugMode) {
-            console.log(`${Hotkeys.LOG_PREFIX} Debug mode ${enable ? 'enabled' : 'disabled'}.`);
+            console.log(`${Hotkeys.LOG_PREFIX} Debug mode ${enable ? "enabled" : "disabled"}.`);
         }
     }
     /**
@@ -87,7 +99,8 @@ export class Hotkeys {
     filterByContext(source$, context) {
         return source$.pipe(withLatestFrom(this.activeContext$), filter(([/* event */ , activeCtx]) => context == null || context === activeCtx), map(([event, /* _activeCtx */]) => event));
     }
-    _registerShortcut(config, subscription, type, detailsForLog) {
+    _registerShortcut(config, subscription, type, // Changed to use Enum
+    detailsForLog) {
         const existingShortcut = this.activeShortcuts.get(config.id);
         if (existingShortcut) {
             console.warn(`${Hotkeys.LOG_PREFIX} Shortcut with ID "${config.id}" already exists. It will be overwritten.`);
@@ -100,35 +113,81 @@ export class Hotkeys {
         return config.id;
     }
     /**
-     * Registers a key combination shortcut (e.g., Ctrl+S, Shift+Enter).
-     * The callback is triggered when the specified key and modifier keys are pressed simultaneously.
+     * 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.
      * @param config - Configuration object for the key combination.
      * See {@link KeyCombinationConfig} for details.
-     * The `key` property within `config.keys` 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 key).
+     * 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.
      * @example
      * ```typescript
-     * import { Keys } from './keys';
+     * import { Keys } from "./keys";
+     * // For Ctrl+S
      * keyManager.addCombination({
      * id: "saveFile",
      * keys: { key: Keys.S, ctrlKey: true },
      * callback: () => console.log("File saved!"),
      * context: "editor"
      * });
+     * // For just the Escape key
+     * keyManager.addCombination({
+     * id: "closeModal",
+     * keys: Keys.Escape, // Shorthand syntax
+     * callback: () => console.log("Modal closed!")
+     * });
      * ```
      */
     addCombination(config) {
         const { keys, callback, context, preventDefault = false, id } = config;
-        if (!keys || !keys.key || typeof keys.key !== 'string' || keys.key.trim() === '') {
-            console.warn(`${Hotkeys.LOG_PREFIX} Invalid 'keys.key' for combination shortcut "${id}". Key must be a non-empty value from Keys. Shortcut not added.`);
-            return undefined;
+        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
+            if (keys.trim() === "") {
+                console.warn(`${Hotkeys.LOG_PREFIX} Invalid "keys" (shorthand) for combination shortcut "${id}". Key string must not be empty. 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)`;
+        }
+        else {
+            // Object form
+            if (!keys || !keys.key || typeof keys.key !== "string" || keys.key.trim() === "") {
+                console.warn(`${Hotkeys.LOG_PREFIX} Invalid "keys.key" for combination shortcut "${id}". Key must be a non-empty value from Keys. Shortcut not added.`);
+                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 = keys.key;
-        const shortcut$ = this.filterByContext(this.keydown$, context).pipe(filter(event => (keys.ctrlKey === undefined || event.ctrlKey === keys.ctrlKey) &&
-            (keys.altKey === undefined || event.altKey === keys.altKey) &&
-            (keys.shiftKey === undefined || event.shiftKey === keys.shiftKey) &&
-            (keys.metaKey === undefined || event.metaKey === keys.metaKey)), filter(event => compareKey(event.key, configuredMainKey)), tap(event => {
+        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 (this.debugMode) {
                 const preventAction = preventDefault ? ", preventing default" : "";
                 console.log(`${Hotkeys.LOG_PREFIX} Combination "${id}" triggered${preventAction}.`);
@@ -147,12 +206,7 @@ export class Hotkeys {
                 console.error(`${Hotkeys.LOG_PREFIX} Error in user callback for combination shortcut "${id}":`, e);
             }
         });
-        const keyDetails = `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}` : "");
-        return this._registerShortcut(config, subscription, "Combination", `Keys: { ${keyDetails} }`);
+        return this._registerShortcut(config, subscription, ShortcutTypes.Combination, `Keys: { ${keyDetailsForLog} }`); // Use Enum
     }
     /**
      * Registers a key sequence shortcut (e.g., g -> i, or ArrowUp -> ArrowUp -> ArrowDown).
@@ -165,7 +219,7 @@ export class Hotkeys {
      * A warning is logged to the console if the configuration is invalid or if a shortcut with the same ID is overwritten.
      * @example
      * ```typescript
-     * import { Keys } from './keys';
+     * import { Keys } from "./keys";
      * keyManager.addSequence({
      * id: "konamiCode",
      * sequence: [Keys.ArrowUp, Keys.ArrowUp, Keys.ArrowDown, Keys.ArrowDown, Keys.A, Keys.B],
@@ -180,7 +234,7 @@ export class Hotkeys {
             console.warn(`${Hotkeys.LOG_PREFIX} Sequence for shortcut "${id}" is empty or invalid. Shortcut not added.`);
             return undefined;
         }
-        if (sequence.some(key => typeof key !== 'string' || key.trim() === '')) {
+        if (sequence.some(key => typeof key !== "string" || key.trim() === "")) {
             console.warn(`${Hotkeys.LOG_PREFIX} Invalid key in sequence for shortcut "${id}". All keys must be non-empty strings from Keys. Shortcut not added.`);
             return undefined;
         }
@@ -192,48 +246,52 @@ export class Hotkeys {
             shortcut$ = baseKeydownStream$.pipe(scan((acc, event) => {
                 let { matchedEvents, lastEventTime } = acc;
                 const currentTime = performance.now();
-                if (acc.emitState === 'emit') {
+                if (acc.emitState === EmitStates.Emit) {
                     matchedEvents = [];
                     lastEventTime = 0;
                 }
                 if (matchedEvents.length > 0 && (currentTime - lastEventTime > sequenceTimeoutMs)) {
                     if (this.debugMode) {
-                        console.log(`${Hotkeys.LOG_PREFIX} Sequence "${id}" (timeout: ${sequenceTimeoutMs}ms) attempt timed out. Matched: ${matchedEvents.map(e => e.key).join(',')}. Resetting.`);
+                        console.log(`${Hotkeys.LOG_PREFIX} Sequence "${id}" (timeout: ${sequenceTimeoutMs}ms) attempt timed out. Matched: ${matchedEvents.map(e => e.key).join(",")}. Resetting.`);
                     }
                     matchedEvents = [];
                 }
                 const nextExpectedKeyIndex = matchedEvents.length;
                 if (nextExpectedKeyIndex >= sequenceLength) {
+                    // Sequence was already emitted or buffer is too long (should not happen if reset correctly)
+                    // Start new sequence if current key matches the first key of the sequence
                     if (sequenceLength > 0 && compareKey(event.key, configuredSequence[0])) {
-                        return { matchedEvents: [event], lastEventTime: currentTime, emitState: 'in-progress' };
+                        return { matchedEvents: [event], lastEventTime: currentTime, emitState: EmitStates.InProgress };
                     }
-                    return { matchedEvents: [], lastEventTime: 0, emitState: 'ignore' };
+                    return { matchedEvents: [], lastEventTime: 0, emitState: EmitStates.Ignore };
                 }
                 if (compareKey(event.key, configuredSequence[nextExpectedKeyIndex])) {
                     const newMatchedEvents = [...matchedEvents, event];
                     if (newMatchedEvents.length === sequenceLength) {
-                        if (this.debugMode)
+                        if (this.debugMode && !acc.emitState)
                             console.log(`${Hotkeys.LOG_PREFIX} Sequence "${id}" (timeout: ${sequenceTimeoutMs}ms) matched.`);
-                        return { matchedEvents: newMatchedEvents, lastEventTime: currentTime, emitState: 'emit' };
+                        return { matchedEvents: newMatchedEvents, lastEventTime: currentTime, emitState: EmitStates.Emit };
                     }
                     else {
-                        return { matchedEvents: newMatchedEvents, lastEventTime: currentTime, emitState: 'in-progress' };
+                        return { matchedEvents: newMatchedEvents, lastEventTime: currentTime, emitState: EmitStates.InProgress };
                     }
                 }
                 else {
+                    // If current key breaks sequence, check if it starts a new sequence
                     if (matchedEvents.length > 0 && this.debugMode) {
-                        console.log(`${Hotkeys.LOG_PREFIX} Sequence "${id}" (timeout: ${sequenceTimeoutMs}ms) broken by key "${event.key}". Matched: ${matchedEvents.map(e => e.key).join(',')}. Resetting.`);
+                        console.log(`${Hotkeys.LOG_PREFIX} Sequence "${id}" (timeout: ${sequenceTimeoutMs}ms) broken by key "${event.key}". Matched: ${matchedEvents.map(e => e.key).join(",")}. Resetting.`);
                     }
                     if (sequenceLength > 0 && compareKey(event.key, configuredSequence[0])) {
-                        return { matchedEvents: [event], lastEventTime: currentTime, emitState: 'in-progress' };
+                        return { matchedEvents: [event], lastEventTime: currentTime, emitState: EmitStates.InProgress };
                     }
                     else {
-                        return { matchedEvents: [], lastEventTime: 0, emitState: 'ignore' };
+                        return { matchedEvents: [], lastEventTime: 0, emitState: EmitStates.Ignore };
                     }
                 }
-            }, { matchedEvents: [], lastEventTime: 0, emitState: 'ignore' }), filter(state => state.emitState === 'emit'), map(state => state.matchedEvents));
+            }, { matchedEvents: [], lastEventTime: 0, emitState: EmitStates.Ignore }), filter(state => state.emitState === EmitStates.Emit), map(state => state.matchedEvents));
         }
         else {
+            // No timeout logic: simple buffer-based matching
             shortcut$ = baseKeydownStream$.pipe(bufferCount(sequenceLength, 1), filter((events) => {
                 if (events.length < sequenceLength)
                     return false;
@@ -255,6 +313,7 @@ export class Hotkeys {
         }));
         const subscription = finalShortcut$.subscribe((events) => {
             try {
+                // Ensure callback receives the last event of the sequence, similar to combination.
                 if (events.length > 0)
                     callback(events[events.length - 1]);
             }
@@ -262,8 +321,8 @@ export class Hotkeys {
                 console.error(`${Hotkeys.LOG_PREFIX} Error in user callback for sequence shortcut "${id}":`, e);
             }
         });
-        const logDetails = `Sequence: ${sequence.join(" -> ")}${sequenceTimeoutMs && sequenceTimeoutMs > 0 ? ` (timeout: ${sequenceTimeoutMs}ms)` : ''}`;
-        return this._registerShortcut(config, subscription, "Sequence", logDetails);
+        const logDetails = `Sequence: ${sequence.join(" -> ")}${sequenceTimeoutMs && sequenceTimeoutMs > 0 ? ` (timeout: ${sequenceTimeoutMs}ms)` : ""}`;
+        return this._registerShortcut(config, subscription, ShortcutTypes.Sequence, logDetails); // Use Enum
     }
     /**
      * Removes a registered shortcut by its ID.
@@ -298,7 +357,7 @@ export class Hotkeys {
                 id,
                 description: activeShortcut.config.description,
                 context: activeShortcut.config.context,
-                type: 'keys' in activeShortcut.config ? "combination" : "sequence"
+                type: ("sequence" in activeShortcut.config) ? ShortcutTypes.Sequence : ShortcutTypes.Combination // Use Enum values
             });
         }
         return shortcuts;

package/dist/hotkeys.test.js

@@ -1,8 +1,6 @@
 import { describe, it, before, beforeEach, afterEach, mock } from "node:test";
 import assert from "node:assert";
-// Importing main library components
-import { Hotkeys } from "./hotkeys.js";
-// Importing Keys and StandardKey from the separate keys.js file
+import { Hotkeys, ShortcutTypes } from "./hotkeys.js";
 import { Keys } from "./keys.js";
 import { fromEvent, BehaviorSubject } from "rxjs";
 import { createMockFn, dispatchKeyEvent } from "./testutils.js";
@@ -27,14 +25,14 @@ before(() => {
     // @ts-ignore
     global.fromEvent = fromEvent;
     // @ts-ignore
-    if (typeof global.performance === 'undefined') {
+    if (typeof global.performance === "undefined") {
         // @ts-ignore
         global.performance = {};
     }
     // @ts-ignore
     originalPerformanceNow = global.performance.now;
     // @ts-ignore
-    if (typeof global.performance.now !== 'function') {
+    if (typeof global.performance.now !== "function") {
         // @ts-ignore
         global.performance.now = (() => {
             const start = Date.now();
@@ -70,6 +68,7 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             global.performance.now = originalPerformanceNow;
         }
     });
+    // ... (Initialization and Basic Context tests remain the same) ...
     describe("Initialization and Basic Context", () => {
         it("should initialize without errors", () => {
             assert(keyManager instanceof Hotkeys);
@@ -92,11 +91,11 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             const consoleLogMock = mock.method(console, "log");
             keyManager.setDebugMode(true);
             keyManager.setContext("debug_test");
-            assert.ok(consoleLogMock.mock.calls.some(call => call.arguments[0].includes('Context changed to "debug_test"')));
+            assert.ok(consoleLogMock.mock.calls.some(call => call.arguments[0].includes(`Context changed to "debug_test"`)));
             consoleLogMock.mock.resetCalls();
             keyManager.setDebugMode(false);
             keyManager.setContext("no_debug_test");
-            assert.ok(!consoleLogMock.mock.calls.some(call => call.arguments[0].includes('Context changed to "no_debug_test"')));
+            assert.ok(!consoleLogMock.mock.calls.some(call => call.arguments[0].includes(`Context changed to "no_debug_test"`)));
             consoleLogMock.mock.restore();
         });
     });
@@ -111,13 +110,12 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             dispatchKeyEvent("A");
             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)", () => {
-            // This test checks runtime robustness if `any` is used to bypass StandardKey
+        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 "keys.key" for combination shortcut "nullKey"`));
         });
         it("should pass the KeyboardEvent to the callback", () => {
             const config = { id: "eventPass", keys: { key: Keys.E }, callback: mockCallback };
@@ -140,14 +138,14 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             dispatchKeyEvent("a", { ctrlKey: false });
             assert.strictEqual(mockCallback.calledCount, 1);
         });
-        it("should trigger for special keys like Escape", () => {
-            const config = { id: "escapeKey", keys: { key: Keys.Escape }, callback: mockCallback };
+        it("should trigger for special keys like Escape (object form)", () => {
+            const config = { id: "escapeKeyObj", keys: { key: Keys.Escape }, callback: mockCallback };
             keyManager.addCombination(config);
             dispatchKeyEvent("Escape"); // Event key matches Keys.Escape
             assert.strictEqual(mockCallback.calledCount, 1);
         });
-        it("should handle preventDefault correctly", () => {
-            const config = { id: "preventA", keys: { key: Keys.A }, callback: mockCallback, preventDefault: true };
+        it("should handle preventDefault correctly (object form)", () => {
+            const config = { id: "preventAObj", keys: { key: Keys.A }, callback: mockCallback, preventDefault: true };
             keyManager.addCombination(config);
             const event = dispatchKeyEvent("a");
             assert.strictEqual(mockCallback.calledCount, 1);
@@ -173,25 +171,92 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             keyManager.addCombination({ id: "workingCombo", keys: { key: Keys.W }, callback: workingCallback });
             dispatchKeyEvent("e");
             assert.strictEqual(consoleErrorMock.mock.calls.length, 1);
-            assert.ok(consoleErrorMock.mock.calls[0].arguments[0].includes('Error in user callback for combination shortcut "errorCombo"'));
+            assert.ok(consoleErrorMock.mock.calls[0].arguments[0].includes(`Error in user callback for combination shortcut "errorCombo"`));
             dispatchKeyEvent("w");
             assert.strictEqual(workingCallback.calledCount, 1);
         });
+        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");
+                mockCallback.mockClear();
+                dispatchKeyEvent(Keys.X);
+                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");
+                mockCallback.mockClear();
+                dispatchKeyEvent(Keys.Y, { altKey: true });
+                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");
+                mockCallback.mockClear();
+                dispatchKeyEvent(Keys.Y, { metaKey: true });
+                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 };
+                keyManager.addCombination(config);
+                dispatchKeyEvent(Keys.Z, { ctrlKey: false, altKey: false, shiftKey: false, metaKey: false });
+                assert.strictEqual(mockCallback.calledCount, 1);
+            });
+            it("should handle preventDefault correctly for shorthand", () => {
+                const config = { id: "shorthandPrevent", keys: Keys.P, callback: mockCallback, preventDefault: true };
+                keyManager.addCombination(config);
+                const event = dispatchKeyEvent(Keys.P.toLowerCase());
+                assert.strictEqual(mockCallback.calledCount, 1);
+                assert.strictEqual(event.defaultPrevented, true);
+            });
+            it("should respect context for shorthand", () => {
+                const config = { id: "shorthandContext", keys: Keys.C, callback: mockCallback, context: "editor" };
+                keyManager.addCombination(config);
+                keyManager.setContext("other");
+                dispatchKeyEvent(Keys.C.toLowerCase());
+                assert.strictEqual(mockCallback.calledCount, 0);
+                keyManager.setContext("editor");
+                dispatchKeyEvent(Keys.C.toLowerCase());
+                assert.strictEqual(mockCallback.calledCount, 1);
+            });
+            it("should return undefined and warn if shorthand key is an empty string", () => {
+                const config = { id: "emptyShorthand", keys: "", callback: mockCallback };
+                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"`));
+            });
+            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`));
+                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]}`);
+                consoleLogMock.mock.restore();
+                keyManager.setDebugMode(false);
+            });
+        });
     });
     describe("addSequence", () => {
         it("should trigger callback for a simple key sequence", () => {
             const config = { id: "seqGI", sequence: [Keys.G, Keys.I], callback: mockCallback };
             const result = keyManager.addSequence(config);
             assert.strictEqual(result, "seqGI");
-            dispatchKeyEvent("g"); // Dispatch 'g' (lowercase)
-            dispatchKeyEvent("i"); // Dispatch 'i' (lowercase)
+            dispatchKeyEvent("g"); // Dispatch "g" (lowercase)
+            dispatchKeyEvent("i"); // Dispatch "i" (lowercase)
             assert.strictEqual(mockCallback.calledCount, 1);
         });
         it("should trigger callback for Konami code using Keys", () => {
             const konamiSequence = [
                 Keys.ArrowUp, Keys.ArrowUp, Keys.ArrowDown, Keys.ArrowDown,
                 Keys.ArrowLeft, Keys.ArrowRight, Keys.ArrowLeft, Keys.ArrowRight,
-                Keys.B, Keys.A // Using 'B' and 'A' from Keys
+                Keys.B, Keys.A // Using "B" and "A" from Keys
             ];
             const config = { id: "konami", sequence: konamiSequence, callback: mockCallback };
             keyManager.addSequence(config);
@@ -236,7 +301,7 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             dispatchKeyEvent("e");
             dispatchKeyEvent("s");
             assert.strictEqual(consoleErrorMock.mock.calls.length, 1);
-            assert.ok(consoleErrorMock.mock.calls[0].arguments[0].includes('Error in user callback for sequence shortcut "errorSeq"'));
+            assert.ok(consoleErrorMock.mock.calls[0].arguments[0].includes(`Error in user callback for sequence shortcut "errorSeq"`));
         });
         describe("Sequence Contextual Triggering", () => {
             let editorSequenceConfig;
@@ -317,17 +382,17 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
         });
     });
     describe("getActiveShortcuts", () => {
-        it("should return active combination and sequence shortcuts", () => {
+        it("should return active combination and sequence shortcuts with enum types", () => {
             keyManager.addCombination({ id: "combo1", keys: { key: Keys.A }, callback: createMockFn(), description: "Test A" });
             keyManager.addSequence({ id: "seq1", sequence: [Keys.B, Keys.C], callback: createMockFn(), context: "modal", description: "Test BC" });
             const active = keyManager.getActiveShortcuts();
             assert.strictEqual(active.length, 2);
             const combo = active.find(s => s.id === "combo1");
             assert.ok(combo);
-            assert.strictEqual(combo.type, "combination");
+            assert.strictEqual(combo.type, ShortcutTypes.Combination); // Use Enum for comparison
             const seq = active.find(s => s.id === "seq1");
             assert.ok(seq);
-            assert.strictEqual(seq.type, "sequence");
+            assert.strictEqual(seq.type, ShortcutTypes.Sequence); // Use Enum for comparison
         });
     });
     describe("hasShortcut", () => {
@@ -347,10 +412,10 @@ describe("Hotkeys Library (Node.js Test Runner)", () => {
             keyManager.addCombination({ id: "destroyTestCombo", keys: { key: Keys.D }, callback: mockCallback });
             keyManager.addSequence({ id: "destroyTestSeq", sequence: [Keys.X, Keys.Y], callback: mockCallback });
             // @ts-ignore
-            assert.strictEqual(keyManager['activeShortcuts'].size, 2);
+            assert.strictEqual(keyManager["activeShortcuts"].size, 2);
             keyManager.destroy();
             // @ts-ignore
-            assert.strictEqual(keyManager['activeShortcuts'].size, 0);
+            assert.strictEqual(keyManager["activeShortcuts"].size, 0);
             dispatchKeyEvent(Keys.D);
             dispatchKeyEvent(Keys.X);
             dispatchKeyEvent(Keys.Y);

package/package.json

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