@easyops-cn/a2ui-react 0.0.0

package/specs/002-playground/quickstart.md

@@ -0,0 +1,158 @@
+# Quickstart: A2UI Playground Development
+
+**Feature**: 002-playground
+**Date**: 2026-01-10
+
+## Prerequisites
+
+- Node.js 18+
+- npm 9+
+- Repository cloned with dependencies installed (`npm install` at root)
+
+## Development Setup
+
+### 1. Install Playground Dependencies
+
+```bash
+# From repository root
+npm install -w playground @uiw/react-codemirror @codemirror/lang-json
+```
+
+### 2. Link Main Library
+
+The playground uses the main `@easyops-cn/a2ui-react` library as a workspace dependency. Ensure the library is built:
+
+```bash
+# Build the main library
+npm run build
+```
+
+### 3. Start Development Server
+
+```bash
+# Start playground dev server
+npm run dev -w playground
+```
+
+The playground will be available at `http://localhost:5173` (or next available port).
+
+## Project Structure
+
+```
+playground/src/
+├── components/          # React components
+│   ├── Header.tsx       # App header with title and theme toggle
+│   ├── ThemeToggle.tsx  # Sun/moon theme switch
+│   ├── JsonEditor.tsx   # CodeMirror JSON editor
+│   ├── Preview.tsx      # A2UIRender wrapper
+│   ├── ExampleSelector.tsx  # Example dropdown
+│   └── ErrorDisplay.tsx # Error state component
+├── data/
+│   └── examples.ts      # Pre-built A2UI examples
+├── hooks/
+│   └── useTheme.ts      # Theme state hook
+├── App.tsx              # Main application
+├── App.css              # Layout styles
+├── main.tsx             # Entry point
+└── index.css            # Global/Tailwind styles
+```
+
+## Key Implementation Notes
+
+### Theme System
+
+The playground uses the same theme approach as the website:
+
+```typescript
+// Set theme via data attribute
+document.documentElement.dataset.theme = 'dark' // or 'light'
+
+// CSS variables respond to theme
+html[data-theme='dark'] {
+  --background-color: hsl(230, 25%, 18%);
+  --text-color: hsl(210, 50%, 96%);
+}
+```
+
+### JSON Editor Integration
+
+```typescript
+import CodeMirror from '@uiw/react-codemirror'
+import { json } from '@codemirror/lang-json'
+
+<CodeMirror
+  value={jsonContent}
+  extensions={[json()]}
+  onChange={(value) => setJsonContent(value)}
+/>
+```
+
+### A2UIRender Integration
+
+```typescript
+import { A2UIRender, type A2UIMessage } from '@easyops-cn/a2ui-react/0.8'
+
+// Parse JSON and render
+const messages: A2UIMessage[] = JSON.parse(jsonContent)
+<A2UIRender messages={messages} onAction={handleAction} />
+```
+
+### Error Boundary Pattern
+
+```typescript
+class ErrorBoundary extends React.Component {
+  state = { hasError: false, error: null }
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true, error }
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <ErrorDisplay error={this.state.error} />
+    }
+    return this.props.children
+  }
+}
+```
+
+## Testing
+
+```bash
+# Run tests (from root)
+npm test -w playground
+
+# Run specific test file
+npm test -w playground -- JsonEditor.test.tsx
+```
+
+## Building for Production
+
+```bash
+# Build playground
+npm run build -w playground
+
+# Preview production build
+npm run preview -w playground
+```
+
+Output will be in `playground/dist/`.
+
+## Common Tasks
+
+### Adding a New Example
+
+1. Edit `playground/src/data/examples.ts`
+2. Add new example object with `id`, `title`, `description`, and `messages`
+3. The example will automatically appear in the dropdown
+
+### Modifying Theme Colors
+
+1. Edit `playground/src/App.css` or `playground/src/index.css`
+2. Update CSS custom properties for light/dark themes
+3. Match website colors from `website/src/global.css`
+
+### Updating CodeMirror Theme
+
+1. Import desired theme: `import { oneDark } from '@codemirror/theme-one-dark'`
+2. Add to extensions array: `extensions={[json(), oneDark]}`

package/specs/002-playground/research.md

@@ -0,0 +1,117 @@
+# Research: A2UI Playground
+
+**Feature**: 002-playground
+**Date**: 2026-01-10
+
+## JSON Editor Library Selection
+
+### Decision
+
+**CodeMirror 6** via `@uiw/react-codemirror` wrapper
+
+### Rationale
+
+- **Bundle size**: ~40-150KB gzipped (vs Monaco's 500KB+)
+- **Performance**: Designed for real-time editing, used by Replit in production
+- **React integration**: Clean wrapper with `@uiw/react-codemirror`
+- **JSON support**: Official `@codemirror/lang-json` package with syntax highlighting
+- **Modular**: Only include needed features
+
+### Alternatives Considered
+
+| Option                   | Bundle Size | Verdict                              |
+| ------------------------ | ----------- | ------------------------------------ |
+| Monaco Editor            | 500KB+      | Too heavy for playground use case    |
+| Prism.js                 | 10-50KB     | Read-only, no editing capability     |
+| react-simple-code-editor | ~5KB        | Limited features, no JSON validation |
+
+### Required Packages
+
+```
+@uiw/react-codemirror
+@codemirror/lang-json
+@codemirror/theme-one-dark (for dark mode)
+```
+
+## Theme Implementation
+
+### Decision
+
+Reuse website's theme approach with `data-theme` attribute on `<html>` element
+
+### Rationale
+
+- Consistent with existing website implementation
+- Uses CSS custom properties for theming
+- localStorage persistence already proven pattern
+- Sun/moon icons from lucide-react (already in main library dependencies)
+
+### Implementation Pattern
+
+```typescript
+// Theme stored in localStorage as 'theme' key
+// Values: 'light' | 'dark'
+// Applied via: document.documentElement.dataset.theme = theme
+```
+
+## A2UI Library Integration
+
+### Decision
+
+Import from workspace dependency `@easyops-cn/a2ui-react/0.8`
+
+### Rationale
+
+- Playground is in same monorepo as library
+- Vite workspace alias already configured
+- Direct import ensures latest library version during development
+
+### Integration Pattern
+
+```typescript
+import { A2UIRender, type A2UIMessage } from '@easyops-cn/a2ui-react/0.8'
+
+// Parse JSON string to A2UIMessage[]
+// Pass to A2UIRender component
+// Handle parse errors gracefully
+```
+
+## Example Categories
+
+### Decision
+
+Include 5 examples covering core A2UI capabilities
+
+### Examples
+
+1. **Hello World** - Basic Text component
+2. **Layout Demo** - Column/Row with multiple children
+3. **Button Actions** - Interactive Button with action handling
+4. **Form Inputs** - TextField, Checkbox, Select components
+5. **Data Binding** - Components with ValueSource path bindings
+
+### Rationale
+
+- Covers all component categories (display, layout, interactive)
+- Progressive complexity for learning
+- Demonstrates key A2UI concepts (actions, data binding)
+
+## Error Handling
+
+### Decision
+
+Use React Error Boundary for preview panel with graceful fallback
+
+### Rationale
+
+- Prevents entire app crash on render errors
+- Shows user-friendly error message
+- Allows continued editing after errors
+
+### Implementation Pattern
+
+```typescript
+// ErrorBoundary wraps A2UIRender
+// Catches render errors, displays ErrorDisplay component
+// JSON parse errors handled separately before render
+```

package/specs/002-playground/spec.md

@@ -0,0 +1,109 @@
+# Feature Specification: A2UI Playground
+
+**Feature Branch**: `002-playground`
+**Created**: 2026-01-10
+**Status**: Draft
+**Input**: User description: "实现 playground，顶栏和 website 现在的 header 一致，包括标题和切换深/浅主题图标；内容区左侧为 json 编辑器，右侧为 A2UIRenderer 的实时预览；同时提供一些常见场景的示例作为 select 项"
+
+## Clarifications
+
+### Session 2026-01-10
+
+- Q: What should users see when they first load the playground? → A: Load with first example pre-selected (editor populated, preview showing)
+
+## User Scenarios & Testing _(mandatory)_
+
+### User Story 1 - Live JSON Editing with Preview (Priority: P1)
+
+A developer wants to experiment with A2UI message structures by editing JSON and seeing the rendered result immediately. They open the playground, type or paste A2UI JSON messages in the left editor panel, and see the corresponding UI rendered in real-time on the right panel.
+
+**Why this priority**: This is the core value proposition of the playground - enabling rapid prototyping and learning of A2UI message structures without setting up a full development environment.
+
+**Independent Test**: Can be fully tested by entering valid A2UI JSON and verifying the preview updates. Delivers immediate value for developers learning the A2UI protocol.
+
+**Acceptance Scenarios**:
+
+1. **Given** the playground is loaded, **When** a user types valid A2UI JSON in the editor, **Then** the preview panel displays the rendered components in real-time
+2. **Given** valid JSON is in the editor, **When** the user modifies the JSON, **Then** the preview updates automatically without requiring manual refresh
+3. **Given** invalid JSON is in the editor, **When** the user views the preview, **Then** the preview shows an appropriate error state without crashing
+
+---
+
+### User Story 2 - Example Selection (Priority: P2)
+
+A developer new to A2UI wants to learn by example. They select a pre-built example from a dropdown menu, which populates the JSON editor with a working A2UI message structure and displays the rendered result.
+
+**Why this priority**: Examples accelerate learning and provide starting points for customization, but the core editing functionality must work first.
+
+**Independent Test**: Can be tested by selecting each example from the dropdown and verifying both the JSON editor content and preview update correctly.
+
+**Acceptance Scenarios**:
+
+1. **Given** the playground is loaded, **When** a user selects an example from the dropdown, **Then** the JSON editor is populated with the example's A2UI messages
+2. **Given** an example is selected, **When** the JSON editor is populated, **Then** the preview panel displays the rendered example
+3. **Given** multiple examples exist, **When** a user switches between examples, **Then** both the editor and preview update to reflect the newly selected example
+
+---
+
+### User Story 3 - Theme Switching (Priority: P3)
+
+A developer wants to test how their A2UI components look in both light and dark modes. They click the theme toggle icon in the header to switch between light and dark themes, and the entire playground (including the preview) updates accordingly.
+
+**Why this priority**: Theme consistency with the website is important for brand coherence, but it's a secondary concern after core functionality.
+
+**Independent Test**: Can be tested by clicking the theme toggle and verifying the visual appearance changes for both the playground chrome and the preview area.
+
+**Acceptance Scenarios**:
+
+1. **Given** the playground is in light mode, **When** a user clicks the theme toggle, **Then** the playground switches to dark mode
+2. **Given** the playground is in dark mode, **When** a user clicks the theme toggle, **Then** the playground switches to light mode
+3. **Given** a theme preference is set, **When** the user returns to the playground later, **Then** the previously selected theme is restored
+
+---
+
+### Edge Cases
+
+- What happens when the JSON editor contains empty content? The preview should show an empty state.
+- How does the system handle extremely large JSON payloads? The editor should remain responsive with reasonable-sized inputs (up to 100KB).
+- What happens when the browser window is resized? The layout should adapt responsively, maintaining usability on different screen sizes.
+- What happens when a user modifies an example after selecting it? The changes should be preserved until a new example is selected.
+
+## Requirements _(mandatory)_
+
+### Functional Requirements
+
+- **FR-001**: System MUST display a header with the title "A2UI React Renderer" matching the website header design
+- **FR-002**: System MUST provide a theme toggle icon (sun/moon) in the header that switches between light and dark modes
+- **FR-003**: System MUST persist theme preference across browser sessions using localStorage
+- **FR-004**: System MUST display a split-panel layout with JSON editor on the left and preview on the right
+- **FR-005**: System MUST render A2UI components in the preview panel based on the JSON editor content
+- **FR-006**: System MUST update the preview automatically when the JSON editor content changes
+- **FR-007**: System MUST provide a dropdown/select control to choose from pre-built examples
+- **FR-008**: System MUST include examples covering common A2UI scenarios: basic text display, layout containers, interactive buttons, form inputs, and data binding
+- **FR-009**: System MUST display a clear error state in the preview when JSON is invalid or cannot be rendered
+- **FR-010**: System MUST maintain responsive layout that works on screens 1024px wide and above
+- **FR-011**: System MUST load with the first example pre-selected, showing populated editor and rendered preview on initial page load
+
+### Key Entities
+
+- **A2UI Messages**: Array of message objects following the A2UI protocol (beginRendering, surfaceUpdate, dataModelUpdate)
+- **Example**: A named preset containing a title, description, and pre-configured A2UI messages array
+- **Theme**: User preference for light or dark color scheme, stored in localStorage
+
+## Success Criteria _(mandatory)_
+
+### Measurable Outcomes
+
+- **SC-001**: Users can see preview updates within 500ms of making JSON edits
+- **SC-002**: All provided examples render correctly without errors
+- **SC-003**: Theme toggle persists preference and applies consistently across the entire interface
+- **SC-004**: Playground loads and becomes interactive within 3 seconds on standard broadband connection
+- **SC-005**: 90% of first-time users can successfully modify an example and see the result without external documentation
+
+## Assumptions
+
+- The playground targets desktop users with screens 1024px or wider; mobile optimization is out of scope
+- Users have basic familiarity with JSON syntax
+- The A2UIRenderer component from the main library is stable and can be used directly
+- Examples will be hardcoded initially; dynamic example loading is out of scope
+- The JSON editor will use a standard code editor component with syntax highlighting (specific library choice is an implementation detail)

package/specs/002-playground/tasks.md

@@ -0,0 +1,224 @@
+# Tasks: A2UI Playground
+
+**Input**: Design documents from `/specs/002-playground/`
+**Prerequisites**: plan.md, spec.md, research.md, data-model.md
+
+**Tests**: Not explicitly requested in specification. Test tasks omitted.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+Based on plan.md, the playground is a workspace within the monorepo:
+
+```text
+playground/
+├── src/
+│   ├── components/    # React components
+│   ├── data/          # Example data
+│   ├── hooks/         # Custom hooks
+│   ├── App.tsx        # Main application
+│   └── ...
+```
+
+---
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and dependency installation
+
+- [x] T001 Install CodeMirror dependencies: `npm install -w playground @uiw/react-codemirror @codemirror/lang-json`
+- [x] T002 Install lucide-react for icons: `npm install -w playground lucide-react`
+- [x] T003 Configure Vite to resolve @easyops-cn/a2ui-react workspace dependency in playground/vite.config.ts
+- [x] T004 [P] Create components directory structure in playground/src/components/
+- [x] T005 [P] Create data directory structure in playground/src/data/
+- [x] T006 [P] Create hooks directory structure in playground/src/hooks/
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+- [x] T007 Create Example type definition in playground/src/data/examples.ts (interface only, no data yet)
+- [x] T008 Create ErrorDisplay component for showing error messages in playground/src/components/ErrorDisplay.tsx
+- [x] T009 Setup global CSS with theme variables (light/dark) matching website in playground/src/index.css
+- [x] T010 Update playground/index.html with proper title and theme initialization script
+
+**Checkpoint**: Foundation ready - user story implementation can now begin
+
+---
+
+## Phase 3: User Story 1 - Live JSON Editing with Preview (Priority: P1) 🎯 MVP
+
+**Goal**: Enable developers to edit A2UI JSON and see real-time rendered preview
+
+**Independent Test**: Enter valid A2UI JSON in editor, verify preview updates within 500ms. Enter invalid JSON, verify error state displays without crash.
+
+### Implementation for User Story 1
+
+- [x] T011 [P] [US1] Create JsonEditor component with CodeMirror integration in playground/src/components/JsonEditor.tsx
+- [x] T012 [P] [US1] Create Preview component wrapping A2UIRender with error boundary in playground/src/components/Preview.tsx
+- [x] T013 [US1] Create split-panel layout in playground/src/App.tsx with editor (left) and preview (right)
+- [x] T014 [US1] Add layout styles for split-panel (50/50) in playground/src/App.css
+- [x] T015 [US1] Implement JSON parsing with error handling in App.tsx (parse on change, update preview or show error)
+- [x] T016 [US1] Add action handler to log dispatched actions to console in App.tsx
+
+**Checkpoint**: User Story 1 complete - can edit JSON and see live preview with error handling
+
+---
+
+## Phase 4: User Story 2 - Example Selection (Priority: P2)
+
+**Goal**: Provide pre-built examples that populate the editor and preview
+
+**Independent Test**: Select each example from dropdown, verify editor content and preview both update correctly.
+
+### Implementation for User Story 2
+
+- [x] T017 [P] [US2] Create "Hello World" example (basic Text component) in playground/src/data/examples.ts
+- [x] T018 [P] [US2] Create "Layout Demo" example (Column/Row with children) in playground/src/data/examples.ts
+- [x] T019 [P] [US2] Create "Button Actions" example (Button with action) in playground/src/data/examples.ts
+- [x] T020 [P] [US2] Create "Form Inputs" example (TextField, Checkbox) in playground/src/data/examples.ts
+- [x] T021 [P] [US2] Create "Data Binding" example (ValueSource path bindings) in playground/src/data/examples.ts
+- [x] T022 [US2] Create ExampleSelector dropdown component in playground/src/components/ExampleSelector.tsx
+- [x] T023 [US2] Integrate ExampleSelector into App.tsx (place above editor, wire up selection handler)
+- [x] T024 [US2] Implement initial load with first example pre-selected in App.tsx
+
+**Checkpoint**: User Story 2 complete - can select examples and see them populate editor/preview
+
+---
+
+## Phase 5: User Story 3 - Theme Switching (Priority: P3)
+
+**Goal**: Allow switching between light and dark themes with persistence
+
+**Independent Test**: Click theme toggle, verify entire UI switches theme. Refresh page, verify theme persists.
+
+### Implementation for User Story 3
+
+- [x] T025 [P] [US3] Create useTheme hook with localStorage persistence in playground/src/hooks/useTheme.ts
+- [x] T026 [P] [US3] Create ThemeToggle component (sun/moon icons) in playground/src/components/ThemeToggle.tsx
+- [x] T027 [US3] Create Header component with title and ThemeToggle in playground/src/components/Header.tsx
+- [x] T028 [US3] Integrate Header into App.tsx layout
+- [x] T029 [US3] Add CodeMirror theme switching (light/dark) based on current theme in JsonEditor.tsx
+- [x] T030 [US3] Style Header to match website design (primary color, font) in playground/src/App.css
+
+**Checkpoint**: User Story 3 complete - theme toggle works with persistence
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: Final improvements and validation
+
+- [x] T031 Add responsive layout adjustments for 1024px+ screens in playground/src/App.css
+- [ ] T032 Verify all examples render without errors (manual test each example)
+- [ ] T033 Verify preview updates within 500ms of JSON edits (performance check)
+- [x] T034 Run `npm run build -w playground` and verify production build succeeds
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3-5)**: All depend on Foundational phase completion
+  - User stories can proceed sequentially in priority order (P1 → P2 → P3)
+  - Or in parallel if multiple developers available
+- **Polish (Phase 6)**: Depends on all user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - Integrates with US1 editor/preview but independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - Integrates with US1 editor but independently testable
+
+### Within Each User Story
+
+- Components before integration
+- Core implementation before styling
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+**Phase 1 (Setup)**:
+
+- T004, T005, T006 can run in parallel (directory creation)
+
+**Phase 3 (US1)**:
+
+- T011, T012 can run in parallel (JsonEditor and Preview are independent components)
+
+**Phase 4 (US2)**:
+
+- T017, T018, T019, T020, T021 can ALL run in parallel (each example is independent)
+
+**Phase 5 (US3)**:
+
+- T025, T026 can run in parallel (useTheme hook and ThemeToggle component are independent)
+
+---
+
+## Parallel Example: User Story 2
+
+```bash
+# Launch all example creation tasks together:
+Task: "Create Hello World example in playground/src/data/examples.ts"
+Task: "Create Layout Demo example in playground/src/data/examples.ts"
+Task: "Create Button Actions example in playground/src/data/examples.ts"
+Task: "Create Form Inputs example in playground/src/data/examples.ts"
+Task: "Create Data Binding example in playground/src/data/examples.ts"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup (T001-T006)
+2. Complete Phase 2: Foundational (T007-T010)
+3. Complete Phase 3: User Story 1 (T011-T016)
+4. **STOP and VALIDATE**: Test JSON editing and preview independently
+5. Deploy/demo if ready - core playground functionality works
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → **MVP Ready!**
+3. Add User Story 2 → Test independently → Examples available
+4. Add User Story 3 → Test independently → Theme switching works
+5. Polish phase → Production ready
+
+### Single Developer Strategy
+
+Execute phases sequentially:
+
+1. Phase 1: Setup (~10 min)
+2. Phase 2: Foundational (~20 min)
+3. Phase 3: User Story 1 (~45 min) → **MVP checkpoint**
+4. Phase 4: User Story 2 (~30 min)
+5. Phase 5: User Story 3 (~30 min)
+6. Phase 6: Polish (~15 min)
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- The playground workspace already exists with basic Vite setup; tasks build on existing structure