fixup: simplify composable

Signed-off-by: Maksim Sukharev <[email protected]>

docs/composables/usekeystroke.md → docs/composables/useHotKey.md

@@ -10,19 +10,17 @@ It respects Nextcloud's value of ```OCP.Accessibility.disableKeyboardShortcuts``
 
 ### Usage
 ```js static
-import { useKeystroke } from '@nextcloud/vue/dist/Composables/useKeyStroke/index.js'
+import { useHotKey } from '@nextcloud/vue/dist/Composables/useHotKey/index.js'
 
-const stop = useKeystroke(keys, callback, modifiers)
+const stop = useHotKey(key, callback, modifiers)
 ```
 where:
-- `keys`: string / array of strings representing the key or keys to listen to (`true` to listen to any key)
+- `key`: string representing the keyboard key to listen to
 
 	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 modifiers should be applied
 - `modifiers`: modifiers to be applied to the shortcut:
-  - `target`: the HTML element (or Vue ref) to listen to the event (`document` by default)
   - `push`: whether the event should be triggered on both keydown and keyup
-  - `press`: whether the event should be triggered, continuously generating events
   - `ctrl`: whether the Ctrl key should be pressed
   - `alt`: whether the Alt key should be pressed
   - `shift`: whether the Shift key should be pressed
@@ -31,18 +29,18 @@ where:
 - `stop`: a function to stop listening to the event
 
 ### Playground
+
 ```vue
 
 <template>
 	<div class="container">
 		<p class="description">Press <kbd>W</kbd> <kbd>S</kbd> <kbd>A</kbd> <kbd>D</kbd> keys to move the ball</p>
-		<p class="description">Hold <kbd>D</kbd> key to continue generate events</p>
 		<div class="square">
 			<div class="circle" :style="{ left: `${circleX}px`, top: `${circleY}px` }"></div>
 		</div>
 		<p class="description">
 			Push <kbd>M</kbd> to highlight the red area
-			<button @click="stop" >Stop listen to this event</button>
+			<button @click="stop">Stop listen to this event</button>
 		</p>
 		<div ref="push"
 			 class="push-square"
@@ -54,7 +52,7 @@ where:
 
 <script>
 	import { ref } from 'vue'
-	import { useKeyStroke } from '../../src/composables/useKeyStroke/index.js'
+	import { useHotKey } from '../../src/composables/useHotKey/index.js'
 
 	export default {
 		setup() {
@@ -78,11 +76,11 @@ where:
 				highlighted.value = !highlighted.value
 			}
 
-			useKeyStroke('w', moveUp)
-			useKeyStroke('s', moveDown)
-			useKeyStroke('a', moveLeft)
-			useKeyStroke('d', moveRight, { press: true })
-			const stop = useKeyStroke('m', toggleHighlighted, { push: true })
+			useHotKey('w', moveUp)
+			useHotKey('s', moveDown)
+			useHotKey('a', moveLeft)
+			useHotKey('d', moveRight)
+			const stop = useHotKey('m', toggleHighlighted, { push: true })
 
 			return {
 				circleX,
@@ -93,7 +91,7 @@ where:
 		},
 
 		created() {
-			useKeyStroke('f', this.focusInput, { ctrl: true, stop: true, prevent: true })
+			useHotKey('f', this.focusInput, { ctrl: true, stop: true, prevent: true })
 		},
 
 		methods: {

src/composables/index.js

@@ -6,4 +6,4 @@
 export * from './useIsFullscreen/index.js'
 export * from './useIsMobile/index.js'
 export * from './useFormatDateTime.ts'
-export * from './useKeyStroke/index.js'
+export * from './useHotKey/index.js'

src/composables/useHotKey/index.js

@@ -0,0 +1,81 @@
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { onKeyStroke } from '@vueuse/core'
+
+const disableKeyboardShortcuts = window.OCP?.Accessibility?.disableKeyboardShortcuts?.()
+
+/**
+ * Check if event target (active element) is editable (allows input from keyboard) or NcModal is open
+ * If true, a hot key should not trigger the callback
+ * TODO discuss if we should abort on another interactive elements (button, a, e.t.c)
+ *
+ * @param {KeyboardEvent} event keyboard event
+ * @return {boolean} whether it should prevent callback
+ */
+function shouldIgnoreEvent(event) {
+	if (event.target instanceof HTMLInputElement
+		|| event.target instanceof HTMLTextAreaElement
+		|| event.target instanceof HTMLSelectElement
+		|| event.target?.isContentEditable) {
+		return true
+	}
+	/** Abort if any modal/dialog opened */
+	return document.getElementsByClassName('modal-mask').length !== 0
+}
+
+const eventHandler = (callback, options) => (event) => {
+	if (!!options.ctrl !== event.ctrlKey) {
+		// Ctrl is required and not pressed, or the opposite
+		return
+	} else if (!!options.alt !== event.altKey) {
+		// Alt is required and not pressed, or the opposite
+		return
+	} else if (!!options.shift !== event.shiftKey) {
+		// Shift is required and not pressed, or the opposite
+		return
+	} else if (shouldIgnoreEvent(event)) {
+		// Keyboard shortcuts are disabled, because active element assumes input
+		return
+	}
+
+	if (options.prevent) {
+		event.preventDefault()
+	}
+	if (options.stop) {
+		event.stopPropagation()
+	}
+	callback(event)
+}
+
+/**
+ * @param {string} key - keyboard key or keys to listen to
+ * @param {Function} callback - callback function
+ * @param {object} options - composable options
+ * @see docs/composables/usekeystroke.md
+ */
+export function useHotKey(key, callback = () => {}, options = {}) {
+	if (disableKeyboardShortcuts) {
+		// Keyboard shortcuts are disabled
+		return () => {}
+	}
+
+	const stopKeyDown = onKeyStroke(key, eventHandler(callback, options), {
+		eventName: 'keydown',
+		dedupe: true,
+		passive: !options.prevent,
+	})
+
+	const stopKeyUp = options.push
+		? onKeyStroke(key, eventHandler(callback, options), {
+			eventName: 'keyup',
+			passive: !options.prevent,
+		})
+		: () => {}
+
+	return () => {
+		stopKeyDown()
+		stopKeyUp()
+	}
+}

styleguide.config.js

@@ -145,8 +145,8 @@ module.exports = async () => {
 				sectionDepth: 1,
 				sections: [
 					{
-						name: 'useKeyStroke',
-						content: 'docs/composables/usekeystroke.md',
+						name: 'useHotKey',
+						content: 'docs/composables/useHotKey.md',
 					},
 				],
 			},