X Card

• 📦 Package Overview
• 🗂️ Component Architecture
• 🚀 Quick Start Decision Guide
• 🛠 Recommended Workflow
• 🚨 Development Rules
• 🤝 Skill Collaboration
• 🔗 Reference Resources

📦 Package Overview

npm install @ant-design/x-card

Exports:

import {
  XCard,
  registerCatalog,
  loadCatalog,
  validateComponent,
  clearCatalogCache,
} from '@ant-design/x-card';
import type {
  XAgentCommand_v0_9,
  XAgentCommand_v0_8,
  ActionPayload,
  Catalog,
  CatalogComponent,
} from '@ant-design/x-card';

// Subcomponents
XCard.Box; // Container: receives commands, owns catalog maps
XCard.Card; // Renderer: renders a single surface by id

🗂️ Component Architecture

XCard.Box
├── owns: catalogMap, surfaceCatalogMap
├── dispatches: commands → all XCard.Card children
├── aggregates: onAction events from all Cards
└── XCard.Card (id="surface-a")
│   ├── owns: component tree, data model, commandVersion
│   └── resolves: data bindings, triggers actions
└── XCard.Card (id="surface-b")
    └── ...

XCard.Box Props

interface BoxProps {
  commands?: (XAgentCommand_v0_9 | XAgentCommand_v0_8)[];
  /** Component names must start with an uppercase letter (React component convention) */
  components?: Record<string, React.ComponentType<any>>;
  onAction?: (payload: ActionPayload) => void;
  children?: React.ReactNode; // Should contain XCard.Card elements
}

XCard.Card Props

interface CardProps {
  id: string; // surfaceId to render
}

ActionPayload

interface ActionPayload {
  name: string; // from action.event.name
  surfaceId: string; // which surface triggered it
  /**
   * Complete dataModel snapshot of the surface at the time the action fired.
   * This is the entire data model, not just the fields listed in action.event.context.
   */
  context: Record<string, any>;
}

🚀 Quick Start Decision Guide

🛠 Recommended Workflow

1. Define your catalog — register a local catalog or use the A2UI Basic Catalog URL.
2. Register custom components — pass them via XCard.Box components prop.
3. Create the React tree — wrap surfaces with XCard.Box, add XCard.Card per surface.
4. Feed commands — push XAgentCommand_v0_9[] into commands prop (typically from streaming agent response).
5. Handle actions — receive ActionPayload in onAction, update commands in response.

Minimal Working Example

import React, { useState } from 'react';
import { XCard, registerCatalog } from '@ant-design/x-card';
import type { XAgentCommand_v0_9, ActionPayload, Catalog } from '@ant-design/x-card';

// 1. Define and register local catalog
const myCatalog: Catalog = {
  catalogId: 'local://my_catalog.json',
  components: {
    Text: {
      type: 'object',
      properties: { text: { type: 'string' }, variant: { type: 'string' } },
      required: ['text'],
    },
    Button: {
      type: 'object',
      properties: { text: { type: 'string' }, action: {} },
      required: ['text'],
    },
  },
};
registerCatalog(myCatalog);

// 2. Custom component implementations
const Text: React.FC<{ text: string; variant?: string }> = ({ text, variant }) => (
  <p className={`text-${variant ?? 'body'}`}>{text}</p>
);

const Button: React.FC<{ text: string; onAction?: (ctx: any) => void; action?: any }> = ({
  text,
  onAction,
  action,
}) => <button onClick={() => onAction?.(action?.event?.context ?? {})}>{text}</button>;

// 3. Build commands (from agent stream)
const commands: XAgentCommand_v0_9[] = [
  {
    version: 'v0.9',
    createSurface: {
      surfaceId: 'welcome',
      catalogId: 'local://my_catalog.json',
    },
  },
  {
    version: 'v0.9',
    updateComponents: {
      surfaceId: 'welcome',
      components: [
        { id: 'root', component: 'Column', children: ['title', 'btn'] },
        { id: 'title', component: 'Text', text: { path: '/user/name' }, variant: 'h1' },
        {
          id: 'btn',
          component: 'Button',
          text: 'Start',
          action: { event: { name: 'start', context: {} } },
        },
      ],
    },
  },
  {
    version: 'v0.9',
    updateDataModel: {
      surfaceId: 'welcome',
      path: '/user/name',
      value: 'Alice',
    },
  },
];

// 4. Render
export default function App() {
  const [cmdQueue, setCmdQueue] = useState<XAgentCommand_v0_9[]>(commands);

  const handleAction = (payload: ActionPayload) => {
    console.log('Action:', payload.name, payload.context);
    // Append new commands based on agent response
    setCmdQueue((prev) => [...prev /* new commands */]);
  };

  return (
    <XCard.Box commands={cmdQueue} components={{ Text, Button }} onAction={handleAction}>
      <XCard.Card id="welcome" />
    </XCard.Box>
  );
}

🚨 Development Rules

• Always include "version": "v0.9" on every command — omitting it causes protocol rejection.
• One and only one id: "root" component per surface's component tree — this is the tree root.
• Flat adjacency list only — never nest component objects inside other component objects; always reference children by id string.
• Separate structure from data — updateComponents for layout, updateDataModel for content/state.
• Register catalog before mounting — call registerCatalog() before the component tree renders.
• Pass components map to XCard.Box, not to XCard.Card — Box distributes to all Cards.
• Never recreate the components object inline — keep it stable with useMemo or module-level constant to avoid re-renders.
• Input components require value: { path: "..." } for two-way binding — literal values do not update the data model.
• For streaming: append new commands to the array rather than replacing it — Card processes the diff incrementally.
• action.event.context paths are write targets — they point to where user-entered data lives in the data model; do not resolve them as read sources.

🤝 Skill Collaboration

🔗 Reference Resources

• USAGE.md — Setup guide, streaming pattern, multi-surface examples
• COMMANDS.md — All four A2UI v0.9 command types, v0.8 vs v0.9 diff
• DATA_BINDING.md — JSON Pointer paths, dynamic types, two-way binding, template iteration
• ACTIONS.md — Action definitions, ActionPayload, form submission pattern
• CATALOG.md — Local catalog registration, remote URL loading, custom component schema
• API.md — Full TypeScript types for Box, Card, commands, catalog, actions

Official Documentation

• A2UI What Is It
• A2UI v0.9 Specification
• Concepts: Data Binding
• Concepts: Catalogs
• Guide: Agent Development
• GitHub: google/A2UI