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

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

• #17
• #19

Start at the core matcher behavior used by useHotkey and inspect how event.key is matched and when event.code fallback is applied. Reproduce the BracketLeft and BracketRight cases with the provided minimal example and event logging, then verify that one logical registration handles both bracket and brace key variants across layouts.