src/lite/axis.ts

Functions

Imports

It imports src/lite/svg.ts. Imported by src/lite/bar.ts, src/lite/series.ts.

Source

1/** Axes and grids drawn as Plot draws them: the same groups, positions and offsets. */
2
3import { type Attrs, el, type FacetContent, markGroup, textElement, translate } from "./svg.js";
4
5/** The drawing area: the SVG's size and the margins around the plotted frame. */
6export interface Frame {
7  readonly width: number;
8  readonly height: number;
9  readonly marginTop: number;
10  readonly marginRight: number;
11  readonly marginBottom: number;
12  readonly marginLeft: number;
13}
14
15/** A tick: where it is, and its label (empty for none). */
16export interface Tick {
17  readonly at: number;
18  readonly label: string;
19}
20
21/** Where a mark is drawn: once, or once per facet with its offset. */
22export type Placement = undefined | readonly { readonly dx: number; readonly dy: number }[];
23
24const HIDDEN = { "aria-hidden": "true" } as const;
25
26function place(placement: Placement, children: string): string | FacetContent[] {
27  return placement ? placement.map((p) => ({ ...p, children })) : children;
28}
29
30/** Light lines across the frame at each tick: horizontal for y, vertical for x. */
31export function grid(
32  k: "x" | "y",
33  at: readonly number[],
34  frame: Frame,
35  placement?: Placement,
36): string {
37  if (at.length === 0) return "";
38  const { width, height, marginTop, marginRight, marginBottom, marginLeft } = frame;
39  const lines = at
40    .map((p) =>
41      k === "y"
42        ? el("line", { x1: marginLeft, x2: width - marginRight, y1: p, y2: p })
43        : el("line", { x1: p, x2: p, y1: marginTop, y2: height - marginBottom }),
44    )
45    .join("");
46  return markGroup(
47    { ...HIDDEN, "data-enarratio-mark": `${k}-grid` },
48    { stroke: "currentColor", "stroke-opacity": "0.1" },
49    place(placement, lines),
50  );
51}
52
53/**
54 * Tick marks on the left (y) or bottom (x) of the frame. `offset` moves them to the middle of a
55 * band, for categories.
56 */
57export function axisTicks(
58  k: "x" | "y",
59  at: readonly number[],
60  frame: Frame,
61  offset = 0,
62  placement?: Placement,
63): string {
64  if (at.length === 0) return "";
65  const paths = at
66    .map((p) =>
67      k === "y"
68        ? el("path", { transform: translate(frame.marginLeft, p), d: "M0,0L-6,0" })
69        : el("path", { transform: translate(p, frame.height - frame.marginBottom), d: "M0,0L0,6" }),
70    )
71    .join("");
72  return markGroup(
73    {
74      ...HIDDEN,
75      "data-enarratio-mark": `${k}-axis tick`,
76      transform: offset ? (k === "y" ? translate(0, offset) : translate(offset, 0)) : undefined,
77    },
78    { fill: "none", stroke: "currentColor" },
79    place(placement, paths),
80  );
81}
82
83/**
84 * Tick labels beside the ticks. `padding` is the gap from the frame: 9 beside a tick mark, as
85 * on value and category axes. `tabular` sets tabular figures, for numbers and dates.
86 */
87export function axisTickLabels(
88  k: "x" | "y" | "fx" | "fy",
89  ticks: readonly Tick[],
90  frame: Frame,
91  options: { offset?: number; tabular?: boolean; placement?: Placement } = {},
92): string {
93  const vertical = k === "y" || k === "fy";
94  const label = (t: Tick): string =>
95    vertical
96      ? textElement({ transform: translate(frame.marginLeft, t.at) }, t.label, "middle")
97      : textElement(
98          { transform: translate(t.at, frame.height - frame.marginBottom) },
99          t.label,
100          "top",
101        );
102  const offset = options.offset ?? 0;
103  const outer: Attrs = {
104    ...HIDDEN,
105    "data-enarratio-mark": `${k}-axis tick label`,
106    transform: vertical ? translate(-9, offset) : translate(offset, 9),
107  };
108  const styles: Attrs = {
109    "font-variant": options.tabular ? "tabular-nums" : undefined,
110    "text-anchor": vertical ? "end" : undefined,
111  };
112  // A tick without a label (between powers of ten on a log axis) still gets an empty text.
113  const children = ticks.map(label).join("");
114  if (children === "") return "";
115  return markGroup(outer, styles, place(options.placement, children));
116}
117
118/**
119 * The labels of a facet axis: each facet's name, centered on its frame, in the facets that are
120 * drawn. `facets` gives each facet's offset and the label it carries, if any.
121 */
122export function facetTickLabels(
123  k: "fx" | "fy",
124  facets: readonly { readonly dx: number; readonly dy: number; readonly label?: string }[],
125  frame: Frame,
126): string {
127  const { width, height, marginTop, marginRight, marginBottom, marginLeft } = frame;
128  const content: FacetContent[] = [];
129  for (const f of facets) {
130    if (f.label === undefined) continue;
131    const children =
132      k === "fx"
133        ? textElement(
134            { transform: translate((marginLeft + width - marginRight) / 2, height - marginBottom) },
135            f.label,
136            "top",
137          )
138        : textElement(
139            { transform: translate(marginLeft, (marginTop + height - marginBottom) / 2) },
140            f.label,
141            "middle",
142          );
143    content.push({ dx: f.dx, dy: f.dy, children });
144  }
145  if (content.length === 0) return "";
146  return markGroup(
147    {
148      ...HIDDEN,
149      "data-enarratio-mark": `${k}-axis tick label`,
150      transform: k === "fx" ? translate(0, 9) : translate(-9, 0),
151    },
152    { "text-anchor": k === "fy" ? "end" : undefined },
153    content,
154  );
155}
156
157/**
158 * An axis label: centered below the frame for x, or rotated and centered beside it for y. The
159 * position comes from `frame`; the offset from `inset`, the margins as given.
160 */
161export function axisLabel(
162  k: "x" | "y" | "fx" | "fy",
163  label: string | null,
164  frame: Frame,
165  inset: Frame = frame,
166): string {
167  // An empty label is still drawn, as Plot draws it; only null hides it.
168  if (label === null) return "";
169  const { width, height, marginTop, marginRight, marginBottom, marginLeft } = frame;
170  const horizontal = k === "x" || k === "fx";
171  const node = horizontal
172    ? textElement(
173        { transform: translate((marginLeft + width - marginRight) / 2, height - marginBottom) },
174        label,
175        "bottom",
176      )
177    : textElement(
178        {
179          transform: `${translate(marginLeft, (marginTop + height - marginBottom) / 2)} rotate(-90)`,
180        },
181        label,
182        "top",
183      );
184  return el(
185    "g",
186    {
187      ...HIDDEN,
188      "data-enarratio-mark": `${k}-axis label`,
189      transform: horizontal
190        ? translate(0, inset.marginBottom - 3)
191        : translate(-(inset.marginLeft - 3), 0),
192    },
193    node,
194  );
195}