Merge pull request #5 from humanlayer/publish-humanlayer

fix: macOS Option key hotkey matching + comma normalization

Author: K-Mistele

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@humanlayer/react-hotkeys-hook",
   "description": "React hook for handling keyboard shortcuts (HumanLayer fork)",
-  "version": "5.3.0",
+  "version": "5.3.1",
   "sideEffects": false,
   "repository": {
     "type": "git",

packages/react-hotkeys-hook/package.json

@@ -1,6 +1,6 @@
 {
-  "name": "react-hotkeys-hook",
-  "version": "5.3.0",
+  "name": "@humanlayer/react-hotkeys-hook",
+  "version": "5.3.1",
   "type": "module",
   "scripts": {
     "dev": "vite",

packages/react-hotkeys-hook/src/lib/validators.ts

@@ -2,6 +2,15 @@ import type { FormTags, Hotkey, Scopes, Trigger } from './types'
 import { isHotkeyPressed, isReadonlyArray } from './isHotkeyPressed'
 import { mapCode } from './parseHotkeys'
 
+// macOS Option key transforms letters to Unicode characters (US keyboard layout)
+// Reverse map to recover intended letter - same approach as GitHub's hotkey library
+const macOSOptionKeyReverseMap: Record<string, string> = {
+  'å': 'a', '∫': 'b', 'ç': 'c', '∂': 'd', '´': 'e', 'ƒ': 'f', '©': 'g',
+  '˙': 'h', 'ˆ': 'i', '∆': 'j', '˚': 'k', '¬': 'l', 'µ': 'm', '˜': 'n',
+  'ø': 'o', 'π': 'p', 'œ': 'q', '®': 'r', 'ß': 's', '†': 't', '¨': 'u',
+  '√': 'v', '∑': 'w', '≈': 'x', '¥': 'y', 'Ω': 'z'
+}
+
 export function maybePreventDefault(e: KeyboardEvent, hotkey: Hotkey, preventDefault?: Trigger): void {
   if ((typeof preventDefault === 'function' && preventDefault(e, hotkey)) || preventDefault === true) {
     e.preventDefault()
@@ -127,8 +136,24 @@ export const isHotkeyMatchingKeyboardEvent = (e: KeyboardEvent, hotkey: Hotkey,
   // If useKey is set, match against the produced key value instead of the key code
   // When useKey is true, we ONLY match produced keys — never fall through to code-based matching
   if (useKey) {
-    // Normalize produced key: map ' ' to 'space' so hotkey string 'space' works with useKey
-    const normalizedKey = producedKey === ' ' ? 'space' : producedKey.toLowerCase()
+    // macOS Option key transforms event.key to Unicode characters (opt+y → '¥')
+    // Try both: physical key (event.code) AND reverse-mapped Unicode for layout support
+    if (altKey) {
+      const reverseMappedKey = macOSOptionKeyReverseMap[producedKey] || producedKey.toLowerCase()
+      if (keys?.length === 1) {
+        return keys.includes(mappedCode) || keys.includes(reverseMappedKey)
+      }
+      if (keys && keys.length > 0) {
+        return isHotkeyPressed(keys.map((k) => k.toLowerCase()))
+      }
+      return !keys || keys.length === 0
+    }
+
+    // Non-alt path: use event.key (layout-aware matching)
+    // Normalize produced key: map ' ' to 'space', ',' to 'comma'
+    const normalizedKey = producedKey === ' ' ? 'space'
+                        : producedKey === ',' ? 'comma'
+                        : producedKey.toLowerCase()
     if (keys?.length === 1) {
       return keys.includes(normalizedKey)
     }

packages/react-hotkeys-hook/src/test/useHotkeys.test.tsx

@@ -1636,6 +1636,77 @@ test('Should match mixed-case keys like PageUp with useKey option', async () =>
   expect(callback).toHaveBeenCalledTimes(2)
 })
 
+test('Should match meta+comma when Cmd+, is pressed', async () => {
+  const callback = vi.fn()
+
+  renderHook(() => useHotkeys('meta+comma', callback))
+
+  document.dispatchEvent(
+    new KeyboardEvent('keydown', {
+      key: ',',
+      code: 'Comma',
+      metaKey: true,
+      bubbles: true,
+    })
+  )
+
+  expect(callback).toHaveBeenCalledTimes(1)
+})
+
+test('Should match alt+y when Option+Y produces Unicode character on macOS (QWERTY)', async () => {
+  const callback = vi.fn()
+
+  renderHook(() => useHotkeys('alt+y', callback))
+
+  // QWERTY: physical KeyY, event.key is '¥'
+  document.dispatchEvent(
+    new KeyboardEvent('keydown', {
+      key: '¥',
+      code: 'KeyY',
+      altKey: true,
+      bubbles: true,
+    })
+  )
+
+  expect(callback).toHaveBeenCalledTimes(1)
+})
+
+test('Should match alt+y via Unicode reverse-mapping on Dvorak', async () => {
+  const callback = vi.fn()
+
+  renderHook(() => useHotkeys('alt+y', callback))
+
+  // Dvorak: physical key is NOT KeyY, but event.key is '¥' (Unicode for opt+y on US layout)
+  // The reverse-mapping detects '¥' → 'y' and matches
+  document.dispatchEvent(
+    new KeyboardEvent('keydown', {
+      key: '¥',
+      code: 'KeyT', // Different physical key
+      altKey: true,
+      bubbles: true,
+    })
+  )
+
+  expect(callback).toHaveBeenCalledTimes(1)
+})
+
+test('Should match alt+a when Option+A produces Unicode character', async () => {
+  const callback = vi.fn()
+
+  renderHook(() => useHotkeys('alt+a', callback))
+
+  document.dispatchEvent(
+    new KeyboardEvent('keydown', {
+      key: 'å',
+      code: 'KeyA',
+      altKey: true,
+      bubbles: true,
+    })
+  )
+
+  expect(callback).toHaveBeenCalledTimes(1)
+})
+
 test('Should remove listener on AbortSignal', async () => {
   const abortController = new AbortController()
   const { signal } = abortController