feat(studio): shortcut combos in the key resolver

This commit is contained in:
Miguel Angel Simon Sierra
2026-11-01 19:27:00 -05:00
parent 7c5c1ce849
commit 252d9ef4da
3 changed files with 174 additions and 14 deletions
@@ -0,0 +1,77 @@
// @vitest-environment happy-dom
import { afterEach, describe, expect, it, vi } from "vitest";
import { formatCombo, matchCombo, parseCombo } from "./studioCombo";
import { getStudioKey, keyHint, matchesKey, setStudioKeys } from "./studioShortcuts";
afterEach(() => {
setStudioKeys(null);
vi.restoreAllMocks();
});
const press = (init: KeyboardEventInit) => new KeyboardEvent("keydown", init);
const matches = (text: string, init: KeyboardEventInit) => matchCombo(press(init), parseCombo(text)!);
describe("combo model", () => {
it("parses characters, named keys and modifiers", () => {
expect(parseCombo("B")).toMatchObject({ key: "b", named: false });
expect(parseCombo("Space")).toMatchObject({ key: "Space", named: true });
expect(parseCombo("mod+shift+z")).toMatchObject({ mod: true, shift: true, key: "z" });
expect(parseCombo("cmd++")).toMatchObject({ meta: true, key: "+" });
});
it("refuses what cannot be matched: modifier-only, unknown, empty, and Ctrl+Alt (AltGr on Windows)", () => {
for (const bad of ["ctrl", "shift+", "", "mod+ab", "hyper+x", "ctrl+alt+x", "mod+alt+x", "Spacebar"]) {
expect(parseCombo(bad), bad).toBeNull();
}
expect(parseCombo("cmd+alt+x")).not.toBeNull();
});
it("mod is Cmd or Ctrl; cmd and ctrl are exact; extra modifiers never match", () => {
expect(matches("mod+c", { key: "c", metaKey: true })).toBe(true);
expect(matches("mod+c", { key: "c", ctrlKey: true })).toBe(true);
expect(matches("mod+c", { key: "c" })).toBe(false);
expect(matches("mod+c", { key: "c", metaKey: true, shiftKey: true })).toBe(false);
expect(matches("cmd+c", { key: "c", ctrlKey: true })).toBe(false);
expect(matches("c", { key: "c", metaKey: true })).toBe(false);
});
it("characters match e.key (so layouts follow the typed letter), named keys match e.code", () => {
expect(matches("a", { key: "a", code: "KeyQ" })).toBe(true);
expect(matches("a", { key: "q", code: "KeyA" })).toBe(false);
expect(matches("Space", { key: " ", code: "Space" })).toBe(true);
expect(matches("shift+ArrowLeft", { key: "ArrowLeft", code: "ArrowLeft", shiftKey: true })).toBe(true);
expect(matches("alt+shift+d", { key: "∂", code: "KeyD", altKey: true, shiftKey: true })).toBe(true);
});
it("formats like the shortcut lists do", () => {
expect(formatCombo(parseCombo("mod+shift+z")!)).toBe("⌘⇧Z");
expect(formatCombo(parseCombo("alt+shift+d")!)).toBe("⌥⇧D");
expect(formatCombo(parseCombo("ArrowLeft")!)).toBe("←");
expect(formatCombo(parseCombo("[")!)).toBe("[");
});
});
describe("resolver with combos", () => {
it("accepts a combo for an action that today takes a single key, and the list follows", () => {
setStudioKeys({ fullscreen: "mod+shift+f" });
expect(getStudioKey("fullscreen")).toBe("mod+shift+f");
expect(keyHint("fullscreen")).toBe("⌘⇧F");
expect(matchesKey(press({ key: "F", metaKey: true, shiftKey: true }), "fullscreen")).toBe(true);
expect(matchesKey(press({ key: "f" }), "fullscreen")).toBe(false);
});
it("keeps a single character working and canonical", () => {
setStudioKeys({ mute: "X" });
expect(getStudioKey("mute")).toBe("x");
expect(matchesKey(press({ key: "x" }), "mute")).toBe(true);
});
it("refuses a map with an AltGr combo or two actions on one combo, keeping every default", () => {
vi.spyOn(console, "warn").mockImplementation(() => {});
setStudioKeys({ mute: "ctrl+alt+m" });
expect(getStudioKey("mute")).toBe("m");
setStudioKeys({ mute: "mod+k", record: "cmd+k" });
expect(getStudioKey("mute")).toBe("m");
expect(getStudioKey("record")).toBe("r");
});
});
@@ -0,0 +1,84 @@
export interface Combo {
mod: boolean;
meta: boolean;
ctrl: boolean;
shift: boolean;
alt: boolean;
key: string;
named: boolean;
}
const NAMED = new Set([
"Space",
"ArrowLeft",
"ArrowRight",
"ArrowUp",
"ArrowDown",
"Home",
"End",
"PageUp",
"PageDown",
"Delete",
"Backspace",
"Escape",
"Enter",
"Tab",
]);
const SYMBOL: Record<string, string> = {
ArrowLeft: "←",
ArrowRight: "→",
ArrowUp: "↑",
ArrowDown: "↓",
Delete: "Del",
Backspace: "⌫",
Escape: "Esc",
};
const MODIFIERS = new Set(["mod", "cmd", "ctrl", "shift", "alt"]);
/** "mod+shift+z", "Space", "b": mod is Cmd or Ctrl; Ctrl+Alt is refused because Windows sends AltGr as Ctrl+Alt. */
export function parseCombo(text: string): Combo | null {
const match = /^((?:[A-Za-z]+\+)*)(.+)$/.exec(text);
if (!match) return null;
const tokens = match[1].split("+").filter(Boolean).map((t) => t.toLowerCase());
const key = match[2];
const named = NAMED.has(key);
if (tokens.some((t) => !MODIFIERS.has(t)) || (!named && [...key].length !== 1)) return null;
const combo = {
mod: tokens.includes("mod"),
meta: tokens.includes("cmd"),
ctrl: tokens.includes("ctrl"),
shift: tokens.includes("shift"),
alt: tokens.includes("alt"),
key: named ? key : key.toLowerCase(),
named,
};
return combo.alt && (combo.ctrl || combo.mod) ? null : combo;
}
/** The one string a combo is stored and compared as. */
export function comboText(c: Combo): string {
const mods = [c.mod && "mod", c.meta && "cmd", c.ctrl && "ctrl", c.alt && "alt", c.shift && "shift"];
return [...mods.filter(Boolean), c.key].join("+");
}
function charMatches(e: KeyboardEvent, c: Combo): boolean {
if (e.key.toLowerCase() === c.key) return true;
// Option rewrites e.key on macOS (Option+D is "∂"), so fall back to the physical key.
const code = /^[0-9]$/.test(c.key) ? `Digit${c.key}` : `Key${c.key.toUpperCase()}`;
return e.altKey && /^[a-z0-9]$/.test(c.key) && e.code === code;
}
export function matchCombo(e: KeyboardEvent, c: Combo): boolean {
if (e.shiftKey !== c.shift || e.altKey !== c.alt) return false;
const modsOk = c.mod ? e.metaKey || e.ctrlKey : e.metaKey === c.meta && e.ctrlKey === c.ctrl;
return modsOk && (c.named ? e.code === c.key : charMatches(e, c));
}
export function formatCombo(c: Combo): string {
const mods = `${c.ctrl ? "⌃" : ""}${c.alt ? "⌥" : ""}${c.mod || c.meta ? "⌘" : ""}${c.shift ? "⇧" : ""}`;
return mods + (SYMBOL[c.key] ?? (c.named ? c.key : c.key.toUpperCase()));
}
/** Two combos clash when one press could satisfy both; Cmd and Ctrl both count as mod. */
export const comboClashKey = (c: Combo) =>
[c.mod || c.meta || c.ctrl, c.alt, c.shift, c.key].join("|");
@@ -1,4 +1,5 @@
import { useSyncExternalStore } from "react";
import { comboClashKey, comboText, formatCombo, matchCombo, parseCombo } from "./studioCombo";
/** Every single-character bare key Studio answers, by action. */
export const DEFAULT_STUDIO_KEYS = {
@@ -44,9 +45,10 @@ const sharedByDesign = (a: StudioKeyAction, b: StudioKeyAction) =>
function findClash(keys: StudioKeys): string | null {
const actions = Object.keys(keys) as StudioKeyAction[];
const clashKey = (action: StudioKeyAction) => comboClashKey(parseCombo(keys[action])!);
for (const [i, a] of actions.entries()) {
for (const b of actions.slice(i + 1)) {
if (keys[a] === keys[b] && !sharedByDesign(a, b)) return `${a} and ${b} both on "${keys[a]}"`;
if (clashKey(a) === clashKey(b) && !sharedByDesign(a, b)) return `${a} and ${b} both on "${keys[a]}"`;
}
}
return null;
@@ -54,18 +56,13 @@ function findClash(keys: StudioKeys): string | null {
function resolve(overrides: Partial<Record<StudioKeyAction, string>>): StudioKeys {
const next: Record<string, string> = { ...DEFAULT_STUDIO_KEYS };
for (const [action, key] of Object.entries(overrides)) {
if (
!Object.hasOwn(DEFAULT_STUDIO_KEYS, action) ||
typeof key !== "string" ||
[...key].length !== 1
) {
console.warn(
`Studio keys: using defaults, "${action}" is not a known action with one character`,
);
for (const [action, text] of Object.entries(overrides)) {
const combo = typeof text === "string" ? parseCombo(text) : null;
if (!Object.hasOwn(DEFAULT_STUDIO_KEYS, action) || !combo) {
console.warn(`Studio keys: using defaults, "${action}" is not a known action with a valid combo`);
return DEFAULT_STUDIO_KEYS;
}
next[action] = key.toLowerCase();
next[action] = comboText(combo);
}
const clash = findClash(next as StudioKeys);
if (!clash) return next as StudioKeys;
@@ -104,10 +101,12 @@ export interface ShortcutSection {
hints: readonly ShortcutHint[];
}
const hintKey = (key: string) => key.toUpperCase();
export const keyHint = (action: StudioKeyAction, keys: StudioKeys = current) =>
hintKey(keys[action]);
formatCombo(parseCombo(keys[action])!);
/** True when the event is the combo the host (or the default) set for this action. */
export const matchesKey = (e: KeyboardEvent, action: StudioKeyAction) =>
matchCombo(e, parseCombo(current[action])!);
export function buildShortcutSections(keys: StudioKeys): readonly ShortcutSection[] {
const k = (action: StudioKeyAction) => keyHint(action, keys);