src/primitives/progress-ring.ts

Functions

Imports

It imports src/html.ts, src/primitives/companion.ts, src/render/figure.ts. Imported by src/index.ts.

Source

1import { element, escapeHtml } from "../html.js";
2import { type SeriesColor, slotStyle } from "../render/figure.js";
3import { type PrimitiveTable, type PrimitiveTableOptions, primitiveTable } from "./companion.js";
4
5/** Options for {@link progressRing}. */
6export interface ProgressRingOptions {
7  /** Progress so far, from 0 to `max`. */
8  readonly value: number;
9  /** The value that fills the ring (default 1). */
10  readonly max?: number;
11  /**
12   * What is progressing, e.g. "Chapters drafted"; it starts the generated text alternative.
13   * Required unless `alt` is given.
14   */
15  readonly label?: string;
16  /** The text alternative, instead of the one generated from `label` and the values (F18). */
17  readonly alt?: string;
18  /** The ring's outer diameter in CSS pixels (default 40). */
19  readonly size?: number;
20  /** The ring's stroke width (default size / 8). */
21  readonly thickness?: number;
22  /** Print the percentage in the middle (default true when size is 36 or more). */
23  readonly showValue?: boolean;
24  /** The ring's color; defaults to the theme's first series color. */
25  readonly color?: SeriesColor;
26}
27
28const round = (n: number): number => Math.round(n * 100) / 100;
29
30/** Everything the ring, its text alternative and its companion table are computed from. */
31interface ProgressRingValues {
32  readonly value: number;
33  readonly max: number;
34  /** The share of the ring filled, from 0 to 1 (a value past `max` fills it). */
35  readonly fraction: number;
36  /** The real percentage, which may pass 100. */
37  readonly percent: number;
38  readonly size: number;
39  readonly thickness: number;
40  readonly subject: string;
41  /** The sentence generated from the label and values, or "" when only `alt` names the ring. */
42  readonly summary: string;
43  readonly alt: string;
44}
45
46/** Validates the options and computes the numbers every part of a progress ring is made from. */
47function prepareProgressRing(options: ProgressRingOptions): ProgressRingValues {
48  const max = options.max ?? 1;
49  const { value } = options;
50  if (!Number.isFinite(max) || max <= 0)
51    throw new Error(`progressRing: max must be above zero, is ${max}`);
52  if (!Number.isFinite(value) || value < 0) {
53    throw new Error(`progressRing: value must be zero or more, is ${value}`);
54  }
55  const subject = options.label?.trim() ?? "";
56  const given = options.alt?.trim() ?? "";
57  if (subject === "" && given === "") throw new Error("progressRing: label or alt is required");
58  const size = options.size ?? 40;
59  const thickness = options.thickness ?? size / 8;
60  for (const [name, n] of [
61    ["size", size],
62    ["thickness", thickness],
63  ] as const) {
64    if (!(Number.isFinite(n) && n > 0)) {
65      throw new Error(`progressRing: ${name} must be a positive number, is ${n}`);
66    }
67  }
68  if (thickness >= size) throw new Error("progressRing: thickness must be less than size");
69  // The ring can only be full, but the number says how far past the total the value is (A7).
70  const fraction = Math.min(1, value / max);
71  const percent = Math.round((value / max) * 100);
72  const over = value > max ? ", more than the total" : "";
73  const summary =
74    subject === ""
75      ? ""
76      : max === 1
77        ? `${subject}: ${percent}%${over}`
78        : `${subject}: ${value} of ${max} (${percent}%${over})`;
79  return {
80    value,
81    max,
82    fraction,
83    percent,
84    size,
85    thickness,
86    subject,
87    summary,
88    alt: given || summary,
89  };
90}
91
92/**
93 * A ring that fills clockwise from the top to show progress toward a total, with the percentage
94 * in the middle. Its text alternative states the label, the value and the total.
95 *
96 * @example
97 * progressRing({ value: 7, max: 12, label: "Chapters drafted" });
98 */
99export function progressRing(options: ProgressRingOptions): string {
100  const { fraction, percent, size, thickness, alt } = prepareProgressRing(options);
101  const radius = (size - thickness) / 2;
102  const circumference = 2 * Math.PI * radius;
103  const c = size / 2;
104  const showValue = options.showValue ?? size >= 36;
105
106  return element(
107    "svg",
108    {
109      class: "enarratio enarratio-progress-ring",
110      "data-enarratio": "progress-ring",
111      xmlns: "http://www.w3.org/2000/svg",
112      viewBox: `0 0 ${size} ${size}`,
113      width: size,
114      height: size,
115      role: "img",
116      "aria-label": alt,
117      style: slotStyle(options.color ? new Map([[1, options.color]]) : undefined),
118    },
119    [
120      element("title", {}, escapeHtml(alt)),
121      element("circle", {
122        cx: c,
123        cy: c,
124        r: round(radius),
125        fill: "none",
126        stroke: "var(--enarratio-grid)",
127        "stroke-width": round(thickness),
128      }),
129      fraction > 0
130        ? element("circle", {
131            cx: c,
132            cy: c,
133            r: round(radius),
134            fill: "none",
135            stroke: "var(--enarratio-series-1)",
136            "stroke-width": round(thickness),
137            "stroke-linecap": fraction < 1 ? "round" : "butt",
138            "stroke-dasharray": `${round(circumference * fraction)} ${round(circumference)}`,
139            transform: `rotate(-90 ${c} ${c})`,
140          })
141        : "",
142      showValue
143        ? element(
144            "text",
145            {
146              x: c,
147              y: c,
148              "text-anchor": "middle",
149              "dominant-baseline": "central",
150              fill: "var(--enarratio-text)",
151              "font-size": round(size * 0.28),
152              class: "enarratio-numeric",
153            },
154            `${percent}%`,
155          )
156        : "",
157    ].join(""),
158  );
159}
160
161/**
162 * A progress ring's numbers as a table (value, total and percentage) and a summary sentence,
163 * computed from the same values as the ring so the two cannot disagree. Takes the same options as
164 * {@link progressRing}. Without `label` the summary is the given `alt`.
165 *
166 * @example
167 * const { summary } = progressRingTable({ value: 7, max: 12, label: "Chapters drafted" });
168 */
169export function progressRingTable(
170  options: ProgressRingOptions,
171  display?: PrimitiveTableOptions,
172): PrimitiveTable {
173  const p = prepareProgressRing(options);
174  return primitiveTable(
175    p.summary || p.alt,
176    {
177      columns: ["Measure", "Value", "Total", "Percent"],
178      rows: [[p.subject || "Progress", String(p.value), String(p.max), `${p.percent}%`]],
179    },
180    p.subject || p.alt,
181    display,
182  );
183}