feat: adds pausing and resuming to the hotkey service

README.md

@@ -210,6 +210,19 @@ this.hotkeys.removeShortcuts('meta.a');
 this.hotkeys.removeShortcuts(['meta.1', 'meta.2']);
 ```
 
+### `pauseShortcuts and resumeShortcuts`
+
+Pause the handling of all shortcuts. This is especially useful to prevent hotkeys from firing when a modal or sidebar is open.
+
+```ts
+// hotkey subscriptions won't emmit, and hotkeys callbacks won't be called
+this.hotkeys.pauseShortcuts();
+// hotkeys will work again
+this.hotkeys.resumeShortcuts();
+// get the current state of the hotkeys
+this.hotkeys.isPaused();
+```
+
 ### `setSequenceDebounce`
 
 Set the number of milliseconds to debounce a sequence of keys

projects/ngneat/hotkeys/src/lib/hotkeys.service.ts

@@ -1,5 +1,5 @@
 import { DOCUMENT } from '@angular/common';
-import { Inject, Injectable } from '@angular/core';
+import { computed, Inject, Injectable, signal } from '@angular/core';
 import { EventManager } from '@angular/platform-browser';
 import { EMPTY, fromEvent, Observable, of, Subject, Subscriber, Subscription } from 'rxjs';
 import { debounceTime, filter, finalize, mergeMap, takeUntil, tap } from 'rxjs/operators';
@@ -55,6 +55,10 @@ export class HotkeysService {
   private sequenceMaps = new Map<HTMLElement, SequenceSummary>();
   private sequenceDebounce: number = 250;
 
+  private _isPaused = signal(false);
+  // readonly interface for the isPaused value
+  isPaused = computed(() => this._isPaused());
+
   constructor(
     private eventManager: EventManager,
     @Inject(DOCUMENT) private document: Document,
@@ -152,7 +156,12 @@ export class HotkeysService {
     return getSequenceCompleteObserver().pipe(
       takeUntil<Hotkey>(this.dispose.pipe(filter((v) => v === normalizedKeys))),
       filter((hotkey) => !this.targetIsExcluded(hotkey.allowIn)),
-      tap((hotkey) => this.callbacks.forEach((cb) => cb(hotkey, normalizedKeys, hotkey.element))),
+      filter((hotkey) => !this._isPaused()),
+      tap((hotkey) => {
+        if (!this._isPaused()) {
+          this.callbacks.forEach((cb) => cb(hotkey, normalizedKeys, hotkey.element));
+        }
+      }),
       finalize(() => this.removeShortcuts(normalizedKeys)),
     );
   }
@@ -182,8 +191,10 @@ export class HotkeysService {
           e.preventDefault();
         }
 
-        this.callbacks.forEach((cb) => cb(e, normalizedKeys, hotkey.element));
-        observer.next(e);
+        if (!this._isPaused()) {
+          this.callbacks.forEach((cb) => cb(e, normalizedKeys, hotkey.element));
+          observer.next(e);
+        }
       };
 
       const dispose = this.eventManager.addEventListener(
@@ -196,7 +207,10 @@ export class HotkeysService {
         this.hotkeys.delete(normalizedKeys);
         dispose();
       };
-    }).pipe(takeUntil<KeyboardEvent>(this.dispose.pipe(filter((v) => v === normalizedKeys))));
+    }).pipe(
+      filter(() => !this._isPaused()),
+      takeUntil<KeyboardEvent>(this.dispose.pipe(filter((v) => v === normalizedKeys))),
+    );
   }
 
   removeShortcuts(hotkeys: string | string[]): void {
@@ -263,4 +277,12 @@ export class HotkeysService {
 
     return isExcluded;
   }
+
+  pauseHotkeys() {
+    this._isPaused.set(true);
+  }
+
+  resumeHotkeys() {
+    this._isPaused.set(false);
+  }
 }

projects/ngneat/hotkeys/src/lib/tests/hotkeys.directive.spec.ts

@@ -16,6 +16,38 @@ describe('Directive: Hotkeys', () => {
     spectator.fixture.detectChanges();
   });
 
+  it('should not trigger hotkey output if hotkeys are paused, should trigger again when resumed', () => {
+    spectator = createDirective(`<div [hotkeys]="'a'"></div>`);
+
+    const hotkeysService = spectator.inject(HotkeysService);
+    hotkeysService.pauseHotkeys();
+    const spyFcn = createSpy('subscribe', (e) => {});
+    spectator.output('hotkey').subscribe(spyFcn);
+    spectator.fixture.detectChanges();
+    spectator.dispatchKeyboardEvent(spectator.element, 'keydown', 'a');
+    expect(spyFcn).not.toHaveBeenCalled();
+
+    hotkeysService.resumeHotkeys();
+    spectator.dispatchKeyboardEvent(spectator.element, 'keydown', 'a');
+    expect(spyFcn).toHaveBeenCalled();
+  });
+
+  it('should not trigger global hotkey output if hotkeys are paused, should trigger again when resumed', () => {
+    spectator = createDirective(`<div [hotkeys]="'a'" isGlobal></div>`);
+
+    const hotkeysService = spectator.inject(HotkeysService);
+    hotkeysService.pauseHotkeys();
+    const spyFcn = createSpy('subscribe', (e) => {});
+    spectator.output('hotkey').subscribe(spyFcn);
+    spectator.fixture.detectChanges();
+    spectator.dispatchKeyboardEvent(document.documentElement, 'keydown', 'a');
+    expect(spyFcn).not.toHaveBeenCalled();
+
+    hotkeysService.resumeHotkeys();
+    spectator.dispatchKeyboardEvent(document.documentElement, 'keydown', 'a');
+    expect(spyFcn).toHaveBeenCalled();
+  });
+
   const shouldIgnoreOnInputTest = (directiveExtras?: string) => {
     const spyFcn = createSpy('subscribe', (...args) => {});
     spectator = createDirective(`<div [hotkeys]="'a'" ${directiveExtras ?? ''}><input></div>`);
@@ -169,6 +201,60 @@ describe('Directive: Sequence Hotkeys', () => {
     return run();
   });
 
+  it('should not trigger sequence hotkey if hotkeys are paused, should trigger again when resumed', () => {
+    const run = async () => {
+      // * Need to space out time to prevent other test keystrokes from interfering with sequence
+      await sleep(250);
+      const spyFcn = createSpy('subscribe', (...args) => {});
+      spectator = createDirective(`<div [hotkeys]="'g>m'" [isSequence]="true"></div>`);
+      const hotkeysService = spectator.inject(HotkeysService);
+
+      hotkeysService.pauseHotkeys();
+      spectator.output('hotkey').subscribe(spyFcn);
+      spectator.dispatchKeyboardEvent(spectator.element, 'keydown', 'g');
+      spectator.dispatchKeyboardEvent(spectator.element, 'keydown', 'm');
+      await sleep(250);
+      spectator.fixture.detectChanges();
+      expect(spyFcn).not.toHaveBeenCalled();
+
+      hotkeysService.resumeHotkeys();
+      spectator.dispatchKeyboardEvent(spectator.element, 'keydown', 'g');
+      spectator.dispatchKeyboardEvent(spectator.element, 'keydown', 'm');
+      await sleep(250);
+      spectator.fixture.detectChanges();
+      expect(spyFcn).toHaveBeenCalled();
+    };
+
+    return run();
+  });
+
+  it('should not trigger global sequence hotkey if hotkeys are paused, should trigger again when resumed', () => {
+    const run = async () => {
+      // * Need to space out time to prevent other test keystrokes from interfering with sequence
+      await sleep(250);
+      const spyFcn = createSpy('subscribe', (...args) => {});
+      spectator = createDirective(`<div [hotkeys]="'g>m'" [isSequence]="true" isGlobal></div>`);
+      const hotkeysService = spectator.inject(HotkeysService);
+
+      hotkeysService.pauseHotkeys();
+      spectator.output('hotkey').subscribe(spyFcn);
+      spectator.dispatchKeyboardEvent(document.documentElement, 'keydown', 'g');
+      spectator.dispatchKeyboardEvent(document.documentElement, 'keydown', 'm');
+      await sleep(250);
+      spectator.fixture.detectChanges();
+      expect(spyFcn).not.toHaveBeenCalled();
+
+      hotkeysService.resumeHotkeys();
+      spectator.dispatchKeyboardEvent(document.documentElement, 'keydown', 'g');
+      spectator.dispatchKeyboardEvent(document.documentElement, 'keydown', 'm');
+      await sleep(250);
+      spectator.fixture.detectChanges();
+      expect(spyFcn).toHaveBeenCalled();
+    };
+
+    return run();
+  });
+
   const shouldIgnoreOnInputTest = async (directiveExtras?: string) => {
     // * Need to space out time to prevent other test keystrokes from interfering with sequence
     await sleep(250);

projects/ngneat/hotkeys/src/lib/tests/hotkeys.service.spec.ts

@@ -45,6 +45,17 @@ describe('Service: Hotkeys', () => {
     expect(spyFcn).toHaveBeenCalled();
   });
 
+  it('should not listen to keydown if hotkeys are paused, should listen again when resumed', () => {
+    const spyFcn = createSpy('subscribe', (e) => {});
+    spectator.service.addShortcut({ keys: 'a' }).subscribe(spyFcn);
+    spectator.service.pauseHotkeys();
+    fakeKeyboardPress('a');
+    expect(spyFcn).not.toHaveBeenCalled();
+    spectator.service.resumeHotkeys();
+    fakeKeyboardPress('a');
+    expect(spyFcn).toHaveBeenCalled();
+  });
+
   it('should listen to keyup', () => {
     const spyFcn = createSpy('subscribe', (e) => {});
     spectator.service.addShortcut({ keys: 'a', trigger: 'keyup' }).subscribe(spyFcn);
@@ -60,6 +71,20 @@ describe('Service: Hotkeys', () => {
     expect(spyFcn).toHaveBeenCalled();
   });
 
+  it('should not call callback when hotkeys are paused, should call again when resumed', () => {
+    const spyFcn = createSpy('subscribe', (...args) => {});
+    spectator.service.addShortcut({ keys: 'a' }).subscribe();
+    spectator.service.onShortcut(spyFcn);
+
+    spectator.service.pauseHotkeys();
+    fakeKeyboardPress('a');
+    expect(spyFcn).not.toHaveBeenCalled();
+
+    spectator.service.resumeHotkeys();
+    fakeKeyboardPress('a');
+    expect(spyFcn).toHaveBeenCalled();
+  });
+
   it('should honor target element', () => {
     const spyFcn = createSpy('subscribe', (...args) => {});
     spectator.service.addShortcut({ keys: 'a', element: document.body }).subscribe(spyFcn);

src/app/app.component.css

@@ -0,0 +1,14 @@
+.container {
+  padding: 2rem;
+  max-width: 400px;
+  margin: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.grid-container {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 1rem;
+}

src/app/app.component.html

@@ -1,4 +1,4 @@
-<div #container>
+<div #container class="container">
   <input
     #input
     placeholder="meta.a"
@@ -27,4 +27,10 @@
     [hotkeysOptions]="{ allowIn: ['INPUT'] }"
     [isSequence]="true"
   />
+
+  <div class="grid-container">
+    <button (click)="pauseHotkeys()">pause hotkeys</button>
+    <button (click)="resumeHotkeys()">resume hotkeys</button>
+  </div>
+  <span> Hotkeys are {{ isPaused() ? 'paused' : 'active' }} </span>
 </div>

src/app/app.component.ts

@@ -16,6 +16,7 @@ export class AppComponent implements AfterViewInit {
   input2 = viewChild<ElementRef<HTMLElement>>('input2');
   input3 = viewChild<ElementRef<HTMLElement>>('input3');
   container = viewChild<ElementRef<HTMLElement>>('container');
+  isPaused = this.hotkeys.isPaused;
 
   ngAfterViewInit(): void {
     this.hotkeys.onShortcut((event, keys) => console.log(keys));
@@ -101,4 +102,12 @@ export class AppComponent implements AfterViewInit {
   handleHotkey(e: KeyboardEvent) {
     console.log('New document hotkey', e);
   }
+
+  pauseHotkeys() {
+    this.hotkeys.pauseHotkeys();
+  }
+
+  resumeHotkeys() {
+    this.hotkeys.resumeHotkeys();
+  }
 }