components/draft-compare/draft-compare-render.ts

Functions

Imports

It imports components/draft-compare/draft-compare-diff.ts, components/time/time.ts. Imported by components/draft-compare/draft-compare-patch.ts, components/draft-compare/draft-compare.ts.

Source

1// Draft compare's renderer: renderCompare returns the HTML string for every view (draft-compare.ts).
2
3import { exact, parse } from "../time/time.ts";
4import { type Analysis, type Counts, type Entry, type Sentence, type SentenceOptions, type WordPart, analyse, countsText } from "./draft-compare-diff.ts";
5
6// ---------------------------------------------------------------------------------------
7// The renderer
8// ---------------------------------------------------------------------------------------
9
10export type CompareView = "side" | "inline" | "changes";
11export const VIEWS: readonly CompareView[] = ["side", "inline", "changes"];
12
13export interface CompareSide {
14  // What the version is called: "Draft 3", "Published 14 September".
15  title: string;
16  // Who wrote or saved it.
17  who?: string;
18  // When, as an ISO string (a time with no zone is read as UTC).
19  time?: string;
20  text: string;
21}
22
23export type RunKind = "you" | "ai" | "quoted";
24
25// A stretch of one side's text, by character offset, with who wrote it. Optional: when given,
26// each sentence is marked (the authorship component's runs) with its kind.
27export interface RunSpan {
28  from: number;
29  to: number;
30  kind: RunKind;
31}
32
33export interface CompareLabels {
34  before: string;
35  after: string;
36}
37
38export interface CompareOptions extends SentenceOptions {
39  // Ids and radio names; give each compare on a page its own. Default "compare".
40  id?: string;
41  // The view shown first. Default "side".
42  view?: CompareView;
43  // Unchanged sentences kept either side of a change before the rest collapse. Default 1.
44  context?: number;
45  labels?: Partial<CompareLabels>;
46  runs?: { before?: RunSpan[]; after?: RunSpan[] };
47  // Leave the chosen view to the app (false): enhance() then does not read or write storage.
48  remember?: boolean;
49}
50
51export const STORAGE_KEY = "cap-compare-view";
52
53const RUN_LABEL: Record<RunKind, string> = { you: "You", ai: "AI", quoted: "Quoted" };
54
55export function esc(s: string): string {
56  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
57}
58
59export const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
60export const sr = (s: string) => `<span class="cap-sr-only"> ${s} </span>`;
61
62function markup(parts: WordPart[], show: "before" | "after" | "both"): string {
63  let out = "";
64  for (const p of parts) {
65    if (p.op === "same") out += esc(p.text);
66    else if (p.op === "ins" && show !== "before") out += `<ins class="cap-ins">${sr("insertion start")}${esc(p.text)}${sr("insertion end")}</ins>`;
67    else if (p.op === "del" && show !== "after") out += `<del class="cap-del">${sr("deletion start")}${esc(p.text)}${sr("deletion end")}</del>`;
68  }
69  return out;
70}
71
72function wholeIns(s: Sentence): string {
73  return markup([{ op: "ins", text: s.text }], "after");
74}
75function wholeDel(s: Sentence): string {
76  return markup([{ op: "del", text: s.text }], "before");
77}
78
79// The html of one sentence entry on one side ("both": the inline view).
80function entryHtml(e: Entry, show: "before" | "after" | "both"): string {
81  switch (e.op) {
82    case "same":
83      return esc((show === "before" ? e.a : e.b).text);
84    case "change":
85      return markup(e.parts, show);
86    case "del":
87      return show === "after" ? "" : wholeDel(e.a);
88    case "ins":
89      return show === "before" ? "" : wholeIns(e.b);
90  }
91}
92
93function kindOf(spans: RunSpan[] | undefined, s: Sentence): RunKind | null {
94  if (!spans) return null;
95  let best: RunKind | null = null;
96  let most = 0;
97  for (const r of spans) {
98    const overlap = Math.min(r.to, s.end) - Math.max(r.from, s.start);
99    if (overlap > most) {
100      most = overlap;
101      best = r.kind;
102    }
103  }
104  return best;
105}
106
107function timeHtml(iso: string): string {
108  const t = parse(iso);
109  if (!Number.isFinite(t)) return esc(iso);
110  return `<time class="cap-time" data-cap="time" data-format="exact" datetime="${new Date(t).toISOString()}">${esc(exact(t, "UTC"))}</time>`;
111}
112
113function sideHead(role: string, s: CompareSide, which: "before" | "after"): string {
114  const meta = [s.who ? esc(s.who) : "", s.time ? timeHtml(s.time) : ""].filter(Boolean).join(" · ");
115  return `<div class="cap-compare-side" data-side="${which}"><span class="cap-compare-side-role">${esc(role)}</span><span class="cap-compare-side-title">${esc(s.title)}</span>${meta ? `<span class="cap-compare-side-meta">${meta}</span>` : ""}</div>`;
116}
117
118// Which sentences collapse: a run of unchanged sentences keeps `context` of them beside each
119// change and folds the rest when that hides at least two.
120function hiddenFlags(entries: Entry[], context: number): boolean[] {
121  const hidden = entries.map(() => false);
122  let s = 0;
123  while (s < entries.length) {
124    if ((entries[s] as Entry).op !== "same") {
125      s++;
126      continue;
127    }
128    let e = s;
129    while (e < entries.length && (entries[e] as Entry).op === "same") e++;
130    const from = s + (s > 0 ? context : 0);
131    const to = e - (e < entries.length ? context : 0);
132    if (to - from >= 2) for (let i = from; i < to; i++) hidden[i] = true;
133    s = e;
134  }
135  return hidden;
136}
137
138const gapWord = (n: number) => plural(n, "unchanged sentence", "unchanged sentences");
139
140interface Ctx {
141  id: string;
142  an: Analysis;
143  opts: CompareOptions;
144  total: number;
145  labels: CompareLabels;
146}
147
148function changeLabel(ctx: Ctx, n: number): string {
149  const c = ctx.an.perChange[n - 1] as { added: number; removed: number };
150  return `<span class="cap-compare-change-label">Change ${n} of ${ctx.total}</span><span class="cap-sr-only">, ${plural(c.added, "word", "words")} added, ${c.removed} removed.</span>`;
151}
152
153// What marks a change's first element, in the one view that carries ids.
154function changeAttrs(ctx: Ctx, n: number, withId: boolean): string {
155  const c = ctx.an.perChange[n - 1] as { added: number; removed: number };
156  return `${withId ? ` id="${ctx.id}-c${n}"` : ""} data-change="${n}" data-added="${c.added}" data-removed="${c.removed}" tabindex="-1"`;
157}
158
159// A sentence wrapped in its author's run, with the label where the kind changes.
160function runWrap(kind: RunKind | null, prev: RunKind | null, html: string, tag: "div" | "span"): string {
161  if (!kind) return html;
162  const label = kind !== prev ? `<span class="cap-run-label">${RUN_LABEL[kind]}</span>` : "";
163  return `<${tag} class="cap-run" data-kind="${kind}">${label}${html}</${tag}>`;
164}
165
166function renderSideRows(ctx: Ctx, from: number, to: number, withIds: boolean, last: { before: RunKind | null; after: RunKind | null }): string {
167  const { an, opts } = ctx;
168  let out = "";
169  for (let i = from; i < to; i++) {
170    const e = an.entries[i] as Entry;
171    const g = an.group[i] as number;
172    const opensChange = g > 0 && (i === 0 || an.group[i - 1] !== g);
173    const para = (e.a?.para ?? false) || (e.b?.para ?? false);
174    const kb = e.a ? kindOf(opts.runs?.before, e.a) : null;
175    const ka = e.b ? kindOf(opts.runs?.after, e.b) : null;
176    const before = e.op === "ins" ? "" : runWrap(kb, last.before, entryHtml(e, "before"), "div");
177    const after = e.op === "del" ? "" : runWrap(ka, last.after, entryHtml(e, "after"), "div");
178    if (e.a) last.before = kb;
179    if (e.b) last.after = ka;
180    const cell = (side: "before" | "after", html: string) =>
181      html === ""
182        ? `<div class="cap-compare-cell" data-side="${side}" data-empty aria-hidden="true"></div>`
183        : `<div class="cap-compare-cell" data-side="${side}"><span class="cap-compare-cell-label">${esc(side === "before" ? ctx.labels.before : ctx.labels.after)}</span><div class="cap-compare-text">${html}</div></div>`;
184    out += `<li class="cap-compare-row" data-op="${e.op}"${para ? " data-para" : ""}${opensChange ? changeAttrs(ctx, g, withIds) : ""}>${opensChange ? changeLabel(ctx, g) : ""}${cell("before", before)}${cell("after", after)}</li>`;
185  }
186  return out;
187}
188
189// Every segment of the entries: runs shown, runs folded.
190function segments(ctx: Ctx): Array<{ hidden: boolean; from: number; to: number }> {
191  const flags = hiddenFlags(ctx.an.entries, ctx.opts.context ?? 1);
192  const out: Array<{ hidden: boolean; from: number; to: number }> = [];
193  let i = 0;
194  while (i < flags.length) {
195    let j = i;
196    while (j < flags.length && flags[j] === flags[i]) j++;
197    out.push({ hidden: flags[i] as boolean, from: i, to: j });
198    i = j;
199  }
200  return out;
201}
202
203function gapDetails(n: number, inner: string): string {
204  return `<details class="cap-disclosure cap-compare-gap" data-cap-part="gap"><summary>${gapWord(n)}</summary>${inner}</details>`;
205}
206
207function renderSide(ctx: Ctx, withIds: boolean): string {
208  const last = { before: null as RunKind | null, after: null as RunKind | null };
209  let rows = "";
210  for (const seg of segments(ctx)) {
211    const inner = renderSideRows(ctx, seg.from, seg.to, withIds, last);
212    rows += seg.hidden ? `<li class="cap-compare-gapitem">${gapDetails(seg.to - seg.from, `<ol class="cap-compare-rows cap-compare-gap-rows">${inner}</ol>`)}</li>` : inner;
213  }
214  return `<ol class="cap-compare-rows">${rows}</ol>`;
215}
216
217// The inline and changes views build paragraphs: entries between paragraph openers.
218function paragraphs(ctx: Ctx, from: number, to: number, withIds: boolean, last: { k: RunKind | null }): string {
219  const { an, opts } = ctx;
220  let out = "";
221  let open = false;
222  let inChange = 0;
223  const closeChange = () => {
224    if (inChange) out += "</span>";
225    inChange = 0;
226  };
227  for (let i = from; i < to; i++) {
228    const e = an.entries[i] as Entry;
229    const g = an.group[i] as number;
230    const para = ((e.a?.para ?? false) || (e.b?.para ?? false));
231    if (!open || para) {
232      closeChange();
233      if (open) out += "</p>";
234      out += `<p class="cap-compare-text">`;
235      open = true;
236    }
237    if (g !== inChange) {
238      closeChange();
239      if (g) {
240        out += `<span class="cap-compare-hunk"${changeAttrs(ctx, g, withIds)}>${changeLabel(ctx, g)} `;
241        inChange = g;
242      }
243    }
244    const spans = e.b ? opts.runs?.after : opts.runs?.before;
245    const sentence = e.b ?? e.a;
246    const kind = sentence ? kindOf(spans, sentence) : null;
247    out += `${runWrap(kind, last.k, entryHtml(e, "both"), "span")} `;
248    last.k = kind;
249  }
250  closeChange();
251  if (open) out += "</p>";
252  return out;
253}
254
255function renderInline(ctx: Ctx, withIds: boolean): string {
256  const last = { k: null as RunKind | null };
257  let out = "";
258  for (const seg of segments(ctx)) {
259    const inner = paragraphs(ctx, seg.from, seg.to, withIds, last);
260    out += seg.hidden ? gapDetails(seg.to - seg.from, `<div class="cap-compare-gap-rows">${inner}</div>`) : inner;
261  }
262  return `<div class="cap-compare-flow">${out}</div>`;
263}
264
265function renderChanges(ctx: Ctx, withIds: boolean): string {
266  const { an } = ctx;
267  const last = { k: null as RunKind | null };
268  let out = "";
269  let skipped = 0;
270  const skip = () => {
271    if (skipped) out += `<p class="cap-compare-skip">${gapWord(skipped)}</p>`;
272    skipped = 0;
273  };
274  let i = 0;
275  while (i < an.entries.length) {
276    const g = an.group[i] as number;
277    if (g === 0) {
278      skipped++;
279      i++;
280      continue;
281    }
282    skip();
283    let j = i;
284    while (j < an.entries.length && an.group[j] === g) j++;
285    out += `<div class="cap-compare-card">${paragraphs(ctx, i, j, withIds, last)}</div>`;
286    i = j;
287  }
288  skip();
289  return `<div class="cap-compare-flow">${out}</div>`;
290}
291
292const VIEW_NAMES: Record<CompareView, string> = { side: "Side by side", inline: "Inline", changes: "Changes only" };
293
294function viewRegion(view: CompareView, label: string, inner: string): string {
295  return `<div class="cap-compare-view" data-view="${view}" role="region" aria-label="${esc(label)}" tabindex="0">${inner}</div>`;
296}
297
298const fmtCounts = (c: Counts) => `<p class="cap-compare-counts" data-cap-part="counts">${esc(countsText(c))}</p>`;
299
300function legend(c: Counts): string {
301  return `<div class="cap-compare-legend">
302<ul class="cap-compare-key" aria-label="Key to the marks">
303<li><span class="cap-compare-key-mark" data-kind="ins">Added</span> underlined, with a plus</li>
304<li><span class="cap-compare-key-mark" data-kind="del">Removed</span> struck through, with a minus</li>
305</ul>
306${fmtCounts(c)}
307<dl class="cap-compare-views-help">
308<div><dt>Side by side</dt><dd>before on the left, after on the right, sentence by sentence</dd></div>
309<div><dt>Inline</dt><dd>one column, with each removal and addition where it happened</dd></div>
310<div><dt>Changes only</dt><dd>just the changed sentences</dd></div>
311</dl>
312</div>`;
313}
314
315function jump(id: string, total: number): string {
316  let items = "";
317  for (let n = 1; n <= total; n++) {
318    items += `<li><a class="cap-compare-jump-link" href="#${id}-c${n}" data-jump="${n}"><span class="cap-sr-only">Change </span>${n}<span class="cap-sr-only"> of ${total}</span></a></li>`;
319  }
320  return `<div class="cap-compare-tools"><nav class="cap-compare-jump" aria-label="Changes">
321<span class="cap-compare-jump-title" aria-hidden="true">Jump to</span>
322<button type="button" class="cap-btn" data-size="sm" data-cap-part="prev" hidden>Previous change <kbd class="cap-kbd">p</kbd></button>
323<button type="button" class="cap-btn" data-size="sm" data-cap-part="next" hidden>Next change <kbd class="cap-kbd">n</kbd></button>
324<ol class="cap-compare-jump-list">${items}</ol>
325</nav>
326<button type="button" class="cap-btn" data-size="sm" data-cap-part="expand" aria-pressed="false" hidden>Expand all unchanged</button></div>`;
327}
328
329function viewSwitch(id: string, view: CompareView): string {
330  const radios = VIEWS.map((v) => `<label><input type="radio" name="${id}-view" value="${v}"${v === view ? " checked" : ""} /> ${VIEW_NAMES[v]}</label>`).join("");
331  return `<fieldset class="cap-seg"><legend class="cap-sr-only">View</legend><div class="cap-seg-options" data-size="sm">${radios}</div></fieldset>`;
332}
333
334// The compared versions, as the HTML a page delivers: both sides named, a switch between three
335// views, a legend with the counts, jump links to each change, and all three views in full.
336// Safe to call on a server; the string needs no script to read. Call enhance() in the page
337// for the jump keys, the remembered view and "expand all".
338export function renderCompare(before: CompareSide, after: CompareSide, options: CompareOptions = {}): string {
339  const id = options.id ?? "compare";
340  const view = options.view ?? "side";
341  const labels: CompareLabels = { before: "Before", after: "After", ...options.labels };
342  const an = analyse(before.text, after.text, options);
343  const name = `Compare ${before.title} with ${after.title}`;
344  const attrs = `class="cap-compare" data-cap="draft-compare" id="${id}" aria-label="${esc(name)}"${options.remember === false ? ' data-remember="off"' : ""}`;
345  const head = `<div class="cap-compare-head">${sideHead(labels.before, before, "before")}${sideHead(labels.after, after, "after")}</div>`;
346
347  if (an.identical) {
348    const words = (s: CompareSide) => `“${esc(s.title)}”${s.who || s.time ? ` (${[s.who ? esc(s.who) : "", s.time ? timeHtml(s.time) : ""].filter(Boolean).join(", ")})` : ""}`;
349    const ctx: Ctx = { id, an, opts: options, total: 0, labels };
350    const flow = `<div class="cap-compare-flow">${paragraphs(ctx, 0, an.entries.length, false, { k: null })}</div>`;
351    return `<section ${attrs}>${head}<p class="cap-compare-none" role="status"><strong>No differences.</strong> ${words(before)} and ${words(after)} read the same, word for word.</p>${an.entries.length ? `<div class="cap-compare-view" data-view="same" role="region" aria-label="The text, the same on both sides" tabindex="0">${flow}</div>` : ""}</section>`;
352  }
353
354  const ctx: Ctx = { id, an, opts: options, total: an.counts.changes, labels };
355  const body = (v: CompareView) => (v === "side" ? renderSide(ctx, v === view) : v === "inline" ? renderInline(ctx, v === view) : renderChanges(ctx, v === view));
356  const views = VIEWS.map((v) => viewRegion(v, `${VIEW_NAMES[v]}, ${name}`, body(v))).join("");
357  return `<section ${attrs}>${head}<div class="cap-compare-bar">${viewSwitch(id, view)}${legend(an.counts)}</div>${jump(id, an.counts.changes)}<p class="cap-sr-only" role="status" data-cap-part="live"></p><div class="cap-compare-views">${views}</div></section>`;
358}