fix(hotkeys): add ? to supported punctuation keys

.changeset/add-question-mark-key.md

@@ -0,0 +1,9 @@
+---
+'@tanstack/hotkeys': patch
+---
+
+Use `event.code` for punctuation key matching to handle Shift-affected keys
+
+Punctuation keys like `/` produce different characters when Shift is pressed (`?`), causing `event.key` to mismatch. The matcher now falls back to `event.code` (e.g., `Slash`, `Comma`) to reliably identify the physical key, matching the existing approach for letters and digits.
+
+Shifted punctuation in hotkey strings is also normalized automatically: `Mod+?` becomes `Mod+Shift+/`.

docs/reference/functions/convertToModFormat.md

@@ -9,7 +9,7 @@ title: convertToModFormat
 function convertToModFormat(hotkey, platform): Hotkey;
 ```
 
-Defined in: [parse.ts:345](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L345)
+Defined in: [parse.ts:353](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L353)
 
 Converts a hotkey string to use 'Mod' format for portability.
 

docs/reference/functions/createHotkeyHandler.md

@@ -12,7 +12,7 @@ function createHotkeyHandler(
    options): (event) => void;
 ```
 
-Defined in: [match.ts:122](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L122)
+Defined in: [match.ts:137](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L137)
 
 Creates a keyboard event handler that calls the callback when the hotkey matches.
 

docs/reference/functions/createMultiHotkeyHandler.md

@@ -9,7 +9,7 @@ title: createMultiHotkeyHandler
 function createMultiHotkeyHandler(handlers, options): (event) => void;
 ```
 
-Defined in: [match.ts:173](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L173)
+Defined in: [match.ts:188](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L188)
 
 Creates a handler that matches multiple hotkeys.
 

docs/reference/functions/hasNonModifierKey.md

@@ -9,7 +9,7 @@ title: hasNonModifierKey
 function hasNonModifierKey(hotkey, platform): boolean;
 ```
 
-Defined in: [parse.ts:314](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L314)
+Defined in: [parse.ts:322](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L322)
 
 Checks if a hotkey or ParsedHotkey contains at least one non-modifier key.
 

docs/reference/functions/isModifier.md

@@ -9,7 +9,7 @@ title: isModifier
 function isModifier(key): boolean;
 ```
 
-Defined in: [parse.ts:186](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L186)
+Defined in: [parse.ts:194](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L194)
 
 Checks if a string represents a modifier key.
 

docs/reference/functions/isModifierKey.md

@@ -9,7 +9,7 @@ title: isModifierKey
 function isModifierKey(event): boolean;
 ```
 
-Defined in: [parse.ts:284](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L284)
+Defined in: [parse.ts:292](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L292)
 
 Checks if a KeyboardEvent represents a modifier-only key press.
 

docs/reference/functions/keyboardEventToHotkey.md

@@ -9,7 +9,7 @@ title: keyboardEventToHotkey
 function keyboardEventToHotkey(event): Hotkey;
 ```
 
-Defined in: [parse.ts:248](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L248)
+Defined in: [parse.ts:256](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L256)
 
 Converts a KeyboardEvent directly to a hotkey string.
 

docs/reference/functions/matchesKeyboardEvent.md

@@ -12,13 +12,14 @@ function matchesKeyboardEvent(
    platform): boolean;
 ```
 
-Defined in: [match.ts:32](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L32)
+Defined in: [match.ts:37](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L37)
 
 Checks if a KeyboardEvent matches a hotkey.
 
 Uses the `key` property from KeyboardEvent for matching, with a fallback to `code`
-for letter keys (A-Z) and digit keys (0-9) when `key` produces special characters
-(e.g., macOS Option+letter or Shift+number). Letter keys are matched case-insensitively.
+for letter keys (A-Z), digit keys (0-9), and punctuation keys when `key` produces
+unexpected characters (e.g., macOS Option+letter, Shift+number, or Shift+punctuation).
+Letter keys are matched case-insensitively.
 
 ## Parameters
 

docs/reference/functions/normalizeHotkey.md

@@ -9,7 +9,7 @@ title: normalizeHotkey
 function normalizeHotkey(hotkey, platform): string;
 ```
 
-Defined in: [parse.ts:160](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L160)
+Defined in: [parse.ts:168](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L168)
 
 Normalizes a hotkey string to its canonical form.
 

docs/reference/functions/normalizeKeyName.md

@@ -9,7 +9,7 @@ title: normalizeKeyName
 function normalizeKeyName(key): string;
 ```
 
-Defined in: [constants.ts:422](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/constants.ts#L422)
+Defined in: [constants.ts:476](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/constants.ts#L476)
 
 Normalizes a key name to its canonical form.
 

docs/reference/functions/parseHotkey.md

@@ -9,7 +9,7 @@ title: parseHotkey
 function parseHotkey(hotkey, platform): ParsedHotkey;
 ```
 
-Defined in: [parse.ts:30](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L30)
+Defined in: [parse.ts:31](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L31)
 
 Parses a hotkey string into its component parts.
 

docs/reference/functions/parseKeyboardEvent.md

@@ -9,7 +9,7 @@ title: parseKeyboardEvent
 function parseKeyboardEvent(event): ParsedHotkey;
 ```
 
-Defined in: [parse.ts:208](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L208)
+Defined in: [parse.ts:216](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L216)
 
 Parses a KeyboardEvent into a ParsedHotkey object.
 

docs/reference/functions/rawHotkeyToParsedHotkey.md

@@ -9,7 +9,7 @@ title: rawHotkeyToParsedHotkey
 function rawHotkeyToParsedHotkey(raw, platform): ParsedHotkey;
 ```
 
-Defined in: [parse.ts:98](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L98)
+Defined in: [parse.ts:106](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/parse.ts#L106)
 
 Converts a RawHotkey object to a ParsedHotkey.
 Optional modifier booleans default to false; modifiers array is derived from them.

docs/reference/index.md

@@ -60,7 +60,9 @@ title: "@tanstack/hotkeys"
 - [MODIFIER\_ORDER](variables/MODIFIER_ORDER.md)
 - [NAVIGATION\_KEYS](variables/NAVIGATION_KEYS.md)
 - [NUMBER\_KEYS](variables/NUMBER_KEYS.md)
+- [PUNCTUATION\_CODE\_TO\_KEY](variables/PUNCTUATION_CODE_TO_KEY.md)
 - [PUNCTUATION\_KEYS](variables/PUNCTUATION_KEYS.md)
+- [SHIFTED\_KEY\_MAP](variables/SHIFTED_KEY_MAP.md)
 - [STANDARD\_MODIFIER\_LABELS](variables/STANDARD_MODIFIER_LABELS.md)
 
 ## Functions

docs/reference/interfaces/CreateHotkeyHandlerOptions.md

@@ -5,7 +5,7 @@ title: CreateHotkeyHandlerOptions
 
 # Interface: CreateHotkeyHandlerOptions
 
-Defined in: [match.ts:95](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L95)
+Defined in: [match.ts:110](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L110)
 
 Options for creating a hotkey handler.
 
@@ -17,7 +17,7 @@ Options for creating a hotkey handler.
 optional platform: "mac" | "windows" | "linux";
 ```
 
-Defined in: [match.ts:101](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L101)
+Defined in: [match.ts:116](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L116)
 
 The target platform for resolving 'Mod'
 
@@ -29,7 +29,7 @@ The target platform for resolving 'Mod'
 optional preventDefault: boolean;
 ```
 
-Defined in: [match.ts:97](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L97)
+Defined in: [match.ts:112](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L112)
 
 Prevent the default browser action when the hotkey matches. Defaults to true
 
@@ -41,6 +41,6 @@ Prevent the default browser action when the hotkey matches. Defaults to true
 optional stopPropagation: boolean;
 ```
 
-Defined in: [match.ts:99](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L99)
+Defined in: [match.ts:114](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/match.ts#L114)
 
 Stop event propagation when the hotkey matches. Defaults to true

docs/reference/interfaces/FormatDisplayOptions.md

@@ -5,7 +5,7 @@ title: FormatDisplayOptions
 
 # Interface: FormatDisplayOptions
 
-Defined in: [hotkey.ts:367](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L367)
+Defined in: [hotkey.ts:365](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L365)
 
 Options for formatting hotkeys for display.
 
@@ -17,6 +17,6 @@ Options for formatting hotkeys for display.
 optional platform: "mac" | "windows" | "linux";
 ```
 
-Defined in: [hotkey.ts:369](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L369)
+Defined in: [hotkey.ts:367](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L367)
 
 The target platform. Defaults to auto-detection.

docs/reference/interfaces/HotkeyCallbackContext.md

@@ -5,7 +5,7 @@ title: HotkeyCallbackContext
 
 # Interface: HotkeyCallbackContext
 
-Defined in: [hotkey.ts:387](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L387)
+Defined in: [hotkey.ts:385](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L385)
 
 Context passed to hotkey callbacks along with the keyboard event.
 
@@ -17,7 +17,7 @@ Context passed to hotkey callbacks along with the keyboard event.
 hotkey: Hotkey;
 ```
 
-Defined in: [hotkey.ts:389](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L389)
+Defined in: [hotkey.ts:387](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L387)
 
 The original hotkey string that was registered
 
@@ -29,6 +29,6 @@ The original hotkey string that was registered
 parsedHotkey: ParsedHotkey;
 ```
 
-Defined in: [hotkey.ts:391](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L391)
+Defined in: [hotkey.ts:389](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L389)
 
 The parsed representation of the hotkey

docs/reference/interfaces/ParsedHotkey.md

@@ -5,7 +5,7 @@ title: ParsedHotkey
 
 # Interface: ParsedHotkey
 
-Defined in: [hotkey.ts:308](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L308)
+Defined in: [hotkey.ts:306](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L306)
 
 A parsed representation of a hotkey string.
 
@@ -33,7 +33,7 @@ useHotkey(parsed, handler) // Works even if userInput isn't in Hotkey type
 alt: boolean;
 ```
 
-Defined in: [hotkey.ts:316](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L316)
+Defined in: [hotkey.ts:314](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L314)
 
 Whether the Alt key is required
 
@@ -45,7 +45,7 @@ Whether the Alt key is required
 ctrl: boolean;
 ```
 
-Defined in: [hotkey.ts:312](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L312)
+Defined in: [hotkey.ts:310](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L310)
 
 Whether the Control key is required
 
@@ -57,7 +57,7 @@ Whether the Control key is required
 key: Key | string & object;
 ```
 
-Defined in: [hotkey.ts:310](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L310)
+Defined in: [hotkey.ts:308](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L308)
 
 The non-modifier key (e.g., 'S', 'Escape', 'F1', '/', '['). Can be any string for flexibility.
 
@@ -69,7 +69,7 @@ The non-modifier key (e.g., 'S', 'Escape', 'F1', '/', '['). Can be any string fo
 meta: boolean;
 ```
 
-Defined in: [hotkey.ts:318](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L318)
+Defined in: [hotkey.ts:316](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L316)
 
 Whether the Meta (Command) key is required
 
@@ -81,7 +81,7 @@ Whether the Meta (Command) key is required
 modifiers: CanonicalModifier[];
 ```
 
-Defined in: [hotkey.ts:320](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L320)
+Defined in: [hotkey.ts:318](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L318)
 
 List of canonical modifier names that are required, in canonical order
 
@@ -93,6 +93,6 @@ List of canonical modifier names that are required, in canonical order
 shift: boolean;
 ```
 
-Defined in: [hotkey.ts:314](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L314)
+Defined in: [hotkey.ts:312](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L312)
 
 Whether the Shift key is required

docs/reference/interfaces/RawHotkey.md

@@ -5,7 +5,7 @@ title: RawHotkey
 
 # Interface: RawHotkey
 
-Defined in: [hotkey.ts:343](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L343)
+Defined in: [hotkey.ts:341](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L341)
 
 A raw hotkey object for programmatic registration.
 
@@ -35,7 +35,7 @@ useHotkey({ key: 'S', mod: true, shift: true }, handler)  // Mod+Shift+S
 optional alt: boolean;
 ```
 
-Defined in: [hotkey.ts:353](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L353)
+Defined in: [hotkey.ts:351](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L351)
 
 Whether the Alt key is required. Defaults to false.
 
@@ -47,7 +47,7 @@ Whether the Alt key is required. Defaults to false.
 optional ctrl: boolean;
 ```
 
-Defined in: [hotkey.ts:349](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L349)
+Defined in: [hotkey.ts:347](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L347)
 
 Whether the Control key is required. Defaults to false.
 
@@ -59,7 +59,7 @@ Whether the Control key is required. Defaults to false.
 key: Key | string & object;
 ```
 
-Defined in: [hotkey.ts:345](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L345)
+Defined in: [hotkey.ts:343](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L343)
 
 The non-modifier key (e.g., 'S', 'Escape', 'F1').
 
@@ -71,7 +71,7 @@ The non-modifier key (e.g., 'S', 'Escape', 'F1').
 optional meta: boolean;
 ```
 
-Defined in: [hotkey.ts:355](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L355)
+Defined in: [hotkey.ts:353](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L353)
 
 Whether the Meta (Command) key is required. Defaults to false.
 
@@ -83,7 +83,7 @@ Whether the Meta (Command) key is required. Defaults to false.
 optional mod: boolean;
 ```
 
-Defined in: [hotkey.ts:347](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L347)
+Defined in: [hotkey.ts:345](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L345)
 
 Platform-adaptive modifier: Command on macOS, Control on Windows/Linux. Defaults to false.
 
@@ -95,6 +95,6 @@ Platform-adaptive modifier: Command on macOS, Control on Windows/Linux. Defaults
 optional shift: boolean;
 ```
 
-Defined in: [hotkey.ts:351](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L351)
+Defined in: [hotkey.ts:349](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L349)
 
 Whether the Shift key is required. Defaults to false.

docs/reference/interfaces/ValidationResult.md

@@ -5,7 +5,7 @@ title: ValidationResult
 
 # Interface: ValidationResult
 
-Defined in: [hotkey.ts:375](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L375)
+Defined in: [hotkey.ts:373](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L373)
 
 Result of validating a hotkey string.
 
@@ -17,7 +17,7 @@ Result of validating a hotkey string.
 errors: string[];
 ```
 
-Defined in: [hotkey.ts:381](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L381)
+Defined in: [hotkey.ts:379](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L379)
 
 Error messages about invalid syntax
 
@@ -29,7 +29,7 @@ Error messages about invalid syntax
 valid: boolean;
 ```
 
-Defined in: [hotkey.ts:377](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L377)
+Defined in: [hotkey.ts:375](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L375)
 
 Whether the hotkey is valid (can still have warnings)
 
@@ -41,6 +41,6 @@ Whether the hotkey is valid (can still have warnings)
 warnings: string[];
 ```
 
-Defined in: [hotkey.ts:379](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L379)
+Defined in: [hotkey.ts:377](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L377)
 
 Warning messages about potential issues

docs/reference/type-aliases/HeldKey.md

@@ -9,7 +9,7 @@ title: HeldKey
 type HeldKey = CanonicalModifier | Key;
 ```
 
-Defined in: [hotkey.ts:154](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L154)
+Defined in: [hotkey.ts:156](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/hotkey.ts#L156)
 
 Keys that can be tracked as "held" (pressed down).
 Includes both modifier keys and regular keys.