components/publish-gate/publish-gate.react.tsx

Functions

Imports

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

Source

1import { useEffect, useId, useRef, useState, type ReactNode } from "react";
2import { confirm } from "../confirm-dialog/confirm-dialog.ts";
3import { fail as plainFail, say as plainSay, type SayOptions } from "../message/message.ts";
4import { attachRowList } from "../row-list/row-list.ts";
5import { Glyph } from "../status/status.react.tsx";
6import { Time } from "../time/time.react.tsx";
7import { FIRST_PUBLICATION_NOTE, appliesTo, checkState, countChecks, advisoryHeading, describeGate, holdText, passedHeading, requiredHeading, siteDetail, siteState, stateWord, type GateCheck, type GateSite, type GateState } from "./publish-gate.ts";
8
9export type { GateCheck, GateHold, GatePublished, GateSite, GateState } from "./publish-gate.ts";
10
11const TONE: Record<GateState, "crit" | "info" | "ok"> = { blocked: "crit", held: "info", ready: "ok", published: "ok" };
12
13function StateStatus({ state }: { state: GateState }) {
14  return (
15    <span className="cap-status" data-tone={TONE[state]}>
16      <Glyph name={TONE[state]} />
17      {stateWord(state)}
18    </span>
19  );
20}
21
22export interface PublishButtonProps {
23  // The gate this belongs to (its id) and the destination.
24  gateId: string;
25  site: GateSite;
26  state: GateState;
27  busy?: boolean;
28  // The id of the gate's summary, which describes a button that is not ready.
29  summaryId: string;
30  // Name the destination in the buttons' accessible names (several destinations).
31  named?: boolean;
32  // "sm" in a row; "default" for the page's own publish control.
33  size?: "sm" | "default";
34  onPublish: () => void;
35  onUnpublish: () => void;
36}
37
38// The paired publish control for one destination: Publish, Publishing..., Publish blocked,
39// Publish held, or, once published, View and Unpublish.
40export function PublishButton({ gateId, site, state, busy = false, summaryId, named = false, size = "sm", onPublish, onUnpublish }: PublishButtonProps) {
41  const suffix = named ? `, ${site.name}` : undefined;
42  const sz = size === "sm" ? "sm" : undefined;
43  if (state === "published" && site.published) {
44    return (
45      <div data-cap-actions="" data-gate={gateId} data-site={site.id} data-site-label={named ? site.name : undefined} data-btn-size={size === "default" ? "default" : undefined}>
46        <a className="cap-btn" data-cap-part="view" data-size={sz} aria-label={suffix ? `View live page${suffix}` : undefined} href={site.published.url}>
47          View
48        </a>
49        <button type="button" className="cap-btn" data-cap-part="unpublish" data-size={sz} data-variant="quiet" data-site={site.id} aria-label={suffix ? `Unpublish${suffix}` : undefined} onClick={onUnpublish}>
50          Unpublish
51        </button>
52      </div>
53    );
54  }
55  const ready = state === "ready" && !busy;
56  const label = busy ? "Publishing..." : state === "blocked" ? "Publish blocked" : state === "held" ? "Publish held" : "Publish";
57  return (
58    <div data-cap-actions="" data-gate={gateId} data-site={site.id} data-site-label={named ? site.name : undefined} data-btn-size={size === "default" ? "default" : undefined}>
59      <button
60        type="submit"
61        name="intent"
62        value="publish"
63        className="cap-btn"
64        data-cap-part="publish"
65        data-size={sz}
66        data-site={site.id}
67        data-variant={ready || busy ? "primary" : "secondary"}
68        aria-disabled={ready ? undefined : true}
69        aria-busy={busy ? true : undefined}
70        aria-describedby={ready ? undefined : summaryId}
71        aria-label={suffix ? `${label}${suffix}` : undefined}
72        onClick={(e) => {
73          // A blocked or held button stays focusable so its reason is heard; pressing it does nothing.
74          if (!ready) return e.preventDefault();
75          e.preventDefault();
76          onPublish();
77        }}
78      >
79        {label}
80      </button>
81    </div>
82  );
83}
84
85// A first publication is one-way, so it is previewed in the shared confirm dialog, the destination
86// listed and focus on Cancel; anything already public is published at once. For a page that
87// places its own <PublishButton>.
88export async function publishWithPreview(site: GateSite, perform: () => Promise<void>): Promise<void> {
89  if (!site.first) return perform();
90  await confirm({
91    title: `Publish to ${site.name}?`,
92    lead: "Publishing for the first time cannot be taken back quietly: it goes public at once.",
93    body: [`${site.name}: ${FIRST_PUBLICATION_NOTE}`],
94    action: `Publish to ${site.name}`,
95    perform,
96  });
97}
98
99export interface PublishGateProps {
100  label: ReactNode;
101  sites: GateSite[];
102  checks: GateCheck[];
103  // Publish to these destinations. Resolve when it is live; reject with an Error saying why not.
104  // The app then passes the destination as published.
105  publish?: (siteIds: string[]) => Promise<void>;
106  // Take it off the public site. Done at once, with Undo.
107  unpublish?: (siteIds: string[]) => Promise<void>;
108  // Where each destination's button is: in its row (default), or "none" when the page places
109  // <PublishButton> itself (the editor bar's own publish control).
110  actions?: "rows" | "none";
111  // Where results are said, with Undo: useMessage().say and .fail. Without them the plain behaviour
112  // module's region (an element with data-cap="message") is used.
113  say?: (text: string, opts?: SayOptions) => void;
114  fail?: (text: string) => void;
115  // Make j and k work before focus is inside the list.
116  primary?: boolean;
117  // The id used to pair a page-level <PublishButton> with this region. A made-up one by default.
118  id?: string;
119  // The summary's id; given so a PublishButton placed elsewhere can describe itself with it.
120  summaryId?: string;
121}
122
123// The gate as the doc page's markup describes it. Rendered from the checks and the destinations,
124// so the summary cannot say Ready while a required check fails.
125export function PublishGate({ label, sites, checks, publish, unpublish, actions = "rows", say = plainSay, fail = plainFail, primary = false, id, summaryId }: PublishGateProps) {
126  const own = useId();
127  const gateId = id ?? `${own}-gate`;
128  const sumId = summaryId ?? `${gateId}-sum`;
129  const [busy, setBusy] = useState<string[]>([]);
130  const rows = useRef<HTMLUListElement>(null);
131  useEffect(() => (rows.current ? attachRowList(rows.current) : undefined), []);
132
133  const reading = describeGate(sites, checks);
134  const counts = countChecks(checks);
135  const failingReq = checks.filter((c) => c.required && !c.ok);
136  const failingAdv = checks.filter((c) => !c.required && !c.ok);
137  const passed = checks.filter((c) => c.ok);
138
139  const announce = (text: string, opts?: SayOptions) => {
140    if (document.querySelector("[data-cap='message']")) say(text, opts);
141  };
142  const problem = (text: string) => {
143    if (document.querySelector("[data-cap='message']")) fail(text);
144  };
145
146  const run = async (site: GateSite) => {
147    setBusy((b) => [...b, site.id]);
148    try {
149      await publish?.([site.id]);
150    } catch (err) {
151      setBusy((b) => b.filter((x) => x !== site.id));
152      problem(`Could not publish to ${site.name}: ${err instanceof Error ? err.message : String(err)}`);
153      return;
154    }
155    setBusy((b) => b.filter((x) => x !== site.id));
156    announce(`Published to ${site.name}.`);
157  };
158
159  const onPublish = async (site: GateSite) => {
160    if (busy.includes(site.id)) return;
161    await publishWithPreview(site, () => run(site));
162  };
163
164  const onUnpublish = async (site: GateSite) => {
165    try {
166      await unpublish?.([site.id]);
167    } catch (err) {
168      return problem(`Could not unpublish from ${site.name}: ${err instanceof Error ? err.message : String(err)}`);
169    }
170    announce(`Unpublished from ${site.name}.`, {
171      undo: async () => {
172        await publish?.([site.id]);
173      },
174      undone: `Published to ${site.name} again.`,
175    });
176  };
177
178  const checkRow = (c: GateCheck) => {
179    const i = checks.indexOf(c);
180    const st = checkState(c);
181    const rid = `${gateId}-c-${c.id}`;
182    const words = c.ok ? (c.pass ?? `${c.name}: passing`) : c.cause;
183    const siteName = c.site ? sites.find((s) => s.id === c.site)?.name : undefined;
184    return (
185      <li
186        key={c.id}
187        className="cap-row cap-check"
188        id={rid}
189        data-check={c.id}
190        data-name={c.name}
191        data-required={c.required ? "" : undefined}
192        data-ok={String(c.ok)}
193        data-cause={c.cause}
194        data-pass={c.pass}
195        data-href={c.href}
196        data-fix={c.fix}
197        data-site={c.site}
198        data-order={String(i)}
199        data-tone={st === "failing" ? "crit" : undefined}
200      >
201        <span className="cap-row-status" id={`${rid}-s`}>
202          <span className="cap-status" data-tone={st === "failing" ? "crit" : st === "advisory" ? "warn" : "ok"}>
203            <Glyph name={st === "failing" ? "crit" : st === "advisory" ? "warn" : "ok"} />
204            {st === "failing" ? "Failing" : st === "advisory" ? "Advisory" : "Passed"}
205          </span>
206        </span>
207        <div className="cap-row-title">
208          {c.href ? (
209            <a href={c.href} aria-describedby={`${rid}-s ${rid}-d`}>
210              {words}
211            </a>
212          ) : (
213            <span className="cap-gate-title-text">{words}</span>
214          )}
215        </div>
216        <p className="cap-row-detail" id={`${rid}-d`}>
217          <span className="cap-check-name">{c.name}</span>
218          {!c.ok && c.fix ? (
219            <>
220              . <span className="cap-check-fix">Fix: {c.fix}</span>
221            </>
222          ) : null}
223        </p>
224        <span className="cap-row-meta">{siteName ? `on ${siteName}` : null}</span>
225      </li>
226    );
227  };
228
229  const section = (name: string, headId: string, heading: string, list: GateCheck[], shown: boolean) => (
230    <li className="cap-gate-section" data-section={name} hidden={!shown}>
231      <h3 className="cap-gate-group-title" id={headId}>
232        {heading}
233      </h3>
234      <ul className="cap-gate-section-rows" role="list" aria-labelledby={headId}>
235        {list.map(checkRow)}
236      </ul>
237    </li>
238  );
239
240  const headingId = `${gateId}-h`;
241  return (
242    <section className="cap-gate" id={gateId} data-state={reading.state} aria-labelledby={headingId}>
243      <header className="cap-gate-head">
244        <h2 className="cap-gate-title" id={headingId}>
245          {label}
246        </h2>
247        <p className="cap-gate-summary" id={sumId} role="status" aria-live="polite" aria-atomic="true" data-cap-part="summary">
248          <StateStatus state={reading.state} />
249          {reading.rest}
250        </p>
251      </header>
252      <ul ref={rows} className="cap-rows cap-gate-all" data-cap="row-list" role="list" aria-labelledby={headingId} data-cap-primary={primary ? "" : undefined}>
253        <li className="cap-gate-section" data-section="sites">
254          <h3 className="cap-gate-group-title" id={`${gateId}-g-sites`}>
255            {sites.length === 1 ? "Destination" : "Destinations"}
256          </h3>
257          <ul className="cap-gate-section-rows" role="list" aria-labelledby={`${gateId}-g-sites`}>
258            {reading.sites.map(({ site, state, failing }) => {
259              const adv = checks.filter((c) => appliesTo(c, site.id) && !c.required && !c.ok).length;
260              const sid = `${gateId}-s-${site.id}`;
261              return (
262                <li key={site.id} className="cap-row cap-gate-site" id={sid} data-site={site.id} data-name={site.name} data-state={state} data-first={site.first ? "" : undefined} data-hold-text={site.hold ? holdText(site.hold) : undefined} data-hold-note={site.hold?.note} data-published-at={site.published?.at} data-published-url={site.published?.url} data-tone={state === "blocked" ? "crit" : undefined}>
263                  <span className="cap-row-status" id={`${sid}-s`}>
264                    <StateStatus state={state} />
265                  </span>
266                  <div className="cap-row-title">
267                    <span className="cap-gate-site-name">{site.name}</span>
268                  </div>
269                  <p className="cap-row-detail" id={`${sid}-d`}>
270                    {siteDetail(state, failing, adv, site)}
271                  </p>
272                  <span className="cap-row-meta">{state === "published" && site.published ? <Time at={site.published.at} format="exact" /> : null}</span>
273                  {actions === "rows" ? <PublishButton gateId={gateId} site={site} state={state} busy={busy.includes(site.id)} summaryId={sumId} named={sites.length > 1} onPublish={() => void onPublish(site)} onUnpublish={() => void onUnpublish(site)} /> : null}
274                </li>
275              );
276            })}
277          </ul>
278        </li>
279        {section("required", `${gateId}-g-req`, requiredHeading(counts.requiredFailing), failingReq, failingReq.length > 0)}
280        {section("advisory", `${gateId}-g-adv`, advisoryHeading(counts.advisoryFailing), failingAdv, failingAdv.length > 0)}
281        <li className="cap-gate-section" data-section="passed" hidden={passed.length === 0}>
282          <details className="cap-disclosure">
283            <summary>{passedHeading(counts.passed)}</summary>
284            <div className="cap-disclosure-body">
285              <ul className="cap-gate-section-rows" role="list" aria-label="Passing checks">
286                {passed.map(checkRow)}
287              </ul>
288            </div>
289          </details>
290        </li>
291      </ul>
292      <p className="cap-gate-clear" data-cap-part="clear" hidden={failingReq.length + failingAdv.length > 0}>
293        No checks are failing.
294      </p>
295    </section>
296  );
297}
298
299// The overall and per-destination states, for a page that places its own <PublishButton>.
300export function gateStates(sites: GateSite[], checks: GateCheck[]): { overall: GateState; sites: Record<string, GateState> } {
301  const overall = describeGate(sites, checks).state;
302  return { overall, sites: Object.fromEntries(sites.map((s) => [s.id, siteState(s, checks)])) };
303}