feat(e10): put every keyboard shortcut in one table
Six surfaces each owned a private keydown listener with its own key literals and its own idea of "am I typing?", and they had drifted: PlexPlayer matched `case "a"` without checking modifiers, so Ctrl+A (select all) cycled the audio track, and its typing guard missed <select> and contentEditable where the other two surfaces covered both. lib/keymap.ts is a TABLE, not a dispatcher. Each surface keeps its own listener and closures - PlexPlayer's refs are not worth re-plumbing - but the chords, the modifier rules and the typing guard live in one place, and dispatch() binds a scope's rows to handlers through a mapped type, so a row without a handler (or a handler without a row) is a tsc error rather than a comment someone forgets. Matching is now exact on modifiers, which is what kills the Ctrl+A bug and lets Shift+arrow be its own row beside the bare arrow. Escape opts out of the typing guard (allowInInput) so it stays the way out of a player's own subtitle-offset field. The player's shortcut sheet renders helpLines() instead of a hand-copied array beside the handler - the two used to be edited separately, which is how a sheet ends up documenting a key that no longer exists. Labels move to the new `keys` i18n namespace (EN + HU), and a test asserts every row is named in both.
This commit is contained in:
@@ -0,0 +1,238 @@
|
||||
// ── The app's ONE keyboard map ────────────────────────────────────────────────────────────────
|
||||
// Before E10 S3 six surfaces each owned a private `keydown` listener with its own key literals and
|
||||
// its own idea of "am I typing?" — and they had drifted: `PlexPlayer` matched `case "a"` without
|
||||
// checking modifiers (so Ctrl+A, select-all, cycled the audio track) and its typing guard missed
|
||||
// `<select>` and `contentEditable`, which the other two surfaces already covered. The classic
|
||||
// comment-vs-code drift this codebase keeps getting bitten by, one layer up.
|
||||
//
|
||||
// The fix is a TABLE, not a dispatcher. Each surface keeps its own listener and its own closures —
|
||||
// `PlexPlayer`'s 1300 lines of refs are not worth re-plumbing — but the key literals, the modifier
|
||||
// rules and the typing guard all live here, and `dispatch()` binds a scope's rows to handlers with
|
||||
// a mapped type. So a row without a handler (or a handler without a row) is a **tsc error**, not a
|
||||
// comment someone forgets: the parity is enforced by the gate, which is the house rule.
|
||||
//
|
||||
// It is also the source for the keyboard help sheet — every shortcut in the app is listed here, in
|
||||
// one place, and the sheet renders this table rather than a hand-copied array beside it.
|
||||
|
||||
/** Which surface a shortcut belongs to. `global` is live app-wide; the rest only while that surface
|
||||
* is mounted. The help sheet shows `global` plus the topmost registered scope. */
|
||||
export type KeyScope = "global" | "undo" | "ytPlayer" | "plexPlayer" | "plexBrowse";
|
||||
|
||||
/** Extra render condition for the help sheet (the shortcut itself is always live). */
|
||||
type ShortcutWhen = "episode";
|
||||
|
||||
export interface Shortcut {
|
||||
/** Unique within its scope; the handler key `dispatch()` demands. */
|
||||
readonly id: string;
|
||||
readonly scope: KeyScope;
|
||||
/** Chords that trigger it, in the `matches()` mini-syntax. All are listed in the help sheet. */
|
||||
readonly keys: readonly string[];
|
||||
/** i18n key (the `keys` namespace) for the description. Rows SHARING a labelKey are shown as one
|
||||
* help line with their chords side by side — that is how "← → Seek" stays a single row. */
|
||||
readonly labelKey: string;
|
||||
readonly when?: ShortcutWhen;
|
||||
/** Fires even while a text field has focus. Escape only: it is the universal "get me out of here",
|
||||
* and a player whose Escape died inside its own subtitle-offset input is a trap. Every other
|
||||
* shortcut stays out of the way of typing. */
|
||||
readonly allowInInput?: boolean;
|
||||
}
|
||||
|
||||
// Chord syntax: `Mod` = Ctrl on Windows/Linux, ⌘ on macOS. `Shift`/`Alt` are literal. The final
|
||||
// segment is a `KeyboardEvent.key` name, except `Space` (which also accepts `code`, because a
|
||||
// focused button reports `key === " "` inconsistently across engines).
|
||||
export const SHORTCUTS = [
|
||||
// --- global ---------------------------------------------------------------------------------
|
||||
{ id: "contextMenu", scope: "global", keys: ["Shift+F10"], labelKey: "keys.contextMenu" },
|
||||
|
||||
// --- undo/redo (wherever an UndoToolbar is mounted) -----------------------------------------
|
||||
{ id: "undo", scope: "undo", keys: ["Mod+z"], labelKey: "keys.undo" },
|
||||
{ id: "redo", scope: "undo", keys: ["Mod+y", "Mod+Shift+z"], labelKey: "keys.redo" },
|
||||
|
||||
// --- the YouTube player modal ---------------------------------------------------------------
|
||||
{ id: "playPause", scope: "ytPlayer", keys: ["Space"], labelKey: "keys.playPause" },
|
||||
{ id: "fullscreen", scope: "ytPlayer", keys: ["f"], labelKey: "keys.fullscreen" },
|
||||
{ id: "seekBack", scope: "ytPlayer", keys: ["ArrowLeft"], labelKey: "keys.seek5" },
|
||||
{ id: "seekFwd", scope: "ytPlayer", keys: ["ArrowRight"], labelKey: "keys.seek5" },
|
||||
{ id: "prevVideo", scope: "ytPlayer", keys: ["Shift+ArrowLeft"], labelKey: "keys.video" },
|
||||
{ id: "nextVideo", scope: "ytPlayer", keys: ["Shift+ArrowRight"], labelKey: "keys.video" },
|
||||
{ id: "volumeUp", scope: "ytPlayer", keys: ["ArrowUp"], labelKey: "keys.volume" },
|
||||
{ id: "volumeDown", scope: "ytPlayer", keys: ["ArrowDown"], labelKey: "keys.volume" },
|
||||
{
|
||||
id: "close",
|
||||
scope: "ytPlayer",
|
||||
keys: ["Escape"],
|
||||
labelKey: "keys.closePlayer",
|
||||
allowInInput: true,
|
||||
},
|
||||
|
||||
// --- the Plex player ------------------------------------------------------------------------
|
||||
{ id: "playPause", scope: "plexPlayer", keys: ["Space", "k"], labelKey: "keys.playPause" },
|
||||
{ id: "fullscreen", scope: "plexPlayer", keys: ["f"], labelKey: "keys.fullscreen" },
|
||||
{ id: "seekBack", scope: "plexPlayer", keys: ["ArrowLeft"], labelKey: "keys.seek" },
|
||||
{ id: "seekFwd", scope: "plexPlayer", keys: ["ArrowRight"], labelKey: "keys.seek" },
|
||||
{ id: "fineBack", scope: "plexPlayer", keys: ["Mod+ArrowLeft"], labelKey: "keys.fineSeek" },
|
||||
{ id: "fineFwd", scope: "plexPlayer", keys: ["Mod+ArrowRight"], labelKey: "keys.fineSeek" },
|
||||
{
|
||||
id: "prevEpisode",
|
||||
scope: "plexPlayer",
|
||||
keys: ["Shift+ArrowLeft"],
|
||||
labelKey: "keys.episode",
|
||||
when: "episode",
|
||||
},
|
||||
{
|
||||
id: "nextEpisode",
|
||||
scope: "plexPlayer",
|
||||
keys: ["Shift+ArrowRight"],
|
||||
labelKey: "keys.episode",
|
||||
when: "episode",
|
||||
},
|
||||
{ id: "volumeUp", scope: "plexPlayer", keys: ["ArrowUp"], labelKey: "keys.volume" },
|
||||
{ id: "volumeDown", scope: "plexPlayer", keys: ["ArrowDown"], labelKey: "keys.volume" },
|
||||
{ id: "mute", scope: "plexPlayer", keys: ["m"], labelKey: "keys.mute" },
|
||||
{ id: "audio", scope: "plexPlayer", keys: ["a"], labelKey: "keys.audio" },
|
||||
{ id: "subtitle", scope: "plexPlayer", keys: ["s"], labelKey: "keys.subtitle" },
|
||||
{ id: "help", scope: "plexPlayer", keys: ["h"], labelKey: "keys.help" },
|
||||
{ id: "info", scope: "plexPlayer", keys: ["i"], labelKey: "keys.info" },
|
||||
{ id: "stats", scope: "plexPlayer", keys: ["d"], labelKey: "keys.stats" },
|
||||
// Two rows, one help line: ⌫ is the plain "stop & out", Escape is the layer-aware cascade (defer to
|
||||
// anything above → cancel auto-skip → close the topmost player overlay → close). Sharing a labelKey
|
||||
// keeps them a single "⌫ Esc Stop & back to feed" row in the sheet.
|
||||
{ id: "back", scope: "plexPlayer", keys: ["Backspace"], labelKey: "keys.back" },
|
||||
{
|
||||
id: "escape",
|
||||
scope: "plexPlayer",
|
||||
keys: ["Escape"],
|
||||
labelKey: "keys.back",
|
||||
allowInInput: true,
|
||||
},
|
||||
|
||||
// --- the Plex browser (drill-down) ----------------------------------------------------------
|
||||
{ id: "back", scope: "plexBrowse", keys: ["Backspace"], labelKey: "keys.browseBack" },
|
||||
] as const satisfies readonly Shortcut[];
|
||||
|
||||
// `as const` keeps the ids literal (that is what makes `dispatch`'s handler map exhaustive), but it
|
||||
// also narrows each row to its own shape — so the optional `when`/`allowInInput` vanish from rows
|
||||
// that omit them. Iterate through this widened view; read ids through `Row`.
|
||||
const ROWS: readonly Shortcut[] = SHORTCUTS;
|
||||
|
||||
type Row = (typeof SHORTCUTS)[number];
|
||||
/** The shortcut ids defined for one scope — the exact handler keys `dispatch()` requires. */
|
||||
export type ShortcutId<S extends KeyScope> = Extract<Row, { scope: S }>["id"];
|
||||
|
||||
/** True while focus sits somewhere that swallows plain keys. The ONE definition: before S3 the
|
||||
* players disagreed about `<select>` and `contentEditable`, so the same keystroke was a shortcut in
|
||||
* one and text in the other. Reads `e.target` (the focused node for a keydown) and falls back to
|
||||
* `document.activeElement` for synthetic events that carry no target. */
|
||||
export function isTypingTarget(e: KeyboardEvent): boolean {
|
||||
const el = (e.target as HTMLElement | null) ?? (document.activeElement as HTMLElement | null);
|
||||
if (!el) return false;
|
||||
const tag = (el.tagName || "").toLowerCase();
|
||||
return tag === "input" || tag === "textarea" || tag === "select" || !!el.isContentEditable;
|
||||
}
|
||||
|
||||
/** True while focus is on something Space/Enter activates natively. Both players defer Space to a
|
||||
* focused button ("Skip intro") rather than toggling playback; this is that shared rule. */
|
||||
export function isActivationTarget(e: KeyboardEvent): boolean {
|
||||
const el = (e.target as HTMLElement | null) ?? (document.activeElement as HTMLElement | null);
|
||||
const tag = (el?.tagName || "").toLowerCase();
|
||||
return tag === "button" || tag === "a";
|
||||
}
|
||||
|
||||
function keyMatches(e: KeyboardEvent, name: string): boolean {
|
||||
if (name === "Space") return e.key === " " || e.code === "Space";
|
||||
if (name.length === 1) return e.key.toLowerCase() === name.toLowerCase();
|
||||
return e.key === name;
|
||||
}
|
||||
|
||||
/** Match one chord EXACTLY, modifiers included. Exactness is the point: `case "a"` used to fire on
|
||||
* Ctrl+A too, so select-all cycled the Plex audio track. It also means Shift+H is not `h` — a
|
||||
* narrowing from the old `case "h": case "H":`, and the reason Shift chords can now be their own
|
||||
* rows (Shift+← steps an episode without ← also seeking). */
|
||||
export function matches(e: KeyboardEvent, chord: string): boolean {
|
||||
const parts = chord.split("+");
|
||||
const key = parts[parts.length - 1] ?? "";
|
||||
const mods = parts.slice(0, -1).map((m) => m.toLowerCase());
|
||||
if ((e.ctrlKey || e.metaKey) !== mods.includes("mod")) return false;
|
||||
if (e.shiftKey !== mods.includes("shift")) return false;
|
||||
if (e.altKey !== mods.includes("alt")) return false;
|
||||
return keyMatches(e, key);
|
||||
}
|
||||
|
||||
/** Run `scope`'s map against an event. Returns true when a shortcut matched (the handler decides
|
||||
* whether to `preventDefault`, because only it knows if it actually acted). `handlers` is a mapped
|
||||
* type over the scope's ids, so the table and the implementation cannot drift without tsc saying
|
||||
* so. Skipped while typing unless the row opts in with `allowInInput` (Escape, and only Escape). */
|
||||
export function dispatch<S extends KeyScope>(
|
||||
e: KeyboardEvent,
|
||||
scope: S,
|
||||
handlers: { readonly [K in ShortcutId<S>]: (e: KeyboardEvent) => void },
|
||||
): boolean {
|
||||
const typing = isTypingTarget(e);
|
||||
for (const s of ROWS) {
|
||||
if (s.scope !== scope) continue;
|
||||
if (typing && !s.allowInInput) continue;
|
||||
if (!s.keys.some((k) => matches(e, k))) continue;
|
||||
(handlers as Record<string, (ev: KeyboardEvent) => void>)[s.id]?.(e);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
// ── Display ───────────────────────────────────────────────────────────────────────────────────
|
||||
const GLYPHS: Record<string, string> = {
|
||||
ArrowLeft: "←",
|
||||
ArrowRight: "→",
|
||||
ArrowUp: "↑",
|
||||
ArrowDown: "↓",
|
||||
Backspace: "⌫",
|
||||
Escape: "Esc",
|
||||
Shift: "⇧",
|
||||
};
|
||||
|
||||
const isMac = (): boolean =>
|
||||
typeof navigator !== "undefined" && /mac|iphone|ipad/i.test(navigator.userAgent);
|
||||
|
||||
/** A chord as the help sheet shows it: `Mod+Shift+z` → `Ctrl ⇧ Z` (`⌘ ⇧ Z` on a Mac). */
|
||||
export function formatChord(chord: string): string {
|
||||
return chord
|
||||
.split("+")
|
||||
.map((part, i, all) => {
|
||||
if (part.toLowerCase() === "mod") return isMac() ? "⌘" : "Ctrl";
|
||||
if (i < all.length - 1) return GLYPHS[part] ?? part;
|
||||
return GLYPHS[part] ?? (part.length === 1 ? part.toUpperCase() : part);
|
||||
})
|
||||
.join(" ");
|
||||
}
|
||||
|
||||
/** One help-sheet line: every chord that shares a description, in table order. */
|
||||
export interface HelpLine {
|
||||
labelKey: string;
|
||||
chords: string[];
|
||||
when?: ShortcutWhen;
|
||||
}
|
||||
|
||||
/** The shortcuts of `scopes`, grouped into help lines by description. Scopes come out in the order
|
||||
* ASKED FOR, rows within a scope in table order — so a surface passing its own scope first heads its
|
||||
* sheet with its own keys and leaves the app-wide ones underneath, where they read as context. */
|
||||
export function helpLines(scopes: readonly KeyScope[]): HelpLine[] {
|
||||
const out: HelpLine[] = [];
|
||||
const byLabel = new Map<string, HelpLine>();
|
||||
for (const scope of scopes) {
|
||||
for (const s of ROWS) {
|
||||
if (s.scope !== scope) continue;
|
||||
const existing = byLabel.get(s.labelKey);
|
||||
if (existing) {
|
||||
existing.chords.push(...s.keys);
|
||||
continue;
|
||||
}
|
||||
const line: HelpLine = {
|
||||
labelKey: s.labelKey,
|
||||
chords: [...s.keys],
|
||||
...(s.when && { when: s.when }),
|
||||
};
|
||||
byLabel.set(s.labelKey, line);
|
||||
out.push(line);
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
Reference in New Issue
Block a user