feat(useHotKey): add new option allowInModal

This allows to also trigger hotkeys in modals.

Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>

Author: susnux

docs/composables/useHotKey.md

@@ -22,13 +22,15 @@ where:
   See [KeyboardEvent.key Value column](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) for possible values
 - `callback`: a function to be called when the key is pressed. Before called, it will be checked whether keyboard shortcuts are disabled, or interactive element is currently focused, or whether options should be applied
 - `options`: options to be applied to the shortcut:
-  - `push`: whether the event should be triggered on both keydown and keyup (default: `false`)
-  - `prevent`: prevents the default action of the event (default: `false`)
-  - `stop`: prevents propagation of the event in the capturing and bubbling phases (default: `false`)
   - `ctrl`: whether the Ctrl key (Cmd key on MacOS) should be pressed (default: `false`)
   - `alt`: whether the Alt key should be pressed (default: `false`)
   - `shift`: whether the Shift key should be pressed (should be explicitly defined as `true`|`false` if needed)
+  - `push`: whether the event should be triggered on both keydown and keyup (default: `false`)
+  - `prevent`: prevents the default action of the event (default: `false`)
+  - `stop`: prevents propagation of the event in the capturing and bubbling phases (default: `false`)
   - `caseSensitive`: whether specific case should be listened, e.g. only 'd' and not 'D' (default: `false`)
+  - `allowInModal`: whether key strokes should also be handled while a modal is shown (default: `false`)
+    By default this is disabled to not trigger hotkeys of an app while the app is overlaid by a modal.
 - `stopCallback`: a callback to stop listening to the event
 
 ### Playground

src/components/NcModal/NcModal.vue

@@ -233,7 +233,7 @@ useHotKey('Escape', () => {
 	if (trapStack.at(-1) === focusTrap) {
 		close()
 	}
-})
+}, { allowInModal: true })
 
 useHotKey(['ArrowLeft', 'ArrowRight'], (event) => {
 	// Ignore arrow navigation, if there is a current focus outside the modal.
@@ -248,7 +248,7 @@ useHotKey(['ArrowLeft', 'ArrowRight'], (event) => {
 	} else {
 		nextSlide()
 	}
-})
+}, { allowInModal: true })
 
 // for developers we should add a warning if used with invalid props combination
 onMounted(() => {

src/composables/useHotKey/index.ts

@@ -39,6 +39,14 @@ export interface UseHotKeyOptions {
 	 * Undefined will be handled the same as `false` and will only run the callback if the 'alt' key is NOT pressed.
 	 */
 	alt?: boolean
+
+	/**
+	 * Allow hot key to trigger even if a modal/dialog is open.
+	 * By default this is disabled to not trigger hot keys in apps if they are overlaid by a modal/dialog.
+	 *
+	 * @default false
+	 */
+	allowInModal?: boolean
 }
 
 /**
@@ -47,17 +55,23 @@ export interface UseHotKeyOptions {
  *
  * @todo Discuss if we should abort on another interactive elements (button, a, e.t.c)
  *
- * @param event keyboard event
+ * @param event - The keyboard event
+ * @param options - The hot key options
  * @return Whether it should prevent callback
  */
-function shouldIgnoreEvent(event: KeyboardEvent): boolean {
+function shouldIgnoreEvent(event: KeyboardEvent, options: UseHotKeyOptions): boolean {
 	if (!(event.target instanceof HTMLElement)
 		|| event.target instanceof HTMLInputElement
 		|| event.target instanceof HTMLTextAreaElement
 		|| event.target instanceof HTMLSelectElement
 		|| event.target.isContentEditable) {
 		return true
 	}
+
+	if (options.allowInModal) {
+		return false
+	}
+
 	/** Abort if any modal/dialog opened */
 	return document.getElementsByClassName('modal-mask').length !== 0
 }
@@ -90,7 +104,7 @@ function eventHandler(callback: KeyboardEventHandler, options: UseHotKeyOptions)
 			 * option should be explicitly defined
 			 */
 			return
-		} else if (shouldIgnoreEvent(event)) {
+		} else if (shouldIgnoreEvent(event, options)) {
 			// Keyboard shortcuts are disabled, because active element assumes input
 			return
 		}

tests/unit/composables/useHotKey.spec.js

@@ -19,6 +19,7 @@ describe('useHotKey', () => {
 
 	afterEach(() => {
 		mockCallback.mockReset()
+		document.body.innerHTML = ''
 	})
 
 	it('should register listener and invoke callback', () => {
@@ -39,6 +40,30 @@ describe('useHotKey', () => {
 		expect(mockCallback).not.toHaveBeenCalled()
 	})
 
+	it('should not invoke callback by default, when a modal is shown', () => {
+		const modal = document.createElement('div')
+		modal.className = 'modal-mask'
+		document.body.appendChild(modal)
+
+		const stop = useHotKey(true, mockCallback)
+		triggerKeyDown({ key: 'a', code: 'KeyA' })
+		stop()
+
+		expect(mockCallback).not.toHaveBeenCalled()
+	})
+
+	it('should invoke callback if modals are allowed, when a modal is shown', () => {
+		const modal = document.createElement('div')
+		modal.className = 'modal-mask'
+		document.body.appendChild(modal)
+
+		const stop = useHotKey(true, mockCallback, { allowInModal: true })
+		triggerKeyDown({ key: 'a', code: 'KeyA' })
+		stop()
+
+		expect(mockCallback).toHaveBeenCalled()
+	})
+
 	describe('options', () => {
 		it('should accept array of keys and invoke callback for all of them', () => {
 			const stop = useHotKey(['a', 'b'], mockCallback)