components/shortcuts/shortcuts.ts

Functions

Imports

It imports components/dialog/dialog.ts, components/shell/shell.ts. Imported by components/command-menu/command-menu.react.tsx, components/command-menu/command-menu.ts, components/moderation-queue/moderation-queue.ts, components/shortcuts/shortcuts.react.tsx.

Source

1// The keyboard shortcut registry and the "?" sheet that lists it (the shared dialog,
2// components/dialog). One document keydown listener for the whole app. Single-key shortcuts (a letter, "?", a sequence like "g o")
3// can be switched off and the choice is remembered (WCAG 2.1.4); shortcuts with Ctrl, Cmd
4// or Alt always work. No framework; the React wrapper uses the same registry.
5import { readPref, writePref } from "../shell/shell.ts";
6import { openDialog, uid, wireDialog } from "../dialog/dialog.ts";
7
8export interface Shortcut {
9  // "r", "?", "g o" (a sequence: g, then o within 1200 ms), "Mod+k" (Ctrl, or Cmd on a
10  // Mac), "Ctrl+Enter", "Alt+n". An array gives one command several keys.
11  key: string | string[];
12  label: string;
13  // One line under the label in the sheet, saying what the command is for: what a view is
14  // for lives here, not in an intro sentence under every heading.
15  about?: string;
16  group: string;
17  run: (e: KeyboardEvent) => void;
18  // Runs only while this returns true.
19  when?: () => boolean;
20}
21
22export const SINGLE_KEYS_PREF = "cap-single-keys";
23// The line under the switch, shared by the built sheet and the React one.
24export const SINGLE_KEYS_NOTE = "Turn these off if they clash with a screen reader or speech input. It applies at once. Shortcuts with Ctrl or ⌘ keep working.";
25export const SEQUENCE_MS = 1200;
26
27const entries: Shortcut[] = [];
28let installed = false;
29let singleOverride: boolean | null = null;
30let pending: { step: string; at: number } | null = null;
31let sheetOpener: () => void = () => openShortcutSheet();
32
33interface Combo {
34  key: string;
35  ctrl: boolean;
36  meta: boolean;
37  alt: boolean;
38  mod: boolean;
39}
40
41export function isMac(): boolean {
42  return typeof navigator !== "undefined" && /Mac|iPhone|iPad|iPod/.test(navigator.userAgent);
43}
44
45function parseStep(step: string): Combo {
46  if (step.length === 1) return { key: step, ctrl: false, meta: false, alt: false, mod: false };
47  const parts = step.split("+");
48  let key = parts.pop() ?? "";
49  if (key === "") key = "+";
50  const mods = parts.map((m) => m.toLowerCase());
51  return {
52    key,
53    ctrl: mods.includes("ctrl") || mods.includes("control"),
54    meta: mods.includes("meta") || mods.includes("cmd"),
55    alt: mods.includes("alt") || mods.includes("option"),
56    mod: mods.includes("mod"),
57  };
58}
59
60const specsOf = (s: Shortcut): string[] => (Array.isArray(s.key) ? s.key : [s.key]);
61const stepsOf = (spec: string): string[] => spec.trim().split(/\s+/);
62
63// A single-key shortcut is one a person can press by accident while typing or speaking:
64// no Ctrl, Cmd or Alt in any step.
65export function isSingleKey(spec: string): boolean {
66  return stepsOf(spec).every((step) => {
67    const c = parseStep(step);
68    return !c.ctrl && !c.meta && !c.alt && !c.mod;
69  });
70}
71
72function matchesStep(step: string, e: KeyboardEvent): boolean {
73  const c = parseStep(step);
74  const mac = isMac();
75  const ctrl = c.ctrl || (c.mod && !mac);
76  const meta = c.meta || (c.mod && mac);
77  if (e.ctrlKey !== ctrl || e.metaKey !== meta || e.altKey !== c.alt) return false;
78  if (!ctrl && !meta && !c.alt) return e.key === c.key;
79  // With a modifier, case does not matter, and Alt's altered characters are read by code.
80  if (e.key.toLowerCase() === c.key.toLowerCase()) return true;
81  return /^[a-z]$/i.test(c.key) && e.code === `Key${c.key.toUpperCase()}`;
82}
83
84export function singleKeysOn(): boolean {
85  if (singleOverride !== null) return singleOverride;
86  return readPref(SINGLE_KEYS_PREF) !== "off";
87}
88
89// Turns single-key shortcuts on or off. Remembered in this browser unless remember is
90// false (a specimen, a test).
91export function setSingleKeys(on: boolean, opts: { remember?: boolean } = {}): void {
92  singleOverride = on;
93  if (opts.remember !== false) writePref(SINGLE_KEYS_PREF, on ? "on" : "off");
94  pending = null;
95  if (typeof document !== "undefined") document.dispatchEvent(new CustomEvent("cap-single-keys", { detail: { on } }));
96}
97
98// Keys typed into a field belong to the field. Checkboxes, radios and buttons are not
99// typing, so shortcuts still work while one has focus.
100const NOT_TYPING = new Set(["checkbox", "radio", "button", "submit", "reset", "range", "color", "file", "image"]);
101export function isTyping(target: EventTarget | null): boolean {
102  if (!(target instanceof Element)) return false;
103  if (target instanceof HTMLInputElement) return !NOT_TYPING.has(target.type);
104  if (target.closest("textarea, select")) return true;
105  return target instanceof HTMLElement && target.isContentEditable;
106}
107
108function modalOpen(): boolean {
109  try {
110    return !!document.querySelector("dialog:modal");
111  } catch {
112    return !!document.querySelector("dialog[open]");
113  }
114}
115
116function fire(s: Shortcut, e: KeyboardEvent): boolean {
117  if (s.when && !s.when()) return false;
118  e.preventDefault();
119  s.run(e);
120  return true;
121}
122
123function onKeyDown(e: KeyboardEvent): void {
124  if (e.defaultPrevented || e.isComposing) return;
125  if (e.key === "Shift" || e.key === "Control" || e.key === "Alt" || e.key === "Meta") return;
126  // A modal dialog owns the keyboard while it is open.
127  if (modalOpen()) {
128    pending = null;
129    return;
130  }
131  const singles = singleKeysOn() && !isTyping(e.target);
132  const now = Date.now();
133  const before = pending;
134  pending = null;
135
136  // The second key of a sequence.
137  if (before && singles && now - before.at <= SEQUENCE_MS) {
138    for (const s of entries) {
139      for (const spec of specsOf(s)) {
140        const steps = stepsOf(spec);
141        if (steps.length === 2 && steps[0] === before.step && matchesStep(steps[1] ?? "", e) && fire(s, e)) return;
142      }
143    }
144  }
145  // A one-step shortcut.
146  for (const s of entries) {
147    for (const spec of specsOf(s)) {
148      const steps = stepsOf(spec);
149      if (steps.length !== 1) continue;
150      if (isSingleKey(spec) && !singles) continue;
151      if (matchesStep(spec, e) && fire(s, e)) return;
152    }
153  }
154  // The first key of a sequence: wait for the second.
155  if (!singles) return;
156  for (const s of entries) {
157    for (const spec of specsOf(s)) {
158      const steps = stepsOf(spec);
159      const first = steps[0] ?? "";
160      if (steps.length === 2 && isSingleKey(spec) && matchesStep(first, e)) {
161        pending = { step: first, at: now };
162        return;
163      }
164    }
165  }
166}
167
168// Installs the one listener and the "?" shortcut. Called by register(); safe to call again.
169export function start(): void {
170  if (installed || typeof document === "undefined") return;
171  installed = true;
172  document.addEventListener("keydown", onKeyDown);
173  entries.unshift({ key: "?", label: "Show keyboard shortcuts", group: "General", run: () => sheetOpener() });
174}
175
176// The registered shortcut with Ctrl, Cmd or Alt that this key event matches, if any, and
177// whether its `when` allows it now. For a surface open over the page (the sheet) that lets
178// such a key through: the Portal's Ctrl K pressed in the help sheet closes the sheet and
179// opens the command menu. Keys that match nothing (Ctrl C) are left alone.
180export function modifiedShortcutFor(e: KeyboardEvent): Shortcut | undefined {
181  for (const s of entries) {
182    if (s.when && !s.when()) continue;
183    for (const spec of specsOf(s)) {
184      if (stepsOf(spec).length === 1 && !isSingleKey(spec) && matchesStep(spec, e)) return s;
185    }
186  }
187  return undefined;
188}
189
190// Removes the listener and every shortcut.
191export function stop(): void {
192  if (typeof document !== "undefined") document.removeEventListener("keydown", onKeyDown);
193  installed = false;
194  entries.length = 0;
195  pending = null;
196}
197
198// Adds a shortcut. Returns a function that removes it.
199export function register(s: Shortcut): () => void {
200  start();
201  entries.push(s);
202  return () => {
203    const i = entries.indexOf(s);
204    if (i >= 0) entries.splice(i, 1);
205  };
206}
207
208export function list(): Shortcut[] {
209  start();
210  return entries.slice();
211}
212
213// The registry by group, in the order each group first appears.
214export function grouped(): Array<{ group: string; items: Shortcut[] }> {
215  const out: Array<{ group: string; items: Shortcut[] }> = [];
216  for (const s of list()) {
217    let g = out.find((x) => x.group === s.group);
218    if (!g) {
219      g = { group: s.group, items: [] };
220      out.push(g);
221    }
222    g.items.push(s);
223  }
224  return out;
225}
226
227// What a key spec looks like on a key cap, one string per step: "Mod+k" is ["Ctrl K"]
228// (["⌘ K"] on a Mac), "g o" is ["g", "o"].
229export function keyCaps(spec: string): string[] {
230  const mac = isMac();
231  return stepsOf(spec).map((step) => {
232    const c = parseStep(step);
233    const names: string[] = [];
234    if (c.ctrl || (c.mod && !mac)) names.push("Ctrl");
235    if (c.meta || (c.mod && mac)) names.push(mac ? "⌘" : "Meta");
236    if (c.alt) names.push(mac ? "⌥" : "Alt");
237    const k = c.key.length === 1 && names.length ? c.key.toUpperCase() : c.key;
238    names.push(k);
239    return names.join(" ");
240  });
241}
242
243// The key caps of a shortcut as <kbd> elements: "g o" is two caps, several keys are joined
244// with "or".
245export function keysFragment(key: string | string[]): DocumentFragment {
246  const frag = document.createDocumentFragment();
247  const specs = Array.isArray(key) ? key : [key];
248  specs.forEach((spec, i) => {
249    if (i > 0) frag.append(" or ");
250    keyCaps(spec).forEach((cap, j) => {
251      if (j > 0) frag.append(" ");
252      const k = document.createElement("kbd");
253      k.textContent = cap;
254      frag.append(k);
255    });
256  });
257  return frag;
258}
259
260// ---------------------------------------------------------------------------------------
261// The sheet.
262
263// Lets an app (the React wrapper) open its own sheet when "?" is pressed.
264export function setSheetOpener(fn: (() => void) | null): void {
265  sheetOpener = fn ?? (() => openShortcutSheet());
266}
267
268// Fills a sheet's list from the registry: one group heading and one description list each.
269export function renderSheetList(container: HTMLElement): void {
270  container.replaceChildren();
271  for (const g of grouped()) {
272    const wrap = document.createElement("div");
273    wrap.className = "cap-keys-group";
274    const h = document.createElement("h3");
275    h.className = "cap-keys-group-title";
276    h.textContent = g.group;
277    const dl = document.createElement("dl");
278    dl.className = "cap-keys-list";
279    for (const s of g.items) {
280      const row = document.createElement("div");
281      const dt = document.createElement("dt");
282      dt.append(keysFragment(s.key));
283      const dd = document.createElement("dd");
284      dd.textContent = s.label;
285      if (s.about) {
286        const about = document.createElement("span");
287        about.className = "cap-keys-about";
288        about.textContent = s.about;
289        dd.append(about);
290      }
291      row.append(dt, dd);
292      dl.append(row);
293    }
294    wrap.append(h, dl);
295    container.append(wrap);
296  }
297}
298
299function syncSwitch(sheet: HTMLElement): void {
300  const box = sheet.querySelector<HTMLInputElement>("[data-cap-part='single-keys']");
301  if (!box) return;
302  const on = singleKeysOn();
303  box.checked = on;
304  const word = box.closest(".cap-switch")?.querySelector(".cap-switch-state");
305  if (word) word.textContent = on ? "On" : "Off";
306}
307
308// Builds the sheet's markup, exactly the contract on the doc page: the shared dialog with a
309// header, the list as its body, the switch in its footer, and the corner Close button.
310export function buildSheet(): HTMLDialogElement {
311  const id = uid("cap-keys");
312  const d = document.createElement("dialog");
313  d.className = "cap-dialog cap-keys";
314  d.dataset.cap = "shortcuts";
315  d.dataset.placement = "center";
316  d.dataset.size = "md";
317  d.setAttribute("aria-labelledby", `${id}-title`);
318
319  const head = document.createElement("div");
320  head.className = "cap-dialog-header";
321  head.dataset.divider = "";
322  const h = document.createElement("h2");
323  h.className = "cap-dialog-title";
324  h.id = `${id}-title`;
325  h.textContent = "Keyboard shortcuts";
326  head.append(h);
327
328  const body = document.createElement("div");
329  body.className = "cap-dialog-body cap-keys-body";
330  body.dataset.capPart = "keys-list";
331
332  const footer = document.createElement("div");
333  footer.className = "cap-dialog-footer";
334  footer.dataset.align = "start";
335  const foot = document.createElement("div");
336  foot.className = "cap-keys-foot";
337  const label = document.createElement("label");
338  label.className = "cap-switch";
339  const box = document.createElement("input");
340  box.type = "checkbox";
341  box.setAttribute("role", "switch");
342  box.dataset.capPart = "single-keys";
343  box.setAttribute("aria-describedby", `${id}-note`);
344  const name = document.createElement("span");
345  name.textContent = "Single-key shortcuts";
346  const state = document.createElement("span");
347  state.className = "cap-switch-state";
348  state.setAttribute("aria-hidden", "true");
349  label.append(box, name, state);
350  const note = document.createElement("p");
351  note.className = "cap-keys-note";
352  note.id = `${id}-note`;
353  note.textContent = SINGLE_KEYS_NOTE;
354  foot.append(label, note);
355  footer.append(foot);
356
357  const close = document.createElement("button");
358  close.type = "button";
359  close.className = "cap-btn cap-dialog-close";
360  close.dataset.variant = "quiet";
361  close.dataset.iconOnly = "";
362  close.dataset.capPart = "close";
363  close.setAttribute("aria-label", "Close");
364  const ns = "http://www.w3.org/2000/svg";
365  const svg = document.createElementNS(ns, "svg");
366  svg.setAttribute("viewBox", "0 0 16 16");
367  svg.setAttribute("width", "16");
368  svg.setAttribute("height", "16");
369  svg.setAttribute("aria-hidden", "true");
370  svg.setAttribute("focusable", "false");
371  const path = document.createElementNS(ns, "path");
372  path.setAttribute("d", "M4 4l8 8M12 4l-8 8");
373  path.setAttribute("fill", "none");
374  path.setAttribute("stroke", "currentColor");
375  path.setAttribute("stroke-width", "1.5");
376  path.setAttribute("stroke-linecap", "round");
377  svg.append(path);
378  close.append(svg);
379
380  d.append(head, body, footer, close);
381  return d;
382}
383
384// Wires one sheet: the shared dialog's rules (Close, the backdrop, Esc, focus returned on
385// close), its list, the switch, and the Ctrl or Cmd shortcuts that still work over it. Returns
386// a function that unwires it.
387export function wireSheet(sheet: HTMLDialogElement): () => void {
388  const unwireBase = wireDialog(sheet);
389  const box = sheet.querySelector<HTMLInputElement>("[data-cap-part='single-keys']");
390  const onChange = () => {
391    if (box) setSingleKeys(box.checked);
392  };
393  const onSingle = () => syncSwitch(sheet);
394  // A shortcut with Ctrl or Cmd still works over the sheet: the sheet closes, then it runs.
395  const onKey = (e: KeyboardEvent) => {
396    if (e.defaultPrevented || e.isComposing) return;
397    const hit = modifiedShortcutFor(e);
398    if (!hit) return;
399    sheet.close();
400    fire(hit, e);
401  };
402  box?.addEventListener("change", onChange);
403  document.addEventListener("cap-single-keys", onSingle);
404  sheet.addEventListener("keydown", onKey);
405  syncSwitch(sheet);
406  return () => {
407    box?.removeEventListener("change", onChange);
408    document.removeEventListener("cap-single-keys", onSingle);
409    sheet.removeEventListener("keydown", onKey);
410    unwireBase();
411  };
412}
413
414// Opens the sheet: the one in the page's markup, or one built on first use.
415export function openShortcutSheet(opener: Element | null = document.activeElement): HTMLDialogElement {
416  let sheet = document.querySelector<HTMLDialogElement>("dialog.cap-keys[data-cap='shortcuts']");
417  if (!sheet) {
418    sheet = buildSheet();
419    document.body.append(sheet);
420  }
421  if (!sheet.dataset.capReady) wireSheet(sheet);
422  const list = sheet.querySelector<HTMLElement>("[data-cap-part='keys-list']");
423  if (list) renderSheetList(list);
424  syncSwitch(sheet);
425  // Focus starts on Close, so Esc and Enter are one key from leaving and nothing is changed by
426  // arriving.
427  if (!sheet.open) openDialog(sheet, opener, { focus: sheet.querySelector<HTMLElement>("[data-cap-part='close']") });
428  return sheet;
429}
430
431// Wires a sheet written in markup and every [data-cap-keys-open] button under root, and
432// starts the registry. Returns a function that detaches them.
433export function enhance(root: ParentNode = document): () => void {
434  start();
435  const undo: Array<() => void> = [];
436  for (const sheet of root.querySelectorAll<HTMLDialogElement>("dialog.cap-keys[data-cap='shortcuts']:not([data-cap-ready])")) {
437    undo.push(wireSheet(sheet));
438  }
439  for (const btn of root.querySelectorAll<HTMLElement>("[data-cap-keys-open]:not([data-cap-ready])")) {
440    btn.dataset.capReady = "";
441    const onClick = () => openShortcutSheet(btn);
442    btn.addEventListener("click", onClick);
443    undo.push(() => {
444      btn.removeEventListener("click", onClick);
445      delete btn.dataset.capReady;
446    });
447  }
448  return () => undo.forEach((f) => f());
449}