components/message/message.ts

Functions

Imports

It imports no other module of this repo. Imported by components/bulk-bar/bulk-bar.ts, components/content/content.react.tsx, components/flag-list/flag-list.react.tsx, components/flag-list/flag-list.ts, components/history-list/history-list-rows.ts, components/history-list/history-list.react.tsx, components/history-list/history-list.ts, components/media/media.ts, components/message/message.react.tsx, components/moderation-queue/moderation-queue-model.ts, components/moderation-queue/moderation-queue.ts, components/publish-gate/publish-gate.react.tsx, components/publish-gate/publish-gate.ts.

Source

1// The page's one status region: the result of an action, said where the person is looking
2// and never taking focus. A message with Undo stays until dismissed; `z` runs its Undo.
3// No floating toast (decision, 0.1). No framework; the React wrapper uses the same helpers.
4//
5// What the region holds follows the Capsid Portal's lib/messages.ts (capsid/decisions.md
6// 2026-09-30, "admin panels review adopted", item 3): a performed action's result, with
7// Undo for a reversible change, and every failure that has no place beside its source. A
8// plain result is replaced by the next one. A warning (an audit row naming you was not
9// written), an Undo that failed, or a failure (a refresh, a copy) stays until you dismiss
10// it, whatever happens after it: the missing audit row is the one fact that cannot be
11// found later by looking.
12
13export type ReturnFocus = HTMLElement | (() => HTMLElement | null);
14
15export interface SayOptions {
16  // Reverses the action. Runs once; the region then says what was undone.
17  undo?: () => void | Promise<void>;
18  // What the region says once Undo has run: "The mention from fieldnotes.example is waiting
19  // again." Defaults to "Undone: " and the message.
20  undone?: string;
21  // A plain confirmation ("Copied") that clears itself after 4 seconds. Only when the
22  // control that caused it also shows it; ignored for a message with Undo, a warning or a
23  // failure.
24  clears?: boolean;
25  // Something that belongs with this result and that the person must not miss ("the audit
26  // row naming you was not written"). The message then stays until dismissed, whatever is
27  // said after it, and it keeps the warning even after its Undo has run.
28  warning?: string;
29  // Something that did not happen and has no control beside it to say so (a failed copy, a
30  // failed refresh). The text is the failure, announced as an alert; it stays until
31  // dismissed. A failure with a source goes beside it, as an alert (see Banner).
32  failure?: boolean;
33  // The control Undo acts on, or a function that finds it: focus goes there once Undo has
34  // run (the Portal returns focus to the switch it undid). Without it, focus goes to Dismiss.
35  returnFocus?: ReturnFocus;
36}
37
38// One message in the region.
39export interface Message {
40  id: number;
41  text: string;
42  warning: string | null;
43  undo: SayOptions["undo"] | null;
44  undone?: string;
45  returnFocus?: ReturnFocus;
46  // An Undo that was refused or could not run: Undo stays, and this says why.
47  error: string | null;
48  // Undo is running.
49  busy: boolean;
50  // Something that did not happen: the text is the failure.
51  failure: boolean;
52  clears: boolean;
53}
54
55export const CLEARS_AFTER_MS = 4000;
56
57export function newMessage(id: number, text: string, opts: SayOptions = {}): Message {
58  const warning = opts.warning ?? null;
59  const failure = !!opts.failure;
60  return {
61    id,
62    text,
63    warning,
64    undo: opts.undo ?? null,
65    undone: opts.undone,
66    returnFocus: opts.returnFocus,
67    error: null,
68    busy: false,
69    failure,
70    clears: !!opts.clears && !opts.undo && warning === null && !failure,
71  };
72}
73
74/** Whether a message stays when the next one arrives. */
75export function lasting(m: Pick<Message, "warning" | "error" | "failure">): boolean {
76  return m.failure || m.warning !== null || m.error !== null;
77}
78
79/** The region after `m` arrives: it first, then every lasting message before it. */
80export function withMessage(all: Message[], m: Message): Message[] {
81  return [m, ...all.filter(lasting)];
82}
83
84export function undoneText(text: string, undone?: string): string {
85  return undone ? `Undone. ${undone}` : `Undone: ${text}`;
86}
87
88// An Undo that threw: nothing was undone, so Undo stays and this says why.
89export function undoErrorText(err: unknown): string {
90  const why = err instanceof Error && err.message ? ` ${err.message}` : "";
91  return `Could not undo that.${why} Try again.`;
92}
93
94export function resolveFocus(f: ReturnFocus | undefined): HTMLElement | null {
95  const el = typeof f === "function" ? f() : (f ?? null);
96  return el?.isConnected ? el : null;
97}
98
99const TEXT_INPUT = /^(text|search|email|url|tel|password|number|date|datetime-local|month|week|time)$/;
100
101// True where a typed z is text, not a command: text inputs, textareas, selects, editable
102// content, and anything that says it is a text box or a combobox.
103export function isTypingTarget(target: EventTarget | null): boolean {
104  if (!(target instanceof Element)) return false;
105  if (target instanceof HTMLInputElement) return TEXT_INPUT.test(target.type || "text");
106  if (target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) return true;
107  if (target instanceof HTMLElement && target.isContentEditable) return true;
108  return !!target.closest("[role='textbox'], [role='combobox'], [role='searchbox']");
109}
110
111// `z` alone: no Ctrl, Alt, Meta or Shift, not a held repeat, not typed into a field.
112export function isUndoKey(e: KeyboardEvent): boolean {
113  return e.key === "z" && !e.ctrlKey && !e.altKey && !e.metaKey && !e.shiftKey && !e.repeat && !e.defaultPrevented && !isTypingTarget(e.composedPath()[0] ?? e.target);
114}
115
116// The message `z` would undo: the newest one with an Undo that is not already running.
117export function currentUndo(all: Message[]): Message | undefined {
118  return all.find((m) => m.undo && !m.busy);
119}
120
121// The leading glyph per kind, drawn in currentColor with the mark cut out (the same shapes
122// as Status: a tick in a circle, a triangle, an octagon). Hidden from screen readers.
123export type MessageKind = "ok" | "warning" | "failure";
124
125export const GLYPHS: Record<MessageKind, string> = {
126  ok: '<path fill="currentColor" fill-rule="evenodd" d="M8 1a7 7 0 1 0 0 14A7 7 0 1 0 8 1zM3.9 9l3 3 5.2-5.6-1.4-1.4-3.8 4.2-1.6-1.6z"/>',
127  warning: '<path fill="currentColor" fill-rule="evenodd" d="M8 1.2 15.4 14H.6zM7.3 6h1.4v4H7.3zM7.3 11h1.4v1.4H7.3z"/>',
128  failure: '<path fill="currentColor" fill-rule="evenodd" d="M5 1h6l4 4v6l-4 4H5l-4-4V5zM7.2 4h1.6v5H7.2zM7.2 10.4h1.6V12H7.2z"/>',
129};
130
131// A 16-unit glyph from one of the drawings above (or any inner SVG), hidden from assistive tech:
132// the word beside it says what it means. The moderation queue and the history list draw theirs with it.
133export function glyphSvg(inner: string, size = 14): SVGSVGElement {
134  const s = document.createElementNS("http://www.w3.org/2000/svg", "svg");
135  s.setAttribute("viewBox", "0 0 16 16");
136  s.setAttribute("width", String(size));
137  s.setAttribute("height", String(size));
138  s.setAttribute("aria-hidden", "true");
139  s.setAttribute("focusable", "false");
140  s.innerHTML = inner;
141  return s;
142}
143
144// What a message is, for its glyph and its edge: a failure; a warning or an Undo that
145// failed; otherwise a plain result.
146export function kindOf(m: Pick<Message, "warning" | "error" | "failure">): MessageKind {
147  return m.failure ? "failure" : m.warning !== null || m.error !== null ? "warning" : "ok";
148}
149
150interface Item {
151  el: HTMLElement;
152  glyph: SVGElement;
153  said: HTMLElement;
154  warn: HTMLElement;
155  warnText: HTMLElement;
156  error: HTMLElement;
157  undoBtn: HTMLButtonElement;
158  undoLabel: HTMLElement;
159  dismissBtn: HTMLButtonElement;
160}
161
162interface Settle {
163  // Focus goes here when given.
164  to?: HTMLElement | null;
165  // The message whose own Dismiss takes focus when its Undo button goes.
166  id?: number;
167  // Prefer the control that caused the message (after a Dismiss or a timer).
168  origin?: boolean;
169}
170
171interface Region {
172  el: HTMLElement;
173  messages: Message[];
174  items: Map<number, Item>;
175  nextId: number;
176  timers: Map<number, number>;
177  // The control that had focus when the last message was said: focus goes back there when
178  // a button inside the region disappears under it.
179  origin: Element | null;
180}
181
182const regions = new WeakMap<HTMLElement, Region>();
183
184function make(tag: string, className?: string, part?: string): HTMLElement {
185  const el = document.createElement(tag);
186  if (className) el.className = className;
187  if (part) el.dataset.capPart = part;
188  return el;
189}
190
191function buildItem(): Item {
192  const el = make("div", "cap-message-item", "item");
193  const glyph = document.createElementNS("http://www.w3.org/2000/svg", "svg");
194  glyph.setAttribute("class", "cap-message-glyph");
195  glyph.setAttribute("viewBox", "0 0 16 16");
196  glyph.setAttribute("aria-hidden", "true");
197  glyph.setAttribute("focusable", "false");
198  const text = make("p", "cap-message-text", "text");
199  const said = make("span", undefined, "said");
200  const warn = make("span", "cap-message-warning");
201  warn.hidden = true;
202  const bold = make("b");
203  bold.textContent = "Warning:";
204  const warnText = make("span");
205  warn.append(" ", bold, " ", warnText);
206  const error = make("span", "cap-message-error");
207  error.setAttribute("role", "alert");
208  error.hidden = true;
209  text.append(said, warn, error);
210
211  const undoBtn = make("button", "cap-link-btn cap-message-undo", "undo") as HTMLButtonElement;
212  undoBtn.type = "button";
213  const undoLabel = make("span");
214  undoLabel.textContent = "Undo";
215  const kbd = make("kbd");
216  kbd.setAttribute("aria-hidden", "true");
217  kbd.textContent = "z";
218  undoBtn.append(undoLabel, " ", kbd);
219
220  const dismissBtn = make("button", "cap-btn cap-message-dismiss", "dismiss") as HTMLButtonElement;
221  dismissBtn.type = "button";
222  dismissBtn.textContent = "Dismiss";
223
224  el.append(glyph, text, undoBtn, dismissBtn);
225  return { el, glyph, said, warn, warnText, error, undoBtn, undoLabel, dismissBtn };
226}
227
228function paint(it: Item, m: Message): void {
229  it.el.dataset.id = String(m.id);
230  if (lasting(m)) it.el.dataset.lasting = "";
231  else delete it.el.dataset.lasting;
232  const kind = kindOf(m);
233  if (it.el.dataset.kind !== kind) {
234    it.el.dataset.kind = kind;
235    it.glyph.innerHTML = GLYPHS[kind];
236  }
237  if (it.said.textContent !== m.text) it.said.textContent = m.text;
238  if (m.failure) it.said.setAttribute("role", "alert");
239  else it.said.removeAttribute("role");
240  it.warn.hidden = m.warning === null;
241  if (it.warnText.textContent !== (m.warning ?? "")) it.warnText.textContent = m.warning ?? "";
242  it.error.hidden = m.error === null;
243  if (it.error.textContent !== (m.error ?? "")) it.error.textContent = m.error ?? "";
244  it.undoBtn.hidden = !m.undo;
245  if (m.busy) it.undoBtn.setAttribute("aria-busy", "true");
246  else it.undoBtn.removeAttribute("aria-busy");
247  it.undoLabel.textContent = m.busy ? "Undoing..." : "Undo";
248  // Every message that stays can be dismissed; one that clears itself has no buttons. While
249  // Undo runs, Dismiss waits, so the answer is not hidden.
250  it.dismissBtn.hidden = m.clears;
251  if (m.busy) it.dismissBtn.setAttribute("aria-disabled", "true");
252  else it.dismissBtn.removeAttribute("aria-disabled");
253}
254
255// Makes the region's children the messages, in order, newest first. An item that is still
256// there is changed in place, so a button that has focus keeps it and a text is not said twice.
257function render(r: Region): void {
258  const live = new Set(r.messages.map((m) => m.id));
259  for (const [id, it] of r.items) {
260    if (!live.has(id)) {
261      it.el.remove();
262      r.items.delete(id);
263    }
264  }
265  let ref = r.el.firstElementChild;
266  for (const m of r.messages) {
267    let it = r.items.get(m.id);
268    const fresh = !it;
269    if (!it) {
270      it = buildItem();
271      r.items.set(m.id, it);
272    }
273    paint(it, m);
274    if (!fresh && it.el === ref) ref = ref.nextElementSibling;
275    else r.el.insertBefore(it.el, ref);
276  }
277}
278
279function focusInside(r: Region): boolean {
280  return r.el.contains(document.activeElement);
281}
282
283// After the button that had focus goes away, focus lands somewhere sensible, never on the
284// body: where the caller says, else the region's own Dismiss for that message, else the
285// control that caused the message, else the main region.
286function settleFocus(r: Region, s: Settle): void {
287  if (s.to) return s.to.focus();
288  const active = document.activeElement;
289  if (active && r.el.contains(active) && active.isConnected && !(active as HTMLElement).hidden) return;
290  const back = r.origin instanceof HTMLElement && r.origin.isConnected ? r.origin : null;
291  if (s.origin) return (back ?? document.querySelector<HTMLElement>("main"))?.focus();
292  const own = s.id !== undefined ? r.items.get(s.id)?.dismissBtn : undefined;
293  if (own && !own.hidden) return own.focus();
294  const any = r.el.querySelector<HTMLButtonElement>("[data-cap-part='dismiss']:not([hidden])");
295  if (any) return any.focus();
296  (back ?? document.querySelector<HTMLElement>("main"))?.focus();
297}
298
299function set(r: Region, next: Message[], settle: Settle = {}): void {
300  const hadFocus = focusInside(r);
301  r.messages = next;
302  render(r);
303  const ids = new Set(next.map((m) => m.id));
304  for (const [id, t] of r.timers) {
305    if (!ids.has(id)) {
306      window.clearTimeout(t);
307      r.timers.delete(id);
308    }
309  }
310  for (const m of next) {
311    if (!m.clears || r.timers.has(m.id)) continue;
312    const id = m.id;
313    r.timers.set(
314      id,
315      window.setTimeout(() => {
316        r.timers.delete(id);
317        set(
318          r,
319          r.messages.filter((x) => x.id !== id),
320          { origin: true },
321        );
322      }, CLEARS_AFTER_MS),
323    );
324  }
325  if (settle.to || hadFocus) settleFocus(r, settle);
326}
327
328function region(el: HTMLElement): Region {
329  let r = regions.get(el);
330  if (r) return r;
331  r = { el, messages: [], items: new Map(), nextId: 1, timers: new Map(), origin: null };
332  regions.set(el, r);
333  return r;
334}
335
336// The page's region: the first one enhanced, or the first one present.
337function find(): Region | null {
338  const el = document.querySelector<HTMLElement>("[data-cap='message'][data-cap-ready]") ?? document.querySelector<HTMLElement>("[data-cap='message']");
339  if (!el) return null;
340  if (!el.hasAttribute("data-cap-ready")) enhance(el.parentNode ?? document);
341  return region(el);
342}
343
344// Says a message in the page's region. Does not move focus. A plain result replaces the
345// plain result before it; a warning, a failure and a failed Undo stay.
346export function say(text: string, opts: SayOptions = {}): void {
347  const r = find();
348  if (!r) {
349    console.warn("capsomer message: no [data-cap='message'] region on this page.");
350    return;
351  }
352  const active = document.activeElement;
353  if (active && active !== document.body && !r.el.contains(active)) r.origin = active;
354  set(r, withMessage(r.messages, newMessage(r.nextId++, text, opts)));
355}
356
357// Says that something did not happen. Stays until dismissed.
358export function fail(text: string): void {
359  say(text, { failure: true });
360}
361
362function clearIn(r: Region, id?: number): void {
363  set(
364    r,
365    id === undefined ? [] : r.messages.filter((m) => m.id !== id),
366    { origin: true },
367  );
368}
369
370// Clears the page's region, lasting messages too.
371export function dismiss(): void {
372  const r = find();
373  if (r) clearIn(r);
374}
375
376async function undoIn(r: Region, id: number): Promise<boolean> {
377  const m = r.messages.find((x) => x.id === id);
378  if (!m?.undo || m.busy) return false;
379  const run = m.undo;
380  set(
381    r,
382    r.messages.map((x) => (x.id === id ? { ...x, busy: true, error: null } : x)),
383  );
384  try {
385    await run();
386  } catch (err) {
387    // Nothing was undone, so Undo stays available, and the message says why. It stays too.
388    if (r.messages.some((x) => x.id === id)) {
389      set(
390        r,
391        r.messages.map((x) => (x.id === id ? { ...x, busy: false, error: undoErrorText(err) } : x)),
392      );
393    }
394    return false;
395  }
396  const to = resolveFocus(m.returnFocus);
397  // The Undo may have said something itself, which replaced this message: then there is
398  // nothing more to say. Either way it has run.
399  if (!r.messages.some((x) => x.id === id)) return true;
400  const said = undoneText(m.text, m.undone);
401  if (m.warning !== null) {
402    // A result that carried a warning keeps it, without its Undo, and the Undo's own result
403    // arrives beside it.
404    const kept = r.messages.map((x) => (x.id === id ? { ...x, undo: null, busy: false, error: null } : x));
405    set(r, withMessage(kept, newMessage(r.nextId++, said)), { to, id });
406  } else {
407    set(
408      r,
409      r.messages.map((x) => (x.id === id ? newMessage(id, said) : x)),
410      { to, id },
411    );
412  }
413  return true;
414}
415
416// Runs the current Undo, once. Returns false when there is nothing to undo.
417export function runUndo(): Promise<boolean> {
418  const r = find();
419  const m = r ? currentUndo(r.messages) : undefined;
420  return r && m ? undoIn(r, m.id) : Promise.resolve(false);
421}
422
423// Attaches to every [data-cap="message"] under root not yet attached: the region is empty
424// and takes the messages said into it, each with its own Undo and Dismiss, and `z` on the
425// document. A region with data-cap-undo-key="off" leaves `z` alone (single-key shortcuts
426// can be switched off). Returns a function that detaches.
427export function enhance(root: ParentNode = document): () => void {
428  const undo: Array<() => void> = [];
429  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='message']:not([data-cap-ready])")) {
430    el.dataset.capReady = "";
431    if (!el.getAttribute("role")) el.setAttribute("role", "status");
432    if (!el.hasAttribute("aria-label")) el.setAttribute("aria-label", "Results and failures");
433    // A new message is read by itself; the ones before it are not read again.
434    if (!el.hasAttribute("aria-atomic")) el.setAttribute("aria-atomic", "false");
435    // 0.1.0's region held one text and its two buttons directly: items replace them.
436    for (const old of el.querySelectorAll(":scope > [data-cap-part]:not([data-cap-part='item'])")) old.remove();
437    const r = region(el);
438    const onClick = (e: MouseEvent) => {
439      const target = e.target as Element;
440      const id = Number(target.closest<HTMLElement>("[data-cap-part='item']")?.dataset.id);
441      const part = target.closest("[data-cap-part]")?.getAttribute("data-cap-part");
442      if (Number.isNaN(id)) return;
443      if (part === "undo") void undoIn(r, id);
444      else if (part === "dismiss" && !r.messages.find((x) => x.id === id)?.busy) clearIn(r, id);
445    };
446    const onKey = (e: KeyboardEvent) => {
447      if (el.dataset.capUndoKey === "off" || !isUndoKey(e)) return;
448      const m = currentUndo(r.messages);
449      if (!m) return;
450      e.preventDefault();
451      void undoIn(r, m.id);
452    };
453    el.addEventListener("click", onClick);
454    document.addEventListener("keydown", onKey);
455    undo.push(() => {
456      el.removeEventListener("click", onClick);
457      document.removeEventListener("keydown", onKey);
458      for (const t of r.timers.values()) window.clearTimeout(t);
459      r.timers.clear();
460      delete el.dataset.capReady;
461    });
462  }
463  return () => undo.forEach((f) => f());
464}