@easyops-cn/a2ui-react 0.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to A2UI React
+
+Thank you for your interest in contributing to `@easyops-cn/a2ui-react`!
+
+## Project Overview
+
+A2UI React Renderer Library - A React implementation for rendering A2UI protocol. This is a library package that downstream developers consume.
+
+## Monorepo Structure
+
+This is an npm workspaces monorepo:
+
+- Root package: `@easyops-cn/a2ui-react` - The main library
+- `website/` - Documentation site using plain-blog
+- `playground/` - Live demo workspace for real-time A2UI rendering development
+
+## Development Setup
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+## Commands
+
+### Library (root)
+
+```bash
+npm run build        # TypeScript compile + Vite build (outputs to dist/)
+npm run dev          # Start Vite dev server for local development
+npm test             # Run Vitest in watch mode
+npm run test:run     # Run tests once
+npm run lint         # Run ESLint
+npm run lint:fix     # ESLint with auto-fix
+```
+
+### Website
+
+```bash
+npm run build -w website     # Build website (outputs to website/dist/)
+npm run serve -w website     # Serve built website locally
+```
+
+### Playground
+
+```bash
+npm run dev -w playground    # Start playground dev server for live A2UI demos
+npm run build -w playground  # Build playground
+```
+
+## Key Directories
+
+- `src/0.8/contexts/` - React context providers (Surface, DataModel, Action)
+- `src/0.8/hooks/` - Custom hooks for data binding and actions
+- `src/0.8/components/` - Component implementations (display/, layout/, interactive/)
+- `src/0.8/schemas/` - JSON schemas for A2UI protocol
+- `src/components/ui/` - shadcn/ui primitives
+
+## Testing
+
+Tests are co-located with source files (`*.test.tsx`). Uses Vitest + React Testing Library + jsdom.
+
+Run tests before submitting:
+
+```bash
+npm run test:run
+```
+
+## Code Style
+
+Run linting before submitting:
+
+```bash
+npm run lint
+```
+
+To auto-fix issues:
+
+```bash
+npm run lint:fix
+```
+
+## Technologies
+
+- TypeScript 5.9
+- React 19
+- Radix UI (for UI primitives)
+- Tailwind CSS (via class-variance-authority)
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests and linting
+5. Submit a pull request

package/README.md

@@ -0,0 +1,126 @@
+# A2UI React Renderer Library
+
+https://easyops-cn.github.io/a2ui-react/
+
+A React renderer library for [A2UI](https://a2ui.org) protocol.
+
+Supports all components in A2UI standard catalog out of the box. Built with [shadcn/ui](https://ui.shadcn.com/) and [Tailwind CSS](https://tailwindcss.com/).
+
+Currently A2UI protocol v0.8 is fully supported. Work on v0.9 is in progress.
+
+## Installation
+
+```sh
+npm install @easyops-cn/a2ui-react
+```
+
+## Usage
+
+First, use the `@source` directive to tell Tailwind to scan the library code for class names in your global CSS:
+
+```css
+@source "../node_modules/@easyops-cn/a2ui-react";
+```
+
+Next, use the `A2UIRender` component to render A2UI messages:
+
+```tsx
+import {
+  A2UIRender,
+  type A2UIMessage,
+  type A2UIAction,
+} from '@easyops-cn/a2ui-react/0.8'
+
+function App() {
+  const messages: A2UIMessage[] = []
+
+  const handleAction = (action: A2UIAction) => {
+    console.log('Action received:', action)
+  }
+
+  return <A2UIRender messages={messages} onAction={handleAction} />
+}
+```
+
+### Custom components
+
+You can override default components or add new custom components via the `components` prop, which takes a `Map<string, React.ComponentType>`.
+
+```tsx
+import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+
+const ComponentsMap = new Map<string, React.ComponentType<any>>([
+  // Override default Button component with a custom one
+  ['Button', CustomButtonComponent],
+
+  // Add a new custom Switch component
+  ['Switch', CustomSwitchComponent],
+])
+
+function App() {
+  return (
+    <A2UIRender
+      components={ComponentsMap}
+      messages={messages}
+      onAction={handleAction}
+    />
+  )
+}
+```
+
+Custom button component with action dispatch:
+
+```tsx
+import {
+  useDispatchAction,
+  ComponentRenderer,
+  type ButtonComponentProps,
+} from '@easyops-cn/a2ui-react/0.8'
+
+export function CustomButtonComponent({
+  surfaceId,
+  componentId,
+  child,
+  action,
+}: ButtonComponentProps) {
+  const dispatchAction = useDispatchAction()
+
+  const handleClick = () => {
+    if (action) {
+      dispatchAction(surfaceId, componentId, action)
+    }
+  }
+
+  return (
+    <button onClick={handleClick}>
+      <ComponentRenderer surfaceId={surfaceId} componentId={child} />
+    </button>
+  )
+}
+```
+
+Custom switch component with data binding:
+
+```tsx
+import { useDataBinding, useFormBinding } from '@easyops-cn/a2ui-react/0.8'
+
+export function CustomSwitchComponent({
+  surfaceId,
+  componentId,
+  label,
+  value,
+}: SwitchComponentProps) {
+  const labelText = useDataBinding<string>(surfaceId, label, '')
+  const [checked, setChecked] = useFormBinding<boolean>(surfaceId, value, false)
+
+  const handleChange = (newChecked: boolean) => {
+    setChecked(newChecked)
+  }
+
+  return (
+    <Switch checked={checked} onChange={handleChange}>
+      {labelText}
+    </Switch>
+  )
+}
+```

package/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/eslint.config.js

@@ -0,0 +1,25 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import tseslint from 'typescript-eslint'
+import eslintConfigPrettier from 'eslint-config-prettier'
+
+export default tseslint.config(
+  { ignores: ['dist', 'node_modules', 'coverage'] },
+  {
+    extends: [js.configs.recommended, ...tseslint.configs.recommended],
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+    plugins: {
+      'react-hooks': reactHooks,
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-hooks/set-state-in-effect': 'off',
+    },
+  },
+  eslintConfigPrettier
+)

package/netlify.toml

@@ -0,0 +1,50 @@
+[[redirects]]
+  from = "/"
+  to = "/a2ui-react/"
+  status = 302
+  force = true
+
+[[headers]]
+  for = "*.js" # js files should be set this way
+  [headers.values]
+    Cache-Control = "public, max-age=604800"
+
+[[headers]]
+  for = "*.css" # css files too
+  [headers.values]
+    Cache-Control = "public, max-age=604800"
+
+[[headers]]
+  for = "*.json"
+  [headers.values]
+    Cache-Control = "public, max-age=604800"
+
+[[headers]]
+  for = "*.svg"
+  [headers.values]
+    Cache-Control = "public, max-age=604800"
+
+[[headers]]
+  for = "*.png"
+  [headers.values]
+    Cache-Control = "public, max-age=604800"
+
+[[headers]]
+  for = "*.jpg"
+  [headers.values]
+    Cache-Control = "public, max-age=604800"
+
+[[headers]]
+  for = "*.gif"
+  [headers.values]
+    Cache-Control = "public, max-age=604800"
+
+[[headers]]
+  for = "*.ttf"
+  [headers.values]
+    Cache-Control = "public, max-age=604800"
+
+[[headers]]
+  for = "*.map"
+  [headers.values]
+    Cache-Control = "public, max-age=604800"

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@easyops-cn/a2ui-react",
+  "version": "0.0.0",
+  "description": "A2UI React Renderer Library",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./0.8": {
+      "types": "./dist/0.8/index.d.ts",
+      "default": "./dist/0.8/index.js"
+    }
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky"
+  },
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^25.0.5",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "globals": "^17.0.0",
+    "husky": "^9.1.7",
+    "jsdom": "^27.4.0",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.52.0",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-tsconfig-paths": "^6.0.4",
+    "vitest": "^4.0.16"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md,css,scss}": [
+      "prettier --write"
+    ]
+  },
+  "dependencies": {
+    "@radix-ui/react-checkbox": "^1.3.3",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slider": "^1.3.6",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "date-fns": "^4.1.0",
+    "lucide-react": "^0.562.0",
+    "react-day-picker": "^9.13.0",
+    "tailwind-merge": "^3.4.0"
+  },
+  "workspaces": [
+    "website",
+    "playground"
+  ]
+}

package/playground/README.md

@@ -0,0 +1,75 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is enabled on this template. See [this documentation](https://react.dev/learn/react-compiler) for more information.
+
+Note: This will impact Vite dev & build performances.
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

package/playground/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>A2UI React Renderer Playground</title>
+    <script>
+      // Initialize theme before page renders to prevent flash
+      (function() {
+        const stored = localStorage.getItem('theme');
+        if (stored === 'dark' || stored === 'light') {
+          document.documentElement.dataset.theme = stored;
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/playground/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "playground",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@codemirror/lang-json": "^6.0.2",
+    "@easyops-cn/a2ui-react": "file:..",
+    "@tailwindcss/vite": "^4.1.18",
+    "@uiw/react-codemirror": "^4.25.4",
+    "lucide-react": "^0.562.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.6",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "globals": "^17.0.0",
+    "typescript": "~5.9.3",
+    "vite": "^7.2.4"
+  }
+}

package/playground/public/favicon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
+<!--!Font Awesome Free 6.7.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2025 Fonticons, Inc.-->
+  <!-- <rect x="0" y="0" width="512" height="512" fill="white" stroke="none"></rect> -->
+  <circle cx="256" cy="256" r="256" fill="white" stroke="none"></circle>
+  <g transform="translate(112 64) scale(0.75)">
+    <path d="M64 464c-8.8 0-16-7.2-16-16L48 64c0-8.8 7.2-16 16-16l160 0 0 80c0 17.7 14.3 32 32 32l80 0 0 288c0 8.8-7.2 16-16 16L64 464zM64 0C28.7 0 0 28.7 0 64L0 448c0 35.3 28.7 64 64 64l256 0c35.3 0 64-28.7 64-64l0-293.5c0-17-6.7-33.3-18.7-45.3L274.7 18.7C262.7 6.7 246.5 0 229.5 0L64 0zm56 256c-13.3 0-24 10.7-24 24s10.7 24 24 24l144 0c13.3 0 24-10.7 24-24s-10.7-24-24-24l-144 0zm0 96c-13.3 0-24 10.7-24 24s10.7 24 24 24l144 0c13.3 0 24-10.7 24-24s-10.7-24-24-24l-144 0z" fill="#009488" stroke="none" />
+  </g>
+</svg>