src/lite/bar.ts

Functions

Imports

It imports src/lite/axis.ts, src/lite/scale.ts, src/lite/svg.ts, src/render/bar-model.ts, src/render/data.ts, src/render/datum.ts. Imported by src/lite/index.ts.

Source

1/**
2 * `enarratio/lite/bar`: {@link barChart} without Observable Plot or a DOM, for browser bundles.
3 * The same options draw the same SVG as `barChart` from `enarratio/plot`.
4 *
5 * @packageDocumentation
6 */
7
8import {
9  type BarChartOptions,
10  type BarModel,
11  type BarPoint,
12  barModel,
13  labelFits,
14} from "../render/bar-model.js";
15import { markKey } from "../render/data.js";
16import { datumAttributes } from "../render/datum.js";
17import {
18  axisLabel,
19  axisTickLabels,
20  axisTicks,
21  type Frame,
22  facetTickLabels,
23  grid,
24  type Placement,
25  type Tick,
26} from "./axis.js";
27import {
28  band,
29  type Continuous,
30  continuous,
31  linearTickFormat,
32  ticks as linearTicks,
33  niceLinear,
34} from "./scale.js";
35import { el, markGroup, svgRoot, text } from "./svg.js";
36
37interface Box {
38  readonly x: number;
39  readonly y: number;
40  readonly width: number;
41  readonly height: number;
42}
43
44export type { BarChartOptions } from "../render/bar-model.js";
45
46const MARGIN_TOP = 20;
47const MARGIN_RIGHT = 20;
48const MARGIN_BOTTOM = 44;
49
50/** Each bar's extent along the value axis, stacked as Plot stacks it. */
51function stack(model: BarModel): Map<BarPoint, [number, number]> {
52  const out = new Map<BarPoint, [number, number]>();
53  const totals = new Map<string, { pos: number; neg: number }>();
54  for (const p of model.points) {
55    // Grouped bars each start at zero; stacked ones continue their category's stack.
56    const id = model.grouped ? markKey(p.x, p.series) : p.x;
57    const total = totals.get(id) ?? { pos: 0, neg: 0 };
58    totals.set(id, total);
59    const v = p.value;
60    if (v < 0) {
61      out.set(p, [total.neg, total.neg + v]);
62      total.neg += v;
63    } else if (v > 0) {
64      out.set(p, [total.pos, total.pos + v]);
65      total.pos += v;
66    } else out.set(p, [total.pos, total.pos]);
67  }
68  return out;
69}
70
71/**
72 * A bar chart, drawn without Observable Plot: one series, or several stacked or grouped. The same
73 * options and output as `barChart` from `enarratio/plot`, in a bundle small enough for a browser.
74 *
75 * @example
76 * barChart({
77 *   data: [{ year: 2023, type: "Publications" }, { year: 2024, type: "Talks" }],
78 *   x: "year",
79 *   series: "type",
80 *   alt: "Entries per year by type, 2023 to 2024.",
81 * });
82 */
83export function barChart<T extends object>(options: BarChartOptions<T>): string {
84  const model = barModel(options);
85  return model.figure(drawBars(model, options));
86}
87
88function drawBars<T extends object>(model: BarModel, options: BarChartOptions<T>): string {
89  const { width, height, horizontal, grouped, xNames, seriesNames, points } = model;
90  const frame: Frame = {
91    width,
92    height,
93    marginTop: MARGIN_TOP,
94    marginRight: MARGIN_RIGHT,
95    marginBottom: MARGIN_BOTTOM,
96    marginLeft: model.marginLeft,
97  };
98  const extents = stack(model);
99
100  // The value scale: the stacks' extent and zero, made round, or the count ticks as given.
101  let lo = 0;
102  let hi = 0;
103  for (const [a, b] of extents.values()) {
104    lo = Math.min(lo, a, b);
105    hi = Math.max(hi, a, b);
106  }
107  const counts = model.countTicks;
108  const domain: [number, number] = counts
109    ? [0, counts[counts.length - 1] ?? 1]
110    : (niceLinear([lo, hi]) as [number, number]);
111  const valueRange: [number, number] = horizontal
112    ? [frame.marginLeft, width - frame.marginRight]
113    : [height - frame.marginBottom, frame.marginTop];
114  const value: Continuous = continuous("linear", domain, valueRange);
115  const tickCount = horizontal
116    ? (valueRange[1] - valueRange[0]) / 80
117    : (valueRange[0] - valueRange[1]) / 35;
118  const valueTicks: Tick[] = counts
119    ? counts.map((t) => ({ at: value(t), label: model.format(t) }))
120    : (() => {
121        const format = linearTickFormat(domain, tickCount);
122        return linearTicks(domain[0], domain[1], tickCount).map((t) => ({
123          at: value(t),
124          label: format(t),
125        }));
126      })();
127
128  // The category scale, and for grouped bars the facets, one per category.
129  const categoryRange: [number, number] = horizontal
130    ? [frame.marginTop, height - frame.marginBottom]
131    : [frame.marginLeft, width - frame.marginRight];
132  const facetBand = grouped ? band(xNames.length, categoryRange, 0.15, 0) : undefined;
133  let inner = frame;
134  if (facetBand) {
135    inner = horizontal
136      ? { ...frame, height: facetBand.bandwidth + frame.marginTop + frame.marginBottom }
137      : { ...frame, width: facetBand.bandwidth + frame.marginLeft + frame.marginRight };
138  }
139  const innerRange: [number, number] = horizontal
140    ? [inner.marginTop, inner.height - inner.marginBottom]
141    : [inner.marginLeft, inner.width - inner.marginRight];
142  const category = grouped
143    ? band(seriesNames.length, innerRange, 0.05, 0.05)
144    : band(xNames.length, innerRange, 0.2, 0.2);
145  const columnOf = new Map(xNames.map((name, i) => [name, i]));
146  const rowOf = new Map(seriesNames.map((name, i) => [name, i]));
147
148  // Facets in category order; a category without bars is an empty facet, drawn without marks.
149  const byCategory = new Map<string, BarPoint[]>();
150  if (facetBand) {
151    for (const p of points) {
152      const list = byCategory.get(p.x);
153      if (list) list.push(p);
154      else byCategory.set(p.x, [p]);
155    }
156  }
157  const facets = facetBand
158    ? xNames.map((name, i) => {
159        const at = facetBand.at(i);
160        return {
161          name,
162          dx: horizontal ? 0 : at - frame.marginLeft,
163          dy: horizontal ? at - frame.marginTop : 0,
164          points: byCategory.get(name) ?? [],
165        };
166      })
167    : undefined;
168  const drawn = facets?.filter((f) => f.points.length > 0);
169  const outer: Frame | undefined = facetBand
170    ? (() => {
171        const first = facetBand.at(0);
172        const last = facetBand.at(xNames.length - 1) + facetBand.bandwidth;
173        return horizontal
174          ? { ...frame, marginTop: first, marginBottom: height - last }
175          : { ...frame, marginLeft: first, marginRight: width - last };
176      })()
177    : undefined;
178
179  const parts: string[] = [];
180  const thinned = model.thinned ? new Set(model.thinned) : undefined;
181  const label = model.categoryLabel;
182  const valueAt = valueTicks.map((t) => t.at);
183
184  if (facets && outer) {
185    const k = horizontal ? "fy" : "fx";
186    parts.push(
187      facetTickLabels(
188        k,
189        facets.map((f) => ({
190          dx: f.dx,
191          dy: f.dy,
192          ...(thinned && !thinned.has(f.name) ? {} : { label: f.name }),
193        })),
194        inner,
195      ),
196      axisLabel(k, label, outer),
197    );
198  }
199
200  const categoryAxis = (k: "x" | "y"): void => {
201    const ticks = xNames
202      .map((name, i) => ({ at: category.at(i), label: name }))
203      .filter((t) => !thinned || thinned.has(t.label));
204    const offset = category.bandwidth / 2;
205    parts.push(
206      axisTicks(
207        k,
208        ticks.map((t) => t.at),
209        frame,
210        offset,
211      ),
212      axisTickLabels(k, ticks, frame, { offset }),
213      axisLabel(k, label, frame),
214    );
215  };
216  const valueAxis = (k: "x" | "y", placement: Placement): void => {
217    parts.push(
218      grid(k, valueAt, inner, drawn),
219      axisTicks(k, valueAt, inner, 0, placement),
220      axisTickLabels(k, valueTicks, inner, { tabular: true, placement }),
221      axisLabel(k, model.valueLabel, outer ?? frame, frame),
222    );
223  };
224  if (horizontal) {
225    if (!grouped) categoryAxis("y");
226    // A faceted axis is drawn in the facets with nothing beyond them: below, for x.
227    valueAxis(
228      "x",
229      facets?.filter((f, i) => f.points.length > 0 && !(facets[i + 1]?.points.length ?? 0)),
230    );
231  } else {
232    // ... and to the left, for y.
233    valueAxis(
234      "y",
235      facets?.filter((f, i) => f.points.length > 0 && !(facets[i - 1]?.points.length ?? 0)),
236    );
237    if (!grouped) categoryAxis("x");
238  }
239
240  // The bars, each its stack's extent across its slot.
241  const boxes = new Map(
242    points.map((p) => {
243      const [a, b] = extents.get(p) as [number, number];
244      const start = category.at(grouped ? (rowOf.get(p.series) ?? 0) : (columnOf.get(p.x) ?? 0));
245      const v1 = value(a);
246      const v2 = value(b);
247      const box: Box = horizontal
248        ? { x: Math.min(v1, v2), width: Math.abs(v1 - v2), y: start, height: category.bandwidth }
249        : { x: start, width: category.bandwidth, y: Math.min(v1, v2), height: Math.abs(v1 - v2) };
250      return [p, box];
251    }),
252  );
253  const barMarkup = (list: readonly BarPoint[]): string =>
254    list
255      .map((p) => {
256        const box = boxes.get(p) as Box;
257        const keys = Object.fromEntries(datumAttributes(model.datum(p)));
258        const shape = { ...box, fill: model.plan.range[rowOf.get(p.series) ?? 0] };
259        const title = el("title", {}, text(model.describe(p)));
260        // A link is read on its own, so it carries its own name.
261        return model.link
262          ? el(
263              "a",
264              { href: model.link(p), fill: "inherit", ...keys, "aria-label": model.describe(p) },
265              el("rect", shape, title),
266            )
267          : el("rect", { ...shape, ...keys }, title);
268      })
269      .join("");
270  parts.push(
271    markGroup(
272      { "data-enarratio-mark": "bar" },
273      {},
274      drawn
275        ? drawn.map((f) => ({ dx: f.dx, dy: f.dy, children: barMarkup(f.points) }))
276        : barMarkup(points),
277    ),
278  );
279
280  if (model.directLabels) {
281    // Each series' name inside the stacked segments it fits in, in the color for text on it.
282    const labels = points
283      .map((p) => {
284        const box = boxes.get(p) as Box;
285        if (!labelFits(p.series, box.width, box.height)) return "";
286        return el(
287          "text",
288          {
289            x: box.x + box.width / 2,
290            y: box.y + box.height / 2,
291            dy: "0.35em",
292            fill: `var(--enarratio-series-text-${(rowOf.get(p.series) ?? 0) + 1})`,
293          },
294          text(p.series),
295        );
296      })
297      .join("");
298    parts.push(
299      el(
300        "g",
301        {
302          "data-enarratio-mark": "bar label",
303          "aria-hidden": "true",
304          // Labels sit on the bars they name; pointer events go through them to the bar.
305          "pointer-events": "none",
306          "text-anchor": "middle",
307          "font-size": "11",
308        },
309        labels,
310      ),
311    );
312  }
313
314  // The rule at zero, across the frame (in each drawn facet).
315  const zero = value(0);
316  const rule = horizontal
317    ? el("line", { x1: zero, x2: zero, y1: inner.marginTop, y2: inner.height - inner.marginBottom })
318    : el("line", { x1: inner.marginLeft, x2: inner.width - inner.marginRight, y1: zero, y2: zero });
319  parts.push(
320    markGroup(
321      { "data-enarratio-mark": "rule" },
322      { stroke: "currentColor" },
323      drawn ? drawn.map((f) => ({ dx: f.dx, dy: f.dy, children: rule })) : rule,
324    ),
325  );
326
327  return svgRoot(width, height, options.alt, options.href ? "group" : "img", parts.join(""));
328}