ngx-keys 1.0.1 → 1.2.0

package/fesm2022/ngx-keys.mjs

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
-import { signal, computed, inject, PLATFORM_ID, Injectable } from '@angular/core';
-import { isPlatformBrowser } from '@angular/common';
+import { DestroyRef, inject, DOCUMENT, signal, computed, afterNextRender, Injectable } from '@angular/core';
+import { Observable, take } from 'rxjs';
 
 /**
  * Centralized error messages for keyboard shortcuts service
@@ -11,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(', ')}`,
@@ -52,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 });
     }
@@ -87,11 +99,51 @@ class KeyboardShortcutsErrorFactory {
     }
 }
 
+/**
+ * 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 {
+    static MODIFIER_KEYS = new Set(['control', 'alt', 'shift', 'meta']);
+    document = inject(DOCUMENT);
+    window = this.document.defaultView;
     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(),
@@ -129,21 +181,18 @@ class KeyboardShortcuts {
         };
     }, ...(ngDevMode ? [{ debugName: "shortcutsUI$" }] : []));
     keydownListener = this.handleKeydown.bind(this);
+    keyupListener = this.handleKeyup.bind(this);
+    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,8 +215,8 @@ class KeyboardShortcuts {
     formatShortcutForUI(shortcut) {
         return {
             id: shortcut.id,
-            keys: this.formatKeysForDisplay(shortcut.keys, false),
-            macKeys: this.formatKeysForDisplay(shortcut.macKeys, true),
+            keys: this.formatStepsForDisplay(shortcut.keys ?? shortcut.steps ?? [], false),
+            macKeys: this.formatStepsForDisplay(shortcut.macKeys ?? shortcut.macSteps ?? [], true),
             description: shortcut.description
         };
     }
@@ -199,56 +248,121 @@ class KeyboardShortcuts {
             .map(key => keyMap[key.toLowerCase()] || key.toUpperCase())
             .join('+');
     }
+    formatStepsForDisplay(steps, isMac = false) {
+        if (!steps)
+            return '';
+        // If the first element is an array, assume steps is string[][]
+        const normalized = this.normalizeToSteps(steps);
+        if (normalized.length === 0)
+            return '';
+        if (normalized.length === 1)
+            return this.formatKeysForDisplay(normalized[0], 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])) {
+            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()) {
-            if (this.keysMatch(newShortcut.keys, existing.keys)) {
+            // 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;
             }
-            if (this.keysMatch(newShortcut.macKeys, existing.macKeys)) {
+            if (newShortcut.macKeys && existing.macKeys && this.keysMatch(newShortcut.macKeys, existing.macKeys)) {
+                return existing.id;
+            }
+            // Compare multi-step shapes
+            if (newShortcut.steps && existing.steps && this.stepsMatch(newShortcut.steps, existing.steps)) {
+                return existing.id;
+            }
+            if (newShortcut.macSteps && existing.macSteps && this.stepsMatch(newShortcut.macSteps, existing.macSteps)) {
                 return existing.id;
             }
         }
         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) {
+    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) {
@@ -276,7 +390,8 @@ class KeyboardShortcuts {
             const group = {
                 id: groupId,
                 shortcuts,
-                active: true
+                active: true,
+                filter: options.filter
             };
             this.groups.set(groupId, group);
             this.activeGroups.add(groupId);
@@ -284,8 +399,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(options.activeUntil, this.unregisterGroup.bind(this, groupId));
     }
     /**
      * Unregister a single keyboard shortcut
@@ -297,6 +414,7 @@ class KeyboardShortcuts {
         }
         this.shortcuts.delete(shortcutId);
         this.activeShortcuts.delete(shortcutId);
+        this.shortcutToGroup.delete(shortcutId);
         this.updateState();
     }
     /**
@@ -312,6 +430,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);
@@ -319,12 +438,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 > 0) {
+            throw KeyboardShortcutsErrorFactory.activationKeyConflict(shortcutId, conflicts);
+        }
         this.activeShortcuts.add(shortcutId);
         this.updateState();
     }
@@ -341,13 +465,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 > 0) {
+            throw KeyboardShortcutsErrorFactory.groupActivationKeyConflict(groupId, allConflicts);
+        }
         this.batchUpdate(() => {
             group.active = true;
             this.activeGroups.add(groupId);
@@ -409,69 +542,466 @@ 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);
+    }
+    /**
+     * 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;
         }
-        document.addEventListener('keydown', this.keydownListener, { passive: false });
+        // 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.
+        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.
+        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);
+        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) {
-        const pressedKeys = this.getPressedKeys(event);
+        // Update the currently down keys with this event's key
+        this.updateCurrentlyDownKeysOnKeydown(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 > 0) {
+            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 ?? []);
+                const normalizedSteps = this.normalizeToSteps(steps);
+                const expected = normalizedSteps[pending.stepIndex];
+                // Use per-event pressed keys for advancing sequence steps. Relying on
+                // the accumulated `currentlyDownKeys` can accidentally include keys
+                // 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 as a Set<string>.
+                const stepPressed = this.getPressedKeys(event);
+                if (expected && this.keysMatch(stepPressed, expected)) {
+                    // Advance sequence
+                    clearTimeout(pending.timerId);
+                    pending.stepIndex += 1;
+                    if (pending.stepIndex >= normalizedSteps.length) {
+                        // Completed - check filters before executing
+                        if (!this.shouldProcessEvent(event, shortcut)) {
+                            this.pendingSequence = null;
+                            return; // Skip execution due to filters
+                        }
+                        event.preventDefault();
+                        event.stopPropagation();
+                        try {
+                            shortcut.action();
+                        }
+                        catch (error) {
+                            console.error(`Error executing keyboard shortcut "${shortcut.id}":`, error);
+                        }
+                        this.pendingSequence = null;
+                        return;
+                    }
+                    // Reset timer for next step
+                    pending.timerId = setTimeout(() => { this.pendingSequence = null; }, this.sequenceTimeout);
+                    return;
+                }
+                else {
+                    // Cancel pending if doesn't match
+                    this.clearPendingSequence();
+                }
+            }
+            else {
+                // pending exists but shortcut not found
+                this.clearPendingSequence();
+            }
+        }
+        // No pending sequence - check active shortcuts for a match or sequence start
         for (const shortcutId of this.activeShortcuts) {
             const shortcut = this.shortcuts.get(shortcutId);
             if (!shortcut)
                 continue;
-            const targetKeys = isMac ? shortcut.macKeys : shortcut.keys;
-            if (this.keysMatch(pressedKeys, targetKeys)) {
-                event.preventDefault();
-                event.stopPropagation();
-                try {
-                    shortcut.action();
+            // 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];
+            // 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;
+            // Normalize pressed keys to a Set<string> for consistent typing
+            const pressedForStep = nonModifierCount > 1
+                ? 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 === 1) {
+                    // single-step
+                    event.preventDefault();
+                    event.stopPropagation();
+                    try {
+                        shortcut.action();
+                    }
+                    catch (error) {
+                        console.error(`Error executing keyboard shortcut "${shortcut.id}":`, error);
+                    }
+                    break;
                 }
-                catch (error) {
-                    console.error(`Error executing keyboard shortcut "${shortcut.id}":`, error);
+                else {
+                    // start pending sequence
+                    if (this.pendingSequence) {
+                        this.clearPendingSequence();
+                    }
+                    this.pendingSequence = {
+                        shortcutId: shortcut.id,
+                        stepIndex: 1,
+                        timerId: setTimeout(() => { this.pendingSequence = null; }, this.sequenceTimeout)
+                    };
+                    event.preventDefault();
+                    event.stopPropagation();
+                    return;
                 }
-                break; // Only execute the first matching shortcut
             }
         }
     }
-    getPressedKeys(event) {
-        const keys = [];
+    handleKeyup(event) {
+        // Remove the key from currentlyDownKeys on keyup
+        const key = event.key ? event.key.toLowerCase() : '';
+        if (key && !KeyboardShortcuts.MODIFIER_KEYS.has(key)) {
+            this.currentlyDownKeys.delete(key);
+        }
+    }
+    /**
+     * Clear the currently-down keys. Exposed for testing and for use by
+     * blur/visibilitychange handlers to avoid stale state when the page loses focus.
+     */
+    clearCurrentlyDownKeys() {
+        this.currentlyDownKeys.clear();
+    }
+    handleWindowBlur() {
+        this.clearCurrentlyDownKeys();
+        // Clear any pressed keys and any pending multi-step sequence to avoid
+        // stale state when the window loses focus.
+        this.clearPendingSequence();
+    }
+    handleVisibilityChange() {
+        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();
+        }
+    }
+    /**
+     * Update the currentlyDownKeys set when keydown events happen.
+     * Normalizes common keys (function keys, space, etc.) to the same values
+     * used by getPressedKeys/keysMatch.
+     */
+    updateCurrentlyDownKeysOnKeydown(event) {
+        const key = event.key ? event.key.toLowerCase() : '';
+        // Ignore modifier-only keydown entries
+        if (KeyboardShortcuts.MODIFIER_KEYS.has(key)) {
+            return;
+        }
+        // Normalize some special cases similar to the demo component's recording logic
+        if (event.code && event.code.startsWith('F') && /^F\d+$/.test(event.code)) {
+            this.currentlyDownKeys.add(event.code.toLowerCase());
+            return;
+        }
+        if (key === ' ') {
+            this.currentlyDownKeys.add('space');
+            return;
+        }
+        if (key === 'escape') {
+            this.currentlyDownKeys.add('escape');
+            return;
+        }
+        if (key === 'enter') {
+            this.currentlyDownKeys.add('enter');
+            return;
+        }
+        if (key && key.length > 0) {
+            this.currentlyDownKeys.add(key);
+        }
+    }
+    /**
+     * Build the pressed keys set 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.
+     *
+     * Returns a Set<string> (lowercased) to allow O(1) lookups and O(n) comparisons
+     * without sorting or allocating sorted arrays on every event.
+     */
+    buildPressedKeysForMatch(event) {
+        const modifiers = new Set();
         if (event.ctrlKey)
-            keys.push('ctrl');
+            modifiers.add('ctrl');
         if (event.altKey)
-            keys.push('alt');
+            modifiers.add('alt');
         if (event.shiftKey)
-            keys.push('shift');
+            modifiers.add('shift');
         if (event.metaKey)
-            keys.push('meta');
-        // Add the main key (normalize to lowercase)
+            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 result = new Set();
+        // Add modifiers first
+        modifiers.forEach(m => result.add(m));
+        if (nonModifierKeys.length > 0) {
+            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)) {
-            keys.push(key);
+        if (!KeyboardShortcuts.MODIFIER_KEYS.has(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 result = new Set();
+        if (event.ctrlKey)
+            result.add('ctrl');
+        if (event.altKey)
+            result.add('alt');
+        if (event.shiftKey)
+            result.add('shift');
+        if (event.metaKey)
+            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)) {
+            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.
+     */
     keysMatch(pressedKeys, targetKeys) {
-        if (pressedKeys.length !== targetKeys.length) {
+        // 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;
+    }
+    /** Compare two multi-step sequences for equality */
+    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;
         }
-        // Normalize and sort both arrays for comparison
-        const normalizedPressed = pressedKeys.map(key => key.toLowerCase()).sort();
-        const normalizedTarget = targetKeys.map(key => key.toLowerCase()).sort();
-        return normalizedPressed.every((key, index) => key === normalizedTarget[index]);
+        return true;
+    }
+    /** Safely clear any pending multi-step sequence */
+    clearPendingSequence() {
+        if (!this.pendingSequence)
+            return;
+        try {
+            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) {
+            return;
+        }
+        if (activeUntil === 'destruct') {
+            inject(DestroyRef).onDestroy(unregister);
+            return;
+        }
+        // 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;
+        }
+        if (activeUntil instanceof Observable) {
+            activeUntil.pipe(take(1)).subscribe(unregister);
+            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 === 0)
+            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' });