components/bulk-bar/bulk-bar.ts

Functions

Imports

It imports components/confirm-dialog/confirm-dialog.ts, components/message/message.ts. Imported by components/bulk-bar/bulk-bar.react.tsx, components/content/content.react.tsx, components/content/content.ts, components/media/media.ts.

Source

1// The bulk action bar: what a selection can be done to, said where the selection is. It counts
2// the selected items ("3 selected", a live status), offers the actions, and clears. A
3// reversible action runs at once and offers Undo through the message region (`z` runs it); a
4// destructive one previews every item in the shared confirm dialog and runs only when the
5// person says so, with focus on Cancel. No framework; the React wrapper calls the same
6// functions.
7
8import { confirm } from "../confirm-dialog/confirm-dialog.ts";
9import { GLYPHS, fail, say } from "../message/message.ts";
10
11const READY = "data-cap-ready";
12const SELECT = "input[type='checkbox'][data-cap-select]";
13
14// ---------------------------------------------------------------------------------------
15// Pure helpers.
16
17export interface BulkItem {
18  // What the app calls it (the checkbox's value).
19  id: string;
20  // What the person calls it: a filename, a post title. Listed in the preview.
21  label: string;
22}
23
24// "3 selected".
25export function countText(n: number): string {
26  return `${n} selected`;
27}
28
29// "item" or "items" for a count; `noun` is the singular.
30export function plural(n: number, noun: string, many?: string): string {
31  return n === 1 ? noun : (many ?? `${noun}s`);
32}
33
34// Fills {n} and {s} in a template: "Bin {n} item{s}" gives "Bin 12 items" and "Bin 1 item".
35export function fillCount(template: string, n: number): string {
36  return template.replace(/\{n\}/g, String(n)).replace(/\{s\}/g, n === 1 ? "" : "s");
37}
38
39// Every item of a destructive action, one line each, for the confirm dialog's list. The title
40// carries the count; the list is not shortened, because a preview that hides items is not one.
41export function previewItems(items: readonly BulkItem[]): string[] {
42  return items.map((i) => i.label);
43}
44
45// One item's outcome after an action that acted on several, for the bar's outcome list. A site
46// can refuse one item and do the rest, so each says its own result.
47export interface BulkOutcome {
48  id: string;
49  label: string;
50  ok: boolean;
51  // Why it was not done, or a note on what was: "Changed since you opened it."
52  message?: string;
53  // Where it is still used, when that is why it was refused: one line each.
54  usedBy?: readonly string[];
55}
56
57// The outcomes to list, refusals first: what needs the person comes before what is done.
58export function orderOutcomes(outcomes: readonly BulkOutcome[]): BulkOutcome[] {
59  return [...outcomes.filter((o) => !o.ok), ...outcomes.filter((o) => o.ok)];
60}
61
62// The outcome list's one line: "All 3 done.", "None done: 2 refused.", "2 done, 1 not done."
63export function outcomeSummary(outcomes: readonly BulkOutcome[]): string {
64  const done = outcomes.filter((o) => o.ok).length;
65  const not = outcomes.length - done;
66  if (not === 0) return done === 1 ? "Done." : `All ${done} done.`;
67  if (done === 0) return not === 1 ? "Not done." : `None done: ${not} refused.`;
68  return `${done} done, ${not} not done.`;
69}
70
71export interface BulkActionSpec {
72  // The action's name: "bin", "archive".
73  action: string;
74  items: readonly BulkItem[];
75  // A value from beside the button, such as a tag to add.
76  value?: string;
77  // Runs the action. Reject with an Error whose message says what happened.
78  run: (items: readonly BulkItem[], value?: string) => void | Promise<void>;
79  // Reverses it, for a reversible action: the message offers Undo.
80  undo?: (items: readonly BulkItem[], value?: string) => void | Promise<void>;
81  // A destructive action previews first: the dialog's title, lead and button, as templates with {n}.
82  destructive?: boolean;
83  confirmTitle?: string;
84  confirmLead?: string;
85  confirmAction?: string;
86  // What the region says afterwards ("Archived {n} drafts") and after Undo.
87  said?: string;
88  undone?: string;
89  // Where focus goes once the selection is cleared and the opener is gone.
90  returnTo?: HTMLElement | null;
91}
92
93// Runs one bulk action the way the family does it. Resolves true when it ran, false when it was
94// cancelled or failed. Reversible: at once, then a message with Undo. Destructive: a confirm
95// dialog lists every item, "Bin 12 items" performs, focus starts on Cancel.
96export async function performBulk(spec: BulkActionSpec): Promise<boolean> {
97  const n = spec.items.length;
98  if (n === 0) return false;
99  const verb = spec.action.charAt(0).toUpperCase() + spec.action.slice(1);
100  if (spec.destructive) {
101    const done = await confirm({
102      title: fillCount(spec.confirmTitle ?? `${verb} {n} item{s}?`, n),
103      lead: spec.confirmLead ? fillCount(spec.confirmLead, n) : undefined,
104      body: previewItems(spec.items),
105      action: fillCount(spec.confirmAction ?? `${verb} {n} item{s}`, n),
106      returnTo: spec.returnTo,
107      perform: async () => {
108        await spec.run(spec.items, spec.value);
109      },
110    });
111    if (done) say(fillCount(spec.said ?? `${verb}: {n} item{s}.`, n));
112    return done;
113  }
114  try {
115    await spec.run(spec.items, spec.value);
116  } catch (err) {
117    fail(fillCount(`Could not ${verb.toLowerCase()} {n} item{s}: ${err instanceof Error && err.message ? err.message : "nothing says why"}`, n));
118    return false;
119  }
120  const undo = spec.undo;
121  say(fillCount(spec.said ?? `${verb}: {n} item{s}.`, n), {
122    undo: undo ? () => undo(spec.items, spec.value) : undefined,
123    undone: spec.undone ? fillCount(spec.undone, n) : undefined,
124    returnFocus: spec.returnTo ?? undefined,
125  });
126  return true;
127}
128
129// ---------------------------------------------------------------------------------------
130// The DOM.
131
132export interface BulkHandler {
133  run: BulkActionSpec["run"];
134  undo?: BulkActionSpec["undo"];
135  said?: string;
136  undone?: string;
137}
138
139const handlers = new WeakMap<HTMLElement, Record<string, BulkHandler>>();
140
141// Says what each action of a bar does. The keys are the buttons' data-cap-bulk-action values.
142export function bindBulk(bar: HTMLElement, actions: Record<string, BulkHandler>): void {
143  handlers.set(bar, actions);
144}
145
146export function listOf(bar: HTMLElement): HTMLElement | null {
147  const id = bar.dataset.capList;
148  return id ? document.getElementById(id) : null;
149}
150
151function visible(el: HTMLElement): boolean {
152  return !el.closest("[hidden]") && el.getClientRects().length > 0;
153}
154
155// The selectable items of a list: its checkboxes marked data-cap-select.
156export function boxesOf(list: ParentNode): HTMLInputElement[] {
157  return Array.from(list.querySelectorAll<HTMLInputElement>(SELECT));
158}
159
160export function labelOf(box: HTMLInputElement): string {
161  const named = box.dataset.label ?? box.closest<HTMLElement>("[data-label]")?.dataset.label;
162  if (named) return named;
163  const text = box.labels?.[0]?.textContent?.trim();
164  return text || box.value;
165}
166
167// The items now selected, in document order. An item that is out of sight (a filter hid it) is
168// not acted on, so an action never reaches what the person cannot see.
169export function selectedItems(bar: HTMLElement): BulkItem[] {
170  const list = listOf(bar);
171  if (!list) return [];
172  return boxesOf(list)
173    .filter((b) => b.checked && !b.disabled && visible(b.closest<HTMLElement>("[data-label], li, tr, label") ?? b))
174    .map((b) => ({ id: b.value, label: labelOf(b) }));
175}
176
177// The selectable items the person can see now (a search or a filter may hide some).
178export function itemsInView(list: ParentNode): HTMLInputElement[] {
179  return boxesOf(list).filter((b) => !b.disabled && visible(b.closest<HTMLElement>("[data-label], li, tr, label") ?? b));
180}
181
182function fire(box: HTMLInputElement): void {
183  box.dispatchEvent(new Event("change", { bubbles: true }));
184}
185
186// Selects (or clears) every item in view. Real checkboxes change, so a form posts them.
187export function setAllInView(list: ParentNode, on: boolean): void {
188  for (const box of on ? itemsInView(list) : boxesOf(list)) {
189    if (box.checked === on) continue;
190    box.checked = on;
191    fire(box);
192  }
193}
194
195const part = <T extends HTMLElement = HTMLElement>(bar: HTMLElement, name: string) => bar.querySelector<T>(`[data-cap-part='${name}']`);
196
197// True while the bar lists outcomes: it stays in view with nothing selected, so the results of
198// the action just run can be read.
199function hasOutcomes(bar: HTMLElement): boolean {
200  const list = part(bar, "results");
201  return !!list && !list.hidden;
202}
203
204function svg(glyph: string): SVGSVGElement {
205  const el = document.createElementNS("http://www.w3.org/2000/svg", "svg");
206  el.setAttribute("class", "cap-status-glyph");
207  el.setAttribute("viewBox", "0 0 16 16");
208  el.setAttribute("aria-hidden", "true");
209  el.setAttribute("focusable", "false");
210  el.innerHTML = glyph;
211  return el;
212}
213
214let resultsSeq = 0;
215
216// Writes the outcome list into the bar (the markup on the doc page), replacing any before it, and
217// shows the bar. An empty list removes it.
218export function showOutcomes(bar: HTMLElement, outcomes: readonly BulkOutcome[]): void {
219  part(bar, "results")?.remove();
220  if (outcomes.length > 0) {
221    const box = document.createElement("div");
222    box.className = "cap-bulk-results";
223    box.dataset.capPart = "results";
224    box.setAttribute("role", "group");
225    const summary = document.createElement("p");
226    summary.className = "cap-bulk-results-summary";
227    summary.id = `${bar.id || "cap-bulk"}-results-${++resultsSeq}`;
228    summary.textContent = outcomeSummary(outcomes);
229    box.setAttribute("aria-labelledby", summary.id);
230    const list = document.createElement("ul");
231    list.className = "cap-bulk-results-list";
232    for (const o of orderOutcomes(outcomes)) {
233      const li = document.createElement("li");
234      li.dataset.ok = String(o.ok);
235      const word = document.createElement("span");
236      word.className = "cap-status";
237      word.dataset.tone = o.ok ? "ok" : "crit";
238      word.append(svg(o.ok ? GLYPHS.ok : GLYPHS.failure), o.ok ? "Done" : "Not done");
239      const label = document.createElement("span");
240      label.className = "cap-bulk-result-label";
241      label.textContent = o.label;
242      li.append(word, " ", label);
243      if (o.message) {
244        const m = document.createElement("span");
245        m.className = "cap-bulk-result-message";
246        m.textContent = o.message;
247        li.append(" ", m);
248      }
249      if (o.usedBy?.length) {
250        const uses = document.createElement("ul");
251        uses.className = "cap-bulk-result-uses";
252        for (const u of o.usedBy) {
253          const item = document.createElement("li");
254          item.textContent = u;
255          uses.append(item);
256        }
257        li.append(uses);
258      }
259      list.append(li);
260    }
261    const dismiss = document.createElement("button");
262    dismiss.type = "button";
263    dismiss.className = "cap-btn";
264    dismiss.dataset.variant = "quiet";
265    dismiss.dataset.size = "sm";
266    dismiss.dataset.capPart = "dismiss-results";
267    dismiss.textContent = "Dismiss results";
268    box.append(summary, list, dismiss);
269    bar.append(box);
270  }
271  refresh(bar);
272  // A bar with no list is not counted by refresh; outcomes alone put it in view.
273  if (outcomes.length > 0) bar.hidden = false;
274}
275const lastTouched = new WeakMap<HTMLElement, HTMLInputElement>();
276
277// Redraws the bar from the list: the count, hidden when there is none, the select-all label
278// and the header checkbox's state. The count is written a frame after the bar appears, so a
279// screen reader announces it (a status region that is shown and filled in one step is often
280// missed).
281export function refresh(bar: HTMLElement): number {
282  const list = listOf(bar);
283  if (!list) return Number.parseInt(part(bar, "count")?.textContent ?? bar.querySelector(".cap-bulk-count")?.textContent ?? "0", 10) || 0;
284  const items = selectedItems(bar);
285  const n = items.length;
286  const count = bar.querySelector<HTMLElement>(".cap-bulk-count");
287  const text = countText(n);
288  if (count) {
289    if (n > 0 && bar.hidden) {
290      bar.hidden = false;
291      count.textContent = "";
292      requestAnimationFrame(() => {
293        if (!bar.hidden) count.textContent = countText(selectedItems(bar).length);
294      });
295    } else if (n > 0) {
296      if (count.textContent !== text) count.textContent = text;
297    } else if (hasOutcomes(bar)) {
298      bar.hidden = false;
299      if (count.textContent !== "Nothing selected") count.textContent = "Nothing selected";
300    } else {
301      bar.hidden = true;
302    }
303  } else bar.hidden = n === 0 && !hasOutcomes(bar);
304  const total = itemsInView(list).length;
305  const all = part(bar, "select-all");
306  if (all) {
307    all.textContent = fillCount(all.dataset.capLabel ?? "Select all {n} in view", total);
308    all.hidden = total === 0 || n >= total;
309  }
310  for (const head of document.querySelectorAll<HTMLInputElement>(`input[data-cap-select-all][data-cap-list='${CSS.escape(list.id)}']`)) {
311    head.checked = total > 0 && n >= total;
312    head.indeterminate = n > 0 && n < total;
313  }
314  bar.dispatchEvent(new CustomEvent("cap-bulk-change", { bubbles: true, detail: { items, count: n } }));
315  return n;
316}
317
318// Where focus goes when the bar goes away: the bar's data-cap-return selector, the item last
319// touched, or the first item.
320function returnTarget(bar: HTMLElement): HTMLElement | null {
321  const list = listOf(bar);
322  const named = bar.dataset.capReturn ? document.querySelector<HTMLElement>(bar.dataset.capReturn) : null;
323  return named ?? lastTouched.get(bar) ?? (list ? boxesOf(list)[0] : null) ?? null;
324}
325
326// Clears the selection. When focus was in the bar (which hides), it goes back to the list: the
327// bar's data-cap-return selector, the item last touched, or the first item.
328export function clearSelection(bar: HTMLElement): void {
329  const list = listOf(bar);
330  if (!list) return;
331  const had = bar.contains(document.activeElement);
332  setAllInView(list, false);
333  refresh(bar);
334  bar.dispatchEvent(new CustomEvent("cap-bulk-clear", { bubbles: true }));
335  if (!had) return;
336  returnTarget(bar)?.focus();
337}
338
339function valueFor(button: HTMLElement): string | undefined {
340  const sel = button.dataset.capValue;
341  if (!sel) return undefined;
342  const el = document.querySelector<HTMLInputElement>(sel);
343  return el?.value.trim() ?? "";
344}
345
346// Presses one action button: the preview or the immediate run, as the button says.
347export async function invoke(bar: HTMLElement, button: HTMLElement): Promise<boolean> {
348  const items = selectedItems(bar);
349  const action = button.dataset.capBulkAction ?? "";
350  if (items.length === 0 || !action) return false;
351  const value = valueFor(button);
352  if (value === "") {
353    const input = document.querySelector<HTMLElement>(button.dataset.capValue ?? "");
354    input?.focus();
355    return false;
356  }
357  const h = handlers.get(bar)?.[action];
358  const ok = await performBulk({
359    action: button.dataset.capLabel ?? action,
360    items,
361    value,
362    run: h?.run ?? (() => undefined),
363    undo: h?.undo,
364    said: h?.said ?? button.dataset.capSaid,
365    undone: h?.undone ?? button.dataset.capUndone,
366    destructive: button.hasAttribute("data-destructive"),
367    confirmTitle: button.dataset.capConfirmTitle,
368    confirmLead: button.dataset.capConfirmLead,
369    confirmAction: button.dataset.capConfirmAction,
370    returnTo: returnTarget(bar),
371  });
372  if (ok) {
373    bar.dispatchEvent(new CustomEvent("cap-bulk-action", { bubbles: true, detail: { action, items, value } }));
374    clearSelection(bar);
375  }
376  return ok;
377}
378
379export function attachBulkBar(bar: HTMLElement): () => void {
380  if (bar.hasAttribute(READY)) return () => {};
381  bar.setAttribute(READY, "");
382  const list = listOf(bar);
383  const undo: Array<() => void> = [];
384  if (list) {
385    const onChange = (e: Event) => {
386      const t = e.target;
387      if (t instanceof HTMLInputElement && t.matches(SELECT)) lastTouched.set(bar, t);
388      refresh(bar);
389    };
390    list.addEventListener("change", onChange);
391    // Items added, removed or hidden (a filter, an upload, a bin) change what can be selected.
392    const watch = new MutationObserver(() => refresh(bar));
393    watch.observe(list, { childList: true, subtree: true, attributes: true, attributeFilter: ["hidden", "disabled"] });
394    const onKey = (e: KeyboardEvent) => {
395      if (e.key !== "Escape" || e.defaultPrevented || e.isComposing || bar.hidden) return;
396      if (selectedItems(bar).length === 0) return;
397      e.preventDefault();
398      clearSelection(bar);
399    };
400    list.addEventListener("keydown", onKey);
401    bar.addEventListener("keydown", onKey);
402    undo.push(
403      () => list.removeEventListener("change", onChange),
404      () => watch.disconnect(),
405      () => list.removeEventListener("keydown", onKey),
406      () => bar.removeEventListener("keydown", onKey),
407    );
408    for (const head of document.querySelectorAll<HTMLInputElement>(`input[data-cap-select-all][data-cap-list='${CSS.escape(list.id)}']`)) {
409      const onHead = () => {
410        setAllInView(list, head.checked);
411        refresh(bar);
412      };
413      head.addEventListener("change", onHead);
414      undo.push(() => head.removeEventListener("change", onHead));
415    }
416  }
417  const onClick = (e: MouseEvent) => {
418    const target = e.target instanceof Element ? e.target : null;
419    const button = target?.closest<HTMLElement>("button, [data-cap-bulk-action]");
420    if (!button || !bar.contains(button) || button.getAttribute("aria-disabled") === "true") return;
421    if (button.classList.contains("cap-bulk-clear")) return void clearSelection(bar);
422    if (button.dataset.capPart === "dismiss-results") {
423      const had = bar.contains(document.activeElement);
424      showOutcomes(bar, []);
425      if (had && bar.hidden) returnTarget(bar)?.focus();
426      return;
427    }
428    if (button.dataset.capPart === "select-all" && list) {
429      setAllInView(list, true);
430      refresh(bar);
431      return;
432    }
433    // Form mode: a submit button is the browser's own. It posts the form with the button's name
434    // and value and the server answers (a destructive intent with its own confirmation page), so
435    // nothing here runs, previews or offers Undo. It only refuses a press with nothing ticked.
436    if (button instanceof HTMLButtonElement && button.type === "submit") {
437      if (list && selectedItems(bar).length === 0) {
438        e.preventDefault();
439        fail("Tick at least one item first.");
440      }
441      return;
442    }
443    if (button.dataset.capBulkAction) void invoke(bar, button);
444  };
445  bar.addEventListener("click", onClick);
446  undo.push(() => bar.removeEventListener("click", onClick));
447  // A server-rendered outcome list carries its Dismiss hidden, since it needs script.
448  const dismiss = part(bar, "dismiss-results");
449  if (dismiss) dismiss.hidden = false;
450  if (list) refresh(bar);
451  return () => {
452    undo.forEach((f) => f());
453    bar.removeAttribute(READY);
454  };
455}
456
457// Attaches to every [data-cap="bulk-bar"] under root not yet attached. Returns a function that
458// detaches them all.
459export function enhance(root: ParentNode = document): () => void {
460  const undo = Array.from(root.querySelectorAll<HTMLElement>("[data-cap='bulk-bar']:not([data-cap-ready])")).map(attachBulkBar);
461  return () => undo.forEach((f) => f());
462}