components/history-list/history-list.react.tsx

Functions

Imports

It imports components/avatar/avatar.ts, components/history-list/history-list.ts, components/message/message.react.tsx, components/message/message.ts, components/time/time.react.tsx, components/time/time.ts. Imported by components/history-list/examples.tsx.

Source

1import { useEffect, useId, useMemo, useRef, useState, type ReactNode } from "react";
2import { GLYPHS } from "../message/message.ts";
3import { useMessage } from "../message/message.react.tsx";
4import { Time } from "../time/time.react.tsx";
5import { initials } from "../avatar/avatar.ts";
6import { parse } from "../time/time.ts";
7import {
8  PICK_BLOCKED,
9  attachListKeys,
10  SIGN_GLYPH,
11  compareHref,
12  condense,
13  deltaOf,
14  deltaSign,
15  deltaText,
16  destinationGlyph,
17  destinationTone,
18  destinationWord,
19  orderPair,
20  pickTwo,
21  pickedText,
22  rangeText,
23  restoredEntry,
24  restoredMessage,
25  runTitle,
26  stamp,
27  type HistoryEntry,
28  type Run,
29} from "./history-list.ts";
30
31export type { HistoryEntry, Destination, HistoryKind } from "./history-list.ts";
32
33export interface RestoreEvent {
34  // The line restored from, and the new line a restore adds on top.
35  source: HistoryEntry;
36  entry: HistoryEntry;
37}
38
39export interface HistoryListProps {
40  // Newest first. The first is the current version.
41  entries: HistoryEntry[];
42  // The list's name: the heading id that names it (preferred), or a label.
43  labelledBy?: string;
44  label?: string;
45  // Who is restoring: the new line is theirs.
46  user: string;
47  // The compare view's path; `?from=<older>&to=<newer>` is added.
48  compareBase?: string;
49  // Where a line's title goes (the version's own page).
50  versionHref?: (id: string) => string;
51  // Load-into-editor mode: an earlier line's action is a "Load into editor" link to this
52  // address (works without script) in place of Restore. Nothing is added to the history; the
53  // app's save makes the version. `onLoad` loads the text in place and stops the navigation.
54  loadHref?: (id: string) => string;
55  onLoad?: (entry: HistoryEntry) => void;
56  // A read-only history: an earlier line has no action, neither Restore nor Load. Entries may
57  // leave out `words`; such a line shows no size change.
58  readOnly?: boolean;
59  // Restoring adds a new line on top: add `entry` to `entries` (and save it). The message with
60  // Undo is said by the list.
61  onRestore?: (e: RestoreEvent) => void | Promise<void>;
62  // Undo of that restore: remove `entry` again.
63  onUndoRestore?: (e: RestoreEvent) => void | Promise<void>;
64  // A fixed "now" for a report or a test.
65  now?: number;
66  // More lines exist before the last: an address (a link that works without script) and/or a
67  // handler (the app fetches the page and adds it to `entries`).
68  olderHref?: string;
69  onLoadOlder?: () => void;
70  loadingOlder?: boolean;
71  // The page's main list: j and k work on it before focus is inside it.
72  primary?: boolean;
73  // Shown in place of the list when there are no versions.
74  empty?: ReactNode;
75}
76
77const Glyph = ({ d, size = 14 }: { d: string; size?: number }) => <svg viewBox="0 0 16 16" width={size} height={size} aria-hidden="true" focusable="false" dangerouslySetInnerHTML={{ __html: d }} />;
78
79function Status({ tone, glyph, word }: { tone: string; glyph: string; word: string }) {
80  return (
81    <span className="cap-status" data-tone={tone}>
82      <Glyph d={glyph} />
83      {word}
84    </span>
85  );
86}
87
88function Who({ id, name, ai }: { id: string; name: string; ai?: boolean }) {
89  return (
90    <span className="cap-hist-who" id={id}>
91      <span className="cap-avatar" data-size="sm" data-kind={ai ? "ai" : undefined} aria-hidden="true">
92        <span className="cap-avatar-fallback">{ai ? "AI" : initials(name.split(" and ")[0] ?? name)}</span>
93      </span>
94      <span className="cap-hist-name">{name}</span>
95    </span>
96  );
97}
98
99function Delta({ id, n }: { id: string; n: number | undefined }) {
100  if (n === undefined) return <span className="cap-hist-delta" data-sign="none" aria-hidden="true" />;
101  const sign = deltaSign(n);
102  return (
103    <span className="cap-hist-delta" id={id} data-sign={sign}>
104      <Glyph d={SIGN_GLYPH[sign]} size={12} />
105      <span>{deltaText(n)}</span>
106    </span>
107  );
108}
109
110function When({ id, iso, now, chevron }: { id: string; iso: string; now?: number; chevron?: boolean }) {
111  return (
112    <span className="cap-row-meta" id={id}>
113      <span className="cap-hist-when">
114        <Time at={iso} now={now} />
115        <time className="cap-hist-exact" dateTime={iso}>
116          {stamp(iso, now)}
117        </time>
118      </span>
119      {chevron ? <span className="cap-row-chevron" aria-hidden="true" /> : null}
120    </span>
121  );
122}
123
124interface LineProps {
125  entry: HistoryEntry;
126  delta: number | undefined;
127  prefix: string;
128  current: boolean;
129  picked: boolean;
130  pickDisabled: boolean;
131  now?: number;
132  href: (id: string) => string;
133  onPick: (id: string, el: HTMLInputElement) => void;
134  onRestore: (e: HistoryEntry, opener: HTMLElement) => void;
135  loadHref?: (id: string) => string;
136  onLoad?: (e: HistoryEntry) => void;
137  readOnly?: boolean;
138}
139
140function Line({ entry: e, delta, prefix, current, picked, pickDisabled, now, href, onPick, onRestore, loadHref, onLoad, readOnly }: LineProps) {
141  const p = `${prefix}-${e.id}`;
142  const stampText = stamp(e.at, now);
143  const hasDetail = e.kind !== "edit";
144  const described = [hasDetail ? `${p}-d` : "", delta === undefined ? "" : `${p}-w`, `${p}-t`].filter(Boolean).join(" ");
145  return (
146    <li className="cap-row cap-hist-row" data-kind={e.kind} data-id={e.id} data-at={e.at} data-words={e.words} data-who={e.who} data-current={current ? "" : undefined}>
147      <span className="cap-hist-pick">
148        <label className="cap-check">
149          <input type="checkbox" name="compare" value={e.id} data-cap-part="pick" checked={picked} aria-disabled={pickDisabled ? "true" : undefined} onChange={(ev) => onPick(e.id, ev.currentTarget)} onClick={(ev) => pickDisabled && ev.preventDefault()} />
150          <span className="cap-sr-only">
151            Compare this version, {stampText}, by {e.who}
152          </span>
153        </label>
154      </span>
155      <Who id={`${p}-who`} name={e.who} ai={e.ai} />
156      <div className="cap-row-title">
157        <a href={href(e.id)} aria-describedby={described} title={e.summary}>
158          {e.summary}
159        </a>
160      </div>
161      {e.kind === "named" ? (
162        <p className="cap-row-detail" id={`${p}-d`}>
163          Named version: <b>{e.name}</b>
164        </p>
165      ) : e.kind === "publish" ? (
166        <p className="cap-row-detail" id={`${p}-d`}>
167          Published to{" "}
168          {(e.destinations ?? []).map((d) => (
169            <span key={d.name} className="cap-hist-dest">
170              <Status tone={destinationTone(d.status)} glyph={destinationGlyph(d.status)} word={destinationWord(d.status)} /> {d.name}{" "}
171            </span>
172          ))}
173        </p>
174      ) : e.kind === "restore" && e.restoredFrom ? (
175        <p className="cap-row-detail" id={`${p}-d`}>
176          Restored from {stamp(e.restoredFrom.at, now)}
177        </p>
178      ) : e.kind === "autosave" ? (
179        <p className="cap-row-detail" id={`${p}-d`}>
180          Autosave
181        </p>
182      ) : null}
183      <Delta id={`${p}-w`} n={delta} />
184      <When id={`${p}-t`} iso={e.at} now={now} />
185      <div className="cap-row-actions">
186        {current ? (
187          <Status tone="ok" glyph={GLYPHS.ok} word="Current" />
188        ) : readOnly ? null : loadHref ? (
189          <a
190            className="cap-btn"
191            data-variant="quiet"
192            data-size="sm"
193            data-cap-part="load"
194            data-version={e.id}
195            href={loadHref(e.id)}
196            onClick={onLoad ? (ev) => (ev.preventDefault(), onLoad(e)) : undefined}
197          >
198            Load into editor<span className="cap-sr-only"> the version from {stampText} by {e.who}</span>
199          </a>
200        ) : (
201          <button type="button" className="cap-btn" data-variant="quiet" data-size="sm" data-cap-part="restore" data-version={e.id} onClick={(ev) => onRestore(e, ev.currentTarget)}>
202            Restore<span className="cap-sr-only"> the version from {stampText} by {e.who}</span>
203          </button>
204        )}
205      </div>
206    </li>
207  );
208}
209
210function RunLines({ run, deltas, prefix, now, open, onToggle, children }: { run: Run; deltas: (number | undefined)[]; prefix: string; now?: number; open: boolean; onToggle: () => void; children: ReactNode }) {
211  const first = run.entries[0] as HistoryEntry;
212  const p = `${prefix}-run-${first.id}`;
213  const title = runTitle(run);
214  const names = run.who.length > 1 ? `${run.who[0]} and ${run.who.length - 1} more` : (run.who[0] ?? "");
215  void deltas;
216  return (
217    <>
218      <li className="cap-row cap-hist-row" data-kind="run">
219        <span className="cap-hist-pick" />
220        <Who id={`${p}-who`} name={names} />
221        <div className="cap-row-title">
222          <button type="button" aria-expanded={open} aria-controls={`${p}-rows`} aria-describedby={`${p}-d ${p}-w ${p}-t`} onClick={onToggle}>
223            {title}
224          </button>
225        </div>
226        <p className="cap-row-detail" id={`${p}-d`}>
227          {rangeText(run.from, run.to, now)}
228        </p>
229        <Delta id={`${p}-w`} n={run.delta} />
230        <When id={`${p}-t`} iso={run.to} now={now} chevron />
231        <div className="cap-row-actions" />
232      </li>
233      <li className="cap-hist-region" id={`${p}-rows`} hidden={!open}>
234        <ul role="list" aria-label={title}>
235          {children}
236        </ul>
237      </li>
238    </>
239  );
240}
241
242export function HistoryList({ entries, labelledBy, label, user, compareBase = "", versionHref, loadHref, onLoad, readOnly, onRestore, onUndoRestore, now, olderHref, onLoadOlder, loadingOlder, primary, empty }: HistoryListProps) {
243  const prefix = useId();
244  const listRef = useRef<HTMLUListElement>(null);
245  const [picked, setPicked] = useState<string[]>([]);
246  const [note, setNote] = useState<string | null>(null);
247  const [open, setOpen] = useState<Record<string, boolean>>({});
248  const { say } = useMessage();
249  useEffect(() => (listRef.current ? attachListKeys(listRef.current) : undefined), [entries.length === 0]);
250  // A pick that is no longer in the list (an Undo removed it) is dropped.
251  useEffect(() => setPicked((p) => p.filter((id) => entries.some((e) => e.id === id))), [entries]);
252
253  const lines = useMemo(() => condense(entries), [entries]);
254  const at = (id: string) => parse(entries.find((e) => e.id === id)?.at ?? "");
255  const pair = orderPair(picked, at);
256  const text = note ?? (pair ? pickedText(2, stamp(entries.find((e) => e.id === pair[0])?.at ?? "", now), stamp(entries.find((e) => e.id === pair[1])?.at ?? "", now)) : pickedText(picked.length));
257  const href = versionHref ?? ((id: string) => `?version=${encodeURIComponent(id)}`);
258
259  const pick = (id: string) => {
260    const next = pickTwo(picked, id);
261    setNote(next.blocked ? PICK_BLOCKED : null);
262    if (!next.blocked) setPicked(next.picked);
263  };
264
265  const restore = async (source: HistoryEntry, opener: HTMLElement) => {
266    const current = entries[0];
267    if (!current) return;
268    const at = new Date(now ?? Date.now()).toISOString();
269    const entry = restoredEntry(source, current, user, `${source.id}-restored-${entries.filter((e) => e.kind === "restore").length + 1}`, at, now);
270    const event = { source, entry };
271    await onRestore?.(event);
272    say(restoredMessage(source, now), {
273      undo: async () => {
274        await onUndoRestore?.(event);
275      },
276      undone: "The restored copy was removed. The earlier version is current again.",
277      returnFocus: () => (opener.isConnected ? opener : null),
278    });
279  };
280
281  if (entries.length === 0) return <div className="cap-hist">{empty}</div>;
282
283  let index = 0;
284  return (
285    <section className="cap-hist" aria-labelledby={labelledBy} aria-label={labelledBy ? undefined : label} data-picked={picked.length} data-readonly={readOnly ? "" : undefined}>
286      <div className="cap-hist-bar">
287        <p className="cap-hist-picked" role="status" data-cap-part="picked">
288          {text}
289        </p>
290        {pair ? (
291          <a className="cap-btn" data-variant="primary" data-cap-part="compare" href={compareHref(compareBase, pair[0], pair[1])}>
292            Compare 2 versions
293          </a>
294        ) : (
295          <a className="cap-btn" data-variant="primary" data-cap-part="compare" role="link" aria-disabled="true" tabIndex={0}>
296            Compare 2 versions
297          </a>
298        )}
299      </div>
300      <ul ref={listRef} className="cap-rows cap-hist-list" role="list" aria-labelledby={labelledBy} aria-label={labelledBy ? undefined : label} data-cap-primary={primary ? "" : undefined}>
301        {lines.map((line) => {
302          const common = (e: HistoryEntry, i: number) => (
303            <Line key={e.id} entry={e} delta={deltaOf(entries, i)} prefix={prefix} current={i === 0} picked={picked.includes(e.id)} pickDisabled={picked.length >= 2 && !picked.includes(e.id)} now={now} href={href} onPick={pick} onRestore={(en, el) => void restore(en, el)} loadHref={loadHref} onLoad={onLoad} readOnly={readOnly} />
304          );
305          if (line.type === "entry") {
306            const node = common(line.entry, index);
307            index += 1;
308            return node;
309          }
310          const start = index;
311          index += line.entries.length;
312          const id = `${prefix}-run-${(line.entries[0] as HistoryEntry).id}`;
313          const isOpen = open[id] === true;
314          return (
315            <RunLines
316              key={id}
317              run={line}
318              deltas={line.entries.map((_e, k) => deltaOf(entries, start + k))}
319              prefix={prefix}
320              now={now}
321              open={isOpen}
322              onToggle={() => setOpen((o) => ({ ...o, [id]: !isOpen }))}
323            >
324              {line.entries.map((e, k) => common(e, start + k))}
325            </RunLines>
326          );
327        })}
328      </ul>
329      {olderHref || onLoadOlder ? (
330        <div className="cap-hist-foot">
331          {olderHref ? (
332            <a className="cap-btn" data-variant="quiet" data-cap-part="older" href={olderHref} aria-busy={loadingOlder || undefined} onClick={onLoadOlder ? (e) => (e.preventDefault(), onLoadOlder()) : undefined}>
333              Load older versions
334            </a>
335          ) : (
336            <button type="button" className="cap-btn" data-variant="quiet" data-cap-part="older" aria-busy={loadingOlder || undefined} onClick={onLoadOlder}>
337              Load older versions
338            </button>
339          )}
340        </div>
341      ) : null}
342    </section>
343  );
344}