components/meter/meter.ts

Functions

Imports

It imports no other module of this repo. Imported by components/media/media-tile.ts, components/media/media.ts, components/meter/meter.react.tsx, components/usage-meter/usage-meter.ts.

Source

1// The meter's behaviour: where the fill, the projection and the threshold tick sit on the
2// bar, set through the CSSOM so apps keep style-src 'self'. The number itself is in the
3// markup's text and aria-valuetext; this only draws the bar. The usage meter, the stat tile
4// and any app's bar use these same functions.
5
6export type MeterTone = "ok" | "warn" | "crit";
7
8// The share of the span, from 0 to 1. A missing, negative or non-finite value is 0.
9export function ratio(value: number, max: number, min = 0): number {
10  const span = max - min;
11  if (!Number.isFinite(value) || !Number.isFinite(span) || span <= 0) return 0;
12  return Math.min(1, Math.max(0, (value - min) / span));
13}
14
15// The tone a value earns by threshold: warning from `warnAt` of the span, critical from
16// `critAt` (both 0 to 1; the defaults are the usage meter's 75% and 90%). The caller still
17// writes the status word beside it: a tone is a word, a shape and a colour, never colour.
18export function toneFor(value: number, max: number, options: { min?: number; warnAt?: number; critAt?: number } = {}): MeterTone {
19  const { min = 0, warnAt = 0.75, critAt = 0.9 } = options;
20  const r = ratio(value, max, min);
21  return r >= critAt ? "crit" : r >= warnAt ? "warn" : "ok";
22}
23
24function num(s: string | null | undefined): number {
25  return s == null || s === "" ? NaN : Number(s);
26}
27
28export interface BarValues {
29  value: number;
30  max: number;
31  min?: number;
32  // The projected value at the end of the period, in the same unit; null or absent: none.
33  projected?: number | null;
34  // Where the threshold tick sits, in the same unit; null or absent: no tick.
35  threshold?: number | null;
36}
37
38// Sets one bar's positions from its values.
39export function setBar(bar: HTMLElement, v: BarValues): void {
40  const min = v.min ?? 0;
41  bar.style.setProperty("--cap-meter-ratio", String(ratio(v.value, v.max, min)));
42  if (v.projected == null) bar.style.removeProperty("--cap-meter-projected");
43  else bar.style.setProperty("--cap-meter-projected", String(Math.max(ratio(v.value, v.max, min), ratio(v.projected, v.max, min))));
44  if (v.threshold == null) bar.style.removeProperty("--cap-meter-threshold");
45  else bar.style.setProperty("--cap-meter-threshold", String(ratio(v.threshold, v.max, min)));
46}
47
48// Reads a bar's aria-valuenow, aria-valuemin, aria-valuemax, data-projected and
49// data-threshold and draws it.
50export function update(bar: HTMLElement): void {
51  const min = num(bar.getAttribute("aria-valuemin"));
52  const projected = num(bar.dataset.projected);
53  const threshold = num(bar.dataset.threshold);
54  setBar(bar, {
55    value: num(bar.getAttribute("aria-valuenow")),
56    max: num(bar.getAttribute("aria-valuemax")),
57    min: Number.isFinite(min) ? min : 0,
58    projected: Number.isFinite(projected) ? projected : null,
59    threshold: Number.isFinite(threshold) ? threshold : null,
60  });
61}
62
63const WATCHED = ["aria-valuenow", "aria-valuemax", "aria-valuemin", "data-projected", "data-threshold"];
64
65// Attaches to every [data-cap="meter"] under root (or root itself) not yet attached, draws
66// its bar, and redraws it whenever a value changes. Returns a function that detaches.
67export function enhance(root: ParentNode = document): () => void {
68  const undo: Array<() => void> = [];
69  const found = [...root.querySelectorAll<HTMLElement>("[data-cap='meter']:not([data-cap-ready])")];
70  if (root instanceof HTMLElement && root.matches("[data-cap='meter']:not([data-cap-ready])")) found.unshift(root);
71  for (const meter of found) {
72    meter.dataset.capReady = "";
73    const bar = meter.querySelector<HTMLElement>(".cap-meter-bar");
74    if (bar) {
75      update(bar);
76      const watch = new MutationObserver(() => update(bar));
77      watch.observe(bar, { attributes: true, attributeFilter: WATCHED });
78      undo.push(() => watch.disconnect());
79    }
80    undo.push(() => {
81      delete meter.dataset.capReady;
82    });
83  }
84  return () => undo.forEach((f) => f());
85}