makersclaw 0.2.0 → 0.3.0

package/templates/next/files/components/ui/stat.jsx

@@ -0,0 +1,574 @@
+import { Children } from "react";
+import { cx } from "./cx";
+import { Icon } from "./icon";
+
+// Numbers at a glance: a Stat, the strip of them, the signed change beside
+// one, a status dot, a legend of dots, a meter against a limit.
+// Server-safe (no hooks), so a server surface can use them directly.
+// Every number is tabular (data-nums), so a column of them lines up and a
+// ticking value does not shake. Colour is the signal: tones are named, as
+// Badge does it, and status tones are for status only — never decoration.
+// A dot can take a categorical `hue` (1..5, the chart colours) instead, for
+// KINDS of things: a platform, a content type. Tone is status, hue is
+// category; a tone given with a hue wins.
+// Blocks use these and never draw their own.
+
+// The text colour of a value in each tone.
+const TEXT_TONES = {
+  neutral: "text-foreground",
+  muted: "text-muted-foreground",
+  primary: "text-primary",
+  success: "text-success",
+  warning: "text-warning",
+  danger: "text-destructive",
+  info: "text-info",
+};
+
+// The fill of a dot or a bar in each tone. neutral is a quiet grey for a
+// dot; a Meter's neutral bar is bg-primary, the same as Progress, and its
+// muted bar is the grey.
+const FILL_TONES = {
+  neutral: "bg-muted-foreground",
+  muted: "bg-muted-foreground",
+  primary: "bg-primary",
+  success: "bg-success",
+  warning: "bg-warning",
+  danger: "bg-destructive",
+  info: "bg-info",
+};
+
+// The fill of a dot in each categorical hue (--color-chart-N).
+const HUE_FILLS = { 1: "bg-chart-1", 2: "bg-chart-2", 3: "bg-chart-3", 4: "bg-chart-4", 5: "bg-chart-5" };
+
+const EN = "en-US"; // one locale on the server and the client: no hydration drift
+const formatNumber = (n) => (typeof n === "number" ? n.toLocaleString(EN, { maximumFractionDigits: 2 }) : String(n ?? ""));
+
+/* ------------------------------------------------------------------------
+   Delta
+   ------------------------------------------------------------------------ */
+
+const DELTA_SIZES = { sm: { text: "text-xs", icon: 12 }, md: { text: "text-sm", icon: 14 } };
+
+/**
+ * A signed change: an arrow, the value with its sign, an optional suffix —
+ * "↑ +12.4%". Up is good (success) and down is bad (danger) unless
+ * `invert`, for "lower is better" (latency, churn, cost). Zero is neutral,
+ * with a flat dash and no sign.
+ *
+ *   value    the change, a number; its sign sets the arrow and the tone
+ *   display  what to show for the size of it instead of the number
+ *            ("$35K"); the sign is still added. Default the number, to at
+ *            most one decimal
+ *   suffix   after the number: "%", " pts", "ms"
+ *   invert   lower is better: down turns success, up turns danger
+ *   label    a muted line after it: "vs last week"
+ *   size     sm (text-xs) · md (text-sm)
+ *   variant  text (bare) · badge (a tinted pill, for a table cell or a tile corner)
+ *   arrow    default true; false for the bare "+$35K" of a dense row
+ *   hideValue  the arrow and its tone alone (a trend in a tight cell);
+ *            the value is still what a screen reader hears. Always draws
+ *            the arrow, whatever `arrow` says
+ */
+export function Delta({ value, display, suffix = "", invert = false, label, size = "sm", variant = "text", arrow = true, hideValue = false, className }) {
+  const n = typeof value === "number" && Number.isFinite(value) ? value : 0;
+  const sign = n > 0 ? 1 : n < 0 ? -1 : 0;
+  const good = invert ? sign < 0 : sign > 0;
+  const tone = sign === 0 ? "neutral" : good ? "success" : "danger";
+  const s = DELTA_SIZES[size] ?? DELTA_SIZES.sm;
+  const amount = display ?? Math.abs(n).toLocaleString(EN, { maximumFractionDigits: 1 });
+  const signed = `${sign > 0 ? "+" : sign < 0 ? "−" : ""}${amount}${suffix}`;
+  const look =
+    variant === "badge"
+      ? {
+          neutral: "bg-muted text-muted-foreground",
+          success: "bg-success/15 text-success",
+          danger: "bg-destructive/15 text-destructive",
+        }[tone]
+      : { neutral: "text-muted-foreground", success: "text-success", danger: "text-destructive" }[tone];
+  return (
+    <span className={cx("inline-flex items-baseline gap-1.5", s.text, className)}>
+      <span
+        data-nums
+        className={cx(
+          "inline-flex items-center gap-0.5 whitespace-nowrap font-medium",
+          variant === "badge" && "rounded-sm px-1.5 py-0.5",
+          look,
+        )}
+      >
+        {arrow || hideValue ? <Icon name={sign > 0 ? "arrow-up" : sign < 0 ? "arrow-down" : "minus"} size={s.icon} className="self-center" /> : null}
+        {/* The sign is a real minus (U+2212) on screen; a reader hears the word. */}
+        {hideValue ? null : <span aria-hidden="true">{signed}</span>}
+        <span className="sr-only">{sign > 0 ? `up ${amount}${suffix}` : sign < 0 ? `down ${amount}${suffix}` : `no change`}</span>
+      </span>
+      {label ? <span className="text-muted-foreground">{label}</span> : null}
+    </span>
+  );
+}
+
+/* ------------------------------------------------------------------------
+   StatusDot and Legend
+   ------------------------------------------------------------------------ */
+
+const DOT_SIZES = { sm: "size-1.5", md: "size-2" };
+
+/**
+ * A small round dot in a tone: a row's state, a service's health, a
+ * legend key. The dot alone says nothing to a screen reader — the meaning
+ * is in `label` (shown), or in `label` + `hideLabel` (read, not shown), or
+ * in the text beside it.
+ *
+ *   tone       neutral · primary · success · warning · danger · info
+ *   hue        1..5 — a categorical colour instead (a kind of thing, not
+ *              a state); ignored when a tone is given
+ *   size       sm (6px, in a dense row) · md (8px)
+ *   pulse      a ring that breathes out, for something live right now
+ *              (deploying, recording); still under prefers-reduced-motion
+ *   label      the words after it: "Healthy", "3 alerts"
+ *   hideLabel  keep the label for readers only
+ */
+export function StatusDot({ tone, hue, size = "md", pulse = false, label, hideLabel = false, className }) {
+  const fill = tone == null && HUE_FILLS[hue] ? HUE_FILLS[hue] : FILL_TONES[tone ?? "neutral"] ?? FILL_TONES.neutral;
+  const dot = (
+    <span aria-hidden="true" className={cx("relative inline-flex shrink-0", DOT_SIZES[size] ?? DOT_SIZES.md)}>
+      {pulse ? <span className={cx("absolute inset-0 rounded-full opacity-60 animate-ping motion-reduce:hidden", fill)} /> : null}
+      <span className={cx("relative inline-flex size-full rounded-full", fill)} />
+    </span>
+  );
+  if (!label) return <span className={cx("inline-flex items-center", className)}>{dot}</span>;
+  return (
+    <span className={cx("inline-flex items-center gap-1.5 text-sm text-muted-foreground", className)}>
+      {dot}
+      <span className={hideLabel ? "sr-only" : "min-w-0 truncate"}>{label}</span>
+    </span>
+  );
+}
+
+/**
+ * A row of dot · count · label, wrapping when it runs out of room — "● 2
+ * overdue · ● 3 urgent". The key under a chart, the summary in a card
+ * header. A list, so a reader hears how many kinds there are.
+ *
+ *   items  [{ tone, label, count }] — count optional; an item with count 0
+ *          is still drawn (say it, or leave it out of items). `hue` (1..5)
+ *          in place of `tone` for a key of categories
+ *   size   sm (text-xs, 6px dots) · md (text-sm, 8px dots)
+ *   label  the list's name for readers: "Tasks by state"
+ */
+export function Legend({ items = [], size = "md", label, className }) {
+  if (!items.length) return null;
+  return (
+    <ul
+      aria-label={label}
+      className={cx("flex flex-wrap items-center gap-x-3 gap-y-1", size === "sm" ? "text-xs" : "text-sm", className)}
+    >
+      {items.map((it, i) => (
+        <li key={it.key ?? `${it.label}-${i}`} className="inline-flex items-center gap-1.5 text-muted-foreground">
+          <StatusDot tone={it.tone} hue={it.hue} size={size === "sm" ? "sm" : "md"} />
+          {it.count != null ? (
+            <span data-nums className="font-medium text-foreground">
+              {formatNumber(it.count)}
+            </span>
+          ) : null}
+          <span>{it.label}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/* ------------------------------------------------------------------------
+   Stat and StatGroup
+   ------------------------------------------------------------------------ */
+
+const STAT_SIZES = {
+  sm: { label: "text-xs", value: "text-lg font-semibold leading-tight", unit: "text-xs", icon: 14, delta: "sm" },
+  md: { label: "text-sm", value: "text-2xl font-semibold leading-tight tracking-tight", unit: "text-sm", icon: 16, delta: "sm" },
+  lg: { label: "text-sm", value: "font-display text-4xl font-semibold leading-none tracking-tight", unit: "text-base", icon: 18, delta: "md" },
+};
+
+/**
+ * One number with its name: "Hit rate 94.8%". The value is the loudest
+ * thing on it; everything else is muted.
+ *
+ *   label    what it counts: "Monthly revenue"
+ *   value    already formatted — "$1.37M", "42", "2.4/4" (a string or a
+ *            number; a number gets thousands separators)
+ *   unit     after the value, smaller and muted: "ms", "%", "/ 10.3 TB"
+ *   caption  a muted line under it: "Unit + integration tests"
+ *   tone     colours the value, for a threshold state (a miss rate over
+ *            budget is danger). neutral (default) · primary · success ·
+ *            warning · danger · info
+ *   dot      a tone for a StatusDot before the label (the state of the
+ *            thing, when the value itself stays neutral)
+ *   icon     an Icon name, muted, at the end of the label row
+ *   delta    the change beside the value: a number (a percent: 12.4 →
+ *            "↑ +12.4%") or Delta's props ({ value, display, suffix, label })
+ *   invert   lower is better, passed to the Delta
+ *   size     sm (a dense strip) · md · lg (the one number a card is about)
+ *   align    start · end (a stat pinned to the right of a header)
+ */
+export function Stat({ label, value, unit, caption, tone = "neutral", dot, icon, delta, invert, size = "md", align = "start", className }) {
+  const s = STAT_SIZES[size] ?? STAT_SIZES.md;
+  const d = delta == null ? null : typeof delta === "number" ? { value: delta, suffix: "%" } : delta;
+  return (
+    <div className={cx("min-w-0", align === "end" && "text-right", className)}>
+      {label || icon || dot ? (
+        <div className={cx("flex items-center gap-1.5 text-muted-foreground", s.label, align === "end" && "justify-end")}>
+          {dot ? <StatusDot tone={dot} size="sm" /> : null}
+          {label ? <span className="min-w-0 truncate">{label}</span> : null}
+          {icon ? <Icon name={icon} size={s.icon} className={cx("shrink-0", align !== "end" && "ml-auto")} /> : null}
+        </div>
+      ) : null}
+      <div className={cx("mt-1 flex flex-wrap items-baseline gap-x-2 gap-y-0.5", align === "end" && "justify-end")}>
+        <span className="inline-flex min-w-0 items-baseline gap-1">
+          <span data-nums className={cx(s.value, TEXT_TONES[tone] ?? TEXT_TONES.neutral)}>
+            {formatNumber(value)}
+          </span>
+          {unit ? (
+            <span data-nums className={cx("text-muted-foreground", s.unit)}>
+              {unit}
+            </span>
+          ) : null}
+        </span>
+        {d ? <Delta invert={invert} size={s.delta} {...d} /> : null}
+      </div>
+      {caption ? <p className="mt-1 text-xs text-muted-foreground">{caption}</p> : null}
+    </div>
+  );
+}
+
+// Literal class names, so Tailwind sees every one.
+const COLS = { 1: "sm:grid-cols-1", 2: "sm:grid-cols-2", 3: "sm:grid-cols-3", 4: "sm:grid-cols-4" };
+const SPAN_SM = { 1: "sm:col-span-1", 2: "sm:col-span-2", 3: "sm:col-span-3", 4: "sm:col-span-4" };
+
+/**
+ * The strip of 2 to 4 Stats across the top of a card or a page. Two
+ * columns on a phone, all of them from sm up; a last cell that would
+ * leave a hole stretches to fill its row.
+ *
+ *   variant  card (default: bordered, a rule between every cell) ·
+ *            divided (no box, a vertical rule between cells — for a strip
+ *            already inside a Card) · bare (spacing only)
+ *   columns  from sm up; default the number of Stats (at most 4). Six
+ *            stats in columns={3} make two rows
+ *   label    the strip's name for readers: "Cache summary"
+ *   children the Stats
+ *
+ * Edge to edge inside a Card: variant="card" with className="rounded-none
+ * border-x-0" and the Card's padding taken off (-mx-4).
+ */
+export function StatGroup({ variant = "card", columns, label, className, children }) {
+  const kids = Children.toArray(children).filter(Boolean);
+  const n = kids.length;
+  if (!n) return null;
+  const cols = Math.min(4, Math.max(1, columns ?? Math.min(n, 4)));
+  const phoneCols = Math.min(2, n);
+  const card = variant === "card";
+  const divided = variant === "divided";
+  return (
+    <div
+      role={label ? "group" : undefined}
+      aria-label={label}
+      className={cx(
+        "grid",
+        phoneCols === 1 ? "grid-cols-1" : "grid-cols-2",
+        COLS[cols],
+        card && "gap-px overflow-hidden rounded-lg border border-border bg-border",
+        divided && "gap-y-4",
+        variant === "bare" && "gap-4",
+        className,
+      )}
+    >
+      {kids.map((kid, i) => {
+        const last = i === n - 1;
+        // A last cell alone on its row spans what is left of it.
+        const phoneSpan = last && n % phoneCols !== 0 ? "col-span-2" : "";
+        const remSm = n % cols;
+        const smSpan = last ? SPAN_SM[remSm ? cols - remSm + 1 : 1] : phoneSpan ? "sm:col-span-1" : "";
+        // Divided: a rule on every cell that does not start a row.
+        const rulePhone = i % phoneCols !== 0;
+        const ruleSm = i % cols !== 0;
+        const rule = divided
+          ? cx(
+              "pr-4",
+              rulePhone && "border-l border-border pl-4",
+              rulePhone && !ruleSm && "sm:border-l-0 sm:pl-0",
+              !rulePhone && ruleSm && "sm:border-l sm:border-border sm:pl-4",
+            )
+          : "";
+        return (
+          <div key={kid.key ?? i} className={cx("min-w-0", card && "bg-card p-4", rule, phoneSpan, smSpan)}>
+            {kid}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------------
+   Meter
+   ------------------------------------------------------------------------ */
+
+const METER_SIZES = { thin: { track: "h-1", mark: "h-3" }, md: { track: "h-2", mark: "h-4" } };
+
+/**
+ * A quantity against a limit: storage used of a plan, spend of a budget,
+ * bandwidth of a cap. Drawn like Progress, but it is a role=meter, not a
+ * progressbar — Progress is how far a job has got, which only moves
+ * forward and ends; a Meter is how full something is, which can fall and
+ * can go OVER. Over the limit the bar stays full, turns danger, and a
+ * reader hears "over by …".
+ *
+ *   value       the amount used, a number in the unit of `max`
+ *   max         the limit; default 100
+ *   label       the meter's name, shown above it and read to a screen reader
+ *   unit        after the numbers: "GB", "credits"
+ *   format      (n) → string for every number shown; default thousands
+ *               separators ("$" + n / 1000 + "K" for money)
+ *   valueText   the right side of the header; default "used / limit unit";
+ *               null hides it (a row that shows its own numbers)
+ *   valueTone   the colour of that text: muted (default) · neutral ·
+ *               primary · success · warning · danger · info · "bar" (the
+ *               bar's own tone). Over the limit it is danger regardless
+ *   target      a mark on the bar at this amount (a goal, a budget line),
+ *               named in the footer and to a reader
+ *   targetMark  default true; false keeps the target in the footer and for
+ *               a reader but draws no tick on the bar
+ *   direction   against `target`, when no `tone` is given: higher (a goal —
+ *               success once reached, warning below it) · lower (a budget —
+ *               success at or under it, warning past it). Higher also keeps
+ *               a bar over the limit out of danger: past a quota is good
+ *   thresholds  [{ at, tone }] — `at` is a percent of max; the bar takes the
+ *               tone of the highest one reached: [{ at: 80, tone: "warning" },
+ *               { at: 95, tone: "danger" }]
+ *   tone        the bar below every threshold: neutral (bg-primary, like
+ *               Progress) · muted (grey, a plain share that signals
+ *               nothing) · success · warning · danger · info
+ *   caption     a muted line under the bar, left of the target
+ *   size        thin (4px, a list row) · md (8px); a ring: sm (40px, a
+ *               list row or a stat tile) · md (64px) · lg (96px)
+ *   shape       bar (default) · ring — a circular gauge, the percent in its
+ *               middle, the label, value text, caption and target beside
+ *               it. Tone, thresholds, target (a tick across the ring),
+ *               direction, over-the-limit and what a reader hears are the
+ *               bar's
+ *   center      a ring's middle instead of the percent: a string or a node
+ *               ("4.2 GB", an Icon); null leaves it empty
+ */
+export function Meter({
+  value,
+  max = 100,
+  label,
+  unit,
+  format = formatNumber,
+  valueText,
+  valueTone = "muted",
+  target,
+  targetMark = true,
+  direction,
+  thresholds,
+  tone,
+  caption,
+  size = "md",
+  shape = "bar",
+  center,
+  className,
+  ...rest
+}) {
+  const v = typeof value === "number" && Number.isFinite(value) ? value : 0;
+  const limit = max > 0 ? max : 100;
+  const pct = (v / limit) * 100;
+  const over = v > limit;
+  const overBad = over && direction !== "higher";
+  const u = unit ? ` ${unit}` : "";
+  const hasTarget = typeof target === "number" && Number.isFinite(target);
+
+  // No tone given: the direction judges the value against the target.
+  const met = direction === "higher" ? v >= target : v <= target;
+  let barTone = tone ?? (hasTarget && (direction === "higher" || direction === "lower") ? (met ? "success" : "warning") : "neutral");
+  for (const t of [...(thresholds ?? [])].sort((a, b) => a.at - b.at)) if (pct >= t.at) barTone = t.tone;
+  if (overBad) barTone = "danger";
+  const fill = barTone === "neutral" ? "bg-primary" : FILL_TONES[barTone] ?? "bg-primary";
+  const valueClass = overBad
+    ? "font-medium text-destructive"
+    : valueTone === "bar"
+      ? cx("font-medium", barTone === "neutral" ? "text-primary" : TEXT_TONES[barTone] ?? "text-primary")
+      : valueTone === "muted"
+        ? "text-muted-foreground"
+        : cx("font-medium", TEXT_TONES[valueTone] ?? "text-muted-foreground");
+
+  const targetPct = hasTarget ? Math.min(100, Math.max(0, (target / limit) * 100)) : 0;
+  const shown = valueText === undefined ? `${format(v)} / ${format(limit)}${u}` : valueText;
+  const said = [
+    `${format(v)} of ${format(limit)}${u}`,
+    over ? `over by ${format(v - limit)}${u}` : `${Math.round(pct)}%`,
+    hasTarget ? `target ${format(target)}${u}` : null,
+  ]
+    .filter(Boolean)
+    .join(", ");
+  const meterProps = {
+    role: "meter",
+    "aria-label": label,
+    "aria-valuemin": 0,
+    "aria-valuemax": limit,
+    "aria-valuenow": Math.min(v, limit),
+    "aria-valuetext": said,
+  };
+
+  if (shape === "ring") {
+    return (
+      <MeterRing
+        {...{ pct, over, overBad, barTone, valueTone, valueClass, label, shown, caption, hasTarget, targetMark, targetPct, center, size, className, meterProps, rest }}
+        targetText={hasTarget ? `Target ${format(target)}${u}` : null}
+      />
+    );
+  }
+
+  const s = METER_SIZES[size] ?? METER_SIZES.md;
+  const footer = caption || (hasTarget && size === "md");
+
+  return (
+    <div className={cx("grid gap-1.5", className)}>
+      {label || shown ? (
+        <div aria-hidden="true" className="flex items-baseline justify-between gap-3 text-sm">
+          <span className="min-w-0 truncate font-medium text-foreground">{label}</span>
+          {shown ? (
+            <span data-nums className={cx("shrink-0 text-xs", valueClass)}>
+              {shown}
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+      <div className="relative">
+        <div
+          role="meter"
+          aria-label={label}
+          aria-valuemin={0}
+          aria-valuemax={limit}
+          aria-valuenow={Math.min(v, limit)}
+          aria-valuetext={said}
+          className={cx("relative w-full overflow-hidden rounded-full bg-accent", s.track)}
+          {...rest}
+        >
+          <div
+            className={cx("h-full rounded-full transition-[width] duration-300 ease-out motion-reduce:transition-none", fill)}
+            style={{ width: `${Math.min(100, Math.max(0, pct))}%` }}
+          />
+        </div>
+        {hasTarget && targetMark ? (
+          <span
+            aria-hidden="true"
+            className={cx("absolute top-1/2 w-0.5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-foreground", s.mark)}
+            style={{ left: `${targetPct}%` }}
+          />
+        ) : null}
+      </div>
+      {footer ? (
+        <div aria-hidden={caption ? undefined : "true"} className="flex items-baseline justify-between gap-3 text-xs text-muted-foreground">
+          <span className="min-w-0">{caption}</span>
+          {hasTarget ? (
+            <span data-nums className="shrink-0">
+              Target {format(target)}
+              {u}
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+// The ring's stroke in each tone (neutral is bg-primary's stroke, as the bar).
+const STROKE_TONES = {
+  neutral: "stroke-primary",
+  muted: "stroke-muted-foreground",
+  primary: "stroke-primary",
+  success: "stroke-success",
+  warning: "stroke-warning",
+  danger: "stroke-destructive",
+  info: "stroke-info",
+};
+
+// px is the ring's box, w its stroke; text the middle's type.
+const RING_SIZES = {
+  sm: { px: 40, w: 4, text: "text-2xs font-semibold", side: "text-sm", gap: "gap-2.5" },
+  md: { px: 64, w: 6, text: "text-sm font-semibold", side: "text-sm", gap: "gap-3" },
+  lg: { px: 96, w: 8, text: "text-xl font-semibold tracking-tight", side: "text-base", gap: "gap-4" },
+};
+RING_SIZES.thin = RING_SIZES.sm;
+
+// Meter shape="ring": the same numbers, drawn as an arc from twelve o'clock.
+function MeterRing({ pct, overBad, barTone, valueTone, valueClass, label, shown, caption, hasTarget, targetMark, targetPct, targetText, center, size, className, meterProps, rest }) {
+  const g = RING_SIZES[size] ?? RING_SIZES.md;
+  const c = g.px / 2;
+  const r = c - g.w / 2;
+  const len = 2 * Math.PI * r;
+  const frac = Math.min(1, Math.max(0, pct / 100));
+  const stroke = STROKE_TONES[barTone] ?? "stroke-primary";
+  const middleClass = overBad
+    ? "text-destructive"
+    : valueTone === "bar"
+      ? barTone === "neutral"
+        ? "text-primary"
+        : TEXT_TONES[barTone] ?? "text-primary"
+      : valueTone === "muted"
+        ? "text-foreground"
+        : TEXT_TONES[valueTone] ?? "text-foreground";
+  const middle = center === undefined ? `${Math.round(pct)}%` : center;
+  // The target tick: a short radial line across the ring, at its angle.
+  const a = (targetPct / 100) * 2 * Math.PI - Math.PI / 2;
+  const tick = (d) => [c + Math.cos(a) * d, c + Math.sin(a) * d];
+  const [x1, y1] = tick(r - g.w / 2 - 1.5);
+  const [x2, y2] = tick(r + g.w / 2 + 1.5);
+  const side = label || shown || caption || (hasTarget && size !== "sm");
+
+  return (
+    <div className={cx("flex min-w-0 items-center", g.gap, className)}>
+      <div {...meterProps} className="relative shrink-0" style={{ width: g.px, height: g.px }} {...rest}>
+        <svg aria-hidden="true" width={g.px} height={g.px} viewBox={`0 0 ${g.px} ${g.px}`} className="block overflow-visible">
+          {/* raw: an SVG gauge — the kit has no smaller part to draw an arc. */}
+          <circle cx={c} cy={c} r={r} fill="none" strokeWidth={g.w} className="stroke-accent" />
+          {frac > 0 ? (
+            <circle
+              cx={c}
+              cy={c}
+              r={r}
+              fill="none"
+              strokeWidth={g.w}
+              strokeLinecap="round"
+              strokeDasharray={`${len * frac} ${len}`}
+              transform={`rotate(-90 ${c} ${c})`}
+              className={cx("transition-[stroke-dasharray] duration-300 ease-out motion-reduce:transition-none", stroke)}
+            />
+          ) : null}
+          {hasTarget && targetMark ? (
+            <line x1={x1} y1={y1} x2={x2} y2={y2} strokeWidth={2} strokeLinecap="round" className="stroke-foreground" />
+          ) : null}
+        </svg>
+        {middle !== null && middle !== false ? (
+          <span aria-hidden="true" data-nums className={cx("absolute inset-0 flex items-center justify-center leading-none", g.text, middleClass)}>
+            {middle}
+          </span>
+        ) : null}
+      </div>
+      {side ? (
+        <div className={cx("grid min-w-0 gap-0.5", g.side)}>
+          {label ? <span aria-hidden="true" className="min-w-0 truncate font-medium text-foreground">{label}</span> : null}
+          {shown ? (
+            <span data-nums aria-hidden="true" className={cx("text-xs", valueClass)}>
+              {shown}
+            </span>
+          ) : null}
+          {caption || (hasTarget && size !== "sm") ? (
+            <span className="text-xs text-muted-foreground">
+              {caption}
+              {caption && hasTarget && size !== "sm" ? " · " : null}
+              {hasTarget && size !== "sm" ? <span aria-hidden="true" data-nums>{targetText}</span> : null}
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}