components/meter/meter.react.tsx

Functions

Imports

It imports components/meter/meter.ts, components/status/status.react.tsx. Imported by components/usage-meter/usage-meter.react.tsx.

Source

1import { useId, useLayoutEffect, useRef, type ReactNode } from "react";
2import { setBar, toneFor, type MeterTone } from "./meter.ts";
3import { Glyph } from "../status/status.react.tsx";
4
5export interface MeterProps {
6  label: ReactNode;
7  // null is no data: the meter shows the no data state and its reason (in `note`), never a
8  // bar at zero.
9  value: number | null;
10  max: number;
11  min?: number;
12  // What a screen reader hears, whole: "78,000 of 100,000 requests today. Near the limit."
13  valueText: string;
14  // The number shown beside the label. Defaults to "value of max".
15  display?: ReactNode;
16  // Overrides the tone from the thresholds.
17  tone?: MeterTone;
18  // Tone by threshold, as a share of the span: warning from warnAt, critical from critAt.
19  // Without either, the tone is the `tone` prop or none.
20  warnAt?: number;
21  critAt?: number;
22  // The word shown with a warn or crit tone, so colour is never alone. Shown when the tone
23  // comes from warnAt/critAt, or when this is given; with a plain `tone` prop and no
24  // `words`, the word is the caller's, in `note`.
25  words?: { warn: string; crit: string };
26  // A threshold tick and a projection, in the same unit as value.
27  threshold?: number;
28  projected?: number;
29  size?: "sm" | "md" | "lg";
30  // The value is being measured now: an indeterminate bar with the reason in `note`.
31  measuring?: boolean;
32  // A line under the bar: what happens next, or why there is no data.
33  note?: ReactNode;
34  // For compositions (the usage meter's row): extra class names, the root element, and
35  // content after the bar, inside the meter's row.
36  className?: string;
37  as?: "div" | "li";
38  after?: ReactNode;
39}
40
41const WORDS = { warn: "Near the limit", crit: "Limit reached" };
42
43export function Meter({ label, value, max, min = 0, valueText, display, tone, warnAt, critAt, words, threshold, projected, size, measuring = false, note, className, as: Root = "div", after }: MeterProps) {
44  const bar = useRef<HTMLSpanElement>(null);
45  const labelId = useId();
46  const root = ["cap-meter", className].filter(Boolean).join(" ");
47  // Positions go through the CSSOM, never a style prop (style-src 'self').
48  useLayoutEffect(() => {
49    if (bar.current && value !== null && !measuring) setBar(bar.current, { value, max, min, projected, threshold });
50  }, [value, max, min, projected, threshold, measuring]);
51
52  if (value === null || measuring) {
53    const what = measuring ? "Measuring" : "No data";
54    return (
55      <Root className={root} data-size={size} data-tone={measuring ? undefined : "nodata"} data-state={measuring ? "indeterminate" : undefined} aria-busy={measuring || undefined}>
56        <span className="cap-meter-label">{label}</span>
57        <span className="cap-meter-value">
58          <span className="cap-status" data-tone="nodata">
59            <Glyph name="nodata" />
60            {what}
61          </span>
62        </span>
63        <span className="cap-meter-bar" aria-hidden="true">
64          <span className="cap-meter-fill" />
65        </span>
66        {note ? <span className="cap-meter-note">{note}</span> : null}
67        {after}
68      </Root>
69    );
70  }
71
72  const earned: MeterTone | undefined = tone ?? (warnAt != null || critAt != null ? toneFor(value, max, { min, warnAt, critAt }) : undefined);
73  const shown = earned === "warn" || earned === "crit" ? earned : undefined;
74  const word = shown && (words !== undefined || tone === undefined) ? (words ?? WORDS)[shown] : null;
75  return (
76    <Root className={root} data-size={size} data-tone={earned}>
77      <span className="cap-meter-label" id={labelId}>
78        {label}
79      </span>
80      {shown && word ? (
81        <span className="cap-status" data-tone={shown}>
82          <Glyph name={shown} />
83          {word}
84        </span>
85      ) : null}
86      <span className="cap-meter-value">{display ?? `${value.toLocaleString()} of ${max.toLocaleString()}`}</span>
87      <span
88        className="cap-meter-bar"
89        ref={bar}
90        role="meter"
91        aria-labelledby={labelId}
92        aria-valuemin={min}
93        aria-valuemax={max}
94        aria-valuenow={value}
95        aria-valuetext={valueText}
96        data-projected={projected}
97        data-threshold={threshold}
98      >
99        <span className="cap-meter-fill" />
100      </span>
101      {note ? <span className="cap-meter-note">{note}</span> : null}
102      {after}
103    </Root>
104  );
105}