@easyops-cn/a2ui-react 0.0.0

package/src/0.8/A2UIRender.tsx

@@ -0,0 +1,142 @@
+/**
+ * A2UIRender - Main entry component for rendering A2UI messages.
+ *
+ * This component processes A2UI messages and renders the resulting UI.
+ * It supports custom component overrides via the components prop.
+ *
+ * @example
+ * ```tsx
+ * import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+ *
+ * function App() {
+ *   const messages: A2UIMessage[] = [...]
+ *   const handleAction = (action: A2UIAction) => {
+ *     console.log('Action:', action)
+ *   }
+ *   return <A2UIRender messages={messages} onAction={handleAction} />
+ * }
+ * ```
+ */
+
+import { useEffect, type ComponentType } from 'react'
+import type { A2UIMessage, ActionPayload, BaseComponentProps } from './types'
+import { A2UIProvider } from './contexts/A2UIProvider'
+import { ComponentsMapProvider } from './contexts/ComponentsMapContext'
+import { useSurfaceContext } from './contexts/SurfaceContext'
+import { useA2UIMessageHandler } from './hooks/useA2UIMessageHandler'
+import {
+  ComponentRenderer,
+  componentRegistry,
+} from './components/ComponentRenderer'
+
+/**
+ * Type for custom component map.
+ */
+export type ComponentsMap = Map<
+  string,
+  ComponentType<BaseComponentProps & Record<string, unknown>>
+>
+
+/**
+ * Props for A2UIRender component.
+ */
+export interface A2UIRenderProps {
+  /** Array of A2UI messages to render */
+  messages: A2UIMessage[]
+  /** Callback when an action is dispatched */
+  onAction?: (action: ActionPayload) => void
+  /** Custom component overrides */
+  components?: ComponentsMap
+}
+
+/**
+ * Internal component that handles message processing and surface rendering.
+ */
+function A2UIRenderInner({ messages }: { messages: A2UIMessage[] }) {
+  const { processMessages, clear } = useA2UIMessageHandler()
+  const { surfaces } = useSurfaceContext()
+
+  // Process messages when they change
+  useEffect(() => {
+    // Clear existing state and process new messages
+    clear()
+    if (messages && messages.length > 0) {
+      processMessages(messages)
+    }
+  }, [messages, processMessages, clear])
+
+  // Render all surfaces
+  const surfaceEntries = Array.from(surfaces.entries())
+
+  if (surfaceEntries.length === 0) {
+    return null
+  }
+
+  return (
+    <>
+      {surfaceEntries.map(([surfaceId, surface]) => {
+        // Only render surfaces that have a root component
+        if (!surface.root) {
+          return null
+        }
+        return (
+          <ComponentRenderer
+            key={surfaceId}
+            surfaceId={surfaceId}
+            componentId={surface.root}
+          />
+        )
+      })}
+    </>
+  )
+}
+
+/**
+ * Main entry component for rendering A2UI messages.
+ *
+ * Processes an array of A2UIMessage objects and renders the resulting UI.
+ * Supports custom component overrides via the components prop.
+ *
+ * @param props - Component props
+ * @param props.messages - Array of A2UI messages to render
+ * @param props.onAction - Optional callback when an action is dispatched
+ * @param props.components - Optional custom component overrides
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <A2UIRender messages={messages} onAction={handleAction} />
+ *
+ * // With custom components
+ * const customComponents = new Map([
+ *   ['Button', CustomButton],
+ *   ['Switch', CustomSwitch],
+ * ])
+ * <A2UIRender
+ *   messages={messages}
+ *   onAction={handleAction}
+ *   components={customComponents}
+ * />
+ * ```
+ */
+export function A2UIRender({
+  messages,
+  onAction,
+  components,
+}: A2UIRenderProps) {
+  // Handle null/undefined messages gracefully
+  const safeMessages = messages ?? []
+
+  return (
+    <A2UIProvider onAction={onAction}>
+      <ComponentsMapProvider
+        components={components}
+        defaultComponents={componentRegistry}
+      >
+        <A2UIRenderInner messages={safeMessages} />
+      </ComponentsMapProvider>
+    </A2UIProvider>
+  )
+}
+
+A2UIRender.displayName = 'A2UI.Render'

package/src/0.8/components/ComponentRenderer.test.tsx

@@ -0,0 +1,373 @@
+/**
+ * ComponentRenderer Tests
+ *
+ * Tests for the ComponentRenderer component that routes rendering based on type.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { ComponentRenderer, registerComponent } from './ComponentRenderer'
+import { SurfaceProvider, useSurfaceContext } from '../contexts/SurfaceContext'
+import { DataModelProvider } from '../contexts/DataModelContext'
+import { ActionProvider } from '../contexts/ActionContext'
+import type { ReactNode } from 'react'
+import type { BaseComponentProps, ComponentDefinition } from '../types'
+import React from 'react'
+
+// Wrapper with all providers
+const wrapper = ({ children }: { children: ReactNode }) => (
+  <SurfaceProvider>
+    <DataModelProvider>
+      <ActionProvider>{children}</ActionProvider>
+    </DataModelProvider>
+  </SurfaceProvider>
+)
+
+// Helper component to set up surface with components
+function SurfaceSetup({
+  children,
+  components,
+}: {
+  children: ReactNode
+  components: ComponentDefinition[]
+}) {
+  const { initSurface, updateSurface } = useSurfaceContext()
+  React.useEffect(() => {
+    initSurface('test-surface', 'root')
+    updateSurface('test-surface', components)
+  }, [initSurface, updateSurface, components])
+  return <>{children}</>
+}
+
+// Custom wrapper that sets up surface
+const createSurfaceWrapper = (components: ComponentDefinition[]) => {
+  return ({ children }: { children: ReactNode }) => (
+    <SurfaceProvider>
+      <DataModelProvider>
+        <ActionProvider>
+          <SurfaceSetup components={components}>{children}</SurfaceSetup>
+        </ActionProvider>
+      </DataModelProvider>
+    </SurfaceProvider>
+  )
+}
+
+describe('ComponentRenderer', () => {
+  let consoleWarn: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    consoleWarn.mockRestore()
+  })
+
+  describe('component not found', () => {
+    it('should return null and warn when component not found', () => {
+      render(
+        <ComponentRenderer
+          surfaceId="test-surface"
+          componentId="nonexistent"
+        />,
+        { wrapper }
+      )
+
+      expect(consoleWarn).toHaveBeenCalledWith(
+        'A2UI: Component not found: nonexistent on surface test-surface'
+      )
+    })
+  })
+
+  describe('component with no type definition', () => {
+    it('should return null and warn when component has no type', () => {
+      const components: ComponentDefinition[] = [
+        { id: 'empty-comp', component: {} },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      render(
+        <ComponentRenderer surfaceId="test-surface" componentId="empty-comp" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(consoleWarn).toHaveBeenCalledWith(
+        'A2UI: Component empty-comp has no type definition'
+      )
+    })
+  })
+
+  describe('unknown component type', () => {
+    it('should return null and warn for unknown component type', () => {
+      const components: ComponentDefinition[] = [
+        { id: 'unknown-comp', component: { UnknownType: {} } },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      render(
+        <ComponentRenderer
+          surfaceId="test-surface"
+          componentId="unknown-comp"
+        />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(consoleWarn).toHaveBeenCalledWith(
+        'A2UI: Unknown component type: UnknownType'
+      )
+    })
+  })
+
+  describe('rendering display components', () => {
+    it('should render Text component', () => {
+      const components: ComponentDefinition[] = [
+        {
+          id: 'text-1',
+          component: { Text: { text: { literalString: 'Hello World' } } },
+        },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      render(
+        <ComponentRenderer surfaceId="test-surface" componentId="text-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(screen.getByText('Hello World')).toBeInTheDocument()
+    })
+
+    it('should render Image component', () => {
+      const components: ComponentDefinition[] = [
+        {
+          id: 'image-1',
+          component: {
+            Image: { url: { literalString: 'https://example.com/image.jpg' } },
+          },
+        },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      render(
+        <ComponentRenderer surfaceId="test-surface" componentId="image-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      const img = screen.getByRole('presentation')
+      expect(img).toHaveAttribute('src', 'https://example.com/image.jpg')
+    })
+
+    it('should render Divider component', () => {
+      const components: ComponentDefinition[] = [
+        { id: 'divider-1', component: { Divider: { axis: 'horizontal' } } },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      const { container } = render(
+        <ComponentRenderer surfaceId="test-surface" componentId="divider-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(
+        container.querySelector('[data-orientation="horizontal"]')
+      ).toBeInTheDocument()
+    })
+  })
+
+  describe('rendering layout components', () => {
+    it('should render Row component', () => {
+      const components: ComponentDefinition[] = [
+        { id: 'row-1', component: { Row: { distribution: 'center' } } },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      const { container } = render(
+        <ComponentRenderer surfaceId="test-surface" componentId="row-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(container.querySelector('.flex-row')).toBeInTheDocument()
+    })
+
+    it('should render Column component', () => {
+      const components: ComponentDefinition[] = [
+        { id: 'column-1', component: { Column: { alignment: 'center' } } },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      const { container } = render(
+        <ComponentRenderer surfaceId="test-surface" componentId="column-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(container.querySelector('.flex-col')).toBeInTheDocument()
+    })
+
+    it('should render Card component', () => {
+      const components: ComponentDefinition[] = [
+        { id: 'card-1', component: { Card: {} } },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      const { container } = render(
+        <ComponentRenderer surfaceId="test-surface" componentId="card-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(container.firstChild).toBeInTheDocument()
+    })
+  })
+
+  describe('rendering interactive components', () => {
+    it('should render Button component', () => {
+      const components: ComponentDefinition[] = [
+        { id: 'button-1', component: { Button: { primary: true } } },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      render(
+        <ComponentRenderer surfaceId="test-surface" componentId="button-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(screen.getByRole('button')).toBeInTheDocument()
+    })
+
+    it('should render CheckBox component', () => {
+      const components: ComponentDefinition[] = [
+        {
+          id: 'checkbox-1',
+          component: { CheckBox: { label: { literalString: 'Accept' } } },
+        },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      render(
+        <ComponentRenderer surfaceId="test-surface" componentId="checkbox-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(screen.getByRole('checkbox')).toBeInTheDocument()
+      expect(screen.getByText('Accept')).toBeInTheDocument()
+    })
+
+    it('should render TextField component', () => {
+      const components: ComponentDefinition[] = [
+        {
+          id: 'field-1',
+          component: { TextField: { label: { literalString: 'Name' } } },
+        },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      render(
+        <ComponentRenderer surfaceId="test-surface" componentId="field-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(screen.getByRole('textbox')).toBeInTheDocument()
+      expect(screen.getByText('Name')).toBeInTheDocument()
+    })
+
+    it('should render Slider component', () => {
+      const components: ComponentDefinition[] = [
+        {
+          id: 'slider-1',
+          component: { Slider: { minValue: 0, maxValue: 100 } },
+        },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      render(
+        <ComponentRenderer surfaceId="test-surface" componentId="slider-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(screen.getByRole('slider')).toBeInTheDocument()
+    })
+  })
+
+  describe('passing props', () => {
+    it('should pass weight prop to component', () => {
+      const components: ComponentDefinition[] = [
+        {
+          id: 'text-1',
+          weight: 2,
+          component: { Text: { text: { literalString: 'Weighted' } } },
+        },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      render(
+        <ComponentRenderer surfaceId="test-surface" componentId="text-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      // Component should render (weight is passed but may not affect visual)
+      expect(screen.getByText('Weighted')).toBeInTheDocument()
+    })
+
+    it('should pass all component props', () => {
+      const components: ComponentDefinition[] = [
+        {
+          id: 'text-1',
+          component: {
+            Text: {
+              text: { literalString: 'Heading' },
+              usageHint: 'h1',
+            },
+          },
+        },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      const { container } = render(
+        <ComponentRenderer surfaceId="test-surface" componentId="text-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(container.querySelector('h1')).toBeInTheDocument()
+      expect(container.querySelector('h1')).toHaveTextContent('Heading')
+    })
+  })
+
+  describe('registerComponent', () => {
+    it('should register and render custom component', () => {
+      // Register a custom component
+      const CustomComponent = ({
+        surfaceId,
+        componentId,
+        customProp,
+      }: BaseComponentProps & { customProp?: string }) => (
+        <div data-testid="custom-component">
+          Custom: {customProp} ({surfaceId}/{componentId})
+        </div>
+      )
+
+      registerComponent('CustomWidget', CustomComponent)
+
+      const components: ComponentDefinition[] = [
+        {
+          id: 'custom-1',
+          component: { CustomWidget: { customProp: 'test-value' } },
+        },
+      ]
+      const surfaceWrapper = createSurfaceWrapper(components)
+
+      render(
+        <ComponentRenderer surfaceId="test-surface" componentId="custom-1" />,
+        { wrapper: surfaceWrapper }
+      )
+
+      expect(screen.getByTestId('custom-component')).toBeInTheDocument()
+      expect(screen.getByTestId('custom-component')).toHaveTextContent(
+        'Custom: test-value'
+      )
+    })
+  })
+
+  describe('displayName', () => {
+    it('should have correct displayName', () => {
+      expect(ComponentRenderer.displayName).toBe('A2UI.ComponentRenderer')
+    })
+  })
+})

package/src/0.8/components/ComponentRenderer.tsx

@@ -0,0 +1,163 @@
+/**
+ * ComponentRenderer - Routes component rendering based on type.
+ */
+
+import { memo, useContext, type ComponentType } from 'react'
+import type { BaseComponentProps } from '../types'
+import { useComponent } from '../hooks/useComponent'
+import { ComponentsMapContext } from '../contexts/ComponentsMapContext'
+
+// Display components
+import {
+  TextComponent,
+  ImageComponent,
+  IconComponent,
+  VideoComponent,
+  AudioPlayerComponent,
+  DividerComponent,
+} from './display'
+
+// Layout components (will be imported after creation)
+import {
+  RowComponent,
+  ColumnComponent,
+  ListComponent,
+  CardComponent,
+  TabsComponent,
+  ModalComponent,
+} from './layout'
+
+// Interactive components (will be imported after creation)
+import {
+  ButtonComponent,
+  CheckBoxComponent,
+  TextFieldComponent,
+  DateTimeInputComponent,
+  MultipleChoiceComponent,
+  SliderComponent,
+} from './interactive'
+
+/**
+ * Component registry mapping component type names to React components.
+ */
+export const componentRegistry: Record<
+  string,
+  ComponentType<BaseComponentProps & Record<string, unknown>>
+> = {
+  // Display components
+  Text: TextComponent,
+  Image: ImageComponent,
+  Icon: IconComponent,
+  Video: VideoComponent,
+  AudioPlayer: AudioPlayerComponent,
+  Divider: DividerComponent,
+
+  // Layout components
+  Row: RowComponent,
+  Column: ColumnComponent,
+  List: ListComponent,
+  Card: CardComponent,
+  Tabs: TabsComponent,
+  Modal: ModalComponent,
+
+  // Interactive components
+  Button: ButtonComponent,
+  CheckBox: CheckBoxComponent,
+  TextField: TextFieldComponent,
+  DateTimeInput: DateTimeInputComponent,
+  MultipleChoice: MultipleChoiceComponent,
+  Slider: SliderComponent,
+}
+
+/**
+ * Props for ComponentRenderer.
+ */
+export interface ComponentRendererProps {
+  surfaceId: string
+  componentId: string
+}
+
+/**
+ * Renders a component based on its type from the component registry.
+ * Supports custom component overrides via ComponentsMapContext.
+ *
+ * @example
+ * ```tsx
+ * // Render a component by ID
+ * <ComponentRenderer surfaceId="surface-1" componentId="text-1" />
+ * ```
+ */
+export const ComponentRenderer = memo(function ComponentRenderer({
+  surfaceId,
+  componentId,
+}: ComponentRendererProps) {
+  const component = useComponent(surfaceId, componentId)
+  const componentsMapContext = useContext(ComponentsMapContext)
+
+  if (!component) {
+    console.warn(
+      `A2UI: Component not found: ${componentId} on surface ${surfaceId}`
+    )
+    return null
+  }
+
+  // Extract the component type and props from the definition
+  // component.component is { [componentType]: props }
+  const entries = Object.entries(component.component)
+  if (entries.length === 0) {
+    console.warn(`A2UI: Component ${componentId} has no type definition`)
+    return null
+  }
+
+  const [componentType, props] = entries[0]
+
+  // Try to get component from context first (custom components), then fall back to registry
+  let Component:
+    | ComponentType<BaseComponentProps & Record<string, unknown>>
+    | undefined
+  if (componentsMapContext) {
+    Component = componentsMapContext.getComponent(componentType)
+  } else {
+    Component = componentRegistry[componentType]
+  }
+
+  if (!Component) {
+    // In development mode, render a placeholder for unknown components
+    // In production, skip unknown components silently
+    console.warn(`A2UI: Unknown component type: ${componentType}`)
+    return null
+  }
+
+  return (
+    // eslint-disable-next-line react-hooks/static-components
+    <Component
+      surfaceId={surfaceId}
+      componentId={componentId}
+      weight={component.weight}
+      {...(props as Record<string, unknown>)}
+    />
+  )
+})
+
+ComponentRenderer.displayName = 'A2UI.ComponentRenderer'
+
+/**
+ * Registers a custom component type.
+ *
+ * @param type - The component type name
+ * @param component - The React component to register
+ *
+ * @example
+ * ```tsx
+ * registerComponent('CustomChart', ({ surfaceId, data }) => {
+ *   const chartData = useDataBinding(surfaceId, data, []);
+ *   return <Chart data={chartData} />;
+ * });
+ * ```
+ */
+export function registerComponent(
+  type: string,
+  component: ComponentType<BaseComponentProps & Record<string, unknown>>
+): void {
+  componentRegistry[type] = component
+}