@gfazioli/mantine-rings-progress 3.0.0 → 4.1.0

package/README.md

@@ -18,19 +18,24 @@
 ## Overview
 
 This component is created on top of the [Mantine](https://mantine.dev/) library.
+It requires **Mantine 9.x** and **React 19**.
 
 [Mantine Rings Progress](https://gfazioli.github.io/mantine-rings-progress/) is a Mantine UI extension that renders multiple concentric ring progress indicators — inspired by the Apple Watch activity rings. Each ring is defined by a value and color, and the component wraps native Mantine `RingProgress` instances with rich customization options.
 
 ### Features
 
 - **Per-ring customization** — Override `thickness`, `roundCaps`, and `rootColor` on individual rings
+- **Per-ring linear gradients** — Paint a ring's stroke with a two-stop gradient via `gradient: { from, to, deg? }`
+- **Per-ring value labels** — `showValues` (or per-ring `showValue`) drops a styled pill at the endpoint of each arc, with custom `formatValue`
+- **Per-ring interactions** — `onClick` and `onHover` callbacks with **geometric hit-testing**, so the right ring fires even when their wrappers overlap
 - **Entrance animation** — Animate rings from 0 to their target values on mount
 - **Staggered animation** — Animate rings one after another with configurable delay
+- **Animated value changes** — `animateValueChanges` interpolates value updates after mount (great for live dashboards)
 - **Glow / neon effect** — `drop-shadow` glow that follows the ring shape, with per-ring intensity and color
 - **Pulse on completion** — Subtle pulse animation when a ring reaches 100%, with `onRingComplete` callback
 - **Start angle & direction** — Customize where rings start filling and in which direction (clockwise/counterclockwise)
 - **Unified tooltip** — `withTooltip` shows a chart-like tooltip with color swatches for all rings
-- **Accessibility** — `role="progressbar"` with ARIA attributes on each ring, `prefers-reduced-motion` support
+- **Accessibility** — `role="progressbar"` with ARIA attributes on each ring, keyboard activation for clickable rings, `prefers-reduced-motion` support
 - **Central label** — Display any React node (text, emoji, component) centered in the rings
 
 > [!note]

package/dist/cjs/RingsProgress.cjs

@@ -1,9 +1,9 @@
 'use client';
 'use strict';
 
-var React = require('react');
 var core = require('@mantine/core');
 var hooks = require('@mantine/hooks');
+var React = require('react');
 var RingsProgress_module = require('./RingsProgress.module.css.cjs');
 
 const defaultProps = {
@@ -11,7 +11,9 @@ const defaultProps = {
   thickness: 12,
   gap: 8,
   animate: false,
+  animateValueChanges: false,
   roundCaps: true,
+  showValues: false,
   transitionDuration: 0,
   rootColorAlpha: 0.15,
   staggerDelay: 0,
@@ -21,7 +23,7 @@ const defaultProps = {
   direction: "clockwise",
   withTooltip: false
 };
-const RingsProgress = core.factory((_props, ref) => {
+const RingsProgress = core.factory((_props) => {
   const theme = core.useMantineTheme();
   const reduceMotion = hooks.useReducedMotion();
   const props = core.useProps("RingsProgress", defaultProps, _props);
@@ -33,6 +35,7 @@ const RingsProgress = core.factory((_props, ref) => {
     rootColorAlpha,
     label,
     animate,
+    animateValueChanges,
     transitionDuration,
     roundCaps,
     staggerDelay,
@@ -43,6 +46,8 @@ const RingsProgress = core.factory((_props, ref) => {
     direction,
     onRingComplete,
     withTooltip,
+    showValues,
+    formatValue,
     classNames,
     styles,
     unstyled,
@@ -58,6 +63,10 @@ const RingsProgress = core.factory((_props, ref) => {
     unstyled,
     vars
   });
+  const [instanceId] = React.useState(() => Math.random().toString(36).slice(2, 9));
+  const ringsRef = React.useRef(rings);
+  ringsRef.current = rings;
+  const ringCount = rings.length;
   const [mountedRings, setMountedRings] = React.useState(
     () => rings.map(() => !animate || reduceMotion)
   );
@@ -68,13 +77,13 @@ const RingsProgress = core.factory((_props, ref) => {
   }, []);
   React.useEffect(() => {
     if (!animate || reduceMotion) {
-      setMountedRings(rings.map(() => true));
+      setMountedRings(Array.from({ length: ringCount }, () => true));
       return;
     }
-    setMountedRings(rings.map(() => false));
+    setMountedRings(Array.from({ length: ringCount }, () => false));
     cleanupTimeouts();
     if (staggerDelay && staggerDelay > 0) {
-      rings.forEach((_, index) => {
+      for (let index = 0; index < ringCount; index++) {
         const timeout = setTimeout(() => {
           setMountedRings((prev) => {
             const next = [...prev];
@@ -83,23 +92,25 @@ const RingsProgress = core.factory((_props, ref) => {
           });
         }, index * staggerDelay);
         timeoutsRef.current.push(timeout);
-      });
+      }
     } else {
       requestAnimationFrame(() => {
-        setMountedRings(rings.map(() => true));
+        setMountedRings(Array.from({ length: ringCount }, () => true));
       });
     }
     return cleanupTimeouts;
-  }, [animate, reduceMotion, rings.length, staggerDelay]);
+  }, [animate, reduceMotion, ringCount, staggerDelay, cleanupTimeouts]);
   const prevValuesRef = React.useRef(rings.map((r) => r.value));
   const [pulsingRings, setPulsingRings] = React.useState(rings.map(() => false));
   const ringValuesKey = rings.map((r) => r.value).join(",");
   React.useEffect(() => {
-    prevValuesRef.current = rings.map((r) => r.value);
-    setPulsingRings(rings.map(() => false));
-  }, [rings.length]);
+    const current = ringsRef.current;
+    prevValuesRef.current = current.map((r) => r.value);
+    setPulsingRings(current.map(() => false));
+  }, [ringCount]);
   React.useEffect(() => {
-    const currentValues = rings.map((r) => r.value);
+    const current = ringsRef.current;
+    const currentValues = current.map((r) => r.value);
     const crossedComplete = currentValues.map((value, i) => {
       const prev = prevValuesRef.current[i] ?? 0;
       return value >= 100 && prev < 100;
@@ -107,7 +118,7 @@ const RingsProgress = core.factory((_props, ref) => {
     if (onRingComplete) {
       crossedComplete.forEach((crossed, i) => {
         if (crossed) {
-          onRingComplete(i, rings[i]);
+          onRingComplete(i, current[i]);
         }
       });
     }
@@ -115,7 +126,20 @@ const RingsProgress = core.factory((_props, ref) => {
       setPulsingRings(crossedComplete);
     }
     prevValuesRef.current = currentValues;
-  }, [ringValuesKey, pulseOnComplete, reduceMotion, onRingComplete, rings]);
+  }, [ringValuesKey, pulseOnComplete, reduceMotion, onRingComplete]);
+  const gradientDefs = rings.map((ring, index) => {
+    if (!ring.gradient) {
+      return null;
+    }
+    const id = `rp-grad-${instanceId}-${index}`;
+    const cssDeg = ring.gradient.deg ?? 0;
+    const svgDeg = cssDeg - 90;
+    const fromColor = core.parseThemeColor({ color: ring.gradient.from, theme }).value;
+    const toColor = core.parseThemeColor({ color: ring.gradient.to, theme }).value;
+    return { id, fromColor, toColor, svgDeg };
+  }).filter(
+    (g) => g !== null
+  );
   const handleAnimationEnd = React.useCallback((index) => {
     setPulsingRings((prev) => {
       const next = [...prev];
@@ -124,25 +148,115 @@ const RingsProgress = core.factory((_props, ref) => {
     });
   }, []);
   const allMounted = mountedRings.every(Boolean);
-  const effectiveTransitionDuration = reduceMotion ? 0 : animate && !allMounted ? transitionDuration || 1e3 : transitionDuration;
+  const effectiveTransitionDuration = reduceMotion ? 0 : animate && !allMounted ? transitionDuration || 1e3 : animateValueChanges ? transitionDuration || 500 : transitionDuration;
   const offsets = [];
   let cumulativeOffset = 0;
   for (let i = 0; i < rings.length; i++) {
     offsets.push(cumulativeOffset);
     const ringThickness = rings[i].thickness ?? thickness;
-    cumulativeOffset += ringThickness + gap;
+    cumulativeOffset += (ringThickness ?? 0) + (gap ?? 0);
   }
+  const hasInteractive = rings.some((r) => r.onClick || r.onHover);
+  const [hoveredIndex, setHoveredIndex] = React.useState(null);
+  const hoveredIndexRef = React.useRef(null);
+  hoveredIndexRef.current = hoveredIndex;
+  const ringAtPoint = React.useCallback(
+    (clientX, clientY, rect) => {
+      const cx = rect.left + rect.width / 2;
+      const cy = rect.top + rect.height / 2;
+      const r = Math.hypot(clientX - cx, clientY - cy);
+      const current = ringsRef.current;
+      for (let i = 0; i < current.length; i++) {
+        const t = current[i].thickness ?? thickness ?? 12;
+        const ringSize = (size ?? 120) - offsets[i] * 2;
+        const centerR = (ringSize * 0.9 - t * 2) / 2;
+        if (Math.abs(r - centerR) <= t / 2) {
+          return i;
+        }
+      }
+      return null;
+    },
+    // offsets is recomputed every render; capture by closure rather than listing it
+    // (size/thickness are stable refs through props).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [size, thickness, ringCount]
+  );
+  const handleContainerClick = React.useCallback(
+    (event) => {
+      if (!hasInteractive) {
+        return;
+      }
+      const rect = event.currentTarget.getBoundingClientRect();
+      const idx = ringAtPoint(event.clientX, event.clientY, rect);
+      if (idx === null) {
+        return;
+      }
+      const ring = ringsRef.current[idx];
+      ring.onClick?.(ring, idx);
+    },
+    [hasInteractive, ringAtPoint]
+  );
+  const handleContainerMouseMove = React.useCallback(
+    (event) => {
+      if (!hasInteractive) {
+        return;
+      }
+      const rect = event.currentTarget.getBoundingClientRect();
+      const idx = ringAtPoint(event.clientX, event.clientY, rect);
+      if (idx === hoveredIndexRef.current) {
+        return;
+      }
+      const prev = hoveredIndexRef.current;
+      if (prev !== null) {
+        const prevRing = ringsRef.current[prev];
+        prevRing.onHover?.(prevRing, prev, false);
+      }
+      setHoveredIndex(idx);
+      if (idx !== null) {
+        const newRing = ringsRef.current[idx];
+        newRing.onHover?.(newRing, idx, true);
+      }
+    },
+    [hasInteractive, ringAtPoint]
+  );
+  const handleContainerMouseLeave = React.useCallback(() => {
+    if (hoveredIndexRef.current === null) {
+      return;
+    }
+    const prev = hoveredIndexRef.current;
+    const prevRing = ringsRef.current[prev];
+    prevRing.onHover?.(prevRing, prev, false);
+    setHoveredIndex(null);
+  }, []);
+  const containerCursor = hoveredIndex !== null && rings[hoveredIndex]?.onClick ? "pointer" : void 0;
   const glowBlur = glow === true ? 6 : typeof glow === "number" ? glow : 0;
-  const svgTransform = startAngle !== 0 || direction === "counterclockwise" ? `rotate(${ -90 + startAngle}deg)${direction === "counterclockwise" ? " scaleX(-1)" : ""}` : void 0;
+  const svgTransform = startAngle !== 0 || direction === "counterclockwise" ? `rotate(${ -90 + (startAngle ?? 0)}deg)${direction === "counterclockwise" ? " scaleX(-1)" : ""}` : void 0;
   const content = /* @__PURE__ */ React.createElement(
     core.Box,
     {
-      ref,
-      ...getStyles("root", { style: { width: size, height: size } }),
-      role: "group",
-      "aria-label": "Progress rings",
-      ...others
+      ...getStyles("root", {
+        style: { width: size, height: size, cursor: containerCursor }
+      }),
+      ...others,
+      role: others.role ?? "group",
+      "aria-label": others["aria-label"] ?? (others["aria-labelledby"] ? void 0 : "Progress rings"),
+      onClick: hasInteractive ? handleContainerClick : others.onClick,
+      onMouseMove: hasInteractive ? handleContainerMouseMove : others.onMouseMove,
+      onMouseLeave: hasInteractive ? handleContainerMouseLeave : others.onMouseLeave,
+      "data-interactive": hasInteractive || void 0,
+      "data-hovered-ring": hoveredIndex ?? void 0
     },
+    gradientDefs.length > 0 && /* @__PURE__ */ React.createElement("svg", { "aria-hidden": true, style: { position: "absolute", width: 0, height: 0, overflow: "hidden" } }, /* @__PURE__ */ React.createElement("defs", null, gradientDefs.map((g) => /* @__PURE__ */ React.createElement(
+      "linearGradient",
+      {
+        key: g.id,
+        id: g.id,
+        gradientUnits: "objectBoundingBox",
+        gradientTransform: `rotate(${g.svgDeg}, 0.5, 0.5)`
+      },
+      /* @__PURE__ */ React.createElement("stop", { offset: "0%", stopColor: g.fromColor }),
+      /* @__PURE__ */ React.createElement("stop", { offset: "100%", stopColor: g.toColor })
+    )))),
     rings.map((ring, index) => {
       const {
         thickness: ringThicknessOverride,
@@ -151,6 +265,11 @@ const RingsProgress = core.factory((_props, ref) => {
         glowIntensity,
         glowColor,
         rootColor: ringRootColor,
+        onClick: ringOnClick,
+        onHover: _ringOnHover,
+        showValue: _ringShowValue,
+        formatValue: _ringFormatValue,
+        gradient: _ringGradient,
         ...ringSection
       } = ring;
       const parsedColor = core.parseThemeColor({ color: ring.color, theme });
@@ -162,22 +281,38 @@ const RingsProgress = core.factory((_props, ref) => {
       const ringGlowColor = glowColor ? core.parseThemeColor({ color: glowColor, theme }).value : parsedColor.value;
       const glowFilter = ringGlowBlur > 0 ? `drop-shadow(0 0 ${ringGlowBlur}px ${ringGlowColor})` : void 0;
       const { tooltip: _tooltip, ...sectionWithoutTooltip } = ringSection;
+      const sectionColor = ring.gradient ? `url(#rp-grad-${instanceId}-${index})` : sectionWithoutTooltip.color;
       const isPulsing = pulseOnComplete && pulsingRings[index];
+      const interactive = Boolean(ringOnClick);
+      const handleKeyDown = ringOnClick ? (event) => {
+        if (event.key === "Enter" || event.key === " ") {
+          event.preventDefault();
+          ringOnClick(ring, index);
+        }
+      } : void 0;
       return /* @__PURE__ */ React.createElement(
         core.RingProgress,
         {
           key: index,
-          rootColor: ringRootColor ? core.parseThemeColor({ color: ringRootColor, theme }).value : core.alpha(parsedColor.value, rootColorAlpha),
-          size: size - offsets[index] * 2,
+          rootColor: ringRootColor ? core.parseThemeColor({ color: ringRootColor, theme }).value : core.alpha(parsedColor.value, rootColorAlpha ?? 0.1),
+          size: (size ?? 0) - offsets[index] * 2,
           thickness: ringThickness,
           roundCaps: ringRoundCaps,
           transitionDuration: effectiveTransitionDuration,
-          sections: [{ ...sectionWithoutTooltip, value: effectiveValue }],
-          role: "progressbar",
+          sections: [
+            {
+              ...sectionWithoutTooltip,
+              value: effectiveValue,
+              color: sectionColor
+            }
+          ],
+          role: interactive ? "button" : "progressbar",
           "aria-valuenow": Math.round(ring.value),
           "aria-valuemin": 0,
           "aria-valuemax": 100,
           "aria-label": ringAriaLabel,
+          tabIndex: interactive ? 0 : void 0,
+          onKeyDown: handleKeyDown,
           styles: glowFilter || svgTransform ? {
             svg: {
               ...glowFilter ? { filter: glowFilter } : {},
@@ -196,6 +331,42 @@ const RingsProgress = core.factory((_props, ref) => {
         }
       );
     }),
+    (showValues || rings.some((r) => r.showValue)) && rings.map((ring, index) => {
+      const shouldShow = ring.showValue ?? showValues;
+      if (!shouldShow) {
+        return null;
+      }
+      const ringT = ring.thickness ?? thickness ?? 12;
+      const ringSize = (size ?? 120) - offsets[index] * 2;
+      const ringR = (ringSize * 0.9 - ringT * 2) / 2;
+      const clampedValue = Math.max(0, Math.min(100, ring.value));
+      const directionMultiplier = direction === "counterclockwise" ? -1 : 1;
+      const endAngleDeg = (startAngle ?? 0) + clampedValue / 100 * 360 * directionMultiplier;
+      const angleRad = endAngleDeg * Math.PI / 180;
+      const center = (size ?? 120) / 2;
+      const x = center + ringR * Math.sin(angleRad);
+      const y = center - ringR * Math.cos(angleRad);
+      const formatter = ring.formatValue ?? formatValue ?? ((v) => `${Math.round(v)}%`);
+      const labelColor = core.parseThemeColor({ color: ring.color, theme }).value;
+      return /* @__PURE__ */ React.createElement(
+        core.Box,
+        {
+          key: `value-${index}`,
+          ...getStyles("valueLabel", {
+            style: {
+              position: "absolute",
+              left: x,
+              top: y,
+              transform: "translate(-50%, -50%)",
+              pointerEvents: "none",
+              color: labelColor
+            }
+          }),
+          "data-ring-index": index
+        },
+        formatter(ring.value)
+      );
+    }),
     label && /* @__PURE__ */ React.createElement(core.Box, { ...getStyles("label") }, label)
   );
   if (withTooltip) {