src/render/bar-model.ts

Functions

Imports

It imports src/render/data.ts, src/render/datum.ts, src/render/figure.ts, src/render/series.ts, src/render/size.ts. Imported by src/lite/bar.ts, src/plot/bar.ts.

Source

1/**
2 * Everything about a bar chart except the drawing: reading and checking the data, the layout
3 * numbers and the data table. Shared by the Observable Plot renderer (`enarratio/plot`) and the
4 * light one (`enarratio/lite`), so both draw the same chart from the same options.
5 */
6
7import {
8  calendarDates,
9  DAY,
10  defaultFormat,
11  domainOf,
12  type KeysOfType,
13  markKey,
14  maxOf,
15  minOf,
16  readCategory,
17  readDate,
18  readLabel,
19  readNumber,
20} from "./data.js";
21import type { MarkDatum } from "./datum.js";
22import { type FigureOptions, figure, type SeriesColor, validateFigure } from "./figure.js";
23import { planSeries, type SeriesPlan } from "./series.js";
24import { DEFAULT_HEIGHT, DEFAULT_WIDTH } from "./size.js";
25
26/** Options for `barChart`, from `enarratio/plot` or `enarratio/lite`. */
27export interface BarChartOptions<T extends object> extends FigureOptions {
28  readonly data: readonly T[];
29  /**
30   * The field for categories along the bar axis: a label, or a number such as a year. With
31   * `xType: "time"` it is a time instead: a Date, an ISO 8601 string or epoch milliseconds.
32   */
33  readonly x: KeysOfType<T, string | number | Date>;
34  /**
35   * `"time"` puts the bars on a time axis: each row falls in the `interval` that contains its
36   * time, one bar slot for every interval from the first to the last (empty ones too, so a gap
37   * in the data is a gap in the chart), labelled for you. A run per day needs no pre-formatted
38   * labels. Rows in the same interval and series are summed, or counted when `y` is omitted.
39   * Dates are instants in UTC, except that when every Date falls at local midnight they are
40   * read as calendar dates, as in `lineChart`. The default, `"category"`, treats `x` as labels.
41   */
42  readonly xType?: "category" | "time";
43  /**
44   * With `xType: "time"`, the length of each bar's interval (default `"day"`). Intervals start
45   * at UTC midnight; weeks start on Monday. Each bar is labelled by its first moment: an hour
46   * as `2026-01-05 14:00 UTC`, a day or week as `2026-01-05`, a month as `2026-01`, a year as
47   * `2026`.
48   */
49  readonly interval?: "hour" | "day" | "week" | "month" | "year";
50  /** With `xType: "time"`, formats each interval's start for labels, hover details and the data table. */
51  readonly formatX?: (start: Date) => string;
52  /**
53   * The field for bar length. Omit it to count rows instead: `barChart({ data: entries, x:
54   * "year", series: "type" })` draws entries per year by type. Rows sharing a category and series
55   * are summed.
56   */
57  readonly y?: KeysOfType<T, number>;
58  /** A field that splits each bar into series, stacked or grouped. */
59  readonly series?: KeysOfType<T, string>;
60  /** How series share a category: stacked (default) or side by side. */
61  readonly layout?: "stacked" | "grouped";
62  /** Vertical bars (default), or horizontal bars for long category names and rankings. */
63  readonly orientation?: "vertical" | "horizontal";
64  /**
65   * Every category in display order. Without it, categories appear in data order, or ascending
66   * when all are numbers. Give it to show empty years or a fixed order. Not used with
67   * `xType: "time"`, which builds its own domain.
68   */
69  readonly xDomain?: readonly (string | number)[];
70  /** Every series in display and color order. Without it, first-seen order. */
71  readonly seriesDomain?: readonly string[];
72  /**
73   * Color overrides by series name. A chart without `series` has one series, named by its value
74   * label (`yLabel`).
75   */
76  readonly colors?: Readonly<Record<string, SeriesColor>>;
77  /** The category axis label; defaults to the `x` field name; `null` hides it. */
78  readonly xLabel?: string | null;
79  /** The value axis label; defaults to the `y` field name or "Count"; `null` hides it. */
80  readonly yLabel?: string | null;
81  /** Formats values in hover details and the data table. */
82  readonly formatValue?: (value: number) => string;
83  /**
84   * What a click on a bar filters by, once enhanced: its series (default when there are series)
85   * or its category (`"x"`, e.g. "this year"). A chart without series always filters by category.
86   */
87  readonly filterBy?: "series" | "x";
88  /**
89   * A link for each category, so that with scripts off a bar is a link (to a filtered page, say).
90   * Once enhanced, bars filter instead and the link moves to `data-enarratio-href`. Only relative,
91   * `http:` and `https:` links are allowed.
92   */
93  readonly href?: (x: string) => string;
94  /**
95   * The most category labels to print. With more categories than this, every nth label is
96   * printed, starting from the first, so labels stay legible when the chart is drawn small.
97   */
98  readonly maxXTicks?: number;
99  /**
100   * Print each series' name inside its bars where the name fits, so series are told apart by
101   * text as well as color (A1). Stacked layouts only; small segments keep their hover details and
102   * the data table.
103   */
104  readonly directLabels?: boolean;
105}
106
107/** One bar, or one series' segment of a bar: the rows sharing a category and series. */
108export interface BarPoint {
109  readonly x: string;
110  readonly series: string;
111  value: number;
112}
113
114const KIND = "barChart";
115
116type Interval = NonNullable<BarChartOptions<object>["interval"]>;
117
118const pad = (n: number): string => String(n).padStart(2, "0");
119
120/** The start of the interval containing `t` (UTC; weeks start on Monday), in epoch milliseconds. */
121function floorTo(t: number, interval: Interval): number {
122  const d = new Date(t);
123  switch (interval) {
124    case "hour":
125      return Math.floor(t / 3_600_000) * 3_600_000;
126    case "day":
127      return Math.floor(t / DAY) * DAY;
128    case "week": {
129      const day = Math.floor(t / DAY) * DAY;
130      const sinceMonday = (new Date(day).getUTCDay() + 6) % 7;
131      return day - sinceMonday * DAY;
132    }
133    case "month":
134      return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1);
135    case "year":
136      return Date.UTC(d.getUTCFullYear(), 0, 1);
137  }
138}
139
140/** The start of the interval after the one starting at `start`. */
141function nextAfter(start: number, interval: Interval): number {
142  const d = new Date(start);
143  switch (interval) {
144    case "hour":
145      return start + 3_600_000;
146    case "day":
147      return start + DAY;
148    case "week":
149      return start + 7 * DAY;
150    case "month":
151      return Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1);
152    case "year":
153      return Date.UTC(d.getUTCFullYear() + 1, 0, 1);
154  }
155}
156
157/** The default label for an interval starting at `start`. */
158function labelFor(start: number, interval: Interval): string {
159  const iso = new Date(start).toISOString();
160  switch (interval) {
161    case "hour":
162      return `${iso.slice(0, 10)} ${pad(new Date(start).getUTCHours())}:00 UTC`;
163    case "day":
164    case "week":
165      return iso.slice(0, 10);
166    case "month":
167      return iso.slice(0, 7);
168    case "year":
169      return iso.slice(0, 4);
170  }
171}
172
173/** The most bars a time axis will draw, so a typo in a date cannot ask for millions. */
174const MAX_PERIODS = 2000;
175
176/**
177 * The time axis: each row's interval start, and the label of every interval from the first to
178 * the last, in order.
179 */
180function timeAxis<T extends object>(
181  data: readonly T[],
182  x: string,
183  options: BarChartOptions<T>,
184): { starts: number[]; names: string[]; byRow: string[] } {
185  const interval = options.interval ?? "day";
186  const rows = calendarDates(data.map((row, i) => readDate(KIND, row, x, i)));
187  const starts = rows.map((d) => floorTo(d.getTime(), interval));
188  const label = (start: number): string =>
189    options.formatX ? options.formatX(new Date(start)) : labelFor(start, interval);
190  const first = minOf(starts);
191  const last = maxOf(starts);
192  const periods: number[] = [];
193  for (let t = first; t <= last; t = nextAfter(t, interval)) {
194    periods.push(t);
195    if (periods.length > MAX_PERIODS) {
196      throw new Error(
197        `${KIND}: the time axis would need more than ${MAX_PERIODS} bars between the first and last row; use a longer interval`,
198      );
199    }
200  }
201  const names = periods.map(label);
202  if (new Set(names).size !== names.length) {
203    throw new Error(`${KIND}: formatX gives two intervals the same label`);
204  }
205  return { starts: periods, names, byRow: starts.map(label) };
206}
207
208/**
209 * Allows relative and http(s) links only, so data can never produce a `javascript:` URL. Browsers
210 * ignore control characters and spaces inside a scheme, so the scheme is read without them. A
211 * leading `//` (or its backslash forms) names another host, so it is refused too (A11), and so is
212 * a user or password before the host, which lets `https://trusted.example@other.example/` read as
213 * the trusted name.
214 */
215function safeHref(href: string): string {
216  const compact = [...href].filter((ch) => ch.charCodeAt(0) > 0x20).join("");
217  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(compact)?.[1]?.toLowerCase();
218  const otherHost = /^[/\\][/\\]/.test(compact);
219  if (
220    otherHost ||
221    (scheme !== undefined && scheme !== "http" && scheme !== "https") ||
222    hasUserinfo(compact, scheme)
223  ) {
224    throw new Error(`${KIND}: href "${href}" is not a relative or http(s) link`);
225  }
226  return href;
227}
228
229/** Whether an absolute http(s) link names a user or password before its host. */
230function hasUserinfo(compact: string, scheme: string | undefined): boolean {
231  if (scheme === undefined) return false;
232  try {
233    const url = new URL(compact);
234    return url.username !== "" || url.password !== "";
235  } catch {
236    return true;
237  }
238}
239
240/** Every nth category, when there are more than `max`, or undefined to print them all. */
241function thinTicks(names: readonly string[], max: number | undefined): string[] | undefined {
242  if (max === undefined) return undefined;
243  if (!Number.isInteger(max) || max < 1)
244    throw new Error(`${KIND}: maxXTicks must be a whole number of 1 or more`);
245  if (names.length <= max) return undefined;
246  const step = Math.ceil(names.length / max);
247  return names.filter((_, i) => i % step === 0);
248}
249
250const STEPS = [1, 2, 5];
251
252/** Whole-number ticks from zero past the tallest bar or stack, about five of them. */
253function countTicks(points: readonly BarPoint[], grouped: boolean): number[] {
254  const totals = new Map<string, number>();
255  for (const p of points) {
256    const id = grouped ? markKey(p.x, p.series) : p.x;
257    totals.set(id, (totals.get(id) ?? 0) + p.value);
258  }
259  const max = Math.max(1, maxOf(totals.values()));
260  let step = 1;
261  for (let magnitude = 1; ; magnitude *= 10) {
262    const found = STEPS.map((s) => s * magnitude).find((s) => max / s <= 6);
263    if (found !== undefined) {
264      step = found;
265      break;
266    }
267  }
268  const ticks: number[] = [];
269  for (let t = 0; t < max + step; t += step) ticks.push(t);
270  return ticks;
271}
272
273/** A bar chart read from its options, ready for a renderer to draw. */
274export interface BarModel {
275  /** The bars, in category order, then series order: the reading order and drawing order. */
276  readonly points: readonly BarPoint[];
277  /** Every category, in display order. */
278  readonly xNames: readonly string[];
279  /** Every series, in display and color order. */
280  readonly seriesNames: readonly string[];
281  readonly plan: SeriesPlan;
282  readonly horizontal: boolean;
283  /** Series side by side, each category a facet. */
284  readonly grouped: boolean;
285  /** Whether a series name goes inside each stacked segment it fits in. */
286  readonly directLabels: boolean;
287  readonly categoryLabel: string | null;
288  readonly valueLabel: string | null;
289  readonly format: (value: number) => string;
290  readonly width: number;
291  readonly height: number;
292  readonly marginLeft: number;
293  /** The category labels to print, when not all of them are. */
294  readonly thinned: readonly string[] | undefined;
295  /** Whole-number value ticks for counted bars; undefined when values come from `y`. */
296  readonly countTicks: readonly number[] | undefined;
297  /** A bar's hover details, and its name when it is a link. */
298  describe(p: BarPoint): string;
299  /** A bar's keys for the enhancement layer. */
300  datum(p: BarPoint): MarkDatum;
301  /** A bar's link, checked, when the chart has `href`. */
302  readonly link: ((p: BarPoint) => string) | undefined;
303  /** Wraps the drawn SVG in the figure, with its legend and data table. */
304  figure(svg: string): string;
305}
306
307/** Reads and checks a bar chart's options and lays it out. Throws on anything it cannot draw. */
308export function barModel<T extends object>(options: BarChartOptions<T>): BarModel {
309  const { data, x, y, series } = options;
310  validateFigure(KIND, options);
311  if (data.length === 0) throw new Error(`${KIND}: data is empty`);
312  if (options.directLabels && options.layout === "grouped") {
313    throw new Error(`${KIND}: directLabels needs the stacked layout; grouped bars have a legend`);
314  }
315  const horizontal = options.orientation === "horizontal";
316  const grouped = options.layout === "grouped" && series !== undefined;
317  const format = options.formatValue ?? defaultFormat;
318  const valueLabel = options.yLabel === undefined ? (y ?? "Count") : options.yLabel;
319  const categoryLabel = options.xLabel === undefined ? x : options.xLabel;
320  const soleSeries = valueLabel ?? "Value";
321
322  const time = options.xType === "time";
323  if (time && options.xDomain) {
324    throw new Error(`${KIND}: xDomain is not used with xType "time", which builds its own axis`);
325  }
326  if (!time && (options.interval !== undefined || options.formatX !== undefined)) {
327    throw new Error(`${KIND}: interval and formatX belong to xType "time"`);
328  }
329  const axis = time ? timeAxis(data, x, options) : undefined;
330  const rawX = axis ? axis.byRow : data.map((row, i) => readCategory(KIND, row, x, i));
331  const xNames = axis ? axis.names : domainOf(KIND, x, rawX, options.xDomain);
332  const seriesOf = (row: T, i: number): string =>
333    series === undefined ? soleSeries : readLabel(KIND, row, series, i);
334  const seriesNames =
335    series === undefined
336      ? [soleSeries]
337      : domainOf(
338          KIND,
339          series,
340          data.map((row, i) => seriesOf(row, i)),
341          options.seriesDomain,
342        );
343  const plan = planSeries(KIND, seriesNames, options.colors);
344
345  const cells = new Map<string, BarPoint>();
346  data.forEach((row, i) => {
347    const point = { x: String(rawX[i]), series: seriesOf(row, i) };
348    const id = markKey(point.x, point.series);
349    const value = y === undefined ? 1 : readNumber(KIND, row, y, i);
350    const existing = cells.get(id);
351    if (existing) existing.value += value;
352    else cells.set(id, { ...point, value });
353  });
354  // In category order, then series order: the reading order, and the order labels are drawn in.
355  const columnOf = new Map(xNames.map((name, i) => [name, i]));
356  const rowOf = new Map(seriesNames.map((name, i) => [name, i]));
357  const points = [...cells.values()].sort(
358    (a, b) =>
359      (columnOf.get(a.x) ?? 0) - (columnOf.get(b.x) ?? 0) ||
360      (rowOf.get(a.series) ?? 0) - (rowOf.get(b.series) ?? 0),
361  );
362
363  const describe = (p: BarPoint): string =>
364    series === undefined
365      ? `${categoryLabel ?? x} ${p.x}: ${format(p.value)}`
366      : `${categoryLabel ?? x} ${p.x}, ${p.series}: ${format(p.value)}`;
367  const datum = (p: BarPoint): MarkDatum => ({
368    key: markKey(p.x, p.series),
369    filter:
370      series === undefined || options.filterBy === "x"
371        ? { field: x, value: p.x }
372        : { field: series, value: p.series },
373    x: p.x,
374    ...(series === undefined ? {} : { series: p.series }),
375    column: columnOf.get(p.x) ?? 0,
376    row: rowOf.get(p.series) ?? 0,
377  });
378  const linkOf = options.href;
379
380  const longest = Math.max(maxOf(xNames.map((n) => n.length)), 1);
381  const width = options.width ?? DEFAULT_WIDTH;
382  const height =
383    options.height ?? (horizontal ? Math.max(120, xNames.length * 28 + 60) : DEFAULT_HEIGHT);
384  // A time axis has many bars and long labels, so it thins them to fit unless told otherwise.
385  const fit = time ? Math.max(2, Math.floor((width - 80) / (longest * 7 + 12))) : undefined;
386  const thinned = thinTicks(xNames, options.maxXTicks ?? fit);
387
388  const rows = xNames.map((name) => [
389    name,
390    ...seriesNames.map((s) => {
391      const cell = cells.get(markKey(name, s));
392      return cell ? format(cell.value) : y === undefined ? format(0) : "";
393    }),
394  ]);
395
396  return {
397    points,
398    xNames,
399    seriesNames,
400    plan,
401    horizontal,
402    grouped,
403    directLabels: options.directLabels === true && series !== undefined,
404    categoryLabel,
405    valueLabel,
406    format,
407    width,
408    height,
409    marginLeft: horizontal ? Math.min(220, longest * 7 + 16) : valueLabel === null ? 44 : 60,
410    thinned,
411    countTicks: y === undefined ? countTicks(points, grouped) : undefined,
412    describe,
413    datum,
414    link: linkOf ? (p) => safeHref(linkOf(p.x)) : undefined,
415    figure: (svg) =>
416      figure(options, {
417        kind: "bar",
418        svg,
419        orientation: horizontal ? "horizontal" : "vertical",
420        legend: series === undefined ? [] : plan.legend,
421        ...(series === undefined ? {} : { seriesField: series }),
422        slotColors: plan.slotColors,
423        table: {
424          columns: [
425            categoryLabel ?? x,
426            ...(series === undefined ? [valueLabel ?? "Value"] : seriesNames),
427          ],
428          rows,
429        },
430      }),
431  };
432}
433
434/** A name fits in a segment when the segment is this much taller and wider than the text. */
435const LABEL_HEIGHT = 16;
436const CHAR_WIDTH = 6.6;
437
438/**
439 * Whether a series name fits inside a stacked segment of the given size, for `directLabels`.
440 * Both renderers decide with this, from the drawn geometry.
441 */
442export function labelFits(name: string, width: number, height: number): boolean {
443  return height >= LABEL_HEIGHT && width >= name.length * CHAR_WIDTH + 8;
444}