{
  "schemaVersion": 1,
  "target": "react",
  "name": "progress",
  "version": "0.1.0",
  "category": "feedback",
  "title": "Progress",
  "description": "A progress bar with label and value, an indeterminate band, a segmented steps bar, and a circular ring, all on Base UI Progress.",
  "tags": [
    "progress bar",
    "loading",
    "upload",
    "steps",
    "stepper",
    "ring",
    "circular progress",
    "indeterminate"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {
    "@base-ui/react": "^1.9.0"
  },
  "registryDependencies": [
    {
      "name": "button",
      "version": "0.2.1"
    }
  ],
  "docsPath": "/components/progress",
  "props": [
    {
      "name": "value",
      "type": "number | null",
      "description": "Current value of Progress and ProgressRing. null makes them indeterminate. For ProgressSteps it is the number of finished steps."
    },
    {
      "name": "min / max",
      "type": "number",
      "default": "0 / 100",
      "description": "Range of the value for Progress and ProgressRing."
    },
    {
      "name": "label",
      "type": "ReactNode",
      "description": "Names the progressbar. Visible above the bar and the steps; visually hidden on the ring. Without it, pass aria-label."
    },
    {
      "name": "tone",
      "type": "\"neutral\" | \"info\" | \"success\" | \"warning\" | \"danger\"",
      "default": "\"neutral\"",
      "description": "Fill hue. Neutral is monochrome; info suits running work, the others outcomes."
    },
    {
      "name": "showValue",
      "type": "boolean",
      "description": "Shows the formatted value. On by default for a labeled bar with a value and for the lg ring."
    },
    {
      "name": "valueText",
      "type": "ReactNode",
      "description": "Replaces the visible value on Progress, such as \"48 of 120 MB\". Pair it with getAriaValueText."
    },
    {
      "name": "format / getAriaValueText",
      "type": "Intl.NumberFormatOptions / (formatted, value) => string",
      "description": "Formats the value text and the spoken aria-valuetext."
    },
    {
      "name": "size",
      "type": "\"sm\" | \"md\" (Progress) | \"sm\" | \"md\" | \"lg\" (ProgressRing)",
      "default": "\"md\"",
      "description": "Bar height 4 or 6px; ring diameter 20, 40, or 64px."
    },
    {
      "name": "ProgressSteps total / steps",
      "type": "number / string[]",
      "description": "Number of segments, and optional step names; the current step's name is shown and spoken with the count."
    }
  ],
  "accessibility": [
    "Every variant renders role=\"progressbar\" through Base UI Progress with aria-valuenow, aria-valuemin, aria-valuemax, and aria-valuetext; the label is linked with aria-labelledby.",
    "Indeterminate bars and rings omit aria-valuenow, so screen readers announce indeterminate progress.",
    "ProgressSteps speaks the position and the step name, for example \"Step 2 of 4: Connect repository\".",
    "The fill moves with transform (translate and scale) only; the ring animates stroke-dashoffset. All value transitions are removed under reduced motion.",
    "Under reduced motion the indeterminate band is replaced by a still dotted fill and the indeterminate ring holds a still arc.",
    "Color is never the only signal: the value text, step count, or label carries the state."
  ],
  "states": [
    "determinate",
    "indeterminate",
    "complete",
    "steps",
    "ring"
  ],
  "files": [
    {
      "path": "ui/progress.tsx",
      "content": "\"use client\";\n\nimport { Progress as BaseProgress } from \"@base-ui/react/progress\";\nimport { type ReactNode, useEffect, useRef } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\n/*\n * Progress on Base UI Progress (role=\"progressbar\", aria-valuenow/min/max/valuetext, and the\n * label wired through aria-labelledby). The fill moves with transform only: the bar is full\n * width and slides in from the left, so value changes never trigger layout.\n */\n\nexport type ProgressTone = \"neutral\" | \"info\" | \"success\" | \"warning\" | \"danger\";\n\n// The fill is drawn in currentColor, so one class sets the hue for bar, segments, and ring.\nconst tones: Record<ProgressTone, string> = {\n  neutral: \"text-zinc-950 dark:text-white\",\n  info: \"text-sky-500 dark:text-sky-400\",\n  success: \"text-emerald-500 dark:text-emerald-400\",\n  warning: \"text-amber-500 dark:text-amber-400\",\n  danger: \"text-red-500 dark:text-red-400\",\n};\n\nconst track = \"bg-zinc-950/[0.07] dark:bg-white/[0.1]\";\nconst fillMotion = \"transition-[translate,scale,opacity] duration-500 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none\";\n\nfunction percentOf(value: number, min: number, max: number) {\n  if (max <= min) return 0;\n  return Math.min(100, Math.max(0, ((value - min) / (max - min)) * 100));\n}\n\n/** Slides an indeterminate band across its track. Shared start time keeps several bars in step. */\nfunction useIndeterminate(active: boolean) {\n  const ref = useRef<HTMLSpanElement>(null);\n  useEffect(() => {\n    const band = ref.current;\n    if (!active || !band || typeof band.animate !== \"function\") return;\n    const motion = window.matchMedia(\"(prefers-reduced-motion: reduce)\");\n    let animation: Animation | undefined;\n    const start = () => {\n      animation?.cancel();\n      animation = undefined;\n      if (motion.matches) return;\n      animation = band.animate(\n        [{ transform: \"translateX(-100%)\" }, { transform: \"translateX(250%)\" }],\n        { duration: 1600, iterations: Infinity, easing: \"cubic-bezier(0.65, 0, 0.35, 1)\" },\n      );\n      animation.startTime = 0;\n    };\n    start();\n    motion.addEventListener(\"change\", start);\n    return () => {\n      animation?.cancel();\n      motion.removeEventListener(\"change\", start);\n    };\n  }, [active]);\n  return ref;\n}\n\ninterface SharedProps {\n  /** Current value. `null` makes it indeterminate (work is happening, amount unknown). */\n  value: number | null;\n  min?: number;\n  max?: number;\n  /** Visible label above the bar; it also names the progressbar. Without it, pass `aria-label`. */\n  label?: ReactNode;\n  /** Fill hue. Neutral is monochrome; use info for running work and the other tones for outcomes. */\n  tone?: ProgressTone;\n  /** Formats the value text and `aria-valuetext`, for example `{ style: \"unit\", unit: \"megabyte\" }`. */\n  format?: Intl.NumberFormatOptions;\n  /** Custom spoken value, e.g. `(formatted, value) => \\`${value} of 12 files\\``. */\n  getAriaValueText?: (formattedValue: string, value: number | null) => string;\n  className?: string;\n  \"aria-label\"?: string;\n  \"aria-labelledby\"?: string;\n}\n\nexport interface ProgressProps extends SharedProps {\n  /** Shows the formatted value at the end of the label row. Defaults to on when there is a label and a value. */\n  showValue?: boolean;\n  /** Replaces the value text, e.g. \"48 of 120 MB\". */\n  valueText?: ReactNode;\n  /** Track height: 4px or 6px. */\n  size?: \"sm\" | \"md\";\n}\n\n/** A determinate or indeterminate progress bar with an optional label and value. */\nexport function Progress({\n  value,\n  min = 0,\n  max = 100,\n  label,\n  tone = \"neutral\",\n  showValue,\n  valueText,\n  size = \"md\",\n  className,\n  ...props\n}: ProgressProps) {\n  const indeterminate = value === null;\n  const band = useIndeterminate(indeterminate);\n  const pct = indeterminate ? 0 : percentOf(value, min, max);\n  const valueVisible = showValue ?? (label != null && !indeterminate);\n\n  return (\n    <BaseProgress.Root value={value} min={min} max={max} className={cx(\"grid w-full gap-2\", className)} {...props}>\n      {label != null || valueVisible ? (\n        <div className=\"flex items-baseline justify-between gap-4 text-sm leading-5\">\n          {label != null ? (\n            <BaseProgress.Label className=\"min-w-0 truncate font-medium text-zinc-950 dark:text-white\">{label}</BaseProgress.Label>\n          ) : (\n            <span />\n          )}\n          {valueVisible ? (\n            valueText != null ? (\n              <span className=\"shrink-0 font-mono text-xs text-zinc-500 tabular-nums\">{valueText}</span>\n            ) : (\n              <BaseProgress.Value className=\"shrink-0 font-mono text-xs text-zinc-500 tabular-nums\" />\n            )\n          ) : null}\n        </div>\n      ) : null}\n      <BaseProgress.Track\n        className={cx(\"relative w-full overflow-hidden rounded-full\", size === \"sm\" ? \"h-1\" : \"h-1.5\", track, tones[tone])}\n      >\n        {indeterminate ? (\n          <>\n            <span\n              ref={band}\n              style={{ transform: \"translateX(-100%)\" }}\n              className=\"absolute inset-y-0 left-0 w-2/5 rounded-full bg-current motion-reduce:hidden\"\n            />\n            {/* Reduced motion: a still dotted fill says \"in progress, amount unknown\" without moving. */}\n            <span className=\"absolute inset-0 hidden bg-[radial-gradient(circle,currentColor_1px,transparent_1.5px)] bg-size-[6px_100%] bg-repeat-x opacity-50 motion-reduce:block\" />\n          </>\n        ) : (\n          <span\n            data-slot=\"progress-fill\"\n            className={cx(\"absolute inset-0 rounded-full bg-current\", fillMotion)}\n            style={{ translate: `${pct - 100}% 0` }}\n          />\n        )}\n      </BaseProgress.Track>\n    </BaseProgress.Root>\n  );\n}\n\nexport interface ProgressStepsProps extends Omit<SharedProps, \"value\" | \"min\" | \"max\" | \"format\"> {\n  /** Number of steps. */\n  total: number;\n  /** Steps finished so far (0 to total). The next one is drawn as the current step. */\n  value: number;\n  /** Name of each step. The current step's name is shown and spoken with the count. */\n  steps?: string[];\n}\n\n/** A segmented bar for multi-step flows: finished segments are filled, the current one is tinted. */\nexport function ProgressSteps({ total, value, steps, label, tone = \"neutral\", className, getAriaValueText, ...props }: ProgressStepsProps) {\n  const done = Math.min(total, Math.max(0, Math.round(value)));\n  const complete = done >= total;\n  const currentIndex = Math.min(done, total - 1);\n  const currentName = steps?.[currentIndex];\n  const position = complete ? `All ${total} steps complete` : `Step ${done + 1} of ${total}`;\n  const spoken = currentName && !complete ? `${position}: ${currentName}` : position;\n\n  return (\n    <BaseProgress.Root\n      value={done}\n      min={0}\n      max={total}\n      getAriaValueText={getAriaValueText ?? (() => spoken)}\n      className={cx(\"grid w-full gap-2\", className)}\n      {...props}\n    >\n      <div className=\"flex items-baseline justify-between gap-4 text-sm leading-5\">\n        {label != null ? (\n          <BaseProgress.Label className=\"min-w-0 truncate font-medium text-zinc-950 dark:text-white\">{label}</BaseProgress.Label>\n        ) : currentName && !complete ? (\n          <span className=\"min-w-0 truncate font-medium text-zinc-950 dark:text-white\">{currentName}</span>\n        ) : (\n          <span />\n        )}\n        <span aria-hidden=\"true\" className=\"shrink-0 text-xs text-zinc-500 tabular-nums\">\n          {complete ? \"Done\" : `Step ${done + 1} of ${total}`}\n        </span>\n      </div>\n      <div aria-hidden=\"true\" className={cx(\"flex gap-1\", tones[tone])}>\n        {Array.from({ length: total }, (_, i) => {\n          const state = i < done ? \"complete\" : i === done ? \"current\" : \"pending\";\n          return (\n            <span key={i} data-state={state} className={cx(\"relative h-1.5 flex-1 overflow-hidden rounded-full\", track)}>\n              <span\n                className={cx(\n                  \"absolute inset-0 origin-left rounded-full bg-current\",\n                  fillMotion,\n                  state === \"complete\" ? \"scale-x-100 opacity-100\" : state === \"current\" ? \"scale-x-100 opacity-30\" : \"scale-x-0 opacity-0\",\n                )}\n              />\n            </span>\n          );\n        })}\n      </div>\n      {label != null && currentName && !complete ? <p className=\"text-xs leading-4 text-zinc-500\">{currentName}</p> : null}\n    </BaseProgress.Root>\n  );\n}\n\nconst ringSizes = { sm: { px: 20, stroke: 2.25 }, md: { px: 40, stroke: 3 }, lg: { px: 64, stroke: 4 } } as const;\n\nexport interface ProgressRingProps extends SharedProps {\n  /** 20px (inline, no value), 40px, or 64px. */\n  size?: keyof typeof ringSizes;\n  /** Shows the value in the center (md and lg). Defaults to on for lg. */\n  showValue?: boolean;\n  /** Replaces the centered content, e.g. an icon or \"3/8\". */\n  children?: ReactNode;\n}\n\n/**\n * A circular progress ring. The label is visually hidden (the ring has no room for it) but\n * names the progressbar; place visible text beside the ring when you need it.\n */\nexport function ProgressRing({\n  value,\n  min = 0,\n  max = 100,\n  label,\n  tone = \"neutral\",\n  size = \"md\",\n  showValue,\n  children,\n  className,\n  ...props\n}: ProgressRingProps) {\n  const indeterminate = value === null;\n  const { px, stroke } = ringSizes[size];\n  const r = (px - stroke) / 2;\n  const circumference = 2 * Math.PI * r;\n  const pct = indeterminate ? 25 : percentOf(value, min, max);\n  const valueVisible = (showValue ?? size === \"lg\") && size !== \"sm\" && !indeterminate;\n\n  return (\n    <BaseProgress.Root\n      value={value}\n      min={min}\n      max={max}\n      className={cx(\"relative inline-flex shrink-0 items-center justify-center\", tones[tone], className)}\n      style={{ width: px, height: px }}\n      {...props}\n    >\n      {label != null ? <BaseProgress.Label className=\"sr-only\">{label}</BaseProgress.Label> : null}\n      <svg\n        aria-hidden=\"true\"\n        width={px}\n        height={px}\n        viewBox={`0 0 ${px} ${px}`}\n        fill=\"none\"\n        className={cx(\"-rotate-90\", indeterminate && \"motion-safe:animate-spin motion-safe:[animation-duration:1.2s]\")}\n      >\n        <circle cx={px / 2} cy={px / 2} r={r} stroke=\"currentColor\" strokeWidth={stroke} className=\"opacity-[0.12] dark:opacity-[0.16]\" />\n        <circle\n          cx={px / 2}\n          cy={px / 2}\n          r={r}\n          stroke=\"currentColor\"\n          strokeWidth={stroke}\n          strokeLinecap=\"round\"\n          strokeDasharray={circumference}\n          strokeDashoffset={circumference * (1 - pct / 100)}\n          className={cx(\n            \"transition-[stroke-dashoffset] duration-500 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none\",\n            !indeterminate && pct === 0 && \"opacity-0\",\n          )}\n        />\n      </svg>\n      {children != null ? (\n        <span className=\"absolute inset-0 flex items-center justify-center text-zinc-950 dark:text-white\">{children}</span>\n      ) : valueVisible ? (\n        <BaseProgress.Value\n          className={cx(\n            \"absolute inset-0 flex items-center justify-center font-mono font-medium text-zinc-950 tabular-nums dark:text-white\",\n            size === \"lg\" ? \"text-sm\" : \"text-[10px]\",\n          )}\n        />\n      ) : null}\n    </BaseProgress.Root>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { useEffect, useState } from \"react\";\nimport { Button } from \"@/components/shaken/ui/button\";\nimport { Progress, ProgressRing, ProgressSteps } from \"@/components/shaken/ui/progress\";\n\nconst steps = [\"Create workspace\", \"Connect repository\", \"Add a domain\", \"Invite your team\"];\n\nexport default function ProgressExample() {\n  const [uploaded, setUploaded] = useState(18);\n  const [step, setStep] = useState(1);\n\n  // Upload a 120 MB archive in uneven chunks, the way a real upload reports progress.\n  useEffect(() => {\n    if (uploaded >= 120) return;\n    const timer = setTimeout(() => setUploaded((mb) => Math.min(120, mb + 6 + Math.round(Math.random() * 14))), 700);\n    return () => clearTimeout(timer);\n  }, [uploaded]);\n\n  const done = uploaded >= 120;\n\n  return (\n    <div className=\"grid w-full max-w-md gap-8\">\n      <div className=\"grid gap-3\">\n        <Progress\n          label=\"Uploading site-assets.zip\"\n          value={uploaded}\n          max={120}\n          tone={done ? \"success\" : \"neutral\"}\n          valueText={done ? \"Uploaded\" : `${uploaded} of 120 MB`}\n          getAriaValueText={(_, mb) => `${mb} of 120 megabytes`}\n        />\n        <Button size=\"sm\" variant=\"secondary\" className=\"justify-self-start\" onClick={() => setUploaded(0)} disabled={!done}>\n          Upload again\n        </Button>\n      </div>\n\n      <Progress label=\"Preparing build environment\" value={null} tone=\"info\" size=\"sm\" />\n\n      <div className=\"grid gap-3\">\n        <ProgressSteps label=\"Set up your project\" total={steps.length} value={step} steps={steps} />\n        <div className=\"flex gap-2\">\n          <Button size=\"sm\" variant=\"secondary\" onClick={() => setStep((s) => Math.max(0, s - 1))} disabled={step === 0}>\n            Back\n          </Button>\n          <Button size=\"sm\" onClick={() => setStep((s) => Math.min(steps.length, s + 1))} disabled={step === steps.length}>\n            {step === steps.length - 1 ? \"Finish\" : \"Next step\"}\n          </Button>\n        </div>\n      </div>\n\n      <div className=\"flex items-center gap-6\">\n        <ProgressRing label=\"Storage used\" value={72} size=\"lg\" tone=\"warning\" />\n        <ProgressRing label=\"Build cache restored\" value={40} />\n        <div className=\"flex items-center gap-2 text-sm text-zinc-600 dark:text-zinc-400\">\n          <ProgressRing label=\"Indexing documents\" value={null} size=\"sm\" tone=\"info\" />\n          Indexing\n        </div>\n      </div>\n    </div>\n  );\n}\n"
  }
}
