render-chart.mjs

Functions

Imports

It imports no other module of this repo. Imported by render-packs.mjs.

Source

1// Validation and CSV parsing for the :::chart directive. The drawing is Enarratio's (the site's charts
2// package, as on /cv): its theme supplies the colours, its figure carries the accessible name and the
3// data table. the site's stylesheet is that theme.
4
5import { areaChart, barChart, lineChart, scatterPlot } from "enarratio/plot";
6import { fromHtml } from "hast-util-from-html";
7
8export const CHART_TYPES = ["bar", "line", "dot", "area"];
9
10const DEFAULT_WIDTH = 700;
11const DEFAULT_HEIGHT = 360;
12
13/**
14 * @param {string} text
15 * @returns {{ columns: string[], rows: string[][] }}
16 */
17function parseChartCsv(text) {
18  const lines = text
19    .split("\n")
20    .map((line) => line.replace(/\r$/, ""))
21    .filter((line) => line.trim() !== "");
22
23  const header = lines[0];
24  if (header === undefined) throw new Error("chart data is empty");
25
26  const parseLine = (/** @type {string} */ line) => {
27    /** @type {string[]} */
28    const out = [];
29    let field = "";
30    let quoted = false;
31    for (let i = 0; i < line.length; i += 1) {
32      const ch = line[i];
33      if (quoted) {
34        if (ch === '"') {
35          if (line[i + 1] === '"') {
36            field += '"';
37            i += 1;
38          } else {
39            quoted = false;
40          }
41        } else {
42          field += ch;
43        }
44      } else if (ch === '"') {
45        quoted = true;
46      } else if (ch === ",") {
47        out.push(field.trim());
48        field = "";
49      } else {
50        field += ch;
51      }
52    }
53    out.push(field.trim());
54    return out;
55  };
56
57  const columns = parseLine(header);
58  const rows = lines.slice(1).map(parseLine);
59
60  if (rows.length === 0) throw new Error("chart data has a header but no rows");
61
62  columns.forEach((name, i) => {
63    if (name === "") throw new Error(`chart data column ${i + 1} has an empty name`);
64  });
65  if (new Set(columns).size !== columns.length) {
66    throw new Error("chart data has duplicate column names");
67  }
68  rows.forEach((row, i) => {
69    if (row.length !== columns.length) {
70      throw new Error(
71        `chart data row ${i + 1} has ${row.length} fields, expected ${columns.length}`,
72      );
73    }
74  });
75
76  return { columns, rows };
77}
78
79/**
80 * The y columns and the label each series is drawn and keyed under, refused unless every column
81 * exists and every multi-series label is present and unique.
82 *
83 * @param {Record<string, string>} attrs
84 * @param {string[]} columns
85 * @returns {{ yColumns: string[], labels: string[] }}
86 */
87function resolveSeries(attrs, columns) {
88  if (!attrs.y) throw new Error(":::chart requires a y attribute naming a data column");
89  const yColumns = attrs.y.split(",").map((s) => s.trim()).filter(Boolean);
90  if (yColumns.length === 0) throw new Error(":::chart y attribute is empty");
91  for (const column of yColumns) {
92    if (!columns.includes(column)) {
93      throw new Error(
94        `:::chart y column "${column}" is not in the data (have ${columns.join(", ")})`,
95      );
96    }
97  }
98
99  let labels = yColumns;
100  if (attrs.labels) {
101    labels = attrs.labels.split(",").map((s) => s.trim());
102    if (labels.length !== yColumns.length) {
103      throw new Error(
104        `:::chart has ${yColumns.length} series but ${labels.length} labels`,
105      );
106    }
107  }
108  if (yColumns.length > 1) {
109    labels.forEach((label, i) => {
110      if (!label) {
111        throw new Error(
112          `:::chart series ${i + 1} ("${yColumns[i]}") has an empty label; multi-series charts must label every series`,
113        );
114      }
115    });
116    if (new Set(labels).size !== labels.length) {
117      throw new Error(":::chart series labels must be unique");
118    }
119  }
120  return { yColumns, labels };
121}
122
123/**
124 * Draws the model with Enarratio. The data is one row per x and series, keyed by "x", "series" and
125 * "value"; the author's column names go back on as the axis labels. Enarratio throws for anything it
126 * cannot draw (too many series, a log of zero), and that reaches the build as a ContentError.
127 *
128 * @param {{ type: string, alt: string, title: string, x: string, yColumns: string[], labels: string[],
129 *   points: Array<{ x: string | number, series: string, value: number }>, xIsNumeric: boolean }} model
130 * @returns {string} the figure's HTML
131 */
132function drawChart(model) {
133  const { type, alt, title, x, yColumns, labels, points, xIsNumeric } = model;
134  const multi = labels.length > 1;
135  const common = {
136    alt,
137    ...(title ? { title } : {}),
138    width: DEFAULT_WIDTH,
139    height: DEFAULT_HEIGHT,
140    xLabel: x,
141    yLabel: multi ? null : yColumns[0],
142  };
143  const series = multi ? { series: "series", seriesDomain: labels } : {};
144  // A one-series chart has no series field, so the label is the value axis' name.
145  const data = multi ? points : points.map(({ x: px, value }) => ({ x: px, value }));
146  const keys = { x: "x", y: "value" };
147  // Cast: Enarratio keys its options on the row type's fields, which are only known here by name.
148  const options = /** @type {any} */ ({ ...common, ...keys, ...series, data });
149
150  if (type === "bar") {
151    return barChart({ ...options, layout: "grouped" });
152  }
153  // Line, area and scatter read x as a number or a date, never as a category.
154  if (!xIsNumeric && type === "dot") {
155    throw new Error(`:::chart type "dot" needs a numeric x column, but "${x}" is not numeric`);
156  }
157  if (type === "dot") {
158    return scatterPlot(options);
159  }
160  const xType = xIsNumeric ? "linear" : "time";
161  return type === "area"
162    ? areaChart({ ...options, xType })
163    : lineChart({ ...options, xType, directLabels: multi });
164}
165
166/**
167 * @param {Record<string, string>} attrs
168 * @param {string} csv
169 */
170export function buildChartModel(attrs, csv) {
171  const type = attrs.type;
172  if (!type) throw new Error(":::chart requires a type attribute");
173  if (!CHART_TYPES.includes(type)) {
174    throw new Error(
175      `:::chart type "${type}" is not one of ${CHART_TYPES.join(", ")}`,
176    );
177  }
178
179  // Required even with the data table: the table is the long description, not the accessible name.
180  const alt = (attrs.alt ?? "").trim();
181  if (!alt) throw new Error(`:::chart "${attrs.title ?? type}" requires an alt attribute`);
182
183  const { columns, rows } = parseChartCsv(csv);
184
185  const x = attrs.x;
186  if (!x) throw new Error(":::chart requires an x attribute naming a data column");
187  if (!columns.includes(x)) {
188    throw new Error(`:::chart x column "${x}" is not in the data (have ${columns.join(", ")})`);
189  }
190
191  const { yColumns, labels } = resolveSeries(attrs, columns);
192
193  const xIndex = columns.indexOf(x);
194
195  // A numeric x column is a number, so Enarratio spaces it on a linear scale.
196  const prepared = rows.map((row, i) => {
197    const xValue = row[xIndex];
198    if (xValue === undefined) {
199      throw new Error(`:::chart row ${i + 1} has no "${x}" cell`);
200    }
201    return { row, xValue };
202  });
203  const xIsNumeric = prepared.every((p) => p.xValue !== "" && Number.isFinite(Number(p.xValue)));
204  const asX = (/** @type {string} */ v) => (xIsNumeric ? Number(v) : v);
205
206  /** @type {Array<{ x: string | number, series: string, value: number }>} */
207  const points = [];
208  prepared.forEach(({ row, xValue }, rowIndex) => {
209    yColumns.forEach((column, seriesIndex) => {
210      const raw = row[columns.indexOf(column)];
211      const value = Number(raw);
212      if (raw === undefined || raw === "" || !Number.isFinite(value)) {
213        throw new Error(
214          `:::chart row ${rowIndex + 1} column "${column}" is "${raw}", which is not a number`,
215        );
216      }
217      const series = labels[seriesIndex];
218      // Thrown, not defaulted: a point with an invented series name would render as a real series.
219      if (series === undefined) {
220        throw new Error(`:::chart has no label for series ${seriesIndex + 1}`);
221      }
222      points.push({ x: asX(xValue), series, value });
223    });
224  });
225
226  const title = (attrs.title ?? "").trim();
227  const html = drawChart({ type, alt, title, x, yColumns, labels, points, xIsNumeric });
228  return { type, alt, title, columns, rows, html };
229}
230
231/**
232 * The figure Enarratio drew, as hast. Parsed rather than allowDangerousHtml, which would open raw HTML
233 * in every post. The author's caption replaces Enarratio's own and sits where it does, above the
234 * data table; the outer figure takes Enarratio's classes and data attributes, so there is one figure.
235 *
236 * @param {ReturnType<typeof buildChartModel>} model
237 * @param {any[]} captionChildren hast for an author-written caption, may be empty
238 * @param {any} figure the directive's figure node, whose properties the chart's merge into
239 */
240export function renderChartHast(model, captionChildren, figure) {
241  const drawn = fromHtml(model.html, { fragment: true }).children.find(
242    (/** @type {any} */ n) => n.type === "element" && n.tagName === "figure",
243  );
244  if (!drawn || drawn.type !== "element") throw new Error("Enarratio returned no <figure>");
245
246  const classes = [...(figure.properties.className ?? []), ...(drawn.properties.className ?? [])];
247  figure.properties = { ...drawn.properties, className: classes };
248
249  const children = drawn.children.filter(
250    (/** @type {any} */ n) => !(n.type === "element" && n.tagName === "figcaption"),
251  );
252  if (captionChildren.length > 0) {
253    const at = children.findIndex((/** @type {any} */ n) => n.type === "element" && n.tagName === "details");
254    /** @type {import("hast").Element} */
255    const caption = {
256      type: "element",
257      tagName: "figcaption",
258      properties: { className: ["enarratio-caption"] },
259      children: captionChildren,
260    };
261    children.splice(at === -1 ? children.length : at, 0, caption);
262  }
263  return children;
264}
265