ngx-keys 1.2.0 → 1.3.1

package/fesm2022/ngx-keys.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { DestroyRef, inject, DOCUMENT, signal, computed, afterNextRender, Injectable } from '@angular/core';
+import { InjectionToken, DestroyRef, inject, DOCUMENT, signal, computed, afterNextRender, Injectable, ElementRef, output, HostBinding, Input, Directive } from '@angular/core';
 import { Observable, take } from 'rxjs';
 
 /**
@@ -99,6 +99,204 @@ class KeyboardShortcutsErrorFactory {
     }
 }
 
+/**
+ * Injection token for providing KeyboardShortcuts configuration.
+ *
+ * @example
+ * ```typescript
+ * providers: [
+ *   provideKeyboardShortcutsConfig({ sequenceTimeoutMs: Infinity })
+ * ]
+ * ```
+ */
+const KEYBOARD_SHORTCUTS_CONFIG = new InjectionToken('KEYBOARD_SHORTCUTS_CONFIG', {
+    providedIn: 'root',
+    factory: () => ({})
+});
+/**
+ * Provides KeyboardShortcuts configuration using Angular's modern provider pattern.
+ *
+ * @param config - Configuration options for KeyboardShortcuts service
+ * @returns Provider array for use in Angular dependency injection
+ *
+ * @example
+ * ```typescript
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideKeyboardShortcutsConfig({ sequenceTimeoutMs: Infinity })
+ *   ]
+ * });
+ * ```
+ */
+function provideKeyboardShortcutsConfig(config) {
+    return [{ provide: KEYBOARD_SHORTCUTS_CONFIG, useValue: config }];
+}
+/**
+ * Initial version number for state change detection.
+ * Used internally to track state updates efficiently.
+ * @internal
+ */
+const INITIAL_STATE_VERSION = 0;
+/**
+ * Increment value for state version updates.
+ * @internal
+ */
+const STATE_VERSION_INCREMENT = 1;
+/**
+ * Index of the first element in an array.
+ * Used for readability when checking array structure.
+ * @internal
+ */
+const FIRST_INDEX = 0;
+/**
+ * Index representing the first step in a multi-step sequence.
+ * @internal
+ */
+const FIRST_STEP_INDEX = 0;
+/**
+ * Index representing the second step in a multi-step sequence (after first step completes).
+ * @internal
+ */
+const SECOND_STEP_INDEX = 1;
+/**
+ * Threshold for determining if a shortcut is a single-step sequence.
+ * @internal
+ */
+const SINGLE_STEP_LENGTH = 1;
+/**
+ * Minimum count indicating that at least one item exists.
+ * @internal
+ */
+const MIN_COUNT_ONE = 1;
+/**
+ * Minimum length for a valid key string.
+ * @internal
+ */
+const MIN_KEY_LENGTH = 0;
+
+/**
+ * Utility class for keyboard shortcut key matching and normalization.
+ * Provides methods for comparing key combinations and normalizing key input.
+ */
+class KeyMatcher {
+    static MODIFIER_KEYS = new Set(['ctrl', 'control', 'alt', 'shift', 'meta']);
+    /**
+     * Normalize a key string to lowercase for consistent comparison.
+     *
+     * @param key - The key string to normalize
+     * @returns The normalized (lowercase) key string
+     *
+     * @example
+     * ```typescript
+     * KeyMatcher.normalizeKey('Ctrl'); // returns 'ctrl'
+     * KeyMatcher.normalizeKey('A');    // returns 'a'
+     * ```
+     */
+    static normalizeKey(key) {
+        return key.toLowerCase();
+    }
+    /**
+     * Check if a key is a modifier key (ctrl, alt, shift, meta).
+     *
+     * @param key - The key to check
+     * @returns true if the key is a modifier key
+     *
+     * @example
+     * ```typescript
+     * KeyMatcher.isModifierKey('ctrl');  // returns true
+     * KeyMatcher.isModifierKey('a');     // returns false
+     * ```
+     */
+    static isModifierKey(key) {
+        return this.MODIFIER_KEYS.has(key.toLowerCase());
+    }
+    /**
+     * Compare two key combinations for equality.
+     * Supports both Set<string> and string[] as input.
+     * Keys are normalized (lowercased) before comparison.
+     *
+     * @param a - First key combination (Set or array)
+     * @param b - Second key combination (array)
+     * @returns true if both combinations contain the same keys
+     *
+     * @example
+     * ```typescript
+     * KeyMatcher.keysMatch(['ctrl', 's'], ['ctrl', 's']); // returns true
+     * KeyMatcher.keysMatch(['ctrl', 's'], ['Ctrl', 'S']); // returns true (normalized)
+     * KeyMatcher.keysMatch(['ctrl', 's'], ['alt', 's']);  // returns false
+     * ```
+     */
+    static keysMatch(a, b) {
+        const setA = a instanceof Set ? a : this.normalizeKeysToSet(a);
+        const setB = this.normalizeKeysToSet(b);
+        if (setA.size !== setB.size) {
+            return false;
+        }
+        for (const key of setA) {
+            if (!setB.has(key)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Compare two multi-step sequences for equality.
+     * Each sequence is an array of steps, where each step is an array of keys.
+     *
+     * @param a - First multi-step sequence
+     * @param b - Second multi-step sequence
+     * @returns true if both sequences are identical
+     *
+     * @example
+     * ```typescript
+     * const seq1 = [['ctrl', 'k'], ['s']];
+     * const seq2 = [['ctrl', 'k'], ['s']];
+     * KeyMatcher.stepsMatch(seq1, seq2); // returns true
+     *
+     * const seq3 = [['ctrl', 'k'], ['t']];
+     * KeyMatcher.stepsMatch(seq1, seq3); // returns false (different final step)
+     * ```
+     */
+    static stepsMatch(a, b) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (!this.keysMatch(a[i], b[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Normalize an array of keys to a Set of lowercase keys.
+     *
+     * @param keys - Array of keys to normalize
+     * @returns Set of normalized (lowercase) keys
+     *
+     * @internal
+     */
+    static normalizeKeysToSet(keys) {
+        return new Set(keys.map(k => k.toLowerCase()));
+    }
+    /**
+     * Get the set of modifier key names.
+     * Useful for filtering or checking if a key is a modifier.
+     *
+     * @returns ReadonlySet of modifier key names
+     *
+     * @example
+     * ```typescript
+     * const modifiers = KeyMatcher.getModifierKeys();
+     * console.log(modifiers.has('ctrl')); // true
+     * console.log(modifiers.has('a'));    // false
+     * ```
+     */
+    static getModifierKeys() {
+        return this.MODIFIER_KEYS;
+    }
+}
+
 /**
  * Type guard to detect KeyboardShortcutGroupOptions at runtime.
  * Centralising this logic keeps registerGroup simpler and less fragile.
@@ -129,9 +327,9 @@ function isDestroyRefLike(obj) {
     return typeof o['onDestroy'] === 'function';
 }
 class KeyboardShortcuts {
-    static MODIFIER_KEYS = new Set(['control', 'alt', 'shift', 'meta']);
     document = inject(DOCUMENT);
     window = this.document.defaultView;
+    config = inject(KEYBOARD_SHORTCUTS_CONFIG);
     shortcuts = new Map();
     groups = new Map();
     activeShortcuts = new Set();
@@ -150,7 +348,7 @@ class KeyboardShortcuts {
         groups: new Map(),
         activeShortcuts: new Set(),
         activeGroups: new Set(),
-        version: 0 // for change detection optimization
+        version: INITIAL_STATE_VERSION // for change detection optimization
     }, ...(ngDevMode ? [{ debugName: "state" }] : []));
     // Primary computed signal - consumers derive what they need from this
     shortcuts$ = computed(() => {
@@ -185,8 +383,6 @@ class KeyboardShortcuts {
     blurListener = this.handleWindowBlur.bind(this);
     visibilityListener = this.handleVisibilityChange.bind(this);
     isListening = false;
-    /** Default timeout (ms) for completing a multi-step sequence */
-    sequenceTimeout = 2000;
     /** Runtime state for multi-step sequences */
     pendingSequence = null;
     constructor() {
@@ -206,7 +402,7 @@ class KeyboardShortcuts {
             groups: new Map(this.groups),
             activeShortcuts: new Set(this.activeShortcuts),
             activeGroups: new Set(this.activeGroups),
-            version: current.version + 1
+            version: current.version + STATE_VERSION_INCREMENT
         }));
     }
     /**
@@ -253,17 +449,17 @@ class KeyboardShortcuts {
             return '';
         // If the first element is an array, assume steps is string[][]
         const normalized = this.normalizeToSteps(steps);
-        if (normalized.length === 0)
+        if (normalized.length === MIN_KEY_LENGTH)
             return '';
-        if (normalized.length === 1)
-            return this.formatKeysForDisplay(normalized[0], isMac);
+        if (normalized.length === SINGLE_STEP_LENGTH)
+            return this.formatKeysForDisplay(normalized[FIRST_INDEX], isMac);
         return normalized.map(step => this.formatKeysForDisplay(step, isMac)).join(', ');
     }
     normalizeToSteps(input) {
         if (!input)
             return [];
         // If first element is an array, assume already KeyStep[]
-        if (Array.isArray(input[0])) {
+        if (Array.isArray(input[FIRST_INDEX])) {
             return input;
         }
         // Single step array
@@ -293,6 +489,32 @@ class KeyboardShortcuts {
             if (newShortcut.macSteps && existing.macSteps && this.stepsMatch(newShortcut.macSteps, existing.macSteps)) {
                 return existing.id;
             }
+            // Check if new single-step shortcut conflicts with first step of existing multi-step shortcut
+            if (newShortcut.keys && existing.steps) {
+                const firstStep = existing.steps[FIRST_INDEX];
+                if (firstStep && this.keysMatch(newShortcut.keys, firstStep)) {
+                    return existing.id;
+                }
+            }
+            if (newShortcut.macKeys && existing.macSteps) {
+                const firstStep = existing.macSteps[FIRST_INDEX];
+                if (firstStep && this.keysMatch(newShortcut.macKeys, firstStep)) {
+                    return existing.id;
+                }
+            }
+            // Check if new multi-step shortcut's first step conflicts with existing single-step shortcut
+            if (newShortcut.steps && existing.keys) {
+                const firstStep = newShortcut.steps[FIRST_INDEX];
+                if (firstStep && this.keysMatch(firstStep, existing.keys)) {
+                    return existing.id;
+                }
+            }
+            if (newShortcut.macSteps && existing.macKeys) {
+                const firstStep = newShortcut.macSteps[FIRST_INDEX];
+                if (firstStep && this.keysMatch(firstStep, existing.macKeys)) {
+                    return existing.id;
+                }
+            }
         }
         return null;
     }
@@ -304,7 +526,7 @@ class KeyboardShortcuts {
         const shortcut = this.shortcuts.get(shortcutId);
         if (!shortcut)
             return [];
-        const conflicts = [];
+        const conflictsSet = new Set();
         for (const existing of this.shortcuts.values()) {
             // Skip self and inactive shortcuts
             if (existing.id === shortcutId || !this.activeShortcuts.has(existing.id)) {
@@ -315,10 +537,41 @@ class KeyboardShortcuts {
                 (shortcut.macKeys && existing.macKeys && this.keysMatch(shortcut.macKeys, existing.macKeys)) ||
                 (shortcut.steps && existing.steps && this.stepsMatch(shortcut.steps, existing.steps)) ||
                 (shortcut.macSteps && existing.macSteps && this.stepsMatch(shortcut.macSteps, existing.macSteps))) {
-                conflicts.push(existing.id);
+                conflictsSet.add(existing.id);
+                continue; // Skip further checks for this shortcut to avoid duplicate adds
+            }
+            // Check if shortcut's single-step conflicts with first step of existing multi-step shortcut
+            if (shortcut.keys && existing.steps) {
+                const firstStep = existing.steps[FIRST_INDEX];
+                if (firstStep && this.keysMatch(shortcut.keys, firstStep)) {
+                    conflictsSet.add(existing.id);
+                    continue;
+                }
+            }
+            if (shortcut.macKeys && existing.macSteps) {
+                const firstStep = existing.macSteps[FIRST_INDEX];
+                if (firstStep && this.keysMatch(shortcut.macKeys, firstStep)) {
+                    conflictsSet.add(existing.id);
+                    continue;
+                }
+            }
+            // Check if shortcut's multi-step first step conflicts with existing single-step shortcut
+            if (shortcut.steps && existing.keys) {
+                const firstStep = shortcut.steps[FIRST_INDEX];
+                if (firstStep && this.keysMatch(firstStep, existing.keys)) {
+                    conflictsSet.add(existing.id);
+                    continue;
+                }
+            }
+            if (shortcut.macSteps && existing.macKeys) {
+                const firstStep = shortcut.macSteps[FIRST_INDEX];
+                if (firstStep && this.keysMatch(firstStep, existing.macKeys)) {
+                    conflictsSet.add(existing.id);
+                    continue;
+                }
             }
         }
-        return conflicts;
+        return Array.from(conflictsSet);
     }
     /**
      * Register a single keyboard shortcut
@@ -365,10 +618,10 @@ class KeyboardShortcuts {
                 keyConflicts.push(`"${shortcut.id}" conflicts with active shortcut "${conflictId}"`);
             }
         });
-        if (duplicateIds.length > 0) {
+        if (duplicateIds.length > MIN_KEY_LENGTH) {
             throw KeyboardShortcutsErrorFactory.shortcutIdsAlreadyRegistered(duplicateIds);
         }
-        if (keyConflicts.length > 0) {
+        if (keyConflicts.length > MIN_KEY_LENGTH) {
             throw KeyboardShortcutsErrorFactory.keyConflictsInGroup(keyConflicts);
         }
         // Validate that all shortcuts have unique IDs within the group
@@ -382,7 +635,7 @@ class KeyboardShortcuts {
                 groupIds.add(shortcut.id);
             }
         });
-        if (duplicatesInGroup.length > 0) {
+        if (duplicatesInGroup.length > MIN_KEY_LENGTH) {
             throw KeyboardShortcutsErrorFactory.duplicateShortcutsInGroup(duplicatesInGroup);
         }
         // Use batch update to reduce signal updates
@@ -446,7 +699,7 @@ class KeyboardShortcuts {
         }
         // Check for conflicts that would be created by activation
         const conflicts = this.findActivationConflicts(shortcutId);
-        if (conflicts.length > 0) {
+        if (conflicts.length > MIN_KEY_LENGTH) {
             throw KeyboardShortcutsErrorFactory.activationKeyConflict(shortcutId, conflicts);
         }
         this.activeShortcuts.add(shortcutId);
@@ -478,7 +731,7 @@ class KeyboardShortcuts {
             const conflicts = this.findActivationConflicts(shortcut.id);
             allConflicts.push(...conflicts);
         });
-        if (allConflicts.length > 0) {
+        if (allConflicts.length > MIN_KEY_LENGTH) {
             throw KeyboardShortcutsErrorFactory.groupActivationKeyConflict(groupId, allConflicts);
         }
         this.batchUpdate(() => {
@@ -608,6 +861,147 @@ class KeyboardShortcuts {
     hasFilter(name) {
         return this.globalFilters.has(name);
     }
+    /**
+     * Remove the filter from a specific group
+     * @param groupId - The group ID
+     * @throws KeyboardShortcutError if group doesn't exist
+     */
+    removeGroupFilter(groupId) {
+        const group = this.groups.get(groupId);
+        if (!group) {
+            throw KeyboardShortcutsErrorFactory.cannotDeactivateGroup(groupId);
+        }
+        if (!group.filter) {
+            // No filter to remove, silently succeed
+            return;
+        }
+        this.groups.set(groupId, {
+            ...group,
+            filter: undefined
+        });
+        this.updateState();
+    }
+    /**
+     * Remove the filter from a specific shortcut
+     * @param shortcutId - The shortcut ID
+     * @throws KeyboardShortcutError if shortcut doesn't exist
+     */
+    removeShortcutFilter(shortcutId) {
+        const shortcut = this.shortcuts.get(shortcutId);
+        if (!shortcut) {
+            throw KeyboardShortcutsErrorFactory.cannotDeactivateShortcut(shortcutId);
+        }
+        if (!shortcut.filter) {
+            // No filter to remove, silently succeed
+            return;
+        }
+        this.shortcuts.set(shortcutId, {
+            ...shortcut,
+            filter: undefined
+        });
+        this.updateState();
+    }
+    /**
+     * Remove all filters from all groups
+     */
+    clearAllGroupFilters() {
+        this.batchUpdate(() => {
+            this.groups.forEach((group, id) => {
+                if (group.filter) {
+                    this.removeGroupFilter(id);
+                }
+            });
+        });
+    }
+    /**
+     * Remove all filters from all shortcuts
+     */
+    clearAllShortcutFilters() {
+        this.batchUpdate(() => {
+            this.shortcuts.forEach((shortcut, id) => {
+                if (shortcut.filter) {
+                    this.removeShortcutFilter(id);
+                }
+            });
+        });
+    }
+    /**
+     * Check if a group has a filter
+     * @param groupId - The group ID
+     * @returns True if the group has a filter
+     */
+    hasGroupFilter(groupId) {
+        const group = this.groups.get(groupId);
+        return !!group?.filter;
+    }
+    /**
+     * Check if a shortcut has a filter
+     * @param shortcutId - The shortcut ID
+     * @returns True if the shortcut has a filter
+     */
+    hasShortcutFilter(shortcutId) {
+        const shortcut = this.shortcuts.get(shortcutId);
+        return !!shortcut?.filter;
+    }
+    /**
+     * Register multiple shortcuts in a single batch update
+     * @param shortcuts - Array of shortcuts to register
+     */
+    registerMany(shortcuts) {
+        this.batchUpdate(() => {
+            shortcuts.forEach(shortcut => this.register(shortcut));
+        });
+    }
+    /**
+     * Unregister multiple shortcuts in a single batch update
+     * @param ids - Array of shortcut IDs to unregister
+     */
+    unregisterMany(ids) {
+        this.batchUpdate(() => {
+            ids.forEach(id => this.unregister(id));
+        });
+    }
+    /**
+     * Unregister multiple groups in a single batch update
+     * @param ids - Array of group IDs to unregister
+     */
+    unregisterGroups(ids) {
+        this.batchUpdate(() => {
+            ids.forEach(id => this.unregisterGroup(id));
+        });
+    }
+    /**
+     * Clear all shortcuts and groups (nuclear reset)
+     */
+    clearAll() {
+        this.batchUpdate(() => {
+            this.shortcuts.clear();
+            this.groups.clear();
+            this.activeShortcuts.clear();
+            this.activeGroups.clear();
+            this.shortcutToGroup.clear();
+            this.globalFilters.clear();
+            this.clearCurrentlyDownKeys();
+            this.clearPendingSequence();
+        });
+    }
+    /**
+     * Get all shortcuts belonging to a specific group
+     * @param groupId - The group ID
+     * @returns Array of shortcuts in the group
+     */
+    getGroupShortcuts(groupId) {
+        const group = this.groups.get(groupId);
+        if (!group)
+            return [];
+        return [...group.shortcuts];
+    }
+    /**
+     * Normalize a key to lowercase for consistent comparison
+     */
+    normalizeKey(key) {
+        return key.toLowerCase();
+    }
     /**
      * Find the group that contains a specific shortcut.
      *
@@ -677,7 +1071,7 @@ class KeyboardShortcuts {
         // Fast path: if any global filter blocks this event, bail out before
         // scanning all active shortcuts. This drastically reduces per-event work
         // when filters are commonly blocking (e.g., while typing in inputs).
-        if (this.globalFilters.size > 0) {
+        if (this.globalFilters.size > MIN_KEY_LENGTH) {
             for (const f of this.globalFilters.values()) {
                 if (!f(event)) {
                     // Also clear any pending multi-step sequence – entering a globally
@@ -716,7 +1110,7 @@ class KeyboardShortcuts {
                 if (expected && this.keysMatch(stepPressed, expected)) {
                     // Advance sequence
                     clearTimeout(pending.timerId);
-                    pending.stepIndex += 1;
+                    pending.stepIndex += STATE_VERSION_INCREMENT;
                     if (pending.stepIndex >= normalizedSteps.length) {
                         // Completed - check filters before executing
                         if (!this.shouldProcessEvent(event, shortcut)) {
@@ -734,8 +1128,10 @@ class KeyboardShortcuts {
                         this.pendingSequence = null;
                         return;
                     }
-                    // Reset timer for next step
-                    pending.timerId = setTimeout(() => { this.pendingSequence = null; }, this.sequenceTimeout);
+                    // Reset timer for next step (only if shortcut has timeout configured)
+                    if (shortcut.sequenceTimeout !== undefined) {
+                        pending.timerId = setTimeout(() => { this.pendingSequence = null; }, shortcut.sequenceTimeout);
+                    }
                     return;
                 }
                 else {
@@ -762,14 +1158,14 @@ class KeyboardShortcuts {
                 ? (shortcut.macSteps ?? shortcut.macKeys ?? shortcut.steps ?? shortcut.keys ?? [])
                 : (shortcut.steps ?? shortcut.keys ?? shortcut.macSteps ?? shortcut.macKeys ?? []);
             const normalizedSteps = this.normalizeToSteps(steps);
-            const firstStep = normalizedSteps[0];
+            const firstStep = normalizedSteps[FIRST_INDEX];
             // Decide which pressed-keys representation to use for this shortcut's
             // expected step: if it requires multiple non-modifier keys, treat it as
             // a chord and use accumulated keys; otherwise use per-event keys to avoid
             // interference from previously pressed non-modifier keys.
-            const nonModifierCount = firstStep.filter(k => !KeyboardShortcuts.MODIFIER_KEYS.has(k.toLowerCase())).length;
+            const nonModifierCount = firstStep.filter(k => !KeyMatcher.isModifierKey(k)).length;
             // Normalize pressed keys to a Set<string> for consistent typing
-            const pressedForStep = nonModifierCount > 1
+            const pressedForStep = nonModifierCount > MIN_COUNT_ONE
                 ? this.buildPressedKeysForMatch(event)
                 : this.getPressedKeys(event);
             if (this.keysMatch(pressedForStep, firstStep)) {
@@ -777,7 +1173,7 @@ class KeyboardShortcuts {
                 if (!this.shouldProcessEvent(event, shortcut)) {
                     continue; // Skip this shortcut due to filters
                 }
-                if (normalizedSteps.length === 1) {
+                if (normalizedSteps.length === SINGLE_STEP_LENGTH) {
                     // single-step
                     event.preventDefault();
                     event.stopPropagation();
@@ -794,10 +1190,13 @@ class KeyboardShortcuts {
                     if (this.pendingSequence) {
                         this.clearPendingSequence();
                     }
+                    const timerId = shortcut.sequenceTimeout !== undefined
+                        ? setTimeout(() => { this.pendingSequence = null; }, shortcut.sequenceTimeout)
+                        : null;
                     this.pendingSequence = {
                         shortcutId: shortcut.id,
-                        stepIndex: 1,
-                        timerId: setTimeout(() => { this.pendingSequence = null; }, this.sequenceTimeout)
+                        stepIndex: SECOND_STEP_INDEX,
+                        timerId
                     };
                     event.preventDefault();
                     event.stopPropagation();
@@ -807,9 +1206,9 @@ class KeyboardShortcuts {
         }
     }
     handleKeyup(event) {
-        // Remove the key from currentlyDownKeys on keyup
+        // Remove the key from currently DownKeys on keyup
         const key = event.key ? event.key.toLowerCase() : '';
-        if (key && !KeyboardShortcuts.MODIFIER_KEYS.has(key)) {
+        if (key && !KeyMatcher.isModifierKey(key)) {
             this.currentlyDownKeys.delete(key);
         }
     }
@@ -834,6 +1233,11 @@ class KeyboardShortcuts {
             this.clearCurrentlyDownKeys();
             this.clearPendingSequence();
         }
+        else if (this.document.visibilityState === 'visible') {
+            // When returning to visibility, clear keys to avoid stale state
+            // from keys that may have been released while document was hidden
+            this.clearCurrentlyDownKeys();
+        }
     }
     /**
      * Update the currentlyDownKeys set when keydown events happen.
@@ -843,7 +1247,7 @@ class KeyboardShortcuts {
     updateCurrentlyDownKeysOnKeydown(event) {
         const key = event.key ? event.key.toLowerCase() : '';
         // Ignore modifier-only keydown entries
-        if (KeyboardShortcuts.MODIFIER_KEYS.has(key)) {
+        if (KeyMatcher.isModifierKey(key)) {
             return;
         }
         // Normalize some special cases similar to the demo component's recording logic
@@ -863,7 +1267,7 @@ class KeyboardShortcuts {
             this.currentlyDownKeys.add('enter');
             return;
         }
-        if (key && key.length > 0) {
+        if (key && key.length > MIN_KEY_LENGTH) {
             this.currentlyDownKeys.add(key);
         }
     }
@@ -886,17 +1290,17 @@ class KeyboardShortcuts {
         if (event.metaKey)
             modifiers.add('meta');
         // Collect non-modifier keys from currentlyDownKeys (excluding modifiers)
-        const nonModifierKeys = Array.from(this.currentlyDownKeys).filter(k => !KeyboardShortcuts.MODIFIER_KEYS.has(k));
+        const nonModifierKeys = Array.from(this.currentlyDownKeys).filter(k => !KeyMatcher.isModifierKey(k));
         const result = new Set();
         // Add modifiers first
         modifiers.forEach(m => result.add(m));
-        if (nonModifierKeys.length > 0) {
+        if (nonModifierKeys.length > MIN_KEY_LENGTH) {
             nonModifierKeys.forEach(k => result.add(k.toLowerCase()));
             return result;
         }
         // Fallback: single main key from the event (existing behavior)
         const key = event.key.toLowerCase();
-        if (!KeyboardShortcuts.MODIFIER_KEYS.has(key)) {
+        if (!KeyMatcher.isModifierKey(key)) {
             result.add(key);
         }
         return result;
@@ -917,7 +1321,7 @@ class KeyboardShortcuts {
             result.add('meta');
         // Add the main key (normalize to lowercase) if it's not a modifier
         const key = (event.key ?? '').toLowerCase();
-        if (key && !KeyboardShortcuts.MODIFIER_KEYS.has(key)) {
+        if (key && !KeyMatcher.isModifierKey(key)) {
             result.add(key);
         }
         return result;
@@ -927,40 +1331,28 @@ class KeyboardShortcuts {
      * Accepts either a Set<string> (preferred) or an array for backwards compatibility.
      * Uses Set-based comparison: sizes must match and every element in target must exist in pressed.
      */
+    /**
+     * @deprecated Use KeyMatcher.keysMatch() instead
+     */
     keysMatch(pressedKeys, targetKeys) {
-        // Normalize targetKeys into a Set<string> (lowercased)
-        const normalizedTarget = new Set(targetKeys.map(k => k.toLowerCase()));
-        // Normalize pressedKeys into a Set<string> if it's an array
-        const pressedSet = Array.isArray(pressedKeys)
-            ? new Set(pressedKeys.map(k => k.toLowerCase()))
-            : new Set(Array.from(pressedKeys).map(k => k.toLowerCase()));
-        if (pressedSet.size !== normalizedTarget.size) {
-            return false;
-        }
-        // Check if every element in normalizedTarget exists in pressedSet
-        for (const key of normalizedTarget) {
-            if (!pressedSet.has(key)) {
-                return false;
-            }
-        }
-        return true;
+        return KeyMatcher.keysMatch(pressedKeys, targetKeys);
     }
-    /** Compare two multi-step sequences for equality */
+    /**
+     * Compare two multi-step sequences for equality
+     * @deprecated Use KeyMatcher.stepsMatch() instead
+     */
     stepsMatch(a, b) {
-        if (a.length !== b.length)
-            return false;
-        for (let i = 0; i < a.length; i++) {
-            if (!this.keysMatch(a[i], b[i]))
-                return false;
-        }
-        return true;
+        return KeyMatcher.stepsMatch(a, b);
     }
     /** Safely clear any pending multi-step sequence */
     clearPendingSequence() {
         if (!this.pendingSequence)
             return;
         try {
-            clearTimeout(this.pendingSequence.timerId);
+            // Only clear timeout if one was set
+            if (this.pendingSequence.timerId !== null) {
+                clearTimeout(this.pendingSequence.timerId);
+            }
         }
         catch { /* ignore */ }
         this.pendingSequence = null;
@@ -993,7 +1385,7 @@ class KeyboardShortcuts {
      */
     precomputeBlockedGroups(event) {
         const blocked = new Set();
-        if (this.activeGroups.size === 0)
+        if (this.activeGroups.size === MIN_KEY_LENGTH)
             return blocked;
         for (const groupId of this.activeGroups) {
             const group = this.groups.get(groupId);
@@ -1013,6 +1405,235 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImpor
                 }]
         }], ctorParameters: () => [] });
 
+/**
+ * Directive for registering keyboard shortcuts directly on elements in templates.
+ *
+ * This directive automatically:
+ * - Registers the shortcut when the directive initializes
+ * - Triggers the host element's click event (default) or executes a custom action
+ * - Unregisters the shortcut when the component is destroyed
+ *
+ * @example
+ * Basic usage with click trigger:
+ * ```html
+ * <button ngxKeys
+ *         keys="ctrl,s"
+ *         description="Save document"
+ *         (click)="save()">
+ *   Save
+ * </button>
+ * ```
+ *
+ * @example
+ * With custom action:
+ * ```html
+ * <button ngxKeys
+ *         keys="ctrl,s"
+ *         description="Save document"
+ *         [action]="customSaveAction">
+ *   Save
+ * </button>
+ * ```
+ *
+ * @example
+ * Multi-step shortcuts:
+ * ```html
+ * <button ngxKeys
+ *         [steps]="[['ctrl', 'k'], ['ctrl', 's']]"
+ *         description="Format document"
+ *         (click)="format()">
+ *   Format
+ * </button>
+ * ```
+ *
+ * @example
+ * Mac-specific keys:
+ * ```html
+ * <button ngxKeys
+ *         keys="ctrl,s"
+ *         macKeys="cmd,s"
+ *         description="Save document"
+ *         (click)="save()">
+ *   Save
+ * </button>
+ * ```
+ *
+ * @example
+ * On non-interactive elements:
+ * ```html
+ * <div ngxKeys
+ *      keys="?"
+ *      description="Show help"
+ *      [action]="showHelp">
+ *   Help content
+ * </div>
+ * ```
+ */
+class KeyboardShortcutDirective {
+    keyboardShortcuts = inject(KeyboardShortcuts);
+    elementRef = inject((ElementRef));
+    /**
+     * Comma-separated string of keys for the shortcut (e.g., "ctrl,s" or "alt,shift,k")
+     * Use either `keys` for single-step shortcuts or `steps` for multi-step shortcuts.
+     */
+    keys;
+    /**
+     * Comma-separated string of keys for Mac users (e.g., "cmd,s")
+     * If not provided, `keys` will be used for all platforms.
+     */
+    macKeys;
+    /**
+     * Multi-step shortcut as an array of key arrays.
+     * Each inner array represents one step in the sequence.
+     * Example: [['ctrl', 'k'], ['ctrl', 's']] for Ctrl+K followed by Ctrl+S
+     */
+    steps;
+    /**
+     * Multi-step shortcut for Mac users.
+     * Example: [['cmd', 'k'], ['cmd', 's']]
+     */
+    macSteps;
+    /**
+     * Description of what the shortcut does (displayed in help/documentation)
+     */
+    description;
+    /**
+     * Optional custom action to execute when the shortcut is triggered.
+     * If not provided, the directive will trigger a click event on the host element.
+     */
+    action;
+    /**
+     * Optional custom ID for the shortcut. If not provided, a unique ID will be generated.
+     * Useful for programmatically referencing the shortcut or for debugging.
+     */
+    shortcutId;
+    /**
+     * Event emitted when the keyboard shortcut is triggered.
+     * This fires in addition to the action or click trigger.
+     */
+    triggered = output();
+    /**
+     * Adds a data attribute to the host element for styling or testing purposes
+     */
+    get dataAttribute() {
+        return this.generatedId;
+    }
+    generatedId = '';
+    isRegistered = false;
+    ngOnInit() {
+        // Generate unique ID if not provided
+        this.generatedId = this.shortcutId || this.generateUniqueId();
+        // Validate inputs
+        this.validateInputs();
+        // Parse keys from comma-separated strings
+        const parsedKeys = this.keys ? this.parseKeys(this.keys) : undefined;
+        const parsedMacKeys = this.macKeys ? this.parseKeys(this.macKeys) : undefined;
+        // Define the action: custom action or default click behavior
+        const shortcutAction = () => {
+            if (this.action) {
+                this.action();
+            }
+            else {
+                // Trigger click on the host element
+                this.elementRef.nativeElement.click();
+            }
+            // Emit the triggered event
+            this.triggered.emit();
+        };
+        // Register the shortcut
+        try {
+            this.keyboardShortcuts.register({
+                id: this.generatedId,
+                keys: parsedKeys,
+                macKeys: parsedMacKeys,
+                steps: this.steps,
+                macSteps: this.macSteps,
+                action: shortcutAction,
+                description: this.description,
+            });
+            this.isRegistered = true;
+        }
+        catch (error) {
+            console.error(`[ngxKeys] Failed to register shortcut:`, error);
+            throw error;
+        }
+    }
+    ngOnDestroy() {
+        // Automatically unregister the shortcut when the directive is destroyed
+        if (this.isRegistered) {
+            try {
+                this.keyboardShortcuts.unregister(this.generatedId);
+            }
+            catch (error) {
+                // Silently handle unregister errors (shortcut might have been manually removed)
+                console.warn(`[ngxKeys] Failed to unregister shortcut ${this.generatedId}:`, error);
+            }
+        }
+    }
+    /**
+     * Parse comma-separated key string into an array
+     * Example: "ctrl,s" -> ["ctrl", "s"]
+     */
+    parseKeys(keysString) {
+        return keysString
+            .split(',')
+            .map(key => key.trim())
+            .filter(key => key.length > 0);
+    }
+    /**
+     * Generate a unique ID for the shortcut based on the element and keys
+     */
+    generateUniqueId() {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 9);
+        const keysStr = this.keys || this.steps?.flat().join('-') || 'unknown';
+        return `ngx-shortcut-${keysStr}-${timestamp}-${random}`;
+    }
+    /**
+     * Validate that required inputs are provided correctly
+     */
+    validateInputs() {
+        const hasSingleStep = this.keys || this.macKeys;
+        const hasMultiStep = this.steps || this.macSteps;
+        if (!hasSingleStep && !hasMultiStep) {
+            throw new Error(`[ngxKeys] Must provide either 'keys'/'macKeys' for single-step shortcuts or 'steps'/'macSteps' for multi-step shortcuts.`);
+        }
+        if (hasSingleStep && hasMultiStep) {
+            throw new Error(`[ngxKeys] Cannot use both single-step ('keys'/'macKeys') and multi-step ('steps'/'macSteps') inputs simultaneously. Choose one approach.`);
+        }
+        if (!this.description) {
+            throw new Error(`[ngxKeys] 'description' input is required.`);
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: KeyboardShortcutDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.2.4", type: KeyboardShortcutDirective, isStandalone: true, selector: "[ngxKeys]", inputs: { keys: "keys", macKeys: "macKeys", steps: "steps", macSteps: "macSteps", description: "description", action: "action", shortcutId: "shortcutId" }, outputs: { triggered: "triggered" }, host: { properties: { "attr.data-keyboard-shortcut": "this.dataAttribute" } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: KeyboardShortcutDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[ngxKeys]',
+                    standalone: true,
+                }]
+        }], propDecorators: { keys: [{
+                type: Input
+            }], macKeys: [{
+                type: Input
+            }], steps: [{
+                type: Input
+            }], macSteps: [{
+                type: Input
+            }], description: [{
+                type: Input,
+                args: [{ required: true }]
+            }], action: [{
+                type: Input
+            }], shortcutId: [{
+                type: Input
+            }], dataAttribute: [{
+                type: HostBinding,
+                args: ['attr.data-keyboard-shortcut']
+            }] } });
+
 /*
  * Public API Surface of ngx-keys
  */
@@ -1021,5 +1642,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.2.4", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { KeyboardShortcutError, KeyboardShortcuts, KeyboardShortcutsErrorFactory, KeyboardShortcutsErrors };
+export { KEYBOARD_SHORTCUTS_CONFIG, KeyboardShortcutDirective, KeyboardShortcutError, KeyboardShortcuts, KeyboardShortcutsErrorFactory, KeyboardShortcutsErrors, provideKeyboardShortcutsConfig };
 //# sourceMappingURL=ngx-keys.mjs.map