@easyops-cn/a2ui-react 0.0.0

package/specs/001-a2ui-renderer/plan.md

@@ -0,0 +1,123 @@
+# Implementation Plan: A2UIRenderer Component Library
+
+**Branch**: `001-a2ui-renderer` | **Date**: 2026-01-10 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/001-a2ui-renderer/spec.md`
+
+## Summary
+
+Implement the A2UIRender component and public API exports for the A2UI React renderer library. The library already has substantial infrastructure implemented (contexts, hooks, component registry, default components). The remaining work focuses on:
+
+1. Creating the main `A2UIRender` component that matches the README.md API
+2. Setting up the versioned export path (`@easyops-cn/a2ui-react/0.8`)
+3. Adding development-mode placeholder for unknown components
+4. Ensuring all public types and hooks are properly exported
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.9, React 19
+**Primary Dependencies**: React 19, Radix UI (for UI primitives), Tailwind CSS (via class-variance-authority)
+**Storage**: N/A (client-side rendering library)
+**Testing**: Vitest with @testing-library/react
+**Target Platform**: Browser (ES2020+)
+**Project Type**: Single library project
+**Performance Goals**: <100ms action callback latency, 10+ levels nested rendering
+**Constraints**: Must work with React 18+ (peer dependency allows ^19.0.0)
+**Scale/Scope**: ~20 component types, single entry point
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
+
+The constitution template is not yet customized for this project. Proceeding with standard library development practices:
+
+- [x] Library-first: Self-contained, independently testable
+- [x] Test coverage: Vitest tests exist for contexts, hooks, and components
+- [x] Type safety: Full TypeScript with strict mode
+- [x] Documentation: JSDoc comments on all public APIs
+
+## Existing Implementation Analysis
+
+### Already Implemented
+
+| Component/Module        | Status      | Location                                                           |
+| ----------------------- | ----------- | ------------------------------------------------------------------ |
+| **Contexts**            | ✅ Complete | `src/0.8/contexts/`                                                |
+| - A2UIProvider          | ✅          | Combines Surface, DataModel, Action providers                      |
+| - SurfaceContext        | ✅          | Surface state management                                           |
+| - DataModelContext      | ✅          | Data model state management                                        |
+| - ActionContext         | ✅          | Action dispatching                                                 |
+| **Hooks**               | ✅ Complete | `src/0.8/hooks/`                                                   |
+| - useDataBinding        | ✅          | Read-only data binding                                             |
+| - useFormBinding        | ✅          | Two-way form binding                                               |
+| - useDispatchAction     | ✅          | Action dispatching                                                 |
+| - useComponent          | ✅          | Component lookup                                                   |
+| - useSurface            | ✅          | Surface lookup                                                     |
+| - useA2UIMessageHandler | ✅          | Message processing                                                 |
+| **Components**          | ✅ Complete | `src/0.8/components/`                                              |
+| - ComponentRenderer     | ✅          | Component routing with registry                                    |
+| - Display (6 types)     | ✅          | Text, Image, Icon, Video, AudioPlayer, Divider                     |
+| - Layout (6 types)      | ✅          | Row, Column, List, Card, Tabs, Modal                               |
+| - Interactive (6 types) | ✅          | Button, CheckBox, TextField, DateTimeInput, MultipleChoice, Slider |
+| **Types**               | ✅ Complete | `src/0.8/types/index.ts`                                           |
+| **Utilities**           | ✅ Complete | `src/0.8/utils/`                                                   |
+
+### Not Yet Implemented
+
+| Component/Module          | Status     | Required For                                |
+| ------------------------- | ---------- | ------------------------------------------- |
+| **A2UIRender**            | ❌ Missing | Main entry component per README.md          |
+| **index.ts exports**      | ❌ Missing | Versioned path `@easyops-cn/a2ui-react/0.8` |
+| **Dev-mode placeholder**  | ❌ Missing | Unknown component handling per spec         |
+| **ComponentsMap support** | ❌ Missing | Custom component override per README.md     |
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/001-a2ui-renderer/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output (N/A - no API contracts)
+└── tasks.md             # Phase 2 output
+```
+
+### Source Code (repository root)
+
+```text
+src/
+├── index.ts                    # Root export (existing)
+└── 0.8/
+    ├── index.ts                 # NEW: Versioned public API exports
+    ├── A2UIRender.tsx          # NEW: Main render component
+    ├── A2UIRender.test.tsx     # NEW: Tests for A2UIRender
+    ├── contexts/               # Existing: Context providers
+    │   ├── A2UIProvider.tsx
+    │   ├── ActionContext.tsx
+    │   ├── DataModelContext.tsx
+    │   └── SurfaceContext.tsx
+    ├── hooks/                  # Existing: React hooks
+    │   ├── useDataBinding.ts
+    │   ├── useDispatchAction.ts
+    │   ├── useComponent.ts
+    │   ├── useSurface.ts
+    │   └── useA2UIMessageHandler.ts
+    ├── components/             # Existing: Component implementations
+    │   ├── ComponentRenderer.tsx
+    │   ├── display/
+    │   ├── layout/
+    │   └── interactive/
+    ├── types/                  # Existing: Type definitions
+    │   └── index.ts
+    └── utils/                  # Existing: Utility functions
+        ├── dataBinding.ts
+        └── pathUtils.ts
+```
+
+**Structure Decision**: Single library project structure. The existing codebase follows a well-organized module structure under `src/0.8/`. New files will be added at the same level.
+
+## Complexity Tracking
+
+No constitution violations. The implementation follows the existing patterns and adds minimal new code.

package/specs/001-a2ui-renderer/quickstart.md

@@ -0,0 +1,141 @@
+# Quickstart: A2UIRenderer Component Library
+
+**Date**: 2026-01-10
+**Feature**: 001-a2ui-renderer
+
+## Installation
+
+```bash
+npm install @easyops-cn/a2ui-react
+# or
+pnpm add @easyops-cn/a2ui-react
+```
+
+## Basic Usage
+
+```tsx
+import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+
+function App() {
+  const messages: A2UIMessage[] = [
+    // Messages from your A2UI server
+  ]
+
+  const handleAction = (action: A2UIAction) => {
+    console.log('Action received:', action)
+    // Handle the action (e.g., send to server)
+  }
+
+  return <A2UIRender messages={messages} onAction={handleAction} />
+}
+```
+
+## Custom Components
+
+Override default components or add new ones:
+
+```tsx
+import {
+  A2UIRender,
+  useDispatchAction,
+  ComponentRenderer,
+} from '@easyops-cn/a2ui-react/0.8'
+
+// Custom Button component
+function CustomButton({ surfaceId, componentId, child, action }) {
+  const dispatchAction = useDispatchAction()
+
+  const handleClick = () => {
+    if (action) {
+      dispatchAction(surfaceId, componentId, action)
+    }
+  }
+
+  return (
+    <button className="my-custom-button" onClick={handleClick}>
+      <ComponentRenderer surfaceId={surfaceId} componentId={child} />
+    </button>
+  )
+}
+
+// Register custom components
+const ComponentsMap = new Map([['Button', CustomButton]])
+
+function App() {
+  return (
+    <A2UIRender
+      components={ComponentsMap}
+      messages={messages}
+      onAction={handleAction}
+    />
+  )
+}
+```
+
+## Data Binding in Custom Components
+
+```tsx
+import { useDataBinding, useFormBinding } from '@easyops-cn/a2ui-react/0.8'
+
+// Read-only binding
+function DisplayComponent({ surfaceId, text }) {
+  const textValue = useDataBinding<string>(surfaceId, text, '')
+  return <span>{textValue}</span>
+}
+
+// Two-way binding for forms
+function InputComponent({ surfaceId, value }) {
+  const [inputValue, setInputValue] = useFormBinding<string>(
+    surfaceId,
+    value,
+    ''
+  )
+
+  return (
+    <input value={inputValue} onChange={(e) => setInputValue(e.target.value)} />
+  )
+}
+```
+
+## API Reference
+
+### A2UIRender Props
+
+| Prop         | Type                           | Required | Description                           |
+| ------------ | ------------------------------ | -------- | ------------------------------------- |
+| `messages`   | `A2UIMessage[]`                | Yes      | Array of A2UI messages to render      |
+| `onAction`   | `(action: A2UIAction) => void` | No       | Callback when user triggers an action |
+| `components` | `Map<string, ComponentType>`   | No       | Custom component overrides            |
+
+### Hooks
+
+| Hook                | Signature                                                 | Description                             |
+| ------------------- | --------------------------------------------------------- | --------------------------------------- |
+| `useDispatchAction` | `() => (surfaceId, componentId, action) => void`          | Dispatch actions from custom components |
+| `useDataBinding`    | `<T>(surfaceId, source, default?) => T`                   | Read data from the data model           |
+| `useFormBinding`    | `<T>(surfaceId, source, default?) => [T, (v: T) => void]` | Two-way data binding                    |
+
+### Types
+
+| Type          | Description                                |
+| ------------- | ------------------------------------------ |
+| `A2UIMessage` | Server-to-client message                   |
+| `A2UIAction`  | Action payload sent to onAction callback   |
+| `Action`      | Action definition in component props       |
+| `ValueSource` | Literal value or data model path reference |
+
+## Message Flow
+
+```
+Server                          Client (A2UIRender)
+  │                                    │
+  │──── beginRendering ───────────────►│ Initialize surface
+  │                                    │
+  │──── surfaceUpdate ────────────────►│ Add/update components
+  │                                    │
+  │──── dataModelUpdate ──────────────►│ Update data model
+  │                                    │
+  │◄─── ActionPayload ────────────────│ User interaction
+  │                                    │
+  │──── deleteSurface ────────────────►│ Remove surface
+```

package/specs/001-a2ui-renderer/research.md

@@ -0,0 +1,140 @@
+# Research: A2UIRenderer Component Library
+
+**Date**: 2026-01-10
+**Feature**: 001-a2ui-renderer
+
+## Overview
+
+This document captures research findings for implementing the A2UIRender component and public API exports.
+
+## Decision 1: A2UIRender Component Architecture
+
+**Decision**: Compose A2UIRender as a thin wrapper around existing infrastructure
+
+**Rationale**:
+
+- The existing `A2UIProvider` already combines all necessary context providers
+- The existing `useA2UIMessageHandler` hook handles message processing
+- The existing `ComponentRenderer` handles component routing
+- A2UIRender only needs to:
+  1. Accept `messages`, `onAction`, and optional `components` props
+  2. Wrap children in A2UIProvider
+  3. Process messages and render surfaces
+
+**Alternatives considered**:
+
+- Rewrite from scratch: Rejected - would duplicate existing tested code
+- Extend A2UIProvider: Rejected - A2UIProvider is a context provider, not a renderer
+
+## Decision 2: ComponentsMap Implementation
+
+**Decision**: Use React Context to pass custom components to ComponentRenderer
+
+**Rationale**:
+
+- The README.md shows `components` prop as `Map<string, React.ComponentType<any>>`
+- ComponentRenderer already has a `componentRegistry` object
+- Need to merge custom components with defaults at render time
+- Context allows deep component tree access without prop drilling
+
+**Alternatives considered**:
+
+- Global registry mutation: Rejected - not React-friendly, causes side effects
+- Prop drilling: Rejected - would require changes to all container components
+- Module-level configuration: Rejected - not compatible with multiple A2UIRender instances
+
+## Decision 3: Unknown Component Handling
+
+**Decision**: Use `process.env.NODE_ENV` to switch between dev placeholder and production skip
+
+**Rationale**:
+
+- Spec requires: "Render placeholder in development, skip in production"
+- Standard React pattern for dev-only features
+- Vite/bundlers automatically replace `process.env.NODE_ENV`
+- No runtime overhead in production builds
+
+**Alternatives considered**:
+
+- Runtime configuration prop: Rejected - adds API complexity
+- Always show placeholder: Rejected - spec requires production skip
+- Always skip: Rejected - spec requires dev visibility
+
+## Decision 4: Export Structure for Versioned Path
+
+**Decision**: Create `src/0.8/index.ts` as the entry point for `@easyops-cn/a2ui-react/0.8`
+
+**Rationale**:
+
+- package.json already defines: `"./0.8": { "default": "./dist/src/0.8/index.js" }`
+- Single file makes it clear what's public API
+- Re-exports from internal modules maintain encapsulation
+- Matches README.md import pattern
+
+**Alternatives considered**:
+
+- index.ts in 0.8 folder: Rejected - index.ts is already configured in package.json
+- Barrel exports from each module: Rejected - harder to control public surface
+
+## Decision 5: Surface Rendering Strategy
+
+**Decision**: Render all surfaces from the surfaces Map, each with its root component
+
+**Rationale**:
+
+- Messages can create multiple surfaces
+- Each surface has its own `root` component ID
+- SurfaceContext already maintains `Map<string, Surface>`
+- A2UIRender should render all active surfaces
+
+**Alternatives considered**:
+
+- Single surface only: Rejected - A2UI protocol supports multiple surfaces
+- Surface selection prop: Could be added later if needed
+
+## Technical Findings
+
+### Existing Hook Signatures (from codebase)
+
+```typescript
+// useDataBinding - matches spec FR-012
+function useDataBinding<T>(
+  surfaceId: string,
+  source: ValueSource | undefined,
+  defaultValue?: T
+): T
+
+// useFormBinding - matches spec FR-013
+function useFormBinding<T>(
+  surfaceId: string,
+  source: ValueSource | undefined,
+  defaultValue?: T
+): [T, (value: T) => void]
+
+// useDispatchAction - matches spec FR-011
+function useDispatchAction(): (
+  surfaceId: string,
+  componentId: string,
+  action: Action
+) => void
+```
+
+### Type Exports Required (from spec)
+
+- `A2UIMessage` - ✅ exists in types/index.ts
+- `A2UIAction` - ❌ needs alias (currently `ActionPayload`)
+- `A2UIRender` - ❌ needs implementation
+- `ComponentRenderer` - ✅ exists
+- `useDispatchAction` - ✅ exists
+- `useDataBinding` - ✅ exists
+- `useFormBinding` - ✅ exists
+
+### API Alignment with README.md
+
+The README.md shows:
+
+```tsx
+import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+```
+
+Current types use `ActionPayload` instead of `A2UIAction`. The index.ts should export `ActionPayload as A2UIAction` for API consistency.

package/specs/001-a2ui-renderer/spec.md

@@ -0,0 +1,165 @@
+# Feature Specification: A2UIRenderer Component Library
+
+**Feature Branch**: `001-a2ui-renderer`
+**Created**: 2026-01-10
+**Status**: Draft
+**Input**: User description: "按 README.md 的下游用户使用示例实现 A2UIRenderer"
+
+## Clarifications
+
+### Session 2026-01-10
+
+- Q: How should unknown component types be handled? → A: Render placeholder in development, skip in production
+- Q: Where does the A2UIMessage schema come from? → A: Define schema internally (this library owns the type definitions)
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - Basic Message Rendering (Priority: P1)
+
+As a developer, I want to render A2UI messages using the A2UIRender component so that I can display dynamic UI content from A2UI protocol messages.
+
+**Why this priority**: This is the core functionality - without basic rendering, no other features can work. It enables the fundamental use case of displaying A2UI messages.
+
+**Independent Test**: Can be fully tested by passing an array of A2UIMessage objects to A2UIRender and verifying the UI renders correctly. Delivers immediate value by enabling basic A2UI integration.
+
+**Acceptance Scenarios**:
+
+1. **Given** an empty messages array, **When** A2UIRender is rendered, **Then** no UI components are displayed
+2. **Given** a messages array with valid A2UIMessage objects, **When** A2UIRender is rendered, **Then** all message components are displayed in order
+3. **Given** a messages array with nested components, **When** A2UIRender is rendered, **Then** nested components are rendered correctly within their parent containers
+
+---
+
+### User Story 2 - Action Handling (Priority: P1)
+
+As a developer, I want to receive action callbacks when users interact with components so that I can respond to user interactions and update application state.
+
+**Why this priority**: Actions are essential for interactive UIs. Without action handling, the rendered UI would be static and non-functional.
+
+**Independent Test**: Can be fully tested by clicking interactive components and verifying the onAction callback receives the correct A2UIAction payload.
+
+**Acceptance Scenarios**:
+
+1. **Given** a component with an action defined, **When** the user triggers the action (e.g., clicks a button), **Then** the onAction callback is invoked with the correct A2UIAction object
+2. **Given** the onAction callback, **When** an action is dispatched, **Then** the callback receives surfaceId, componentId, and action payload
+3. **Given** multiple interactive components, **When** different components are clicked, **Then** each dispatches its own unique action correctly
+
+---
+
+### User Story 3 - Custom Component Override (Priority: P2)
+
+As a developer, I want to override default components with custom implementations so that I can customize the look and behavior of rendered UI elements.
+
+**Why this priority**: Customization is important for branding and specific UX requirements, but the library should work with defaults first.
+
+**Independent Test**: Can be fully tested by providing a ComponentsMap with a custom Button component and verifying the custom component renders instead of the default.
+
+**Acceptance Scenarios**:
+
+1. **Given** a ComponentsMap with a custom Button component, **When** A2UIRender renders a Button, **Then** the custom Button component is used instead of the default
+2. **Given** a ComponentsMap with multiple custom components, **When** A2UIRender renders those component types, **Then** each custom component is used appropriately
+3. **Given** a ComponentsMap that does not override a component type, **When** A2UIRender renders that component type, **Then** the default component is used
+
+---
+
+### User Story 4 - Custom Component Creation (Priority: P2)
+
+As a developer, I want to add new custom component types that don't exist in the default set so that I can extend the UI capabilities beyond the built-in components.
+
+**Why this priority**: Extensibility allows the library to support domain-specific components, but basic functionality must work first.
+
+**Independent Test**: Can be fully tested by adding a new component type (e.g., Switch) to ComponentsMap and verifying it renders when that component type appears in messages.
+
+**Acceptance Scenarios**:
+
+1. **Given** a ComponentsMap with a new component type "Switch", **When** A2UIRender encounters a Switch component in messages, **Then** the custom Switch component is rendered
+2. **Given** a custom component using useDispatchAction hook, **When** the component dispatches an action, **Then** the action flows through the onAction callback correctly
+
+---
+
+### User Story 5 - Data Binding in Custom Components (Priority: P3)
+
+As a developer, I want to use data binding hooks in custom components so that I can read dynamic values from the A2UI data context.
+
+**Why this priority**: Data binding enables dynamic content, but basic rendering and actions are more fundamental.
+
+**Independent Test**: Can be fully tested by creating a custom component that uses useDataBinding and verifying it displays the bound value.
+
+**Acceptance Scenarios**:
+
+1. **Given** a custom component using useDataBinding hook, **When** the component renders, **Then** it displays the bound data value
+2. **Given** a data binding with a default value, **When** the bound path has no data, **Then** the default value is used
+
+---
+
+### User Story 6 - Form Binding in Custom Components (Priority: P3)
+
+As a developer, I want to use form binding hooks in custom components so that I can create two-way data binding for form inputs.
+
+**Why this priority**: Form binding enables interactive forms, building on top of basic data binding.
+
+**Independent Test**: Can be fully tested by creating a custom Switch component that uses useFormBinding and verifying value changes are reflected.
+
+**Acceptance Scenarios**:
+
+1. **Given** a custom component using useFormBinding hook, **When** the component renders, **Then** it displays the current bound value
+2. **Given** a custom component using useFormBinding hook, **When** the user changes the value, **Then** the bound value is updated
+3. **Given** a form binding with a default value, **When** the bound path has no data, **Then** the default value is used
+
+---
+
+### Edge Cases
+
+- What happens when messages array is null or undefined? System should handle gracefully without crashing
+- What happens when a component type in messages has no matching renderer? System renders a visible placeholder in development mode to aid debugging, and silently skips the component in production mode
+- What happens when an action is dispatched but no onAction callback is provided? System should handle gracefully
+- What happens when useDataBinding references a non-existent path? System should return the default value
+- What happens when ComponentsMap contains invalid component references? System should fall back to defaults or skip
+
+## Requirements _(mandatory)_
+
+### Functional Requirements
+
+- **FR-001**: System MUST export A2UIRender component that accepts messages and onAction props
+- **FR-002**: System MUST export A2UIMessage type for defining message structures
+- **FR-003**: System MUST export A2UIAction type for defining action payloads
+- **FR-004**: A2UIRender MUST render all components defined in the messages array
+- **FR-005**: A2UIRender MUST invoke onAction callback when user interactions trigger actions
+- **FR-006**: A2UIRender MUST accept an optional components prop (ComponentsMap) for custom component overrides
+- **FR-007**: System MUST export useDispatchAction hook for custom components to dispatch actions
+- **FR-008**: System MUST export ComponentRenderer component for rendering child components within custom components
+- **FR-009**: System MUST export useDataBinding hook for reading data from the A2UI context
+- **FR-010**: System MUST export useFormBinding hook for two-way data binding in form components
+- **FR-011**: useDispatchAction hook MUST accept surfaceId, componentId, and action parameters
+- **FR-012**: useDataBinding hook MUST accept surfaceId, binding path, and default value parameters
+- **FR-013**: useFormBinding hook MUST return a tuple of [currentValue, setValue] for two-way binding
+- **FR-014**: ComponentRenderer MUST accept surfaceId and componentId props to render specific components
+- **FR-015**: Custom components MUST receive surfaceId and componentId as props for context identification
+
+### Key Entities
+
+- **A2UIMessage**: Represents a message containing UI component definitions to be rendered. Contains component tree structure and associated data.
+- **A2UIAction**: Represents an action payload triggered by user interaction. Contains action type and associated data for the callback.
+- **ComponentsMap**: A Map structure mapping component type names (strings) to React component implementations. Used for overriding defaults and adding custom components.
+- **Surface**: A rendering context identified by surfaceId that contains components and their associated data bindings.
+- **Component**: An individual UI element within a surface, identified by componentId, with properties specific to its type.
+
+## Success Criteria _(mandatory)_
+
+### Measurable Outcomes
+
+- **SC-001**: Developers can render A2UI messages with a single component import and minimal configuration (under 10 lines of code for basic usage)
+- **SC-002**: All user interactions on rendered components trigger the onAction callback within 100ms of user input
+- **SC-003**: Custom component overrides work without modifying library source code
+- **SC-004**: Custom components can access all necessary hooks (useDispatchAction, useDataBinding, useFormBinding) from the library exports
+- **SC-005**: The library exports are accessible via the versioned path '@easyops-cn/a2ui-react/0.8'
+- **SC-006**: Nested component rendering works to at least 10 levels deep without performance degradation
+- **SC-007**: Form bindings reflect value changes immediately (within one render cycle)
+
+## Assumptions
+
+- This library defines and owns the A2UI protocol message format types (A2UIMessage, A2UIAction, Surface, Component schemas)
+- React 18+ is the target runtime environment
+- TypeScript types are required for all public exports
+- Default components will be provided for common UI elements (Button, Text, etc.)
+- The versioned export path pattern (@easyops-cn/a2ui-react/0.8) follows npm package subpath exports convention