{
  "schemaVersion": 1,
  "target": "react",
  "name": "approval-card",
  "version": "0.3.0",
  "category": "agent",
  "title": "Approval Card",
  "description": "Ask a person to approve or reject an agent action: the state in words, the question, what will run, and two decisions, with calm resolved states and duplicate-click protection while a decision is saved.",
  "tags": [
    "agent",
    "approval",
    "human-in-the-loop",
    "confirm",
    "review"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {},
  "registryDependencies": [
    {
      "name": "button",
      "version": "0.2.1"
    },
    {
      "name": "agent-run",
      "version": "0.1.2"
    }
  ],
  "docsPath": "/components/approval-card",
  "props": [
    {
      "name": "title",
      "type": "ReactNode",
      "description": "The question, phrased as what the agent wants to do."
    },
    {
      "name": "status",
      "type": "\"pending\" | \"approved\" | \"rejected\" | \"expired\"",
      "description": "Decision state. Approve and Reject show only while pending."
    },
    {
      "name": "description",
      "type": "ReactNode",
      "description": "Context for the decision."
    },
    {
      "name": "detail",
      "type": "string",
      "description": "The exact action, e.g. a command or diff, shown in a well. It recedes once the request is rejected or expires."
    },
    {
      "name": "onApprove / onReject",
      "type": "() => void | Promise<void>",
      "description": "Called once per decision; both buttons ignore clicks until it settles. Errors show a retry message."
    },
    {
      "name": "approveLabel / rejectLabel",
      "type": "string",
      "default": "\"Approve\" / \"Reject\"",
      "description": "Button text."
    },
    {
      "name": "detailLabel",
      "type": "string",
      "default": "\"What will run\"",
      "description": "Accessible caption for detail."
    },
    {
      "name": "outcome",
      "type": "ReactNode",
      "description": "Replaces the sentence shown after a decision, for example \"Approved by Dana at 14:02.\""
    }
  ],
  "accessibility": [
    "The state leads the card as a live region with a text label and glyph (\"Needs your approval\", \"Approved\"), not color alone.",
    "The detail well has an accessible caption (detailLabel).",
    "While a decision is saving, the chosen button shows a busy state and keeps focus; repeated clicks are ignored.",
    "After a decision, the buttons give way to a sentence that states the outcome (for example \"Nothing ran.\"). Transitions are removed with reduced motion.",
    "The card only reports a decision. Your backend must verify the approval and the user's authorization before acting."
  ],
  "states": [
    "pending",
    "approved",
    "rejected",
    "expired"
  ],
  "files": [
    {
      "path": "agent/approval-card.tsx",
      "content": "\"use client\";\n\nimport { type ComponentProps, type ReactNode, useRef, useState } from \"react\";\nimport { Button } from \"../ui/button\";\nimport type { ApprovalStatus } from \"./agent-run\";\n\nconst statuses: Record<ApprovalStatus, { label: string; outcome: string; tone: string }> = {\n  pending: { label: \"Needs your approval\", outcome: \"\", tone: \"text-amber-700 dark:text-amber-400\" },\n  approved: { label: \"Approved\", outcome: \"The agent can continue.\", tone: \"text-emerald-700 dark:text-emerald-400\" },\n  rejected: { label: \"Rejected\", outcome: \"Nothing ran.\", tone: \"text-red-700 dark:text-red-400\" },\n  expired: { label: \"Expired\", outcome: \"No decision was made in time. Nothing ran.\", tone: \"text-zinc-500\" },\n};\n\nconst ease = \"ease-[cubic-bezier(0.23,1,0.32,1)]\";\nconst enter = `transition-[opacity,translate] duration-200 ${ease} starting:opacity-0 motion-safe:starting:translate-y-1 motion-reduce:transition-none`;\n\nexport interface ApprovalCardProps extends Omit<ComponentProps<\"section\">, \"title\" | \"children\"> {\n  /** The question, phrased as what the agent wants to do. */\n  title: ReactNode;\n  status: ApprovalStatus;\n  description?: ReactNode;\n  /** What will happen if approved, such as a command or diff. Shown as preformatted text. */\n  detail?: string;\n  /** Called once per decision. While it runs, both buttons ignore further clicks. */\n  onApprove?: () => void | Promise<void>;\n  onReject?: () => void | Promise<void>;\n  approveLabel?: string;\n  rejectLabel?: string;\n  /** Caption for `detail`. */\n  detailLabel?: string;\n  /** Replaces the sentence shown after a decision, for example \"Approved by Dana at 14:02.\" */\n  outcome?: ReactNode;\n}\n\n/**\n * Asks a person to approve or reject an agent action: the question, what will run, then two\n * decisions. The UI only reports the decision: your backend must verify the approval and the\n * user's authorization before acting.\n */\nexport function ApprovalCard({\n  title,\n  status,\n  description,\n  detail,\n  onApprove,\n  onReject,\n  approveLabel = \"Approve\",\n  rejectLabel = \"Reject\",\n  detailLabel = \"What will run\",\n  outcome,\n  className,\n  ...props\n}: ApprovalCardProps) {\n  const [submitting, setSubmitting] = useState<\"approve\" | \"reject\" | null>(null);\n  const [error, setError] = useState<string | null>(null);\n  const inFlight = useRef(false);\n  const meta = statuses[status];\n  const pending = status === \"pending\";\n\n  async function decide(decision: \"approve\" | \"reject\") {\n    // A ref (not state) guards against double clicks that land before React re-renders.\n    if (inFlight.current || status !== \"pending\") return;\n    inFlight.current = true;\n    setSubmitting(decision);\n    setError(null);\n    try {\n      await (decision === \"approve\" ? onApprove : onReject)?.();\n    } catch {\n      setError(\"Your decision was not saved. Try again.\");\n    } finally {\n      inFlight.current = false;\n      setSubmitting(null);\n    }\n  }\n\n  return (\n    <section\n      aria-label={typeof title === \"string\" ? `Approval: ${title}` : \"Approval request\"}\n      data-status={status}\n      className={[\n        \"rounded-xl border border-zinc-950/10 bg-white p-4 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        .filter(Boolean)\n        .join(\" \")}\n      {...props}\n    >\n      {/* The state, in words and a glyph, leads the card; it is the live region. */}\n      <p role=\"status\" className={`flex items-center gap-1.5 text-xs font-medium ${meta.tone}`}>\n        <DecisionGlyph key={status} status={status} />\n        <span key={`${status}-label`} className={`transition-opacity duration-200 ${ease} starting:opacity-0 motion-reduce:transition-none`}>\n          {meta.label}\n        </span>\n      </p>\n\n      <h3 className=\"mt-2 text-[15px] leading-snug font-semibold tracking-[-0.01em] text-pretty\">{title}</h3>\n      {description ? <p className=\"mt-1 text-sm leading-relaxed text-pretty text-zinc-600 dark:text-zinc-400\">{description}</p> : null}\n\n      {detail ? (\n        <figure\n          className={[\n            \"mt-3 transition-opacity duration-200 ease-out motion-reduce:transition-none\",\n            // Once rejected or expired the command never ran, so it recedes.\n            status === \"rejected\" || status === \"expired\" ? \"opacity-55\" : \"\",\n          ].join(\" \")}\n        >\n          <figcaption className=\"sr-only\">{detailLabel}</figcaption>\n          <pre\n            className=\"overflow-x-auto rounded-lg border border-zinc-950/[0.07] bg-zinc-950/[0.02] px-3 py-2.5 font-mono text-xs leading-relaxed text-zinc-800 dark:border-white/[0.08] dark:bg-white/[0.02] dark:text-zinc-300\"\n          >\n            {detail}\n          </pre>\n        </figure>\n      ) : null}\n\n      {pending ? (\n        <div className=\"mt-4\">\n          <div className=\"grid grid-cols-2 gap-2 sm:flex sm:justify-end\">\n            <Button\n              size=\"sm\"\n              variant=\"ghost\"\n              loading={submitting === \"reject\"}\n              disabled={submitting === \"approve\"}\n              onClick={() => decide(\"reject\")}\n              className=\"border border-zinc-950/10 sm:border-transparent dark:border-white/10 sm:dark:border-transparent\"\n            >\n              {rejectLabel}\n            </Button>\n            <Button size=\"sm\" loading={submitting === \"approve\"} disabled={submitting === \"reject\"} onClick={() => decide(\"approve\")}>\n              {approveLabel}\n            </Button>\n          </div>\n          {error ? (\n            <p role=\"alert\" className={`mt-3 text-sm text-red-600 dark:text-red-400 ${enter}`}>\n              {error}\n            </p>\n          ) : null}\n        </div>\n      ) : (\n        <p key={status} className={`mt-3 text-sm text-zinc-500 ${enter}`}>\n          {outcome ?? meta.outcome}\n        </p>\n      )}\n    </section>\n  );\n}\n\n/** The shared status shapes at 14px: pause bars while waiting, then check, x, or slash. */\nfunction DecisionGlyph({ status }: { status: ApprovalStatus }) {\n  // A 16 unit box drawn at 14px: a 1.6 stroke renders at 1.4px.\n  const stroke = { fill: \"none\", stroke: \"currentColor\", strokeWidth: 1.6, strokeLinecap: \"round\", strokeLinejoin: \"round\" } as const;\n\n  return (\n    <svg\n      aria-hidden=\"true\"\n      viewBox=\"0 0 16 16\"\n      {...stroke}\n      className={`size-3.5 shrink-0 transition-[opacity,scale] duration-200 ${ease} starting:opacity-0 motion-safe:starting:scale-90 motion-reduce:transition-none`}\n    >\n      <circle cx=\"8\" cy=\"8\" r=\"6.25\" />\n      {status === \"pending\" ? (\n        <path d=\"M6.6 5.9v4.2M9.4 5.9v4.2\" />\n      ) : status === \"approved\" ? (\n        <path\n          d=\"m5.35 8.25 1.75 1.75 3.55-3.75\"\n          pathLength={1}\n          strokeDasharray=\"1\"\n          className={`[stroke-dashoffset:0] transition-[stroke-dashoffset] delay-75 duration-300 ${ease} starting:[stroke-dashoffset:1] motion-reduce:transition-none`}\n        />\n      ) : status === \"rejected\" ? (\n        <path d=\"m6.1 6.1 3.8 3.8m0-3.8-3.8 3.8\" />\n      ) : (\n        <path d=\"m5.6 10.4 4.8-4.8\" />\n      )}\n    </svg>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { useState } from \"react\";\nimport type { ApprovalStatus } from \"@/components/shaken/agent/agent-run\";\nimport { ApprovalCard } from \"@/components/shaken/agent/approval-card\";\n\nexport default function ApprovalCardExample() {\n  const [status, setStatus] = useState<ApprovalStatus>(\"pending\");\n\n  // Replace with a call to your backend, which must verify the user may approve this action.\n  const record = (decision: \"approved\" | \"rejected\") => new Promise<void>((resolve) => setTimeout(() => (setStatus(decision), resolve()), 600));\n\n  return (\n    <ApprovalCard\n      className=\"w-full max-w-md\"\n      title=\"Open a pull request?\"\n      description=\"The agent wants to push a branch and open a pull request in acme/docs.\"\n      detail={'git push origin docs/rate-limits\\ngh pr create --title \"Update rate limits\"'}\n      status={status}\n      onApprove={() => record(\"approved\")}\n      onReject={() => record(\"rejected\")}\n    />\n  );\n}\n"
  }
}
