app/enhance/blog.ts

Functions

Imports

It imports app/lib/clipboard.ts, app/lib/text-fragment.mjs. No module of this repo imports it.

Source

1import { copyText } from "../lib/clipboard";
2import { textFragment } from "../lib/text-fragment.mjs";
3
4const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
5
6function onIdle(fn: () => void) {
7  // Not in this tsconfig's DOM lib, so it is typed as an optional extra; the `in` guard decides.
8  const idle = window as typeof window & {
9    requestIdleCallback?: (cb: () => void) => void;
10  };
11  if ("requestIdleCallback" in window && idle.requestIdleCallback) {
12    idle.requestIdleCallback(fn);
13  } else {
14    setTimeout(fn, 1);
15  }
16}
17
18// Two viewports, not one: at one the bar describes a few pixels of scroll and jumps from empty to full.
19const PROGRESS_MIN_VIEWPORTS = 2;
20
21function readingProgress() {
22  const article = document.querySelector<HTMLElement>(".post .prose");
23  if (!article) return;
24
25  const worthDrawing = () => article.offsetHeight >= window.innerHeight * PROGRESS_MIN_VIEWPORTS;
26  if (!worthDrawing()) return;
27
28  const bar = document.createElement("div");
29  bar.className = "reading-progress";
30  bar.setAttribute("role", "presentation");
31  document.body.insertBefore(bar, document.body.firstChild);
32
33  let ticking = false;
34  const update = () => {
35    bar.hidden = !worthDrawing();
36    const start = article.offsetTop;
37    const height = article.offsetHeight - window.innerHeight;
38    const scrolled = height > 0 ? (window.scrollY - start) / height : 0;
39    bar.style.transform = `scaleX(${Math.min(1, Math.max(0, scrolled))})`;
40    ticking = false;
41  };
42
43  const schedule = () => {
44    if (ticking) return;
45    ticking = true;
46    requestAnimationFrame(update);
47  };
48
49  addEventListener("scroll", schedule, { passive: true });
50  /* A rotation changes both the viewport and the article's height, so it re-asks the question. */
51  addEventListener("resize", schedule, { passive: true });
52  update();
53}
54
55function scrollSpy() {
56  const toc = document.querySelector<HTMLElement>(".post-toc");
57  if (!toc) return;
58
59  const links = Array.from(toc.querySelectorAll<HTMLAnchorElement>("a[href^='#']"));
60  const targets = links
61    .map((link) => document.getElementById(decodeURIComponent(link.hash.slice(1))))
62    .filter((el): el is HTMLElement => el !== null);
63  if (targets.length === 0) return;
64
65  const seen = new Map<string, boolean>();
66  const observer = new IntersectionObserver(
67    (entries) => {
68      for (const entry of entries) seen.set(entry.target.id, entry.isIntersecting);
69      const active = targets.find((t) => seen.get(t.id));
70      for (const link of links) {
71        const isActive = active !== undefined && link.hash === `#${active.id}`;
72        // The state itself, not a styling hook, so a screen reader hears which section is current.
73        if (isActive) link.setAttribute("aria-current", "location");
74        else link.removeAttribute("aria-current");
75      }
76    },
77    { rootMargin: "0px 0px -70% 0px" },
78  );
79  for (const target of targets) observer.observe(target);
80}
81
82/**
83 * One shared live region for every copy control: a live region announces changes to its own
84 * contents, so one per control would compete. `role="status"` so it never interrupts reading.
85 */
86let statusRegion: HTMLElement | null = null;
87
88function announce(message: string) {
89  if (!statusRegion) {
90    statusRegion = document.createElement("p");
91    statusRegion.className = "sr-only";
92    statusRegion.setAttribute("role", "status");
93    document.body.appendChild(statusRegion);
94  }
95  // Cleared first: a live region announces a change, so writing the same string twice would be silent.
96  statusRegion.textContent = "";
97  requestAnimationFrame(() => {
98    if (statusRegion) statusRegion.textContent = message;
99  });
100}
101
102function decorateCodeBlock(pre: HTMLElement) {
103  // Tests for the button, not `data-enhanced`: the attribute can be lost while the button survives.
104  if (pre.querySelector(":scope > .code-copy")) return;
105
106  const lang = pre.dataset.lang;
107  if (lang && lang !== "text") {
108    const label = document.createElement("span");
109    label.className = "code-lang";
110    label.textContent = lang;
111    label.setAttribute("aria-hidden", "true");
112    pre.appendChild(label);
113  }
114
115  const button = document.createElement("button");
116  button.type = "button";
117  button.className = "code-copy";
118  button.textContent = "Copy";
119  button.setAttribute("aria-label", "Copy code to clipboard");
120  button.addEventListener("click", async () => {
121    const code = pre.querySelector("code")?.textContent ?? "";
122    try {
123      await copyText(code);
124      button.textContent = "Copied";
125      button.setAttribute("data-copied", "true");
126      announce("Code copied");
127    } catch {
128      button.textContent = "Press Ctrl C";
129      announce("Copy failed. Press Control C to copy.");
130    }
131    setTimeout(() => {
132      button.textContent = "Copy";
133      button.removeAttribute("data-copied");
134    }, 2000);
135  });
136  pre.appendChild(button);
137
138  // Last, so the padding never arrives before the thing it makes room for.
139  pre.setAttribute("data-enhanced", "");
140}
141
142/**
143 * Keeps observing so decoration does not depend on when this bundle runs relative to a subtree
144 * rewrite. It terminates: `decorateCodeBlock` writes nothing to a `pre` already carrying `data-enhanced`.
145 */
146function codeBlocks() {
147  const prose = document.querySelector<HTMLElement>(".prose");
148  const decorateAll = () => {
149    for (const pre of document.querySelectorAll<HTMLElement>(".prose pre[data-lang]")) {
150      decorateCodeBlock(pre);
151    }
152  };
153
154  decorateAll();
155  if (!prose) return;
156  new MutationObserver(decorateAll).observe(prose, { childList: true, subtree: true });
157}
158
159function headingLinks() {
160  for (const anchor of document.querySelectorAll<HTMLAnchorElement>(
161    ".prose .heading-anchor",
162  )) {
163    anchor.addEventListener("click", (event) => {
164      /*
165       * `focus()` rather than `scrollIntoView`, so a screen reader announces the heading and the next Tab
166       * continues from it. `tabindex="-1"` makes it focusable without adding it to the tab order.
167       */
168      if (!navigator.clipboard) return;
169      event.preventDefault();
170      const url = new URL(anchor.getAttribute("href") ?? "", location.href);
171      const heading = anchor.closest("h2, h3, h4") ?? document.getElementById(url.hash.slice(1));
172
173      const land = () => {
174        history.replaceState(null, "", url.hash);
175        if (!(heading instanceof HTMLElement)) return;
176        const had = heading.hasAttribute("tabindex");
177        if (!had) heading.setAttribute("tabindex", "-1");
178        heading.focus();
179        // Removed on blur rather than immediately: taking it away while the
180        // element still holds focus drops focus to the body in some engines.
181        if (!had) heading.addEventListener("blur", () => heading.removeAttribute("tabindex"), {
182          once: true,
183        });
184      };
185
186      void copyText(url.href)
187        .then(() => {
188          anchor.setAttribute("data-copied", "true");
189          setTimeout(() => anchor.removeAttribute("data-copied"), 1500);
190          announce("Link copied");
191        })
192        // A refused clipboard must not cost the reader the navigation, so landing happens either way.
193        .catch(() => announce("Copy failed. The link is in the address bar."))
194        .finally(land);
195    });
196  }
197}
198
199function footnotePreviews() {
200  const notes = document.querySelector(".prose .footnotes");
201  if (!notes) return;
202
203  let bubble: HTMLElement | null = null;
204  // The reference being previewed, and the aria-describedby it had before ("footnote-label").
205  let owner: HTMLElement | null = null;
206  let prior = "";
207  let pending: ReturnType<typeof setTimeout> | null = null;
208  /*
209   * A manual popover, so the top layer lifts it over everything and CSS anchor positioning keeps it
210   * under its reference (post-enhancements.css). Without anchor positioning it is placed once, in
211   * document coordinates, as before. Every engine with anchor positioning shipped popover first, so
212   * one probe answers both.
213   */
214  const anchored = CSS.supports("anchor-name: --a");
215
216  const cancelHide = () => {
217    if (pending !== null) clearTimeout(pending);
218    pending = null;
219  };
220
221  const hide = () => {
222    cancelHide();
223    bubble?.remove();
224    bubble = null;
225    owner?.setAttribute("aria-describedby", prior);
226    owner = null;
227  };
228
229  /*
230   * WCAG 1.4.13 hoverable: leaving the reference schedules a hide and entering the bubble cancels it,
231   * so the pointer can cross the gap to the bubble.
232   */
233  const HOVER_GRACE_MS = 220;
234  const scheduleHide = () => {
235    cancelHide();
236    pending = setTimeout(hide, HOVER_GRACE_MS);
237  };
238
239  for (const ref of document.querySelectorAll<HTMLAnchorElement>(
240    ".prose a[data-footnote-ref]",
241  )) {
242    const show = () => {
243      const target = document.getElementById(decodeURIComponent(ref.hash.slice(1)));
244      if (!target) return;
245      hide();
246      bubble = document.createElement("div");
247      // One preview at a time, so its class can double as its id.
248      bubble.id = bubble.className = "footnote-preview";
249      bubble.setAttribute("role", "note");
250      bubble.innerHTML = target.innerHTML;
251      for (const back of bubble.querySelectorAll("[data-footnote-backref]")) back.remove();
252
253      bubble.addEventListener("mouseenter", cancelHide);
254      bubble.addEventListener("mouseleave", scheduleHide);
255
256      // 1.3.1: the reference is described by the note it previews, so a screen reader hears it on focus.
257      owner = ref;
258      prior = ref.getAttribute("aria-describedby") ?? "";
259      ref.setAttribute("aria-describedby", `${bubble.id} ${prior}`);
260      document.body.appendChild(bubble);
261      if (anchored) {
262        bubble.popover = "manual";
263        bubble.showPopover();
264        return;
265      }
266      const box = ref.getBoundingClientRect();
267      bubble.style.top = `${box.bottom + window.scrollY + 8}px`;
268      bubble.style.left = `${Math.max(8, box.left + window.scrollX - 20)}px`;
269    };
270    ref.addEventListener("mouseenter", show);
271    ref.addEventListener("focus", show);
272    ref.addEventListener("mouseleave", scheduleHide);
273    ref.addEventListener("blur", scheduleHide);
274  }
275
276  // Escape dismisses WITHOUT moving focus, as 1.4.13 asks.
277  document.addEventListener("keydown", (event) => {
278    if (event.key === "Escape" && bubble) {
279      event.stopPropagation();
280      hide();
281    }
282  });
283}
284
285
286/**
287 * `src` is passed in rather than read from `currentSrc`, which is whichever `srcset` rung the browser
288 * downloaded: a resized copy shown as full size.
289 */
290/** One name, moved from the figure to the full image and back, so the browser morphs one into the other. */
291const GROW_NAME = "lightbox-figure";
292
293/**
294 * The figure grows into the viewer and shrinks back, as a same-document View Transition. It carries
295 * no type, so the cross-document page fade (motion-print.css, type site) does not restyle it.
296 * Skipped under reduced motion, which the stylesheet's rule cannot reach from script, and where the
297 * API is missing: then the change simply happens, as it did before.
298 */
299function grow(from: HTMLElement | undefined, to: HTMLElement, change: () => void) {
300  const start = (document as Document & {
301    startViewTransition?: (update: () => void) => { ready: Promise<void>; finished: Promise<void> };
302  }).startViewTransition;
303  if (!from || !start || reduceMotion.matches) {
304    change();
305    return;
306  }
307  from.style.viewTransitionName = GROW_NAME;
308  const transition = start.call(document, () => {
309    from.style.viewTransitionName = "";
310    to.style.viewTransitionName = GROW_NAME;
311    change();
312  });
313  // A skipped transition rejects `ready` with an InvalidStateError: the tab went hidden, or another
314  // transition started first. The update callback still ran, so the change happened and only the
315  // animation was dropped. Anything else is a real failure and is rethrown to where it can be seen.
316  void transition.ready.catch((error: unknown) => {
317    if (error instanceof DOMException && error.name === "InvalidStateError") return;
318    throw error;
319  });
320  // The name is cleared once the morph ends, so no later transition picks up a stale pair.
321  void transition.finished.finally(() => {
322    to.style.viewTransitionName = "";
323  });
324}
325
326function openOverlay(
327  src: string,
328  alt: string,
329  restoreFocus: () => void,
330  label?: string,
331  source?: HTMLElement,
332) {
333  // `restoreFocus` is kept because the opener is not always the element focus should land on.
334  const dialog = document.createElement("dialog");
335  dialog.className = "lightbox";
336  /*
337   * Empty alt means decorative, so the dialog gets a generic label rather than an empty one. A
338   * diagram passes its own short label: its alt describes every node and is too long for a name.
339   */
340  dialog.setAttribute("aria-label", label ?? (alt || "Full size image"));
341  if (reduceMotion.matches) dialog.dataset.reduced = "true";
342
343  const full = document.createElement("img");
344  full.src = src;
345  full.alt = alt;
346  dialog.appendChild(full);
347
348  const close = document.createElement("button");
349  close.type = "button";
350  close.className = "lightbox-close";
351  close.textContent = "Close";
352  dialog.appendChild(close);
353
354  // The full image shrinks back into the figure it came from. Escape closes natively, without it.
355  const dismiss = () => grow(full, source ?? full, () => dialog.close());
356  close.addEventListener("click", dismiss);
357
358  // On a `<dialog>` the element itself is the click target for its backdrop.
359  dialog.addEventListener("click", (event) => {
360    if (event.target === dialog) dismiss();
361  });
362
363  dialog.addEventListener("close", () => {
364    dialog.remove();
365    restoreFocus();
366  });
367
368  grow(source, full, () => {
369    document.body.appendChild(dialog);
370    dialog.showModal();
371  });
372}
373
374function lightbox() {
375  const links = Array.from(
376    document.querySelectorAll<HTMLAnchorElement>(".prose a.image-link"),
377  );
378  for (const link of links) {
379    link.addEventListener("click", (event) => {
380      const href = link.getAttribute("href");
381      if (!href) return;
382      event.preventDefault();
383      const image = link.querySelector("img");
384      openOverlay(
385        href,
386        image?.alt ?? "",
387        () => link.focus({ preventScroll: true }),
388        undefined,
389        image ?? undefined,
390      );
391    });
392  }
393
394  // Diagram images are not wrapped in an anchor, and carry no `srcset`, so their `src` is the original.
395  const diagrams = Array.from(
396    document.querySelectorAll<HTMLImageElement>(".prose img.diagram-image"),
397  );
398  for (const image of diagrams) {
399    image.classList.add("zoomable");
400    /* A button to assistive technology and the keyboard too, not only to a pointer. */
401    image.tabIndex = 0;
402    image.setAttribute("role", "button");
403    image.setAttribute("aria-label", `Enlarge diagram: ${image.alt}`);
404    const open = () =>
405      openOverlay(
406        image.src,
407        image.alt,
408        () => image.focus({ preventScroll: true }),
409        "Diagram, full size",
410        image,
411      );
412    image.addEventListener("click", open);
413    image.addEventListener("keydown", (event) => {
414      if (event.key !== "Enter" && event.key !== " ") return;
415      event.preventDefault();
416      open();
417    });
418  }
419}
420
421function copyMarkdown() {
422  const trigger = document.querySelector<HTMLAnchorElement>("[data-copy-markdown]");
423  if (!trigger || !navigator.clipboard) return;
424
425  trigger.addEventListener("click", async (event) => {
426    event.preventDefault();
427    const original = trigger.textContent;
428    try {
429      const response = await fetch(trigger.getAttribute("href") ?? "");
430      // An error page is not the markdown: fail over to opening the link, which shows what went wrong.
431      if (!response.ok) throw new Error(`HTTP ${response.status}`);
432      await copyText(await response.text());
433      trigger.textContent = "Copied";
434      trigger.setAttribute("data-copied", "true");
435      announce("Markdown copied");
436    } catch {
437      location.href = trigger.getAttribute("href") ?? "";
438      return;
439    }
440    setTimeout(() => {
441      trigger.textContent = original;
442      trigger.removeAttribute("data-copied");
443    }, 2000);
444  });
445}
446
447const SELECTION_LABEL = "Copy link to selection";
448
449/**
450 * Script-only with no fallback: there is no scriptless way to read a selection, and the permalink
451 * is the equivalent path. Placed in the flow after the selected block, it is the next tab stop.
452 * The origin comes from the permalink, never `location`.
453 */
454function selectionLink() {
455  const article = document.querySelector<HTMLElement>(".post .prose");
456  const permalink = document.querySelector<HTMLAnchorElement>(".post-share .u-url");
457  if (!article || !permalink || !navigator.clipboard) return;
458
459  const button = document.createElement("button");
460  button.type = "button";
461  button.className = "selection-link";
462  button.textContent = SELECTION_LABEL;
463
464  let url = "";
465  let dragging = false;
466
467  const blockOf = (node: Node) => {
468    let element = node instanceof Element ? node : node.parentElement;
469    while (element && element !== article && element.parentElement !== article) {
470      element = element.parentElement;
471    }
472    return element === article ? null : element;
473  };
474
475  const update = () => {
476    const selection = getSelection();
477    const fragment = selection?.isCollapsed ? null : textFragment(selection?.toString() ?? "");
478    if (!selection || !fragment || !article.contains(selection.getRangeAt(0).commonAncestorContainer)) {
479      button.remove();
480      return;
481    }
482    url = `${permalink.href}#:~:text=${fragment}`;
483    button.textContent = SELECTION_LABEL;
484    const block = blockOf(selection.getRangeAt(0).endContainer);
485    /*
486     * Only when not already there: `insertBefore` detaches a node that has a parent, and a target
487     * detached between pointerup and click never gets the click. Not `.after()`: the global Element
488     * here is HTMLRewriter's.
489     */
490    if (block && block.nextSibling !== button) article.insertBefore(button, block.nextSibling);
491  };
492
493  // A mousedown on the button would collapse the selection and take the button away with it.
494  button.addEventListener("mousedown", (event) => event.preventDefault());
495
496  button.addEventListener("click", () => {
497    const shown = (label: string) => {
498      button.textContent = label;
499      button.setAttribute("data-copied", "true");
500      announce(label);
501      setTimeout(() => {
502        button.textContent = SELECTION_LABEL;
503        button.removeAttribute("data-copied");
504      }, 2000);
505    };
506    copyText(url).then(
507      () => shown("Link copied"),
508      () => shown("Copy failed"),
509    );
510  });
511
512  // `selectionchange` fires on every character of a drag, so pointer drags update only on release.
513  document.addEventListener("selectionchange", () => {
514    if (!dragging) update();
515  });
516  document.addEventListener("pointerdown", () => {
517    dragging = true;
518  });
519  document.addEventListener("pointerup", () => {
520    dragging = false;
521    update();
522  });
523}
524
525readingProgress();
526scrollSpy();
527codeBlocks();
528headingLinks();
529onIdle(() => {
530  footnotePreviews();
531  lightbox();
532  copyMarkdown();
533  selectionLink();
534});