src/render/plot.ts

Functions

Imports

It imports src/html.ts, src/render/datum.ts, src/render/document.ts, src/render/figure.ts. Imported by src/plot/bar.ts, src/plot/heatmap.ts, src/plot/line.ts, src/plot/scatter.ts, src/science/genome.ts, src/science/network.ts, src/science/titer.ts.

Source

1/**
2 * Runs Observable Plot on the server and turns its SVG into Enarratio markup: no inline styles,
3 * no per-chart `<style>`, marks named by `data-enarratio-mark`, every drawn datum keyed so the
4 * enhancement layer can find it, and coordinates rounded so output is stable across engines.
5 */
6
7import * as Plot from "@observablehq/plot";
8import { createDocument } from "#document";
9import { escapeHtml } from "../html.js";
10import { datumAttributes, type MarkDatum } from "./datum.js";
11import type { ScaleDescription } from "./figure.js";
12
13export type { MarkDatum } from "./datum.js";
14
15/**
16 * A Plot render transform that calls `apply` on each element a mark draws with the datum it
17 * draws. Plot draws one element per index entry, in index order, for bar, dot, cell, rect and text.
18 */
19export function decorate<T>(
20  items: readonly T[],
21  apply: (el: Element, item: T) => void,
22): Plot.RenderFunction {
23  return (index, scales, values, dimensions, context, next) => {
24    if (!next) throw new Error("decorate() must be used as a render transform");
25    const group = next(index, scales, values, dimensions, context);
26    if (!group) return group;
27    const children = [...group.children];
28    if (children.length !== index.length) {
29      throw new Error(`a decorated mark drew ${children.length} elements for ${index.length} data`);
30    }
31    children.forEach((child, i) => {
32      const item = items[index[i] as number];
33      if (item === undefined) throw new Error(`decorated mark index ${index[i]} has no datum`);
34      apply(child, item);
35    });
36    return group;
37  };
38}
39
40/**
41 * A render transform that tags each element with its datum's keys for the enhancement layer, and
42 * optionally decorates it further.
43 */
44export function keyed<T>(
45  items: readonly T[],
46  describe: (item: T) => MarkDatum,
47  also?: (el: Element, item: T) => void,
48): Plot.RenderFunction {
49  return decorate(items, (el, item) => {
50    tag(el, describe(item));
51    also?.(el, item);
52  });
53}
54
55/** Writes a datum's keys onto an element. */
56function tag(el: Element, datum: MarkDatum): void {
57  for (const [name, value] of datumAttributes(datum)) el.setAttribute(name, value);
58}
59
60const NUMBER = /-?\d+\.\d{3,}(?:e-?\d+)?/g;
61const ROUNDED_ATTRIBUTES = new Set([
62  "x",
63  "y",
64  "x1",
65  "x2",
66  "y1",
67  "y2",
68  "cx",
69  "cy",
70  "r",
71  "width",
72  "height",
73  "d",
74  "points",
75  "transform",
76  "viewBox",
77]);
78
79function roundCoordinates(root: Element): void {
80  for (const el of [root, ...root.querySelectorAll("*")]) {
81    for (const name of el.getAttributeNames()) {
82      if (!ROUNDED_ATTRIBUTES.has(name)) continue;
83      const value = el.getAttribute(name);
84      if (value === null) continue;
85      el.setAttribute(
86        name,
87        value.replace(NUMBER, (n) => String(Math.round(Number(n) * 100) / 100)),
88      );
89    }
90  }
91}
92
93const ELEMENT_NODE = 1;
94const TEXT_NODE = 3;
95
96/**
97 * Serializes an SVG tree with every attribute and text node escaped, so the markup is valid in
98 * HTML and XML alike whatever the data contains. Childless elements self-close, as SVG allows.
99 */
100function serialize(node: Node): string {
101  if (node.nodeType === TEXT_NODE) return escapeHtml(node.textContent ?? "");
102  if (node.nodeType !== ELEMENT_NODE) return "";
103  const el = node as Element;
104  const attrs = el
105    .getAttributeNames()
106    .map((name) => ` ${name}="${escapeHtml(el.getAttribute(name) ?? "")}"`)
107    .join("");
108  const children = [...el.childNodes].map(serialize).join("");
109  return children === ""
110    ? `<${el.localName}${attrs}/>`
111    : `<${el.localName}${attrs}>${children}</${el.localName}>`;
112}
113
114/** The result of {@link renderPlot}. */
115export interface RenderedPlot {
116  readonly svg: string;
117  readonly x?: ScaleDescription;
118}
119
120/**
121 * Draws a Plot specification into SVG markup named by `alt`: one image, or a group when its
122 * marks are links. Throws if Plot warns, because a warning means the chart shown would not be the
123 * chart intended.
124 */
125export function renderPlot(
126  options: Plot.PlotOptions,
127  alt: string,
128  role: "img" | "group" = "img",
129  after?: (svg: SVGSVGElement) => void,
130): RenderedPlot {
131  const document = createDocument();
132  const svg = Plot.plot({ ...options, document }) as unknown as SVGSVGElement & Plot.Plot;
133
134  // Plot's warning is its own node: a top-level <text> whose <title> counts the warnings. Found by
135  // that structure, not by the glyph, which data may contain (F13).
136  const warning = [...svg.children].find(
137    (el) =>
138      el.localName === "text" &&
139      /^\d+ warnings?\. Please check the console\.$/.test(
140        el.querySelector("title")?.textContent ?? "",
141      ),
142  );
143  if (warning) {
144    throw new Error(
145      `Observable Plot warned while drawing "${alt}": ${warning.querySelector("title")?.textContent ?? ""}`,
146    );
147  }
148  if (svg.localName !== "svg") {
149    throw new Error(
150      "Enarratio charts must draw a single SVG; remove Plot options that add a legend or caption",
151    );
152  }
153
154  for (const style of svg.querySelectorAll("style")) style.remove();
155  for (const name of ["class", "font-family", "font-size", "style"]) svg.removeAttribute(name);
156  // Plot names groups with aria-label, which is invalid on a <g> without a role and hidden anyway
157  // inside role="img". The name moves to a data attribute for CSS and the enhancement layer.
158  for (const group of svg.querySelectorAll("[aria-label]")) {
159    group.setAttribute("data-enarratio-mark", group.getAttribute("aria-label") ?? "");
160    group.removeAttribute("aria-label");
161    // Axes repeat what the text alternative and the data table say; once enhanced, loose tick
162    // text would be read before the marks (A12).
163    if (/axis/.test(group.getAttribute("data-enarratio-mark") ?? "")) {
164      group.setAttribute("aria-hidden", "true");
165    }
166  }
167  after?.(svg);
168  roundCoordinates(svg);
169  // A chart whose marks are links cannot be one image: role="img" would hide the links.
170  svg.setAttribute("role", role);
171  if (role === "group") svg.setAttribute("aria-roledescription", "chart");
172  svg.setAttribute("aria-label", alt);
173
174  let x: ScaleDescription | undefined;
175  const scale = svg.scale("x");
176  if (scale?.domain && scale.range && scale.type) {
177    x = {
178      type: scale.type,
179      domain: [...scale.domain].map((d) =>
180        d instanceof Date ? d.getTime() : (d as number | string),
181      ),
182      range: [...scale.range] as number[],
183    };
184  }
185  const markup = serialize(svg);
186  return x ? { svg: markup, x } : { svg: markup };
187}