ngx-keys 1.0.1 → 1.2.0

package/README.md

@@ -10,7 +10,8 @@ A lightweight, reactive Angular service for managing keyboard shortcuts with sig
 - **🌍 Cross-Platform**: Automatic Mac/PC key display formatting
 - **🔄 Dynamic Management**: Add, remove, activate/deactivate shortcuts at runtime
 - **📁 Group Management**: Organize shortcuts into logical groups
-- **🪶 Lightweight**: Zero dependencies, minimal bundle impact
+- **� Smart Conflict Detection**: Register multiple shortcuts with same keys when not simultaneously active
+- **�🪶 Lightweight**: Zero dependencies, minimal bundle impact
 
 ## Installation
 
@@ -122,6 +123,79 @@ 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`:
+
+```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)'
+});
+```
+
+**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.
+
+
 Use the `activate()` and `deactivate()` methods for dynamic control after registration:
 
 ```typescript
@@ -132,6 +206,155 @@ this.keyboardService.deactivate('save');
 this.keyboardService.activate('save');
 ```
 
+## Advanced Usage
+
+### 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
@@ -139,15 +362,18 @@ 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*
 
 **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*
+- `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*
 
 **Query Methods:**
@@ -201,8 +427,14 @@ interface KeyboardShortcutUI {
 ```typescript
 interface KeyboardShortcut {
   id: string;           // Unique identifier
-  keys: string[];       // Key combination for PC/Linux (e.g., ['ctrl', 's'])
-  macKeys: string[];    // Key combination for Mac (e.g., ['meta', 's'])
+  // Single-step combinations (existing API)
+  keys?: string[];       // Key combination for PC/Linux (e.g., ['ctrl', 's'])
+  macKeys?: string[];    // Key combination for Mac (e.g., ['meta', 's'])
+
+  // Multi-step sequences (new)
+  // Each step is an array of keys pressed together. Example: steps: [['ctrl','k'], ['s']]
+  steps?: string[][];
+  macSteps?: string[][];
   action: () => void;   // Function to execute
   description: string;  // Human-readable description
 }
@@ -356,6 +588,62 @@ export class FeatureComponent {
 }
 ```
 
+### Automatic unregistering
+
+`register` and `registerGroup` have the optional parameter: `activeUntil`. 
+The `activeUntil` parameter allows you to connect the shortcut to the wrappers lifecycle or logic in general.  
+
+`activeUntil` supports three types:
+- `'destruct'`: the shortcut injects the parents `DestroyRef` and unregisters once the component destructs
+- `DestroyRef`: DestroyRef which should trigger the destruction of the shortcut
+- `Observable<unknown>`: an Observable which will unregister the shortcut when triggered
+
+#### Example: `'destruct'`
+Shortcuts defined by this component will only be listening during the lifecycle of the component.
+Shortcuts are registered on construction and are automatically unregistered on destruction.
+
+```typescript
+export class Component {
+  constructor() {
+    const keyboardService = inject(KeyboardShortcuts)
+
+    keyboardService.register({
+      // ...
+      activeUntil: 'destruct', // alternatively: inject(DestroyRef)
+    });
+
+    keyboardService.registerGroup(
+      'shortcuts',
+      [/* ... */],
+      'destruct', // alternatively: inject(DestroyRef)
+    );
+  }
+}
+```
+
+#### Example: `Observable`
+
+```typescript
+const shortcutTTL = new Subject<void>();
+
+keyboardService.register({
+  // ...
+  activeUntil: shortcutTTL,
+});
+
+keyboardService.registerGroup(
+  'shortcuts',
+  [/* ... */], 
+  shortcutTTL,
+);
+
+// Shortcuts are listening...
+
+shortcutTTL.next();
+
+// Shortcuts are unregistered
+```
+
 ### Batch Operations
 
 For better performance when making multiple changes, use the `batchUpdate` method.
@@ -423,6 +711,176 @@ export class MyComponent {
 }
 ```
 
+### Chords (multiple non-modifier keys)
+
+- ngx-keys supports chords composed of multiple non-modifier keys pressed simultaneously (for example `C + A`).
+- When multiple non-modifier keys are physically held down at the same time, the service uses the set of currently pressed keys plus any modifier flags to match registered shortcuts.
+- Example: register a chord with `keys: ['c','a']` and pressing and holding `c` then pressing `a` will trigger the shortcut.
+- Note: Browsers deliver separate keydown events for each physical key; the library maintains a Set of currently-down keys via `keydown`/`keyup` listeners to enable chords. This approach attempts to be robust but can be affected by browser focus changes — ensure tests in your target browsers.
+
+Example registration:
+
+```typescript
+this.keyboardService.register({
+  id: 'chord-ca',
+  keys: ['c', 'a'],
+  macKeys: ['c', 'a'],
+  action: () => console.log('Chord C+A executed'),
+  description: 'Demo chord'
+});
+```
+
+### 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:
@@ -451,4 +909,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