{
  "schemaVersion": 1,
  "target": "react",
  "name": "recommendation-card",
  "version": "0.1.0",
  "category": "ai-elements",
  "title": "Recommendation Card",
  "description": "One action an agent suggests, with a short rationale, a three-bar confidence meter, Accept, and an alternatives drawer that swaps another option into the main slot as a shared element.",
  "tags": [
    "ai",
    "agent",
    "recommendation",
    "suggestion",
    "confidence",
    "decision",
    "motion"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {
    "motion": "^14.14.0"
  },
  "registryDependencies": [],
  "docsPath": "/components/recommendation-card",
  "props": [
    {
      "name": "options",
      "type": "{ id, title, rationale?, confidence, media?, note? }[]",
      "description": "The first option is the recommendation; the rest are alternatives. confidence is high, medium, low or none."
    },
    {
      "name": "question",
      "type": "ReactNode",
      "description": "The question being answered, shown above the suggestion."
    },
    {
      "name": "defaultValue",
      "type": "string",
      "default": "the first option",
      "description": "Id of the option in the main slot initially."
    },
    {
      "name": "onValueChange",
      "type": "(id) => void",
      "description": "Called when an alternative is swapped in."
    },
    {
      "name": "onAccept",
      "type": "(option) => void",
      "description": "Called with the option in the main slot when Accept is pressed."
    },
    {
      "name": "onDismiss",
      "type": "() => void",
      "description": "Adds a Dismiss button."
    },
    {
      "name": "onUndo",
      "type": "() => void",
      "description": "Adds an Undo button after accepting."
    },
    {
      "name": "acceptLabel",
      "type": "string",
      "default": "\"Accept\"",
      "description": "Text of the primary button."
    },
    {
      "name": "acceptedLabel",
      "type": "(option) => ReactNode",
      "default": "\"Accepted\"",
      "description": "Text after accepting."
    },
    {
      "name": "ConfidenceMeter level",
      "type": "\"high\" | \"medium\" | \"low\" | \"none\"",
      "description": "ConfidenceMeter: three rising bars; three for high, two for medium, one for low, none for no signal."
    },
    {
      "name": "ConfidenceMeter showLabel",
      "type": "boolean",
      "default": "false",
      "description": "ConfidenceMeter: shows the level as text beside the bars."
    }
  ],
  "accessibility": [
    "The card is a section labelled by the suggestion's title. The confidence meter is role=\"img\" with its level as the label, and the level is also written out.",
    "Alternatives is a button with aria-expanded and aria-controls; the closed drawer is inert. Each alternative is a button that swaps it in, and focus stays on the same row afterwards.",
    "Swapping and accepting are announced through a polite live region (\"Now suggesting: Assign to Tomas Lindqvist. Medium confidence.\").",
    "Under reduced motion the shared-element travel, the rationale cross-fade and the drawer are instant."
  ],
  "states": [
    "suggested",
    "alternatives-open",
    "swapped",
    "accepted"
  ],
  "files": [
    {
      "path": "agent/recommendation-card.tsx",
      "content": "\"use client\";\n\nimport { AnimatePresence, LayoutGroup, motion, useReducedMotion } from \"motion/react\";\nimport { type ComponentProps, type ReactNode, useEffect, useId, useRef, useState } from \"react\";\n\n/*\n * Recommendation card: one action an agent suggests, why, and how sure it is, with Accept as the\n * main action. Alternatives open in a drawer inside the card; choosing one swaps it into the main\n * slot as a shared element (its title and media travel up while the previous suggestion travels\n * down into the list), and the confidence meter refills bar by bar.\n *\n * Under reduced motion the swap and the drawer are instant.\n */\n\nexport type ConfidenceLevel = \"high\" | \"medium\" | \"low\" | \"none\";\n\nexport interface RecommendationOption {\n  id: string;\n  /** The action, for example \"Assign to Priya Raman\". */\n  title: ReactNode;\n  /** One or two sentences on why. */\n  rationale?: ReactNode;\n  confidence: ConfidenceLevel;\n  /** A small leading visual: an avatar, a logo, an icon. Travels with the title on a swap. */\n  media?: ReactNode;\n  /** Short status shown for this option in the alternatives list, for example \"Needs review\". */\n  note?: ReactNode;\n}\n\nexport interface RecommendationCardProps extends Omit<ComponentProps<\"section\">, \"title\"> {\n  /** The question being answered, for example \"Who should own the Northwind renewal?\". */\n  question?: ReactNode;\n  /** The first option is the recommendation; the rest are alternatives. */\n  options: RecommendationOption[];\n  /** Id of the option in the main slot initially. Defaults to the first. */\n  defaultValue?: string;\n  /** Called when an alternative is swapped into the main slot. */\n  onValueChange?: (id: string) => void;\n  onAccept?: (option: RecommendationOption) => void;\n  /** Adds a Dismiss button. */\n  onDismiss?: () => void;\n  /** Adds an Undo button after accepting. */\n  onUndo?: () => void;\n  acceptLabel?: string;\n  /** Text after accepting. Receives the accepted option. */\n  acceptedLabel?: (option: RecommendationOption) => ReactNode;\n}\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nconst ease = \"ease-[cubic-bezier(0.23,1,0.32,1)]\";\n\nconst levels: Record<ConfidenceLevel, { bars: number; label: string; fill: string; text: string }> = {\n  high: { bars: 3, label: \"High confidence\", fill: \"bg-emerald-500 dark:bg-emerald-400\", text: \"text-emerald-700 dark:text-emerald-400\" },\n  medium: { bars: 2, label: \"Medium confidence\", fill: \"bg-amber-500 dark:bg-amber-400\", text: \"text-amber-700 dark:text-amber-400\" },\n  low: { bars: 1, label: \"Low confidence\", fill: \"bg-zinc-500 dark:bg-zinc-400\", text: \"text-zinc-600 dark:text-zinc-400\" },\n  none: { bars: 0, label: \"No signal\", fill: \"bg-zinc-500\", text: \"text-zinc-500\" },\n};\n\nexport interface ConfidenceMeterProps extends Omit<ComponentProps<\"span\">, \"children\"> {\n  level: ConfidenceLevel;\n  /** Shows \"High confidence\" and so on beside the bars. */\n  showLabel?: boolean;\n  size?: \"sm\" | \"md\";\n}\n\n/**\n * Three short bars of rising height, like a signal meter: three for high, two for medium, one for\n * low, none for no signal. Bars refill one after another when the level changes.\n */\nexport function ConfidenceMeter({ level, showLabel = false, size = \"md\", className, ...props }: ConfidenceMeterProps) {\n  const config = levels[level];\n  const heights = size === \"sm\" ? [\"h-1.5\", \"h-2\", \"h-2.5\"] : [\"h-2\", \"h-2.5\", \"h-3\"];\n  return (\n    <span role=\"img\" aria-label={config.label} className={cx(\"inline-flex items-center gap-2\", className)} {...props}>\n      <span aria-hidden=\"true\" className=\"inline-flex items-end gap-[2px]\">\n        {heights.map((height, i) => (\n          <span\n            key={i}\n            className={cx(\n              \"w-[3px] rounded-full transition-colors duration-300 motion-reduce:transition-none\",\n              ease,\n              height,\n              i < config.bars ? config.fill : \"bg-zinc-950/[0.12] dark:bg-white/[0.14]\",\n            )}\n            // Fill climbs from the short bar to the tall one.\n            style={{ transitionDelay: `${i * 60}ms` }}\n          />\n        ))}\n      </span>\n      {showLabel ? <span className={cx(\"text-xs font-medium transition-colors duration-300 motion-reduce:transition-none\", config.text)}>{config.label}</span> : null}\n    </span>\n  );\n}\n\nconst button = {\n  base: \"inline-flex h-8 items-center justify-center gap-1.5 rounded-lg px-2.5 text-sm font-medium whitespace-nowrap select-none transition-[background-color,border-color,color,scale] duration-150 ease-out motion-safe:active:scale-[0.97] motion-reduce:transition-none focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n  primary: \"bg-zinc-950 text-white shadow-[inset_0_1px_0_rgb(255_255_255/0.12),0_1px_2px_rgb(0_0_0/0.2)] hover:bg-zinc-800 dark:bg-white dark:text-black dark:shadow-[inset_0_-1px_0_rgb(0_0_0/0.12)] dark:hover:bg-zinc-200\",\n  secondary: \"border border-zinc-950/12 bg-white hover:border-zinc-950/20 hover:bg-zinc-950/[0.03] dark:border-white/15 dark:bg-black dark:hover:border-white/25 dark:hover:bg-white/[0.06]\",\n  ghost: \"text-zinc-600 hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:text-zinc-400 dark:hover:bg-white/[0.06] dark:hover:text-white\",\n};\n\n/** One suggested action with its rationale, a confidence meter, Accept, and a drawer of alternatives. */\nexport function RecommendationCard({\n  question,\n  options,\n  defaultValue,\n  onValueChange,\n  onAccept,\n  onDismiss,\n  onUndo,\n  acceptLabel = \"Accept\",\n  acceptedLabel,\n  className,\n  ...props\n}: RecommendationCardProps) {\n  const reduce = useReducedMotion();\n  const uid = useId();\n  const [order, setOrder] = useState<string[]>(() => {\n    const ids = options.map((o) => o.id);\n    const first = defaultValue && ids.includes(defaultValue) ? defaultValue : ids[0];\n    return first ? [first, ...ids.filter((id) => id !== first)] : ids;\n  });\n  const [drawer, setDrawer] = useState(false);\n  const [accepted, setAccepted] = useState(false);\n  const [announcement, setAnnouncement] = useState(\"\");\n  const focusIndex = useRef<number | null>(null);\n  const rowRefs = useRef<(HTMLButtonElement | null)[]>([]);\n  const acceptRef = useRef<HTMLButtonElement>(null);\n\n  const byId = new Map(options.map((o) => [o.id, o]));\n  // Options that arrive later go to the end; options that disappear drop out.\n  const ids = [...order.filter((id) => byId.has(id)), ...options.map((o) => o.id).filter((id) => !order.includes(id))];\n  const main = byId.get(ids[0] ?? \"\");\n  const alternatives = ids.slice(1).map((id) => byId.get(id)!);\n\n  useEffect(() => {\n    if (focusIndex.current == null) return;\n    rowRefs.current[focusIndex.current]?.focus({ preventScroll: true });\n    focusIndex.current = null;\n  }, [order]);\n\n  if (!main) return null;\n\n  function swap(index: number) {\n    const next = [...ids];\n    const chosen = next[index + 1]!;\n    next[index + 1] = next[0]!;\n    next[0] = chosen;\n    // Keep focus where the user was: the row now holds the previous suggestion.\n    focusIndex.current = index;\n    setOrder(next);\n    const option = byId.get(chosen)!;\n    setAnnouncement(`Now suggesting: ${typeof option.title === \"string\" ? option.title : \"the selected option\"}. ${levels[option.confidence].label}.`);\n    onValueChange?.(chosen);\n  }\n\n  const layout = reduce ? { duration: 0 } : { type: \"spring\" as const, duration: 0.45, bounce: 0 };\n  const drawerId = `${uid}-alternatives`;\n  const titleId = `${uid}-title`;\n\n  return (\n    <section\n      aria-labelledby={titleId}\n      data-accepted={accepted || undefined}\n      className={cx(\n        \"w-full overflow-hidden rounded-xl border border-zinc-950/10 bg-white text-left 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      <span role=\"status\" className=\"sr-only\">\n        {announcement}\n      </span>\n      <LayoutGroup id={uid}>\n        <div className=\"px-4 pt-4 pb-3\">\n          {question ? <p className=\"mb-2.5 text-xs font-medium text-zinc-500\">{question}</p> : null}\n          <div className=\"flex items-start gap-3\">\n            {main.media ? (\n              <motion.span layoutId={`${uid}-media-${main.id}`} transition={layout} className=\"mt-0.5 flex size-8 shrink-0 items-center justify-center\">\n                {main.media}\n              </motion.span>\n            ) : null}\n            <div className=\"min-w-0 flex-1\">\n              <motion.h3\n                id={titleId}\n                layoutId={`${uid}-title-${main.id}`}\n                transition={layout}\n                className=\"inline-block text-base leading-6 font-semibold text-balance\"\n              >\n                {main.title}\n              </motion.h3>\n              <AnimatePresence mode=\"popLayout\" initial={false}>\n                {main.rationale ? (\n                  <motion.p\n                    key={main.id}\n                    initial={reduce ? false : { opacity: 0, y: 4, filter: \"blur(2px)\" }}\n                    animate={{ opacity: 1, y: 0, filter: \"blur(0px)\" }}\n                    exit={reduce ? { opacity: 0, transition: { duration: 0 } } : { opacity: 0, transition: { duration: 0.1 } }}\n                    transition={{ duration: 0.28, ease: [0.23, 1, 0.32, 1], delay: reduce ? 0 : 0.22 }}\n                    className=\"mt-1 text-sm leading-relaxed text-pretty text-zinc-600 dark:text-zinc-400\"\n                  >\n                    {main.rationale}\n                  </motion.p>\n                ) : null}\n              </AnimatePresence>\n            </div>\n          </div>\n        </div>\n\n        <div className=\"flex flex-wrap items-center justify-between gap-x-4 gap-y-3 px-4 pb-4\">\n          <ConfidenceMeter level={main.confidence} showLabel />\n          <div className=\"relative flex min-w-0 items-center gap-2\">\n            <div\n              inert={accepted || undefined}\n              className={cx(\"flex flex-wrap items-center justify-end gap-2 transition-[opacity,translate] duration-200 motion-reduce:transition-none\", ease, accepted && \"pointer-events-none translate-y-1 opacity-0\")}\n            >\n              {onDismiss ? (\n                <button type=\"button\" onClick={onDismiss} className={cx(button.base, button.ghost)}>\n                  Dismiss\n                </button>\n              ) : null}\n              {alternatives.length ? (\n                <button\n                  type=\"button\"\n                  aria-expanded={drawer}\n                  aria-controls={drawerId}\n                  onClick={() => setDrawer((open) => !open)}\n                  className={cx(button.base, button.secondary)}\n                >\n                  Alternatives\n                  <span className=\"font-mono text-xs text-zinc-500 tabular-nums\">{alternatives.length}</span>\n                  <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" className={cx(\"size-3.5 text-zinc-500 transition-transform duration-200 motion-reduce:transition-none\", ease, drawer && \"rotate-180\")}>\n                    <path d=\"m4.5 6.25 3.5 3.5 3.5-3.5\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" />\n                  </svg>\n                </button>\n              ) : null}\n              <button\n                ref={acceptRef}\n                type=\"button\"\n                onClick={() => {\n                  setAccepted(true);\n                  setDrawer(false);\n                  setAnnouncement(`Accepted: ${typeof main.title === \"string\" ? main.title : \"the suggestion\"}.`);\n                  onAccept?.(main);\n                }}\n                className={cx(button.base, button.primary)}\n              >\n                {acceptLabel}\n              </button>\n            </div>\n            <div\n              inert={!accepted || undefined}\n              className={cx(\n                \"absolute inset-y-0 right-0 flex items-center gap-3 transition-[opacity,translate] duration-200 motion-reduce:transition-none\",\n                ease,\n                accepted ? \"opacity-100 delay-100\" : \"pointer-events-none translate-y-1 opacity-0\",\n              )}\n            >\n              <span className=\"flex items-center gap-1.5 text-sm whitespace-nowrap text-zinc-600 dark:text-zinc-400\">\n                <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" className=\"size-4 text-emerald-600 dark:text-emerald-400\">\n                  <path d=\"m3.5 8.5 3 3 6-7\" />\n                </svg>\n                {acceptedLabel ? acceptedLabel(main) : \"Accepted\"}\n              </span>\n              {onUndo ? (\n                <button\n                  type=\"button\"\n                  onClick={() => {\n                    setAccepted(false);\n                    setAnnouncement(\"\");\n                    onUndo();\n                    requestAnimationFrame(() => acceptRef.current?.focus({ preventScroll: true }));\n                  }}\n                  className={cx(button.base, button.ghost)}\n                >\n                  Undo\n                </button>\n              ) : null}\n            </div>\n          </div>\n        </div>\n\n        {alternatives.length ? (\n          <div\n            id={drawerId}\n            inert={!drawer || undefined}\n            className={cx(\n              \"grid grid-cols-[minmax(0,1fr)] transition-[grid-template-rows] duration-300 motion-reduce:transition-none\",\n              ease,\n              drawer ? \"grid-rows-[1fr]\" : \"grid-rows-[0fr]\",\n            )}\n          >\n            <div className=\"min-h-0 overflow-hidden\">\n              <div\n                className={cx(\n                  \"border-t border-zinc-950/[0.07] px-2 pt-2.5 pb-2 transition-opacity duration-200 motion-reduce:transition-none dark:border-white/[0.08]\",\n                  drawer ? \"opacity-100 delay-75\" : \"opacity-0\",\n                )}\n              >\n                <p className=\"px-2 pb-1.5 text-xs font-medium text-zinc-500\">Other options</p>\n                <ul className=\"grid grid-cols-[minmax(0,1fr)] gap-0.5\">\n                  {alternatives.map((option, index) => (\n                    <li key={option.id}>\n                      <button\n                        ref={(el) => {\n                          rowRefs.current[index] = el;\n                        }}\n                        type=\"button\"\n                        onClick={() => swap(index)}\n                        className={cx(\n                          \"group/row flex w-full items-center gap-3 rounded-lg px-2 py-2 text-left\",\n                          \"transition-[background-color] duration-150 ease-out hover:bg-zinc-950/[0.04] motion-reduce:transition-none dark:hover:bg-white/[0.06]\",\n                          \"focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-sky-500\",\n                        )}\n                      >\n                        {option.media ? (\n                          <motion.span layoutId={`${uid}-media-${option.id}`} transition={layout} className=\"flex size-6 shrink-0 items-center justify-center\">\n                            {option.media}\n                          </motion.span>\n                        ) : null}\n                        <span className=\"min-w-0 flex-1\">\n                          <motion.span layoutId={`${uid}-title-${option.id}`} transition={layout} className=\"inline-block max-w-full truncate align-top text-sm leading-5 font-medium\">\n                            {option.title}\n                          </motion.span>\n                          {option.rationale ? <span className=\"block truncate text-xs leading-5 text-zinc-500\">{option.rationale}</span> : null}\n                        </span>\n                        <span className=\"flex shrink-0 items-center gap-2.5\">\n                          {option.note ? <span className=\"hidden text-xs text-zinc-500 sm:inline\">{option.note}</span> : null}\n                          <ConfidenceMeter level={option.confidence} size=\"sm\" />\n                          <span className=\"text-xs font-medium text-zinc-500 transition-colors duration-150 group-hover/row:text-zinc-950 motion-reduce:transition-none dark:group-hover/row:text-white\">\n                            Use\n                          </span>\n                        </span>\n                      </button>\n                    </li>\n                  ))}\n                </ul>\n              </div>\n            </div>\n          </div>\n        ) : null}\n      </LayoutGroup>\n    </section>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { RecommendationCard, type RecommendationOption } from \"@/components/shaken/agent/recommendation-card\";\n\nfunction Initials({ children }: { children: string }) {\n  return (\n    <span className=\"flex size-full items-center justify-center rounded-full border border-zinc-950/10 bg-zinc-950/[0.04] text-[11px] font-medium text-zinc-700 dark:border-white/15 dark:bg-white/[0.06] dark:text-zinc-300\">\n      {children}\n    </span>\n  );\n}\n\nconst options: RecommendationOption[] = [\n  {\n    id: \"priya\",\n    title: \"Assign to Priya Raman\",\n    rationale: \"She ran the last two Northwind renewals and closed both a week early. Her pipeline has room this quarter.\",\n    confidence: \"high\",\n    media: <Initials>PR</Initials>,\n  },\n  {\n    id: \"tomas\",\n    title: \"Assign to Tomas Lindqvist\",\n    rationale: \"Owns the Kestrel account in the same region, but is carrying 14 open deals.\",\n    confidence: \"medium\",\n    media: <Initials>TL</Initials>,\n    note: \"Needs review\",\n  },\n  {\n    id: \"queue\",\n    title: \"Leave it in the renewals queue\",\n    rationale: \"Nobody has touched the account in 60 days, so there is little history to go on.\",\n    confidence: \"none\",\n    media: <Initials>Q</Initials>,\n    note: \"No signal\",\n  },\n];\n\nexport default function RecommendationCardExample() {\n  return (\n    <RecommendationCard\n      className=\"max-w-md\"\n      question=\"Who should own the Northwind renewal?\"\n      options={options}\n      onDismiss={() => {}}\n      onUndo={() => {}}\n    />\n  );\n}\n"
  }
}
