@lotics/ui 40.2.0 → 41.0.0

package/MIGRATION.md

@@ -4,6 +4,48 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 41.0.0 — `RingGauge` is `ProgressRing`, and circular progress is one component
+
+`RingGauge` is **deleted**. `ProgressRing` replaces it and covers both what it did and the
+bare arc it could not.
+
+```diff
+- import { RingGauge } from "@lotics/ui/ring_gauge";
++ import { ProgressRing } from "@lotics/ui/progress_ring";
+
+- <RingGauge value={87} label="On time" caption="33 of 38 deliveries" />
++ <ProgressRing value={87} label="On time" caption="33 of 38 deliveries" />
+```
+
+For that shape nothing else changes — same 140px default, same figure, same label column.
+
+**What is new is the other end of the axis.** `format="none"` with no label leaves the arc
+bare, at any size, which is what makes one component enough:
+
+```tsx
+<ProgressRing value={15200} max={1000000} size={16} format="none" />
+```
+
+**Why it had to be one.** `RingGauge` and `ProgressBar` were the same concept in two
+geometries built to two APIs — the ring took 0–100 where the bar takes `value`/`max`, hardcoded
+`Math.round(value)%` in its centre where the bar has a `format` axis, and *required* a label
+where the bar's title is optional. Reaching for a second, smaller ring component made the
+duplication obvious rather than fixing it. `ProgressRing` now mirrors `ProgressBar`: a reader
+who knows one knows the other.
+
+Two consequences of that mirroring worth knowing:
+
+- **Pass the real pair, not a percentage.** `value`/`max` (default `max: 100`, so an existing
+  0–100 value still reads directly). The arc and the figure then derive from the same untouched
+  numbers, which is how they stay in agreement.
+- **`thickness` derives from `size`** — 10% of the diameter, floored at 2 — because no fixed
+  default serves both 16 and 140, and 14 at icon scale is absurd. The centre figure's type
+  scales the same way. Both are still overridable.
+
+A bare ring renders no text and so announces nothing to a screen reader. That is correct for a
+decoration inside a labelled control, and it means a bare ring must never be the only thing
+carrying a meaning — whatever owns it says what it measures.
+
 ## 40.0.0 — `PopoverContent` decides its own presentation; `small` is gone
 
 `PopoverContent` took a `small` prop meaning "render as a bottom sheet". It now asks

package/docs/catalog.md

@@ -209,7 +209,7 @@ Two columnar shapes, and the choice is about data size:
 `KPIStrip` (the dashboard stat band), `SummaryLine` (the light inline register/list summary
 — below the toolbar, from the filtered rows), `KPICard` / `Metric` (headline figures),
 `TrendChip` (delta), `Sparkline`, `BarChart` / `LineChart` / `PieChart` (the canonical SVG
-set — no recharts), `RingGauge`, `ProgressBar` (its `compact` prop = ONE row, track + a
+set — no recharts), `ProgressRing`, `ProgressBar` (its `compact` prop = ONE row, track + a
 plain sm tabular count beside it — the cell/heading/peek-trigger meter; a caption floating
 above a tiny bar reads misaligned. **The track clamps at 100%, the caption does not** — over
 its max it reads `2,100 / 2,000 (105%)`, because a meter that says "100%" when you are over
@@ -1329,9 +1329,17 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`sparkline`** — `Sparkline`: the inline mini trend line.
 - **`bar_chart`** / **`line_chart`** / **`pie_chart`** — `BarChart` / `LineChart` /
   `PieChart`: the canonical SVG chart set (no recharts).
-- **`ring_gauge`** — `RingGauge`: single-fraction circular gauge.
 - **`progress_bar`** — `ProgressBar`: the determinate meter; `compact` = ONE row, track + a
   plain sm tabular count beside it.
+- **`progress_ring`** — `ProgressRing`: the same meter in a circle, and the ONLY circular one
+  (it replaced `RingGauge`). Same API shape as the bar — a real `value`/`max` rather than a
+  pre-computed percentage, optional `label`/`caption`, and a `format` that turns the centre
+  figure off. `format="none"` with no label leaves the arc bare at any size: that is the
+  TRIGGER form, for a control row where a figure would be unreadable and a bar would not
+  read. `thickness` derives from `size` (10%, floored at 2) because no fixed default serves
+  both 16 and 140, and the centre figure's type scales with the ring for the same reason. A
+  bare ring renders no text, so it announces nothing — whatever owns it must say what it
+  measures.
 - **`stacked_progress_bar`** — `StackedProgressBar`: one whole split across segments (a
   status mix on one bar).
 - **`step_progress`** — `StepProgress`: N-of-M dots/segments progress. A real `progressbar`

package/docs/templates.md

@@ -142,7 +142,7 @@ the pipeline (`StackedProgressBar`, blue = pipeline), a **Needs attention** `Acc
 (icon + label + count `Badge`; expanding opens the records behind the count, each row
 carrying its domain `⋯ ActionMenu`), top customers (`Avatar` + revenue + margin badge; the
 name `Peek`s the dossier). Also exercises the wider chart family (`LineChart`, `PieChart`,
-`RingGauge`, `Sparkline`, `TrendFooter`, `Funnel`) and `DateRangeFilterField` — the date
+`ProgressRing`, `Sparkline`, `TrendFooter`, `Funnel`) and `DateRangeFilterField` — the date
 filter actually filters the KPI datasets. Start here for any "state of the operation"
 landing screen.
 

package/examples/tpl_dashboard.tsx

@@ -15,7 +15,7 @@ import { Badge } from "@lotics/ui/badge";
 import { BarChart } from "@lotics/ui/bar_chart";
 import { LineChart } from "@lotics/ui/line_chart";
 import { PieChart } from "@lotics/ui/pie_chart";
-import { RingGauge } from "@lotics/ui/ring_gauge";
+import { ProgressRing } from "@lotics/ui/progress_ring";
 import { Sparkline } from "@lotics/ui/sparkline";
 import { TrendFooter } from "@lotics/ui/trend_footer";
 import { Button } from "@lotics/ui/button";
@@ -405,7 +405,7 @@ export function TplDashboard() {
               </CardHeaderTitle>
             </CardHeader>
             <View style={{ paddingHorizontal: 20, paddingVertical: 16, flex: 1, alignItems: "center", justifyContent: "center" }}>
-              <RingGauge value={87} label="On time" caption="33 of 38 deliveries" color={solid("emerald")} />
+              <ProgressRing value={87} label="On time" caption="33 of 38 deliveries" color={solid("emerald")} />
             </View>
           </Card>
         </View>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "40.2.0",
+  "version": "41.0.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -73,7 +73,7 @@
     "./format_money": "./src/format_money.ts",
     "./calendar": "./src/calendar/index.ts",
     "./gantt": "./src/gantt/index.ts",
-    "./ring_gauge": "./src/ring_gauge.tsx",
+    "./progress_ring": "./src/progress_ring.tsx",
     "./stacked_progress_bar": "./src/stacked_progress_bar.tsx",
     "./legend_item": "./src/legend_item.tsx",
     "./breakdown": "./src/breakdown.tsx",

package/src/progress_bar.tsx

@@ -26,6 +26,17 @@ export interface ProgressBarProps {
    * and the percentage too, which is how a 99.6%-full meter starts claiming it is exactly full.
    */
   formatValue?: (n: number) => string;
+  /**
+   * How the PERCENTAGE in the caption renders, given `value / max` as a fraction
+   * (which can exceed 1 — see the clamping note below). Defaults to whole points.
+   *
+   * Separate from `formatValue` because they answer different questions and a
+   * caller needs both: `formatValue` reshapes the two amounts, this reshapes the
+   * ratio between them. Without it a surface that renders percentages of its own
+   * cannot make them agree with this one — a meter reading "(2%)" beside a row
+   * reading "1,5%", where both are 1.52%, is the same number twice in one panel.
+   */
+  formatPercent?: (fraction: number) => string;
   color?: string;
   completeColor?: string;
   /** COMPACT: one row — the track (flex) with a plain sm tabular count beside
@@ -48,6 +59,7 @@ export function ProgressBar(props: ProgressBarProps) {
     title,
     format = "percentage",
     formatValue,
+    formatPercent,
     color = colors.blue["500"],
     completeColor = colors.green["500"],
     compact = false,
@@ -67,10 +79,13 @@ export function ProgressBar(props: ProgressBarProps) {
   const percentage = Math.min(100, ratio);
   const isComplete = ratio >= 100;
   const num = formatValue ?? ((n: number) => n.toLocaleString(localeTag));
+  const pct = formatPercent
+    ? (r: number) => formatPercent(r / 100)
+    : (r: number) => `${Math.round(r)}%`;
 
   if (compact) {
     const label =
-      format === "percentage" ? `${Math.round(ratio)}%` : `${num(value)}/${num(max)}`;
+      format === "percentage" ? pct(ratio) : `${num(value)}/${num(max)}`;
     return (
       <View style={styles.compactRow}>
         <View style={[styles.track, styles.compactTrack]}>
@@ -87,9 +102,9 @@ export function ProgressBar(props: ProgressBarProps) {
 
   const caption =
     format === "fraction"
-      ? `${num(value)} / ${num(max)} (${Math.round(ratio)}%)`
+      ? `${num(value)} / ${num(max)} (${pct(ratio)})`
       : format === "percentage"
-        ? `${Math.round(ratio)}%`
+        ? pct(ratio)
         : null;
 
   return (

package/src/progress_ring.tsx

@@ -0,0 +1,148 @@
+import { View } from "react-native";
+import { colors } from "./colors";
+import { Text } from "./text";
+
+export type ProgressRingFormat = "percentage" | "none";
+
+export interface ProgressRingProps {
+  value: number;
+  /** What `value` is a fraction OF. Default 100, so a value already expressed
+   *  as a percentage reads directly. Pass the real pair (tokens used / window,
+   *  slots filled / slots) rather than pre-computing: the arc and the figure
+   *  then derive from the same untouched numbers, which is how they stay in
+   *  agreement. */
+  max?: number;
+  /** Diameter in px. Default 140 — the dashboard figure. Drop to ~16 for a
+   *  control row or a trigger, where the arc is the whole content. */
+  size?: number;
+  /** Ring stroke. Derived from `size` when unset — 10% of the diameter, floored
+   *  at 2px so a small ring still paints. A fixed default cannot serve both
+   *  scales: 14 is right at 140 and absurd at 16. */
+  thickness?: number;
+  /** Short label under the ring. */
+  label?: string;
+  /** One-line context under the label. */
+  caption?: string;
+  /** What the CENTRE shows. `none` leaves the arc bare — the trigger form,
+   *  where a figure would be unreadable anyway. */
+  format?: ProgressRingFormat;
+  /** Arc color. */
+  color?: string;
+  /** The unfilled remainder. */
+  trackColor?: string;
+}
+
+/** The centre figure only reads at dashboard scale; below that it must shrink
+ *  with the ring or it overflows the circle it sits in. */
+function centreTextSize(size: number): "sm" | "lg" | "xxl" | "xxxl" {
+  if (size >= 120) return "xxxl";
+  if (size >= 88) return "xxl";
+  if (size >= 56) return "lg";
+  return "sm";
+}
+
+/**
+ * Circular progress — the ring form of `ProgressBar`, and the ONLY one.
+ *
+ * Same concept, different geometry, so it takes the same shape of API: a real
+ * `value`/`max` rather than a pre-computed percentage, optional `label` and
+ * `caption` slots, and a `format` that can turn the figure off entirely. A
+ * reader who knows the bar knows this.
+ *
+ * The `format="none"` end of that axis is what makes one component enough. At
+ * trigger scale the arc IS the content — no figure, no label, nothing to read —
+ * and at dashboard scale the figure leads with the label beneath it. That was
+ * two components (`RingGauge` and a bare ring) until the second one made it
+ * obvious they were one component with a suppressed centre.
+ *
+ * With `format="none"` and no label it renders no text at all, so it announces
+ * nothing to a screen reader. That is correct for a decoration inside a labelled
+ * control — but it means a bare ring must never be the only thing carrying a
+ * meaning: whatever owns it says what it measures.
+ *
+ * Implementation: native HTML `<svg>` (like `Sparkline`) — Vite can't resolve
+ * react-native-svg's native paths, and the `<View>` wrapper preserves the RN
+ * layout surface. The arc starts at 12 o'clock (`rotate(-90)`) and grows
+ * clockwise via `strokeDasharray`.
+ */
+export function ProgressRing(props: ProgressRingProps) {
+  const {
+    value,
+    max = 100,
+    size = 140,
+    thickness = Math.max(2, size * 0.1),
+    label,
+    caption,
+    format = "percentage",
+    color = colors.teal[600],
+    trackColor = colors.zinc[100],
+  } = props;
+
+  // The ARC clamps — an arc longer than its own circle is meaningless — while
+  // the figure reports the true ratio, the same split `ProgressBar` makes. A
+  // ring reading 100% while the number says 130% is the honest rendering of
+  // being over.
+  const ratio = max > 0 ? (value / max) * 100 : 0;
+  const clamped = Math.max(0, Math.min(100, ratio));
+  const center = size / 2;
+  const radius = (size - thickness) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const dash = (clamped / 100) * circumference;
+
+  const ring = (
+    <View style={{ width: size, height: size, alignItems: "center", justifyContent: "center" }}>
+      <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} style={{ position: "absolute" }}>
+        <circle
+          cx={center}
+          cy={center}
+          r={radius}
+          fill="none"
+          stroke={trackColor}
+          strokeWidth={thickness}
+        />
+        {/* A zero-length dash still paints a dot under `round` caps, which reads
+            as progress where there is none. Omit the arc entirely at 0. */}
+        {clamped > 0 ? (
+          <circle
+            cx={center}
+            cy={center}
+            r={radius}
+            fill="none"
+            stroke={color}
+            strokeWidth={thickness}
+            strokeLinecap="round"
+            strokeDasharray={`${dash} ${circumference}`}
+            transform={`rotate(-90 ${center} ${center})`}
+          />
+        ) : null}
+      </svg>
+      {format === "percentage" ? (
+        <Text size={centreTextSize(size)} weight="semibold">
+          {`${Math.round(ratio)}%`}
+        </Text>
+      ) : null}
+    </View>
+  );
+
+  // No label and no caption is the trigger form: the ring alone, with none of
+  // the column's centring or gap to shift it inside a control row.
+  if (!label && !caption) return ring;
+
+  return (
+    <View style={{ alignItems: "center", gap: 12 }}>
+      {ring}
+      <View style={{ alignItems: "center", gap: 2 }}>
+        {label ? (
+          <Text size="md" weight="semibold">
+            {label}
+          </Text>
+        ) : null}
+        {caption ? (
+          <Text size="sm" color="muted">
+            {caption}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}

package/src/vite.mjs

@@ -22,7 +22,7 @@
  *
  * Why each family is here:
  *  - `react-native-svg` — @lotics/ui's svg charts (PieChart/LineChart/Sparkline/
- *    RingGauge) reach a named-export entry the dev optimizer won't resolve
+ *    ProgressRing) reach a named-export entry the dev optimizer won't resolve
  *    unbundled ("does not provide an export named 'parse'").
  *  - `react-native-web` + `@react-native/normalize-colors` + the `inline-style-
  *    prefixer` / `fbjs` / `styleq` / `postcss-value-parser` / `nullthrows` core —

package/src/ring_gauge.tsx

@@ -1,72 +0,0 @@
-import { View } from "react-native";
-import { colors } from "./colors";
-import { Text } from "./text";
-
-export interface RingGaugeProps {
-  /** Progress value, 0–100. Clamped to that range. */
-  value: number;
-  /** Short label under the ring. */
-  label: string;
-  /** Optional one-line context under the label. */
-  caption?: string;
-  /** Diameter in px. Default 128. */
-  size?: number;
-  /** Ring stroke width in px. Default 14 — thinner reads weak. */
-  thickness?: number;
-  /** Arc color. Default teal accent. */
-  color?: string;
-}
-
-/**
- * Circular progress gauge — an at-a-glance ring for a 0–100% metric
- * (on-time rate, SLA compliance, win rate). The percentage leads in the
- * center; the track behind it shows the remaining-to-100 context. Pairs
- * with `KPICard` (figures) — use a ring when the number IS a ratio to 100.
- *
- * Implementation: native HTML `<svg>` (like `Sparkline`) — Vite can't
- * resolve react-native-svg's native paths, and the `<View>` wrapper
- * preserves the RN layout surface. The arc starts at 12 o'clock
- * (`rotate(-90)`) and grows clockwise via `strokeDasharray`.
- */
-export function RingGauge(props: RingGaugeProps) {
-  const { value, label, caption, size = 140, thickness = 14, color = colors.teal[600] } = props;
-  const clamped = Math.max(0, Math.min(100, value));
-  const center = size / 2;
-  const radius = (size - thickness) / 2;
-  const circumference = 2 * Math.PI * radius;
-  const dash = (clamped / 100) * circumference;
-
-  return (
-    <View style={{ alignItems: "center", gap: 12 }}>
-      <View style={{ width: size, height: size, alignItems: "center", justifyContent: "center" }}>
-        <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} style={{ position: "absolute" }}>
-          <circle cx={center} cy={center} r={radius} fill="none" stroke={colors.zinc[100]} strokeWidth={thickness} />
-          <circle
-            cx={center}
-            cy={center}
-            r={radius}
-            fill="none"
-            stroke={color}
-            strokeWidth={thickness}
-            strokeLinecap="round"
-            strokeDasharray={`${dash} ${circumference}`}
-            transform={`rotate(-90 ${center} ${center})`}
-          />
-        </svg>
-        <Text size="xxxl" weight="semibold">
-          {Math.round(clamped)}%
-        </Text>
-      </View>
-      <View style={{ alignItems: "center", gap: 2 }}>
-        <Text size="md" weight="semibold">
-          {label}
-        </Text>
-        {caption ? (
-          <Text size="sm" color="muted">
-            {caption}
-          </Text>
-        ) : null}
-      </View>
-    </View>
-  );
-}