{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "composed-surface",
  "title": "ComposedSurface",
  "description": "Draws Ouro's composed tree with Ouro HX, whatever format it came in: core's `ComposedNode`, from A2UI messages, an MCP tool result's `structuredContent.ouro`, or your own code.",
  "registryDependencies": [
    "@ouro/alert",
    "@ouro/aspect-ratio",
    "@ouro/badge",
    "@ouro/button",
    "@ouro/card",
    "@ouro/confirm-dialog",
    "@ouro/description-list",
    "@ouro/heading",
    "@ouro/lib-a2ui-core",
    "@ouro/lib-cn",
    "@ouro/lib-env",
    "@ouro/lib-use-dev-messages",
    "@ouro/row",
    "@ouro/separator",
    "@ouro/stack",
    "@ouro/text"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/composed-surface/composed-surface-styles.ts",
      "content": "import type { LayoutGap } from \"@/registry/ouro/components/ouro/stack/stack-styles\";\n\n/** The catalog's Stack gaps, on HX's spacing scale. */\nexport const GAPS: Record<string, LayoutGap> = { none: \"none\", small: \"sm\", medium: \"md\", large: \"lg\" };\n\n/** The catalog's Badge tones, as HX's theme tokens. `neutral` is left out: it is Badge's own default. */\nexport const BADGE_TONES: Record<string, \"primary\" | \"success\" | \"warning\" | \"destructive\"> = { info: \"primary\", success: \"success\", warning: \"warning\", danger: \"destructive\" };\n\n/** The catalog's Alert tones, as HX's theme tokens. */\nexport const ALERT_TONES: Record<string, \"primary\" | \"success\" | \"warning\" | \"destructive\"> = { info: \"primary\", success: \"success\", warning: \"warning\", danger: \"destructive\" };\n\n/** The catalog's Image aspects, as ratios. */\nexport const ASPECTS: Record<string, number> = { landscape: 4 / 3, square: 1, portrait: 3 / 4, wide: 16 / 9 };\n\n/** A List's items: the theme's text, a marker inside the column, and HX's small gap between items. */\nexport const LIST_CLASS = \"m-0 grid gap-1 ps-5 text-base text-foreground marker:text-muted-foreground\";\n\n/** A value the agent prepared, on its own line in a consequential action's confirmation. */\nexport const FIELD_CLASS = \"mt-1 block\";\n\n/** The field's label before its value. */\nexport const FIELD_LABEL_CLASS = \"font-medium text-foreground\";\n\n/** The id a name stands in for, small and muted beside the name. */\nexport const RAW_CLASS = \"text-xs text-[color-mix(in_oklab,var(--muted-foreground)_80%,var(--foreground))]\";\n",
      "type": "registry:ui",
      "target": "@components/ouro/composed-surface/composed-surface-styles.ts"
    },
    {
      "path": "registry/ouro/components/ouro/composed-surface/composed-surface.tsx",
      "content": "\"use client\";\n\nimport { type JSX, type ReactNode, type SVGProps, useState } from \"react\";\nimport { AspectRatio } from \"@/registry/ouro/components/ouro/aspect-ratio/aspect-ratio\";\nimport { Alert } from \"@/registry/ouro/components/ouro/alert/alert\";\nimport { Badge } from \"@/registry/ouro/components/ouro/badge/badge\";\nimport { Button } from \"@/registry/ouro/components/ouro/button/button\";\nimport { Card } from \"@/registry/ouro/components/ouro/card/card\";\nimport { DescriptionList } from \"@/registry/ouro/components/ouro/description-list/description-list\";\nimport { ConfirmDialog } from \"@/registry/ouro/components/ouro/dialog/confirm-dialog\";\nimport { Separator } from \"@/registry/ouro/components/ouro/separator/separator\";\nimport { Row } from \"@/registry/ouro/components/ouro/stack/row\";\nimport { Stack } from \"@/registry/ouro/components/ouro/stack/stack\";\nimport { Heading } from \"@/registry/ouro/components/ouro/text/heading\";\nimport { Text } from \"@/registry/ouro/components/ouro/text/text\";\nimport { personPress, type ComposedNode, type PersonPress } from \"@/registry/ouro/lib/ouro/a2ui-core\";\nimport { cn } from \"@/registry/ouro/lib/ouro/cn\";\nimport { useDevWarnings } from \"@/registry/ouro/lib/ouro/use-dev-messages\";\nimport { ALERT_TONES, ASPECTS, BADGE_TONES, FIELD_CLASS, FIELD_LABEL_CLASS, GAPS, LIST_CLASS, RAW_CLASS } from \"@/registry/ouro/components/ouro/composed-surface/composed-surface-styles\";\n\n/** Where a person-only button takes the person: the action's id and the catalog's `how`. */\nexport interface ComposedHandoff {\n  action: string;\n  how: string;\n}\n\n/** Props for {@link ComposedSurface}. */\nexport interface ComposedSurfaceProps {\n  /**\n   * The composed tree to draw: core's `ComposedNode`, its values resolved. Check one you didn't resolve yourself\n   * with core's `validateTree` against the app's catalog first; A2UI's resolver already has.\n   */\n  tree: ComposedNode;\n  /**\n   * Runs a pressed read or write button, and a consequential one once the person confirms. `press` is core's\n   * `PersonPress` (the action, the prepared input, its consent, and that the person pressed it); `button` is the node,\n   * for a format that names its source. Return a promise to show the button loading until it settles.\n   */\n  onPress: (press: PersonPress, button: ComposedNode) => void | Promise<void>;\n  /**\n   * A person-only button never runs from composed UI: take the person to your app's own screen for it.\n   *\n   * @claim \"A person-only button never runs\" registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > hands a person-only action to the app's own screen and never presses it)\n   */\n  onHandoff: (handoff: ComposedHandoff) => void;\n  /** Layout only: margins, width (`max-w-md`). */\n  className?: string | undefined;\n\n  /** Not a prop. A pressed button calls `onPress`, or `onHandoff` for a person-only one: `<ComposedSurface onPress={run} onHandoff={openApp}>`. */\n  onAction?: { \"Use onPress={run} onHandoff={openApp}\": never };\n}\n\ninterface Context {\n  onPress: ComposedSurfaceProps[\"onPress\"];\n  onHandoff: ComposedSurfaceProps[\"onHandoff\"];\n}\n\n/** A resolved prop the resolver gives as text (core's `asText`), typed as one. */\nconst text = (v: unknown): string => v as string;\n\n/**\n * Draws Ouro's composed tree with Ouro HX, whatever format it came in: core's `ComposedNode`, from A2UI messages, an\n * MCP tool result's `structuredContent.ouro`, or your own code. Every button is one of your app's declared actions:\n * read and write run, a consequential one asks the person to confirm what the agent prepared, and a person-only one\n * takes them to your app's own screen.\n *\n * Use A2UISurface instead for A2UI messages, and HX's components directly when your own code, not an agent, decides\n * the layout.\n *\n * @claim \"Every button is one\" registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > presses a write button with the prepared input, pressed by the person)\n * @claim \"Every button is one\" registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > asks the person to confirm a consequential action with what the agent prepared, and presses it only on confirm)\n * @claim \"Every button is one\" registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx verify:testExists(registry/ouro/components/ouro/composed-surface/composed-surface.test.tsx::ComposedSurface > hands a person-only action to the app's own screen and never presses it)\n *\n * @group Display\n * @see https://ui.ouroboros.bot/docs/composed-surface\n *\n * @example\n * <ComposedSurface\n *   tree={result.structuredContent.ouro.tree}\n *   onPress={(press) => callTool(press.action, press.input)}\n *   onHandoff={({ action }) => navigate(`/recipes/${id}?do=${action}`)}\n * />\n */\nexport function ComposedSurface(props: ComposedSurfaceProps): JSX.Element {\n  const { tree, onPress, onHandoff, className, onAction } = props;\n  useDevWarnings(\n    \"ComposedSurface\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [onAction !== undefined && [\"onAction is not a prop; a pressed button calls onPress, or onHandoff for a person-only one\", \"<ComposedSurface onPress={run} onHandoff={openApp} />\"]]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n  return (\n    <div data-ouro=\"composed-surface\" className={cn(\"min-w-0\", className)}>\n      <ComposedTree tree={tree} onPress={onPress} onHandoff={onHandoff} />\n    </div>\n  );\n}\n\n/**\n * The tree's components, drawn straight into the parent: the body of ComposedSurface and of A2UISurface.\n *\n * @internal\n */\nexport function ComposedTree({ tree, onPress, onHandoff }: Pick<ComposedSurfaceProps, \"tree\" | \"onPress\" | \"onHandoff\">): ReactNode {\n  // Stryker disable next-line StringLiteral: the root's key only prefixes its descendants' keys, which are unique under any prefix.\n  return renderNode(tree, { onPress, onHandoff }, \"root\");\n}\n\nfunction renderNode(node: ComposedNode, ctx: Context, key: string): ReactNode {\n  const p = node.props;\n  const kids = () => node.children.map((child, i) => renderNode(child, ctx, `${key}.${i}`));\n  switch (node.component) {\n    case \"Card\": {\n      const [first, ...rest] = node.children;\n      const media = first?.component === \"Image\" ? first : undefined;\n      return (\n        // Stryker disable next-line StringLiteral: the media slot holds one element, so its key matches no sibling's.\n        <Card key={key} media={media ? image(media, \"media\") : undefined}>\n          <Stack gap=\"md\">{(media ? rest : node.children).map((child, i) => renderNode(child, ctx, `${key}.${i}`))}</Stack>\n        </Card>\n      );\n    }\n    case \"Stack\":\n      return p.direction === \"horizontal\" ? (\n        <Row key={key} wrap gap={GAPS[text(p.gap)]}>\n          {kids()}\n        </Row>\n      ) : (\n        <Stack key={key} gap={GAPS[text(p.gap)]}>\n          {kids()}\n        </Stack>\n      );\n    case \"Heading\":\n      return (\n        <Heading key={key} level={p.level as 1 | 2 | 3}>\n          {text(p.text)}\n        </Heading>\n      );\n    case \"Text\":\n      return (\n        <Text key={key} tone={p.tone === \"muted\" ? \"muted\" : \"default\"}>\n          {text(p.text)}\n        </Text>\n      );\n    case \"Image\":\n      return image(node, key);\n    case \"Badge\":\n      return (\n        <Badge key={key} tone={BADGE_TONES[text(p.tone)]}>\n          {text(p.text)}\n        </Badge>\n      );\n    case \"List\": {\n      const items = (p.items as string[]).map((item, i) => <li key={i}>{item}</li>);\n      return p.ordered === true ? (\n        <ol key={key} className={cn(LIST_CLASS, \"list-decimal\")}>\n          {items}\n        </ol>\n      ) : (\n        <ul key={key} className={cn(LIST_CLASS, \"list-disc\")}>\n          {items}\n        </ul>\n      );\n    }\n    case \"DescriptionList\":\n      return <DescriptionList key={key} items={(p.items as { term: string; detail: string }[]).map((item) => ({ term: item.term, details: item.detail }))} />;\n    case \"Separator\":\n      return <Separator key={key} />;\n    case \"Alert\":\n      return <Alert key={key} tone={ALERT_TONES[text(p.tone)]} title={text(p.title)} description={p.text as string | undefined} />;\n    default:\n      return <ActionButton key={key} node={node} ctx={ctx} />;\n  }\n}\n\nfunction image(node: ComposedNode, key: string): JSX.Element {\n  return (\n    <AspectRatio key={key} ratio={ASPECTS[text(node.props.aspect)]!}>\n      <img src={text(node.props.url)} alt={text(node.props.description)} />\n    </AspectRatio>\n  );\n}\n\n/** An arrow out to the app's own screen, on a person-only action's button. */\nfunction HandoffIcon(props: SVGProps<SVGSVGElement>): JSX.Element {\n  return (\n    <svg viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" strokeWidth={2} strokeLinecap=\"round\" strokeLinejoin=\"round\" aria-hidden=\"true\" {...props}>\n      <path d=\"M7 17 17 7M8 7h9v9\" />\n    </svg>\n  );\n}\n\n/** How a button other than the agent's primary action looks: soft, in the secondary tone. */\nconst SECONDARY = { tone: \"secondary\", variant: \"soft\" } as const;\n\nfunction ActionButton({ node, ctx }: { node: ComposedNode; ctx: Context }): JSX.Element {\n  const p = node.props as { label: string; press: \"run\" | \"confirm\" | \"handoff\"; action: string; emphasis?: string; handoff?: string; confirm?: { description: string; fields: { label: string; value: string; raw?: string }[] } };\n  const [pending, setPending] = useState(false);\n  const [open, setOpen] = useState(false);\n  const primary = p.emphasis === \"primary\";\n  const send = (confirmed?: true) => ctx.onPress(personPress(node, confirmed), node);\n  const button = (onClick: () => void, end?: typeof HandoffIcon) => (\n    // A primary button is Button's default, solid in the primary tone.\n    <Button {...(primary ? {} : SECONDARY)} loading={pending} endIcon={end} onClick={onClick} data-action={p.action}>\n      {p.label}\n    </Button>\n  );\n  if (p.press === \"handoff\") return button(() => ctx.onHandoff({ action: p.action, how: p.handoff! }), HandoffIcon);\n  if (p.press === \"confirm\")\n    return (\n      <>\n        {button(() => setOpen(true))}\n        <ConfirmDialog\n          open={open}\n          onOpenChange={setOpen}\n          title={`${p.label}?`}\n          description={\n            // The confirmation's description is a <p>, so each prepared value is a line of its own inside it.\n            <>\n              {p.confirm!.description}\n              {p.confirm!.fields.map((f) => (\n                <span key={f.label} className={FIELD_CLASS}>\n                  <span className={FIELD_LABEL_CLASS}>{f.label}:</span> {f.value}\n                  {f.raw !== undefined && (\n                    <>\n                      {\" \"}\n                      <span className={RAW_CLASS}>{f.raw}</span>\n                    </>\n                  )}\n                </span>\n              ))}\n            </>\n          }\n          confirmLabel={p.label}\n          onConfirm={() => send(true)}\n        />\n      </>\n    );\n  return button(() => {\n    const done = send();\n    if (done) {\n      setPending(true);\n      void Promise.resolve(done).finally(() => setPending(false));\n    }\n  });\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/composed-surface/composed-surface.tsx"
    }
  ],
  "docs": "Draws Ouro's composed tree with Ouro HX, whatever format it came in: core's `ComposedNode`, from A2UI messages, an MCP tool result's `structuredContent.ouro`, or your own code. Import: import { ComposedSurface } from \"@/components/ouro/composed-surface/composed-surface\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: alert, aspect-ratio, badge, button, card, confirm-dialog, description-list, dialog, heading, row, separator, sheet, stack, text, the helpers they import in lib/ouro. Needs ouro-base in your stylesheet: add that item once per app, from the same place as this one, if you have not. Docs: https://ui.ouroboros.bot/docs/composed-surface.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}