{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"approval-card","type":"registry:ui","title":"ApprovalCard","description":"A human-in-the-loop gate before a side effect: the agent states what it is about to do, and the footer swaps its approve and deny buttons for a one-line verdict once someone decides","author":"fancy-ui <https://fancy-ui.rama.app>","categories":["ai-agents"],"registryDependencies":["https://fancy-ui.rama.app/r/internals-dom.json","https://fancy-ui.rama.app/r/sound.json","https://fancy-ui.rama.app/r/utils.json"],"files":[{"path":"react/src/components/approval-card/ApprovalCard.tsx","content":"\"use client\";\n\nimport { forwardRef, useEffect, useRef, useState } from \"react\";\nimport type { ReactNode } from \"react\";\nimport { cn } from \"../../utils\";\nimport { useSoundCue } from \"../../sound/use-sound\";\nimport \"./approval-card.css\";\n\n/** The three states of a human-in-the-loop gate. */\nexport type ApprovalState = \"pending\" | \"approved\" | \"denied\";\n\n/** Spoken and shown once the gate is behind us. */\nconst RESOLVED_LABELS = {\n\tapproved: \"Approved\",\n\tdenied: \"Denied\",\n} as const;\n\n/**\n * Props for ApprovalCard\n */\nexport interface ApprovalCardProps {\n\t/** What the agent is asking permission for, e.g. \"Run database migration\". */\n\ttitle: string;\n\t/** Secondary muted line under the title — the consequence, the blast radius. */\n\tdescription?: string;\n\t/**\n\t * Which side of the gate we are on. Controlled when supplied: pair it\n\t * with `onStateChange`, the React counterpart of the Svelte source's\n\t * `bind:state`. Left out, the card keeps the state itself and starts\n\t * at `\"pending\"`.\n\t */\n\tstate?: ApprovalState;\n\t/** Called with the new state whenever it changes, however the change happened. */\n\tonStateChange?: (state: ApprovalState) => void;\n\t/** Marks the action as irreversible: red approve button and a warning tint on the card. */\n\tdestructive?: boolean;\n\t/** Label for the approve button. */\n\tapproveLabel?: string;\n\t/** Label for the deny button. */\n\tdenyLabel?: string;\n\t/**\n\t * Called when approve is pressed, with the decision that was just taken\n\t * (always `\"approved\"`). The argument is the point: `onStateChange` has\n\t * only just been called at this instant, so a controlled consumer's own\n\t * `state` has not re-rendered yet and still reads `\"pending\"`. The Svelte\n\t * source's `bind:state` writes through synchronously and needs no argument;\n\t * React does. A `() => void` handler keeps working — it simply ignores it.\n\t */\n\tonApprove?: (state: ApprovalState) => void;\n\t/** Called when deny is pressed, with the decision (always `\"denied\"`). See `onApprove`. */\n\tonDeny?: (state: ApprovalState) => void;\n\t/** The consumer is executing the decision: both buttons go disabled and the card is `aria-busy`. */\n\tbusy?: boolean;\n\t/** The detail region between the header and the footer — a diff, a command preview. */\n\tchildren?: ReactNode;\n\t/** Additional CSS classes */\n\tclassName?: string;\n\t/**\n\t * Plays the matching interface cue through the sound controller. Off by\n\t * default; only audible once the user has enabled sound.\n\t */\n\tsound?: boolean;\n}\n\n/**\n * A human-in-the-loop gate: nothing happens until someone presses a button,\n * then the footer collapses to a one-line verdict.\n *\n * The root element arrives through the ref channel rather than a `ref`\n * prop, per PORTING.md — the Svelte source declares `ref = $bindable(null)`.\n */\nexport const ApprovalCard = forwardRef<HTMLDivElement, ApprovalCardProps>(function ApprovalCard(\n\t{\n\t\ttitle,\n\t\tdescription,\n\t\tstate,\n\t\tonStateChange,\n\t\tdestructive = false,\n\t\tapproveLabel = \"Approve\",\n\t\tdenyLabel = \"Deny\",\n\t\tonApprove,\n\t\tonDeny,\n\t\tbusy = false,\n\t\tchildren,\n\t\tclassName,\n\t\tsound = false,\n\t},\n\tref\n) {\n\t// `state = $bindable(\"pending\")` on the Svelte side. A supplied prop\n\t// wins and the consumer owns the value; with nothing supplied the\n\t// component owns it, starting at the same \"pending\" default.\n\tconst [uncontrolledState, setUncontrolledState] = useState<ApprovalState>(\"pending\");\n\tconst isControlled = state !== undefined;\n\tconst currentState = isControlled ? state : uncontrolledState;\n\n\tconst isPending = currentState === \"pending\";\n\tconst isApproved = currentState === \"approved\";\n\tconst resolvedLabel = isApproved ? RESOLVED_LABELS.approved : RESOLVED_LABELS.denied;\n\n\t/** Where focus lands once the buttons it might have held are gone. */\n\tconst resolvedRef = useRef<HTMLParagraphElement | null>(null);\n\tconst shouldFocusResolved = useRef(false);\n\tconst playCue = useSoundCue(sound);\n\n\tuseEffect(() => {\n\t\tif (shouldFocusResolved.current) {\n\t\t\tshouldFocusResolved.current = false;\n\t\t\tresolvedRef.current?.focus();\n\t\t}\n\t});\n\n\t/**\n\t * The decision is written to `state` before the callback fires — and then\n\t * handed to the callback as well. In controlled mode `onStateChange` only\n\t * *schedules* the consumer's update, so its `state` prop is still\n\t * `\"pending\"` when `onApprove` runs one line later; the argument is the\n\t * committed answer it can act on without waiting for its own re-render.\n\t * Re-entry is refused rather than re-announced: a gate resolves once.\n\t */\n\tfunction decide(next: \"approved\" | \"denied\") {\n\t\tif (busy || currentState !== \"pending\") return;\n\t\tif (!isControlled) {\n\t\t\tsetUncontrolledState(next);\n\t\t}\n\t\tonStateChange?.(next);\n\t\t// Deny is a legitimate choice, not a failure — both sides of the gate\n\t\t// play the same cue, never `error` for a refusal.\n\t\tplayCue(\"select\");\n\t\tif (next === \"approved\") onApprove?.(next);\n\t\telse onDeny?.(next);\n\t\t// The button just pressed is about to leave the DOM along with the\n\t\t// rest of the action group, so focus is moved to the verdict once it\n\t\t// has painted — otherwise the browser drops it back to the document\n\t\t// body.\n\t\tshouldFocusResolved.current = true;\n\t}\n\n\treturn (\n\t\t<div\n\t\t\tref={ref}\n\t\t\tclassName={cn(\n\t\t\t\t\"ft-approval border-border bg-card/50 w-full rounded-lg border p-4 text-sm\",\n\t\t\t\tdestructive && \"ft-destructive\",\n\t\t\t\tclassName\n\t\t\t)}\n\t\t\trole=\"group\"\n\t\t\taria-label={title}\n\t\t\taria-busy={busy ? \"true\" : undefined}\n\t\t\tdata-state={currentState}\n\t\t>\n\t\t\t<div className=\"flex items-start gap-2.5\">\n\t\t\t\t{/*\n\t\t\t\t\tDecorative: the title carries the ask in words. On a destructive\n\t\t\t\t\tgate the shield picks up an alert mark, so \"this one is\n\t\t\t\t\tirreversible\" is not left to the tint alone.\n\t\t\t\t*/}\n\t\t\t\t<span className=\"ft-approval-icon mt-0.5 flex-none\" aria-hidden=\"true\">\n\t\t\t\t\t<svg\n\t\t\t\t\t\tclassName=\"size-4\"\n\t\t\t\t\t\tviewBox=\"0 0 24 24\"\n\t\t\t\t\t\tfill=\"none\"\n\t\t\t\t\t\tstroke=\"currentColor\"\n\t\t\t\t\t\tstrokeWidth=\"2\"\n\t\t\t\t\t\tstrokeLinecap=\"round\"\n\t\t\t\t\t\tstrokeLinejoin=\"round\"\n\t\t\t\t\t>\n\t\t\t\t\t\t<path d=\"M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z\" />\n\t\t\t\t\t\t{destructive && (\n\t\t\t\t\t\t\t<>\n\t\t\t\t\t\t\t\t<path d=\"M12 8v3.5\" />\n\t\t\t\t\t\t\t\t<path d=\"M12 15h.01\" />\n\t\t\t\t\t\t\t</>\n\t\t\t\t\t\t)}\n\t\t\t\t\t</svg>\n\t\t\t\t</span>\n\n\t\t\t\t<div className=\"min-w-0 flex-1\">\n\t\t\t\t\t<p className=\"ft-approval-title text-foreground font-medium\">{title}</p>\n\t\t\t\t\t{description && (\n\t\t\t\t\t\t<p className=\"ft-approval-description text-muted-foreground mt-0.5 text-xs leading-relaxed\">\n\t\t\t\t\t\t\t{description}\n\t\t\t\t\t\t</p>\n\t\t\t\t\t)}\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{/*\n\t\t\t\tNullish and boolean children mean \"no detail region\"; every other\n\t\t\t\tvalue renders inside the wrapper, so a numeric `0` cannot leak out\n\t\t\t\tas bare text the way a plain truthiness test would let it.\n\t\t\t*/}\n\t\t\t{children != null && children !== false && (\n\t\t\t\t<div className=\"ft-approval-detail mt-3 min-w-0\">{children}</div>\n\t\t\t)}\n\n\t\t\t{/*\n\t\t\t\tOne footer element, mounted from the first render, so the live\n\t\t\t\tregion exists before the decision lands in it — a region that\n\t\t\t\tappears at the same moment as its own text is routinely missed by\n\t\t\t\tscreen readers.\n\t\t\t*/}\n\t\t\t<div className=\"ft-approval-foot mt-3\" aria-live=\"polite\">\n\t\t\t\t{isPending ? (\n\t\t\t\t\t<div className=\"ft-approval-actions flex flex-wrap items-center justify-end gap-2\">\n\t\t\t\t\t\t<button\n\t\t\t\t\t\t\ttype=\"button\"\n\t\t\t\t\t\t\tclassName=\"ft-approval-deny text-muted-foreground hover:text-foreground hover:bg-foreground/5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors disabled:pointer-events-none disabled:opacity-60\"\n\t\t\t\t\t\t\tdisabled={busy}\n\t\t\t\t\t\t\tonClick={() => decide(\"denied\")}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t{denyLabel}\n\t\t\t\t\t\t</button>\n\t\t\t\t\t\t<button\n\t\t\t\t\t\t\ttype=\"button\"\n\t\t\t\t\t\t\tclassName={cn(\n\t\t\t\t\t\t\t\t\"ft-approval-approve bg-foreground text-background hover:bg-foreground/90 rounded-md px-3 py-1.5 text-xs font-medium transition-colors disabled:pointer-events-none disabled:opacity-60\",\n\t\t\t\t\t\t\t\tdestructive && \"ft-destructive\"\n\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\tdisabled={busy}\n\t\t\t\t\t\t\tonClick={() => decide(\"approved\")}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t{approveLabel}\n\t\t\t\t\t\t</button>\n\t\t\t\t\t</div>\n\t\t\t\t) : (\n\t\t\t\t\t<p\n\t\t\t\t\t\tref={resolvedRef}\n\t\t\t\t\t\ttabIndex={-1}\n\t\t\t\t\t\tclassName={cn(\n\t\t\t\t\t\t\t\"ft-approval-resolved focus-visible:ring-ring flex items-center gap-1.5 rounded-md text-xs font-medium focus-visible:ring-1 focus-visible:outline-none\",\n\t\t\t\t\t\t\tisApproved && \"ft-approved\"\n\t\t\t\t\t\t)}\n\t\t\t\t\t>\n\t\t\t\t\t\t<span className=\"flex-none\" aria-hidden=\"true\">\n\t\t\t\t\t\t\t<svg\n\t\t\t\t\t\t\t\tclassName=\"size-3.5\"\n\t\t\t\t\t\t\t\tviewBox=\"0 0 24 24\"\n\t\t\t\t\t\t\t\tfill=\"none\"\n\t\t\t\t\t\t\t\tstroke=\"currentColor\"\n\t\t\t\t\t\t\t\tstrokeWidth=\"2.5\"\n\t\t\t\t\t\t\t\tstrokeLinecap=\"round\"\n\t\t\t\t\t\t\t\tstrokeLinejoin=\"round\"\n\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t{isApproved ? (\n\t\t\t\t\t\t\t\t\t<path d=\"m20 6-11 11-5-5\" />\n\t\t\t\t\t\t\t\t) : (\n\t\t\t\t\t\t\t\t\t<>\n\t\t\t\t\t\t\t\t\t\t<path d=\"M18 6 6 18\" />\n\t\t\t\t\t\t\t\t\t\t<path d=\"m6 6 12 12\" />\n\t\t\t\t\t\t\t\t\t</>\n\t\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t</svg>\n\t\t\t\t\t\t</span>\n\t\t\t\t\t\t{resolvedLabel}\n\t\t\t\t\t</p>\n\t\t\t\t)}\n\t\t\t</div>\n\t\t</div>\n\t);\n});\n\nApprovalCard.displayName = \"ApprovalCard\";\n","type":"registry:ui","target":"@ui/fancy/components/approval-card/ApprovalCard.tsx"},{"path":"react/src/components/approval-card/approval-card.css","content":"/*\n * Every colour is read at the point of use through two hooks: this card's own\n * `--ft-approval-*`, then the `--ft-status-*` vocabulary the whole AI family\n * shares, then the literal. Setting either anywhere up the tree retints the\n * card without having to win a specificity fight against these scoped rules,\n * and the shared one recolours every sibling component at once.\n */\n.ft-approval.ft-destructive {\n\tbackground: var(\n\t\t--ft-approval-danger-bg,\n\t\tcolor-mix(\n\t\t\tin oklab,\n\t\t\tvar(\n\t\t\t\t\t--ft-approval-danger,\n\t\t\t\t\tvar(--ft-status-error, light-dark(oklch(0.5 0.19 25), oklch(0.7 0.18 25)))\n\t\t\t\t)\n\t\t\t\t6%,\n\t\t\ttransparent\n\t\t)\n\t);\n\tborder-color: var(\n\t\t--ft-approval-danger-border,\n\t\tcolor-mix(\n\t\t\tin oklab,\n\t\t\tvar(\n\t\t\t\t\t--ft-approval-danger,\n\t\t\t\t\tvar(--ft-status-error, light-dark(oklch(0.5 0.19 25), oklch(0.7 0.18 25)))\n\t\t\t\t)\n\t\t\t\t22%,\n\t\t\ttransparent\n\t\t)\n\t);\n}\n\n.ft-approval.ft-destructive .ft-approval-icon {\n\tcolor: var(\n\t\t--ft-approval-danger,\n\t\tvar(--ft-status-error, light-dark(oklch(0.5 0.19 25), oklch(0.7 0.18 25)))\n\t);\n}\n\n/*\n * Unlayered scoped rules beat Tailwind's layered utilities, so the destructive\n * button overrides `bg-foreground` / `text-background` without `!important`.\n * Its text flips with the scheme because no single ink clears 4.5:1 against a\n * red that is dark on a light page and light on a dark one.\n */\n.ft-approval-approve.ft-destructive {\n\tbackground: var(\n\t\t--ft-approval-danger,\n\t\tvar(--ft-status-error, light-dark(oklch(0.5 0.19 25), oklch(0.7 0.18 25)))\n\t);\n\tcolor: var(--ft-approval-danger-fg, light-dark(oklch(0.985 0 0), oklch(0.16 0 0)));\n}\n\n.ft-approval-approve.ft-destructive:hover:not(:disabled) {\n\tbackground: color-mix(\n\t\tin oklab,\n\t\tvar(\n\t\t\t\t--ft-approval-danger,\n\t\t\t\tvar(--ft-status-error, light-dark(oklch(0.5 0.19 25), oklch(0.7 0.18 25)))\n\t\t\t)\n\t\t\t88%,\n\t\ttransparent\n\t);\n}\n\n/* Denied stays deliberately quiet — a refusal is not a failure. */\n.ft-approval-resolved {\n\tcolor: var(--ft-approval-denied, color-mix(in oklab, currentColor 65%, transparent));\n}\n\n.ft-approval-resolved.ft-approved {\n\tcolor: var(\n\t\t--ft-approval-approved,\n\t\tvar(--ft-status-done, light-dark(oklch(0.5 0.14 145), oklch(0.72 0.15 145)))\n\t);\n}\n\n/*\n * The verdict's fade is the whole animation, and it lives behind the query, so\n * reduced motion is not a degraded variant to keep in sync: the footer simply\n * swaps, with the same colours and the same words.\n *\n * The footer's height is deliberately left alone. A transition needs the\n * specified value to change, and `height: auto` never changes — only the\n * content under it does — so an `interpolate-size` rule here would have been\n * dead weight rather than a smooth collapse.\n */\n@media (prefers-reduced-motion: no-preference) {\n\t.ft-approval-resolved {\n\t\tanimation: ft-approval-resolve-in 240ms cubic-bezier(0.4, 0, 0.2, 1);\n\t}\n}\n\n@keyframes ft-approval-resolve-in {\n\tfrom {\n\t\topacity: 0;\n\t\ttransform: translateY(-3px);\n\t}\n\tto {\n\t\topacity: 1;\n\t\ttransform: none;\n\t}\n}\n","type":"registry:ui","target":"@ui/fancy/components/approval-card/approval-card.css"},{"path":"react/src/components/approval-card/index.ts","content":"\"use client\";\n\nexport { ApprovalCard } from \"./ApprovalCard\";\nexport type { ApprovalCardProps, ApprovalState } from \"./ApprovalCard\";\n","type":"registry:ui","target":"@ui/fancy/components/approval-card/index.ts"}],"meta":{"license":"MIT","package":"fancy-ui-react","version":"0.7.0","source":"https://fancy-ui.rama.app/docs/components/approval-card?framework=react"}}