components/history-list/history-list-model.ts

Functions

Imports

It imports components/time/time.ts. Imported by components/history-list/history-list-rows.ts, components/history-list/history-list.ts.

Source

1// The history list's data and its pure helpers (history-list.ts).
2
3import { parse } from "../time/time.ts";
4
5// ---------------------------------------------------------------------------------------
6// The data.
7
8export type HistoryKind = "edit" | "autosave" | "named" | "publish" | "restore";
9
10export interface Destination {
11  name: string;
12  // Words, not colours alone: Live, Failed, Queued.
13  status: "live" | "failed" | "queued";
14}
15
16export interface HistoryEntry {
17  id: string;
18  kind: HistoryKind;
19  // Who made the change, by name. `ai` sets the avatar's initials in the mono face.
20  who: string;
21  ai?: boolean;
22  // When, as an ISO timestamp (a zoneless one is UTC, as in the time component).
23  at: string;
24  // The post's length in words after this change. The line's signed size change is the
25  // difference from the next older line. Leave it out where there is no word count (a site
26  // revision): the line then shows no size change.
27  words?: number;
28  // The signed change, when the caller knows it better than the difference (the oldest line,
29  // whose predecessor is not loaded).
30  delta?: number;
31  // One line; the whole text stays in the link's name.
32  summary: string;
33  // A named version's name.
34  name?: string;
35  destinations?: Destination[];
36  // A restore: the line it restored from.
37  restoredFrom?: { id: string; at: string };
38}
39
40export interface Run {
41  type: "run";
42  entries: HistoryEntry[];
43  // The oldest and newest times in the run.
44  from: string;
45  to: string;
46  // Undefined when a line in the run has no word count.
47  delta?: number;
48  who: string[];
49}
50export interface Single {
51  type: "entry";
52  entry: HistoryEntry;
53}
54export type Line = Run | Single;
55
56// ---------------------------------------------------------------------------------------
57// Pure helpers.
58
59export function countWords(text: string): number {
60  const t = text.trim();
61  return t === "" ? 0 : t.split(/\s+/).length;
62}
63
64// The signed change in length, in words: `after` minus `before`. Each is the text or its
65// word count.
66export function wordDelta(before: string | number, after: string | number): number {
67  const n = (v: string | number) => (typeof v === "number" ? v : countWords(v));
68  return n(after) - n(before);
69}
70
71export type Sign = "plus" | "minus" | "zero";
72
73export function deltaSign(n: number): Sign {
74  return n > 0 ? "plus" : n < 0 ? "minus" : "zero";
75}
76
77// "+142 words", "−30 words" (a real minus sign, which a screen reader says as "minus"),
78// "+1 word", "no change in length". The sign is text; a drawn mark repeats it.
79export function deltaText(n: number): string {
80  if (n === 0) return "no change in length";
81  const abs = Math.abs(n);
82  return `${n > 0 ? "+" : "\u2212"}${abs} word${abs === 1 ? "" : "s"}`;
83}
84
85// The change each entry made, newest first: its length less the next older entry's. An
86// entry that carries its own `delta`, or the oldest one (whose predecessor is not loaded),
87// uses that, else the whole length. Undefined when the entry or the one it is measured
88// against has no word count: that line shows no size change.
89export function deltaOf(entries: readonly HistoryEntry[], index: number): number | undefined {
90  const e = entries[index];
91  if (!e) return 0;
92  if (e.delta !== undefined) return e.delta;
93  if (e.words === undefined) return undefined;
94  const older = entries[index + 1];
95  if (!older) return e.words;
96  return older.words === undefined ? undefined : e.words - older.words;
97}
98
99// The sum of the changes, undefined as soon as one has none.
100function sumDeltas(parts: (number | undefined)[]): number | undefined {
101  let total = 0;
102  for (const p of parts) {
103    if (p === undefined) return undefined;
104    total += p;
105  }
106  return total;
107}
108
109// Groups runs of consecutive autosaves into one line each; every other entry stays a line
110// of its own. Newest first, as the list is shown. The newest entry is the current version
111// and always stays a line. A run needs `minRun` autosaves (two by default): one autosave on
112// its own is just a line.
113export function condense(entries: readonly HistoryEntry[], minRun = 2): Line[] {
114  const out: Line[] = [];
115  let i = 0;
116  while (i < entries.length) {
117    const e = entries[i] as HistoryEntry;
118    if (e.kind !== "autosave" || i === 0) {
119      out.push({ type: "entry", entry: e });
120      i += 1;
121      continue;
122    }
123    let j = i;
124    while (j < entries.length && (entries[j] as HistoryEntry).kind === "autosave") j += 1;
125    const run = entries.slice(i, j);
126    if (run.length >= minRun) {
127      const times = run.map((r) => parse(r.at));
128      out.push({
129        type: "run",
130        entries: run,
131        from: run[times.indexOf(Math.min(...times))]?.at ?? "",
132        to: run[times.indexOf(Math.max(...times))]?.at ?? "",
133        delta: sumDeltas(run.map((_r, k) => deltaOf(entries, i + k))),
134        who: [...new Set(run.map((r) => r.who))],
135      });
136    } else {
137      for (const r of run) out.push({ type: "entry", entry: r });
138    }
139    i = j;
140  }
141  return out;
142}
143
144const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
145const two = (n: number) => String(n).padStart(2, "0");
146
147// "2 Oct, 14:40 UTC", with the year when it is not the reference year ("2 Oct 2025, ...").
148// Always UTC, so the page delivered by a server and the page a browser draws agree.
149export function stamp(iso: string, now: number = Date.now()): string {
150  const t = parse(iso);
151  if (!Number.isFinite(t)) return "an unreadable time";
152  const d = new Date(t);
153  const year = d.getUTCFullYear() === new Date(now).getUTCFullYear() ? "" : ` ${d.getUTCFullYear()}`;
154  return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]}${year}, ${two(d.getUTCHours())}:${two(d.getUTCMinutes())} UTC`;
155}
156
157// "2 Oct": the day alone, for a sentence ("Restored version from 2 Oct").
158export function dayOf(iso: string, now: number = Date.now()): string {
159  return stamp(iso, now).replace(/, \d\d:\d\d UTC$/, "");
160}
161
162// "14:02 to 14:40 UTC" for a run inside one UTC day; with days when it spans more than one.
163export function rangeText(fromIso: string, toIso: string, now: number = Date.now()): string {
164  const a = new Date(parse(fromIso));
165  const b = new Date(parse(toIso));
166  const clock = (d: Date) => `${two(d.getUTCHours())}:${two(d.getUTCMinutes())}`;
167  if (a.toISOString().slice(0, 10) === b.toISOString().slice(0, 10)) return `${clock(a)} to ${clock(b)} UTC`;
168  return `${stamp(fromIso, now)} to ${stamp(toIso, now)}`;
169}
170
171// "12 autosaves", "2 autosaves".
172export function runTitle(run: Pick<Run, "entries">): string {
173  return `${run.entries.length} autosaves`;
174}
175
176export interface Picks {
177  picked: string[];
178  // True when a third pick was refused: two are picked already.
179  blocked: boolean;
180}
181
182// Toggles one id in the picks. At most two: a third is refused (not swapped in), so the
183// person chooses which to untick. Unpicking always works.
184export function pickTwo(picked: readonly string[], id: string): Picks {
185  if (picked.includes(id)) return { picked: picked.filter((p) => p !== id), blocked: false };
186  if (picked.length >= 2) return { picked: [...picked], blocked: true };
187  return { picked: [...picked, id], blocked: false };
188}
189
190// The pair in time order, older first, whichever was picked first. Ties keep the pick order.
191export function orderPair(picked: readonly string[], at: (id: string) => number): [string, string] | null {
192  const [a, b] = picked;
193  if (a === undefined || b === undefined) return null;
194  return at(b) < at(a) ? [b, a] : [a, b];
195}
196
197// The compare view's address: `?from=<older>&to=<newer>`, after `base` (a path, or "").
198export function compareHref(base: string, older: string, newer: string): string {
199  return `${base}?from=${encodeURIComponent(older)}&to=${encodeURIComponent(newer)}`;
200}
201
202export const PICK_NONE = "Pick two versions to compare.";
203export const PICK_BLOCKED = "Two versions are picked; untick one first.";
204
205export function pickedText(count: number, older?: string, newer?: string): string {
206  if (count === 0) return PICK_NONE;
207  if (count === 1) return "1 version picked. Pick one more.";
208  return `2 versions picked. Older: ${older}. Newer: ${newer}. The older is always first, whichever you picked first.`;
209}
210
211// The line a restore adds on top: the restored text, as a new version.
212export function restoredEntry(source: HistoryEntry, current: HistoryEntry, who: string, id: string, atIso: string, now: number = parse(atIso)): HistoryEntry {
213  return {
214    id,
215    kind: "restore",
216    who,
217    at: atIso,
218    ...(source.words !== undefined ? { words: source.words } : {}),
219    ...(source.words !== undefined && current.words !== undefined ? { delta: wordDelta(current.words, source.words) } : {}),
220    summary: `Restored the version from ${stamp(source.at, now)}`,
221    restoredFrom: { id: source.id, at: source.at },
222  };
223}
224
225export function restoredMessage(source: Pick<HistoryEntry, "at">, now: number = Date.now()): string {
226  return `Restored version from ${dayOf(source.at, now)} as a new version.`;
227}
228
229export function destinationWord(s: Destination["status"]): string {
230  return s === "live" ? "Live" : s === "failed" ? "Failed" : "Queued";
231}