{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "zeno-progress", "type": "registry:ui", "title": "Zeno Progress", "description": "A progress bar that closes half the remaining gap at every step, so it never reaches the end while work is still running. The last stretch becomes a ruler that keeps zooming into itself, and the gap snaps shut the moment the real result arrives.", "author": "KeyframeUI ", "categories": [ "progress", "loading", "ai", "canvas" ], "docs": "Live preview, examples and props: https://keyframeui.com/components/zeno-progress", "dependencies": [ "motion", "clsx", "tailwind-merge" ], "registryDependencies": [ "utils" ], "files": [ { "path": "components/ui/zeno-progress.tsx", "type": "registry:ui", "content": "\"use client\";\n\nimport * as React from \"react\";\nimport {\n AnimatePresence,\n animate,\n motion,\n useMotionValue,\n useReducedMotion,\n} from \"motion/react\";\n\nimport { cn } from \"@/lib/utils\";\n\n/**\n * Keep:\n * - One rAF loop draws the bar on a canvas and writes the percentage and `aria-valuenow` straight\n * to the DOM, so a run never re-renders except when the step label changes.\n * - The gap is tracked as log10 and only ever halves, so the fill never reaches the end on its\n * own; only `done` closes it, on a spring with `bounce: 0` that never overshoots.\n * - The zoom window freezes when `done` arrives, so the snap runs through the magnified gap.\n * - The percentage is floored and never reads 100% until the fill has landed.\n * - Reduced motion drops the ruler and zoom: past 90% the track breathes instead, `done` jumps the\n * fill and labels only fade.\n */\nconst TIMING = {\n /** Each halving of the gap, in ms (the `interval` prop). */\n interval: 1000,\n /** Halvings the fill takes to get up to speed from a standstill. */\n rampUp: 0.35,\n /** The gap closing when done arrives, over `snapDuration`. */\n snap: { type: \"spring\", bounce: 0 },\n /** How long the snap takes, in seconds (the `snapDuration` prop, the spring's visualDuration). */\n snapDuration: 0.36,\n /** The ticks flashing and sinking after the snap, in seconds. */\n clear: 0.62,\n /** Labels sliding. */\n roll: { type: \"spring\", visualDuration: 0.34, bounce: 0 },\n /** Labels fading under reduced motion, in seconds. */\n fade: { duration: 0.16 },\n /** The fill heading back for a new run, in seconds, and its curve. */\n rewind: { duration: 0.5, ease: [0.22, 1, 0.36, 1] },\n /** One breath of the reduced-motion gap, in seconds. */\n breathe: 2.8,\n} as const;\n\n/* ─────────────────────────────────────────────────────────\n * ZENO PROGRESS STORYBOARD\n *\n * run the fill closes half of what's left every\n * `interval`, easing out of a standstill, so it\n * reads as steady work early and a crawl late. It\n * never reaches the end on its own\n * ruler past ~90% the gap grows a ruler: ticks rise out\n * of the track across the last stretch\n * zoom the last stretch becomes a magnifier with a fixed\n * width. The gap is re-scaled to fill most of it,\n * so the ruler zooms in toward the end point at a\n * steady rate: ticks stream out from the end, grow\n * as they spread, a finer tier rises between them\n * and the fill eats them as they pass its edge. The\n * label gains a decimal every tenfold zoom\n * done the zoom holds, the fill runs through the gap to\n * the end on a spring with no overshoot, the ticks\n * flash once and sink, and the label rolls to the\n * done text\n * again `done` back to false: the fill rewinds to the\n * start and a new run begins\n * reduced no ruler or zoom. Past 90% the gap breathes\n * slowly instead, and done is a plain jump\n * ───────────────────────────────────────────────────────── */\n\nconst BAR = {\n height: 6, // px track\n canvas: 22, // px drawing area: ticks reach above and below the track\n tick: [4, 18], // px tick height, finest to tallest\n minSpacing: 2.5, // px between ticks before a finer tier shows\n tallSpacing: 90, // px between ticks at which they reach full height\n eat: 18, // px past the fill's edge over which ticks are eaten\n lens: [0.24, 48, 160], // magnifier: share of the track, min px, max px\n gapShare: 0.55, // share of the magnifier the zoomed gap keeps\n rulerFrom: 0.12, // gap left when the ruler starts to rise\n rulerTo: 0.07, // gap left when it's fully up\n maxDecimals: 6,\n} as const;\n\nconst LOG2 = Math.log10(2);\nconst clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));\nconst smoothstep = (a: number, b: number, v: number) => {\n const t = clamp((v - a) / (b - a), 0, 1);\n return t * t * (3 - 2 * t);\n};\n\n/** Percent left to go, shown at a precision that keeps two digits of it moving. */\nfunction formatPercent(logGap: number, maxDecimals: number) {\n const decimals = clamp(Math.floor(-(logGap + 2)) + 2, 0, maxDecimals);\n const f = 10 ** decimals;\n let shown = Math.floor((100 - 100 * 10 ** logGap) * f) / f;\n // Floats round 99.99999999… up to 100; never claim the end early.\n if (shown >= 100) shown = 100 - 1 / f;\n return { text: `${shown.toFixed(decimals)}%`, decimals };\n}\n\n/** Halvings of the gap so far, easing out of a standstill. */\nconst halvingsAt = (ms: number, interval: number) => {\n const t = Math.max(0, ms / interval);\n return (t * t) / (t + TIMING.rampUp);\n};\n\n/** Width of the magnifier at the end of a track this wide. */\nconst lensOf = (width: number) => clamp(width * BAR.lens[0], BAR.lens[1], BAR.lens[2]);\n\n/**\n * The window the lens shows, as log10 of a share of the bar: the lens at 1:1,\n * then the gap over `gapShare` of it, joined by a soft minimum so the zoom\n * eases in instead of starting with a kink.\n */\nfunction zoomFor(gap: number, width: number, zooming: boolean) {\n const z0 = Math.log10(lensOf(width) / Math.max(width, 1));\n if (!zooming) return z0;\n const u = gap - Math.log10(BAR.gapShare) - z0;\n return z0 + u - Math.log10(1 + 10 ** (3 * u)) / 3;\n}\n\ntype Geometry = { width: number; dpr: number };\n\n/** Everything a frame needs, kept out of React so a run never re-renders. */\ntype Run = {\n /** performance.now() the run began; null until its first frame. */\n start: number | null;\n /** log10 of the gap and the zoom window at the moment `done` arrived. */\n doneGap: number | null;\n doneZoom: number;\n doneDecimals: number;\n /** When the fill reached the end, for the ticks' flash. */\n landed: number | null;\n completed: boolean;\n /** Ruler height when done arrived, so an early finish has no ticks to flash. */\n doneRuler: number;\n step: number;\n value: number;\n text: string;\n};\n\nconst freshRun = (): Run => ({\n start: null,\n doneGap: null,\n doneZoom: 0,\n doneDecimals: 0,\n landed: null,\n completed: false,\n doneRuler: 0,\n step: 0,\n value: 0,\n text: \"0%\",\n});\n\nexport interface ZenoProgressProps {\n /** The work is finished. The parent owns it: the bar only gets there when this turns true. */\n done?: boolean;\n /** Labels shown in turn as the fill moves. The last one holds through the crawl. */\n steps?: string[];\n /** Fixed label while running. Overrides `steps`. */\n label?: string;\n /** Label once done. */\n doneLabel?: string;\n /** Milliseconds for each halving of the gap. */\n interval?: number;\n /** Seconds the gap takes to snap shut once `done` arrives, on a spring that never overshoots. */\n snapDuration?: number;\n /** Zoom into the gap with a ruler past 90%. Off, the bar just crawls. */\n ruler?: boolean;\n /** Called once the fill reaches the end after `done`. */\n onComplete?: () => void;\n /** Classes that set the bar's color (a `text-*` color). The track and ticks are drawn from it. */\n barClassName?: string;\n className?: string;\n}\n\nexport function ZenoProgress({\n done = false,\n steps,\n label,\n doneLabel = \"Done\",\n interval = TIMING.interval,\n snapDuration = TIMING.snapDuration,\n ruler = true,\n onComplete,\n barClassName,\n className,\n}: ZenoProgressProps) {\n const reduced = useReducedMotion() ?? false;\n const rootRef = React.useRef(null);\n const canvasRef = React.useRef(null);\n const percentRef = React.useRef(null);\n\n const snap = useMotionValue(done ? 1 : 0);\n const rewind = useMotionValue(0);\n const [step, setStep] = React.useState(0);\n // A new run starts back on the first step.\n const [lastDone, setLastDone] = React.useState(done);\n if (lastDone !== done) {\n setLastDone(done);\n if (!done) setStep(0);\n }\n\n const stepCount = steps?.length ?? 0;\n const options = React.useRef({ interval, snapDuration, ruler, reduced, stepCount, onComplete });\n React.useEffect(() => {\n options.current = { interval, snapDuration, ruler, reduced, stepCount, onComplete };\n });\n\n const run = React.useRef(freshRun());\n const geometry = React.useRef({ width: 0, dpr: 1 });\n const color = React.useRef(\"#000\");\n const frame = React.useRef(0);\n const wake = React.useRef<() => void>(() => {});\n const seenDone = React.useRef(null);\n\n // The frame loop: reads the clock and the springs, draws the bar and writes the label.\n React.useEffect(() => {\n const canvas = canvasRef.current;\n const root = rootRef.current;\n const percent = percentRef.current;\n if (!canvas || !root || !percent) return;\n const ctx = canvas.getContext(\"2d\");\n if (!ctx) return;\n\n let colorAge = Infinity;\n const readColor = () => {\n // Passed to the canvas as-is: Tailwind's colors are oklch().\n color.current = getComputedStyle(canvas).color;\n };\n\n const draw = (now: number) => {\n frame.current = 0;\n const { interval, ruler, reduced, stepCount, onComplete } = options.current;\n const r = run.current;\n const { width: W, dpr } = geometry.current;\n if (r.start === null) r.start = now;\n\n // Gap left, in log10 so it can shrink past what a float can hold.\n const halvings = halvingsAt(now - r.start, interval);\n const liveGap = -halvings * LOG2;\n\n const lens = lensOf(W);\n const z0 = Math.log10(lens / Math.max(W, 1));\n const zooming = ruler && !reduced;\n\n const s = snap.get();\n let gap: number;\n let zoom: number;\n if (r.doneGap === null) {\n gap = liveGap;\n zoom = zoomFor(gap, W, zooming);\n } else {\n gap = s >= 1 ? -Infinity : r.doneGap + Math.log10(1 - s);\n zoom = r.doneZoom;\n }\n const g = 10 ** gap;\n const z = 10 ** zoom;\n\n // Fill edge: the main stretch shows [0, 1 - z], the lens shows [1 - z, 1].\n const split = W - lens;\n const edge = g < z ? split + lens * (1 - g / z) : ((1 - g) / Math.max(1 - z, 1e-9)) * split;\n const fill = Math.max(edge, rewind.get() * W);\n\n // The ruler rises with the fill and, after done, flashes and sinks.\n const liveRuler = zooming ? smoothstep(BAR.rulerFrom, BAR.rulerTo, 10 ** liveGap) : 0;\n const rulerUp = r.doneGap === null ? liveRuler : r.doneRuler;\n if (r.doneGap !== null && s > 0.985 && r.landed === null) r.landed = now;\n const clearing = r.landed === null ? 0 : clamp((now - r.landed) / 1000 / TIMING.clear, 0, 1);\n const flash = clearing < 0.22 ? clearing / 0.22 : 1 - (clearing - 0.22) / 0.78;\n const sink = 1 - clearing * clearing;\n\n // Label and value.\n let text: string;\n let value: number;\n if (r.doneGap !== null && (r.landed !== null || s >= 1)) {\n text = \"100%\";\n value = 100;\n } else {\n const max = reduced ? 0 : r.doneGap === null ? BAR.maxDecimals : r.doneDecimals;\n text = formatPercent(gap, max).text;\n value = Math.floor(100 * (1 - g));\n }\n if (text !== r.text) {\n r.text = text;\n percent.textContent = text;\n }\n if (value !== r.value) {\n r.value = value;\n root.setAttribute(\"aria-valuenow\", String(value));\n }\n if (stepCount > 1 && r.doneGap === null) {\n const next = Math.min(stepCount - 1, Math.floor(halvings / (Math.log2(10) / (stepCount - 1))));\n if (next !== r.step) {\n r.step = next;\n setStep(next);\n }\n }\n if (r.landed !== null && !r.completed) {\n r.completed = true;\n onComplete?.();\n }\n\n // Draw.\n if (colorAge++ > 30) {\n readColor();\n colorAge = 0;\n }\n const H = BAR.canvas;\n const cy = H / 2;\n const T = BAR.height;\n ctx.setTransform(dpr, 0, 0, dpr, 0, 0);\n ctx.clearRect(0, 0, W, H);\n if (W <= 0) return;\n\n const breathing = reduced && r.doneGap === null && 10 ** liveGap < 0.1;\n const breath = breathing ? 0.5 - 0.5 * Math.cos(((now - r.start) / 1000 / TIMING.breathe) * Math.PI * 2) : 0;\n ctx.save();\n ctx.beginPath();\n ctx.roundRect(0, cy - T / 2, W, T, T / 2);\n ctx.clip();\n ctx.fillStyle = color.current;\n ctx.globalAlpha = 0.12 + 0.16 * breath;\n ctx.fillRect(0, 0, W, H);\n ctx.globalAlpha = 1;\n ctx.fillRect(0, 0, fill, H);\n ctx.restore();\n\n const height = rulerUp * sink;\n if (height > 0.001) {\n const windowPx = lens / (z * 100); // px per percent inside the lens\n // Tiers like a ruler's: tenths, halves, wholes, then the next decade up.\n // A tick belongs to the coarsest tier it lands on, and its height and\n // opacity follow that tier's spacing, so every tick grows continuously.\n const decade = Math.floor(Math.log10(BAR.minSpacing / windowPx));\n const tiers: number[] = [];\n for (let level = decade; level <= decade + 3; level++) tiers.push(10 ** level, 5 * 10 ** level);\n const marks: { x: number; h: number; a: number }[] = [];\n tiers.forEach((unit, k) => {\n const spacing = unit * windowPx;\n if (spacing < BAR.minSpacing || spacing > lens) return;\n const every = k + 1 < tiers.length ? Math.round(tiers[k + 1] / unit) : Infinity;\n const grown = clamp(Math.log10(spacing / BAR.minSpacing) / Math.log10(BAR.tallSpacing / BAR.minSpacing), 0, 1);\n const h = BAR.tick[0] + (BAR.tick[1] - BAR.tick[0]) * grown;\n const a = smoothstep(BAR.minSpacing, BAR.minSpacing * 3, spacing);\n for (let j = 1; j * spacing <= lens + 0.5; j++) {\n if (j % every !== 0) marks.push({ x: W - j * spacing, h, a });\n }\n });\n marks.push({ x: W - 0.75, h: BAR.tick[1], a: 1 }); // the end post\n // The lens' left edge, cut into the fill once the zoom is under way.\n const zoomed = smoothstep(0, 0.3, z0 - zoom);\n\n ctx.fillStyle = color.current;\n for (const m of marks) {\n if (m.x < split - 0.5) continue;\n const eaten = m.x <= fill ? 1 - clamp((fill - m.x) / BAR.eat, 0, 1) : 1;\n // Over the fill only the ends that stick out of the track show.\n const alpha = m.a * Math.max(0.6 * eaten, flash);\n if (alpha <= 0.01) continue;\n const h = m.h * height;\n ctx.globalAlpha = alpha;\n ctx.fillRect(Math.round(m.x * dpr) / dpr - 0.5, cy - h / 2, 1, h);\n }\n if (zoomed > 0.01 && fill > split) {\n ctx.globalCompositeOperation = \"destination-out\";\n ctx.globalAlpha = zoomed * (1 - clearing);\n ctx.fillRect(Math.round(split * dpr) / dpr - 1, cy - T / 2, 1.5, T);\n }\n ctx.globalCompositeOperation = \"source-over\";\n ctx.globalAlpha = 1;\n }\n\n const settled = r.doneGap !== null && (r.landed !== null ? clearing >= 1 : false) && rewind.get() === 0;\n if (!settled) frame.current = requestAnimationFrame(draw);\n };\n\n wake.current = () => {\n if (!frame.current) frame.current = requestAnimationFrame(draw);\n };\n\n const observer = new ResizeObserver(([entry]) => {\n const dpr = window.devicePixelRatio || 1;\n const width = entry.contentRect.width;\n geometry.current = { width, dpr };\n canvas.width = Math.round(width * dpr);\n canvas.height = Math.round(BAR.canvas * dpr);\n colorAge = Infinity;\n wake.current();\n });\n observer.observe(canvas);\n wake.current();\n\n return () => {\n observer.disconnect();\n cancelAnimationFrame(frame.current);\n frame.current = 0;\n wake.current = () => {};\n };\n }, [snap, rewind]);\n\n // `done` drives the run: arriving snaps the gap shut, leaving starts a new run.\n React.useEffect(() => {\n const previous = seenDone.current;\n seenDone.current = done;\n const r = run.current;\n if (previous === done) return;\n\n if (done) {\n if (previous === null) {\n // Mounted finished: show the full bar, nothing to animate.\n Object.assign(r, { doneGap: -Infinity, landed: -Infinity, completed: true, text: \"100%\", value: 100 });\n snap.jump(1);\n if (percentRef.current) percentRef.current.textContent = \"100%\";\n wake.current();\n return;\n }\n const { interval, snapDuration, ruler, reduced } = options.current;\n const gap = r.start === null ? 0 : -halvingsAt(performance.now() - r.start, interval) * LOG2;\n r.doneZoom = zoomFor(gap, geometry.current.width, ruler && !reduced);\n r.doneGap = gap;\n r.doneDecimals = formatPercent(gap, reduced ? 0 : BAR.maxDecimals).decimals;\n r.doneRuler = ruler && !reduced ? smoothstep(BAR.rulerFrom, BAR.rulerTo, 10 ** gap) : 0;\n if (reduced) snap.jump(1);\n else animate(snap, 1, { ...TIMING.snap, visualDuration: snapDuration });\n wake.current();\n return;\n }\n\n // A new run. Rewind from wherever the last one left the fill.\n const from = previous === null ? 0 : r.doneGap === null ? 0 : 1;\n run.current = freshRun();\n snap.jump(0);\n if (percentRef.current) percentRef.current.textContent = \"0%\";\n rootRef.current?.setAttribute(\"aria-valuenow\", \"0\");\n if (from > 0 && !options.current.reduced) {\n rewind.jump(from);\n animate(rewind, 0, TIMING.rewind);\n } else {\n rewind.jump(0);\n }\n wake.current();\n }, [done, snap, rewind]);\n\n const text = done ? doneLabel : (label ?? steps?.[Math.min(step, stepCount - 1)] ?? \"Working\");\n const slide = reduced ? { opacity: 0 } : { y: \"100%\", opacity: 0 };\n const leave = reduced ? { opacity: 0 } : { y: \"-100%\", opacity: 0 };\n\n return (\n \n
\n \n \n \n {text}\n \n \n \n \n 0%\n \n
\n \n \n {done ? doneLabel : \"\"}\n \n \n );\n}\n" } ] }