components/publish-gate/publish-gate.ts

Functions

Imports

It imports components/confirm-dialog/confirm-dialog.ts, components/flag-list/flag-list.ts, components/message/message.ts, components/publish-gate/publish-gate-model.ts, components/publish-gate/publish-transition.ts, components/row-list/row-list.ts, components/time/time.ts. Imported by components/publish-gate/publish-gate.react.tsx.

Source

1// The publish gate: one region beside the publish button that says whether this can go out, and if
2// not, exactly why. Failing checks come first, required apart from advisory, each row naming its
3// cause and linking to it; the passing ones fold into a disclosure; one row per destination site
4// carries its own state and its own button. Pure helpers first (they decide the states and the
5// words), then the page: the DOM is the one source of truth, every row is rendered from its data
6// attributes, so what the server delivered and what this module redraws are the same markup. No
7// framework; the React wrapper reuses the pure functions.
8// The transitions and their intents are publish-transition.ts, the gate's DOM-free half.
9
10import { confirm } from "../confirm-dialog/confirm-dialog.ts";
11import { statusEl } from "../flag-list/flag-list.ts";
12import { fail, say } from "../message/message.ts";
13import { attachRowList } from "../row-list/row-list.ts";
14import { enhance as enhanceTime } from "../time/time.ts";
15import { type CheckState, type GateCheck, type GateHold, type GatePublished, type GateSite, type GateState, WORD, advisoryHeading, appliesTo, checkState, countChecks, describeGate, holdText, passedHeading, requiredHeading, siteDetail, siteState } from "./publish-gate-model.ts";
16import { FIRST_PUBLICATION_NOTE, PUBLISH_CONFIRMED_INTENT } from "./publish-transition.ts";
17
18export { checkState, sortChecks, gateState, appliesTo, siteState, worstState, countChecks, requiredHeading, advisoryHeading, passedHeading, holdText, nameList, stateWord, describeGate, siteDetail } from "./publish-gate-model.ts";
19export type { GateState, CheckState, GateCheck, GateHold, GatePublished, GateSite, GateCounts, GateReading } from "./publish-gate-model.ts";
20
21export { FIRST_PUBLICATION_NOTE };
22
23// ---------------------------------------------------------------------------------------
24// The page.
25
26const READY = "data-cap-ready";
27const part = <T extends HTMLElement = HTMLElement>(el: ParentNode, name: string) => el.querySelector<T>(`[data-cap-part='${name}']`);
28
29function h<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, text?: string): HTMLElementTagNameMap[K] {
30  const e = document.createElement(tag);
31  if (className) e.className = className;
32  if (text !== undefined) e.textContent = text;
33  return e;
34}
35
36const TONE: Record<GateState, "crit" | "info" | "ok"> = { blocked: "crit", held: "info", ready: "ok", published: "ok" };
37const GLYPH: Record<GateState, string> = { blocked: "crit", held: "info", ready: "ok", published: "ok" };
38
39export function stateStatus(s: GateState): HTMLSpanElement {
40  return statusEl(TONE[s], WORD[s], GLYPH[s]);
41}
42
43// A check, read from its row.
44export function readCheck(li: HTMLElement): GateCheck {
45  const c: GateCheck = {
46    id: li.dataset.check ?? li.id,
47    name: li.dataset.name ?? "",
48    required: li.hasAttribute("data-required"),
49    ok: li.dataset.ok === "true",
50    cause: li.dataset.cause ?? "",
51  };
52  if (li.dataset.pass) c.pass = li.dataset.pass;
53  if (li.dataset.href) c.href = li.dataset.href;
54  if (li.dataset.fix) c.fix = li.dataset.fix;
55  if (li.dataset.site) c.site = li.dataset.site;
56  return c;
57}
58
59export function readSite(li: HTMLElement): GateSite {
60  const s: GateSite = { id: li.dataset.site ?? li.id, name: li.dataset.name ?? "" };
61  if (li.dataset.holdText) s.hold = { text: li.dataset.holdText, note: li.dataset.holdNote };
62  if (li.dataset.publishedAt && li.dataset.publishedUrl) s.published = { at: li.dataset.publishedAt, url: li.dataset.publishedUrl };
63  if (li.hasAttribute("data-first")) s.first = true;
64  return s;
65}
66
67export interface GateHooks {
68  // Publish to these destinations. Resolve when it is live; reject with an Error whose message says why not.
69  publish?: (siteIds: string[]) => Promise<void>;
70  // Take it off the public site. Reversible, so it is done at once and offers Undo.
71  unpublish?: (siteIds: string[]) => Promise<void>;
72}
73
74export interface GateHandle {
75  refresh(): void;
76  // Sets one check's result: the row, the groups, the counts, the destinations and the summary follow.
77  setCheck(id: string, patch: { ok: boolean; cause?: string }): void;
78  setHold(siteId: string, hold: GateHold | null): void;
79  setPublished(siteId: string, published: GatePublished | null): void;
80  detach(): void;
81}
82
83const hooksFor = new WeakMap<HTMLElement, GateHooks>();
84
85export function attachPublishGate(region: HTMLElement, hooks: GateHooks = {}): GateHandle {
86  hooksFor.set(region, hooks);
87  const summary = part(region, "summary");
88  const summaryId = summary?.id ?? "";
89  const list = region.querySelector<HTMLElement>(".cap-gate-all");
90  const detachRows = list ? attachRowList(list) : () => {};
91  const busy = new Set<string>();
92  let previous = "";
93
94  const sectionRows = (name: string) => region.querySelector<HTMLElement>(`.cap-gate-section[data-section='${name}'] .cap-gate-section-rows`);
95  const checkRows = () => Array.from(region.querySelectorAll<HTMLElement>("li.cap-check"));
96  const siteRows = () => Array.from(region.querySelectorAll<HTMLElement>("li.cap-gate-site"));
97
98  // The containers that hold a destination's buttons: inside its row, or anywhere on the page
99  // that names this gate and site (the editor bar's own publish button).
100  const containers = (siteId: string) => {
101    const all = Array.from(document.querySelectorAll<HTMLElement>("[data-cap-actions]")).filter((c) => c.dataset.site === siteId && (c.dataset.gate === region.id || region.contains(c)));
102    return all;
103  };
104
105  // A check's row, from its data: status, title and link, detail, the site it concerns.
106  const renderCheck = (li: HTMLElement) => {
107    const c = readCheck(li);
108    const st = checkState(c);
109    const status = li.querySelector<HTMLElement>(".cap-row-status");
110    if (status) status.replaceChildren(st === "failing" ? statusEl("crit", "Failing") : st === "advisory" ? statusEl("warn", "Advisory") : statusEl("ok", "Passed"));
111    if (st === "failing") li.dataset.tone = "crit";
112    else delete li.dataset.tone;
113    const words = c.ok ? (c.pass ?? `${c.name}: passing`) : c.cause;
114    const title = li.querySelector<HTMLElement>(".cap-row-title");
115    if (title) {
116      if (c.href) {
117        const a = h("a", undefined, words);
118        a.href = c.href;
119        a.setAttribute("aria-describedby", `${li.id}-s ${li.id}-d`);
120        title.replaceChildren(a);
121      } else title.replaceChildren(Object.assign(h("span", "cap-gate-title-text"), { textContent: words }));
122    }
123    const detail = li.querySelector<HTMLElement>(".cap-row-detail");
124    if (detail) {
125      detail.replaceChildren(h("span", "cap-check-name", c.name));
126      if (!c.ok && c.fix) detail.append(". ", h("span", "cap-check-fix", `Fix: ${c.fix}`));
127    }
128    const meta = li.querySelector<HTMLElement>(".cap-row-meta");
129    if (meta) {
130      const siteName = c.site ? siteRows().find((r) => r.dataset.site === c.site)?.dataset.name : undefined;
131      meta.replaceChildren(...(siteName ? [document.createTextNode(`on ${siteName}`)] : []));
132    }
133  };
134
135  // One destination's buttons, in each container that holds them.
136  const renderActions = (site: GateSite, state: GateState) => {
137    for (const box of containers(site.id)) {
138      const name = box.dataset.siteLabel;
139      const suffix = name ? `, ${name}` : "";
140      // Buttons in a row are small; the page's own publish control sets data-btn-size="default".
141      const size = box.dataset.btnSize === "default" ? "" : (box.dataset.btnSize ?? "sm");
142      if (state === "published") {
143        const view = box.querySelector<HTMLAnchorElement>("a[data-cap-part='view']");
144        const un = box.querySelector<HTMLButtonElement>("button[data-cap-part='unpublish']");
145        if (!view || !un || box.querySelector("[data-cap-part='publish']")) {
146          const a = h("a", "cap-btn");
147          a.dataset.capPart = "view";
148          if (size) a.dataset.size = size;
149          a.href = site.published?.url ?? "#";
150          a.textContent = "View";
151          // With several destinations the name says which one; the visible word starts it.
152          if (suffix) a.setAttribute("aria-label", `View live page${suffix}`);
153          const b = h("button", "cap-btn");
154          b.type = "button";
155          b.dataset.capPart = "unpublish";
156          if (size) b.dataset.size = size;
157          b.dataset.variant = "quiet";
158          b.dataset.site = site.id;
159          b.textContent = "Unpublish";
160          if (suffix) b.setAttribute("aria-label", `Unpublish${suffix}`);
161          box.replaceChildren(a, b);
162        } else if (site.published) view.href = site.published.url;
163        continue;
164      }
165      let b = box.querySelector<HTMLButtonElement>("button[data-cap-part='publish']");
166      if (!b) {
167        b = h("button", "cap-btn");
168        b.type = "submit";
169        b.name = "intent";
170        b.value = "publish";
171        b.dataset.capPart = "publish";
172        if (size) b.dataset.size = size;
173        b.dataset.site = site.id;
174        box.replaceChildren(b);
175      }
176      const isBusy = busy.has(site.id);
177      const label = isBusy ? "Publishing..." : state === "blocked" ? "Publish blocked" : state === "held" ? "Publish held" : "Publish";
178      b.dataset.variant = state === "ready" || isBusy ? "primary" : "secondary";
179      if (state === "ready" && !isBusy) b.removeAttribute("aria-disabled");
180      else b.setAttribute("aria-disabled", "true");
181      if (isBusy) b.setAttribute("aria-busy", "true");
182      else b.removeAttribute("aria-busy");
183      // A blocked or held button stays focusable and says why: the region's summary describes it.
184      if (state === "ready" && !isBusy) b.removeAttribute("aria-describedby");
185      else if (summaryId) b.setAttribute("aria-describedby", summaryId);
186      if (b.textContent !== label) b.textContent = label;
187      if (suffix) b.setAttribute("aria-label", `${label}${suffix}`);
188      else b.removeAttribute("aria-label");
189    }
190  };
191
192  const refresh = () => {
193    const checks = checkRows();
194    const sites = siteRows();
195    // Rows into the group their state says.
196    const order = new Map(checks.map((li, i) => [li, Number(li.dataset.order ?? i)]));
197    for (const li of checks) {
198      if (!li.dataset.order) li.dataset.order = String(order.get(li));
199      renderCheck(li);
200    }
201    const targets: Record<CheckState, HTMLElement | null> = { failing: sectionRows("required"), advisory: sectionRows("advisory"), passed: sectionRows("passed") };
202    const bucket: Record<CheckState, HTMLElement[]> = { failing: [], advisory: [], passed: [] };
203    for (const li of checks) bucket[checkState(readCheck(li))].push(li);
204    for (const k of ["failing", "advisory", "passed"] as const) {
205      const ul = targets[k];
206      if (!ul) continue;
207      const rows = bucket[k].sort((a, b) => Number(a.dataset.order) - Number(b.dataset.order));
208      rows.forEach((li, i) => {
209        if (ul.children[i] !== li) ul.insertBefore(li, ul.children[i] ?? null);
210      });
211    }
212    const data = checks.map(readCheck);
213    const counts = countChecks(data);
214    const setSection = (name: string, heading: string, shown: boolean) => {
215      const sec = region.querySelector<HTMLElement>(`.cap-gate-section[data-section='${name}']`);
216      if (!sec) return;
217      sec.hidden = !shown;
218      const t = sec.querySelector<HTMLElement>(".cap-gate-group-title");
219      if (t && t.textContent !== heading) t.textContent = heading;
220    };
221    setSection("required", requiredHeading(counts.requiredFailing), counts.requiredFailing > 0);
222    setSection("advisory", advisoryHeading(counts.advisoryFailing), counts.advisoryFailing > 0);
223    const passedSec = region.querySelector<HTMLElement>(".cap-gate-section[data-section='passed']");
224    if (passedSec) {
225      passedSec.hidden = counts.passed === 0;
226      const sum = passedSec.querySelector("summary");
227      if (sum && sum.textContent !== passedHeading(counts.passed)) sum.textContent = passedHeading(counts.passed);
228    }
229    const clear = part(region, "clear");
230    if (clear) clear.hidden = counts.requiredFailing + counts.advisoryFailing > 0;
231
232    // Destinations.
233    const model = sites.map(readSite);
234    for (const [i, li] of sites.entries()) {
235      const site = model[i] as GateSite;
236      const mine = data.filter((c) => appliesTo(c, site.id));
237      const state = siteState(site, data);
238      li.dataset.state = state;
239      if (state === "blocked") li.dataset.tone = "crit";
240      else delete li.dataset.tone;
241      li.querySelector(".cap-row-status")?.replaceChildren(stateStatus(state));
242      const detail = li.querySelector<HTMLElement>(".cap-row-detail");
243      if (detail) {
244        const failing = mine.filter((c) => c.required && !c.ok);
245        const adv = mine.filter((c) => !c.required && !c.ok).length;
246        detail.textContent = siteDetail(state, failing, adv, site);
247      }
248      const meta = li.querySelector<HTMLElement>(".cap-row-meta");
249      if (meta) {
250        meta.replaceChildren();
251        if (state === "published" && site.published) {
252          const t = h("time", "cap-time");
253          t.dataset.cap = "time";
254          t.dataset.format = "exact";
255          t.dateTime = site.published.at;
256          t.textContent = site.published.at;
257          meta.append(t);
258          enhanceTime(meta);
259        }
260      }
261      renderActions(site, state);
262    }
263
264    // The region.
265    const reading = describeGate(model, data);
266    region.dataset.state = reading.state;
267    if (summary) {
268      // Only a changed sentence is written, so a polite region does not repeat itself.
269      const words = `${WORD[reading.state]}${reading.rest}`;
270      if (summary.textContent !== words) summary.replaceChildren(stateStatus(reading.state), reading.rest);
271    }
272    if (previous && previous !== reading.state) region.dispatchEvent(new CustomEvent("cap:gate-state", { bubbles: true, detail: { state: reading.state, sites: Object.fromEntries(sites.map((li) => [li.dataset.site, li.dataset.state])) } }));
273    previous = reading.state;
274  };
275
276  // The page's message region says results, with Undo; the summary is itself polite and live.
277  const announce = (text: string, undo?: () => Promise<void>, undone?: string) => {
278    if (!document.querySelector("[data-cap='message']")) return;
279    say(text, undo ? { undo, undone } : {});
280  };
281  const problem = (text: string) => {
282    if (document.querySelector("[data-cap='message']")) fail(text);
283  };
284
285  const setBusy = (id: string, on: boolean) => {
286    if (on) busy.add(id);
287    else busy.delete(id);
288    refresh();
289  };
290
291  const siteRow = (id: string) => siteRows().find((r) => r.dataset.site === id);
292  const setPublished = (id: string, p: GatePublished | null) => {
293    const li = siteRow(id);
294    if (!li) return;
295    if (p) {
296      li.dataset.publishedAt = p.at;
297      li.dataset.publishedUrl = p.url;
298      delete li.dataset.first;
299    } else {
300      delete li.dataset.publishedAt;
301      delete li.dataset.publishedUrl;
302    }
303    refresh();
304  };
305  const setHold = (id: string, hold: GateHold | null) => {
306    const li = siteRow(id);
307    if (!li) return;
308    if (hold) {
309      li.dataset.holdText = holdText(hold);
310      if (hold.note) li.dataset.holdNote = hold.note;
311      else delete li.dataset.holdNote;
312    } else {
313      delete li.dataset.holdText;
314      delete li.dataset.holdNote;
315    }
316    refresh();
317  };
318  const setCheck = (id: string, patch: { ok: boolean; cause?: string }) => {
319    const li = checkRows().find((r) => r.dataset.check === id);
320    if (!li) return;
321    li.dataset.ok = String(patch.ok);
322    if (patch.cause !== undefined) li.dataset.cause = patch.cause;
323    refresh();
324  };
325
326  const run = async (site: GateSite, button: HTMLElement | null): Promise<void> => {
327    const hk = hooksFor.get(region) ?? {};
328    const form = (button as HTMLButtonElement | null)?.form;
329    if (!hk.publish && form && button instanceof HTMLButtonElement) {
330      // No script hook: the form posts as it would without JavaScript, with the confirmed intent.
331      button.value = site.first ? PUBLISH_CONFIRMED_INTENT : "publish";
332      form.requestSubmit(button);
333      return;
334    }
335    setBusy(site.id, true);
336    try {
337      await hk.publish?.([site.id]);
338    } catch (err) {
339      setBusy(site.id, false);
340      problem(`Could not publish to ${site.name}: ${err instanceof Error ? err.message : String(err)}`);
341      (button?.isConnected ? button : containers(site.id)[0]?.querySelector<HTMLElement>("button"))?.focus();
342      return;
343    }
344    busy.delete(site.id);
345    setPublished(site.id, { at: new Date().toISOString(), url: siteRow(site.id)?.dataset.liveUrl ?? "#" });
346    announce(`Published to ${site.name}.`);
347    containers(site.id)[0]?.querySelector<HTMLElement>("a, button")?.focus();
348  };
349
350  const publish = async (id: string, button: HTMLElement | null) => {
351    const li = siteRow(id);
352    if (!li || busy.has(id)) return;
353    const site = readSite(li);
354    if (site.first) {
355      // One-way for a first publication: previewed, with the destination listed, focus on Cancel.
356      await confirm({
357        title: `Publish to ${site.name}?`,
358        lead: "Publishing for the first time cannot be taken back quietly: it goes public at once.",
359        body: [`${site.name}: ${FIRST_PUBLICATION_NOTE}`],
360        action: `Publish to ${site.name}`,
361        returnTo: button,
362        perform: async () => {
363          await run(site, button);
364        },
365      });
366      return;
367    }
368    await run(site, button);
369  };
370
371  const unpublish = async (id: string, button: HTMLElement | null) => {
372    const li = siteRow(id);
373    if (!li) return;
374    const site = readSite(li);
375    const hk = hooksFor.get(region) ?? {};
376    const was = site.published;
377    try {
378      await hk.unpublish?.([id]);
379    } catch (err) {
380      return problem(`Could not unpublish from ${site.name}: ${err instanceof Error ? err.message : String(err)}`);
381    }
382    void button;
383    setPublished(id, null);
384    containers(id)[0]?.querySelector<HTMLElement>("button")?.focus();
385    announce(
386      `Unpublished from ${site.name}.`,
387      async () => {
388        await hk.publish?.([id]);
389        if (was) setPublished(id, was);
390      },
391      `Published to ${site.name} again.`,
392    );
393  };
394
395  const onClick = (e: MouseEvent) => {
396    const btn = (e.target as Element).closest<HTMLElement>("[data-cap-part='publish'], [data-cap-part='unpublish']");
397    if (!btn) return;
398    const box = btn.closest<HTMLElement>("[data-cap-actions]");
399    if (!box || !(box.dataset.gate === region.id || region.contains(box))) return;
400    const id = box.dataset.site ?? "";
401    if (btn.dataset.capPart === "unpublish") return void unpublish(id, btn);
402    // A blocked or held button is focusable so its reason can be heard; pressing it does nothing.
403    if (btn.getAttribute("aria-disabled") === "true") return void e.preventDefault();
404    const li = siteRow(id);
405    const hk = hooksFor.get(region) ?? {};
406    // With no hook and a form, a republication posts natively; a first one is previewed first.
407    if (!hk.publish && btn instanceof HTMLButtonElement && btn.form && li && !li.hasAttribute("data-first")) return;
408    e.preventDefault();
409    void publish(id, btn);
410  };
411  document.addEventListener("click", onClick);
412
413  // Any change to a check, a hold or a publication redraws; an app only flips the data.
414  const mo = new MutationObserver(() => refresh());
415  mo.observe(region, { subtree: true, attributes: true, attributeFilter: ["data-ok", "data-cause", "data-hold-text", "data-hold-note", "data-published-at", "data-published-url"] });
416
417  refresh();
418  return {
419    refresh,
420    setCheck,
421    setHold,
422    setPublished,
423    detach() {
424      document.removeEventListener("click", onClick);
425      mo.disconnect();
426      detachRows();
427      hooksFor.delete(region);
428      region.removeAttribute(READY);
429    },
430  };
431}
432
433// Attaches to every [data-cap="publish-gate"] under root not attached yet. Hooks say what publish
434// and unpublish do; without them a publish button inside a form posts the form, and a first
435// publication is previewed first. Returns a function that detaches them all.
436export function enhance(root: ParentNode = document, hooks?: GateHooks): () => void {
437  const handles: GateHandle[] = [];
438  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='publish-gate']:not([data-cap-ready])")) {
439    el.setAttribute(READY, "");
440    handles.push(attachPublishGate(el, hooks));
441  }
442  return () => handles.forEach((hd) => hd.detach());
443}