A2UI surface

Preview

Install

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/a2ui-surface

Brings in: button, card-registry, dialog, input, locale, locked, tabs, textarea, use-copy, utils · npm: lucide-react@^1.67.0

Usage

"use client"

import { A2uiSurface, A2UI_BASIC_CATALOG, applyA2uiMessages, emptyA2uiState } from "@/components/a2ui-surface"

// What an agent sends: a surface, its components as a flat list, then its data.
const state = applyA2uiMessages(emptyA2uiState(), [
  { version: "v0.9", createSurface: { surfaceId: "invite", catalogId: A2UI_BASIC_CATALOG } },
  {
    version: "v0.9",
    updateComponents: {
      surfaceId: "invite",
      components: [
        { id: "root", component: "Card", child: "body" },
        { id: "body", component: "Column", children: ["title", "email", "send"] },
        { id: "title", component: "Text", variant: "h3", text: { call: "formatString", args: { value: "Invite someone to ${/team}" } } },
        { id: "email", component: "TextField", label: "Email", value: { path: "/email" } },
        { id: "send-label", component: "Text", text: "Send invite" },
        { id: "send", component: "Button", variant: "primary", child: "send-label", action: { event: { name: "invite", context: { email: { path: "/email" } } } } },
      ],
    },
  },
  { version: "v0.9", updateDataModel: { surfaceId: "invite", value: { team: "Platform", email: "" } } },
])

export default function Example() {
  return <A2uiSurface className="max-w-sm" state={state} surfaceId="invite" onAction={(m) => console.log(m.action.name, m.action.context)} />
}

<A2uiSurface>

Functions

Strings

Types

A2uiComponent

One component in a surface's flat list: an id, a type from the catalog, and that type's properties.

{ id: string; component: string; [prop: string]: unknown }

A2uiSurfaceState

One surface: its components by id and its data model.

{ surfaceId: string catalogId: string theme?: Record<string, unknown> | undefined /** When true, actions from this surface carry the whole data model. */ sendDataModel: boolean components: Record<string, A2uiComponent> dataModel: unknown }

A2uiState

Every surface the agent has made, plus what couldn't be applied and why.

{ surfaces: Record<string, A2uiSurfaceState> /** Messages that were ignored, in plain words, newest last (at most 20). */ problems: string[] }

A2uiActionMessage

What the app receives when a person uses a control with an event action (A2UI's client-to-server `action` message).

{ version: "v0.9" action: { name: string surfaceId: string sourceComponentId: string /** ISO 8601. */ timestamp: string /** The action's context with every binding resolved against the data model. */ context: Record<string, unknown> } }

A2uiActionHandler

(message: A2uiActionMessage, extra: { dataModel?: unknown }) => void

A2uiStore

A small store around the processor, for apps that stream messages in and for inputs that write back.

{ getState: () => A2uiState /** Applies one message or a list of them. */ apply: (message: unknown) => void setData: (surfaceId: string, path: string, value: unknown) => void subscribe: (listener: () => void) => () => void }

A2uiScope

Where a binding is read: the data model and the base path relative paths hang off (a template item, or "/").

{ dataModel: unknown; base: string }

A2uiCardProps

A2UI messages carried in a reply card: `{card: "a2ui", props: {messages: [...]}}`.

{ messages: unknown[]; surfaceId?: string | undefined }