components/moderation-queue/moderation-queue.ts

Functions

Imports

It imports components/confirm-dialog/confirm-dialog.ts, components/disclosure/disclosure.ts, components/message/message.ts, components/moderation-queue/moderation-queue-model.ts, components/row-list/row-list.ts, components/shortcuts/shortcuts.ts, components/time/time.ts. Imported by components/content/content.ts, components/mentions-list/examples.tsx, components/mentions-list/mentions-list.react.tsx, components/mentions-list/mentions-list.ts.

Source

1// The moderation queue's behaviour and its pure helpers. Mentions from strangers wait in a list;
2// a and r approve or reject the row under focus at once (act first), a message says what
3// happened and offers Undo where the site can reverse it (z undoes it), d deletes after a
4// confirm, x selects, j and k move. The states are the site-api contract's own: Waiting
5// (pending), Approved, Rejected, Not yet checked (unverified) and Source not found (failed).
6//
7// The page is delivered with every row in the HTML, each with its state in words; this
8// module adds only what a person's action creates. No framework; MentionsList, the React
9// component on the contract's data, uses the same helpers.
10import { confirm } from "../confirm-dialog/confirm-dialog.ts";
11import { toggleGroup } from "../disclosure/disclosure.ts";
12import { enhance as enhanceMessage, say } from "../message/message.ts";
13import { isTypingKey, listOwnsKeys, moveRowFocus, singleKeysOff } from "../row-list/row-list.ts";
14import { enhance as enhanceShortcuts, register } from "../shortcuts/shortcuts.ts";
15import { enhance as enhanceTime, parse } from "../time/time.ts";
16import { ACTION_KEY, DELETE_KEY, EMPTY_TEXT, type Mention, type ModAction, type ModState, type ModView, NO_UNDO_TEXT, type UndoEntry, type UndoStack, VIEWS, actionButton, actionsFor, bulkActionsFor, countStates, decide, decidedText, h, inView, mentionsWord, statusEl, summaryText, sweepLines, undoAction, undoStack, undoneText } from "./moderation-queue-model.ts";
17
18export { VIEWS, VIEW_LABEL, STATE_LABEL, ACTIONS, ACTION_KEY, DELETE_KEY, decide, actionsFor, bulkActionsFor, inView, countStates, summaryText, statusOf, ACTION_LABEL, decidedText, undoneText, undoAction, NO_UNDO_TEXT, undoStack, sweepLines, mentionsWord, EMPTY_TEXT, statusEl, actionButton } from "./moderation-queue-model.ts";
19export type { ModState, ModView, ModAction, Mention, Counts, Status, UndoEntry, UndoStack } from "./moderation-queue-model.ts";
20
21export { isTypingKey };
22
23// ---------------------------------------------------------------------------------------
24// The behaviour.
25
26const READY = "data-cap-ready";
27
28const rowsOf = (root: HTMLElement) => Array.from(root.querySelectorAll<HTMLLIElement>(".cap-mq-row"));
29const listOf = (root: HTMLElement) => root.querySelector<HTMLElement>(".cap-mq-list");
30const titleOf = (row: Element) => row.querySelector<HTMLElement>(".cap-row-title button");
31const visible = (row: HTMLElement) => !row.hidden;
32const currentView = (root: HTMLElement): ModView => ((VIEWS as readonly string[]).includes(root.dataset.view ?? "") ? (root.dataset.view as ModView) : "pending");
33// The site offers Back to waiting (site-api v0.6, decision "reset").
34const resetOn = (root: HTMLElement) => root.hasAttribute("data-cap-reset");
35const deleteOn = (root: HTMLElement) => !root.hasAttribute("data-cap-no-delete");
36
37export function mentionOf(row: HTMLElement): Pick<Mention, "id" | "state" | "at" | "decidedAt" | "author" | "host" | "expiring"> {
38  return {
39    id: row.dataset.id ?? "",
40    state: (row.dataset.state ?? "pending") as ModState,
41    at: row.dataset.at ?? "",
42    decidedAt: row.dataset.decided || undefined,
43    author: row.dataset.author ?? "",
44    host: row.dataset.host ?? "",
45    expiring: row.hasAttribute("data-expiring"),
46  };
47}
48
49function nowOf(root: Element): number {
50  const fixed = root.closest<HTMLElement>("[data-cap-now]")?.dataset.capNow;
51  return fixed ? parse(fixed) : Date.now();
52}
53
54// The page's status region for results and Undo is one; where there is none, one goes after
55// the queue.
56function ensureRegion(after: Element): void {
57  if (document.querySelector("[data-cap='message']")) return;
58  const region = h("div", { class: "cap-message", "data-cap": "message", role: "status", "aria-label": "Results and failures", "aria-atomic": "false" });
59  after.after(region);
60  enhanceMessage(region.parentNode ?? document);
61}
62
63// Paints one row for its state: the status, the buttons that apply.
64function paintRow(root: HTMLElement, row: HTMLLIElement): void {
65  const m = mentionOf(row);
66  row.querySelector<HTMLElement>(".cap-row-status")?.replaceChildren(statusEl(m.state));
67  const actions = row.querySelector<HTMLElement>("[data-cap-part='actions']");
68  if (actions) {
69    actions.replaceChildren(...actionsFor(m.state, resetOn(root)).map((a) => actionButton(a, m.author)));
70    if (deleteOn(root)) actions.append(actionButton("delete", m.author));
71  }
72}
73
74// Which rows are in view, the counts, the live line, the empty state, the bulk bar.
75export function refresh(root: HTMLElement): void {
76  const view = currentView(root);
77  const rows = rowsOf(root);
78  for (const row of rows) {
79    row.hidden = !inView(mentionOf(row).state, view);
80    const box = row.querySelector<HTMLInputElement>("[data-cap-part='select']");
81    if (row.hidden && box?.checked) box.checked = false;
82    row.toggleAttribute("data-selected", !!box?.checked);
83  }
84  const counts = countStates(rows.map((r) => mentionOf(r)));
85  for (const el of root.querySelectorAll<HTMLElement>("[data-cap-count]")) {
86    const v = el.dataset.capCount as ModView;
87    const n = String(counts[v] ?? 0);
88    const first = el.firstChild;
89    if (first && first.nodeType === Node.TEXT_NODE) first.nodeValue = n;
90    else el.prepend(n);
91  }
92  const summary = root.querySelector<HTMLElement>("[data-cap-part='summary']");
93  const line = summaryText(counts);
94  if (summary && summary.textContent !== line) summary.textContent = line;
95  const shown = rows.filter(visible).length;
96  const empty = root.querySelector<HTMLElement>("[data-cap-part='empty']");
97  if (empty) {
98    empty.hidden = shown > 0;
99    const t = EMPTY_TEXT[view];
100    const title = empty.querySelector(".cap-empty-title");
101    const text = empty.querySelector(".cap-empty-text");
102    if (title) title.textContent = t.title;
103    if (text) text.textContent = t.text;
104    empty.dataset.kind = view === "pending" ? "all-clear" : "nothing-yet";
105  }
106  const list = listOf(root);
107  if (list) list.hidden = shown === 0;
108  syncSelection(root);
109  syncRetention(root);
110}
111
112function selectedRows(root: HTMLElement): HTMLLIElement[] {
113  return rowsOf(root).filter((r) => !r.hidden && r.querySelector<HTMLInputElement>("[data-cap-part='select']")?.checked);
114}
115
116// The selection: each row's mark, the select-all box, the bulk bar (count, and the buttons
117// that apply to this view).
118export function syncSelection(root: HTMLElement): HTMLLIElement[] {
119  const rows = rowsOf(root).filter(visible);
120  const picked = selectedRows(root);
121  for (const r of rows) r.toggleAttribute("data-selected", picked.includes(r));
122  const all = root.querySelector<HTMLInputElement>("[data-cap-part='select-all']");
123  if (all) {
124    all.checked = rows.length > 0 && picked.length === rows.length;
125    all.indeterminate = picked.length > 0 && picked.length < rows.length;
126    const noun = all.closest("label")?.querySelector<HTMLElement>("[data-cap-part='select-all-text']");
127    if (noun) noun.textContent = rows.length === 0 ? "Select all" : `Select all ${rows.length} shown`;
128  }
129  const bar = root.querySelector<HTMLElement>("[data-cap='bulk-bar']");
130  if (bar) {
131    const count = bar.querySelector<HTMLElement>(".cap-bulk-count");
132    const text = picked.length === 0 ? "No rows selected" : `${picked.length} selected`;
133    if (count && count.textContent !== text) count.textContent = text;
134    bar.toggleAttribute("data-empty", picked.length === 0);
135    const holder = bar.querySelector<HTMLElement>(".cap-bulk-actions");
136    const view = currentView(root);
137    const key = `${view}:${picked.length > 0}`;
138    if (holder && holder.dataset.key !== key) {
139      holder.dataset.key = key;
140      const acts: Array<ModAction | "delete"> = picked.length ? [...bulkActionsFor(view, resetOn(root)), ...(deleteOn(root) ? (["delete"] as const) : [])] : [];
141      holder.replaceChildren(...acts.map((a) => actionButton(a, "", { bar: true })));
142    }
143    const clear = bar.querySelector<HTMLElement>(".cap-bulk-clear");
144    if (clear) clear.hidden = picked.length === 0;
145    if (holder) holder.hidden = picked.length === 0;
146  }
147  return picked;
148}
149
150// The sweep: what the site says will expire, counted from the rows it marked.
151function expiringRows(root: HTMLElement): HTMLLIElement[] {
152  return rowsOf(root).filter((r) => r.hasAttribute("data-expiring"));
153}
154
155function syncRetention(root: HTMLElement): void {
156  const button = root.querySelector<HTMLElement>("[data-cap-part='sweep']");
157  if (!button) return;
158  const n = expiringRows(root).length;
159  button.textContent = `Remove ${n} expired`;
160  if (n === 0) button.setAttribute("aria-disabled", "true");
161  else button.removeAttribute("aria-disabled");
162}
163
164// The row to focus once `acted` rows have left the view: the next one down, else the one
165// above, else null (the empty state takes focus).
166function focusTargetAfter(root: HTMLElement, acted: HTMLElement[]): HTMLElement | null {
167  const rows = rowsOf(root).filter(visible);
168  const last = rows.reduce((at, r, i) => (acted.includes(r) ? i : at), -1);
169  const first = rows.findIndex((r) => acted.includes(r));
170  const after = rows.slice(last + 1).find((r) => !acted.includes(r));
171  const before = rows.slice(0, Math.max(first, 0)).reverse().find((r) => !acted.includes(r));
172  const row = after ?? before;
173  return row ? titleOf(row) : null;
174}
175
176function focusAfter(root: HTMLElement, target: HTMLElement | null): void {
177  const el = target?.isConnected && !target.closest("[hidden]") ? target : root.querySelector<HTMLElement>("[data-cap-part='empty']:not([hidden])");
178  el?.focus({ preventScroll: false });
179}
180
181export interface DecidedDetail {
182  ids: string[];
183  action: ModAction;
184  from: Record<string, ModState>;
185  to: Record<string, ModState>;
186}
187
188interface Ctx {
189  root: HTMLElement;
190  stack: UndoStack<UndoEntry>;
191}
192
193const contexts = new WeakMap<HTMLElement, Ctx>();
194
195function applyState(root: HTMLElement, row: HTMLLIElement, to: ModState, decidedAt: string | undefined): void {
196  row.dataset.state = to;
197  if (decidedAt) row.dataset.decided = decidedAt;
198  else delete row.dataset.decided;
199  paintRow(root, row);
200}
201
202// What Undo does for one decision: reverses it, and when earlier decisions are still
203// undoable offers the next one, so z walks back through them.
204function undoThen(ctx: Ctx, entry: UndoEntry): () => void {
205  return () => {
206    undoEntry(ctx, entry);
207    const prior = ctx.stack.peek();
208    if (prior) say(`${undoneText(entry.who)} Earlier: ${decidedText(prior.action, prior.who)}`, { undo: undoThen(ctx, prior) });
209    else say(undoneText(entry.who));
210  };
211}
212
213function undoEntry(ctx: Ctx, entry: UndoEntry): void {
214  const { root, stack } = ctx;
215  stack.remove((e) => e === entry);
216  const to: Record<string, ModState> = {};
217  const back: HTMLLIElement[] = [];
218  for (const row of rowsOf(root)) {
219    const was = entry.from[row.dataset.id ?? ""];
220    if (!was) continue;
221    to[row.dataset.id ?? ""] = was.state;
222    applyState(root, row, was.state, was.decidedAt);
223    back.push(row);
224  }
225  refresh(root);
226  // Focus goes to the first mention that came back, when it is in view (the one that was
227  // undone, as the message component returns focus to the control it undid). Undo's own
228  // button is gone by now.
229  const first = back.find(visible);
230  if (first) titleOf(first)?.focus();
231  root.dispatchEvent(new CustomEvent("cap:mod-undone", { bubbles: true, detail: { ids: entry.ids, to } }));
232}
233
234// Decides these rows at once: each moves to its new state, the counts and the live line
235// follow, focus moves to the next row, and the message says so, with Undo where the site can
236// put each one back. A row the table does not allow is left alone. Returns the ids that moved.
237export function decideRows(root: HTMLElement, rows: HTMLLIElement[], action: ModAction, opts: { focus?: boolean; announce?: boolean; note?: string } = {}): string[] {
238  const ctx = contexts.get(root);
239  const reset = resetOn(root);
240  const moved: HTMLLIElement[] = [];
241  const from: UndoEntry["from"] = {};
242  const to: Record<string, ModState> = {};
243  const decidedAt = new Date(nowOf(root)).toISOString();
244  // Focus is on one of these rows, or on the bulk bar's button that was just pressed (which is
245  // rebuilt): either way it moves to the next row.
246  const hadFocus = rows.some((r) => r.contains(document.activeElement)) || !!root.querySelector("[data-cap='bulk-bar']")?.contains(document.activeElement);
247  const target = hadFocus && opts.focus !== false ? focusTargetAfter(root, rows) : null;
248  for (const row of rows) {
249    const m = mentionOf(row);
250    const next = decide(m.state, action, reset);
251    if (!next) continue;
252    from[m.id] = { state: m.state, decidedAt: m.decidedAt };
253    to[m.id] = next;
254    applyState(root, row, next, next === "pending" ? undefined : decidedAt);
255    moved.push(row);
256  }
257  if (moved.length === 0) return [];
258  refresh(root);
259  if (hadFocus && opts.focus !== false) focusAfter(root, target);
260  const ids = moved.map((r) => r.dataset.id ?? "");
261  root.dispatchEvent(new CustomEvent<DecidedDetail>("cap:mod-decided", { bubbles: true, detail: { ids, action, from: Object.fromEntries(Object.entries(from).map(([k, v]) => [k, v.state])), to } }));
262  if (ctx && opts.announce !== false) {
263    const entry: UndoEntry = { ids, who: moved.map((r) => r.dataset.author ?? ""), action, from };
264    const text = [decidedText(action, entry.who), opts.note].filter(Boolean).join(" ");
265    if (Object.values(from).every((f) => undoAction(f.state, reset))) {
266      ctx.stack.push(entry);
267      say(text, { undo: undoThen(ctx, entry) });
268    } else say(`${text} ${NO_UNDO_TEXT}`);
269  }
270  return ids;
271}
272
273// Delete is for good: previewed in a confirm dialog with focus on Cancel, the count typed.
274async function deleteRows(root: HTMLElement, rows: HTMLLIElement[]): Promise<void> {
275  if (rows.length === 0) return;
276  const ctx = contexts.get(root);
277  const ids = rows.map((r) => r.dataset.id ?? "");
278  const who = rows.map((r) => r.dataset.author ?? "");
279  const one = rows.length === 1;
280  const target = focusTargetAfter(root, rows);
281  await confirm({
282    title: one ? `Delete the mention from ${who[0]}?` : `Delete ${rows.length} mentions?`,
283    lead: "This cannot be undone. Reject it instead to keep it off the post and keep the record.",
284    body: rows.map((r) => `From ${r.dataset.author ?? ""} (${r.dataset.host ?? ""})`),
285    action: one ? "Delete the mention" : `Delete ${rows.length} mentions`,
286    typeToConfirm: String(rows.length),
287    returnTo: target,
288    perform: async () => {
289      for (const r of rows) r.remove();
290      ctx?.stack.remove((e) => e.ids.some((id) => ids.includes(id)));
291      refresh(root);
292      root.dispatchEvent(new CustomEvent("cap:mod-deleted", { bubbles: true, detail: { ids } }));
293      say(one ? `Deleted the mention from ${who[0]}.` : `Deleted ${rows.length} mentions.`);
294    },
295  });
296  if (!root.contains(document.activeElement)) focusAfter(root, target);
297}
298
299async function sweepExpired(root: HTMLElement): Promise<void> {
300  const doomed = expiringRows(root);
301  if (doomed.length === 0) return;
302  const counts = countStates(doomed.map((r) => mentionOf(r)));
303  const n = doomed.length;
304  await confirm({
305    title: `Remove ${n} expired ${mentionsWord(n)}?`,
306    lead: "This cannot be undone. Nothing that is waiting or approved is touched.",
307    body: sweepLines(counts),
308    action: "Remove them",
309    returnTo: root.querySelector<HTMLElement>("[data-cap-part='sweep']"),
310    perform: async () => {
311      const ids = doomed.map((r) => r.dataset.id ?? "");
312      for (const r of doomed) r.remove();
313      contexts.get(root)?.stack.remove((e) => e.ids.some((id) => ids.includes(id)));
314      refresh(root);
315      root.dispatchEvent(new CustomEvent("cap:mod-deleted", { bubbles: true, detail: { ids } }));
316      say(`Removed ${n} expired ${mentionsWord(n)}.`);
317    },
318  });
319}
320
321// Runs one action for these rows. A decision leaves the rows it does not apply to (a mention not
322// yet checked, or whose source was not found) and says so.
323export async function run(root: HTMLElement, rows: HTMLLIElement[], action: ModAction | "delete"): Promise<void> {
324  if (action === "delete") return deleteOn(root) ? deleteRows(root, rows) : undefined;
325  const n = rows.filter((r) => actionsFor(mentionOf(r).state, true).length === 0).length;
326  const note = n > 0 ? `${n} ${n === 1 ? "was" : "were"} left as ${n === 1 ? "it was" : "they were"}: there is nothing to decide about a mention not yet checked or whose source was not found.` : undefined;
327  const moved = decideRows(root, rows, action, { note });
328  if (moved.length === 0 && note) say(note);
329}
330
331export function setView(root: HTMLElement, view: ModView): void {
332  root.dataset.view = view;
333  for (const box of root.querySelectorAll<HTMLInputElement>("[data-cap-part='select']")) box.checked = false;
334  const radio = root.querySelector<HTMLInputElement>(`[data-cap-part='view'][value='${view}']`);
335  if (radio && !radio.checked) radio.checked = true;
336  refresh(root);
337}
338
339// The keys of the sheet: listed there, never run from the registry (the queue runs them,
340// because they act on the row that has focus, and only inside the queue).
341export const QUEUE_SHORTCUTS = [
342  { key: "j", label: "Next row" },
343  { key: "k", label: "Previous row" },
344  { key: "a", label: "Approve the row" },
345  { key: "r", label: "Reject the row" },
346  { key: "d", label: "Delete the row, after a confirm" },
347  { key: "x", label: "Select the row" },
348] as const;
349
350// Attaches to every [data-cap="moderation-queue"] under root not yet attached. Returns a
351// function that detaches them.
352export function enhance(root: ParentNode = document): () => void {
353  const undo: Array<() => void> = [];
354  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='moderation-queue']")) {
355    if (el.hasAttribute(READY)) continue;
356    el.setAttribute(READY, "");
357    const ctx: Ctx = { root: el, stack: undoStack<UndoEntry>() };
358    contexts.set(el, ctx);
359    enhanceTime(el);
360    ensureRegion(el);
361    undo.push(enhanceShortcuts(el));
362    for (const s of QUEUE_SHORTCUTS) undo.push(register({ ...s, group: "Moderation queue", when: () => false, run: () => {} }));
363
364    const list = listOf(el);
365    const rowOf = (n: Element | null) => n?.closest<HTMLLIElement>(".cap-mq-row") ?? null;
366
367    const onClick = (e: MouseEvent) => {
368      const t = e.target as Element;
369      const toggle = t.closest<HTMLElement>(".cap-row-title button[aria-expanded]");
370      if (toggle && el.contains(toggle)) return toggleGroup(toggle);
371      const act = t.closest<HTMLElement>("[data-cap-action]");
372      if (act && el.contains(act)) {
373        const action = act.dataset.capAction as ModAction | "delete";
374        const row = rowOf(act);
375        void run(el, row ? [row] : selectedRows(el), action);
376        return;
377      }
378      if (t.closest(".cap-bulk-clear")) {
379        for (const box of el.querySelectorAll<HTMLInputElement>("[data-cap-part='select']")) box.checked = false;
380        syncSelection(el);
381        (list?.querySelector<HTMLElement>(".cap-mq-row:not([hidden]) .cap-row-title button") ?? null)?.focus();
382        return;
383      }
384      const sweep = t.closest<HTMLElement>("[data-cap-part='sweep']");
385      if (sweep) {
386        if (sweep.getAttribute("aria-disabled") !== "true") void sweepExpired(el);
387        return;
388      }
389    };
390    const onChange = (e: Event) => {
391      const t = e.target as HTMLInputElement;
392      if (t.matches("[data-cap-part='select']")) syncSelection(el);
393      else if (t.matches("[data-cap-part='select-all']")) {
394        for (const row of rowsOf(el).filter(visible)) {
395          const box = row.querySelector<HTMLInputElement>("[data-cap-part='select']");
396          if (box) box.checked = t.checked;
397        }
398        syncSelection(el);
399      } else if (t.matches("[data-cap-part='view']")) setView(el, t.value as ModView);
400    };
401    const onKey = (e: KeyboardEvent) => {
402      if (e.defaultPrevented || !list || isTypingKey(e) || singleKeysOff() || e.repeat) return;
403      const key = e.key;
404      if (key === "j" || key === "k") {
405        if (!listOwnsKeys(list)) return;
406        if (moveRowFocus(list, key === "j" ? 1 : -1) || list.contains(document.activeElement)) e.preventDefault();
407        return;
408      }
409      if (!["a", "r", "d", "x"].includes(key)) return;
410      const row = rowOf(document.activeElement);
411      if (!row || !list.contains(row) || document.querySelector("dialog:modal")) return;
412      e.preventDefault();
413      if (key === "x") {
414        const box = row.querySelector<HTMLInputElement>("[data-cap-part='select']");
415        if (box) {
416          box.checked = !box.checked;
417          syncSelection(el);
418        }
419        return;
420      }
421      // The focused row, or every selected row when the focused one is part of the selection.
422      const picked = selectedRows(el);
423      const rows = picked.includes(row) ? picked : [row];
424      if (key === DELETE_KEY) return void run(el, rows, "delete");
425      const action = (Object.keys(ACTION_KEY) as ModAction[]).find((a) => ACTION_KEY[a] === key);
426      if (!action || rows.every((r) => !decide(mentionOf(r).state, action, resetOn(el)))) return;
427      void run(el, rows, action);
428    };
429    // Single keys off: the hints and the announced keys go quiet, because pressing them does nothing.
430    const syncKeys = () => {
431      const off = singleKeysOff();
432      for (const b of el.querySelectorAll<HTMLElement>("[aria-keyshortcuts], [data-keys]")) {
433        if (off && b.hasAttribute("aria-keyshortcuts")) {
434          b.dataset.keys = b.getAttribute("aria-keyshortcuts") ?? "";
435          b.removeAttribute("aria-keyshortcuts");
436        } else if (!off && b.dataset.keys) {
437          b.setAttribute("aria-keyshortcuts", b.dataset.keys);
438          delete b.dataset.keys;
439        }
440      }
441    };
442    const observer = new MutationObserver(syncKeys);
443    observer.observe(document.documentElement, { attributes: true, attributeFilter: ["data-cap-single-keys"] });
444    const reapply = new MutationObserver(() => singleKeysOff() && syncKeys());
445    reapply.observe(el, { childList: true, subtree: true });
446
447    el.addEventListener("click", onClick);
448    el.addEventListener("change", onChange);
449    document.addEventListener("keydown", onKey);
450    refresh(el);
451    undo.push(() => {
452      el.removeEventListener("click", onClick);
453      el.removeEventListener("change", onChange);
454      document.removeEventListener("keydown", onKey);
455      observer.disconnect();
456      reapply.disconnect();
457      contexts.delete(el);
458      el.removeAttribute(READY);
459    });
460  }
461  return () => undo.forEach((f) => f());
462}