Shift+punctuation hotkeys (Mod+Shift+[ / ]) are layout-dependent

[songkeys]

TanStack Hotkeys version

0.1.0

Framework/Library version

React 19 (also reproducible with core matcher behavior)

Describe the bug

Mod+Shift+[ / ] cannot be represented robustly with a single registration across layouts/browser event variations.

For this common shortcut pattern, event.key may arrive as either [ / ] or { / } depending on layout/IME/browser behavior.

Current behavior appears to rely on event.key for punctuation matching, while event.code fallback exists only for letters/digits. That makes bracket shortcuts layout-sensitive.

Minimal repro

useHotkey({ key: '{', mod: true, shift: true }, () => console.log('prev'))
useHotkey({ key: '}', mod: true, shift: true }, () => console.log('next'))

And event logging for the same physical combo:

window.addEventListener('keydown', (e) => {
  if (e.metaKey && e.shiftKey && (e.code === 'BracketLeft' || e.code === 'BracketRight')) {
    console.log({ key: e.key, code: e.code })
  }
})

Depending on environment, the combo can surface as key: '['/']' instead of {/} (or vice versa), so one registration path fails.

Expected behavior

A single logical definition for previous/next tab should work reliably across keyboard layouts/event key variants.

Possible fix directions

1. Add optional event.code fallback for punctuation keys (e.g. BracketLeft, BracketRight).
2. Add an explicit code-based registration mode/syntax.
3. Provide a built-in alias strategy for shifted punctuation keys.

Related

• Hotkey registering both for the key and code fields for normal characters #17
• Mod+? / ? missing #19