components/row-list/row-list.ts

Functions

Imports

It imports no other module of this repo. Imported by components/attention-list/attention-list.ts, components/draft-compare/draft-compare.ts, components/flag-list/flag-list.react.tsx, components/flag-list/flag-list.ts, components/history-list/history-list.ts, components/mentions-list/mentions-list.react.tsx, components/moderation-queue/moderation-queue.ts, components/publish-gate/publish-gate.react.tsx, components/publish-gate/publish-gate.ts, components/row-list/row-list.react.tsx.

Source

1// The row list's behaviour: j and k move keyboard focus between the rows' title links.
2// Focus itself moves (there is no second selection), so Enter follows the link, the
3// browser scrolls the row into view, and a screen reader reads the row it lands on.
4// No framework; the React wrapper uses the same functions.
5
6// Every row's one link or button, in order, skipping rows hidden or disabled.
7export function rowTargets(list: ParentNode): HTMLElement[] {
8  return Array.from(list.querySelectorAll<HTMLElement>(".cap-row-title :is(a[href], button:not([disabled]))")).filter(
9    (el) => el.getClientRects().length > 0,
10  );
11}
12
13// Moves focus to the next (1) or previous (-1) row's title. From outside the list, j starts
14// at the first row and k at the last (the Portal's rule, App.tsx "step"). At either end
15// focus stays where it is. Focus moves without the browser's own scroll, then the row is
16// scrolled the least distance that shows it ("nearest"), as the Portal does: a row already
17// in view does not jump, and the scroller's scroll-padding keeps it clear of a sticky bar.
18// Returns the element focused, or null when nothing moved.
19export function moveRowFocus(list: ParentNode, step: 1 | -1): HTMLElement | null {
20  const targets = rowTargets(list);
21  if (targets.length === 0) return null;
22  const active = document.activeElement;
23  const current = targets.findIndex((el) => el === active || el.closest(".cap-row")?.contains(active));
24  const next = current === -1 ? (step === 1 ? 0 : targets.length - 1) : current + step;
25  const el = targets[next];
26  if (!el || next === current) return null;
27  el.focus({ preventScroll: true });
28  el.scrollIntoView({ block: "nearest" });
29  return el;
30}
31
32// A key typed into a field, or with a modifier, is never a list shortcut.
33export function isTyping(e: KeyboardEvent): boolean {
34  if (e.ctrlKey || e.metaKey || e.altKey || e.isComposing) return true;
35  const t = e.target as HTMLElement | null;
36  if (!t) return false;
37  return t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName) || t.closest("[role='combobox'], [role='textbox']") !== null;
38}
39
40// The same check for a list whose rows hold their own checkboxes (the moderation queue, the
41// history list): a checkbox, a radio or a button is not typing, so a list key works from a box
42// a person has just ticked.
43const TEXT_INPUT = /^(text|search|email|url|tel|password|number|date|datetime-local|month|week|time)$/;
44export function isTypingKey(e: KeyboardEvent): boolean {
45  if (e.ctrlKey || e.metaKey || e.altKey || e.isComposing) return true;
46  const t = e.target as HTMLElement | null;
47  if (!t) return false;
48  if (t instanceof HTMLInputElement) return TEXT_INPUT.test(t.type || "text");
49  return t.isContentEditable || /^(TEXTAREA|SELECT)$/.test(t.tagName) || t.closest("[role='combobox'], [role='textbox']") !== null;
50}
51
52// Single-key shortcuts can be switched off (DEFAULTS.md). The shortcuts registry records the
53// choice as data-cap-single-keys="off" on <html>.
54export function singleKeysOff(): boolean {
55  return document.documentElement.dataset.capSingleKeys === "off";
56}
57
58// Whether j and k should act on this list now: focus is in it, or it is the page's primary
59// list and focus is in no other list and no open dialog.
60export function listOwnsKeys(list: HTMLElement): boolean {
61  const active = document.activeElement;
62  if (active && list.contains(active)) return true;
63  if (!list.hasAttribute("data-cap-primary")) return false;
64  if (active?.closest("[data-cap='row-list']")) return false;
65  if (active?.closest("dialog[open], [role='dialog'], [role='menu'], [role='listbox']")) return false;
66  return !list.closest("[inert]");
67}
68
69// Attaches j and k to one list. Returns a function that detaches them. A list already
70// attached (by enhance or by the React wrapper) is left alone, so keys never act twice.
71export function attachRowList(list: HTMLElement): () => void {
72  if (list.dataset.capReady !== undefined) return () => {};
73  list.dataset.capReady = "";
74  const onKey = (e: KeyboardEvent) => {
75    if (e.defaultPrevented || (e.key !== "j" && e.key !== "k")) return;
76    if (isTyping(e) || singleKeysOff() || !listOwnsKeys(list)) return;
77    if (moveRowFocus(list, e.key === "j" ? 1 : -1) || list.contains(document.activeElement)) e.preventDefault();
78  };
79  document.addEventListener("keydown", onKey);
80  return () => {
81    document.removeEventListener("keydown", onKey);
82    delete list.dataset.capReady;
83  };
84}
85
86// Attaches to every [data-cap="row-list"] under root that is not attached yet. Returns a
87// function that detaches them all.
88export function enhance(root: ParentNode = document): () => void {
89  const undo = Array.from(root.querySelectorAll<HTMLElement>("[data-cap='row-list']:not([data-cap-ready])")).map(attachRowList);
90  return () => undo.forEach((f) => f());
91}