components/flag-list/flag-list.react.tsx

Functions

Imports

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

Source

1import { useEffect, useId, useMemo, 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 { anchorStatus, appliable, applySuggestion, countFlags, groupFlags, revertSuggestion, summaryLine, type AnchorStatus, type Flag as FlagData, type FlagKind, type Resolution } from "./flag-list.ts";
8
9export type { AnchorStatus, Flag as FlagData, FlagKind, Resolution } from "./flag-list.ts";
10
11type FilterValue = "open" | "resolved" | "all";
12
13export interface FlagListProps {
14  // The list's heading: "Flags on this draft".
15  label: ReactNode;
16  flags: FlagData[];
17  // Called with the whole new list after a flag is resolved, dismissed, reopened or applied.
18  onFlagsChange?: (flags: FlagData[]) => void;
19  // The current text the anchors are read against, and how to write it back. Without `text`
20  // the flags' own `anchor.lost` marks are believed and Apply is not offered.
21  text?: string;
22  onTextChange?: (text: string) => void;
23  // The owner may apply suggestions; nobody else is offered the button.
24  owner?: boolean;
25  ownerName?: string;
26  // Who is resolving: written on the flag.
27  viewer?: string;
28  // Where results are said, with Undo. Pass useMessage().say and .fail; without them the
29  // plain behaviour module's region (an element with data-cap="message") is used.
30  say?: (text: string, opts?: SayOptions) => void;
31  fail?: (text: string) => void;
32  filter?: FilterValue;
33  // Make j and k work before focus is inside the list.
34  primary?: boolean;
35}
36
37const WORDS: Record<Resolution, string> = { resolved: "Resolved", dismissed: "Dismissed", applied: "Applied" };
38
39export interface FlagProps {
40  flag: FlagData;
41  anchor: AnchorStatus;
42  owner: boolean;
43  ownerName?: string;
44  // The row's id prefix, so ids are unique when several lists are on a page.
45  idPrefix: string;
46  onResolve: () => void;
47  onDismiss: () => void;
48  onReopen: () => void;
49  onApply: () => void;
50  // A router's link component for the passage link; a plain <a> by default.
51  now?: number;
52}
53
54// One flag as a row of the row list. Renders exactly the contract on the doc page.
55export function Flag({ flag, anchor, owner, ownerName, idPrefix, onResolve, onDismiss, onReopen, onApply, now }: FlagProps) {
56  const id = `${idPrefix}-${flag.id}`;
57  const open = flag.state === "open";
58  const r: Resolution = flag.resolution ?? "resolved";
59  const a = flag.anchor;
60  const crit = flag.kind === "blocking";
61  const sug = flag.suggestion;
62  const applied = !open && r === "applied";
63  const attrs: Record<string, string | undefined> = {
64    "data-flag": flag.id,
65    "data-kind": flag.kind,
66    "data-state": flag.state,
67    "data-anchor": a ? anchor : "none",
68    "data-anchor-id": a?.id,
69    "data-resolution": open ? undefined : r,
70    "data-resolved-by": open ? undefined : flag.resolvedBy,
71    "data-resolved-at": open ? undefined : flag.resolvedAt,
72    "data-tone": crit && open ? "crit" : undefined,
73  };
74  const message = <span className="cap-flag-message">{flag.message}</span>;
75  return (
76    <li className="cap-row cap-flag" id={id} {...attrs}>
77      <span className="cap-row-status" id={`${id}-s`}>
78        <span className="cap-status" data-tone={crit ? "crit" : "warn"}>
79          <Glyph name={crit ? "crit" : "warn"} />
80          {crit ? "Blocking" : "Advisory"}
81        </span>
82      </span>
83      <div className="cap-row-title">
84        {a && anchor === "found" ? (
85          <a href={`#${a.id}`} aria-describedby={`${id}-s ${id}-d`}>
86            {message}
87            {" "}
88            <span className="cap-flag-goto">{a.label ?? "Go to passage"}</span>
89          </a>
90        ) : (
91          <span className="cap-flag-title">
92            {message}
93            {a ? (
94              <>
95                {" "}
96                <span className="cap-status" data-tone="nodata">
97                  <Glyph name="nodata" />
98                  Anchor lost
99                </span>
100              </>
101            ) : null}
102          </span>
103        )}
104      </div>
105      <p className="cap-row-detail" id={`${id}-d`}>
106        {flag.raisedBy ? `${flag.raisedBy}. ` : ""}Cause: <span data-cap-part="cause">{flag.cause}</span>
107      </p>
108      <span className="cap-row-meta">
109        {open ? null : (
110          <span className="cap-status" data-tone={r === "dismissed" ? "nodata" : "ok"}>
111            <Glyph name={r === "dismissed" ? "nodata" : "ok"} />
112            {WORDS[r]}
113          </span>
114        )}
115      </span>
116      <div className="cap-row-actions">
117        {open ? (
118          <>
119            <button type="button" className="cap-btn" data-size="sm" data-cap-part="resolve" onClick={onResolve}>
120              Resolve<span className="cap-sr-only"> flag: {flag.message}</span>
121            </button>
122            <button type="button" className="cap-btn" data-size="sm" data-variant="quiet" data-cap-part="dismiss" onClick={onDismiss}>
123              Dismiss<span className="cap-sr-only"> flag: {flag.message}</span>
124            </button>
125          </>
126        ) : (
127          <button type="button" className="cap-btn" data-size="sm" data-cap-part="reopen" onClick={onReopen}>
128            Reopen<span className="cap-sr-only"> flag: {flag.message}</span>
129          </button>
130        )}
131      </div>
132      <div className="cap-flag-body">
133        {a ? (
134          <blockquote className="cap-flag-quote">
135            <p className="cap-flag-anchor-note" data-cap-part="anchor-note" hidden={anchor === "none"}>
136              {anchor === "lost" ? "The text this flag was raised on changed or was removed. Last known text:" : "Raised on this passage:"}
137            </p>
138            <p>
139              <span className="cap-sr-only">Quoted passage: </span>
140              <q className="cap-flag-quote-text">{a.quote}</q>
141            </p>
142          </blockquote>
143        ) : null}
144        {sug && a ? (
145          <div className="cap-flag-suggestion" data-state={applied ? "applied" : "inert"}>
146            <p className="cap-flag-suggestion-head">Suggested by {sug.by ?? "a reviewer"}</p>
147            <div className="cap-flag-diff">
148              <del>
149                <span className="cap-flag-mark" aria-hidden="true">
150                  &minus;
151                </span>
152                <span className="cap-sr-only">Before: </span>
153                {a.quote}
154              </del>
155              <ins>
156                <span className="cap-flag-mark" aria-hidden="true">
157                  +
158                </span>
159                <span className="cap-sr-only">After: </span>
160                <span className="cap-flag-after-text">{sug.replacement}</span>
161              </ins>
162            </div>
163            <div className="cap-flag-suggestion-foot" data-cap-part="suggestion-foot">
164              {applied ? (
165                <p className="cap-flag-note">Applied to the draft.</p>
166              ) : !open ? (
167                <p className="cap-flag-note">Not applied. Reopen the flag to apply it.</p>
168              ) : anchor !== "found" ? (
169                <p className="cap-flag-note">Cannot be applied: the passage it replaces has changed or gone.</p>
170              ) : owner ? (
171                <>
172                  <button type="button" className="cap-btn" data-size="sm" data-variant="primary" data-cap-part="apply" onClick={onApply}>
173                    Apply<span className="cap-sr-only"> suggestion: {flag.message}</span>
174                  </button>
175                  <span className="cap-flag-note">Nothing changes in the draft until you apply it.</span>
176                </>
177              ) : (
178                <p className="cap-flag-note">Only the owner{ownerName ? `, ${ownerName},` : ""} can apply this. The draft stays as it is until they do.</p>
179              )}
180            </div>
181          </div>
182        ) : null}
183        {!open ? (
184          <p className="cap-flag-resolution">
185            {WORDS[r]}
186            {flag.resolvedBy ? ` by ${flag.resolvedBy}` : ""}
187            {flag.resolvedAt ? (
188              <>
189                {" "}
190                <Time at={flag.resolvedAt} now={now} />
191              </>
192            ) : null}
193            .
194          </p>
195        ) : null}
196      </div>
197    </li>
198  );
199}
200
201export function FlagList({ label, flags: given, onFlagsChange, text, onTextChange, owner = false, ownerName, viewer, say = plainSay, fail = plainFail, filter: initial = "open", primary = false }: FlagListProps) {
202  const uid = useId();
203  const [flags, setFlags] = useState(given);
204  useEffect(() => setFlags(given), [given]);
205  const [filter, setFilter] = useState<FilterValue>(initial);
206  const live = useRef<HTMLDivElement>(null);
207  const root = useRef<HTMLElement>(null);
208  const rows = useRef<HTMLUListElement>(null);
209  // j and k, as the row list wires them.
210  useEffect(() => (rows.current ? attachRowList(rows.current) : undefined), []);
211
212  const counts = countFlags(flags);
213  const groups = useMemo(() => groupFlags(flags), [flags]);
214  // A closed flag is a record: it keeps what it said when it was closed.
215  const status = (f: FlagData) => anchorStatus(f, f.state === "resolved" ? undefined : text);
216  const waiting = appliable(flags, text);
217  const batchApplicable = owner && text !== undefined && onTextChange !== undefined;
218
219  const announce = (words: string, opts?: SayOptions) => {
220    if (document.querySelector("[data-cap='message']")) say(words, opts);
221    else if (live.current) {
222      live.current.textContent = "";
223      requestAnimationFrame(() => {
224        if (live.current) live.current.textContent = words;
225      });
226    }
227  };
228  const problem = (words: string) => (document.querySelector("[data-cap='message']") ? fail(words) : announce(words));
229
230  const commit = (next: FlagData[]) => {
231    setFlags(next);
232    onFlagsChange?.(next);
233  };
234  const patch = (list: FlagData[], id: string, to: Partial<FlagData>): FlagData[] => list.map((f) => (f.id === id ? { ...f, ...to } : f));
235  const close = (f: FlagData, resolution: Resolution): Partial<FlagData> => ({ state: "resolved", resolution, resolvedBy: viewer, resolvedAt: new Date().toISOString() });
236  const reopened: Partial<FlagData> = { state: "open", resolution: undefined, resolvedBy: undefined, resolvedAt: undefined };
237
238  // The list as it will be, held in a ref, so an Undo that runs later acts on the current one.
239  const latest = useRef(flags);
240  latest.current = flags;
241  const set = (next: FlagData[]) => {
242    latest.current = next;
243    commit(next);
244  };
245
246  const focusFlag = (id: string) => () => root.current?.querySelector<HTMLElement>(`[data-flag='${CSS.escape(id)}'] .cap-row-actions button`) ?? null;
247
248  const change = (f: FlagData, to: Partial<FlagData>, said: string, undone: string) => {
249    const before = f;
250    set(patch(latest.current, f.id, to));
251    announce(said, { undo: () => set(patch(latest.current, f.id, { state: before.state, resolution: before.resolution, resolvedBy: before.resolvedBy, resolvedAt: before.resolvedAt })), undone, returnFocus: focusFlag(f.id) });
252  };
253
254  const applyOne = (f: FlagData) => {
255    if (!batchApplicable || text === undefined) return;
256    const next = applySuggestion(text, f);
257    if (next === null) return problem("Could not apply the suggestion: the passage it replaces has changed.");
258    onTextChange?.(next);
259    const current = next;
260    const before = f;
261    set(patch(latest.current, f.id, close(f, "applied")));
262    announce("Suggestion applied to the draft.", {
263      undo: () => {
264        const back = revertSuggestion(current, f);
265        if (back === null) throw new Error("The draft has changed around that passage since. Undo the edit in the editor instead.");
266        onTextChange?.(back);
267        set(patch(latest.current, f.id, { state: before.state, resolution: before.resolution, resolvedBy: before.resolvedBy, resolvedAt: before.resolvedAt }));
268      },
269      undone: "Suggestion taken back. The passage is as it was.",
270      returnFocus: focusFlag(f.id),
271    });
272  };
273
274  const applyAll = async () => {
275    if (!batchApplicable || text === undefined) return;
276    const todo = appliable(latest.current, text);
277    if (todo.length === 0) return;
278    const quoted = (s: string) => `“${s}”`;
279    const n = todo.length;
280    await confirm({
281      title: `Apply ${n} suggestion${n === 1 ? "" : "s"}?`,
282      lead: "This rewrites the draft. Each replacement is listed; nothing else changes.",
283      body: todo.map((f) => `${quoted(f.anchor?.quote ?? "")} becomes ${quoted(f.suggestion?.replacement ?? "")}`),
284      action: `Apply ${n} suggestion${n === 1 ? "" : "s"}`,
285      perform: async () => {
286        let next = text;
287        const done: FlagData[] = [];
288        for (const f of todo) {
289          const out = applySuggestion(next, f);
290          if (out !== null) {
291            next = out;
292            done.push(f);
293          }
294        }
295        if (done.length === 0) throw new Error("None of the passages could be found any more.");
296        onTextChange?.(next);
297        let list = latest.current;
298        for (const f of done) list = patch(list, f.id, close(f, "applied"));
299        set(list);
300        const skipped = todo.length - done.length;
301        announce(`Applied ${done.length} suggestion${done.length === 1 ? "" : "s"} to the draft.${skipped ? ` ${skipped} skipped: the passage changed.` : ""}`, {
302          undo: () => {
303            let back = next;
304            for (const f of [...done].reverse()) {
305              const out = revertSuggestion(back, f);
306              if (out === null) throw new Error("The draft has changed around those passages since. Undo the edits in the editor instead.");
307              back = out;
308            }
309            onTextChange?.(back);
310            let again = latest.current;
311            for (const f of done) again = patch(again, f.id, reopened);
312            set(again);
313          },
314          undone: "Suggestions taken back. The passages are as they were.",
315        });
316      },
317    });
318  };
319
320  const group = (kind: FlagKind, name: string, list: FlagData[]) => {
321    if (list.length === 0) return null;
322    const open = list.filter((f) => f.state === "open").length;
323    const hid = `${uid}-g-${kind}`;
324    return (
325      <li className="cap-flag-group" data-group={kind} key={kind}>
326        <div className="cap-flag-group-head">
327          <h3 className="cap-flag-group-title" id={hid}>
328            {name}
329          </h3>
330          <span className="cap-flag-group-count">
331            {open} open, {list.length - open} resolved
332          </span>
333        </div>
334        <ul className="cap-flag-group-rows" role="list" aria-labelledby={hid}>
335          {list.map((f) => (
336            <Flag
337              key={f.id}
338              flag={f}
339              anchor={status(f)}
340              owner={batchApplicable}
341              ownerName={ownerName}
342              idPrefix={uid}
343              onResolve={() => change(f, close(f, "resolved"), "Flag resolved.", "Flag reopened.")}
344              onDismiss={() => change(f, close(f, "dismissed"), "Flag dismissed.", "Flag reopened.")}
345              onReopen={() => change(f, reopened, "Flag reopened.", "Flag closed again.")}
346              onApply={() => applyOne(f)}
347            />
348          ))}
349        </ul>
350      </li>
351    );
352  };
353
354  const headingId = `${uid}-h`;
355  const radio = (v: FilterValue, word: string, n: number) => (
356    <label>
357      <input type="radio" name={`${uid}-filter`} value={v} checked={filter === v} onChange={() => setFilter(v)} /> {word}
358      <span className="cap-flags-count" data-count={v}>
359        {n}
360      </span>
361    </label>
362  );
363  const n = waiting.length;
364  return (
365    <section ref={root} className="cap-flags" aria-labelledby={headingId} data-owner={owner ? "" : undefined} data-owner-name={ownerName} data-viewer={viewer}>
366      <header className="cap-flags-head">
367        <h2 className="cap-flags-title" id={headingId}>
368          {label}
369        </h2>
370        <p className="cap-flags-summary" data-cap-part="summary">
371          {summaryLine(counts)}
372        </p>
373        <fieldset className="cap-seg cap-flags-filter" data-cap-part="filter">
374          <legend className="cap-sr-only">Show</legend>
375          <div className="cap-seg-options" data-size="sm">
376            {radio("open", "Open", counts.open)}
377            {radio("resolved", "Resolved", counts.resolved)}
378            {radio("all", "All", counts.total)}
379          </div>
380        </fieldset>
381        <div className="cap-flags-batch">
382          <button type="button" className="cap-btn" data-variant="primary" data-cap-part="apply-all" hidden={!batchApplicable || n === 0} onClick={() => void applyAll()}>
383            Apply {n} suggestion{n === 1 ? "" : "s"}
384          </button>
385          <p className="cap-flags-note" data-cap-part="owner-note" hidden={owner || n === 0}>
386            {n} suggestion{n === 1 ? " is" : "s are"} waiting for the owner{ownerName ? `, ${ownerName}` : ""}. Only they can apply them.
387          </p>
388        </div>
389      </header>
390      <ul ref={rows} className="cap-rows cap-flags-list" data-cap="row-list" role="list" aria-labelledby={headingId} data-cap-primary={primary ? "" : undefined}>
391        {group("blocking", "Blocking", groups.blocking)}
392        {group("advisory", "Advisory", groups.advisory)}
393        <li className="cap-flags-empty" data-for="open">
394          No open flags.
395        </li>
396        <li className="cap-flags-empty" data-for="resolved">
397          Nothing resolved yet.
398        </li>
399        <li className="cap-flags-empty" data-for="all">
400          No flags on this draft.
401        </li>
402      </ul>
403      <div className="cap-sr-only" role="status" ref={live} />
404    </section>
405  );
406}