render-diagram.mjs

Functions

Imports

It imports render-hast.mjs. Imported by render-packs.mjs.

Source

1// Draws nothing: diagram layout needs real font metrics, which no DOM shim in a Worker provides, so
2// the site's build renders assets ahead of time and the HTML carries only the key and source.
3
4import { h, text } from "./render-hast.mjs";
5
6// Bump when the token map, the site's colour tokens or the mermaid version changes: the key hashes
7// only the source, so a restyle without a bump leaves every rendered asset at the old colors forever.
8const DIAGRAM_TEMPLATE_VERSION = 1;
9
10/**
11 * FNV-1a, 32 bits, over UTF-16 code units: a short stable fingerprint, not a security boundary.
12 *
13 * @param {string} input
14 * @returns {string} eight lowercase hex digits
15 */
16function fnv1a32(input) {
17  let hash = 0x811c9dc5;
18  for (let i = 0; i < input.length; i += 1) {
19    hash ^= input.charCodeAt(i);
20    hash = Math.imul(hash, 0x01000193) >>> 0;
21  }
22  return hash.toString(16).padStart(8, "0");
23}
24
25export const DIAGRAM_ASSET_DIR = "diagrams";
26
27export const DIAGRAM_THEMES = ["light", "dark"];
28
29/**
30 * Posts check out as LF and the rest of the tree as CRLF; without this, clones on different OSes
31 * compute different keys for the same diagram.
32 *
33 * @param {string} source
34 */
35function normalizeDiagramSource(source) {
36  return source.replace(/\r\n/g, "\n").replace(/\s+$/, "").replace(/^\n+/, "");
37}
38
39/**
40 * @param {string} source the mermaid source, unnormalised
41 */
42function diagramKey(source) {
43  const input = `${DIAGRAM_TEMPLATE_VERSION}\n${normalizeDiagramSource(source)}`;
44  return fnv1a32(input);
45}
46
47/**
48 * @param {string} key
49 * @param {string} theme one of DIAGRAM_THEMES
50 * @param {string} assetPrefix the site's asset name prefix, for example "dustin-edwards-"
51 */
52export function diagramAssetPath(key, theme, assetPrefix) {
53  return `/${DIAGRAM_ASSET_DIR}/${assetPrefix}${key}-${theme}.svg`;
54}
55
56/**
57 * @param {Record<string, string>} attrs
58 * @param {string} source the fenced mermaid block's contents
59 */
60export function buildDiagramModel(attrs, source) {
61  // The alt must name the boxes and arrows: there is no generated equivalent like a chart's data table.
62  const alt = (attrs.alt ?? "").trim();
63  if (!alt) {
64    throw new Error(`:::diagram "${attrs.title ?? "untitled"}" requires an alt attribute`);
65  }
66
67  const normalized = normalizeDiagramSource(source);
68  if (!normalized) throw new Error(":::diagram source is empty");
69
70  return {
71    alt,
72    title: (attrs.title ?? "").trim(),
73    source: normalized,
74    key: diagramKey(source),
75  };
76}
77
78/**
79 * Two images switched by display: none in the site's stylesheet, because an <img> SVG cannot see the page's custom
80 * properties and the theme comes from a cookie, not prefers-color-scheme. No width or height: the
81 * asset may not exist yet and the pipeline cannot read the filesystem.
82 *
83 * @param {string} assetPrefix the site's asset name prefix
84 * @returns {(model: ReturnType<typeof buildDiagramModel>, captionChildren: any[]) => any[]} the rehype renderer
85 *   `captionChildren` is hast for an author-written caption, may be empty
86 */
87export const renderDiagramHast = (assetPrefix) => (model, captionChildren) => {
88  /** @type {any[]} */
89  const children = [];
90
91  if (model.title) {
92    // A <p>, not a heading: rehypeCollectToc would put diagram titles in the table of contents.
93    children.push(h("p", { className: ["diagram-title"] }, [text(model.title)]));
94  }
95
96  for (const theme of DIAGRAM_THEMES) {
97    children.push(
98      h("img", {
99        className: ["diagram-image", `diagram-${theme}`],
100        src: diagramAssetPath(model.key, theme, assetPrefix),
101        alt: model.alt,
102      }, []),
103    );
104  }
105
106  if (captionChildren.length > 0) {
107    children.push(h("figcaption", {}, captionChildren));
108  }
109
110  return children;
111};