render-packs.mjs

Functions

Imports

It imports render-chart.mjs, render-diagram.mjs, render-directives.mjs, render-error.mjs. No module of this repo imports it.

Source

1// The directives dustinedwards-info writes with, registered as a pack so another site opts into them rather than inheriting them:
2// :swatch, :pullquote, :::sidenote, :::chart and :::diagram. The core (render-nomath.mjs) knows nothing of these names. A site that needs a
3// directive of its own writes a pack of the same shape: { name, directives, setup }.
4
5import { visit } from "unist-util-visit";
6
7import { buildChartModel, renderChartHast } from "./render-chart.mjs";
8import { buildDiagramModel, renderDiagramHast } from "./render-diagram.mjs";
9import {
10  refuseHeading,
11  rehypeModelMarker,
12  remarkModelDirective,
13} from "./render-directives.mjs";
14import { ContentError } from "./render-error.mjs";
15
16// Hex only: a named color, rgb() or color-mix() makes the render depend on the UA or the cascade.
17// Anchored at both ends, or #6B4FBBZZ would pass on its prefix.
18const SWATCH_HEX = /^#(?:[0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/;
19
20/**
21 * Uppercased so two spellings of one color render the same bytes. The chip is aria-hidden because the
22 * code-span label is the second channel. The inline --swatch style is already permitted by
23 * style-src-attr 'unsafe-inline' in the site's CSP, which a site using this pack must allow.
24 *
25 * @param {string} file
26 */
27export function remarkSwatch(file) {
28  return (/** @type {import("mdast").Root} */ tree) => {
29    visit(tree, (node) => {
30      if (node.type !== "textDirective" || node.name !== "swatch") return;
31
32      const attrs = /** @type {Record<string, string>} */ (node.attributes ?? {});
33      // Text children only: nested markup would put an element inside the <code> label.
34      const label = (node.children ?? [])
35        .map((child) => (child.type === "text" ? child.value : ""))
36        .join("")
37        .trim();
38      // A line of the BODY: the tree is parsed without frontmatter, and the editor preview has no file.
39      const line = node.position?.start?.line;
40      const where = `:swatch${line ? ` on line ${line} of the body` : ""}`;
41
42      const raw = (attrs.color ?? label).trim();
43      if (raw.length === 0) {
44        throw new ContentError(
45          file,
46          `${where} carries no color. Write :swatch[#RRGGBB], or ` +
47            `:swatch[a label]{color=#RRGGBB} when the label is not the hex.`,
48        );
49      }
50      if (!SWATCH_HEX.test(raw)) {
51        throw new ContentError(
52          file,
53          `${where} cannot use ${JSON.stringify(raw)} as a color. Only #RGB, ` +
54            `#RRGGBB and #RRGGBBAA are accepted: a named color, rgb() or ` +
55            `color-mix() would make the rendered page depend on something ` +
56            `outside this file.`,
57        );
58      }
59
60      const hex = raw.toUpperCase();
61      // Only a hex label is uppercased; a prose label stays as written.
62      const text = attrs.color && label ? label : hex;
63
64      node.data = {
65        ...node.data,
66        hName: "span",
67        hProperties: { className: ["swatch"] },
68      };
69      node.children = /** @type {any} */ ([
70        {
71          // emphasis is only an inline carrier: hName replaces the tag before serialization.
72          type: "emphasis",
73          data: {
74            hName: "span",
75            hProperties: {
76              className: ["swatch-chip"],
77              style: `--swatch:${hex}`,
78              "aria-hidden": "true",
79            },
80          },
81          children: [],
82        },
83        {
84          type: "inlineCode",
85          value: text,
86          data: { hProperties: { className: ["swatch-label"] } },
87        },
88      ]);
89    });
90  };
91}
92
93const PULL_QUOTE_LIMIT = 2;
94
95/**
96 * Stays in the prose flow and the site's stylesheet floats it into the rail: that aligns it with its paragraph
97 * without measuring, on a plane that does not hydrate.
98 *
99 * @param {string} file
100 */
101export function remarkSidenote(file) {
102  return (/** @type {import("mdast").Root} */ tree) => {
103    let noteIndex = 0;
104    visit(tree, (node) => {
105      if (node.type !== "containerDirective" || node.name !== "sidenote") return;
106
107      const kind = (node.attributes ?? {}).kind;
108      if (!kind) {
109        throw new ContentError(
110          file,
111          ':::sidenote requires a kind attribute, for example :::sidenote{kind="Fallback"}. ' +
112            "The label is the reader's only cue about what the note is before they read it.",
113        );
114      }
115
116      refuseHeading(
117        file,
118        node,
119        ". A heading is a section of the argument: it lands in the table of contents and is a " +
120          "link target, and the rail is not where a section goes. Keep a note to prose.",
121      );
122
123      // Numbered in source order so #sn-1 stays the first note for anyone linking to it.
124      noteIndex += 1;
125      node.data = {
126        ...node.data,
127        hName: "aside",
128        hProperties: { className: ["post-note"], id: `sn-${noteIndex}` },
129      };
130      node.children = [
131        {
132          type: "paragraph",
133          data: { hName: "b", hProperties: { className: ["post-note-kind"] } },
134          children: [{ type: "text", value: String(kind) }],
135        },
136        .../** @type {any[]} */ (node.children ?? []),
137      ];
138    });
139  };
140}
141
142const PULL_QUOTE_MAX_CHARS = 160;
143
144/**
145 * Marks a sentence already in the prose instead of duplicating it, so the .md twin, which serves the
146 * source verbatim, has it once. The raised copy is aria-hidden so a screen reader hears it once.
147 *
148 * @param {string} file
149 */
150export function remarkPullQuote(file) {
151  return (/** @type {import("mdast").Root} */ tree) => {
152    let raised = 0;
153    visit(tree, (node, index, parent) => {
154      if (node.type !== "paragraph" || parent?.type !== "root" || index === undefined) return;
155
156      /** @type {any[]} */
157      const marks = [];
158      visit(node, "textDirective", (child) => {
159        if (child.name === "pullquote") marks.push(child);
160      });
161      if (marks.length === 0) return;
162
163      const line = marks[0].position?.start?.line;
164      const where = `:pullquote${line ? ` on line ${line} of the body` : ""}`;
165
166      if (marks.length > 1) {
167        throw new ContentError(
168          file,
169          `${where}: one paragraph carries ${marks.length} pull quotes. A paragraph has one ` +
170            "sentence worth raising, and two raised above the same paragraph read as a list.",
171        );
172      }
173
174      const mark = marks[0];
175      const text = (mark.children ?? [])
176        .map((/** @type {any} */ child) => (child.type === "text" ? child.value : ""))
177        .join("")
178        .trim();
179
180      if (text.length === 0) {
181        throw new ContentError(
182          file,
183          `${where} is empty. Wrap the sentence it should raise: :pullquote[the sentence].`,
184        );
185      }
186      if (text.length > PULL_QUOTE_MAX_CHARS) {
187        throw new ContentError(
188          file,
189          `${where} is ${text.length} characters and the limit is ${PULL_QUOTE_MAX_CHARS}. ` +
190            "A pull quote is read at a glance; mark the clause rather than the sentence.",
191        );
192      }
193
194      const at = (node.children ?? []).indexOf(mark);
195      if (at === -1) {
196        throw new ContentError(
197          file,
198          `${where} is nested inside other markup. It must sit directly in the paragraph, so the ` +
199            "sentence it raises is the sentence a reader reads.",
200        );
201      }
202
203      raised += 1;
204      if (raised > PULL_QUOTE_LIMIT) {
205        throw new ContentError(
206          file,
207          `${where} is pull quote number ${raised} and the limit is ${PULL_QUOTE_LIMIT}. ` +
208            "A third one is a page with no emphasis left to spend.",
209        );
210      }
211
212      node.children.splice(at, 1, .../** @type {any[]} */ (mark.children ?? []));
213
214      parent.children.splice(index, 0, {
215        type: "paragraph",
216        data: {
217          hName: "p",
218          hProperties: { className: ["pull-quote"], "aria-hidden": "true" },
219        },
220        children: [{ type: "text", value: text }],
221      });
222
223      // Skip the quote just inserted and the paragraph it came from.
224      return index + 2;
225    });
226
227    // Every mark handled above was spliced out of its paragraph, so one still in the tree sits where the pull quote cannot be raised
228    // (a list item, a quote, a table cell). Left alone it renders as a bare <div> in the middle of a sentence.
229    visit(tree, "textDirective", (node) => {
230      if (node.name !== "pullquote") return;
231      const line = node.position?.start?.line;
232      throw new ContentError(
233        file,
234        `:pullquote${line ? ` on line ${line} of the body` : ""} is not in a top-level paragraph. A pull quote is raised above its ` +
235          "paragraph, so it cannot sit inside a list, a quote or a table.",
236      );
237    });
238  };
239}
240
241const remarkChart = remarkModelDirective({
242  name: "chart",
243  marker: "data-chart",
244  className: "chart-figure",
245  what: "data",
246  build: buildChartModel,
247});
248const rehypeChart = rehypeModelMarker("data-chart", renderChartHast);
249
250const remarkDiagram = remarkModelDirective({
251  name: "diagram",
252  marker: "data-diagram",
253  className: "diagram-figure",
254  what: "mermaid source",
255  lang: "mermaid",
256  build: buildDiagramModel,
257});
258
259/**
260 * @typedef {object} RenderPack
261 * @property {string} name
262 * @property {readonly string[]} directives every directive name the pack handles, so the unknown-directive guard allows them
263 * @property {(context: { file: string, body: string }) => {
264 *   remark: Array<[unknown, ...unknown[]]>,
265 *   rehype: Array<[unknown, ...unknown[]]>,
266 *   result?: () => Record<string, unknown>,
267 * }} setup called once per render; `result` is merged into what render returns
268 */
269
270/**
271 * dustinedwards-info's directives, in the order its renderer ran them, so the output is the same bytes.
272 *
273 * @param {object} options
274 * @param {string} options.assetPrefix the prefix of the site's diagram assets, for example "dustin-edwards-"
275 * @returns {RenderPack}
276 */
277export function editorialPack({ assetPrefix }) {
278  const rehypeDiagram = rehypeModelMarker("data-diagram", renderDiagramHast(assetPrefix));
279  return {
280    name: "editorial",
281    directives: ["chart", "diagram", "pullquote", "sidenote", "swatch"],
282    setup({ file }) {
283      /** @type {any[]} */
284      const charts = [];
285      /** @type {any[]} */
286      const diagrams = [];
287      return {
288        remark: [
289          [remarkPullQuote, file],
290          [remarkSidenote, file],
291          [remarkSwatch, file],
292          [remarkChart, file, charts],
293          [remarkDiagram, file, diagrams],
294        ],
295        rehype: [
296          [rehypeChart, charts],
297          [rehypeDiagram, diagrams],
298        ],
299        result: () => ({
300          diagrams: diagrams.map((/** @type {any} */ d) => ({ key: d.key, source: d.source })),
301        }),
302      };
303    },
304  };
305}