useKeyboardShortcut

1"use client"
2 
3import * as React from "react"
4 
5export interface UseKeyboardShortcutOptions {
6  /** Turn the listener off (e.g. a shortcut that only applies while a panel is open). Defaults to true. */
7  enabled?: boolean
8  /** Call `event.preventDefault()` on a match, blocking the browser's own behaviour (⌘S saves the page, ⌘K jumps to the address bar). Defaults to true. */
9  preventDefault?: boolean
10  /** Don't fire while focus is in an input / textarea / select / contenteditable. Defaults to true. */
11  ignoreInputs?: boolean
12  /**
13   * Where to attach the listener, `window` by default. Pass a node, or a ref object — the latter is
14   * the only reliable way to scope a shortcut to a container: `ref.current` is still null on the
15   * first render and assigning to a ref triggers no re-render, so passing `ref.current` leaves the
16   * listener on window forever.
17   */
18  target?: EventTarget | React.RefObject<EventTarget | null> | null
19}
20 
21interface ParsedShortcut {
22  key: string
23  mod: boolean
24  ctrl: boolean
25  meta: boolean
26  shift: boolean
27  alt: boolean
28}
29 
30/** Human spelling → the lower-cased `KeyboardEvent.key` value. */
31const KEY_ALIASES: Record<string, string> = {
32  esc: "escape",
33  space: " ",
34  spacebar: " ",
35  plus: "+",
36  up: "arrowup",
37  down: "arrowdown",
38  left: "arrowleft",
39  right: "arrowright",
40  return: "enter",
41  del: "delete",
42}
43 
44/** Parses "mod+shift+k" into a structured shortcut; returns null when only modifiers were given and no actual key. */
45function parseShortcut(combo: string): ParsedShortcut | null {
46  const parsed: ParsedShortcut = {
47    key: "",
48    mod: false,
49    ctrl: false,
50    meta: false,
51    shift: false,
52    alt: false,
53  }
54 
55  const parts = combo
56    .toLowerCase()
57    .split("+")
58    .map(part => part.trim())
59    .filter(Boolean)
60 
61  for (const part of parts) {
62    switch (part) {
63      case "mod":
64        parsed.mod = true
65        break
66      case "ctrl":
67      case "control":
68        parsed.ctrl = true
69        break
70      case "meta":
71      case "cmd":
72      case "command":
73        parsed.meta = true
74        break
75      case "shift":
76        parsed.shift = true
77        break
78      case "alt":
79      case "option":
80        parsed.alt = true
81        break
82      default:
83        parsed.key = KEY_ALIASES[part] ?? part
84    }
85  }
86 
87  return parsed.key ? parsed : null
88}
89 
90/** `mod` is ⌘ on Apple platforms and Ctrl elsewhere. Called from effects only — navigator is never read during render. */
91// … truncated