ngx-keys 1.1.0 → 1.3.0

package/fesm2022/ngx-keys.mjs

@@ -1,6 +1,5 @@
 import * as i0 from '@angular/core';
-import { signal, computed, inject, PLATFORM_ID, DestroyRef, Injectable } from '@angular/core';
-import { isPlatformBrowser } from '@angular/common';
+import { InjectionToken, DestroyRef, inject, DOCUMENT, signal, computed, afterNextRender, Injectable, ElementRef, output, HostBinding, Input, Directive } from '@angular/core';
 import { Observable, take } from 'rxjs';
 
 /**
@@ -12,6 +11,9 @@ const KeyboardShortcutsErrors = {
     SHORTCUT_ALREADY_REGISTERED: (id) => `Shortcut "${id}" already registered`,
     GROUP_ALREADY_REGISTERED: (id) => `Group "${id}" already registered`,
     KEY_CONFLICT: (conflictId) => `Key conflict with "${conflictId}"`,
+    ACTIVE_KEY_CONFLICT: (conflictId) => `Key conflict with active shortcut "${conflictId}"`,
+    ACTIVATION_KEY_CONFLICT: (shortcutId, conflictIds) => `Cannot activate "${shortcutId}": would conflict with active shortcuts: ${conflictIds.join(', ')}`,
+    GROUP_ACTIVATION_KEY_CONFLICT: (groupId, conflictIds) => `Cannot activate group "${groupId}": would conflict with active shortcuts: ${conflictIds.join(', ')}`,
     SHORTCUT_IDS_ALREADY_REGISTERED: (ids) => `Shortcut IDs already registered: ${ids.join(', ')}`,
     DUPLICATE_SHORTCUTS_IN_GROUP: (ids) => `Duplicate shortcuts in group: ${ids.join(', ')}`,
     KEY_CONFLICTS_IN_GROUP: (conflicts) => `Key conflicts: ${conflicts.join(', ')}`,
@@ -53,6 +55,15 @@ class KeyboardShortcutsErrorFactory {
     static keyConflict(conflictId) {
         return new KeyboardShortcutError('KEY_CONFLICT', KeyboardShortcutsErrors.KEY_CONFLICT(conflictId), { conflictId });
     }
+    static activeKeyConflict(conflictId) {
+        return new KeyboardShortcutError('ACTIVE_KEY_CONFLICT', KeyboardShortcutsErrors.ACTIVE_KEY_CONFLICT(conflictId), { conflictId });
+    }
+    static activationKeyConflict(shortcutId, conflictIds) {
+        return new KeyboardShortcutError('ACTIVATION_KEY_CONFLICT', KeyboardShortcutsErrors.ACTIVATION_KEY_CONFLICT(shortcutId, conflictIds), { shortcutId, conflictIds });
+    }
+    static groupActivationKeyConflict(groupId, conflictIds) {
+        return new KeyboardShortcutError('GROUP_ACTIVATION_KEY_CONFLICT', KeyboardShortcutsErrors.GROUP_ACTIVATION_KEY_CONFLICT(groupId, conflictIds), { groupId, conflictIds });
+    }
     static shortcutIdsAlreadyRegistered(ids) {
         return new KeyboardShortcutError('SHORTCUT_IDS_ALREADY_REGISTERED', KeyboardShortcutsErrors.SHORTCUT_IDS_ALREADY_REGISTERED(ids), { duplicateIds: ids });
     }
@@ -88,19 +99,256 @@ 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.
+ */
+function isGroupOptions(param) {
+    if (!param || typeof param !== 'object')
+        return false;
+    // Narrow to object for property checks
+    const obj = param;
+    return ('filter' in obj) || ('activeUntil' in obj);
+}
+/**
+ * Detect real DestroyRef instances or duck-typed objects exposing onDestroy(fn).
+ * Returns true for either an actual DestroyRef or an object with an onDestroy method.
+ */
+function isDestroyRefLike(obj) {
+    if (!obj || typeof obj !== 'object')
+        return false;
+    try {
+        // Prefer instanceof when available (real DestroyRef)
+        if (obj instanceof DestroyRef)
+            return true;
+    }
+    catch {
+        // instanceof may throw if DestroyRef is not constructable in certain runtimes/tests
+    }
+    const o = obj;
+    return typeof o['onDestroy'] === 'function';
+}
 class KeyboardShortcuts {
+    document = inject(DOCUMENT);
+    window = this.document.defaultView;
+    config = inject(KEYBOARD_SHORTCUTS_CONFIG);
     shortcuts = new Map();
     groups = new Map();
     activeShortcuts = new Set();
     activeGroups = new Set();
     currentlyDownKeys = new Set();
+    // O(1) lookup from shortcutId to its groupId to avoid scanning all groups per event
+    shortcutToGroup = new Map();
+    /**
+     * Named global filters that apply to all shortcuts.
+     * All global filters must return `true` for a shortcut to be processed.
+     */
+    globalFilters = new Map();
     // Single consolidated state signal - reduces memory overhead
     state = signal({
         shortcuts: new Map(),
         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(() => {
@@ -135,24 +383,12 @@ class KeyboardShortcuts {
     blurListener = this.handleWindowBlur.bind(this);
     visibilityListener = this.handleVisibilityChange.bind(this);
     isListening = false;
-    isBrowser;
-    /** Default timeout (ms) for completing a multi-step sequence */
-    sequenceTimeout = 2000;
     /** Runtime state for multi-step sequences */
     pendingSequence = null;
     constructor() {
-        // Use try-catch to handle injection context for better testability
-        try {
-            const platformId = inject(PLATFORM_ID);
-            this.isBrowser = isPlatformBrowser(platformId);
-        }
-        catch {
-            // Fallback for testing - assume browser environment
-            this.isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
-        }
-        if (this.isBrowser) {
+        afterNextRender(() => {
             this.startListening();
-        }
+        });
     }
     ngOnDestroy() {
         this.stopListening();
@@ -166,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
         }));
     }
     /**
@@ -213,28 +449,32 @@ 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
         return [input];
     }
     /**
-     * Check if a key combination is already registered
-     * @returns The ID of the conflicting shortcut, or null if no conflict
+     * Check if a key combination is already registered by an active shortcut
+     * @returns The ID of the conflicting active shortcut, or null if no active conflict
      */
-    findConflict(newShortcut) {
+    findActiveConflict(newShortcut) {
         for (const existing of this.shortcuts.values()) {
+            // Only check conflicts with active shortcuts
+            if (!this.activeShortcuts.has(existing.id)) {
+                continue;
+            }
             // Compare single-step shapes if provided
             if (newShortcut.keys && existing.keys && this.keysMatch(newShortcut.keys, existing.keys)) {
                 return existing.id;
@@ -252,48 +492,79 @@ class KeyboardShortcuts {
         }
         return null;
     }
+    /**
+     * Check if activating a shortcut would create key conflicts with other active shortcuts
+     * @returns Array of conflicting shortcut IDs that would be created by activation
+     */
+    findActivationConflicts(shortcutId) {
+        const shortcut = this.shortcuts.get(shortcutId);
+        if (!shortcut)
+            return [];
+        const conflicts = [];
+        for (const existing of this.shortcuts.values()) {
+            // Skip self and inactive shortcuts
+            if (existing.id === shortcutId || !this.activeShortcuts.has(existing.id)) {
+                continue;
+            }
+            // Check for key conflicts
+            if ((shortcut.keys && existing.keys && this.keysMatch(shortcut.keys, existing.keys)) ||
+                (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);
+            }
+        }
+        return conflicts;
+    }
     /**
      * Register a single keyboard shortcut
-     * @throws KeyboardShortcutError if shortcut ID is already registered or key combination is in use
+     * @throws KeyboardShortcutError if shortcut ID is already registered or if the shortcut would conflict with currently active shortcuts
      */
     register(shortcut) {
         if (this.shortcuts.has(shortcut.id)) {
             throw KeyboardShortcutsErrorFactory.shortcutAlreadyRegistered(shortcut.id);
         }
-        const conflictId = this.findConflict(shortcut);
+        // Check for conflicts only with currently active shortcuts
+        const conflictId = this.findActiveConflict(shortcut);
         if (conflictId) {
-            throw KeyboardShortcutsErrorFactory.keyConflict(conflictId);
+            throw KeyboardShortcutsErrorFactory.activeKeyConflict(conflictId);
         }
         this.shortcuts.set(shortcut.id, shortcut);
         this.activeShortcuts.add(shortcut.id);
         this.updateState();
         this.setupActiveUntil(shortcut.activeUntil, this.unregister.bind(this, shortcut.id));
     }
-    /**
-     * Register multiple keyboard shortcuts as a group
-     * @throws KeyboardShortcutError if group ID is already registered or if any shortcut ID or key combination conflicts
-     */
-    registerGroup(groupId, shortcuts, activeUntil) {
+    registerGroup(groupId, shortcuts, optionsOrActiveUntil) {
+        // Parse parameters - support both old (activeUntil) and new (options) formats
+        let options;
+        if (isGroupOptions(optionsOrActiveUntil)) {
+            // New format with options object
+            options = optionsOrActiveUntil;
+        }
+        else {
+            // Old format with just activeUntil parameter
+            options = { activeUntil: optionsOrActiveUntil };
+        }
         // Check if group ID already exists
         if (this.groups.has(groupId)) {
             throw KeyboardShortcutsErrorFactory.groupAlreadyRegistered(groupId);
         }
-        // Check for duplicate shortcut IDs and key combination conflicts
+        // Check for duplicate shortcut IDs and key combination conflicts with active shortcuts
         const duplicateIds = [];
         const keyConflicts = [];
         shortcuts.forEach(shortcut => {
             if (this.shortcuts.has(shortcut.id)) {
                 duplicateIds.push(shortcut.id);
             }
-            const conflictId = this.findConflict(shortcut);
+            const conflictId = this.findActiveConflict(shortcut);
             if (conflictId) {
-                keyConflicts.push(`"${shortcut.id}" conflicts with "${conflictId}"`);
+                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
@@ -307,7 +578,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
@@ -315,7 +586,8 @@ class KeyboardShortcuts {
             const group = {
                 id: groupId,
                 shortcuts,
-                active: true
+                active: true,
+                filter: options.filter
             };
             this.groups.set(groupId, group);
             this.activeGroups.add(groupId);
@@ -323,9 +595,10 @@ class KeyboardShortcuts {
             shortcuts.forEach(shortcut => {
                 this.shortcuts.set(shortcut.id, shortcut);
                 this.activeShortcuts.add(shortcut.id);
+                this.shortcutToGroup.set(shortcut.id, groupId);
             });
         });
-        this.setupActiveUntil(activeUntil, this.unregisterGroup.bind(this, groupId));
+        this.setupActiveUntil(options.activeUntil, this.unregisterGroup.bind(this, groupId));
     }
     /**
      * Unregister a single keyboard shortcut
@@ -337,6 +610,7 @@ class KeyboardShortcuts {
         }
         this.shortcuts.delete(shortcutId);
         this.activeShortcuts.delete(shortcutId);
+        this.shortcutToGroup.delete(shortcutId);
         this.updateState();
     }
     /**
@@ -352,6 +626,7 @@ class KeyboardShortcuts {
             group.shortcuts.forEach(shortcut => {
                 this.shortcuts.delete(shortcut.id);
                 this.activeShortcuts.delete(shortcut.id);
+                this.shortcutToGroup.delete(shortcut.id);
             });
             this.groups.delete(groupId);
             this.activeGroups.delete(groupId);
@@ -359,12 +634,17 @@ class KeyboardShortcuts {
     }
     /**
      * Activate a single keyboard shortcut
-     * @throws KeyboardShortcutError if shortcut ID doesn't exist
+     * @throws KeyboardShortcutError if shortcut ID doesn't exist or if activation would create key conflicts
      */
     activate(shortcutId) {
         if (!this.shortcuts.has(shortcutId)) {
             throw KeyboardShortcutsErrorFactory.cannotActivateShortcut(shortcutId);
         }
+        // Check for conflicts that would be created by activation
+        const conflicts = this.findActivationConflicts(shortcutId);
+        if (conflicts.length > MIN_KEY_LENGTH) {
+            throw KeyboardShortcutsErrorFactory.activationKeyConflict(shortcutId, conflicts);
+        }
         this.activeShortcuts.add(shortcutId);
         this.updateState();
     }
@@ -381,13 +661,22 @@ class KeyboardShortcuts {
     }
     /**
      * Activate a group of keyboard shortcuts
-     * @throws KeyboardShortcutError if group ID doesn't exist
+     * @throws KeyboardShortcutError if group ID doesn't exist or if activation would create key conflicts
      */
     activateGroup(groupId) {
         const group = this.groups.get(groupId);
         if (!group) {
             throw KeyboardShortcutsErrorFactory.cannotActivateGroup(groupId);
         }
+        // Check for conflicts that would be created by activating all shortcuts in the group
+        const allConflicts = [];
+        group.shortcuts.forEach(shortcut => {
+            const conflicts = this.findActivationConflicts(shortcut.id);
+            allConflicts.push(...conflicts);
+        });
+        if (allConflicts.length > MIN_KEY_LENGTH) {
+            throw KeyboardShortcutsErrorFactory.groupActivationKeyConflict(groupId, allConflicts);
+        }
         this.batchUpdate(() => {
             group.active = true;
             this.activeGroups.add(groupId);
@@ -449,45 +738,306 @@ class KeyboardShortcuts {
     getGroups() {
         return this.groups;
     }
+    /**
+     * Add a named global filter that applies to all shortcuts.
+     * All global filters must return `true` for a shortcut to execute.
+     *
+     * @param name - Unique name for this filter
+     * @param filter - Function that returns `true` to allow shortcuts, `false` to block them
+     *
+     * @example
+     * ```typescript
+     * // Block shortcuts in form elements
+     * keyboardService.addFilter('forms', (event) => {
+     *   const target = event.target as HTMLElement;
+     *   const tagName = target?.tagName?.toLowerCase();
+     *   return !['input', 'textarea', 'select'].includes(tagName) && !target?.isContentEditable;
+     * });
+     *
+     * // Block shortcuts when modal is open
+     * keyboardService.addFilter('modal', (event) => {
+     *   return !document.querySelector('.modal.active');
+     * });
+     * ```
+     */
+    addFilter(name, filter) {
+        this.globalFilters.set(name, filter);
+    }
+    /**
+     * Remove a named global filter.
+     *
+     * @param name - Name of the filter to remove
+     * @returns `true` if filter was removed, `false` if it didn't exist
+     */
+    removeFilter(name) {
+        return this.globalFilters.delete(name);
+    }
+    /**
+     * Get a named global filter.
+     *
+     * @param name - Name of the filter to retrieve
+     * @returns The filter function, or undefined if not found
+     */
+    getFilter(name) {
+        return this.globalFilters.get(name);
+    }
+    /**
+     * Get all global filter names.
+     *
+     * @returns Array of filter names
+     */
+    getFilterNames() {
+        return Array.from(this.globalFilters.keys());
+    }
+    /**
+     * Remove all global filters.
+     */
+    clearFilters() {
+        this.globalFilters.clear();
+    }
+    /**
+     * Check if a named filter exists.
+     *
+     * @param name - Name of the filter to check
+     * @returns `true` if filter exists, `false` otherwise
+     */
+    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.
+     *
+     * @param shortcutId - The ID of the shortcut to find
+     * @returns The group containing the shortcut, or undefined if not found in any group
+     */
+    findGroupForShortcut(shortcutId) {
+        const groupId = this.shortcutToGroup.get(shortcutId);
+        return groupId ? this.groups.get(groupId) : undefined;
+    }
+    /**
+     * Check if a keyboard event should be processed based on global, group, and per-shortcut filters.
+     * Filter hierarchy: Global filters → Group filter → Individual shortcut filter
+     *
+     * @param event - The keyboard event to evaluate
+     * @param shortcut - The shortcut being evaluated (for per-shortcut filter)
+     * @returns `true` if event should be processed, `false` if it should be ignored
+     */
+    shouldProcessEvent(event, shortcut) {
+        // First, check all global filters - ALL must return true
+        // Note: handleKeydown pre-checks these once per event for early exit,
+        // but we keep this for direct calls and completeness.
+        for (const globalFilter of this.globalFilters.values()) {
+            if (!globalFilter(event)) {
+                return false;
+            }
+        }
+        // Then check group filter if shortcut belongs to a group
+        const group = this.findGroupForShortcut(shortcut.id);
+        if (group?.filter && !group.filter(event)) {
+            return false;
+        }
+        // Finally check per-shortcut filter if it exists
+        if (shortcut.filter && !shortcut.filter(event)) {
+            return false;
+        }
+        return true;
+    }
     startListening() {
-        if (!this.isBrowser || this.isListening) {
+        if (this.isListening) {
             return;
         }
         // Listen to both keydown and keyup so we can maintain a Set of currently
         // pressed physical keys. We avoid passive:true because we may call
         // preventDefault() when matching shortcuts.
-        document.addEventListener('keydown', this.keydownListener, { passive: false });
-        document.addEventListener('keyup', this.keyupListener, { passive: false });
+        this.document.addEventListener('keydown', this.keydownListener, { passive: false });
+        this.document.addEventListener('keyup', this.keyupListener, { passive: false });
         // Listen for blur/visibility changes so we can clear the currently-down keys
         // and avoid stale state when the browser or tab loses focus.
-        window.addEventListener('blur', this.blurListener);
-        document.addEventListener('visibilitychange', this.visibilityListener);
+        this.window.addEventListener('blur', this.blurListener);
+        this.document.addEventListener('visibilitychange', this.visibilityListener);
         this.isListening = true;
     }
     stopListening() {
-        if (!this.isBrowser || !this.isListening) {
+        if (!this.isListening) {
             return;
         }
-        document.removeEventListener('keydown', this.keydownListener);
-        document.removeEventListener('keyup', this.keyupListener);
-        window.removeEventListener('blur', this.blurListener);
-        document.removeEventListener('visibilitychange', this.visibilityListener);
+        this.document.removeEventListener('keydown', this.keydownListener);
+        this.document.removeEventListener('keyup', this.keyupListener);
+        this.window.removeEventListener('blur', this.blurListener);
+        this.document.removeEventListener('visibilitychange', this.visibilityListener);
         this.isListening = false;
     }
     handleKeydown(event) {
         // Update the currently down keys with this event's key
         this.updateCurrentlyDownKeysOnKeydown(event);
-        // Build the pressed keys set used for matching. Prefer the currentlyDownKeys
-        // if it contains more than one non-modifier key; otherwise fall back to the
-        // traditional per-event pressed keys calculation for compatibility.
-        // Use a Set for matching to avoid allocations and sorting on every event
-        const pressedKeys = this.buildPressedKeysForMatch(event);
+        // 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 > MIN_KEY_LENGTH) {
+            for (const f of this.globalFilters.values()) {
+                if (!f(event)) {
+                    // Also clear any pending multi-step sequence – entering a globally
+                    // filtered context should not allow sequences to continue.
+                    this.clearPendingSequence();
+                    return;
+                }
+            }
+        }
         const isMac = this.isMacPlatform();
+        // Evaluate active group-level filters once per event and cache blocked groups
+        const blockedGroups = this.precomputeBlockedGroups(event);
         // If there is a pending multi-step sequence, try to advance it first
         if (this.pendingSequence) {
             const pending = this.pendingSequence;
             const shortcut = this.shortcuts.get(pending.shortcutId);
             if (shortcut) {
+                // If the pending shortcut belongs to a blocked group, cancel sequence
+                const g = this.findGroupForShortcut(shortcut.id);
+                if (g && blockedGroups.has(g.id)) {
+                    this.clearPendingSequence();
+                    return;
+                }
                 const steps = isMac
                     ? (shortcut.macSteps ?? shortcut.macKeys ?? shortcut.steps ?? shortcut.keys ?? [])
                     : (shortcut.steps ?? shortcut.keys ?? shortcut.macSteps ?? shortcut.macKeys ?? []);
@@ -498,14 +1048,18 @@ class KeyboardShortcuts {
                 // from previous steps (if tests or callers don't emit keyup), which
                 // would prevent matching a simple single-key step like ['s'] after
                 // a prior ['k'] step. Use getPressedKeys(event) which reflects the
-                // actual modifier/main-key state for this event.
+                // actual modifier/main-key state for this event as a Set<string>.
                 const stepPressed = this.getPressedKeys(event);
                 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
+                        // Completed - check filters before executing
+                        if (!this.shouldProcessEvent(event, shortcut)) {
+                            this.pendingSequence = null;
+                            return; // Skip execution due to filters
+                        }
                         event.preventDefault();
                         event.stopPropagation();
                         try {
@@ -517,8 +1071,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 {
@@ -536,13 +1092,31 @@ class KeyboardShortcuts {
             const shortcut = this.shortcuts.get(shortcutId);
             if (!shortcut)
                 continue;
+            // Skip expensive matching entirely when the shortcut's group is blocked
+            const g = this.findGroupForShortcut(shortcut.id);
+            if (g && blockedGroups.has(g.id)) {
+                continue;
+            }
             const steps = isMac
                 ? (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];
-            if (this.keysMatch(pressedKeys, firstStep)) {
-                if (normalizedSteps.length === 1) {
+            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 => !KeyMatcher.isModifierKey(k)).length;
+            // Normalize pressed keys to a Set<string> for consistent typing
+            const pressedForStep = nonModifierCount > MIN_COUNT_ONE
+                ? this.buildPressedKeysForMatch(event)
+                : this.getPressedKeys(event);
+            if (this.keysMatch(pressedForStep, firstStep)) {
+                // Check if this event should be processed based on filters
+                if (!this.shouldProcessEvent(event, shortcut)) {
+                    continue; // Skip this shortcut due to filters
+                }
+                if (normalizedSteps.length === SINGLE_STEP_LENGTH) {
                     // single-step
                     event.preventDefault();
                     event.stopPropagation();
@@ -559,10 +1133,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();
@@ -572,9 +1149,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 && !['control', 'alt', 'shift', 'meta'].includes(key)) {
+        if (key && !KeyMatcher.isModifierKey(key)) {
             this.currentlyDownKeys.delete(key);
         }
     }
@@ -592,13 +1169,18 @@ class KeyboardShortcuts {
         this.clearPendingSequence();
     }
     handleVisibilityChange() {
-        if (document.visibilityState === 'hidden') {
+        if (this.document.visibilityState === 'hidden') {
             // When the document becomes hidden, clear both pressed keys and any
             // pending multi-step sequence. This prevents sequences from remaining
             // active when the user switches tabs or minimizes the window.
             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.
@@ -608,7 +1190,7 @@ class KeyboardShortcuts {
     updateCurrentlyDownKeysOnKeydown(event) {
         const key = event.key ? event.key.toLowerCase() : '';
         // Ignore modifier-only keydown entries
-        if (['control', 'alt', 'shift', 'meta'].includes(key)) {
+        if (KeyMatcher.isModifierKey(key)) {
             return;
         }
         // Normalize some special cases similar to the demo component's recording logic
@@ -628,15 +1210,10 @@ class KeyboardShortcuts {
             this.currentlyDownKeys.add('enter');
             return;
         }
-        if (key && key.length > 0) {
+        if (key && key.length > MIN_KEY_LENGTH) {
             this.currentlyDownKeys.add(key);
         }
     }
-    /**
-     * Build the pressed keys array used for matching against registered shortcuts.
-     * If multiple non-modifier keys are currently down, include them (chord support).
-     * Otherwise fall back to single main-key detection from the event for compatibility.
-     */
     /**
      * Build the pressed keys set used for matching against registered shortcuts.
      * If multiple non-modifier keys are currently down, include them (chord support).
@@ -656,83 +1233,75 @@ class KeyboardShortcuts {
         if (event.metaKey)
             modifiers.add('meta');
         // Collect non-modifier keys from currentlyDownKeys (excluding modifiers)
-        const nonModifierKeys = Array.from(this.currentlyDownKeys).filter(k => !['control', 'alt', 'shift', 'meta'].includes(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 (!['control', 'alt', 'shift', 'meta'].includes(key)) {
+        if (!KeyMatcher.isModifierKey(key)) {
             result.add(key);
         }
         return result;
     }
+    /**
+     * Return the pressed keys for this event as a Set<string>.
+     * This is the canonical internal API used for matching.
+     */
     getPressedKeys(event) {
-        const keys = [];
+        const result = new Set();
         if (event.ctrlKey)
-            keys.push('ctrl');
+            result.add('ctrl');
         if (event.altKey)
-            keys.push('alt');
+            result.add('alt');
         if (event.shiftKey)
-            keys.push('shift');
+            result.add('shift');
         if (event.metaKey)
-            keys.push('meta');
-        // Add the main key (normalize to lowercase)
-        const key = event.key.toLowerCase();
-        if (!['control', 'alt', 'shift', 'meta'].includes(key)) {
-            keys.push(key);
+            result.add('meta');
+        // Add the main key (normalize to lowercase) if it's not a modifier
+        const key = (event.key ?? '').toLowerCase();
+        if (key && !KeyMatcher.isModifierKey(key)) {
+            result.add(key);
         }
-        return keys;
+        return result;
     }
     /**
      * Compare pressed keys against a target key combination.
      * 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;
     }
     isMacPlatform() {
-        return this.isBrowser && /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+        return /Mac|iPod|iPhone|iPad/.test(this.window.navigator.platform ?? '');
     }
     setupActiveUntil(activeUntil, unregister) {
         if (!activeUntil) {
@@ -742,7 +1311,10 @@ class KeyboardShortcuts {
             inject(DestroyRef).onDestroy(unregister);
             return;
         }
-        if (activeUntil instanceof DestroyRef) {
+        // Support both real DestroyRef instances and duck-typed objects (e.g.,
+        // Jasmine spies) that expose an onDestroy(fn) method for backwards
+        // compatibility with earlier APIs and tests.
+        if (isDestroyRefLike(activeUntil)) {
             activeUntil.onDestroy(unregister);
             return;
         }
@@ -751,6 +1323,21 @@ class KeyboardShortcuts {
             return;
         }
     }
+    /**
+     * Evaluate group filters once per event and return the set of blocked group IDs.
+     */
+    precomputeBlockedGroups(event) {
+        const blocked = new Set();
+        if (this.activeGroups.size === MIN_KEY_LENGTH)
+            return blocked;
+        for (const groupId of this.activeGroups) {
+            const group = this.groups.get(groupId);
+            if (group && group.filter && !group.filter(event)) {
+                blocked.add(groupId);
+            }
+        }
+        return blocked;
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: KeyboardShortcuts, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.2.4", ngImport: i0, type: KeyboardShortcuts, providedIn: 'root' });
 }
@@ -761,6 +1348,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
  */
@@ -769,5 +1585,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