M1.8: command palette, global keymap, UI commands

- Engine: ui.registerCommands (validated, replaces the previous set),
  UI commands in listCommands with ui: true and labelKey, running one
  through the engine emits uiCommand {id, params}.
- Frontend: ui/src/commands/ (keymap by key code, fuzzy ranking, Pinia
  commands store with handlers, recents and error toasts), the command
  palette (Mod+Shift+P), UI commands palette.open, settings.open (Mod+,,
  disabled until M1.9b) and view.toggleProjectTree (Mod+1). The editor's
  shortcuts.ts moved into the global keymap.
- Tests: engine and control-channel tests for registration and
  uiCommand, Vitest for keymap, ranking, store, palette and App wiring.
- Docs: architecture, ui-parity, target-app-parity, gaps, roadmap,
  ROADMAP, README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-16 16:59:43 +02:00
parent 2f8fef876b
commit 184b8a3468
33 changed files with 2282 additions and 233 deletions

205
ui/src/commands/keymap.ts Normal file
View file

@ -0,0 +1,205 @@
/**
* 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<Record<string, string>> = {
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("+");
}