{
  "schemaVersion": 1,
  "target": "react",
  "name": "plan",
  "version": "0.1.0",
  "category": "ai-elements",
  "title": "Plan",
  "description": "The steps an agent intends to take with progress, the current step highlighted with a live mark and finished steps checked, plus an editable mode for approval before anything runs.",
  "tags": [
    "ai",
    "agent",
    "plan",
    "steps",
    "progress",
    "approval",
    "editable"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [
    {
      "name": "agent-state",
      "version": "0.1.0"
    },
    {
      "name": "step-list",
      "version": "0.3.0"
    },
    {
      "name": "button",
      "version": "0.2.1"
    }
  ],
  "docsPath": "/components/plan",
  "props": [
    {
      "name": "steps",
      "type": "{ id, label, detail?, status? }[]",
      "description": "Steps in order. label is plain text so it can be edited. status overrides the value derived from current."
    },
    {
      "name": "current",
      "type": "number",
      "description": "Index of the step in progress; earlier steps count as done. Leave it out while the plan waits for approval."
    },
    {
      "name": "title / description",
      "type": "ReactNode",
      "default": "\"Plan\"",
      "description": "Heading and an optional line under it."
    },
    {
      "name": "activity",
      "type": "AgentActivity",
      "default": "\"working\"",
      "description": "The Agent State mark on the current step."
    },
    {
      "name": "editable",
      "type": "boolean",
      "default": "false",
      "description": "Turns steps into text fields with add and remove. Uncontrolled while editing: steps seeds it and onStepsChange reports changes."
    },
    {
      "name": "onApprove / onReject",
      "type": "(steps) => void / () => void",
      "description": "Show the approve and discard buttons. onApprove receives the edited steps without empty ones."
    },
    {
      "name": "approveLabel / rejectLabel",
      "type": "ReactNode",
      "default": "\"Approve plan\" / \"Discard\"",
      "description": "Button text."
    }
  ],
  "accessibility": [
    "The plan is a labeled section; progress is a progressbar with aria-valuetext such as \"2 of 5 steps done\".",
    "The current step has aria-current=\"step\" and every step has a screen-reader status after its label.",
    "In editable mode each field is labeled \"Step N\" and each remove button \"Remove step N\". Enter adds a step below and moves focus to it; Backspace on an empty step removes it and focuses the previous one.",
    "Remove buttons appear on hover and on keyboard focus, and stay visible on touch screens.",
    "With reduced motion the progress bar, new rows, and glyph swaps change without animation."
  ],
  "states": [
    "awaiting-approval",
    "editing",
    "running",
    "done",
    "failed"
  ],
  "files": [
    {
      "path": "agent/plan.tsx",
      "content": "\"use client\";\n\nimport { type ComponentProps, type KeyboardEvent, type ReactNode, useEffect, useId, useRef, useState } from \"react\";\nimport { Button } from \"../ui/button\";\nimport { type AgentActivity, AgentMark } from \"./agent-state\";\nimport { StatusGlyph } from \"./step-list\";\n\nfunction cx(...classes: Array<string | false | null | undefined>) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nconst ease = \"ease-[cubic-bezier(0.23,1,0.32,1)]\";\n\nexport type PlanStepStatus = \"pending\" | \"current\" | \"done\" | \"failed\" | \"skipped\";\n\nexport interface PlanStep {\n  id: string;\n  /** What the agent will do. Plain text so it can be edited before approval. */\n  label: string;\n  /** Optional second line, such as the files or tools involved. */\n  detail?: ReactNode;\n  /** Overrides the status derived from `current`. */\n  status?: PlanStepStatus;\n}\n\nexport interface PlanProps extends Omit<ComponentProps<\"section\">, \"children\" | \"title\"> {\n  /** @default \"Plan\" */\n  title?: ReactNode;\n  /** One line under the title, for example the goal the plan serves. */\n  description?: ReactNode;\n  steps: PlanStep[];\n  /**\n   * Index of the step in progress. Earlier steps count as done, later ones as pending.\n   * Leave it out while the plan waits for approval, or when every step carries a `status`.\n   */\n  current?: number;\n  /** Which Agent State mark moves on the current step. @default \"working\" */\n  activity?: AgentActivity;\n  /**\n   * Turns the steps into text fields so the reader can edit, add, and remove steps before\n   * approving. The list is uncontrolled while editing: `steps` seeds it, `onStepsChange`\n   * reports every change, and `onApprove` receives the final list.\n   */\n  editable?: boolean;\n  onStepsChange?: (steps: PlanStep[]) => void;\n  /** Shows the approve button. Receives the steps as edited. */\n  onApprove?: (steps: PlanStep[]) => void;\n  /** Shows a secondary button next to approve, for example to discard the plan. */\n  onReject?: () => void;\n  /** @default \"Approve plan\" */\n  approveLabel?: ReactNode;\n  /** @default \"Discard\" */\n  rejectLabel?: ReactNode;\n}\n\nfunction statusOf(step: PlanStep, index: number, current: number | undefined): PlanStepStatus {\n  if (step.status) return step.status;\n  if (current == null) return \"pending\";\n  return index < current ? \"done\" : index === current ? \"current\" : \"pending\";\n}\n\nconst spoken: Record<PlanStepStatus, string> = {\n  pending: \"Not started\",\n  current: \"In progress\",\n  done: \"Done\",\n  failed: \"Failed\",\n  skipped: \"Skipped\",\n};\n\n/**\n * The steps an agent intends to take, with progress (\"2 of 5\"). Finished steps are checked,\n * the current one is highlighted with a live mark, and the rest wait in order. With\n * `editable`, the reader can rewrite the plan and approve it before anything runs.\n */\nexport function Plan({\n  title = \"Plan\",\n  description,\n  steps,\n  current,\n  activity = \"working\",\n  editable = false,\n  onStepsChange,\n  onApprove,\n  onReject,\n  approveLabel = \"Approve plan\",\n  rejectLabel = \"Discard\",\n  className,\n  ...props\n}: PlanProps) {\n  const titleId = useId();\n  const [draft, setDraft] = useState(steps);\n  const list = editable ? draft : steps;\n  const statuses = list.map((step, index) => statusOf(step, index, current));\n  const done = statuses.filter((status) => status === \"done\" || status === \"skipped\").length;\n  const failed = statuses.includes(\"failed\");\n  const total = list.length;\n  const ratio = total ? done / total : 0;\n  const finished = total > 0 && done === total;\n  const awaiting = editable || (current == null && !list.some((step) => step.status));\n\n  function update(next: PlanStep[]) {\n    setDraft(next);\n    onStepsChange?.(next);\n  }\n\n  return (\n    <section\n      aria-labelledby={titleId}\n      data-state={awaiting ? \"awaiting-approval\" : finished ? \"done\" : failed ? \"failed\" : \"running\"}\n      className={cx(\n        \"w-full overflow-hidden rounded-xl border border-zinc-950/10 bg-white text-zinc-950 shadow-[0_1px_2px_rgb(0_0_0/0.04)]\",\n        \"dark:border-white/10 dark:bg-black dark:text-white dark:shadow-[inset_0_1px_0_rgb(255_255_255/0.06)]\",\n        className,\n      )}\n      {...props}\n    >\n      <header className=\"px-4 pt-3.5 pb-3\">\n        <div className=\"flex flex-wrap items-baseline justify-between gap-x-4 gap-y-1\">\n          <h3 id={titleId} className=\"min-w-0 text-sm leading-5 font-semibold text-pretty\">\n            {title}\n          </h3>\n          <PlanMeta awaiting={awaiting} finished={finished} failed={failed} done={done} total={total} />\n        </div>\n        {description != null ? <p className=\"mt-0.5 text-sm text-zinc-600 dark:text-zinc-400\">{description}</p> : null}\n        {!awaiting ? (\n          <div\n            role=\"progressbar\"\n            aria-label=\"Plan progress\"\n            aria-valuemin={0}\n            aria-valuemax={total}\n            aria-valuenow={done}\n            aria-valuetext={`${done} of ${total} steps done`}\n            className=\"mt-3 h-0.5 overflow-hidden rounded-full bg-zinc-950/[0.07] dark:bg-white/10\"\n          >\n            <div\n              className={cx(\n                \"h-full origin-left rounded-full transition-[scale,background-color] duration-500 motion-reduce:transition-none\",\n                ease,\n                failed ? \"bg-red-500\" : \"bg-zinc-950 dark:bg-white\",\n              )}\n              style={{ scale: `${ratio} 1` }}\n            />\n          </div>\n        ) : null}\n      </header>\n\n      {editable ? (\n        <EditableSteps steps={draft} onChange={update} />\n      ) : (\n        <ol className=\"grid gap-0.5 border-t border-zinc-950/[0.07] p-1.5 dark:border-white/[0.08]\">\n          {list.map((step, index) => (\n            <PlanRow key={step.id} step={step} index={index} status={statuses[index] ?? \"pending\"} activity={activity} />\n          ))}\n        </ol>\n      )}\n\n      {onApprove || onReject ? (\n        <footer className=\"flex items-center justify-end gap-2 border-t border-zinc-950/[0.07] px-4 py-3 dark:border-white/[0.08]\">\n          {onReject ? (\n            <Button variant=\"ghost\" size=\"sm\" onClick={onReject}>\n              {rejectLabel}\n            </Button>\n          ) : null}\n          {onApprove ? (\n            <Button size=\"sm\" disabled={!list.some((step) => step.label.trim())} onClick={() => onApprove(list.filter((step) => step.label.trim()))}>\n              {approveLabel}\n            </Button>\n          ) : null}\n        </footer>\n      ) : null}\n    </section>\n  );\n}\n\nfunction PlanMeta({ awaiting, finished, failed, done, total }: { awaiting: boolean; finished: boolean; failed: boolean; done: number; total: number }) {\n  if (awaiting) {\n    return (\n      <span className=\"inline-flex shrink-0 items-center gap-1.5 self-start text-xs leading-5 text-amber-700 dark:text-amber-400\">\n        <StatusGlyph kind=\"waiting\" />\n        Waiting for approval\n      </span>\n    );\n  }\n  return (\n    <span\n      key={finished ? \"done\" : failed ? \"failed\" : \"progress\"}\n      className={cx(\n        \"inline-flex shrink-0 items-center gap-1.5 font-mono text-xs tabular-nums\",\n        failed ? \"text-red-600 dark:text-red-400\" : \"text-zinc-500\",\n        `transition-opacity duration-200 ${ease} starting:opacity-0 motion-reduce:transition-none`,\n      )}\n    >\n      {finished ? <StatusGlyph kind=\"success\" /> : failed ? <StatusGlyph kind=\"failed\" /> : null}\n      {done} of {total}\n    </span>\n  );\n}\n\nfunction PlanRow({ step, index, status, activity }: { step: PlanStep; index: number; status: PlanStepStatus; activity: AgentActivity }) {\n  const isCurrent = status === \"current\";\n  return (\n    <li\n      aria-current={isCurrent ? \"step\" : undefined}\n      data-status={status}\n      className={cx(\n        \"grid grid-cols-[1.25rem_minmax(0,1fr)] gap-x-2.5 rounded-lg px-2.5 py-2\",\n        \"transition-[background-color] duration-200 motion-reduce:transition-none\",\n        isCurrent ? \"bg-zinc-950/[0.04] dark:bg-white/[0.06]\" : \"\",\n      )}\n    >\n      <span aria-hidden=\"true\" className=\"flex h-5 items-center justify-center\">\n        {isCurrent ? (\n          <AgentMark activity={activity} size={16} className=\"text-zinc-950 dark:text-white\" />\n        ) : status === \"done\" ? (\n          <StatusGlyph key=\"done\" kind=\"success\" />\n        ) : status === \"failed\" ? (\n          <StatusGlyph key=\"failed\" kind=\"failed\" />\n        ) : status === \"skipped\" ? (\n          <StatusGlyph key=\"skipped\" kind=\"skipped\" />\n        ) : (\n          <StepNumber n={index + 1} />\n        )}\n      </span>\n      <div className=\"min-w-0\">\n        <p\n          className={cx(\n            \"text-sm leading-5 break-words transition-colors duration-200 motion-reduce:transition-none\",\n            isCurrent\n              ? \"font-medium text-zinc-950 dark:text-white\"\n              : status === \"done\"\n                ? \"text-zinc-600 dark:text-zinc-400\"\n                : status === \"failed\"\n                  ? \"text-zinc-950 dark:text-white\"\n                  : status === \"skipped\"\n                    ? \"text-zinc-500 line-through decoration-zinc-500/60\"\n                    : \"text-zinc-500\",\n          )}\n        >\n          {step.label}\n          <span className=\"sr-only\">, {spoken[status]}</span>\n        </p>\n        {step.detail != null ? (\n          <p className={cx(\"mt-0.5 text-xs\", status === \"failed\" ? \"text-red-600 dark:text-red-400\" : \"text-zinc-500\")}>{step.detail}</p>\n        ) : null}\n      </div>\n    </li>\n  );\n}\n\nfunction StepNumber({ n }: { n: number }) {\n  return (\n    <span className=\"flex size-4 items-center justify-center rounded-full border border-dashed border-zinc-950/25 font-mono text-[9px] leading-none text-zinc-500 tabular-nums dark:border-white/25\">\n      {n}\n    </span>\n  );\n}\n\nlet created = 0;\n\nfunction EditableSteps({ steps, onChange }: { steps: PlanStep[]; onChange: (steps: PlanStep[]) => void }) {\n  const inputs = useRef(new Map<string, HTMLTextAreaElement>());\n  const [focusId, setFocusId] = useState<string | null>(null);\n  const prefix = useId();\n\n  useEffect(() => {\n    if (!focusId) return;\n    const input = inputs.current.get(focusId);\n    input?.focus();\n    setFocusId(null);\n  }, [focusId]);\n\n  function insertAfter(index: number) {\n    created += 1;\n    const step: PlanStep = { id: `${prefix}-new-${created}`, label: \"\" };\n    onChange([...steps.slice(0, index + 1), step, ...steps.slice(index + 1)]);\n    setFocusId(step.id);\n  }\n\n  function remove(index: number) {\n    const next = steps.filter((_, i) => i !== index);\n    onChange(next);\n    const neighbour = next[Math.max(0, index - 1)];\n    if (neighbour) setFocusId(neighbour.id);\n  }\n\n  function onKeyDown(event: KeyboardEvent<HTMLTextAreaElement>, index: number) {\n    if (event.key === \"Enter\" && !event.nativeEvent.isComposing) {\n      event.preventDefault();\n      insertAfter(index);\n    } else if (event.key === \"Backspace\" && event.currentTarget.value === \"\" && steps.length > 1) {\n      event.preventDefault();\n      remove(index);\n    }\n  }\n\n  return (\n    <div className=\"border-t border-zinc-950/[0.07] p-1.5 dark:border-white/[0.08]\">\n      <ol className=\"grid gap-0.5\">\n        {steps.map((step, index) => (\n          <li\n            key={step.id}\n            className={cx(\n              \"group grid grid-cols-[1.25rem_minmax(0,1fr)_auto] items-start gap-x-2.5 rounded-lg py-1 pr-1 pl-2.5\",\n              `transition-[opacity,translate] duration-200 ${ease} starting:-translate-y-1 starting:opacity-0 motion-reduce:transition-none`,\n            )}\n          >\n            <span aria-hidden=\"true\" className=\"flex h-8 items-center justify-center\">\n              <StepNumber n={index + 1} />\n            </span>\n            <textarea\n              rows={1}\n              ref={(node) => {\n                if (node) inputs.current.set(step.id, node);\n                else inputs.current.delete(step.id);\n              }}\n              value={step.label}\n              aria-label={`Step ${index + 1}`}\n              placeholder=\"Describe the step\"\n              onChange={(event) => onChange(steps.map((item) => (item.id === step.id ? { ...item, label: event.target.value.replace(/\\s*\\n\\s*/g, \" \") } : item)))}\n              onKeyDown={(event) => onKeyDown(event, index)}\n              className={cx(\n                \"-ml-2 block min-h-8 min-w-0 resize-none rounded-md border border-transparent bg-transparent px-2 py-1.5 text-sm leading-5 field-sizing-content text-zinc-950 placeholder:text-zinc-400 dark:text-white dark:placeholder:text-zinc-600\",\n                \"transition-[border-color,background-color] duration-150 ease-out motion-reduce:transition-none\",\n                \"hover:border-zinc-950/10 dark:hover:border-white/10\",\n                \"focus-visible:border-zinc-950/15 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-sky-500 dark:focus-visible:border-white/20\",\n              )}\n            />\n            <button\n              type=\"button\"\n              aria-label={`Remove step ${index + 1}`}\n              disabled={steps.length <= 1}\n              onClick={() => remove(index)}\n              className={cx(\n                \"mt-0.5 inline-flex size-7 cursor-pointer items-center justify-center rounded-md text-zinc-500\",\n                \"transition-[background-color,color,opacity] duration-150 ease-out motion-reduce:transition-none\",\n                \"opacity-0 group-focus-within:opacity-100 group-hover:opacity-100 [@media(hover:none)]:opacity-100\",\n                \"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white\",\n                \"focus-visible:opacity-100 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n                \"disabled:pointer-events-none disabled:opacity-0\",\n              )}\n            >\n              <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" strokeWidth={1.5} strokeLinecap=\"round\" className=\"size-3.5\">\n                <path d=\"m4.5 4.5 7 7m0-7-7 7\" />\n              </svg>\n            </button>\n          </li>\n        ))}\n      </ol>\n      <button\n        type=\"button\"\n        onClick={() => insertAfter(steps.length - 1)}\n        className={cx(\n          \"mt-0.5 flex h-8 w-full cursor-pointer items-center gap-2.5 rounded-lg px-2.5 text-sm text-zinc-500\",\n          \"transition-[background-color,color] duration-150 ease-out motion-reduce:transition-none\",\n          \"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white\",\n          \"focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-sky-500\",\n        )}\n      >\n        <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" strokeWidth={1.5} strokeLinecap=\"round\" className=\"size-4 shrink-0 translate-x-0.5\">\n          <path d=\"M8 3.5v9M3.5 8h9\" />\n        </svg>\n        Add step\n      </button>\n      <p className=\"px-2.5 pt-1 pb-1.5 text-xs text-zinc-500\">Enter adds a step below. Backspace on an empty step removes it.</p>\n    </div>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "import { Plan } from \"@/components/shaken/agent/plan\";\n\nexport default function PlanExample() {\n  return (\n    <Plan\n      className=\"max-w-md\"\n      title=\"Migrate billing emails to the new template\"\n      current={2}\n      activity=\"working\"\n      steps={[\n        { id: \"1\", label: \"Find every place that sends a billing email\", detail: \"4 call sites in api/billing\" },\n        { id: \"2\", label: \"Map old template fields to the new ones\" },\n        { id: \"3\", label: \"Update the senders to use the new template\", detail: \"invoice.ts, receipt.ts\" },\n        { id: \"4\", label: \"Render each email with test data\" },\n        { id: \"5\", label: \"Open a pull request\" },\n      ]}\n    />\n  );\n}\n"
  }
}
