ngx-keys 1.1.0 → 1.3.0

package/README.md

@@ -5,11 +5,14 @@ A lightweight, reactive Angular service for managing keyboard shortcuts with sig
 ## Features
 
 - **🎯 Service-Focused**: Clean, focused API without unnecessary UI components
+- **📝 Declarative Directive**: Optional directive for template-based shortcut registration
 - **⚡ Reactive Signals**: Track active/inactive shortcuts with Angular signals
 - **🔧 UI-Agnostic**: Build your own UI using the provided reactive signals
 - **🌍 Cross-Platform**: Automatic Mac/PC key display formatting
 - **🔄 Dynamic Management**: Add, remove, activate/deactivate shortcuts at runtime
 - **📁 Group Management**: Organize shortcuts into logical groups
+- **⚙️ Configurable**: Customize sequence timeout and other behavior via dependency injection
+- **🔍 Smart Conflict Detection**: Register multiple shortcuts with same keys when not simultaneously active
 - **🪶 Lightweight**: Zero dependencies, minimal bundle impact
 
 ## Installation
@@ -83,7 +86,110 @@ export class MyComponent {
 }
 ```
 
+### Using the Directive (Declarative Approach)
 
+For a more declarative approach, use the `ngxKeys` directive directly on your elements:
+
+```typescript
+import { Component } from '@angular/core';
+import { KeyboardShortcutDirective } from 'ngx-keys';
+
+@Component({
+  standalone: true,
+  imports: [KeyboardShortcutDirective],
+  template: `
+    <h3>My App</h3>
+    <p>Last action: {{ lastAction }}</p>
+    
+    <!-- Directive automatically registers and unregisters shortcuts -->
+    <button 
+      ngxKeys
+      keys="ctrl,s"
+      macKeys="cmd,s"
+      description="Save document"
+      (click)="save()">
+      Save
+    </button>
+    
+    <button 
+      ngxKeys
+      keys="ctrl,h"
+      macKeys="cmd,h"
+      description="Show help"
+      (click)="showHelp()">
+      Help
+    </button>
+    
+    <!-- Multi-step shortcuts work too -->
+    <button 
+      ngxKeys
+      [steps]="[['ctrl', 'k'], ['ctrl', 'p']]"
+      [macSteps]="[['cmd', 'k'], ['cmd', 'p']]"
+      description="Open command palette (Ctrl+K then Ctrl+P)"
+      (click)="openCommandPalette()">
+      Command Palette
+    </button>
+    
+    <!-- Use custom action instead of click -->
+    <div 
+      ngxKeys
+      keys="?"
+      description="Show help overlay"
+      [action]="showHelpOverlay">
+      Press ? for help
+    </div>
+  `
+})
+export class MyComponent {
+  protected lastAction = 'Try pressing Ctrl+S or Ctrl+H';
+  
+  protected readonly showHelpOverlay = () => {
+    this.lastAction = 'Help overlay displayed!';
+  };
+
+  protected save() {
+    this.lastAction = 'Document saved!';
+  }
+
+  protected showHelp() {
+    this.lastAction = 'Help displayed!';
+  }
+  
+  protected openCommandPalette() {
+    this.lastAction = 'Command palette opened!';
+  }
+}
+```
+
+> [!TIP]
+> The directive automatically:
+> - Registers shortcuts when initialized
+> - Triggers click events on the host element (or executes a custom action)
+> - Unregisters shortcuts when destroyed
+> - Adds a `data-keyboard-shortcut` attribute for styling/testing
+
+**Directive Inputs:**
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `keys` | `string` | Comma-separated keys for single-step shortcut (e.g., `"ctrl,s"`) |
+| `macKeys` | `string` | Comma-separated keys for Mac (e.g., `"cmd,s"`) |
+| `steps` | `string[][]` | Multi-step sequence (e.g., `[['ctrl', 'k'], ['ctrl', 'd']]`) |
+| `macSteps` | `string[][]` | Multi-step sequence for Mac |
+| `description` | `string` | Required. Description of what the shortcut does |
+| `action` | `() => void` | Optional custom action. If not provided, triggers click on host element |
+| `shortcutId` | `string` | Optional custom ID. If not provided, generates unique ID |
+
+**Directive Outputs:**
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `triggered` | `void` | Emitted when the keyboard shortcut is triggered |
+
+**When to use the directive vs. the service:**
+
+- **Use the directive** when shortcuts are tied to specific UI elements and their lifecycle
+- **Use the service** when you need programmatic control, dynamic shortcuts, or shortcuts not tied to elements
 
 ## Explore the Demo
 
@@ -94,6 +200,7 @@ Want to see ngx-keys in action? Check out our comprehensive [demo application](/
 | [**App Component**](/projects/demo/src/app/app.ts)                                 | Global shortcuts           | Single & group registration, cleanup patterns |
 | [**Home Component**](/projects/demo/src/app/home/home.component.ts)                | Reactive UI                | Real-time status display, toggle controls     |
 | [**Feature Component**](/projects/demo/src/app/feature/feature.component.ts)       | Route-specific shortcuts   | Scoped shortcuts, lifecycle management        |
+| [**Directive Demo**](/projects/demo/src/app/directive-demo/directive-demo.component.ts) | Declarative shortcuts      | Directive usage, automatic lifecycle management |
 | [**Customize Component**](/projects/demo/src/app/customize/customize.component.ts) | Dynamic shortcut recording | Real-time key capture, shortcut customization |
 
 **Run the demo:**
@@ -122,27 +229,107 @@ this.keyboardService.register({
 });
 ```
 
+### Smart Conflict Detection
+> [!IMPORTANT]
+Conflicts are only checked among **active** shortcuts, not all registered shortcuts.
+
+ngx-keys allows registering multiple shortcuts with the same key combination, as long as they're not simultaneously active. This enables powerful patterns:
+
+- **Context-specific shortcuts**: Same keys for different UI contexts
+- **Alternative shortcuts**: Multiple ways to trigger the same action 
+- **Feature toggles**: Same keys for different modes
+
+```typescript
+// Basic conflict handling
+this.keyboardService.register(shortcut1); // Active by default
+this.keyboardService.deactivate('shortcut1'); 
+this.keyboardService.register(shortcut2); // Same keys, but shortcut1 is inactive ✅
+
+// This would fail - conflicts with active shortcut2
+// this.keyboardService.activate('shortcut1'); // ❌ Throws error
+```
+
+### Group Management
+
+Organize related shortcuts into groups for easier management:
+
+```typescript
+const editorShortcuts = [
+  {
+    id: 'bold',
+    keys: ['ctrl', 'b'],
+    macKeys: ['meta', 'b'],
+    action: () => this.makeBold(),
+    description: 'Make text bold'
+  },
+  {
+    id: 'italic', 
+    keys: ['ctrl', 'i'],
+    macKeys: ['meta', 'i'],
+    action: () => this.makeItalic(),
+    description: 'Make text italic'
+  }
+];
+
+// Register all shortcuts in the group
+this.keyboardService.registerGroup('editor', editorShortcuts);
+
+// Control the entire group
+this.keyboardService.deactivateGroup('editor'); // Disable all editor shortcuts
+this.keyboardService.activateGroup('editor');   // Re-enable all editor shortcuts
+```
+
 ### Multi-step (sequence) shortcuts
 
 In addition to single-step shortcuts using `keys` / `macKeys`, ngx-keys supports ordered multi-step sequences using `steps` and `macSteps` on the `KeyboardShortcut` object. Each element in `steps` is itself an array of key tokens that must be pressed together for that step.
 
-Example: register a sequence that requires `Ctrl+K` followed by `S`:
+Example: register a sequence that requires `Ctrl+K` followed by `Ctrl+D`:
 
 ```typescript
 this.keyboardService.register({
-  id: 'open-settings-seq',
-  steps: [['ctrl', 'k'], ['s']],
-  macSteps: [['meta', 'k'], ['s']],
-  action: () => this.openSettings(),
-  description: 'Open settings (Ctrl+K then S)'
+  id: 'format-document-seq',
+  steps: [['ctrl', 'k'], ['ctrl', 'd']],
+  macSteps: [['meta', 'k'], ['meta', 'd']],
+  action: () => this.formatDocument(),
+  description: 'Format document (Ctrl+K then Ctrl+D)'
 });
 ```
 
-Important behavior notes:
+**Configuring Sequence Timeout**
+
+By default, multi-step shortcuts have **no timeout** - users can take as long as they need between steps. You can configure a timeout globally using a provider function:
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideKeyboardShortcutsConfig } from 'ngx-keys';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideKeyboardShortcutsConfig({ sequenceTimeoutMs: 2000 })  // 2 seconds
+  ]
+};
+```
+
+Alternatively, you can use the injection token directly:
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { KEYBOARD_SHORTCUTS_CONFIG } from 'ngx-keys';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: KEYBOARD_SHORTCUTS_CONFIG,
+      useValue: { sequenceTimeoutMs: 2000 }  // 2 seconds
+    }
+  ]
+};
+```
+
+**Important behavior notes**
 
-- Default sequence timeout: the service requires the next step to be entered within 2000ms (2 seconds) of the previous step; otherwise the pending sequence is cleared. This timeout is intentionally conservative and can be changed in future releases or exposed per-shortcut if needed.
-- Steps are order-sensitive. `steps: [['ctrl','k'], ['s']]` is different from `steps: [['s'], ['ctrl','k']]`.
-- Existing single-step `keys` / `macKeys` remain supported and continue to work as before.
+- **Sequence timeout**: Steps must be entered within the configured timeout (default 2000ms) or the sequence is cleared.
+- **Order-sensitive**: Steps are order-sensitive. `steps: [['ctrl','k'], ['s']]` is different from `steps: [['s'], ['ctrl','k']]`.
 
 
 Use the `activate()` and `deactivate()` methods for dynamic control after registration:
@@ -155,6 +342,201 @@ this.keyboardService.deactivate('save');
 this.keyboardService.activate('save');
 ```
 
+## Advanced Usage
+
+### Type-Safe Action Functions
+
+For better type safety and code reusability, use the exported `Action` type when defining action functions:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { KeyboardShortcuts, Action } from 'ngx-keys';
+
+export class MyComponent {
+  private readonly keyboardService = inject(KeyboardShortcuts);
+
+  // Define reusable, type-safe action functions
+  private readonly saveAction: Action = () => {
+    console.log('Saving document...');
+    this.performSave();
+  };
+
+  private readonly undoAction: Action = () => {
+    console.log('Undoing...');
+    this.performUndo();
+  };
+
+  constructor() {
+    // Use the typed actions in shortcuts
+    this.keyboardService.register({
+      id: 'save',
+      keys: ['ctrl', 's'],
+      macKeys: ['meta', 's'],
+      action: this.saveAction,
+      description: 'Save document'
+    });
+
+    this.keyboardService.register({
+      id: 'undo',
+      keys: ['ctrl', 'z'],
+      macKeys: ['meta', 'z'],
+      action: this.undoAction,
+      description: 'Undo last action'
+    });
+  }
+
+  private performSave() { /* implementation */ }
+  private performUndo() { /* implementation */ }
+}
+```
+
+### Context-Specific Shortcuts
+
+Register different actions for the same keys in different UI contexts:
+
+```typescript
+// Modal context
+this.keyboardService.register({
+  id: 'modal-escape',
+  keys: ['escape'],
+  action: () => this.closeModal(),
+  description: 'Close modal'
+});
+
+// Initially deactivate since modal isn't shown
+this.keyboardService.deactivate('modal-escape');
+
+// Editor context  
+this.keyboardService.register({
+  id: 'editor-escape',
+  keys: ['escape'], // Same key, different context
+  action: () => this.exitEditMode(),
+  description: 'Exit edit mode'
+});
+
+// Switch contexts dynamically
+showModal() {
+  this.keyboardService.deactivate('editor-escape');
+  this.keyboardService.activate('modal-escape');
+}
+
+hideModal() {
+  this.keyboardService.deactivate('modal-escape');
+  this.keyboardService.activate('editor-escape');
+}
+```
+
+### Alternative Shortcuts
+
+Provide multiple ways to trigger the same functionality:
+
+```typescript
+// Primary shortcut
+this.keyboardService.register({
+  id: 'help-f1',
+  keys: ['f1'],
+  action: () => this.showHelp(),
+  description: 'Show help (F1)'
+});
+
+// Alternative shortcut - different keys, same action
+this.keyboardService.register({
+  id: 'help-ctrl-h',
+  keys: ['ctrl', 'h'],
+  action: () => this.showHelp(), // Same action
+  description: 'Show help (Ctrl+H)'
+});
+
+// Both are active simultaneously since they don't conflict
+```
+
+### Feature Toggles
+
+Switch between different modes that use the same keys:
+
+```typescript
+// Design mode
+this.keyboardService.register({
+  id: 'design-mode-space',
+  keys: ['space'],
+  action: () => this.toggleDesignElement(),
+  description: 'Toggle design element'
+});
+
+// Play mode (same key, different action)
+this.keyboardService.register({
+  id: 'play-mode-space',
+  keys: ['space'],
+  action: () => this.pausePlayback(),
+  description: 'Pause/resume playback'
+});
+
+// Initially deactivate play mode
+this.keyboardService.deactivate('play-mode-space');
+
+// Switch modes
+switchToPlayMode() {
+  this.keyboardService.deactivate('design-mode-space');
+  this.keyboardService.activate('play-mode-space');
+}
+
+switchToDesignMode() {
+  this.keyboardService.deactivate('play-mode-space');
+  this.keyboardService.activate('design-mode-space');
+}
+```
+
+### Advanced Group Patterns
+
+Use groups for complex activation/deactivation scenarios:
+
+```typescript
+// Create context-specific groups
+const modalShortcuts = [
+  { id: 'modal-close', keys: ['escape'], action: () => this.closeModal(), description: 'Close modal' },
+  { id: 'modal-confirm', keys: ['enter'], action: () => this.confirmModal(), description: 'Confirm' }
+];
+
+const editorShortcuts = [
+  { id: 'editor-save', keys: ['ctrl', 's'], action: () => this.save(), description: 'Save' },
+  { id: 'editor-undo', keys: ['ctrl', 'z'], action: () => this.undo(), description: 'Undo' }
+];
+
+// Register both groups
+this.keyboardService.registerGroup('modal', modalShortcuts);
+this.keyboardService.registerGroup('editor', editorShortcuts);
+
+// Initially only editor is active
+this.keyboardService.deactivateGroup('modal');
+
+// Switch contexts
+showModal() {
+  this.keyboardService.deactivateGroup('editor');
+  this.keyboardService.activateGroup('modal');
+}
+
+hideModal() {
+  this.keyboardService.deactivateGroup('modal');
+  this.keyboardService.activateGroup('editor');
+}
+```
+
+### Conflict Detection Rules
+
+- **Registration**: Only checks conflicts with currently **active** shortcuts
+- **Activation**: Throws error if activating would conflict with other active shortcuts
+- **Groups**: Same rules apply - groups can contain conflicting shortcuts as long as they're not simultaneously active
+
+```typescript
+// ✅ This works - shortcuts with same keys but only one active at a time
+this.keyboardService.register(shortcut1); // Active by default
+this.keyboardService.deactivate('shortcut1'); 
+this.keyboardService.register(shortcut2); // Same keys, but shortcut1 is inactive
+
+// ❌ This fails - trying to activate would create conflict
+this.keyboardService.activate('shortcut1'); // Throws error - conflicts with active shortcut2
+```
+
 ## API Reference
 
 ### KeyboardShortcuts Service
@@ -162,17 +544,43 @@ this.keyboardService.activate('save');
 #### Methods
 
 **Registration Methods:**
-- `register(shortcut: KeyboardShortcut)` - Register and automatically activate a single shortcut *Throws error on conflicts*
-- `registerGroup(groupId: string, shortcuts: KeyboardShortcut[])` - Register and automatically activate a group of shortcuts *Throws error on conflicts*
+> [!TIP]
+Conflicts are only checked among **active** shortcuts, not all registered shortcuts.
+
+- `register(shortcut: KeyboardShortcut)` - Register and automatically activate a single shortcut *Throws error on conflicts with active shortcuts only*
+- `registerGroup(groupId: string, shortcuts: KeyboardShortcut[])` - Register and automatically activate a group of shortcuts *Throws error on conflicts with active shortcuts only*
+- `registerMany(shortcuts: KeyboardShortcut[])` - Register multiple shortcuts in a single batch update
+
+**Unregistration Methods:**
+> [!NOTE]
+> `unregister()` automatically removes shortcuts from all groups they belong to.
+
+- `unregister(shortcutId: string)` - Remove a shortcut and its group associations *Throws error if not found*
+- `unregisterGroup(groupId: string)` - Remove a group and all its shortcuts *Throws error if not found*
+- `unregisterMany(ids: string[])` - Unregister multiple shortcuts in a single batch update
+- `unregisterGroups(ids: string[])` - Unregister multiple groups in a single batch update
+- `clearAll()` - Remove all shortcuts, groups, and filters (nuclear reset)
 
-**Management Methods:**
-- `unregister(shortcutId: string)` - Remove a shortcut *Throws error if not found*
-- `unregisterGroup(groupId: string)` - Remove a group *Throws error if not found*
-- `activate(shortcutId: string)` - Activate a shortcut *Throws error if not registered*
+**Activation Methods:**
+- `activate(shortcutId: string)` - Activate a shortcut *Throws error if not registered or would create conflicts*
 - `deactivate(shortcutId: string)` - Deactivate a shortcut *Throws error if not registered*
-- `activateGroup(groupId: string)` - Activate all shortcuts in a group *Throws error if not found*
+- `activateGroup(groupId: string)` - Activate all shortcuts in a group *Throws error if not found or would create conflicts*
 - `deactivateGroup(groupId: string)` - Deactivate all shortcuts in a group *Throws error if not found*
 
+**Filter Methods:**
+- `addFilter(name: string, filter: Function)` - Add a named global filter
+- `removeFilter(name: string)` - Remove a named global filter
+- `clearFilters()` - Remove all global filters
+- `hasFilter(name: string): boolean` - Check if a filter exists
+- `getFilter(name: string)` - Get a filter function by name
+- `getFilterNames(): string[]` - Get all filter names
+- `removeGroupFilter(groupId: string)` - Remove filter from a group
+- `removeShortcutFilter(shortcutId: string)` - Remove filter from a shortcut
+- `clearAllGroupFilters()` - Remove all group filters
+- `clearAllShortcutFilters()` - Remove all shortcut filters
+- `hasGroupFilter(groupId: string): boolean` - Check if group has a filter
+- `hasShortcutFilter(shortcutId: string): boolean` - Check if shortcut has a filter
+
 **Query Methods:**
 - `isActive(shortcutId: string): boolean` - Check if a shortcut is active
 - `isRegistered(shortcutId: string): boolean` - Check if a shortcut is registered
@@ -180,6 +588,7 @@ this.keyboardService.activate('save');
 - `isGroupRegistered(groupId: string): boolean` - Check if a group is registered
 - `getShortcuts(): ReadonlyMap<string, KeyboardShortcut>` - Get all registered shortcuts
 - `getGroups(): ReadonlyMap<string, KeyboardShortcutGroup>` - Get all registered groups
+- `getGroupShortcuts(groupId: string): KeyboardShortcut[]` - Get all shortcuts in a specific group
 
 **Utility Methods:**
 - `formatShortcutForUI(shortcut: KeyboardShortcut): KeyboardShortcutUI` - Format a shortcut for display
@@ -222,6 +631,9 @@ interface KeyboardShortcutUI {
 ### KeyboardShortcut Interface
 
 ```typescript
+// Type for shortcut action functions
+type Action = () => void;
+
 interface KeyboardShortcut {
   id: string;           // Unique identifier
   // Single-step combinations (existing API)
@@ -232,7 +644,7 @@ interface KeyboardShortcut {
   // Each step is an array of keys pressed together. Example: steps: [['ctrl','k'], ['s']]
   steps?: string[][];
   macSteps?: string[][];
-  action: () => void;   // Function to execute
+  action: Action;       // Function to execute
   description: string;  // Human-readable description
 }
 ```
@@ -247,6 +659,108 @@ interface KeyboardShortcutGroup {
 }
 ```
 
+### KeyboardShortcutDirective
+
+A declarative directive for registering keyboard shortcuts directly in templates.
+
+#### Selector
+```typescript
+[ngxKeys]
+```
+
+#### Inputs
+
+| Input | Type | Required | Description |
+|-------|------|----------|-------------|
+| `keys` | `string` | No* | Comma-separated keys for single-step shortcut (e.g., `"ctrl,s"`) |
+| `macKeys` | `string` | No | Comma-separated keys for Mac (e.g., `"cmd,s"`) |
+| `steps` | `string[][]` | No* | Multi-step sequence. Each inner array is one step (e.g., `[['ctrl', 'k'], ['ctrl', 'd']]`) |
+| `macSteps` | `string[][]` | No | Multi-step sequence for Mac |
+| `description` | `string` | **Yes** | Human-readable description of what the shortcut does |
+| `action` | `() => void` | No | Custom action to execute. If not provided, triggers click on host element |
+| `shortcutId` | `string` | No | Custom ID for the shortcut. If not provided, generates a unique ID |
+
+\* Either `keys`/`macKeys` OR `steps`/`macSteps` must be provided (not both)
+
+#### Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `triggered` | `void` | Emitted when the keyboard shortcut is triggered (in addition to the action) |
+
+#### Host Bindings
+
+The directive adds the following to the host element:
+- `data-keyboard-shortcut` attribute with the shortcut ID (useful for styling or testing)
+
+#### Behavior
+
+- **Registration**: Automatically registers the shortcut when the directive initializes
+- **Default Action**: Triggers a click event on the host element (unless custom `action` is provided)
+- **Cleanup**: Automatically unregisters the shortcut when the directive is destroyed
+- **Error Handling**: Throws errors for invalid input combinations or registration failures
+
+#### Usage Examples
+
+**Basic button with click trigger:**
+```html
+<button 
+  ngxKeys
+  keys="ctrl,s"
+  macKeys="cmd,s"
+  description="Save document"
+  (click)="save()">
+  Save
+</button>
+```
+
+**Multi-step shortcut:**
+```html
+<button 
+  ngxKeys
+  [steps]="[['ctrl', 'k'], ['ctrl', 'd']]"
+  [macSteps]="[['cmd', 'k'], ['cmd', 'd']]"
+  description="Format document (Ctrl+K then Ctrl+D)"
+  (click)="format()">
+  Format
+</button>
+```
+
+**Custom action on non-interactive element:**
+```html
+<div 
+  ngxKeys
+  keys="?"
+  description="Show help"
+  [action]="showHelp">
+  Press ? for help
+</div>
+```
+
+**Listen to triggered event:**
+```html
+<button 
+  ngxKeys
+  keys="ctrl,s"
+  description="Save document"
+  (triggered)="onShortcutTriggered()"
+  (click)="save()">
+  Save
+</button>
+```
+
+**Custom shortcut ID:**
+```html
+<button 
+  ngxKeys
+  keys="ctrl,s"
+  description="Save document"
+  shortcutId="my-custom-save-shortcut"
+  (click)="save()">
+  Save
+</button>
+```
+
 ## Key Mapping Reference
 
 ### Modifier Keys
@@ -483,6 +997,130 @@ export class BatchUpdateComponent {
 }
 ```
 
+### Bulk Registration and Unregistration
+
+Register or unregister multiple shortcuts efficiently:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { KeyboardShortcuts } from 'ngx-keys';
+
+export class MyComponent {
+  private readonly keyboardService = inject(KeyboardShortcuts);
+
+  setupToolbarShortcuts() {
+    // Register multiple shortcuts at once
+    this.keyboardService.registerMany([
+      {
+        id: 'save',
+        keys: ['ctrl', 's'],
+        macKeys: ['meta', 's'],
+        action: () => this.save(),
+        description: 'Save document'
+      },
+      {
+        id: 'save-as',
+        keys: ['ctrl', 'shift', 's'],
+        macKeys: ['meta', 'shift', 's'],
+        action: () => this.saveAs(),
+        description: 'Save as...'
+      },
+      {
+        id: 'print',
+        keys: ['ctrl', 'p'],
+        macKeys: ['meta', 'p'],
+        action: () => this.print(),
+        description: 'Print document'
+      }
+    ]);
+  }
+
+  cleanup() {
+    // Unregister multiple shortcuts at once
+    this.keyboardService.unregisterMany(['save', 'save-as', 'print']);
+    
+    // Or unregister entire groups
+    this.keyboardService.unregisterGroups(['toolbar', 'menu']);
+    
+    // Or clear everything
+    this.keyboardService.clearAll();
+  }
+
+  private save() { /* implementation */ }
+  private saveAs() { /* implementation */ }
+  private print() { /* implementation */ }
+}
+```
+
+### Managing Group Shortcuts
+
+Remove individual shortcuts from groups and query group contents:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { KeyboardShortcuts } from 'ngx-keys';
+
+export class MyComponent {
+  private readonly keyboardService = inject(KeyboardShortcuts);
+
+  manageEditorGroup() {
+    // Check if a shortcut is registered
+    if (this.keyboardService.isRegistered('bold')) {
+      // Remove a shortcut - automatically removes it from all groups
+      this.keyboardService.unregister('bold');
+    }
+
+    // Remove multiple shortcuts (automatically removes from groups)
+    this.keyboardService.unregisterMany(['bold', 'italic', 'underline']);
+
+    // Get all shortcuts in a group
+    const editorShortcuts = this.keyboardService.getGroupShortcuts('editor');
+    console.log('Remaining editor shortcuts:', editorShortcuts);
+
+    // Or remove the entire group and all its shortcuts
+    this.keyboardService.unregisterGroup('editor');
+  }
+}
+```
+
+### Filter Management
+
+Remove filters when no longer needed:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { KeyboardShortcuts } from 'ngx-keys';
+
+export class MyComponent {
+  private readonly keyboardService = inject(KeyboardShortcuts);
+
+  setupModalFilters() {
+    // Add filters for modal context
+    this.keyboardService.addGroupFilter('navigation', () => this.isModalOpen);
+    this.keyboardService.addShortcutFilter('global-search', () => this.isModalOpen);
+  }
+
+  cleanupModalFilters() {
+    // Check if filters exist
+    if (this.keyboardService.hasGroupFilter('navigation')) {
+      // Remove specific group filter
+      this.keyboardService.removeGroupFilter('navigation');
+    }
+
+    if (this.keyboardService.hasShortcutFilter('global-search')) {
+      // Remove specific shortcut filter
+      this.keyboardService.removeShortcutFilter('global-search');
+    }
+
+    // Or clear all filters at once
+    this.keyboardService.clearAllGroupFilters();
+    this.keyboardService.clearAllShortcutFilters();
+  }
+
+  private isModalOpen = false;
+}
+```
+
 ### Checking Status
 
 > [!NOTE]
@@ -527,6 +1165,157 @@ this.keyboardService.register({
 });
 ```
 
+### Event Filtering
+
+You can configure which keyboard events should be processed by setting a filter function. This is useful for ignoring shortcuts when users are typing in input fields, text areas, or other form elements.
+
+> [!NOTE]
+> **No Default Filtering**: ngx-keys processes ALL keyboard events by default. This gives you maximum flexibility - some apps want shortcuts to work everywhere, others want to exclude form inputs. You decide!
+
+#### Named filters (recommended)
+
+For efficiency and control, prefer named global filters. You can toggle them on/off without replacing others, and ngx-keys evaluates them only once per keydown event (fast path), short‑circuiting further work when blocked.
+
+```typescript
+// Add named filters
+keyboardService.addFilter('forms', (event) => {
+  const t = event.target as HTMLElement | null;
+  const tag = t?.tagName?.toLowerCase();
+  return !(['input', 'textarea', 'select'].includes(tag ?? '')) && !t?.isContentEditable;
+});
+
+keyboardService.addFilter('modal-scope', (event) => {
+  const t = event.target as HTMLElement | null;
+  return !!t?.closest('.modal');
+});
+
+// Remove/toggle when context changes
+keyboardService.removeFilter('modal-scope');
+
+// Inspect and manage
+keyboardService.getFilterNames(); // ['forms']
+keyboardService.clearFilters();   // remove all
+```
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { KeyboardShortcuts, KeyboardShortcutFilter } from 'ngx-keys';
+
+export class FilterExampleComponent {
+  private readonly keyboardService = inject(KeyboardShortcuts);
+
+  constructor() {
+    // Set up shortcuts
+    this.keyboardService.register({
+      id: 'save',
+      keys: ['ctrl', 's'],
+      macKeys: ['meta', 's'],
+      action: () => this.save(),
+      description: 'Save document'
+    });
+
+    // Configure filtering to ignore form elements
+    this.setupInputFiltering();
+  }
+
+  private setupInputFiltering() {
+    const inputFilter: KeyboardShortcutFilter = (event) => {
+      const target = event.target as HTMLElement;
+      const tagName = target?.tagName?.toLowerCase();
+      return !['input', 'textarea', 'select'].includes(tagName) && !target?.isContentEditable;
+    };
+
+    // Use named filter for toggling
+    this.keyboardService.addFilter('forms', inputFilter);
+  }
+
+  private save() {
+    console.log('Document saved!');
+  }
+}
+```
+
+#### Common Filter Patterns
+
+**Ignore form elements:**
+```typescript
+const formFilter: KeyboardShortcutFilter = (event) => {
+  const target = event.target as HTMLElement;
+  const tagName = target?.tagName?.toLowerCase();
+  return !['input', 'textarea', 'select'].includes(tagName) && !target?.isContentEditable;
+};
+
+keyboardService.addFilter('forms', formFilter);
+```
+
+**Ignore elements with specific attributes:**
+```typescript
+const attributeFilter: KeyboardShortcutFilter = (event) => {
+  const target = event.target as HTMLElement;
+  return !target?.hasAttribute('data-no-shortcuts');
+};
+
+keyboardService.addFilter('no-shortcuts-attr', attributeFilter);
+```
+
+**Complex conditional filtering:**
+```typescript
+const conditionalFilter: KeyboardShortcutFilter = (event) => {
+  const target = event.target as HTMLElement;
+  
+  // Allow shortcuts in code editors (even though they're contentEditable)
+  if (target?.classList?.contains('code-editor')) {
+    return true;
+  }
+  
+  // Block shortcuts in form elements
+  if (target?.tagName?.match(/INPUT|TEXTAREA|SELECT/i) || target?.isContentEditable) {
+    return false;
+  }
+  
+  return true;
+};
+
+keyboardService.addFilter('conditional', conditionalFilter);
+```
+
+**Remove filtering:**
+```typescript
+// Remove a specific named filter
+keyboardService.removeFilter('forms');
+// Or remove all
+keyboardService.clearFilters();
+```
+
+#### Example: Modal Context Filtering
+
+```typescript
+export class ModalComponent {
+  constructor() {
+    // When modal opens, only allow modal-specific shortcuts
+    this.keyboardService.addFilter('modal-scope', (event) => {
+      const target = event.target as HTMLElement;
+      
+      // Only process events within the modal
+      return target?.closest('.modal') !== null;
+    });
+  }
+
+  onClose() {
+    // Restore normal filtering when modal closes
+    this.keyboardService.removeFilter('modal-scope');
+  }
+}
+```
+
+#### Performance tips
+
+- Filters are evaluated once per keydown before scanning shortcuts. If any global filter returns false, ngx-keys exits early and clears pending sequences.
+- Group-level filters are precomputed once per event; shortcuts in blocked groups are skipped without key matching.
+- Keep filters cheap and synchronous. Prefer reading event.target properties (tagName, isContentEditable, classList) over layout-triggering queries.
+- Use named filters to toggle contexts (modals, editors) without allocating new closures per interaction.
+- Avoid complex DOM traversals inside filters; if needed, memoize simple queries or use attributes (e.g., data-no-shortcuts).
+
 ## Building
 
 To build the library:
@@ -555,4 +1344,4 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
 4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+5. Open a Pull Request