{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "approval-card", "type": "registry:ui", "title": "Approval Card", "description": "An inline permission request that answers to Enter and Escape, then folds to one line.", "categories": [ "ai-agents" ], "dependencies": [ "motion" ], "registryDependencies": [ "https://www.stealth.pm/r/tokens.json", "https://www.stealth.pm/r/cn.json", "https://www.stealth.pm/r/motion.json", "https://www.stealth.pm/r/use-controllable-state.json" ], "files": [ { "path": "components/ui/approval-card.tsx", "content": "\"use client\";\nimport { AnimatePresence, motion, useReducedMotion } from \"motion/react\";\nimport { useEffect, useId, useRef, useState } from \"react\";\nimport { cn } from \"@/lib/cn\";\nimport { ease, spring } from \"@/lib/motion\";\nimport { useControllableState } from \"@/lib/use-controllable-state\";\n\nexport type ApprovalDecision = \"pending\" | \"allowed\" | \"always\" | \"denied\" | \"expired\";\nexport type ApprovalRisk = \"low\" | \"medium\" | \"high\";\n\nexport type ApprovalCardProps = Omit, \"title\" | \"children\"> & {\n /** What the agent wants to do, as a verb phrase: “Run a database migration”. */\n title: React.ReactNode;\n /** The exact target, one line: “on billing-staging”, “to alex@acme.dev”. */\n description?: React.ReactNode;\n /** The specifics: the command, the diff, the recipient, the amount. */\n children?: React.ReactNode;\n risk?: ApprovalRisk;\n /** Why it carries that risk, in one sentence. */\n riskReason?: React.ReactNode;\n /** Short text for the decided line. Defaults to the title. */\n summary?: React.ReactNode;\n /** Offers a third button that allows this kind of action from now on. Never offered for high risk. */\n alwaysLabel?: string;\n decision?: ApprovalDecision;\n defaultDecision?: ApprovalDecision;\n onDecisionChange?: (decision: ApprovalDecision) => void;\n /** Milliseconds to wait before denying on the person's behalf. The timer pauses while the pointer is over the card. */\n timeout?: number;\n /** Move focus to the card when it appears, so Enter and Escape answer it. */\n autoFocus?: boolean;\n};\n\nconst riskCopy: Record = { low: \"Low risk\", medium: \"Medium risk\", high: \"High risk\" };\nconst decided: Record, string> = { allowed: \"Allowed\", always: \"Always allowed\", denied: \"Denied\", expired: \"Timed out\" };\n\n/**\n * A request from an agent, in the flow of the conversation, waiting for a person.\n * Enter allows and Escape denies while the card has focus; once answered it folds\n * to a single line that records what was decided.\n */\nexport function ApprovalCard({\n title,\n description,\n children,\n risk = \"medium\",\n riskReason,\n summary,\n alwaysLabel,\n decision: decisionProp,\n defaultDecision = \"pending\",\n onDecisionChange,\n timeout,\n autoFocus = true,\n className,\n ...rest\n}: ApprovalCardProps) {\n const reduce = useReducedMotion();\n const [decision, setDecision] = useControllableState({ value: decisionProp, defaultValue: defaultDecision, onChange: onDecisionChange });\n const pending = decision === \"pending\";\n const card = useRef(null);\n const line = useRef(null);\n const hadFocus = useRef(false);\n const titleId = useId();\n const high = risk === \"high\";\n const offerAlways = !!alwaysLabel && !high;\n\n const decide = (next: Exclude) => {\n if (!pending) return;\n hadFocus.current = !!card.current?.contains(document.activeElement);\n setDecision(next);\n };\n\n // Countdown: one tick a second, paused while the pointer rests on the card.\n // Running out denies. Never the other way round.\n const [left, setLeft] = useState(timeout ?? 0);\n const [paused, setPaused] = useState(false);\n const remaining = useRef(timeout ?? 0);\n const expire = useRef(() => {});\n useEffect(() => {\n expire.current = () => setDecision(\"expired\");\n });\n useEffect(() => {\n if (!pending || timeout == null || paused) return;\n const id = window.setInterval(() => {\n remaining.current = Math.max(0, remaining.current - 1000);\n setLeft(remaining.current);\n if (remaining.current === 0) expire.current();\n }, 1000);\n return () => window.clearInterval(id);\n }, [pending, timeout, paused]);\n\n // Focus arrives with the request, and moves to the record once it is answered.\n useEffect(() => {\n if (pending && autoFocus) card.current?.focus({ preventScroll: true });\n }, [pending, autoFocus]);\n useEffect(() => {\n if (!pending && hadFocus.current) {\n hadFocus.current = false;\n line.current?.focus({ preventScroll: true });\n }\n }, [pending]);\n\n // Measure the content so the card can shrink to one line instead of snapping.\n const inner = useRef(null);\n const [height, setHeight] = useState();\n useEffect(() => {\n const el = inner.current;\n if (!el) return;\n const ro = new ResizeObserver(([entry]) => setHeight(entry.borderBoxSize?.[0]?.blockSize ?? el.offsetHeight));\n ro.observe(el);\n return () => ro.disconnect();\n }, []);\n\n const onKeyDown = (e: React.KeyboardEvent) => {\n if (!pending || e.defaultPrevented) return;\n if (e.key === \"Escape\") {\n e.preventDefault();\n decide(\"denied\");\n }\n // Enter on the card itself; on a focused button the button's own action wins.\n // High-risk requests don't take the shortcut: allowing them is a deliberate press.\n if (e.key === \"Enter\" && e.target === e.currentTarget && !high) {\n e.preventDefault();\n decide(\"allowed\");\n }\n };\n\n const seconds = Math.ceil(left / 1000);\n\n return (\n \n \n
\n \n {pending ? (\n e.pointerType === \"mouse\" && setPaused(true)}\n onPointerLeave={() => setPaused(false)}\n className=\"rounded-[11px] outline-none focus-visible:outline-solid focus-visible:outline-1 focus-visible:-outline-offset-1 focus-visible:outline-fg-3\"\n exit={reduce ? { opacity: 0, transition: { duration: 0.12 } } : { opacity: 0, y: -6, filter: \"blur(2px)\", transition: { duration: 0.16, ease: ease.in } }}\n >\n
\n
\n \n \n \n
\n

\n {title}\n

\n \n \n {riskCopy[risk]}\n \n

{description}

\n {timeout != null && (\n {paused ? \"Timer paused\" : `Denies in ${seconds}s`}\n )}\n
\n
\n\n {children != null &&
{children}
}\n\n {riskReason != null && (\n

\n \n \n \n \n \n {riskReason}\n

\n )}\n
\n\n
\n {/* The divider doubles as the countdown: it drains toward the left. */}\n {timeout != null && (\n \n \n \n )}\n {offerAlways && (\n decide(\"always\")}>\n {alwaysLabel}\n \n )}\n \n \n
\n \n ) : (\n \n \n {decided[decision]}\n {decision === \"always\" && alwaysLabel ? alwaysLabel.replace(/^always allow\\s*/i, \"\") || (summary ?? title) : (summary ?? title)}\n {decision === \"expired\" && timeout != null && No answer in {Math.round(timeout / 1000)}s}\n \n )}\n \n
\n \n \n {pending ? \"\" : decided[decision]}\n \n \n );\n}\n\nfunction Button({ variant, hint, className, children, ...rest }: React.ComponentProps<\"button\"> & { variant: \"primary\" | \"secondary\" | \"ghost\"; hint?: string }) {\n return (\n \n {children}\n {hint && (\n