components/command-menu/command-menu.ts

Functions

Imports

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

Source

1// The command menu: the shared dialog (components/dialog) as a palette near the top, holding a
2// combobox input and the shared listbox (components/listbox) in its "input" mode: the input
3// keeps focus and names the active option (aria-activedescendant). Typing filters, arrows move
4// the active option, Enter runs it, Esc closes. Ctrl K, Cmd K and "/" open it, through the
5// shortcut registry. Every command shows its shortcut. No framework; the React wrapper uses
6// the same pure functions.
7import { closeDialog, openDialog, uid, wireDialog } from "../dialog/dialog.ts";
8import { createListbox, filterCommands as filterItems, groupBy, matchesQuery as matches, step as stepIndex, type Listbox } from "../listbox/listbox.ts";
9import { keysFragment, register } from "../shortcuts/shortcuts.ts";
10
11export interface Command {
12  id: string;
13  label: string;
14  group: string;
15  // Other words that find it: "home" finds Overview.
16  keywords?: string[];
17  // The registry's spec: "g o", "r", "Mod+k". Shown in <kbd>; registering it is the app's job.
18  shortcut?: string | string[];
19  // A short note beside the label, in words, for what the command will do or ask: "asks a
20  // reason", "preview first", an item's state. Read by a screen reader after the label.
21  hint?: string;
22  run: () => void;
23}
24
25// Every way to stop something lives in one group, so typing "stop" lists them all. A stop
26// command opens the control it stands for (a switch's reason field, the confirm dialog) and
27// never performs anything itself. List a stop only while there is something to stop. There is
28// no "stop everything" command.
29export const STOP_GROUP = "Stop";
30export const STOP_HINTS = { reason: "asks a reason", preview: "preview first" } as const;
31
32// A stop command: group Stop, found by "stop" and "pause", its hint saying what opening it
33// will ask for. `run` must only open the control.
34export function stopCommand(o: { id: string; label: string; ask: keyof typeof STOP_HINTS; keywords?: string[]; run: () => void }): Command {
35  return { id: o.id, label: o.label, group: STOP_GROUP, keywords: ["stop", "pause", ...(o.keywords ?? [])], hint: STOP_HINTS[o.ask], run: o.run };
36}
37
38// The listbox's own filtering, grouping and stepping, under the names this module has always
39// exported: a case-insensitive substring over the group, the label and the keywords (so the
40// name of a group finds all of it; an empty query matches all).
41export const matchesQuery = matches;
42export const filterCommands = filterItems;
43export const step = stepIndex;
44
45// Commands by group, in the order each group first appears.
46export function groupCommands<T extends { group: string }>(commands: T[]): Array<{ group: string; items: T[] }> {
47  return groupBy(commands, (c) => c.group);
48}
49
50export function emptyText(query: string): string {
51  return `No commands match “${query.trim()}”`;
52}
53
54// What the empty status says while a live search (the React menu's `search`) has not answered.
55export const SEARCHING = "Searching…";
56
57export interface MenuOptions {
58  // The input's accessible name (a visually hidden label).
59  label?: string;
60  // Shown in the empty input; "Search commands" by default.
61  placeholder?: string;
62}
63
64const SEARCH_ICON = "M7 2.5a4.5 4.5 0 1 0 2.7 8.1l3 3 1.1-1.1-3-3A4.5 4.5 0 0 0 7 2.5zm0 1.5a3 3 0 1 1 0 6 3 3 0 0 1 0-6z";
65
66// Builds the dialog's markup, exactly the contract on the doc page.
67export function buildMenu(commands: Command[], opts: MenuOptions = {}): HTMLDialogElement {
68  const id = uid("cap-cmd");
69  const d = document.createElement("dialog");
70  d.className = "cap-dialog cap-cmd";
71  d.dataset.cap = "command-menu";
72  d.dataset.placement = "top";
73  d.dataset.size = "lg";
74  d.setAttribute("aria-label", "Command menu");
75
76  const search = document.createElement("div");
77  search.className = "cap-cmd-search";
78  const ns = "http://www.w3.org/2000/svg";
79  const icon = document.createElementNS(ns, "svg");
80  icon.setAttribute("viewBox", "0 0 16 16");
81  icon.setAttribute("width", "16");
82  icon.setAttribute("height", "16");
83  icon.setAttribute("aria-hidden", "true");
84  icon.setAttribute("focusable", "false");
85  const path = document.createElementNS(ns, "path");
86  path.setAttribute("fill", "currentColor");
87  path.setAttribute("fill-rule", "evenodd");
88  path.setAttribute("d", SEARCH_ICON);
89  icon.append(path);
90  const label = document.createElement("label");
91  label.className = "cap-sr-only";
92  label.htmlFor = `${id}-input`;
93  label.textContent = opts.label ?? "Search commands";
94  const input = document.createElement("input");
95  input.className = "cap-cmd-input";
96  input.id = `${id}-input`;
97  input.type = "text";
98  input.autocomplete = "off";
99  input.spellcheck = false;
100  input.setAttribute("role", "combobox");
101  input.setAttribute("aria-expanded", "true");
102  input.setAttribute("aria-controls", `${id}-list`);
103  input.setAttribute("aria-autocomplete", "list");
104  input.placeholder = opts.placeholder ?? "Search commands";
105  search.append(icon, label, input);
106
107  const list = document.createElement("div");
108  list.className = "cap-listbox cap-cmd-list";
109  list.id = `${id}-list`;
110  list.dataset.controlled = "";
111  list.setAttribute("role", "listbox");
112  list.setAttribute("aria-label", "Commands");
113  groupCommands(commands).forEach((g, gi) => {
114    const group = document.createElement("div");
115    group.className = "cap-listbox-group";
116    group.setAttribute("role", "group");
117    group.setAttribute("aria-labelledby", `${id}-g${gi}`);
118    const title = document.createElement("div");
119    title.className = "cap-listbox-label";
120    title.id = `${id}-g${gi}`;
121    title.setAttribute("role", "presentation");
122    title.textContent = g.group;
123    group.append(title);
124    for (const c of g.items) {
125      const o = document.createElement("div");
126      o.className = "cap-option";
127      o.id = `${id}-o-${c.id}`;
128      o.setAttribute("role", "option");
129      o.dataset.capCommand = c.id;
130      o.dataset.value = c.id;
131      o.dataset.group = c.group;
132      if (c.keywords?.length) o.dataset.keywords = c.keywords.join(",");
133      const text = document.createElement("span");
134      text.className = "cap-option-label";
135      text.textContent = c.label;
136      o.append(text);
137      if (c.shortcut || c.hint) {
138        const keys = document.createElement("span");
139        keys.className = "cap-option-keys";
140        if (c.hint) {
141          const sr = document.createElement("span");
142          sr.className = "cap-sr-only";
143          sr.textContent = ", ";
144          const hint = document.createElement("span");
145          hint.className = "cap-option-hint";
146          hint.textContent = c.hint;
147          keys.append(sr, hint);
148        }
149        if (c.shortcut) {
150          const sr = document.createElement("span");
151          sr.className = "cap-sr-only";
152          sr.textContent = ", shortcut ";
153          keys.append(sr, keysFragment(c.shortcut));
154        }
155        o.append(keys);
156      }
157      group.append(o);
158    }
159    list.append(group);
160  });
161
162  const empty = document.createElement("p");
163  empty.className = "cap-listbox-empty";
164  empty.setAttribute("role", "status");
165  empty.dataset.capPart = "empty";
166
167  const foot = document.createElement("div");
168  foot.className = "cap-cmd-foot";
169  foot.setAttribute("aria-hidden", "true");
170  const hint = (keys: string[], what: string) => {
171    const s = document.createElement("span");
172    keys.forEach((k, i) => {
173      if (i > 0) s.append(" ");
174      const kbd = document.createElement("kbd");
175      kbd.textContent = k;
176      s.append(kbd);
177    });
178    s.append(` ${what}`);
179    return s;
180  };
181  foot.append(hint(["↑", "↓"], "move"), hint(["Enter"], "run"), hint(["Esc"], "close"));
182
183  d.append(search, list, empty, foot);
184  return d;
185}
186
187export interface Attached {
188  open: (query?: string, opener?: Element | null) => void;
189  close: () => void;
190  // Makes the option at this index among those shown the active one.
191  setActive: (index: number) => void;
192  detach: () => void;
193}
194
195// Wires one menu dialog: the shared dialog's rules (Esc, the backdrop, focus handed back), the
196// shared listbox over the commands (filtering, the active option, Enter, a click), and Ctrl K to
197// close. `run` is called with the chosen option after the dialog has closed.
198export function attach(dialog: HTMLDialogElement, run: (option: HTMLElement) => void): Attached {
199  const unwireBase = wireDialog(dialog);
200  const input = dialog.querySelector<HTMLInputElement>("[role='combobox']");
201  const list = dialog.querySelector<HTMLElement>("[role='listbox']");
202  const empty = dialog.querySelector<HTMLElement>("[data-cap-part='empty']");
203  if (!input || !list) return { open() {}, close() {}, setActive() {}, detach: unwireBase };
204  list.dataset.controlled = "";
205  // A menu written for 0.1 named keywords, group and the active option another way.
206  for (const o of list.querySelectorAll<HTMLElement>("[role='option']")) {
207    if (o.dataset.capKeywords && !o.dataset.keywords) o.dataset.keywords = o.dataset.capKeywords;
208    if (o.dataset.capGroup && !o.dataset.group) o.dataset.group = o.dataset.capGroup;
209    if (o.getAttribute("aria-selected") === "true") {
210      o.removeAttribute("aria-selected");
211      o.dataset.active = "";
212    } else if (o.getAttribute("aria-selected") === "false") o.removeAttribute("aria-selected");
213  }
214
215  const lb: Listbox = createListbox(list, {
216    input,
217    empty,
218    homeEnd: true,
219    filterInput: true,
220    onFilter(count, query) {
221      input.setAttribute("aria-expanded", String(count > 0));
222      if (empty) empty.textContent = count === 0 && query.trim() ? emptyText(query) : "";
223    },
224  });
225  list.dataset.capReady = "";
226
227  const choose = (o: HTMLElement | null | undefined) => {
228    if (!o) return;
229    dialog.close();
230    run(o);
231  };
232  const onSelect = (e: Event) => choose((e as CustomEvent<{ option: HTMLElement }>).detail.option);
233  const onKey = (e: KeyboardEvent) => {
234    // The key that opened it closes it.
235    if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "k") {
236      e.preventDefault();
237      dialog.close();
238    }
239  };
240  list.addEventListener("cap:option-select", onSelect);
241  input.addEventListener("keydown", onKey);
242  // A menu written with a query or an active option in its markup keeps them.
243  const preset = lb.active();
244  lb.filter(input.value);
245  if (preset && !preset.hidden) lb.setActive(preset, { scroll: false });
246
247  return {
248    open(query = "", opener: Element | null = document.activeElement) {
249      if (dialog.open) return;
250      input.value = query;
251      lb.filter(query);
252      openDialog(dialog, opener, { focus: input });
253    },
254    close() {
255      closeDialog(dialog);
256    },
257    setActive: (i) => lb.setActive(i),
258    detach() {
259      list.removeEventListener("cap:option-select", onSelect);
260      input.removeEventListener("keydown", onKey);
261      lb.detach();
262      unwireBase();
263    },
264  };
265}
266
267// The menu that openCommandMenu() opens: the last one created or enhanced.
268let current: Attached | null = null;
269let unregisterKeys: (() => void) | null = null;
270
271function ensureShortcut(): void {
272  if (unregisterKeys) return;
273  unregisterKeys = register({ key: ["Mod+k", "/"], label: "Open the command menu", group: "General", run: () => openCommandMenu() });
274}
275
276export function openCommandMenu(query = ""): void {
277  current?.open(query);
278}
279
280export interface CommandMenu extends Attached {
281  dialog: HTMLDialogElement;
282}
283
284// Builds a menu from a list of commands, adds it to the page, and binds Ctrl K, Cmd K and
285// "/" to open it.
286export function createCommandMenu(commands: Command[], opts: MenuOptions = {}): CommandMenu {
287  const dialog = buildMenu(commands, opts);
288  document.body.append(dialog);
289  const byId = new Map(commands.map((c) => [c.id, c]));
290  const a = attach(dialog, (o) => byId.get(o.dataset.capCommand ?? "")?.run());
291  current = a;
292  ensureShortcut();
293  return {
294    ...a,
295    dialog,
296    detach() {
297      a.detach();
298      dialog.remove();
299      if (current === a) current = null;
300    },
301  };
302}
303
304// Wires a menu written in markup: choosing an option follows its data-href, or dispatches a
305// "cap-command" event (detail: { id }) on the dialog. Also wires every
306// [data-cap-command-open] button under root, and binds the keys.
307export function enhance(root: ParentNode = document): () => void {
308  const undo: Array<() => void> = [];
309  for (const dialog of root.querySelectorAll<HTMLDialogElement>("dialog.cap-cmd[data-cap='command-menu']:not([data-cap-ready])")) {
310    const a = attach(dialog, (o) => {
311      const href = o.dataset.href;
312      if (href) location.assign(href);
313      else dialog.dispatchEvent(new CustomEvent("cap-command", { bubbles: true, detail: { id: o.dataset.capCommand ?? o.id } }));
314    });
315    current = a;
316    undo.push(a.detach);
317  }
318  for (const btn of root.querySelectorAll<HTMLElement>("[data-cap-command-open]:not([data-cap-ready])")) {
319    btn.dataset.capReady = "";
320    const onClick = () => current?.open("", btn);
321    btn.addEventListener("click", onClick);
322    undo.push(() => {
323      btn.removeEventListener("click", onClick);
324      delete btn.dataset.capReady;
325    });
326  }
327  ensureShortcut();
328  return () => undo.forEach((f) => f());
329}