Progress Ring

1"use client"
2 
3import * as React from "react"
4 
5import { cn } from "@/lib/utils"
6import { useSpring, type SpringOptions } from "@/registry/lib/use-spring"
7 
8export interface ProgressRingProps extends Omit<
9  React.ComponentProps<"div">,
10  "children"
11> {
12  /** Where the ring is now. */
13  value: number
14  /** What a full ring means. */
15  max?: number
16  /** Outside diameter in pixels. */
17  size?: number
18  /** Stroke width in pixels. */
19  thickness?: number
20  /** How the value travels when it changes. */
21  spring?: SpringOptions
22  /** Print the number in the middle. */
23  showValue?: boolean
24  /** Turns the value into the text in the middle. */
25  format?: (value: number) => string
26  /** Accessible name. Give it one if the ring is the only label. */
27  label?: string
28  /** Render the ring at its value without animating to it. */
29  disabled?: boolean
30  /** Children sit in the middle instead of the number. */
31  center?: React.ReactNode
32}
33 
34/** The box the ring is drawn in. Every measurement is a share of this. */
35const BOX = 100
36 
37const clamp = (value: number, max: number) =>
38  Math.min(Math.max(value, 0), max) / (max || 1)
39 
40/**
41 * A ring that fills to a value, on a spring.
42 *
43 * The arc is drawn by walking the stroke's own dash offset around the circle.
44 * That is a paint rather than a composite, which is the one place this steps
45 * outside transform and opacity, and there is no way to draw an arc without it.
46 * It stays cheap because only the stroke is repainted, never the layout.
47 *
48 * The value springs rather than tweens, so a target that changes while the ring
49 * is still moving keeps the speed it already had. A progress ring that restarts
50 * from a standstill every time the number updates is the tell.
51 */
52export function ProgressRing({
53  value,
54  max = 100,
55  size = 120,
56  thickness = 10,
57  spring,
58  showValue = true,
59  format,
60  label,
61  disabled = false,
62  center,
63  className,
64  style,
65  ...props
66}: ProgressRingProps) {
67  const arcRef = React.useRef<SVGCircleElement>(null)
68  const textRef = React.useRef<HTMLSpanElement>(null)
69 
70  const radius = (BOX - thickness) / 2
71  const circumference = 2 * Math.PI * radius
72  const target = clamp(value, max)
73 
74  const paint = React.useCallback(
75    ({ fill = 0 }: Record<string, number>) => {
76      const arc = arcRef.current
77      if (arc) {
78        arc.style.strokeDashoffset = `${circumference * (1 - fill)}`
79      }
80 
81      const text = textRef.current
82      if (text) {
83        const shown = fill * max
84// … truncated