ngx-keys 1.1.0 → 1.2.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 { DestroyRef, inject, DOCUMENT, signal, computed, afterNextRender, Injectable } 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,12 +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(),
@@ -135,24 +185,14 @@ 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();
@@ -230,11 +270,15 @@ class KeyboardShortcuts {
         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,42 +296,73 @@ 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) {
@@ -315,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);
@@ -323,9 +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(activeUntil, this.unregisterGroup.bind(this, groupId));
+        this.setupActiveUntil(options.activeUntil, this.unregisterGroup.bind(this, groupId));
     }
     /**
      * Unregister a single keyboard shortcut
@@ -337,6 +414,7 @@ class KeyboardShortcuts {
         }
         this.shortcuts.delete(shortcutId);
         this.activeShortcuts.delete(shortcutId);
+        this.shortcutToGroup.delete(shortcutId);
         this.updateState();
     }
     /**
@@ -352,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);
@@ -359,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();
     }
@@ -381,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);
@@ -449,45 +542,165 @@ 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;
         }
         // 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 > 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 ?? []);
@@ -498,14 +711,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;
                     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 {
@@ -536,12 +753,30 @@ 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)) {
+            // 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();
@@ -574,7 +809,7 @@ class KeyboardShortcuts {
     handleKeyup(event) {
         // Remove the key from currentlyDownKeys on keyup
         const key = event.key ? event.key.toLowerCase() : '';
-        if (key && !['control', 'alt', 'shift', 'meta'].includes(key)) {
+        if (key && !KeyboardShortcuts.MODIFIER_KEYS.has(key)) {
             this.currentlyDownKeys.delete(key);
         }
     }
@@ -592,7 +827,7 @@ 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.
@@ -608,7 +843,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 (KeyboardShortcuts.MODIFIER_KEYS.has(key)) {
             return;
         }
         // Normalize some special cases similar to the demo component's recording logic
@@ -632,11 +867,6 @@ class KeyboardShortcuts {
             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,7 +886,7 @@ 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 => !KeyboardShortcuts.MODIFIER_KEYS.has(k));
         const result = new Set();
         // Add modifiers first
         modifiers.forEach(m => result.add(m));
@@ -666,27 +896,31 @@ class KeyboardShortcuts {
         }
         // Fallback: single main key from the event (existing behavior)
         const key = event.key.toLowerCase();
-        if (!['control', 'alt', 'shift', 'meta'].includes(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 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 && !KeyboardShortcuts.MODIFIER_KEYS.has(key)) {
+            result.add(key);
         }
-        return keys;
+        return result;
     }
     /**
      * Compare pressed keys against a target key combination.
@@ -732,7 +966,7 @@ class KeyboardShortcuts {
         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 +976,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 +988,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 === 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' });
 }