src/primitives/sparkline.ts

Functions

Imports

It imports src/html.ts, src/primitives/companion.ts, src/render/data.ts, src/render/figure.ts. Imported by src/index.ts.

Source

1import { element, escapeHtml } from "../html.js";
2import { defaultFormat, maxOf, minOf } from "../render/data.js";
3import { type SeriesColor, slotStyle } from "../render/figure.js";
4import { type PrimitiveTable, type PrimitiveTableOptions, primitiveTable } from "./companion.js";
5
6/** Options for {@link sparkline}. */
7export interface SparklineOptions {
8  /** The values in order. `null` is a gap: the line breaks rather than dropping to zero. */
9  readonly values: readonly (number | null)[];
10  /** What the values measure, e.g. "Entries per year"; it starts the generated description. */
11  readonly label?: string;
12  /** A description to use instead of the generated one. */
13  readonly alt?: string;
14  readonly width?: number;
15  readonly height?: number;
16  /** Shade the area under the line. */
17  readonly area?: boolean;
18  /** Mark the last value with a dot (default true). */
19  readonly endDot?: boolean;
20  /** The line's color; defaults to the theme's first series color. */
21  readonly color?: SeriesColor;
22  readonly formatValue?: (value: number) => string;
23}
24
25const INSET = 2.5;
26
27const round = (n: number): number => Math.round(n * 100) / 100;
28
29/** Everything the sparkline, its text alternative and its companion table are computed from. */
30interface SparklineValues {
31  readonly values: readonly (number | null)[];
32  /** The values that are not gaps, in order. */
33  readonly present: readonly number[];
34  readonly min: number;
35  readonly max: number;
36  readonly width: number;
37  readonly height: number;
38  readonly format: (value: number) => string;
39  /** The sentence generated from the data: count, first, last, lowest, highest. */
40  readonly summary: string;
41  readonly alt: string;
42}
43
44/** Validates the options and computes the numbers every part of a sparkline is made from. */
45function prepareSparkline(options: SparklineOptions): SparklineValues {
46  const { values } = options;
47  const width = options.width ?? 120;
48  const height = options.height ?? 32;
49  for (const [name, n] of [
50    ["width", width],
51    ["height", height],
52  ] as const) {
53    if (!(Number.isFinite(n) && n > 0)) {
54      throw new Error(`sparkline: ${name} must be a positive number, is ${n}`);
55    }
56  }
57  const format = options.formatValue ?? defaultFormat;
58  values.forEach((v, i) => {
59    if (v !== null && !Number.isFinite(v)) {
60      throw new Error(`sparkline: value ${i + 1} is ${v}, not a finite number or null`);
61    }
62  });
63  const present = values.filter((v): v is number => v !== null);
64  if (present.length === 0) throw new Error("sparkline: needs at least one value");
65  const min = minOf(present);
66  const max = maxOf(present);
67  const summary = `${options.label ? `${options.label}: ` : ""}${defaultFormat(values.length)} values, from ${format(present[0] as number)} to ${format(present[present.length - 1] as number)}; lowest ${format(min)}, highest ${format(max)}.`;
68  return {
69    values,
70    present,
71    min,
72    max,
73    width,
74    height,
75    format,
76    summary,
77    alt: options.alt?.trim() || summary,
78  };
79}
80
81/**
82 * A word-sized line chart for a trend beside a number, without axes. Its text alternative is
83 * generated from the data (count, first, last, lowest, highest) unless `alt` is given.
84 *
85 * @example
86 * sparkline({ values: [3, 5, 4, 8, 11], label: "Entries per year" });
87 */
88export function sparkline(options: SparklineOptions): string {
89  const { values, width, height, min, max, alt } = prepareSparkline(options);
90
91  const xOf = (i: number): number =>
92    round(
93      values.length === 1 ? width / 2 : INSET + (i * (width - 2 * INSET)) / (values.length - 1),
94    );
95  const yOf = (v: number): number =>
96    round(
97      max === min ? height / 2 : height - INSET - ((v - min) * (height - 2 * INSET)) / (max - min),
98    );
99
100  const segments: [number, number][][] = [];
101  let current: [number, number][] = [];
102  values.forEach((v, i) => {
103    if (v === null) {
104      if (current.length > 0) segments.push(current);
105      current = [];
106    } else current.push([xOf(i), yOf(v)]);
107  });
108  if (current.length > 0) segments.push(current);
109
110  const line = segments
111    .map((seg) => seg.map(([x, y], i) => `${i === 0 ? "M" : "L"}${x},${y}`).join(""))
112    .join("");
113  const areaPath = options.area
114    ? segments
115        .map(
116          (seg) =>
117            `M${seg[0]?.[0]},${height}${seg.map(([x, y]) => `L${x},${y}`).join("")}L${seg[seg.length - 1]?.[0]},${height}Z`,
118        )
119        .join("")
120    : "";
121
122  const lastIndex = values.length - 1;
123  const lastValue = values[lastIndex];
124
125  const parts = [
126    element("title", {}, escapeHtml(alt)),
127    areaPath
128      ? element("path", {
129          d: areaPath,
130          fill: "var(--enarratio-series-1)",
131          "fill-opacity": 0.15,
132          stroke: "none",
133        })
134      : "",
135    element("path", {
136      d: line,
137      fill: "none",
138      stroke: "var(--enarratio-series-1)",
139      "stroke-width": 1.5,
140      "stroke-linejoin": "round",
141      "stroke-linecap": "round",
142    }),
143    options.endDot !== false && lastValue !== null && lastValue !== undefined
144      ? element("circle", {
145          cx: xOf(lastIndex),
146          cy: yOf(lastValue),
147          r: 2.25,
148          fill: "var(--enarratio-series-1)",
149        })
150      : "",
151  ];
152
153  return element(
154    "svg",
155    {
156      class: "enarratio enarratio-sparkline",
157      "data-enarratio": "sparkline",
158      xmlns: "http://www.w3.org/2000/svg",
159      viewBox: `0 0 ${width} ${height}`,
160      width,
161      height,
162      role: "img",
163      "aria-label": alt,
164      style: slotStyle(options.color ? new Map([[1, options.color]]) : undefined),
165    },
166    parts.join(""),
167  );
168}
169
170/**
171 * A sparkline's numbers as a table (position and value, `no data` for a gap) and a summary
172 * sentence, computed from the same values as the drawing so the two cannot disagree. Takes the
173 * same options as {@link sparkline}. The summary is the generated description even when `alt`
174 * is given.
175 *
176 * @example
177 * const { summary, markup } = sparklineTable({ values: [3, 5, 4], label: "Entries per year" });
178 */
179export function sparklineTable(
180  options: SparklineOptions,
181  display?: PrimitiveTableOptions,
182): PrimitiveTable {
183  const p = prepareSparkline(options);
184  const name = options.label?.trim() || "Value";
185  return primitiveTable(
186    p.summary,
187    {
188      columns: ["Position", name],
189      rows: p.values.map((v, i) => [String(i + 1), v === null ? "no data" : p.format(v)]),
190    },
191    options.label?.trim() || p.alt,
192    display,
193  );
194}