react-hotkeys-hook 5.0.0-0 → 5.0.0-1

package/dist/useRecordHotkeys.d.ts

@@ -1,5 +1,6 @@
 export default function useRecordHotkeys(): readonly [Set<string>, {
     readonly start: () => void;
     readonly stop: () => void;
+    readonly resetKeys: () => void;
     readonly isRecording: boolean;
 }];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-hotkeys-hook",
   "description": "React hook for handling keyboard shortcuts",
-  "version": "5.0.0-0",
+  "version": "5.0.0-1",
   "repository": {
     "type": "git",
     "url": "https://github.com/JohannesKlauss/react-keymap-hook.git"
@@ -88,7 +88,7 @@
     "@testing-library/react": "14.1.2",
     "@testing-library/user-event": "14.5.2",
     "@types/jest": "29.5.11",
-    "@types/react": "18.2.46",
+    "@types/react": "18.2.47",
     "@types/react-dom": "18.2.18",
     "@typescript-eslint/eslint-plugin": "5.60.0",
     "@typescript-eslint/parser": "5.60.0",

package/src/isHotkeyPressed.ts

@@ -2,23 +2,21 @@ import { isHotkeyModifier, mapKey } from './parseHotkeys'
 ;(() => {
   if (typeof document !== 'undefined') {
     document.addEventListener('keydown', (e) => {
-      if (e.key === undefined) {
+      if (e.code === undefined) {
         // Synthetic event (e.g., Chrome autofill). Ignore.
         return
       }
 
-      console.log('keydown', e.key, mapKey(e.key), e.key.length)
-
-      pushToCurrentlyPressedKeys([mapKey(e.key)])
+      pushToCurrentlyPressedKeys([mapKey(e.code)])
     })
 
     document.addEventListener('keyup', (e) => {
-      if (e.key === undefined) {
+      if (e.code === undefined) {
         // Synthetic event (e.g., Chrome autofill). Ignore.
         return
       }
 
-      removeFromCurrentlyPressedKeys([mapKey(e.key)])
+      removeFromCurrentlyPressedKeys([mapKey(e.code)])
     })
   }
 
@@ -36,8 +34,8 @@ export function isReadonlyArray(value: unknown): value is readonly unknown[] {
   return Array.isArray(value)
 }
 
-export function isHotkeyPressed(key: string | readonly string[], splitKey = ','): boolean {
-  const hotkeyArray = isReadonlyArray(key) ? key : key.split(splitKey)
+export function isHotkeyPressed(key: string | readonly string[], delimiter = ','): boolean {
+  const hotkeyArray = isReadonlyArray(key) ? key : key.split(delimiter)
 
   return hotkeyArray.every((hotkey) => currentlyPressedKeys.has(hotkey.trim().toLowerCase()))
 }

package/src/parseHotkeys.ts

@@ -1,6 +1,6 @@
 import { Hotkey, KeyboardModifiers } from './types'
 
-const reservedModifierKeywords = ['shift', 'alt', 'meta', 'mod', 'ctrl']
+const reservedModifierKeywords = ['shift', 'alt', 'meta', 'mod', 'ctrl', 'control']
 
 const mappedKeys: Record<string, string> = {
   esc: 'escape',
@@ -9,7 +9,6 @@ const mappedKeys: Record<string, string> = {
   right: 'arrowright',
   up: 'arrowup',
   down: 'arrowdown',
-  space: ' ',
   ShiftLeft: 'shift',
   ShiftRight: 'shift',
   AltLeft: 'alt',
@@ -30,14 +29,14 @@ export function isHotkeyModifier(key: string) {
   return reservedModifierKeywords.includes(key)
 }
 
-export function parseKeysHookInput(keys: string, splitKey = ','): string[] {
-  return keys.split(splitKey)
+export function parseKeysHookInput(keys: string, delimiter = ','): string[] {
+  return keys.toLowerCase().split(delimiter)
 }
 
-export function parseHotkey(hotkey: string, combinationKey = '+', description?: string): Hotkey {
+export function parseHotkey(hotkey: string, splitKey = '+', useKey = false, description?: string): Hotkey {
   const keys = hotkey
     .toLocaleLowerCase()
-    .split(combinationKey)
+    .split(splitKey)
     .map((k) => mapKey(k))
 
   const modifiers: KeyboardModifiers = {
@@ -46,6 +45,7 @@ export function parseHotkey(hotkey: string, combinationKey = '+', description?:
     shift: keys.includes('shift'),
     meta: keys.includes('meta'),
     mod: keys.includes('mod'),
+    useKey,
   }
 
   const singleCharKeys = keys.filter((k) => !reservedModifierKeywords.includes(k))

package/src/types.ts

@@ -12,6 +12,7 @@ export type KeyboardModifiers = {
   meta?: boolean
   shift?: boolean
   mod?: boolean
+  useKey?: boolean // Custom modifier to listen to the produced key instead of the code
 }
 
 export type Hotkey = KeyboardModifiers & {
@@ -27,19 +28,34 @@ export type HotkeyCallback = (keyboardEvent: KeyboardEvent, hotkeysEvent: Hotkey
 export type Trigger = boolean | ((keyboardEvent: KeyboardEvent, hotkeysEvent: HotkeysEvent) => boolean)
 
 export type Options = {
-  enabled?: Trigger // Main setting that determines if the hotkey is enabled or not. (Default: true)
-  enableOnFormTags?: readonly FormTags[] | boolean // Enable hotkeys on a list of tags. (Default: false)
-  enableOnContentEditable?: boolean // Enable hotkeys on tags with contentEditable props. (Default: false)
-  ignoreEventWhen?: (e: KeyboardEvent) => boolean // Ignore evenets based on a condition (Default: undefined)
-  combinationKey?: string // Character to split keys in hotkeys combinations. (Default: +)
-  splitKey?: string // Character to separate different hotkeys. (Default: ,)
-  scopes?: Scopes // Scope
-  keyup?: boolean // Trigger on keyup event? (Default: undefined)
-  keydown?: boolean // Trigger on keydown event? (Default: true)
-  preventDefault?: Trigger // Prevent default browser behavior? (Default: false)
-  description?: string // Use this option to describe what the hotkey does. (Default: undefined)
-  document?: Document // Listen to events on the document instead of the window. (Default: false)
-  ignoreModifiers?: boolean // Ignore modifiers when matching hotkeys. (Default: false)
+  // Main setting that determines if the hotkey is enabled or not. (Default: true)
+  enabled?: Trigger
+  // Enable hotkeys on a list of tags. (Default: false)
+  enableOnFormTags?: readonly FormTags[] | boolean
+  // Enable hotkeys on tags with contentEditable props. (Default: false)
+  enableOnContentEditable?: boolean
+  // Ignore evenets based on a condition (Default: undefined)
+  ignoreEventWhen?: (e: KeyboardEvent) => boolean
+  // Character to split keys in hotkeys combinations. (Default: +)
+  splitKey?: string
+  // Character to separate different hotkeys. (Default: ,)
+  delimiter?: string
+  // Scope of the hotkey. (Default: undefined)
+  scopes?: Scopes
+  // Trigger on keyup event? (Default: undefined)
+  keyup?: boolean
+  // Trigger on keydown event? (Default: true)
+  keydown?: boolean
+  // Prevent default browser behavior? (Default: false)
+  preventDefault?: Trigger
+  // Use this option to describe what the hotkey does. (Default: undefined)
+  description?: string
+  // Listen to events on the document instead of the window. (Default: false)
+  document?: Document
+  // Ignore modifiers when matching hotkeys. (Default: false)
+  ignoreModifiers?: boolean
+  // Listen to the produced key instead of the code. (Default: false)
+  useKey?: boolean
 }
 
 export type OptionsOrDependencyArray = Options | DependencyList

package/src/useHotkeys.ts

@@ -36,7 +36,7 @@ export default function useHotkeys<T extends HTMLElement>(
     : !(dependencies instanceof Array)
     ? (dependencies as Options)
     : undefined
-  const _keys: string = isReadonlyArray(keys) ? keys.join(_options?.splitKey) : keys
+  const _keys: string = isReadonlyArray(keys) ? keys.join(_options?.delimiter) : keys
   const _deps: DependencyList | undefined =
     options instanceof Array ? options : dependencies instanceof Array ? dependencies : undefined
 
@@ -83,8 +83,8 @@ export default function useHotkeys<T extends HTMLElement>(
         return
       }
 
-      parseKeysHookInput(_keys, memoisedOptions?.splitKey).forEach((key) => {
-        const hotkey = parseHotkey(key, memoisedOptions?.combinationKey)
+      parseKeysHookInput(_keys, memoisedOptions?.delimiter).forEach((key) => {
+        const hotkey = parseHotkey(key, memoisedOptions?.splitKey, memoisedOptions?.useKey)
 
         if (isHotkeyMatchingKeyboardEvent(e, hotkey, memoisedOptions?.ignoreModifiers) || hotkey.keys?.includes('*')) {
           if (memoisedOptions?.ignoreEventWhen?.(e)) {
@@ -114,12 +114,12 @@ export default function useHotkeys<T extends HTMLElement>(
     }
 
     const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === undefined) {
+      if (event.code === undefined) {
         // Synthetic event (e.g., Chrome autofill).  Ignore.
         return
       }
 
-      pushToCurrentlyPressedKeys(mapKey(event.key))
+      pushToCurrentlyPressedKeys(mapKey(event.code))
 
       if ((memoisedOptions?.keydown === undefined && memoisedOptions?.keyup !== true) || memoisedOptions?.keydown) {
         listener(event)
@@ -127,12 +127,12 @@ export default function useHotkeys<T extends HTMLElement>(
     }
 
     const handleKeyUp = (event: KeyboardEvent) => {
-      if (event.key === undefined) {
+      if (event.code === undefined) {
         // Synthetic event (e.g., Chrome autofill).  Ignore.
         return
       }
 
-      removeFromCurrentlyPressedKeys(mapKey(event.key))
+      removeFromCurrentlyPressedKeys(mapKey(event.code))
 
       hasTriggeredRef.current = false
 
@@ -149,8 +149,10 @@ export default function useHotkeys<T extends HTMLElement>(
     domNode.addEventListener('keydown', handleKeyDown)
 
     if (proxy) {
-      parseKeysHookInput(_keys, memoisedOptions?.splitKey).forEach((key) =>
-        proxy.addHotkey(parseHotkey(key, memoisedOptions?.combinationKey, memoisedOptions?.description))
+      parseKeysHookInput(_keys, memoisedOptions?.delimiter).forEach((key) =>
+        proxy.addHotkey(
+          parseHotkey(key, memoisedOptions?.splitKey, memoisedOptions?.useKey, memoisedOptions?.description)
+        )
       )
     }
 
@@ -161,8 +163,10 @@ export default function useHotkeys<T extends HTMLElement>(
       domNode.removeEventListener('keydown', handleKeyDown)
 
       if (proxy) {
-        parseKeysHookInput(_keys, memoisedOptions?.splitKey).forEach((key) =>
-          proxy.removeHotkey(parseHotkey(key, memoisedOptions?.combinationKey, memoisedOptions?.description))
+        parseKeysHookInput(_keys, memoisedOptions?.delimiter).forEach((key) =>
+          proxy.removeHotkey(
+            parseHotkey(key, memoisedOptions?.splitKey, memoisedOptions?.useKey, memoisedOptions?.description)
+          )
         )
       }
     }

package/src/useRecordHotkeys.ts

@@ -6,7 +6,7 @@ export default function useRecordHotkeys() {
   const [isRecording, setIsRecording] = useState(false)
 
   const handler = useCallback((event: KeyboardEvent) => {
-    if (event.key === undefined) {
+    if (event.code === undefined) {
       // Synthetic event (e.g., Chrome autofill).  Ignore.
       return
     }
@@ -17,7 +17,7 @@ export default function useRecordHotkeys() {
     setKeys((prev) => {
       const newKeys = new Set(prev)
 
-      newKeys.add(mapKey(event.key))
+      newKeys.add(mapKey(event.code))
 
       return newKeys
     })
@@ -43,5 +43,9 @@ export default function useRecordHotkeys() {
     }
   }, [handler, stop])
 
-  return [keys, { start, stop, isRecording }] as const
+  const resetKeys = useCallback(() => {
+    setKeys(new Set<string>())
+  }, [])
+
+  return [keys, { start, stop, resetKeys, isRecording }] as const
 }

package/src/validators.ts

@@ -1,5 +1,6 @@
 import { FormTags, Hotkey, Scopes, Trigger } from './types'
 import { isHotkeyPressed, isReadonlyArray } from './isHotkeyPressed'
+import { mapKey } from './parseHotkeys'
 
 export function maybePreventDefault(e: KeyboardEvent, hotkey: Hotkey, preventDefault?: Trigger): void {
   if ((typeof preventDefault === 'function' && preventDefault(e, hotkey)) || preventDefault === true) {
@@ -31,7 +32,7 @@ export function isHotkeyEnabledOnTag(
     )
   }
 
-  return Boolean(targetTagName && enabledOnTags && enabledOnTags === true)
+  return Boolean(targetTagName && enabledOnTags && enabledOnTags)
 }
 
 export function isScopeActive(activeScopes: string[], scopes?: Scopes): boolean {
@@ -51,25 +52,29 @@ export function isScopeActive(activeScopes: string[], scopes?: Scopes): boolean
 }
 
 export const isHotkeyMatchingKeyboardEvent = (e: KeyboardEvent, hotkey: Hotkey, ignoreModifiers = false): boolean => {
-  const { alt, meta, mod, shift, ctrl, keys } = hotkey
-  const { key: pressedKeyUppercase, ctrlKey, metaKey, shiftKey, altKey } = e
+  const { alt, meta, mod, shift, ctrl, keys, useKey } = hotkey
+  const { code, key: producedKey, ctrlKey, metaKey, shiftKey, altKey } = e
 
-  const pressedKey = pressedKeyUppercase.toLowerCase()
+  const mappedCode = mapKey(code)
+
+  if (useKey && keys?.length === 1 && keys.includes(producedKey)) {
+    return true
+  }
 
   if (
-    !keys?.includes(pressedKey) &&
-    !['ctrl', 'control', 'unknown', 'meta', 'alt', 'shift', 'os'].includes(pressedKey)
+    !keys?.includes(mappedCode) &&
+    !['ctrl', 'control', 'unknown', 'meta', 'alt', 'shift', 'os'].includes(mappedCode)
   ) {
     return false
   }
 
   if (!ignoreModifiers) {
     // We check the pressed keys for compatibility with the keyup event. In keyup events the modifier flags are not set.
-    if (alt === !altKey && pressedKey !== 'alt') {
+    if (alt !== altKey && mappedCode !== 'alt') {
       return false
     }
 
-    if (shift === !shiftKey && pressedKey !== 'shift') {
+    if (shift !== shiftKey && mappedCode !== 'shift') {
       return false
     }
 
@@ -79,11 +84,11 @@ export const isHotkeyMatchingKeyboardEvent = (e: KeyboardEvent, hotkey: Hotkey,
         return false
       }
     } else {
-      if (meta === !metaKey && pressedKey !== 'meta' && pressedKey !== 'os') {
+      if (meta !== metaKey && mappedCode !== 'meta' && mappedCode !== 'os') {
         return false
       }
 
-      if (ctrl === !ctrlKey && pressedKey !== 'ctrl' && pressedKey !== 'control') {
+      if (ctrl !== ctrlKey && mappedCode !== 'ctrl' && mappedCode !== 'control') {
         return false
       }
     }
@@ -91,7 +96,7 @@ export const isHotkeyMatchingKeyboardEvent = (e: KeyboardEvent, hotkey: Hotkey,
 
   // All modifiers are correct, now check the key
   // If the key is set, we check for the key
-  if (keys && keys.length === 1 && keys.includes(pressedKey)) {
+  if (keys && keys.length === 1 && keys.includes(mappedCode)) {
     return true
   } else if (keys) {
     // Check if all keys are present in pressedDownKeys set