ngx-keys 1.2.0 → 1.3.0

package/README.md

@@ -5,13 +5,15 @@ 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
-- **� Smart Conflict Detection**: Register multiple shortcuts with same keys when not simultaneously active
-- **�🪶 Lightweight**: Zero dependencies, minimal bundle impact
+- **⚙️ 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
 
@@ -84,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
 
@@ -95,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:**
@@ -177,23 +283,53 @@ this.keyboardService.activateGroup('editor');   // Re-enable all editor shortcut
 
 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)'
 });
 ```
 
+**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:
@@ -208,6 +344,52 @@ 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:
@@ -367,15 +549,38 @@ Conflicts are only checked among **active** shortcuts, not all registered shortc
 
 - `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*
+**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 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
@@ -383,6 +588,7 @@ Conflicts are only checked among **active** shortcuts, not all registered shortc
 - `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
@@ -425,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)
@@ -435,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
 }
 ```
@@ -450,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
@@ -686,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]