components/history-list/history-list.ts

Functions

Imports

It imports components/disclosure/disclosure.ts, components/history-list/history-list-model.ts, components/history-list/history-list-rows.ts, components/message/message.ts, components/row-list/row-list.ts, components/time/time.ts. Imported by components/history-list/history-list.react.tsx.

Source

1// The history list's behaviour and its pure helpers. One line per change; autosaves fold
2// into one line that opens in place; any two lines can be picked to compare; restoring a
3// line makes a NEW version on top and offers Undo, so nothing is ever overwritten.
4//
5// The page is delivered with every line in the HTML. This module adds what only a person's
6// action creates: the picks, the restore, the group that opens, a page of older lines.
7// No framework; the React wrapper uses the same helpers.
8import { toggleGroup } from "../disclosure/disclosure.ts";
9import { GLYPHS, enhance as enhanceMessage, say } from "../message/message.ts";
10import { isTypingKey, listOwnsKeys, moveRowFocus, singleKeysOff } from "../row-list/row-list.ts";
11import { enhance as enhanceTime, parse } from "../time/time.ts";
12import { type HistoryEntry, type HistoryKind, PICK_BLOCKED, PICK_NONE, compareHref, condense, deltaOf, orderPair, pickedText, restoredEntry, restoredMessage, stamp } from "./history-list-model.ts";
13import { actionFor, buildRow, buildRun, h, statusEl } from "./history-list-rows.ts";
14
15export { countWords, wordDelta, deltaSign, deltaText, deltaOf, condense, stamp, dayOf, rangeText, runTitle, pickTwo, orderPair, compareHref, PICK_NONE, PICK_BLOCKED, pickedText, restoredEntry, restoredMessage, destinationWord } from "./history-list-model.ts";
16export type { HistoryKind, Destination, HistoryEntry, Run, Single, Line, Sign, Picks } from "./history-list-model.ts";
17export { SIGN_GLYPH, destinationGlyph, destinationTone, buildRow, buildRun } from "./history-list-rows.ts";
18export type { BuildOptions } from "./history-list-rows.ts";
19
20export { isTypingKey };
21
22// ---------------------------------------------------------------------------------------
23// The behaviour.
24
25const READY = "data-cap-ready";
26
27function nowOf(root: Element): number {
28  const fixed = root.closest<HTMLElement>("[data-cap-now]")?.dataset.capNow;
29  return fixed ? parse(fixed) : Date.now();
30}
31
32const rowsOf = (root: HTMLElement) => root.querySelector<HTMLElement>(":scope > .cap-hist-list");
33
34// j and k between the lines' titles, row-list's movement (moveRowFocus) with its isTypingKey check.
35// Attached once per list.
36export function attachListKeys(list: HTMLElement): () => void {
37  if (list.dataset.capKeys !== undefined) return () => {};
38  list.dataset.capKeys = "";
39  const onKey = (e: KeyboardEvent) => {
40    if (e.defaultPrevented || (e.key !== "j" && e.key !== "k")) return;
41    if (isTypingKey(e) || singleKeysOff() || !listOwnsKeys(list)) return;
42    if (moveRowFocus(list, e.key === "j" ? 1 : -1) || list.contains(document.activeElement)) e.preventDefault();
43  };
44  document.addEventListener("keydown", onKey);
45  return () => {
46    document.removeEventListener("keydown", onKey);
47    delete list.dataset.capKeys;
48  };
49}
50const lineRows = (root: HTMLElement) => Array.from(root.querySelectorAll<HTMLLIElement>(".cap-hist-row[data-id]"));
51const rowById = (root: HTMLElement, id: string) => lineRows(root).find((r) => r.dataset.id === id) ?? null;
52
53// The status region for results and Undo is the page's one; where the page has none yet,
54// one is placed after the list.
55function ensureRegion(after: Element): void {
56  if (document.querySelector("[data-cap='message']")) return;
57  const region = h("div", { class: "cap-message", "data-cap": "message", role: "status", "aria-label": "Results and failures", "aria-atomic": "false" });
58  after.after(region);
59  enhanceMessage(region.parentNode ?? document);
60}
61
62function entryOf(row: HTMLElement): HistoryEntry {
63  return { id: row.dataset.id ?? "", kind: (row.dataset.kind ?? "edit") as HistoryKind, who: row.dataset.who ?? "", at: row.dataset.at ?? "", ...(row.dataset.words !== undefined ? { words: Number(row.dataset.words) } : {}), summary: row.querySelector(".cap-row-title a")?.textContent ?? "" };
64}
65
66function setCurrent(root: HTMLElement, row: HTMLLIElement, current: boolean): void {
67  const entry = entryOf(row);
68  const actions = row.querySelector<HTMLElement>(".cap-row-actions");
69  if (!actions) return;
70  const now = nowOf(root);
71  if (current) {
72    row.dataset.current = "";
73    actions.replaceChildren(statusEl("ok", GLYPHS.ok, "Current"));
74  } else {
75    delete row.dataset.current;
76    actions.replaceChildren(...[actionFor(entry, now, { prefix: "", loadHref: root.dataset.loadHref, readOnly: root.dataset.readonly !== undefined })].filter((a): a is HTMLElement => a !== null));
77  }
78}
79
80function currentRow(root: HTMLElement): HTMLLIElement | null {
81  return root.querySelector<HTMLLIElement>(".cap-hist-row[data-current]");
82}
83
84export interface LoadDetail {
85  // The line whose text goes to the editor.
86  entry: HistoryEntry;
87}
88
89export interface RestoreDetail {
90  // The line restored from, and the line a restore adds on top.
91  source: HistoryEntry;
92  entry: HistoryEntry;
93}
94
95// Restores a version: adds a new line on top, makes it current, says so with Undo. Nothing
96// is overwritten; the line restored from stays. Fires `cap:history-restored` (and
97// `cap:history-unrestored` on Undo) on the root, so the app can save or undo the new
98// version on its server. Returns the new line, or null when the id is unknown.
99export function restoreVersion(root: HTMLElement, id: string): HTMLLIElement | null {
100  const list = rowsOf(root);
101  const sourceRow = rowById(root, id);
102  const previous = currentRow(root);
103  if (!list || !sourceRow || !previous || sourceRow === previous) return null;
104  const now = nowOf(root);
105  const prefix = root.id || "cap-hist";
106  const source = entryOf(sourceRow);
107  const entry = restoredEntry(source, entryOf(previous), root.dataset.user || "You", `${id}-restored-${list.querySelectorAll("[data-kind='restore']").length + 1}`, new Date(now).toISOString(), now);
108  const row = buildRow(entry, entry.delta, { prefix, current: true, now, versionHref: root.dataset.versionHref, loadHref: root.dataset.loadHref, readOnly: root.dataset.readonly !== undefined });
109  setCurrent(root, previous, false);
110  list.prepend(row);
111  enhanceTime(row);
112  root.dispatchEvent(new CustomEvent<RestoreDetail>("cap:history-restored", { bubbles: true, detail: { source, entry } }));
113  ensureRegion(root);
114  const opener = sourceRow.querySelector<HTMLElement>("[data-cap-part='restore']");
115  say(restoredMessage(source, now), {
116    undo: () => {
117      row.remove();
118      setCurrent(root, previous, true);
119      syncPicks(root);
120      root.dispatchEvent(new CustomEvent<RestoreDetail>("cap:history-unrestored", { bubbles: true, detail: { source, entry } }));
121    },
122    undone: "The restored copy was removed. The earlier version is current again.",
123    returnFocus: () => (opener?.isConnected ? opener : (previous.querySelector<HTMLElement>(".cap-row-title a") ?? null)),
124  });
125  return row;
126}
127
128// Adds older lines at the foot (a page of history the app fetched). `more: false` removes
129// the Load older control, because there is nothing older. A page should start on a line
130// that is not an autosave, or a run is split in two at the join.
131export function appendEntries(root: HTMLElement, entries: readonly HistoryEntry[], opts: { more?: boolean } = {}): void {
132  const list = rowsOf(root);
133  if (!list) return;
134  const now = nowOf(root);
135  const prefix = root.id || "cap-hist";
136  const lines = condense(entries.map((e) => e));
137  let index = 0;
138  for (const line of lines) {
139    if (line.type === "entry") {
140      list.append(buildRow(line.entry, deltaOf(entries, index), { prefix, now, versionHref: root.dataset.versionHref, loadHref: root.dataset.loadHref, readOnly: root.dataset.readonly !== undefined }));
141      index += 1;
142    } else {
143      const deltas = line.entries.map((_e, k) => deltaOf(entries, index + k));
144      list.append(...buildRun(line, deltas, { prefix, now, versionHref: root.dataset.versionHref, loadHref: root.dataset.loadHref, readOnly: root.dataset.readonly !== undefined }));
145      index += line.entries.length;
146    }
147  }
148  enhanceTime(list);
149  const more = root.querySelector<HTMLElement>("[data-cap-part='older']");
150  if (more) {
151    more.removeAttribute("aria-busy");
152    if (opts.more === false) more.remove();
153    else (more as HTMLAnchorElement).href = `?before=${encodeURIComponent((entries[entries.length - 1] as HistoryEntry).id)}`;
154  }
155  syncPicks(root);
156}
157
158// Reads the picks from the checkboxes, applies the "at most two" rule to the rest of them,
159// and says what is picked. `blocked` says a third pick was just refused.
160export function syncPicks(root: HTMLElement, blocked = false): string[] {
161  const boxes = Array.from(root.querySelectorAll<HTMLInputElement>("[data-cap-part='pick']"));
162  const picked = boxes.filter((b) => b.checked).map((b) => b.value);
163  const at = (id: string) => parse(rowById(root, id)?.dataset.at ?? "");
164  const pair = orderPair(picked, at);
165  for (const b of boxes) {
166    if (!b.checked && picked.length >= 2) b.setAttribute("aria-disabled", "true");
167    else b.removeAttribute("aria-disabled");
168  }
169  const now = nowOf(root);
170  const status = root.querySelector<HTMLElement>("[data-cap-part='picked']");
171  if (status) {
172    const text = pair ? pickedText(2, stamp(rowById(root, pair[0])?.dataset.at ?? "", now), stamp(rowById(root, pair[1])?.dataset.at ?? "", now)) : pickedText(picked.length);
173    status.textContent = blocked ? PICK_BLOCKED : text;
174  }
175  const link = root.querySelector<HTMLAnchorElement>("[data-cap-part='compare']");
176  if (link) {
177    if (pair) {
178      link.href = compareHref(root.dataset.compareHref ?? "", pair[0], pair[1]);
179      link.removeAttribute("aria-disabled");
180      link.removeAttribute("role");
181      link.removeAttribute("tabindex");
182    } else {
183      link.removeAttribute("href");
184      link.setAttribute("aria-disabled", "true");
185      link.setAttribute("role", "link");
186      link.setAttribute("tabindex", "0");
187    }
188  }
189  root.dataset.picked = String(picked.length);
190  return picked;
191}
192
193// Attaches to every [data-cap="history-list"] under root not yet attached: j and k on its
194// list, the group lines that open, the picks, Restore and Load older. Returns a function
195// that detaches them.
196export function enhance(root: ParentNode = document): () => void {
197  const undo: Array<() => void> = [];
198  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='history-list']")) {
199    if (el.hasAttribute(READY)) continue;
200    el.setAttribute(READY, "");
201    const list = rowsOf(el);
202    if (list) undo.push(attachListKeys(list));
203    enhanceTime(el);
204
205    const onClick = (e: MouseEvent) => {
206      const t = e.target as Element;
207      const group = t.closest<HTMLElement>("button[aria-expanded][aria-controls]");
208      if (group && el.contains(group)) return toggleGroup(group);
209      const box = t.closest<HTMLInputElement>("[data-cap-part='pick']");
210      if (box && box.getAttribute("aria-disabled") === "true") {
211        // A third pick: refused, and said.
212        e.preventDefault();
213        syncPicks(el, true);
214        return;
215      }
216      const restore = t.closest<HTMLElement>("[data-cap-part='restore']");
217      if (restore) return void restoreVersion(el, restore.dataset.version ?? "");
218      const load = t.closest<HTMLAnchorElement>("[data-cap-part='load']");
219      if (load) {
220        // The app may load the text into its own editor: cancel the event and do it. Without
221        // a listener the link is followed, so the page works as delivered.
222        const row = load.closest<HTMLElement>(".cap-hist-row");
223        if (row && !el.dispatchEvent(new CustomEvent<LoadDetail>("cap:history-load", { bubbles: true, cancelable: true, detail: { entry: entryOf(row) } }))) e.preventDefault();
224        return;
225      }
226      const compare = t.closest<HTMLElement>("[data-cap-part='compare']");
227      if (compare && compare.getAttribute("aria-disabled") === "true") {
228        e.preventDefault();
229        const status = el.querySelector<HTMLElement>("[data-cap-part='picked']");
230        if (status) status.textContent = PICK_NONE;
231        return;
232      }
233      const older = t.closest<HTMLAnchorElement>("[data-cap-part='older']");
234      if (older) {
235        // The app may fetch the page itself: cancel the event and call appendEntries. Without
236        // a listener the link is followed, so the page works as delivered.
237        const last = lineRows(el).at(-1)?.dataset.id ?? "";
238        const handled = !el.dispatchEvent(new CustomEvent("cap:history-older", { bubbles: true, cancelable: true, detail: { before: last } }));
239        if (handled) {
240          e.preventDefault();
241          older.setAttribute("aria-busy", "true");
242        }
243      }
244    };
245    const onChange = (e: Event) => {
246      if ((e.target as Element).matches("[data-cap-part='pick']")) syncPicks(el);
247    };
248    // A space on the aria-disabled compare link is a press, as on a button.
249    const onKey = (e: KeyboardEvent) => {
250      const t = e.target as HTMLElement;
251      if (e.key === " " && t.matches("[data-cap-part='compare']")) {
252        e.preventDefault();
253        t.click();
254      }
255    };
256    el.addEventListener("click", onClick);
257    el.addEventListener("change", onChange);
258    el.addEventListener("keydown", onKey);
259    syncPicks(el);
260    undo.push(() => {
261      el.removeEventListener("click", onClick);
262      el.removeEventListener("change", onChange);
263      el.removeEventListener("keydown", onKey);
264      el.removeAttribute(READY);
265    });
266  }
267  return () => undo.forEach((f) => f());
268}