{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"recommendation-card","type":"registry:ui","title":"RecommendationCard","description":"An agent's proposal awaiting an answer: a kicker, the recommendation, a confidence figure counted up beside a ring that fills to match, and two buttons that collapse into one quiet resolved line","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/number-ticker.json","https://fancy-ui.rama.app/r/sound.json","https://fancy-ui.rama.app/r/utils.json"],"files":[{"path":"react/src/components/recommendation-card/RecommendationCard.tsx","content":"\"use client\";\n\nimport { forwardRef, useEffect, useRef, useState } from \"react\";\nimport type { ReactNode } from \"react\";\nimport { useIsomorphicLayoutEffect } from \"../../internals/dom/ssr\";\nimport { useSoundCue } from \"../../sound/use-sound\";\nimport { cn } from \"../../utils\";\nimport { NumberTicker } from \"../number-ticker/index\";\nimport \"./recommendation-card.css\";\n\n/** Where a proposal stands: still on the table, taken up, or waved off. */\nexport type RecommendationState = \"open\" | \"accepted\" | \"dismissed\";\n\n/** Shown and spoken once the proposal is behind us. */\nconst RESOLVED_LABELS = {\n\taccepted: \"Applied\",\n\tdismissed: \"Dismissed\",\n} as const;\n\n/** How long the percentage takes to count up, before the reduced-motion clamp. */\nconst TICKER_MS = 900;\n\n/** Ring geometry. The radius picks the circumference the dash array runs on. */\nconst RING_R = 13;\nconst RING_C = 2 * Math.PI * RING_R;\n\n/**\n * Props for RecommendationCard\n */\nexport interface RecommendationCardProps {\n\t/** What the agent is proposing, e.g. \"Add an index on orders.customer_id\". */\n\ttitle: string;\n\t/** Secondary muted line under the title — the reasoning, the expected effect. */\n\tdescription?: string;\n\t/**\n\t * How sure the agent is, from 0 to 1. Omitted, the whole confidence block\n\t * disappears rather than reading as zero. Out-of-range numbers are clamped.\n\t */\n\tconfidence?: number;\n\t/** Label for the confirm button. */\n\tacceptLabel?: string;\n\t/** Label for the decline button. */\n\tdismissLabel?: string;\n\t/** Called when the recommendation is accepted, after `state` has been written. */\n\tonAccept?: () => void;\n\t/** Called when the recommendation is dismissed, after `state` has been written. */\n\tonDismiss?: () => void;\n\t/**\n\t * Where the recommendation stands. Controlled when supplied: pair it with\n\t * `onStateChange`, the React counterpart of the Svelte source's `bind:state`.\n\t * Left out, the card keeps the state itself and starts at `\"open\"`.\n\t */\n\tstate?: RecommendationState;\n\t/** Called with the new state whenever it changes, however the change happened. */\n\tonStateChange?: (state: RecommendationState) => void;\n\t/** Small kicker above the title, e.g. \"Suggestion\". */\n\tbadge?: string;\n\t/** The detail region between the header and the footer — a preview of the change. */\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 proposal an agent puts on the table: a title, an optional confidence ring\n * that sweeps to its figure, and a footer that collapses to a one-line verdict\n * once someone answers.\n *\n * The root element arrives through the ref channel rather than a `ref` prop,\n * per PORTING.md — the Svelte source declares `ref = $bindable(null)`.\n */\nexport const RecommendationCard = forwardRef<HTMLDivElement, RecommendationCardProps>(\n\tfunction RecommendationCard(\n\t\t{\n\t\t\ttitle,\n\t\t\tdescription,\n\t\t\tconfidence,\n\t\t\tacceptLabel = \"Apply\",\n\t\t\tdismissLabel = \"Dismiss\",\n\t\t\tonAccept,\n\t\t\tonDismiss,\n\t\t\tstate,\n\t\t\tonStateChange,\n\t\t\tbadge,\n\t\t\tchildren,\n\t\t\tclassName,\n\t\t\tsound = false,\n\t\t},\n\t\tref\n\t) {\n\t\t// `state = $bindable(\"open\")` on the Svelte side. A supplied prop wins and\n\t\t// the consumer owns the value; with nothing supplied the component owns it,\n\t\t// starting at the same \"open\" default.\n\t\tconst [uncontrolledState, setUncontrolledState] = useState<RecommendationState>(\"open\");\n\t\tconst isControlled = state !== undefined;\n\t\tconst current = isControlled ? state : uncontrolledState;\n\n\t\tconst isOpen = current === \"open\";\n\t\tconst resolvedLabel =\n\t\t\tcurrent === \"accepted\" ? RESOLVED_LABELS.accepted : RESOLVED_LABELS.dismissed;\n\n\t\t// A missing confidence is not a confidence of zero: the block only exists for\n\t\t// a real number, so `NaN` and `Infinity` are treated as \"not reported\".\n\t\tconst hasConfidence = typeof confidence === \"number\" && Number.isFinite(confidence);\n\t\tconst fraction = hasConfidence ? Math.min(1, Math.max(0, confidence as number)) : 0;\n\t\tconst percent = Math.round(fraction * 100);\n\n\t\t/** Three bands, borrowing the run-status vocabulary the AI family already shares. */\n\t\tconst band = fraction >= 0.75 ? \"done\" : fraction >= 0.5 ? \"running\" : \"pending\";\n\n\t\tconst [filled, setFilled] = useState(false);\n\t\tconst [reduced, setReduced] = useState(false);\n\n\t\tconst playCue = useSoundCue(sound);\n\n\t\t// `current` inside `decide` is the value of the render that built the\n\t\t// closure, so two clicks dispatched in one synchronous batch would both read\n\t\t// \"open\" and resolve the proposal twice. The ref carries the answer across\n\t\t// that gap, and is put back in step with `current` on every commit so a\n\t\t// proposal reopened from outside can be answered again.\n\t\tconst currentRef = useRef<RecommendationState>(current);\n\t\tuseIsomorphicLayoutEffect(() => {\n\t\t\tcurrentRef.current = current;\n\t\t}, [current]);\n\n\t\t/** Where focus lands once the buttons it might have held are gone. */\n\t\tconst resolvedRef = useRef<HTMLParagraphElement | null>(null);\n\t\tconst shouldFocusResolved = useRef(false);\n\n\t\t// The ring starts empty and fills once the target is written, so its sweep runs\n\t\t// from a known origin — a transition never animates from a value the browser\n\t\t// has not painted yet.\n\t\tconst sweep = filled ? fraction : 0;\n\t\tconst ringOffset = RING_C * (1 - sweep);\n\n\t\t// The counter is JS-driven, so reduced motion is honoured by collapsing its\n\t\t// duration rather than by a media query: it lands on the number immediately.\n\t\tconst tickerMs = Math.max(0.01, reduced ? 0 : TICKER_MS);\n\n\t\t// A layout effect, not a passive one: the reduced-motion branch below writes\n\t\t// the settled arc, and it has to land in the commit that mounts the card or\n\t\t// the browser paints the empty ring for a frame first — the very artefact\n\t\t// the branch exists to remove.\n\t\tuseIsomorphicLayoutEffect(() => {\n\t\t\tconst isReduced = window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches;\n\t\t\tsetReduced(isReduced);\n\n\t\t\t// Reduced motion wants the settled arc, not a fast one: write it in the same\n\t\t\t// breath so there is never a frame of empty ring to notice.\n\t\t\tif (isReduced) {\n\t\t\t\tsetFilled(true);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// The mount effect still runs inside the frame that mounted the card, so\n\t\t\t// setting the target here would land in the same paint as the empty ring and\n\t\t\t// the browser would have nothing to transition between. Two frames out is the\n\t\t\t// guarantee: the first callback can still belong to the mounting frame, the\n\t\t\t// second cannot, so the empty ring is on screen before the target is written.\n\t\t\tlet second = 0;\n\t\t\tconst first = requestAnimationFrame(() => {\n\t\t\t\tsecond = requestAnimationFrame(() => {\n\t\t\t\t\tsetFilled(true);\n\t\t\t\t});\n\t\t\t});\n\n\t\t\treturn () => {\n\t\t\t\tcancelAnimationFrame(first);\n\t\t\t\tcancelAnimationFrame(second);\n\t\t\t};\n\t\t}, []);\n\n\t\t// The button just pressed is about to leave the DOM along with the rest of the\n\t\t// action group, so focus is moved to the verdict once it has painted —\n\t\t// otherwise the browser drops it back to the document body.\n\t\tuseEffect(() => {\n\t\t\tif (shouldFocusResolved.current) {\n\t\t\t\tshouldFocusResolved.current = false;\n\t\t\t\tresolvedRef.current?.focus();\n\t\t\t}\n\t\t});\n\n\t\t/**\n\t\t * The answer is written to `state` before the callback fires, so a consumer\n\t\t * reading the controlled value from inside its own handler already sees it.\n\t\t * Re-entry is refused rather than re-announced: a proposal resolves once.\n\t\t */\n\t\tfunction decide(next: \"accepted\" | \"dismissed\") {\n\t\t\tif (currentRef.current !== \"open\") return;\n\t\t\tcurrentRef.current = next;\n\t\t\tif (!isControlled) {\n\t\t\t\tsetUncontrolledState(next);\n\t\t\t}\n\t\t\tonStateChange?.(next);\n\t\t\t// The deliberate asymmetry with ApprovalCard: accepting is a commit\n\t\t\t// (`select`), dismissing is a close (`close`), never `error` either way.\n\t\t\tplayCue(next === \"accepted\" ? \"select\" : \"close\");\n\t\t\tif (next === \"accepted\") onAccept?.();\n\t\t\telse onDismiss?.();\n\t\t\tshouldFocusResolved.current = true;\n\t\t}\n\n\t\treturn (\n\t\t\t<div\n\t\t\t\tref={ref}\n\t\t\t\tclassName={cn(\n\t\t\t\t\t\"ft-rec border-border w-full rounded-lg border p-4 text-sm\",\n\t\t\t\t\tisOpen && \"bg-card/50\",\n\t\t\t\t\tclassName\n\t\t\t\t)}\n\t\t\t\trole=\"group\"\n\t\t\t\taria-label={title}\n\t\t\t\tdata-state={current}\n\t\t\t>\n\t\t\t\t<div className=\"flex items-start gap-3\">\n\t\t\t\t\t<div className=\"min-w-0 flex-1\">\n\t\t\t\t\t\t{badge && (\n\t\t\t\t\t\t\t<p className=\"ft-rec-badge text-muted-foreground mb-1 text-[0.6875rem] font-medium uppercase\">\n\t\t\t\t\t\t\t\t{badge}\n\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t)}\n\t\t\t\t\t\t<p className=\"ft-rec-title text-foreground font-medium\">{title}</p>\n\t\t\t\t\t\t{description && (\n\t\t\t\t\t\t\t<p className=\"ft-rec-description text-muted-foreground mt-0.5 text-xs leading-relaxed\">\n\t\t\t\t\t\t\t\t{description}\n\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t)}\n\t\t\t\t\t</div>\n\n\t\t\t\t\t{hasConfidence && (\n\t\t\t\t\t\t/*\n\t\t\t\t\t\t\tOne label for the pair: the counter is mid-animation for most of its\n\t\t\t\t\t\t\tlife and the ring says nothing out loud, so assistive tech is given the\n\t\t\t\t\t\t\tsettled figure once and both halves are hidden behind it.\n\t\t\t\t\t\t*/\n\t\t\t\t\t\t<div\n\t\t\t\t\t\t\tclassName=\"ft-rec-confidence flex flex-none items-center gap-2\"\n\t\t\t\t\t\t\trole=\"img\"\n\t\t\t\t\t\t\taria-label={`Confidence ${percent}%`}\n\t\t\t\t\t\t\tdata-band={band}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<span\n\t\t\t\t\t\t\t\tclassName=\"ft-rec-percent text-foreground text-xs font-medium tabular-nums\"\n\t\t\t\t\t\t\t\taria-hidden=\"true\"\n\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t<NumberTicker\n\t\t\t\t\t\t\t\t\tvalue={percent}\n\t\t\t\t\t\t\t\t\tduration={tickerMs}\n\t\t\t\t\t\t\t\t\tclassName=\"text-inherit dark:text-inherit\"\n\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</span>\n\n\t\t\t\t\t\t\t<svg className=\"ft-rec-ring\" viewBox=\"0 0 32 32\" aria-hidden=\"true\">\n\t\t\t\t\t\t\t\t<circle\n\t\t\t\t\t\t\t\t\tclassName=\"ft-rec-ring-track\"\n\t\t\t\t\t\t\t\t\tcx=\"16\"\n\t\t\t\t\t\t\t\t\tcy=\"16\"\n\t\t\t\t\t\t\t\t\tr={RING_R}\n\t\t\t\t\t\t\t\t\tfill=\"none\"\n\t\t\t\t\t\t\t\t\tstrokeWidth=\"3\"\n\t\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t\t<circle\n\t\t\t\t\t\t\t\t\tclassName={cn(\n\t\t\t\t\t\t\t\t\t\t\"ft-rec-ring-value\",\n\t\t\t\t\t\t\t\t\t\tband === \"done\" && \"ft-status-done\",\n\t\t\t\t\t\t\t\t\t\tband === \"running\" && \"ft-status-running\",\n\t\t\t\t\t\t\t\t\t\tband === \"pending\" && \"ft-status-pending\"\n\t\t\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t\t\tcx=\"16\"\n\t\t\t\t\t\t\t\t\tcy=\"16\"\n\t\t\t\t\t\t\t\t\tr={RING_R}\n\t\t\t\t\t\t\t\t\tfill=\"none\"\n\t\t\t\t\t\t\t\t\tstrokeWidth=\"3\"\n\t\t\t\t\t\t\t\t\tstrokeLinecap=\"round\"\n\t\t\t\t\t\t\t\t\tstrokeDasharray={RING_C}\n\t\t\t\t\t\t\t\t\tstrokeDashoffset={ringOffset}\n\t\t\t\t\t\t\t\t\ttransform=\"rotate(-90 16 16)\"\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</div>\n\t\t\t\t\t)}\n\t\t\t\t</div>\n\n\t\t\t\t{/*\n\t\t\t\t\tNullish and boolean children mean \"no detail region\"; every other\n\t\t\t\t\tvalue renders inside the wrapper, so a numeric `0` cannot leak out\n\t\t\t\t\tas bare text the way a plain truthiness test would let it.\n\t\t\t\t*/}\n\t\t\t\t{children != null && children !== false && (\n\t\t\t\t\t<div className=\"ft-rec-detail mt-3 min-w-0\">{children}</div>\n\t\t\t\t)}\n\n\t\t\t\t{/*\n\t\t\t\t\tOne footer element, mounted from the first render, so the live region\n\t\t\t\t\texists before the outcome lands in it — a region that appears at the same\n\t\t\t\t\tmoment as its own text is routinely missed by screen readers.\n\t\t\t\t*/}\n\t\t\t\t<div className=\"ft-rec-foot mt-3\" aria-live=\"polite\">\n\t\t\t\t\t{isOpen ? (\n\t\t\t\t\t\t<div className=\"ft-rec-actions flex flex-wrap items-center justify-end gap-2\">\n\t\t\t\t\t\t\t<button\n\t\t\t\t\t\t\t\ttype=\"button\"\n\t\t\t\t\t\t\t\tclassName=\"ft-rec-dismiss text-muted-foreground hover:text-foreground hover:bg-foreground/5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors\"\n\t\t\t\t\t\t\t\tonClick={() => decide(\"dismissed\")}\n\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t{dismissLabel}\n\t\t\t\t\t\t\t</button>\n\t\t\t\t\t\t\t<button\n\t\t\t\t\t\t\t\ttype=\"button\"\n\t\t\t\t\t\t\t\tclassName=\"ft-rec-accept bg-foreground text-background hover:bg-foreground/90 rounded-md px-3 py-1.5 text-xs font-medium transition-colors\"\n\t\t\t\t\t\t\t\tonClick={() => decide(\"accepted\")}\n\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t{acceptLabel}\n\t\t\t\t\t\t\t</button>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t) : (\n\t\t\t\t\t\t<p\n\t\t\t\t\t\t\tref={resolvedRef}\n\t\t\t\t\t\t\ttabIndex={-1}\n\t\t\t\t\t\t\tclassName={cn(\n\t\t\t\t\t\t\t\t\"ft-rec-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\t\tcurrent === \"accepted\" && \"ft-accepted\"\n\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<span className=\"flex-none\" aria-hidden=\"true\">\n\t\t\t\t\t\t\t\t<svg\n\t\t\t\t\t\t\t\t\tclassName=\"size-3.5\"\n\t\t\t\t\t\t\t\t\tviewBox=\"0 0 24 24\"\n\t\t\t\t\t\t\t\t\tfill=\"none\"\n\t\t\t\t\t\t\t\t\tstroke=\"currentColor\"\n\t\t\t\t\t\t\t\t\tstrokeWidth=\"2.5\"\n\t\t\t\t\t\t\t\t\tstrokeLinecap=\"round\"\n\t\t\t\t\t\t\t\t\tstrokeLinejoin=\"round\"\n\t\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t\t{current === \"accepted\" ? (\n\t\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\t) : (\n\t\t\t\t\t\t\t\t\t\t<>\n\t\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\t<path d=\"m6 6 12 12\" />\n\t\t\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</svg>\n\t\t\t\t\t\t\t</span>\n\t\t\t\t\t\t\t{resolvedLabel}\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\t\t);\n\t}\n);\n\nRecommendationCard.displayName = \"RecommendationCard\";\n","type":"registry:ui","target":"@ui/fancy/components/recommendation-card/RecommendationCard.tsx"},{"path":"react/src/components/recommendation-card/index.ts","content":"\"use client\";\n\nexport { RecommendationCard } from \"./RecommendationCard\";\nexport type { RecommendationCardProps, RecommendationState } from \"./RecommendationCard\";\n","type":"registry:ui","target":"@ui/fancy/components/recommendation-card/index.ts"},{"path":"react/src/components/recommendation-card/recommendation-card.css","content":"/*\n * Every colour is read at the point of use through two hooks: this card's own\n * `--ft-rec-*`, then the `--ft-status-*` vocabulary the whole AI family shares,\n * then the literal. Setting either anywhere up the tree retints the card\n * without having to win a specificity fight against these rules, and the shared\n * one recolours every sibling component at once.\n */\n.ft-rec-badge {\n\tletter-spacing: 0.08em;\n}\n\n.ft-rec-ring {\n\twidth: var(--ft-rec-ring-size, 1.75rem);\n\theight: var(--ft-rec-ring-size, 1.75rem);\n}\n\n.ft-rec-ring-track {\n\tstroke: var(--ft-rec-track, color-mix(in oklab, currentColor 15%, transparent));\n}\n\n/*\n * The band is carried by the arc's length as much as by its hue — a quarter\n * ring and a full ring are told apart without seeing colour at all, and the\n * figure beside it says the number in words either way.\n */\n.ft-rec-ring-value.ft-status-done {\n\tstroke: var(\n\t\t--ft-rec-high,\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.ft-rec-ring-value.ft-status-running {\n\tstroke: var(\n\t\t--ft-rec-medium,\n\t\tvar(--ft-status-running, light-dark(oklch(0.5 0.18 265), oklch(0.72 0.15 265)))\n\t);\n}\n\n.ft-rec-ring-value.ft-status-pending {\n\tstroke: var(\n\t\t--ft-rec-low,\n\t\tvar(--ft-status-pending, light-dark(oklch(0.5 0.02 260), oklch(0.72 0.02 260)))\n\t);\n}\n\n/* A dismissal is not a failure, so it stays deliberately quiet. */\n.ft-rec-resolved {\n\tcolor: var(--ft-rec-dismissed, color-mix(in oklab, currentColor 65%, transparent));\n}\n\n.ft-rec-resolved.ft-accepted {\n\tcolor: var(\n\t\t--ft-rec-accepted,\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 * Both moving parts live behind the query, so reduced motion is not a degraded\n * variant to keep in sync: the ring is drawn at its final length and the\n * footer simply swaps, with the same colours and the same words. The counter\n * is JS-driven and collapses its own duration alongside.\n */\n@media (prefers-reduced-motion: no-preference) {\n\t.ft-rec-ring-value {\n\t\ttransition: stroke-dashoffset 700ms cubic-bezier(0.4, 0, 0.2, 1);\n\t}\n\n\t.ft-rec-resolved {\n\t\tanimation: ft-rec-resolve-in 240ms cubic-bezier(0.4, 0, 0.2, 1);\n\t}\n}\n\n@keyframes ft-rec-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/recommendation-card/recommendation-card.css"}],"meta":{"license":"MIT","package":"fancy-ui-react","version":"0.7.0","source":"https://fancy-ui.rama.app/docs/components/recommendation-card?framework=react"}}