/** * The global keymap: default shortcuts of every command, engine and UI, * matched against key presses by key code. * * Shortcuts are written in Lutra notation (`Mod+Alt+S`, `Mod` = Cmd on * macOS, Ctrl elsewhere) and come from the command list (`listCommands` * plus the UI commands); nothing here hard-codes a key. */ import { t } from "../i18n"; /** A parsed shortcut. */ export interface Shortcut { /** Ctrl must be held. */ ctrl: boolean; /** Meta (Cmd) must be held. */ meta: boolean; /** Alt (Option) must be held. */ alt: boolean; /** Shift must be held. */ shift: boolean; /** The key, lower case (`s`, `f4`, `enter`, `,`). */ key: string; } /** One binding of the keymap. */ export interface Binding { /** The command id. */ command: string; /** The shortcut that runs it. */ shortcut: Shortcut; } /** Whether the frontend runs on macOS, where `Mod` means Cmd. */ export function isMac(): boolean { return typeof navigator !== "undefined" && /Mac OS X|Macintosh|iPhone|iPad/.test(navigator.userAgent); } /** * Parses a shortcut in Lutra notation. * * @param text - for example `Mod+Alt+S`; a trailing `+` is the plus key * (`Mod++`). * @param mac - whether `Mod` means Cmd. * @returns the shortcut, or null when the text has no key or an unknown modifier. */ export function parseShortcut(text: string, mac: boolean): Shortcut | null { const plusKey = text.endsWith("++"); const parts = (plusKey ? text.slice(0, -2) : text).split("+").map((part) => part.trim().toLowerCase()); const key = plusKey ? "+" : parts.pop(); if (key === undefined || key === "") { return null; } const shortcut: Shortcut = { ctrl: false, meta: false, alt: false, shift: false, key }; for (const part of parts) { switch (part) { case "": if (!plusKey) { return null; } break; case "mod": if (mac) { shortcut.meta = true; } else { shortcut.ctrl = true; } break; case "ctrl": shortcut.ctrl = true; break; case "cmd": case "meta": shortcut.meta = true; break; case "alt": shortcut.alt = true; break; case "shift": shortcut.shift = true; break; default: return null; } } return shortcut; } /** Punctuation keys by `KeyboardEvent.code`, as the US layout labels them. */ const PUNCTUATION: Readonly> = { Comma: ",", Period: ".", Slash: "/", Semicolon: ";", Quote: "'", BracketLeft: "[", BracketRight: "]", Backslash: "\\", Minus: "-", Equal: "=", Backquote: "`", }; /** * The key of an event, independent of the keyboard layout effects of Alt * and Shift for letters, digits and punctuation (`Alt+S` on macOS types * `ß`, `Shift+1` types `!`). * * @param event - the key event. */ export function eventKey(event: KeyboardEvent): string { const code = event.code; if (/^Key[A-Z]$/.test(code)) { return code.slice(3).toLowerCase(); } if (/^(Digit|Numpad)[0-9]$/.test(code)) { return code.slice(-1); } const punctuation = PUNCTUATION[code]; if (punctuation !== undefined) { return punctuation; } return event.key.toLowerCase(); } /** * Whether a key event matches a shortcut exactly. * * @param event - the key event. * @param shortcut - the shortcut. */ export function matches(event: KeyboardEvent, shortcut: Shortcut): boolean { return ( event.ctrlKey === shortcut.ctrl && event.metaKey === shortcut.meta && event.altKey === shortcut.alt && event.shiftKey === shortcut.shift && eventKey(event) === shortcut.key ); } /** * Builds the keymap from command descriptions. Commands without a shortcut * or with one that does not parse are left out; when two commands share a * shortcut, the first one listed wins. * * @param commands - id and default shortcut of each command. * @param mac - whether `Mod` means Cmd. */ export function buildKeymap( commands: readonly { id: string; defaultShortcut?: string | null | undefined }[], mac: boolean, ): Binding[] { const keymap: Binding[] = []; for (const command of commands) { const raw: unknown = command.defaultShortcut; const shortcut = typeof raw === "string" ? parseShortcut(raw, mac) : null; if (shortcut) { keymap.push({ command: command.id, shortcut }); } } return keymap; } /** * The command a key event triggers. * * @param keymap - the keymap. * @param event - the key event. * @returns the command id, or null. */ export function commandFor(keymap: readonly Binding[], event: KeyboardEvent): string | null { return keymap.find((binding) => matches(event, binding.shortcut))?.command ?? null; } /** * Formats a shortcut for display: modifier names from the catalog, in the * order Ctrl, Alt, Shift, Cmd, and the key in upper case * (`Ctrl+Shift+P`, `Cmd+,`). * * @param text - the shortcut in Lutra notation. * @param mac - whether `Mod` means Cmd. * @returns the display text, or null when the shortcut does not parse. */ export function formatShortcut(text: string, mac: boolean): string | null { const shortcut = parseShortcut(text, mac); if (shortcut === null) { return null; } const parts: string[] = []; if (shortcut.ctrl) { parts.push(t("command.key.ctrl")); } if (shortcut.alt) { parts.push(mac ? t("command.key.option") : t("command.key.alt")); } if (shortcut.shift) { parts.push(t("command.key.shift")); } if (shortcut.meta) { parts.push(t("command.key.cmd")); } const key = shortcut.key; parts.push(key.length === 1 ? key.toUpperCase() : key.charAt(0).toUpperCase() + key.slice(1)); return parts.join("+"); }