Add useKeyboardShortcut hook

Author: ThaNarie

src/hooks/useKeyboardShortcut/index.ts

@@ -0,0 +1,6 @@
+export type { UseKeyboardShortcutOptions } from './useKeyboardShortcut.js';
+export { useKeyboardShortcut } from './useKeyboardShortcut.js';
+
+export type { Command, Shortcut, SimpleShortcut } from './useKeyboardShortcut.types.js';
+export { keyCodes, modifierKeys } from './keyCodes.js';
+export type { KeyCode, Modifier } from './keyCodes.js';

src/hooks/useKeyboardShortcut/isShortcutDown.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { isShortcutDown } from './isShortcutDown.js';
+import type { Command } from './useKeyboardShortcut.types.js';
+
+describe('isShortcutDown', () => {
+  it('should return true when key and modifiers match exactly', () => {
+    const event = new KeyboardEvent('keydown', {
+      code: 'KeyA',
+      ctrlKey: true,
+      shiftKey: false,
+      altKey: false,
+      metaKey: false,
+    });
+
+    const command: Command = {
+      code: 'KeyA',
+      ctrlKey: true,
+    };
+
+    expect(isShortcutDown(event, command)).toBe(true);
+  });
+
+  it('should return false when key matches but modifiers do not', () => {
+    const event = new KeyboardEvent('keydown', {
+      code: 'KeyA',
+      ctrlKey: true,
+      shiftKey: true,
+      altKey: false,
+      metaKey: false,
+    });
+
+    const command: Command = {
+      code: 'KeyA',
+      ctrlKey: true,
+    };
+
+    expect(isShortcutDown(event, command)).toBe(false);
+  });
+
+  it('should return false when modifiers match but key does not', () => {
+    const event = new KeyboardEvent('keydown', {
+      code: 'KeyB',
+      ctrlKey: true,
+    });
+
+    const command: Command = {
+      code: 'KeyA',
+      ctrlKey: true,
+    };
+
+    expect(isShortcutDown(event, command)).toBe(false);
+  });
+
+  it('should be case-insensitive for key matching with the shift key', () => {
+    const event = new KeyboardEvent('keydown', {
+      code: 'KeyA',
+      ctrlKey: false,
+      shiftKey: true,
+      altKey: false,
+      metaKey: false,
+    });
+
+    const command: Command = {
+      code: 'KeyA',
+      shiftKey: true,
+    };
+
+    expect(isShortcutDown(event, command)).toBe(true);
+  });
+
+  it('should handle multiple modifiers correctly', () => {
+    const event = new KeyboardEvent('keydown', {
+      code: 'KeyA',
+      ctrlKey: true,
+      shiftKey: true,
+      altKey: true,
+      metaKey: true,
+    });
+
+    const command: Command = {
+      code: 'KeyA',
+      ctrlKey: true,
+      shiftKey: true,
+      altKey: true,
+      metaKey: true,
+    };
+
+    expect(isShortcutDown(event, command)).toBe(true);
+  });
+
+  it('should match alt+key even when it produces a special character', () => {
+    // On macOS, alt+n produces ñ, but we want to match 'n'
+    const event = new KeyboardEvent('keydown', {
+      code: 'KeyN',
+      altKey: true,
+    });
+
+    const command: Command = {
+      code: 'KeyN',
+      altKey: true,
+    };
+
+    expect(isShortcutDown(event, command)).toBe(true);
+  });
+});

src/hooks/useKeyboardShortcut/isShortcutDown.ts

@@ -0,0 +1,44 @@
+import type { Command } from './useKeyboardShortcut.types.js';
+
+const modifiers = ['ctrl', 'shift', 'alt', 'meta'] as const;
+
+/**
+ * Checks if the provided event matches the command.
+ * - if they key code matches
+ * - if all modifiers match, no more and no less
+ *
+ * @param event The keyboard event to check.
+ * @param command The command to match against.
+ * @returns True if the event matches the command, false otherwise.
+ */
+export function isShortcutDown(event: KeyboardEvent, command: Command): boolean {
+  // Check that only the required modifiers are down
+  const areModifiersCorrect = modifiers.every(
+    (modifier) => event[`${modifier}Key`] === Boolean(command[`${modifier}Key`]),
+  );
+  if (!areModifiersCorrect) {
+    return false;
+  }
+
+  // Check if the pressed key matches the command key
+  const isKeyDown = event.code === command.code;
+
+  // TODO: Add a mode where it checks against the `key` instead of `code`,
+  // to allow for better support for different keyboard layouts,
+  // where the same code might input a different character
+  // However, this would only work with specific modifier:
+  //
+  // Shift will do capitals or other characters:
+  // - shift+/ = ?, so '?' is the shortcut to register in that mode
+  //
+  // Alt/Option will do special characters:
+  // - Alt+/ = ÷, so '÷' is the shortcut to register in that mode
+  // - Alt+n = Dead Key for a ~ character above the next key, so cannot be used as a shortcut that way.
+  //
+  // Ctrl/Cmd should be fine, as they don't change the character that would be typed.
+  //
+  // Likely the `Command` type should be updated to add a `key` field, and both `key` and `code` should be optional.
+  // Unless we can make one required based on the `mode` configuration.
+
+  return isKeyDown;
+}

src/hooks/useKeyboardShortcut/keyCodes.ts

@@ -0,0 +1,210 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+
+export const modifierKeys = {
+  AltLeft: 'AltLeft',
+  AltRight: 'AltRight',
+  ControlLeft: 'ControlLeft',
+  ControlRight: 'ControlRight',
+  OSLeft: 'OSLeft',
+  OSRight: 'OSRight',
+  ShiftLeft: 'ShiftLeft',
+  ShiftRight: 'ShiftRight',
+  MetaLeft: 'MetaLeft',
+  MetaRight: 'MetaRight',
+};
+
+export type Modifier = keyof typeof modifierKeys;
+
+/**
+ * Keyboard event code values based on MDN documentation
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values
+ */
+export const keyCodes = {
+  // Digit Keys
+  Digit0: 'Digit0',
+  Digit1: 'Digit1',
+  Digit2: 'Digit2',
+  Digit3: 'Digit3',
+  Digit4: 'Digit4',
+  Digit5: 'Digit5',
+  Digit6: 'Digit6',
+  Digit7: 'Digit7',
+  Digit8: 'Digit8',
+  Digit9: 'Digit9',
+
+  // Letter Keys
+  KeyA: 'KeyA',
+  KeyB: 'KeyB',
+  KeyC: 'KeyC',
+  KeyD: 'KeyD',
+  KeyE: 'KeyE',
+  KeyF: 'KeyF',
+  KeyG: 'KeyG',
+  KeyH: 'KeyH',
+  KeyI: 'KeyI',
+  KeyJ: 'KeyJ',
+  KeyK: 'KeyK',
+  KeyL: 'KeyL',
+  KeyM: 'KeyM',
+  KeyN: 'KeyN',
+  KeyO: 'KeyO',
+  KeyP: 'KeyP',
+  KeyQ: 'KeyQ',
+  KeyR: 'KeyR',
+  KeyS: 'KeyS',
+  KeyT: 'KeyT',
+  KeyU: 'KeyU',
+  KeyV: 'KeyV',
+  KeyW: 'KeyW',
+  KeyX: 'KeyX',
+  KeyY: 'KeyY',
+  KeyZ: 'KeyZ',
+
+  // Function Keys
+  F1: 'F1',
+  F2: 'F2',
+  F3: 'F3',
+  F4: 'F4',
+  F5: 'F5',
+  F6: 'F6',
+  F7: 'F7',
+  F8: 'F8',
+  F9: 'F9',
+  F10: 'F10',
+  F11: 'F11',
+  F12: 'F12',
+  F13: 'F13',
+  F14: 'F14',
+  F15: 'F15',
+  F16: 'F16',
+  F17: 'F17',
+  F18: 'F18',
+  F19: 'F19',
+  F20: 'F20',
+  F21: 'F21',
+  F22: 'F22',
+  F23: 'F23',
+  F24: 'F24',
+
+  // Navigation Keys
+  ArrowDown: 'ArrowDown',
+  ArrowLeft: 'ArrowLeft',
+  ArrowRight: 'ArrowRight',
+  ArrowUp: 'ArrowUp',
+  End: 'End',
+  Home: 'Home',
+  PageDown: 'PageDown',
+  PageUp: 'PageUp',
+
+  // Editing Keys
+  Space: 'Space',
+  Backspace: 'Backspace',
+  Delete: 'Delete',
+  Enter: 'Enter',
+  Insert: 'Insert',
+  Tab: 'Tab',
+
+  // UI Keys
+  Escape: 'Escape',
+  CapsLock: 'CapsLock',
+  PrintScreen: 'PrintScreen',
+  ScrollLock: 'ScrollLock',
+  Pause: 'Pause',
+
+  // Modifier Keys
+  ...modifierKeys,
+
+  // Punctuation Keys
+  Backquote: 'Backquote',
+  BracketLeft: 'BracketLeft',
+  BracketRight: 'BracketRight',
+  Comma: 'Comma',
+  Period: 'Period',
+  Semicolon: 'Semicolon',
+  Quote: 'Quote',
+  Backslash: 'Backslash',
+  Slash: 'Slash',
+  Minus: 'Minus',
+  Equal: 'Equal',
+
+  // Numpad Keys
+  NumLock: 'NumLock',
+  Numpad0: 'Numpad0',
+  Numpad1: 'Numpad1',
+  Numpad2: 'Numpad2',
+  Numpad3: 'Numpad3',
+  Numpad4: 'Numpad4',
+  Numpad5: 'Numpad5',
+  Numpad6: 'Numpad6',
+  Numpad7: 'Numpad7',
+  Numpad8: 'Numpad8',
+  Numpad9: 'Numpad9',
+  NumpadAdd: 'NumpadAdd',
+  NumpadDecimal: 'NumpadDecimal',
+  NumpadDivide: 'NumpadDivide',
+  NumpadEnter: 'NumpadEnter',
+  NumpadEqual: 'NumpadEqual',
+  NumpadMultiply: 'NumpadMultiply',
+  NumpadSubtract: 'NumpadSubtract',
+  NumpadComma: 'NumpadComma',
+
+  // Media Keys
+  MediaPlayPause: 'MediaPlayPause',
+  MediaStop: 'MediaStop',
+  MediaTrackNext: 'MediaTrackNext',
+  MediaTrackPrevious: 'MediaTrackPrevious',
+  AudioVolumeMute: 'AudioVolumeMute',
+  AudioVolumeDown: 'AudioVolumeDown',
+  AudioVolumeUp: 'AudioVolumeUp',
+
+  // Browser Keys
+  BrowserBack: 'BrowserBack',
+  BrowserFavorites: 'BrowserFavorites',
+  BrowserForward: 'BrowserForward',
+  BrowserHome: 'BrowserHome',
+  BrowserRefresh: 'BrowserRefresh',
+  BrowserSearch: 'BrowserSearch',
+  BrowserStop: 'BrowserStop',
+
+  // Special Keys
+  LaunchApp1: 'LaunchApp1',
+  LaunchApp2: 'LaunchApp2',
+  LaunchMail: 'LaunchMail',
+  MediaSelect: 'MediaSelect',
+  ContextMenu: 'ContextMenu',
+  Power: 'Power',
+  Sleep: 'Sleep',
+  WakeUp: 'WakeUp',
+
+  // International Keys
+  IntlBackslash: 'IntlBackslash',
+  IntlRo: 'IntlRo',
+  IntlYen: 'IntlYen',
+  KanaMode: 'KanaMode',
+  Lang1: 'Lang1',
+  Lang2: 'Lang2',
+  Convert: 'Convert',
+  NonConvert: 'NonConvert',
+} as const;
+
+export type KeyCode = keyof typeof keyCodes;
+
+export const characterMappings = {
+  '`': keyCodes.Backquote,
+  '-': keyCodes.Minus,
+  '=': keyCodes.Equal,
+  '[': keyCodes.BracketLeft,
+  ']': keyCodes.BracketRight,
+  '\\': keyCodes.Backslash,
+  ';': keyCodes.Semicolon,
+  "'": keyCodes.Quote,
+  ',': keyCodes.Comma,
+  '.': keyCodes.Period,
+  '/': keyCodes.Slash,
+  up: 'ArrowUp',
+  down: 'ArrowDown',
+  left: 'ArrowLeft',
+  right: 'ArrowRight',
+} as const;
+
+export type CharacterKey = keyof typeof characterMappings;