src/primitives/heat-strip.ts

Functions

Imports

It imports src/html.ts, src/primitives/companion.ts, src/primitives/tick-gap.ts, src/render/data.ts. Imported by src/index.ts.

Source

1import { element, escapeHtml } from "../html.js";
2import {
3  defaultFormat,
4  maxOf,
5  minOf,
6  rampStep,
7  rampThresholds,
8  requireSize,
9} from "../render/data.js";
10import { type PrimitiveTable, type PrimitiveTableOptions, primitiveTable } from "./companion.js";
11import { tickGap } from "./tick-gap.js";
12
13/** Options for {@link heatStrip}. */
14export interface HeatStripOptions {
15  /** One value per cell, in order. `null` is a cell with no data, drawn as a dashed outline. */
16  readonly values: readonly (number | null)[];
17  /**
18   * What the strip shows and over what window, e.g. "Requests per hour, last 48 hours"; it starts
19   * the generated text alternative. Required unless `alt` is given.
20   */
21  readonly label?: string;
22  /** The text alternative, instead of the one generated from `label` and the values. */
23  readonly alt?: string;
24  /** The strip's width in CSS pixels (default 240). */
25  readonly width?: number;
26  /** The strip's height in CSS pixels (default 24). */
27  readonly height?: number;
28  /**
29   * The values the ramp runs from and to. Default: the lowest and highest value, so the strip
30   * uses all five steps; fix them to compare strips drawn from different data.
31   */
32  readonly min?: number;
33  readonly max?: number;
34  /**
35   * Four ascending values splitting the range into the ramp's five steps, as in `heatmap`.
36   * Default: equal intervals between `min` and `max`.
37   */
38  readonly thresholds?: readonly [number, number, number, number];
39  /** Hover text naming each cell, e.g. "Mon 14:00"; the value is added. Default "Cell 3". */
40  readonly cellLabels?: readonly string[];
41  /** Formats values in hover details and the text alternative. */
42  readonly formatValue?: (value: number) => string;
43}
44
45const KIND = "heatStrip";
46
47/** Everything the strip, its text alternative and its companion table are computed from. */
48interface HeatStripValues {
49  readonly values: readonly (number | null)[];
50  /** The ramp step, 1 to 5, of each cell; 0 for a cell with no data. */
51  readonly steps: readonly number[];
52  readonly min: number;
53  readonly max: number;
54  readonly thresholds: readonly number[];
55  readonly format: (value: number) => string;
56  readonly cellLabel: (index: number) => string;
57  readonly subject: string;
58  /** The sentence that names the values; the default text alternative. */
59  readonly summary: string;
60  readonly width: number;
61  readonly height: number;
62  readonly alt: string;
63}
64
65const round = (n: number): number => Math.round(n * 100) / 100;
66
67/** Validates the options and computes the numbers every part of a heat strip is made from. */
68function prepareHeatStrip(options: HeatStripOptions): HeatStripValues {
69  const { values } = options;
70  if (values.length === 0) throw new Error(`${KIND}: needs at least one value`);
71  const subject = options.label?.trim() ?? "";
72  const given = options.alt?.trim() ?? "";
73  if (subject === "" && given === "") throw new Error(`${KIND}: label or alt is required`);
74  const width = options.width ?? 240;
75  const height = options.height ?? 24;
76  requireSize(KIND, "width", width);
77  requireSize(KIND, "height", height);
78  values.forEach((v, i) => {
79    if (v !== null && !Number.isFinite(v)) {
80      throw new Error(`${KIND}: value ${i + 1} is ${v}, not a finite number or null`);
81    }
82  });
83  const present = values.filter((v): v is number => v !== null);
84  if (present.length === 0) throw new Error(`${KIND}: every value is empty`);
85  const min = options.min ?? minOf(present);
86  const max = options.max ?? maxOf(present);
87  for (const [name, n] of [
88    ["min", min],
89    ["max", max],
90  ] as const) {
91    if (!Number.isFinite(n)) throw new Error(`${KIND}: ${name} must be a finite number, is ${n}`);
92  }
93  if (min > max) throw new Error(`${KIND}: min ${min} is above max ${max}`);
94  const thresholds = rampThresholds(KIND, min, max, options.thresholds);
95  const labels = options.cellLabels;
96  if (labels !== undefined && labels.length !== values.length) {
97    throw new Error(
98      `${KIND}: cellLabels has ${labels.length} entries for ${values.length} values; give one each`,
99    );
100  }
101  const format = options.formatValue ?? defaultFormat;
102  const lowest = minOf(present);
103  const highest = maxOf(present);
104  const missing = values.length - present.length;
105  const summary = `${subject === "" ? "" : `${subject}: `}${defaultFormat(values.length)} cells, from ${format(present[0] as number)} to ${format(present[present.length - 1] as number)}; lowest ${format(lowest)}, highest ${format(highest)}${missing > 0 ? `; ${missing} with no data` : ""}.`;
106  return {
107    values,
108    steps: values.map((v) => (v === null ? 0 : rampStep(v, thresholds))),
109    min,
110    max,
111    thresholds,
112    format,
113    cellLabel: (i) => labels?.[i] ?? `Cell ${i + 1}`,
114    subject,
115    summary,
116    width,
117    height,
118    alt: given || summary,
119  };
120}
121
122/**
123 * A one-row strip of cells with no axis, each colored on the theme's sequential ramp by its value:
124 * hours of load, days of activity, a sibling of {@link uptimeStrip}. It carries a text alternative
125 * summarizing the values, and each cell has hover details. Colors come in five steps, so read the
126 * numbers from the hover details or from {@link heatStripTable}.
127 *
128 * @example
129 * heatStrip({ values: [3, 5, 9, 14, 8, 2], label: "Requests per hour" });
130 */
131export function heatStrip(options: HeatStripOptions): string {
132  const p = prepareHeatStrip(options);
133  const step = p.width / p.values.length;
134  const gap = tickGap(step);
135  const cells = p.values.map((value, i) => {
136    const title = `${p.cellLabel(i)}: ${value === null ? "no data" : p.format(value)}`;
137    const common = {
138      x: round(i * step),
139      y: 0,
140      width: round(step - gap),
141      height: p.height,
142    };
143    return element(
144      "rect",
145      value === null
146        ? {
147            ...common,
148            x: round(i * step + 0.5),
149            y: 0.5,
150            width: round(step - gap - 1),
151            height: p.height - 1,
152            fill: "none",
153            stroke: "var(--enarratio-text-muted)",
154            "stroke-dasharray": "2,2",
155          }
156        : {
157            ...common,
158            fill: `var(--enarratio-sequential-${p.steps[i]})`,
159            // A hairline keeps the palest step visible against the page.
160            stroke: "var(--enarratio-grid)",
161            "stroke-width": 0.5,
162            "data-enarratio-step": p.steps[i],
163          },
164      element("title", {}, escapeHtml(title)),
165    );
166  });
167  return element(
168    "svg",
169    {
170      class: "enarratio enarratio-heat-strip",
171      "data-enarratio": "heat-strip",
172      xmlns: "http://www.w3.org/2000/svg",
173      viewBox: `0 0 ${p.width} ${p.height}`,
174      width: p.width,
175      height: p.height,
176      role: "img",
177      "aria-label": p.alt,
178    },
179    cells.join(""),
180  );
181}
182
183/**
184 * A heat strip's cells as a table (cell, value and ramp step, `no data` for a gap) and a summary
185 * sentence, computed from the same values as the strip so the two cannot disagree. Takes the same
186 * options as {@link heatStrip}. The summary is the generated description even when `alt` is given.
187 *
188 * @example
189 * const { markup } = heatStripTable({ values: [3, 5, 9], label: "Requests per hour" });
190 */
191export function heatStripTable(
192  options: HeatStripOptions,
193  display?: PrimitiveTableOptions,
194): PrimitiveTable {
195  const p = prepareHeatStrip(options);
196  return primitiveTable(
197    p.summary,
198    {
199      columns: ["Cell", "Value", "Ramp step"],
200      rows: p.values.map((v, i) => [
201        p.cellLabel(i),
202        v === null ? "no data" : p.format(v),
203        v === null ? "" : String(p.steps[i]),
204      ]),
205    },
206    p.subject || p.alt,
207    display,
208  );
209}