src/render/figure.ts

Functions

Imports

It imports src/html.ts, src/render/size.ts. Imported by src/index.ts, src/lite/series.ts, src/plot/heatmap.ts, src/plot/scatter.ts, src/primitives/companion.ts, src/primitives/progress-ring.ts, src/primitives/sparkline.ts, src/render/bar-model.ts, src/render/line-model.ts, src/render/plot.ts, src/render/series.ts, src/science/genome.ts, src/science/network.ts, src/science/titer.ts.

Source

1/**
2 * The figure every chart is delivered in: an optional title, a legend, the SVG named by its text
3 * alternative, an optional caption and a data table. The accessible name lives on the SVG, never
4 * on the figure, because `role="img"` hides its descendants: naming the figure would hide the
5 * caption and table from the readers they exist for.
6 */
7
8import { element, escapeHtml } from "../html.js";
9import { DEFAULT_WIDTH } from "./size.js";
10
11/** A color for one series: any CSS color, or a pair for light and dark. */
12export type SeriesColor = string | { readonly light: string; readonly dark: string };
13
14/** Options every chart accepts. */
15export interface FigureOptions {
16  /**
17   * Required. What the chart shows, including its finding, written for someone who cannot see
18   * it: "Publications rose from 2 in 2015 to 11 in 2024", not "Bar chart of publications".
19   */
20  readonly alt: string;
21  /** A visible title above the chart. */
22  readonly title?: string;
23  /** A visible caption below the chart: method, source, caveats. */
24  readonly caption?: string;
25  /** An `id` for the figure, which enhancement events carry as `chartId`. */
26  readonly id?: string;
27  /** The drawing's width in CSS pixels; the SVG scales down to fit narrower containers. */
28  readonly width?: number;
29  /** The drawing's height in CSS pixels. */
30  readonly height?: number;
31  /**
32   * How the equivalent data table is shown: in a closed disclosure (default), or only to
33   * assistive technology. It is always present.
34   */
35  readonly dataTable?: "details" | "visually-hidden";
36}
37
38/** A scale as the enhancement layer needs it to turn a pointer position back into data. */
39export interface ScaleDescription {
40  readonly type: string;
41  readonly domain: readonly (number | string)[];
42  readonly range: readonly number[];
43}
44
45/** A table of the values a chart draws. The first column holds row headers. */
46export interface DataTable {
47  readonly columns: readonly string[];
48  readonly rows: readonly (readonly string[])[];
49}
50
51/** One legend entry. */
52export interface LegendItem {
53  readonly label: string;
54  /** The palette slot, 1 to 8. */
55  readonly slot: number;
56}
57
58/** One step of a sequential color legend. */
59export interface RampItem {
60  readonly label: string;
61  /** The ramp step, 1 to 5. */
62  readonly step: number;
63}
64
65/** Everything a chart hands to {@link figure}. */
66export interface FigureParts {
67  readonly kind: string;
68  readonly svg: string;
69  readonly table: DataTable;
70  readonly legend?: readonly LegendItem[];
71  /** A legend for a sequential ramp (heatmaps, maps), shown instead of a series legend. */
72  readonly ramp?: readonly RampItem[];
73  /** The data field series come from, which legend filters report. */
74  readonly seriesField?: string;
75  readonly x?: ScaleDescription;
76  /** Which way bars run, for the entrance animation. */
77  readonly orientation?: "vertical" | "horizontal";
78  /** Per-figure overrides of palette slots, as CSS custom property declarations. */
79  readonly slotColors?: ReadonlyMap<number, SeriesColor>;
80}
81
82/**
83 * Checks the options every chart shares before anything is drawn: a meaningful `alt`, and a
84 * positive finite width and height when given (A7, F15).
85 */
86export function validateFigure(kind: string, options: FigureOptions): void {
87  requireAlt(options.alt, kind);
88  for (const name of ["width", "height"] as const) {
89    const value = options[name];
90    if (value !== undefined && !(Number.isFinite(value) && value > 0)) {
91      throw new Error(`${kind}: ${name} must be a positive number, is ${value}`);
92    }
93  }
94}
95
96/** Throws unless `alt` is meaningful text. */
97function requireAlt(alt: string | undefined, kind: string): string {
98  const trimmed = (alt ?? "").trim();
99  if (trimmed === "") {
100    throw new Error(`${kind}: alt is required and must describe what the chart shows`);
101  }
102  return trimmed;
103}
104
105/** What a caller-supplied color may contain: enough for hex, color functions and var(), not url(). */
106const SAFE_COLOR = /^[#a-z0-9(),.%\s-]+$/i;
107
108function cssColor(value: string): string {
109  if (!SAFE_COLOR.test(value) || /url\s*\(/i.test(value)) {
110    throw new Error(`"${value}" is not an allowed color; use hex, a color function or var(--name)`);
111  }
112  return value;
113}
114
115/** Per-figure palette overrides as an inline style value, or undefined when there are none. */
116export function slotStyle(
117  colors: ReadonlyMap<number, SeriesColor> | undefined,
118): string | undefined {
119  if (!colors || colors.size === 0) return undefined;
120  return [...colors]
121    .map(([slot, color]) => {
122      const value =
123        typeof color === "string"
124          ? cssColor(color)
125          : `light-dark(${cssColor(color.light)}, ${cssColor(color.dark)})`;
126      return `--enarratio-series-${slot}: ${value}`;
127    })
128    .join("; ");
129}
130
131function tableMarkup(table: DataTable, caption: string): string {
132  const head = element(
133    "tr",
134    {},
135    table.columns.map((c) => element("th", { scope: "col" }, escapeHtml(c))).join(""),
136  );
137  const body = table.rows
138    .map((row) =>
139      element(
140        "tr",
141        {},
142        row
143          .map((cell, i) =>
144            i === 0
145              ? element("th", { scope: "row" }, escapeHtml(cell))
146              : element("td", {}, escapeHtml(cell)),
147          )
148          .join(""),
149      ),
150    )
151    .join("");
152  return element(
153    "table",
154    {},
155    `${element("caption", { class: "enarratio-visually-hidden" }, escapeHtml(caption))}${element("thead", {}, head)}${element("tbody", {}, body)}`,
156  );
157}
158
159/**
160 * A data table as the markup a figure carries: in a closed disclosure (default), or visible only
161 * to assistive technology. `caption` names the table for screen readers.
162 */
163export function dataTableBlock(
164  table: DataTable,
165  caption: string,
166  display: "details" | "visually-hidden" = "details",
167): string {
168  const markup = tableMarkup(table, caption);
169  return display === "visually-hidden"
170    ? element("div", { class: "enarratio-data enarratio-visually-hidden" }, markup)
171    : element(
172        "details",
173        { class: "enarratio-data" },
174        `${element("summary", {}, "Data table")}${markup}`,
175      );
176}
177
178function legendMarkup(parts: FigureParts): string {
179  const swatch = element("span", { class: "enarratio-swatch", "aria-hidden": "true" });
180  if (parts.ramp && parts.ramp.length > 0) {
181    return element(
182      "ul",
183      { class: "enarratio-legend enarratio-ramp" },
184      parts.ramp
185        .map((item) =>
186          element("li", { "data-step": item.step }, `${swatch}${escapeHtml(item.label)}`),
187        )
188        .join(""),
189    );
190  }
191  if (!parts.legend || parts.legend.length === 0) return "";
192  return element(
193    "ul",
194    { class: "enarratio-legend" },
195    parts.legend
196      .map((item) =>
197        element(
198          "li",
199          { "data-enarratio-series": item.label, "data-slot": item.slot },
200          `${swatch}${escapeHtml(item.label)}`,
201        ),
202      )
203      .join(""),
204  );
205}
206
207/** Assembles the figure markup for a chart. */
208export function figure(options: FigureOptions, parts: FigureParts): string {
209  const alt = requireAlt(options.alt, parts.kind);
210  const title = options.title?.trim();
211  const caption = options.caption?.trim();
212
213  const legend = legendMarkup(parts);
214  const wide = (options.width ?? DEFAULT_WIDTH) >= 480;
215  const tableBlock = dataTableBlock(parts.table, `Data for: ${title ?? alt}`, options.dataTable);
216
217  return element(
218    "figure",
219    {
220      class: "enarratio",
221      id: options.id,
222      "data-enarratio": parts.kind,
223      "data-enarratio-orientation": parts.orientation,
224      "data-enarratio-x-scale": parts.x ? JSON.stringify(parts.x) : undefined,
225      "data-enarratio-series-field": parts.seriesField,
226      style: slotStyle(parts.slotColors),
227    },
228    [
229      title ? element("p", { class: "enarratio-title" }, escapeHtml(title)) : "",
230      legend,
231      // A frame that scrolls sideways on narrow screens instead of shrinking the text (A13).
232      // Drawings 30rem or wider keep that width and scroll; narrower ones scale as usual. A wide
233      // frame is the one that can scroll, so a keyboard can reach it (tabindex), and the group
234      // role lets it carry a name. Markup cannot know whether it overflows, so every wide frame
235      // gets both; enhance() drops the tab stop once the marks take focus. The name is the title,
236      // not the alt, which the SVG inside already reads.
237      element(
238        "div",
239        wide
240          ? {
241              class: "enarratio-frame enarratio-frame-wide",
242              tabindex: "0",
243              role: "group",
244              "aria-label": `${title || "Chart"}, scrolls sideways`,
245            }
246          : { class: "enarratio-frame" },
247        parts.svg,
248      ),
249      caption ? element("figcaption", { class: "enarratio-caption" }, escapeHtml(caption)) : "",
250      tableBlock,
251    ].join(""),
252  );
253}