app/lib/cv/charts.ts

Functions

Imports

It imports app/lib/cv/view.mjs. Imported by app/lib/cv/render-charts.ts.

Source

1/**
2 * THE CV'S CHARTS, behind one small interface: the stacked timeline of output per year and the three
3 * headline sparklines, drawn by Enarratio (the site's charts package, built on Observable Plot). The
4 * route renders them into the page, so they are in the HTML with script off, and /cv/charts.json
5 * renders them again for app/enhance/cv.ts when a filter changes. Both get markup back.
6 *
7 * Enarratio's stylesheet is app/styles/enarratio.css (scripts/build-chart-css.mjs), because the public
8 * policy allows no inline <style>. With script off each bar is a link to its year's filtered page;
9 * its enhancement layer (enarratio/enhance) turns the bars into keyboard filter buttons and reports a
10 * selection as an `enarratio:select` event, which app/enhance/cv.ts turns into a year range.
11 */
12
13import { sparkline } from "enarratio";
14import { barChart } from "enarratio/plot";
15
16import { TIMELINE_ID } from "./view.mjs";
17
18type TimelineSeries = { key: string; label: string; token: string; values: number[] };
19
20export type TimelineInput = {
21  years: number[];
22  series: TimelineSeries[];
23  /** The year range the filters select, drawn at full strength; the rest is faded. Null: all. */
24  selected: [number, number] | null;
25  /** The chart's accessible name. */
26  label: string;
27  /** Where a bar links with script off: the page filtered to that year. */
28  hrefForYear: (year: number) => string;
29  /** What to say when there is nothing to chart (see timelineEmptyText); the chart is not drawn then. */
30  emptyText?: string | null;
31  /** Drawing width in CSS pixels; the browser passes its container's, so type is drawn at size. */
32  width?: number;
33};
34
35export type SparklineInput = {
36  years: number[];
37  values: number[];
38  selected: [number, number] | null;
39  label: string;
40};
41
42const TIMELINE = { width: 640, height: 220 };
43
44const NOTHING_TO_CHART = "There is nothing to chart for these filters.";
45
46/**
47 * The timeline's place when nothing is charted: one plain sentence in the page's note style, marked so
48 * app/enhance/cv.ts knows no Enarratio figure is there. The text is ours, never a visitor's, so it is not escaped.
49 */
50const EMPTY_TIMELINE_ATTR = "data-cv-timeline-empty";
51function emptyTimeline(text: string): string {
52  return `<p class="cv-timeline-hint" ${EMPTY_TIMELINE_ATTR}="">${text}</p>`;
53}
54
55/**
56 * One row per counted entry, which is the shape Enarratio counts. The bars outside the selected range
57 * are marked with an attribute for the stylesheet to fade, found by the year Enarratio writes on each
58 * bar as `data-enarratio-x`. Its `data-enarratio-key` is opaque JSON.
59 */
60export function timelineSvg(input: TimelineInput): string {
61  const { years, series, selected } = input;
62  const rows = series.flatMap((s) =>
63    years.flatMap((year, i) => Array.from({ length: s.values[i] ?? 0 }, () => ({ year, type: s.label }))),
64  );
65  // Enarratio throws "data is empty" for no rows, which would be a 500 for a filter that selects nothing chartable.
66  if (rows.length === 0) return emptyTimeline(input.emptyText ?? NOTHING_TO_CHART);
67  const width = Math.max(280, Math.round(input.width ?? TIMELINE.width));
68  const markup = barChart({
69    id: TIMELINE_ID,
70    data: rows,
71    x: "year",
72    series: "type",
73    filterBy: "x",
74    href: (year) => input.hrefForYear(Number(year)),
75    // Every year where there is room, every other year on a laptop, every fifth on a phone.
76    maxXTicks: width < 520 ? 5 : width < 1000 ? 11 : years.length,
77    xDomain: years,
78    seriesDomain: series.map((s) => s.label),
79    colors: Object.fromEntries(series.map((s) => [s.label, s.token])),
80    xLabel: null,
81    yLabel: null,
82    alt: input.label,
83    width,
84    height: TIMELINE.height,
85  });
86  return fadeOutside(markup, selected);
87}
88
89/**
90 * A range wider than one year fades the bars outside it. One year is Enarratio's own filter, shown by
91 * the enhancement with setFilter, so the two dimmings never stack.
92 */
93function fadeOutside(markup: string, selected: [number, number] | null) {
94  if (!selected || selected[0] === selected[1]) return markup;
95  return markup.replace(/data-enarratio-x="(\d{4})"/g, (match, year: string) =>
96    Number(year) < selected[0] || Number(year) > selected[1] ? `data-cv-out="" ${match}` : match,
97  );
98}
99
100/** A line of per-year values; the number beside it carries the value. */
101export function sparklineSvg(input: SparklineInput): string {
102  return sparkline({ values: input.values, alt: input.label, area: true, color: "var(--brand)" });
103}