fix(hotkeys): support numpad plus shortcuts

packages/hotkeys/src/constants.ts

@@ -283,10 +283,12 @@ export const EDITING_KEYS = new Set<EditingKey>([
  * so they're excluded from Shift-based hotkey combinations to avoid layout-dependent behavior.
  */
 export const PUNCTUATION_KEYS = new Set<PunctuationKey>([
+  'Plus',
   '/',
   '[',
   ']',
   '\\',
+  '+',
   '=',
   '-',
   ',',
@@ -312,6 +314,7 @@ export const PUNCTUATION_CODE_MAP: Record<string, string> = {
   Comma: ',',
   Equal: '=',
   Minus: '-',
+  NumpadAdd: '+',
   Period: '.',
   Semicolon: ';',
   Slash: '/',
@@ -410,6 +413,10 @@ const KEY_ALIASES: Record<string, string> = {
   PgDn: 'PageDown',
   pgup: 'PageUp',
   pgdn: 'PageDown',
+
+  // Punctuation variants
+  Plus: '+',
+  plus: '+',
 }
 
 /**
@@ -563,11 +570,13 @@ export const LINUX_MODIFIER_LABELS: Record<CanonicalModifier | 'Mod', string> =
   }
 
 export const PUNCTUATION_KEY_DISPLAY_LABELS = {
+  Plus: 'Plus',
   '`': 'Backquote',
   '\\': 'Backslash',
   '[': 'Left Bracket',
   ']': 'Right Bracket',
   ',': 'Comma',
+  '+': 'Plus',
   '=': 'Equal',
   '-': 'Minus',
   '.': 'Period',

packages/hotkeys/src/format.ts

@@ -61,7 +61,7 @@ export function formatHotkey(parsed: ParsedHotkey): string {
   }
 
   // Add the key
-  parts.push(parsed.key)
+  parts.push(parsed.key === '+' ? 'Plus' : parsed.key)
 
   return parts.join('+')
 }

packages/hotkeys/src/hotkey.ts

@@ -115,10 +115,12 @@ export type EditingKey =
  * (layout-dependent, typically US keyboard layout).
  */
 export type PunctuationKey =
+  | 'Plus'
   | '/'
   | '['
   | ']'
   | '\\'
+  | '+'
   | '='
   | '-'
   | ','

packages/hotkeys/src/match.ts

@@ -93,9 +93,15 @@ export function matchesKeyboardEvent(
   // event.key is a non-letter special character.
   // Dead keys: Option+letter on macOS, international layouts produce event.key === 'Dead'
   // Single-char mismatches: Cmd+Option+T gives '†' instead of 'T', Shift+4 gives '$'
+  const hasPunctuationCode = Boolean(
+    event.code && event.code in PUNCTUATION_CODE_MAP,
+  )
+
   if (
     event.code &&
-    (eventKey === 'Dead' || (eventKey.length === 1 && hotkeyKey.length === 1))
+    (eventKey === 'Dead' ||
+      (eventKey.length === 1 && hotkeyKey.length === 1) ||
+      hasPunctuationCode)
   ) {
     // fallback for letter keys (common with mac option + letter)
     if (event.code.startsWith('Key')) {

packages/hotkeys/src/parse.ts

@@ -32,7 +32,7 @@ export function parseHotkey(
   hotkey: Hotkey | (string & {}),
   platform: 'mac' | 'windows' | 'linux' = detectPlatform(),
 ): ParsedHotkey {
-  const parts = hotkey.split('+')
+  const parts = splitHotkeyParts(hotkey)
   const modifiers: Set<CanonicalModifier> = new Set()
   let key = ''
 
@@ -75,6 +75,28 @@ export function parseHotkey(
   }
 }
 
+function splitHotkeyParts(hotkey: string): Array<string> {
+  const parts = hotkey.split('+').map((part) => part.trim())
+
+  if (hotkey.endsWith('+') && parts.length > 1) {
+    parts.pop()
+
+    if (parts.at(-1) === '') {
+      parts.pop()
+    }
+
+    parts.push('+')
+  }
+
+  return parts
+}
+
+function hotkeyKeyToken(key: string): string {
+  const normalizedKey = normalizeKeyName(key)
+
+  return normalizedKey === '+' ? 'Plus' : normalizedKey
+}
+
 /**
  * Converts a RawHotkey object to a ParsedHotkey.
  * Optional modifier booleans default to false; modifiers array is derived from them.
@@ -129,7 +151,7 @@ export function rawHotkeyToParsedHotkey(
     }
   })
   return {
-    key: raw.key,
+    key: normalizeKeyName(raw.key),
     ctrl,
     shift,
     alt,
@@ -170,7 +192,7 @@ function normalizedHotkeyStringFromParsed(
     }
   }
 
-  parts.push(normalizeKeyName(parsed.key))
+  parts.push(hotkeyKeyToken(parsed.key))
   return parts.join('+') as Hotkey
 }
 

packages/hotkeys/src/validate.ts

@@ -1,4 +1,4 @@
-import { ALL_KEYS, MODIFIER_ALIASES } from './constants'
+import { ALL_KEYS, MODIFIER_ALIASES, normalizeKeyName } from './constants'
 import type { Hotkey, ValidationResult } from './hotkey'
 
 /**
@@ -36,7 +36,7 @@ export function validateHotkey(
     }
   }
 
-  const parts = hotkey.split('+').map((p) => p.trim())
+  const parts = splitHotkeyParts(hotkey)
 
   // Must have at least one part (the key)
   if (parts.length === 0 || parts.some((p) => p === '')) {
@@ -61,7 +61,7 @@ export function validateHotkey(
   }
 
   // Check if key is known
-  const normalizedKey = normalizeKeyForValidation(keyPart)
+  const normalizedKey = normalizeKeyName(normalizeKeyForValidation(keyPart))
   if (!isKnownKey(normalizedKey) && !isKnownKey(keyPart)) {
     warnings.push(
       `Unknown key: '${keyPart}'. This may still work but won't have type-safe autocomplete.`,
@@ -75,6 +75,22 @@ export function validateHotkey(
   }
 }
 
+function splitHotkeyParts(hotkey: string): Array<string> {
+  const parts = hotkey.split('+').map((p) => p.trim())
+
+  if (hotkey.endsWith('+') && parts.length > 1) {
+    parts.pop()
+
+    if (parts.at(-1) === '') {
+      parts.pop()
+    }
+
+    parts.push('+')
+  }
+
+  return parts
+}
+
 /**
  * Normalizes a key for validation checking.
  */

packages/hotkeys/tests/hotkey-manager.test.ts

@@ -12,10 +12,12 @@ function createKeyboardEvent(
     shiftKey?: boolean
     altKey?: boolean
     metaKey?: boolean
+    code?: string
   } = {},
 ): KeyboardEvent {
   return new KeyboardEvent(type, {
     key,
+    code: options.code,
     ctrlKey: options.ctrlKey ?? false,
     shiftKey: options.shiftKey ?? false,
     altKey: options.altKey ?? false,
@@ -124,6 +126,25 @@ describe('HotkeyManager', () => {
       )
       expect(callback).toHaveBeenCalledTimes(1)
     })
+
+    it('should register a RawHotkey plus key and match NumpadAdd', () => {
+      const manager = HotkeyManager.getInstance()
+      const callback = vi.fn()
+
+      manager.register({ key: '+', mod: true }, callback, {
+        platform: 'windows',
+      })
+
+      expect(manager.getRegistrationCount()).toBe(1)
+      expect(manager.isRegistered('Control+Plus')).toBe(true)
+      document.dispatchEvent(
+        createKeyboardEvent('keydown', 'Unidentified', {
+          code: 'NumpadAdd',
+          ctrlKey: true,
+        }),
+      )
+      expect(callback).toHaveBeenCalledTimes(1)
+    })
   })
 
   describe('HotkeyRegistrationHandle', () => {

packages/hotkeys/tests/match.test.ts

@@ -5,6 +5,7 @@ import {
   matchesKeyboardEvent,
 } from '../src/match'
 import { Hotkey } from '../src'
+import { rawHotkeyToParsedHotkey } from '../src/parse'
 
 /**
  * Helper to create a mock KeyboardEvent
@@ -704,6 +705,30 @@ describe('matchesKeyboardEvent', () => {
       expect(matchesKeyboardEvent(event, 'Alt+-' as Hotkey)).toBe(false)
     })
 
+    it('should match NumpadAdd for plus hotkeys', () => {
+      const event = createKeyboardEvent('Unidentified', {
+        ctrlKey: true,
+        code: 'NumpadAdd',
+      })
+
+      expect(matchesKeyboardEvent(event, 'Mod++' as Hotkey, 'windows')).toBe(
+        true,
+      )
+    })
+
+    it('should match NumpadAdd for parsed raw plus hotkeys', () => {
+      const event = createKeyboardEvent('Unidentified', {
+        metaKey: true,
+        code: 'NumpadAdd',
+      })
+      const parsedHotkey = rawHotkeyToParsedHotkey(
+        { key: '+', mod: true },
+        'mac',
+      )
+
+      expect(matchesKeyboardEvent(event, parsedHotkey, 'mac')).toBe(true)
+    })
+
     it('should match Ctrl+punctuation without needing fallback (non-macOS)', () => {
       const event = createKeyboardEvent('-', {
         ctrlKey: true,

packages/hotkeys/tests/parse.test.ts

@@ -49,6 +49,18 @@ describe('parseHotkey', () => {
       expect(parseHotkey('ArrowDown').key).toBe('ArrowDown')
     })
 
+    it('should parse plus keys from delimiter-based strings', () => {
+      expect(parseHotkey('+').key).toBe('+')
+      expect(parseHotkey('Mod++', 'windows')).toMatchObject({
+        ctrl: true,
+        key: '+',
+      })
+      expect(parseHotkey('Mod+Plus', 'mac')).toMatchObject({
+        key: '+',
+        meta: true,
+      })
+    })
+
     it('should handle key aliases', () => {
       expect(parseHotkey('Esc').key).toBe('Escape')
       expect(parseHotkey('Return').key).toBe('Enter')
@@ -210,6 +222,8 @@ describe('normalizeHotkey', () => {
     expect(normalizeHotkey('Ctrl+Esc', 'mac')).toBe('Control+Escape')
     expect(normalizeHotkey('Ctrl+Esc', 'windows')).toBe('Mod+Escape')
     expect(normalizeHotkey('Mod+Return', 'mac')).toBe('Mod+Enter')
+    expect(normalizeHotkey('Mod++', 'windows')).toBe('Mod+Plus')
+    expect(normalizeHotkey('Mod+Plus', 'mac')).toBe('Mod+Plus')
   })
 
   it('should normalize single keys', () => {
@@ -456,6 +470,9 @@ describe('normalizeRegisterableHotkey', () => {
     expect(
       normalizeRegisterableHotkey({ key: 's', mod: true }, 'windows'),
     ).toBe('Mod+S')
+    expect(
+      normalizeRegisterableHotkey({ key: '+', mod: true }, 'windows'),
+    ).toBe('Mod+Plus')
   })
 })
 

packages/hotkeys/tests/validate.test.ts

@@ -26,6 +26,15 @@ describe('validateHotkey', () => {
       expect(validateHotkey('Esc').valid).toBe(true)
       expect(validateHotkey('Return').valid).toBe(true)
       expect(validateHotkey('Del').valid).toBe(true)
+      expect(validateHotkey('Mod+Plus').valid).toBe(true)
+    })
+
+    it('should validate plus keys written with a trailing plus delimiter', () => {
+      const result = validateHotkey('Mod++')
+
+      expect(result.valid).toBe(true)
+      expect(result.errors).toHaveLength(0)
+      expect(result.warnings).toHaveLength(0)
     })
   })