{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "agent-steps", "title": "Agent steps", "description": "Shows the steps an AI agent is working through — done, running, waiting or failed — with a count in the header and rows that open to show what happened.", "registryDependencies": [ "button", "https://www.quilldesignsystem.com/r/icon.json", "https://www.quilldesignsystem.com/r/ai-mark.json" ], "files": [ { "path": "registry/lib/agent-steps.tsx", "content": "'use client'\n\nimport * as React from 'react'\nimport { Button } from '@/components/ui/button'\nimport { Icon } from '@/components/ui/icon'\nimport { AiMark } from '@/components/ui/ai-mark'\nimport { cn } from '@/lib/utils'\n\nexport type AgentStepStatus = 'done' | 'running' | 'waiting' | 'failed'\n\nexport type AgentStep = {\n /** What the step is, in a few words: \"Read signups-sept.csv\". */\n label: string\n status: AgentStepStatus\n /** What happened in the step. A step with detail opens to show it; one without is a plain row. */\n detail?: React.ReactNode\n /** A short note at the end of the row, such as how long it took (\"4 s\"). A running step says \"running\" on its own. */\n meta?: string\n /** Start with the detail open. */\n defaultOpen?: boolean\n}\n\nconst STATUSES: AgentStepStatus[] = ['done', 'running', 'waiting', 'failed']\nconst STATE_LABEL: Record = { done: 'Done', running: 'Running', waiting: 'Waiting', failed: 'Failed' }\n// Done goes muted (never struck through); the running step is the one at full strength.\nconst TONE: Record = {\n done: 'text-muted-foreground',\n running: 'font-semibold text-foreground',\n waiting: 'text-ink-soft',\n failed: 'text-ink-soft',\n}\n// items-start, with the dot in a box one line tall, keeps the dot on the first line of a label that wraps.\nconst ROW = 'flex min-w-0 flex-1 items-start gap-2.5 rounded-md px-1 py-1.5 text-left'\n\n// A status this version does not know (a newer agent, a typo) reads as waiting rather than drawing nothing.\nconst statusOf = (step: AgentStep): AgentStepStatus => (STATUSES.includes(step.status) ? step.status : 'waiting')\nconst hasDetail = (step: AgentStep) => step.detail !== undefined && step.detail !== null && step.detail !== false && step.detail !== ''\n\n// Progress is moss and terracotta, never the AI gradient. The deep cuts clear 3:1 on the card in every theme.\nfunction StepDot({ status }: { status: AgentStepStatus }) {\n if (status === 'running') return \n if (status === 'done') return \n if (status === 'failed') return \n return \n}\n\n/** Shows the steps an AI agent is working through — done, running, waiting or failed — with a count in the header and rows that open to show what happened. */\nexport function AgentSteps({ title, steps, onRetry, className }: {\n title: string\n steps: AgentStep[]\n /** Shows Retry on failed steps; called with the step's position in the list. */\n onRetry?: (index: number) => void\n className?: string\n}) {\n const baseId = React.useId()\n // Open rows are tracked by position: labels may repeat, positions cannot.\n const [open, setOpen] = React.useState>(\n () => new Set(steps.flatMap((step, index) => (step.defaultOpen && hasDetail(step) ? [index] : []))),\n )\n // The status region is on the page from the first paint but stays empty until just after mount: a live region\n // that arrives already filled is announced unreliably, one whose text changes is.\n const [announcing, setAnnouncing] = React.useState(false)\n React.useEffect(() => {\n const timer = window.setTimeout(() => setAnnouncing(true), 100)\n return () => window.clearTimeout(timer)\n }, [])\n\n const statuses = steps.map(statusOf)\n const doneCount = statuses.filter((status) => status === 'done').length\n const runningIndex = statuses.indexOf('running')\n const failedIndex = statuses.indexOf('failed')\n const active = runningIndex !== -1 || failedIndex !== -1\n // A list that was never active while on the page (restored from history, already finished) must not announce itself.\n const [wasActive, setWasActive] = React.useState(active)\n if (active && !wasActive) setWasActive(true)\n\n if (!steps.length) return null\n\n const count = `${doneCount} of ${steps.length} done`\n const spoken = !announcing || !(active || wasActive) ? ''\n : failedIndex !== -1 ? `Failed: ${steps[failedIndex].label}. ${count}`\n : runningIndex !== -1 ? `Running: ${steps[runningIndex].label}. ${count}`\n : count\n const toggle = (index: number) => setOpen((current) => {\n const next = new Set(current)\n if (!next.delete(index)) next.add(index)\n return next\n })\n\n return (\n
\n {/* px-1 matches the rows' inset, so the mark lines up with the dots and the count with the times. */}\n
\n \n

{title}

\n {/* Hidden from screen readers only while the status region below is saying the same count. */}\n

{count}

\n
\n {/* sr-only makes the region a real box that takes no space; it carries the one copy a screen reader hears. */}\n
{spoken}
\n
    \n {steps.map((step, index) => {\n const status = statuses[index]\n const expandable = hasDetail(step)\n const isOpen = expandable && open.has(index)\n const detailId = `${baseId}-detail-${index}`\n const meta = step.meta ?? (status === 'running' ? 'running' : undefined)\n const row = (\n <>\n \n \n {STATE_LABEL[status]}: \n {step.label}\n {expandable ? : null}\n \n {meta ? (\n // The outer box is one row-line tall so the smaller note still sits on the label's first line.\n // The automatic \"running\" is hidden from screen readers: the row already starts with \"Running:\".\n \n {meta}\n \n ) : null}\n \n )\n return (\n
  1. \n
    \n {expandable ? (\n \n ) : (\n
    {row}
    \n )}\n {status === 'failed' && onRetry ? (\n \n ) : null}\n
    \n {expandable ? (\n \n ) : null}\n
    2. \n )\n })}\n
\n
\n )\n}\n", "type": "registry:ui", "target": "components/ui/agent-steps.tsx" } ], "docs": "Shows the steps an AI agent is working through — done, running, waiting or failed — with a count in the header and rows that open to show what happened. Do: Leave the ticks and the spinner in moss; the AI mark in the header already says an agent is working. Don't: Paint progress with the AI gradient — the gradient marks AI, moss marks progress. Do: Let finished steps go muted so the running step stands out. Don't: Strike finished steps through — long labels become hard to read. Do: Put what a step found in its detail, opened by pressing the row. Don't: Print every step's detail in the list — the list has to stay scannable. Use ai-thinking when the AI is only thinking before one answer; there are no separate steps to follow. Use progress when you know a percentage and there is nothing to read step by step. Use wizard when the person, not the AI, moves through the steps.", "type": "registry:ui" }