@easyops-cn/a2ui-react 0.0.0

package/playground/src/hooks/useTheme.ts

@@ -0,0 +1,55 @@
+import { useState, useEffect, useCallback } from 'react'
+
+type Theme = 'light' | 'dark'
+
+function getInitialTheme(): Theme {
+  // Check localStorage first
+  const stored = localStorage.getItem('theme')
+  if (stored === 'light' || stored === 'dark') {
+    return stored
+  }
+  // Fall back to system preference
+  if (typeof window !== 'undefined' && window.matchMedia) {
+    return window.matchMedia('(prefers-color-scheme: dark)').matches
+      ? 'dark'
+      : 'light'
+  }
+  return 'light'
+}
+
+export function useTheme() {
+  const [theme, setThemeState] = useState<Theme>(getInitialTheme)
+
+  const setTheme = useCallback((newTheme: Theme) => {
+    setThemeState(newTheme)
+    document.documentElement.dataset.theme = newTheme
+    document.documentElement.classList.remove('light', 'dark')
+    document.documentElement.classList.add(newTheme)
+    localStorage.setItem('theme', newTheme)
+  }, [])
+
+  const toggleTheme = useCallback(() => {
+    setTheme(theme === 'dark' ? 'light' : 'dark')
+  }, [theme, setTheme])
+
+  // Initialize theme on mount
+  useEffect(() => {
+    document.documentElement.dataset.theme = theme
+    document.documentElement.classList.add(theme)
+  }, [])
+
+  // Listen for system theme changes
+  useEffect(() => {
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+    const handleChange = (e: MediaQueryListEvent) => {
+      // Only update if no explicit preference is stored
+      if (!localStorage.getItem('theme')) {
+        setTheme(e.matches ? 'dark' : 'light')
+      }
+    }
+    mediaQuery.addEventListener('change', handleChange)
+    return () => mediaQuery.removeEventListener('change', handleChange)
+  }, [setTheme])
+
+  return { theme, toggleTheme, setTheme }
+}

package/playground/src/index.css

@@ -0,0 +1,220 @@
+@import 'tailwindcss';
+@import 'tw-animate-css';
+/* @source "../../src*.{ts,tsx}"; */
+@source "../../node_modules/@easyops-cn/a2ui-react";
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  --background: hsl(10, 10%, 98%);
+  --foreground: hsl(10, 20%, 20%);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: #009488;
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --radius: 0.625rem;
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: hsl(230, 25%, 18%);
+  --foreground: hsl(210, 50%, 96%);
+  --card: oklch(0.145 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.145 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: #80cbc4;
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.396 0.141 25.723);
+  --destructive-foreground: oklch(0.637 0.237 25.331);
+  --border: #ffffff1a;
+  --input: #ffffff1a;
+  --ring: oklch(0.439 0 0);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(0.269 0 0);
+  --sidebar-ring: oklch(0.439 0 0);
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+html {
+  --primary-color: var(--primary);
+  --text-color: var(--foreground);
+  --muted-color: var(--muted);
+  --background-color: var(--background);
+  --border-color: var(--border);
+  --editor-bg: hsl(0, 0%, 100%);
+  --preview-bg: hsl(0, 0%, 98%);
+
+  color-scheme: light;
+}
+
+@media (prefers-color-scheme: dark) {
+  html:not([data-theme='light']) {
+    --editor-bg: oklch(0.145 0 0);
+    --preview-bg: oklch(0.145 0 0);
+
+    color-scheme: dark;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+}
+
+html[data-theme='dark'] {
+  --editor-bg: oklch(0.145 0 0);
+  --preview-bg: oklch(0.145 0 0);
+
+  color-scheme: dark;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  font-family:
+    system-ui,
+    -apple-system,
+    Segoe UI,
+    Roboto,
+    Ubuntu,
+    Cantarell,
+    Noto Sans,
+    sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+  font-size: 16px;
+  margin: 0;
+}
+
+#root {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Error Display */
+.error-display {
+  padding: 16px;
+  background-color: hsl(0, 70%, 95%);
+  border: 1px solid hsl(0, 70%, 80%);
+  border-radius: 8px;
+  color: hsl(0, 70%, 30%);
+}
+
+html[data-theme='dark'] .error-display,
+html:not([data-theme='light']) .error-display {
+  background-color: hsl(0, 50%, 20%);
+  border-color: hsl(0, 50%, 35%);
+  color: hsl(0, 70%, 80%);
+}
+
+@media (prefers-color-scheme: dark) {
+  html:not([data-theme='light']) .error-display {
+    background-color: hsl(0, 50%, 20%);
+    border-color: hsl(0, 50%, 35%);
+    color: hsl(0, 70%, 80%);
+  }
+}
+
+.error-title {
+  font-weight: 600;
+  margin-bottom: 8px;
+}
+
+.error-message {
+  font-family: monospace;
+  font-size: 14px;
+  white-space: pre-wrap;
+  word-break: break-word;
+  margin: 0;
+}

package/playground/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+)

package/playground/tsconfig.app.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["../src/*"],
+      "@easyops-cn/a2ui-react/0.8": ["../src/0.8/index.ts"]
+    }
+  },
+  "include": ["src"]
+}

package/playground/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}

package/playground/tsconfig.node.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}

package/playground/vite.config.ts

@@ -0,0 +1,31 @@
+import path from 'path'
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+// https://vite.dev/config/
+export default defineConfig({
+  base: '/a2ui-react/playground/',
+  plugins: [
+    react({
+      babel: {
+        plugins: [['babel-plugin-react-compiler']],
+      },
+    }),
+    tailwindcss(),
+  ],
+  server: {
+    proxy: {
+      '^/a2ui-react/(?!playground/)': {
+        target: 'http://localhost:3000',
+        changeOrigin: true,
+      },
+    },
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, '../src'),
+      '@easyops-cn/a2ui-react/0.8': path.resolve(__dirname, '../src/0.8'),
+    },
+  },
+})

package/specs/001-a2ui-renderer/checklists/requirements.md

@@ -0,0 +1,41 @@
+# Specification Quality Checklist: A2UIRenderer Component Library
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-01-10
+**Feature**: [spec.md](./spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All items pass validation
+- Specification is ready for `/speckit.clarify` or `/speckit.plan`
+- The spec covers all usage patterns shown in README.md:
+  - Basic rendering with A2UIRender component
+  - Action handling via onAction callback
+  - Custom component overrides via ComponentsMap
+  - Custom component creation with hooks (useDispatchAction, useDataBinding, useFormBinding)
+  - Child component rendering via ComponentRenderer

package/specs/001-a2ui-renderer/data-model.md

@@ -0,0 +1,140 @@
+# Data Model: A2UIRenderer Component Library
+
+**Date**: 2026-01-10
+**Feature**: 001-a2ui-renderer
+
+## Overview
+
+This document describes the data model for the A2UI React renderer. The types are already defined in `src/0.8/types/index.ts`.
+
+## Core Entities
+
+### A2UIMessage
+
+The primary input to the renderer. Messages are processed to build surfaces and data models.
+
+```
+A2UIMessage
+├── beginRendering?: BeginRenderingPayload
+│   ├── surfaceId: string (required)
+│   ├── root: string (required) - root component ID
+│   ├── catalogId?: string
+│   └── styles?: SurfaceStyles
+├── surfaceUpdate?: SurfaceUpdatePayload
+│   ├── surfaceId: string (required)
+│   └── components: ComponentDefinition[] (required)
+├── dataModelUpdate?: DataModelUpdatePayload
+│   ├── surfaceId: string (required)
+│   ├── path?: string (default: "/")
+│   └── contents: DataEntry[] (required)
+└── deleteSurface?: DeleteSurfacePayload
+    └── surfaceId: string (required)
+```
+
+### Surface
+
+Runtime representation of a renderable UI surface.
+
+```
+Surface
+├── surfaceId: string (required) - unique identifier
+├── root: string (required) - root component ID
+├── components: Map<string, ComponentDefinition> (required)
+└── styles?: SurfaceStyles
+    ├── font?: string
+    └── primaryColor?: string
+```
+
+### ComponentDefinition
+
+Definition of a single UI component.
+
+```
+ComponentDefinition
+├── id: string (required) - unique within surface
+├── weight?: number - for ordering siblings
+└── component: { [type: string]: ComponentProps }
+    └── [type]: Record<string, unknown>
+```
+
+### DataModel
+
+Hierarchical key-value store for dynamic data.
+
+```
+DataModel
+└── [key: string]: DataModelValue
+    where DataModelValue = string | number | boolean | DataModel | unknown[]
+```
+
+### Action / ActionPayload
+
+User interaction events.
+
+```
+Action (input from component definition)
+├── name: string (required)
+└── context?: ActionContextItem[]
+    ├── key: string
+    └── value: ValueSource
+
+ActionPayload (output to onAction callback)
+├── surfaceId: string (required)
+├── name: string (required)
+├── context: Record<string, unknown> (resolved values)
+└── sourceComponentId: string (required)
+```
+
+### ValueSource
+
+Reference to data - either literal or path-based.
+
+```
+ValueSource (discriminated union)
+├── { literalString: string }
+├── { literalNumber: number }
+├── { literalBoolean: boolean }
+├── { literalArray: string[] }
+└── { path: string } - reference to DataModel path
+```
+
+## Entity Relationships
+
+```
+┌─────────────────┐
+│   A2UIMessage   │
+└────────┬────────┘
+         │ processes
+         ▼
+┌─────────────────┐     contains      ┌─────────────────────┐
+│     Surface     │◄─────────────────►│ ComponentDefinition │
+└────────┬────────┘                   └──────────┬──────────┘
+         │                                       │
+         │ references                            │ may contain
+         ▼                                       ▼
+┌─────────────────┐                   ┌─────────────────────┐
+│    DataModel    │◄──────────────────│       Action        │
+└─────────────────┘    resolves       └──────────┬──────────┘
+                       context                   │
+                                                 │ dispatches
+                                                 ▼
+                                      ┌─────────────────────┐
+                                      │    ActionPayload    │
+                                      └─────────────────────┘
+```
+
+## State Management
+
+| State          | Provider          | Access Hook                                         |
+| -------------- | ----------------- | --------------------------------------------------- |
+| Surfaces       | SurfaceProvider   | useSurfaceContext, useSurface                       |
+| Data Models    | DataModelProvider | useDataModelContext, useDataBinding, useFormBinding |
+| Action Handler | ActionProvider    | useActionContext, useDispatchAction                 |
+
+## Validation Rules
+
+1. **surfaceId**: Must be unique across all surfaces
+2. **componentId**: Must be unique within a surface
+3. **root**: Must reference a valid componentId in the surface
+4. **path**: Must start with "/" for DataModel references
+5. **ValueSource**: Exactly one variant must be set