src/plot/bar.ts

Functions

Imports

It imports src/render/bar-model.ts, src/render/plot.ts. Imported by src/plot/index.ts.

Source

1import * as Plot from "@observablehq/plot";
2import { type BarChartOptions, type BarPoint, barModel, labelFits } from "../render/bar-model.js";
3import { keyed, renderPlot } from "../render/plot.js";
4
5export type { BarChartOptions } from "../render/bar-model.js";
6
7/**
8 * A bar chart, drawn on the server: one series, or several stacked or grouped. Negative values
9 * stack below zero. Each bar carries hover details and, once enhanced, filters by its series (or
10 * its category when there is one series).
11 *
12 * @example
13 * barChart({
14 *   data: [{ year: 2023, type: "Publications" }, { year: 2024, type: "Talks" }],
15 *   x: "year",
16 *   series: "type",
17 *   alt: "Entries per year by type, 2023 to 2024.",
18 * });
19 */
20export function barChart<T extends object>(options: BarChartOptions<T>): string {
21  const model = barModel(options);
22  const { points, xNames, seriesNames, horizontal, grouped, thinned, categoryLabel } = model;
23
24  const render = keyed(
25    points,
26    model.datum,
27    // A link is read on its own, so it carries its own name.
28    options.href ? (el, p) => el.setAttribute("aria-label", model.describe(p)) : undefined,
29  );
30
31  const link = model.link;
32  const common = {
33    fill: "series",
34    title: model.describe,
35    render,
36    ...(link ? { href: (p: BarPoint) => link(p) } : {}),
37  };
38  const order = { order: [...seriesNames] };
39  let bar: Plot.Markish;
40  if (horizontal) {
41    bar = grouped
42      ? Plot.barX(points, { ...common, x: "value", y: "series", fy: "x" })
43      : Plot.barX(points, Plot.stackX({ ...common, ...order, x: "value", y: "x" }));
44  } else {
45    bar = grouped
46      ? Plot.barY(points, { ...common, y: "value", x: "series", fx: "x" })
47      : Plot.barY(points, Plot.stackY({ ...common, ...order, y: "value", x: "x" }));
48  }
49
50  const categoryScale = {
51    domain: grouped ? seriesNames : xNames,
52    label: grouped ? null : categoryLabel,
53    padding: grouped ? 0.05 : 0.2,
54    ...(grouped ? { axis: null } : thinned ? { ticks: thinned } : {}),
55  };
56  const facetScale = {
57    domain: xNames,
58    label: categoryLabel,
59    padding: 0.15,
60    axis: horizontal ? "left" : "bottom",
61    ...(thinned ? { ticks: thinned } : {}),
62  } as const;
63  const ticks = model.countTicks;
64  const valueScale = {
65    label: model.valueLabel,
66    labelArrow: "none",
67    labelAnchor: "center",
68    grid: true,
69    zero: true,
70    // Counts are whole numbers, so their axis never shows 0.5, and the axis ends at the last
71    // tick so no tick is drawn past the plot (A2).
72    ...(ticks
73      ? {
74          ticks,
75          tickFormat: model.format,
76          domain: [0, ticks[ticks.length - 1] ?? 1],
77          nice: false,
78        }
79      : { nice: true }),
80  } as const;
81
82  const { svg } = renderPlot(
83    {
84      width: model.width,
85      height: model.height,
86      marginTop: 20,
87      marginLeft: model.marginLeft,
88      marginBottom: 44,
89      ...(horizontal
90        ? {
91            y: { ...categoryScale, type: "band" },
92            x: valueScale,
93            ...(grouped ? { fy: facetScale } : {}),
94          }
95        : {
96            x: { ...categoryScale, type: "band" },
97            y: valueScale,
98            ...(grouped ? { fx: facetScale } : {}),
99          }),
100      color: { domain: seriesNames, range: [...model.plan.range] },
101      marks: [bar, horizontal ? Plot.ruleX([0]) : Plot.ruleY([0])],
102    },
103    options.alt,
104    options.href ? "group" : "img",
105    model.directLabels ? (svg) => labelSegments(svg) : undefined,
106  );
107
108  return model.figure(svg);
109}
110
111/**
112 * Writes each series' name inside the stacked segments it fits in, in the color chosen for text
113 * on that series. Drawn after Plot lays out the bars, from their final geometry.
114 */
115function labelSegments(svg: SVGSVGElement): void {
116  const group = svg.querySelector('[data-enarratio-mark="bar"]');
117  if (!group) return;
118  const document = svg.ownerDocument;
119  const labels = document.createElementNS("http://www.w3.org/2000/svg", "g");
120  labels.setAttribute("data-enarratio-mark", "bar label");
121  labels.setAttribute("aria-hidden", "true");
122  // Labels sit on the bars they name; pointer events go through them to the bar.
123  labels.setAttribute("pointer-events", "none");
124  labels.setAttribute("text-anchor", "middle");
125  labels.setAttribute("font-size", "11");
126  for (const mark of group.querySelectorAll("[data-enarratio-key]")) {
127    const shape = mark.localName === "rect" ? mark : mark.querySelector("rect");
128    const name = mark.getAttribute("data-enarratio-series");
129    const fill = shape?.getAttribute("fill") ?? "";
130    const slot = /--enarratio-series-(\d)/.exec(fill)?.[1];
131    if (!shape || !name || !slot) continue;
132    const [bx, by, bw, bh] = ["x", "y", "width", "height"].map((a) =>
133      Number(shape.getAttribute(a)),
134    ) as [number, number, number, number];
135    if (!labelFits(name, bw, bh)) continue;
136    const text = document.createElementNS("http://www.w3.org/2000/svg", "text");
137    text.setAttribute("x", String(bx + bw / 2));
138    text.setAttribute("y", String(by + bh / 2));
139    text.setAttribute("dy", "0.35em");
140    text.setAttribute("fill", `var(--enarratio-series-text-${slot})`);
141    text.textContent = name;
142    labels.append(text);
143  }
144  group.after(labels);
145}