@easyops-cn/a2ui-react 0.0.0

package/src/0.8/contexts/A2UIProvider.test.tsx

@@ -0,0 +1,226 @@
+/**
+ * A2UIProvider Tests
+ *
+ * Tests for the combined A2UI provider component.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, act } from '@testing-library/react'
+import { renderHook } from '@testing-library/react'
+import { A2UIProvider } from './A2UIProvider'
+import { useSurfaceContext } from './SurfaceContext'
+import { useDataModelContext } from './DataModelContext'
+import { useActionContext } from './ActionContext'
+import type { ReactNode } from 'react'
+
+describe('A2UIProvider', () => {
+  describe('rendering', () => {
+    it('should render children', () => {
+      render(
+        <A2UIProvider>
+          <div data-testid="child">Child content</div>
+        </A2UIProvider>
+      )
+      expect(screen.getByTestId('child')).toBeInTheDocument()
+    })
+  })
+
+  describe('context availability', () => {
+    // Wrapper for hooks
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <A2UIProvider>{children}</A2UIProvider>
+    )
+
+    it('should provide SurfaceContext', () => {
+      const { result } = renderHook(() => useSurfaceContext(), { wrapper })
+      expect(result.current).toBeDefined()
+      expect(result.current.surfaces).toBeInstanceOf(Map)
+      expect(result.current.initSurface).toBeDefined()
+    })
+
+    it('should provide DataModelContext', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+      expect(result.current).toBeDefined()
+      expect(result.current.dataModels).toBeInstanceOf(Map)
+      expect(result.current.setDataValue).toBeDefined()
+    })
+
+    it('should provide ActionContext', () => {
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+      expect(result.current).toBeDefined()
+      expect(result.current.dispatchAction).toBeDefined()
+    })
+  })
+
+  describe('onAction prop', () => {
+    it('should pass onAction to ActionProvider', () => {
+      const onAction = vi.fn()
+
+      const wrapper = ({ children }: { children: ReactNode }) => (
+        <A2UIProvider onAction={onAction}>{children}</A2UIProvider>
+      )
+
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+
+      act(() => {
+        result.current.dispatchAction('surface-1', 'button-1', {
+          name: 'test',
+        })
+      })
+
+      expect(onAction).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: 'test',
+          surfaceId: 'surface-1',
+          sourceComponentId: 'button-1',
+        })
+      )
+    })
+
+    it('should work without onAction prop', () => {
+      const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+      const wrapper = ({ children }: { children: ReactNode }) => (
+        <A2UIProvider>{children}</A2UIProvider>
+      )
+
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+
+      // Should not throw
+      expect(() => {
+        act(() => {
+          result.current.dispatchAction('surface-1', 'button-1', {
+            name: 'test',
+          })
+        })
+      }).not.toThrow()
+
+      consoleWarn.mockRestore()
+    })
+  })
+
+  describe('integration', () => {
+    it('should allow interaction between contexts', () => {
+      const onAction = vi.fn()
+
+      // Test component that uses all contexts
+      function TestComponent() {
+        const { initSurface, updateSurface, getSurface } = useSurfaceContext()
+        const { setDataValue, getDataValue } = useDataModelContext()
+        const { dispatchAction } = useActionContext()
+
+        return (
+          <div>
+            <button
+              onClick={() => {
+                initSurface('test-surface', 'root')
+                updateSurface('test-surface', [
+                  { id: 'text-1', component: { Text: {} } },
+                ])
+              }}
+            >
+              Init Surface
+            </button>
+            <button
+              onClick={() => {
+                setDataValue('test-surface', '/name', 'John')
+              }}
+            >
+              Set Data
+            </button>
+            <button
+              onClick={() => {
+                dispatchAction('test-surface', 'button-1', {
+                  name: 'submit',
+                  context: [{ key: 'name', value: { path: '/name' } }],
+                })
+              }}
+            >
+              Dispatch Action
+            </button>
+            <span data-testid="surface-exists">
+              {getSurface('test-surface') ? 'yes' : 'no'}
+            </span>
+            <span data-testid="data-value">
+              {String(getDataValue('test-surface', '/name') ?? 'none')}
+            </span>
+          </div>
+        )
+      }
+
+      render(
+        <A2UIProvider onAction={onAction}>
+          <TestComponent />
+        </A2UIProvider>
+      )
+
+      // Initially no surface
+      expect(screen.getByTestId('surface-exists').textContent).toBe('no')
+      expect(screen.getByTestId('data-value').textContent).toBe('none')
+
+      // Init surface
+      act(() => {
+        screen.getByText('Init Surface').click()
+      })
+      expect(screen.getByTestId('surface-exists').textContent).toBe('yes')
+
+      // Set data
+      act(() => {
+        screen.getByText('Set Data').click()
+      })
+      expect(screen.getByTestId('data-value').textContent).toBe('John')
+
+      // Dispatch action
+      act(() => {
+        screen.getByText('Dispatch Action').click()
+      })
+      expect(onAction).toHaveBeenCalledWith({
+        surfaceId: 'test-surface',
+        name: 'submit',
+        context: { name: 'John' },
+        sourceComponentId: 'button-1',
+      })
+    })
+
+    it('should maintain separate data for multiple surfaces', () => {
+      function TestComponent() {
+        const { initSurface } = useSurfaceContext()
+        const { setDataValue, getDataValue } = useDataModelContext()
+
+        return (
+          <div>
+            <button
+              onClick={() => {
+                initSurface('surface-1', 'root')
+                initSurface('surface-2', 'root')
+                setDataValue('surface-1', '/name', 'John')
+                setDataValue('surface-2', '/name', 'Jane')
+              }}
+            >
+              Setup
+            </button>
+            <span data-testid="surface-1-name">
+              {String(getDataValue('surface-1', '/name') ?? '')}
+            </span>
+            <span data-testid="surface-2-name">
+              {String(getDataValue('surface-2', '/name') ?? '')}
+            </span>
+          </div>
+        )
+      }
+
+      render(
+        <A2UIProvider>
+          <TestComponent />
+        </A2UIProvider>
+      )
+
+      act(() => {
+        screen.getByText('Setup').click()
+      })
+
+      expect(screen.getByTestId('surface-1-name').textContent).toBe('John')
+      expect(screen.getByTestId('surface-2-name').textContent).toBe('Jane')
+    })
+  })
+})

package/src/0.8/contexts/A2UIProvider.tsx

@@ -0,0 +1,54 @@
+/**
+ * A2UIProvider - Combined provider for all A2UI contexts.
+ *
+ * This component wraps all the necessary context providers for A2UI rendering.
+ * It should be placed at the top level of any component tree that uses A2UI.
+ */
+
+import { type ReactNode } from 'react'
+import { SurfaceProvider } from './SurfaceContext'
+import { DataModelProvider } from './DataModelContext'
+import { ActionProvider } from './ActionContext'
+import type { ActionHandler } from '../types'
+
+/**
+ * Props for A2UIProvider.
+ */
+export interface A2UIProviderProps {
+  /** Callback when an action is dispatched */
+  onAction?: ActionHandler
+  children: ReactNode
+}
+
+/**
+ * Combined provider for all A2UI contexts.
+ *
+ * Provides:
+ * - SurfaceContext: Component tree management
+ * - DataModelContext: Data model state
+ * - ActionContext: Action dispatching
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const handleAction = (action) => {
+ *     console.log('Action:', action);
+ *   };
+ *
+ *   return (
+ *     <A2UIProvider onAction={handleAction}>
+ *       <A2UIReactRenderer messages={messages} />
+ *     </A2UIProvider>
+ *   );
+ * }
+ * ```
+ */
+export function A2UIProvider({ onAction, children }: A2UIProviderProps) {
+  return (
+    <SurfaceProvider>
+      <DataModelProvider>
+        <ActionProvider onAction={onAction}>{children}</ActionProvider>
+      </DataModelProvider>
+    </SurfaceProvider>
+  )
+}

package/src/0.8/contexts/ActionContext.test.tsx

@@ -0,0 +1,242 @@
+/**
+ * ActionContext Tests
+ *
+ * Tests for the Action context provider and hook.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, act } from '@testing-library/react'
+import { renderHook } from '@testing-library/react'
+import { ActionProvider, useActionContext } from './ActionContext'
+import { DataModelProvider, useDataModelContext } from './DataModelContext'
+import type { ReactNode } from 'react'
+import type { Action, ActionPayload } from '../types'
+
+describe('ActionContext', () => {
+  // Helper to render hook with providers
+  const createWrapper =
+    (onAction?: (action: ActionPayload) => void) =>
+    ({ children }: { children: ReactNode }) => (
+      <DataModelProvider>
+        <ActionProvider onAction={onAction}>{children}</ActionProvider>
+      </DataModelProvider>
+    )
+
+  describe('ActionProvider', () => {
+    it('should render children', () => {
+      render(
+        <DataModelProvider>
+          <ActionProvider>
+            <div data-testid="child">Child content</div>
+          </ActionProvider>
+        </DataModelProvider>
+      )
+      expect(screen.getByTestId('child')).toBeInTheDocument()
+    })
+
+    it('should provide context value', () => {
+      const wrapper = createWrapper()
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+      expect(result.current).toBeDefined()
+      expect(result.current.dispatchAction).toBeDefined()
+    })
+  })
+
+  describe('useActionContext', () => {
+    it('should throw error when used outside provider', () => {
+      const consoleError = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {})
+
+      expect(() => {
+        renderHook(() => useActionContext())
+      }).toThrow('useActionContext must be used within an ActionProvider')
+
+      consoleError.mockRestore()
+    })
+  })
+
+  describe('dispatchAction', () => {
+    it('should call onAction with resolved payload', () => {
+      const onAction = vi.fn()
+      const wrapper = createWrapper(onAction)
+
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+
+      const action: Action = {
+        name: 'submit',
+        context: [{ key: 'type', value: { literalString: 'form' } }],
+      }
+
+      act(() => {
+        result.current.dispatchAction('surface-1', 'button-1', action)
+      })
+
+      expect(onAction).toHaveBeenCalledWith({
+        surfaceId: 'surface-1',
+        name: 'submit',
+        context: { type: 'form' },
+        sourceComponentId: 'button-1',
+      })
+    })
+
+    it('should resolve path references from data model', () => {
+      const onAction = vi.fn()
+
+      // Custom wrapper that sets up data model
+      const TestWrapper = ({ children }: { children: ReactNode }) => {
+        return (
+          <DataModelProvider>
+            <DataModelSetup>
+              <ActionProvider onAction={onAction}>{children}</ActionProvider>
+            </DataModelSetup>
+          </DataModelProvider>
+        )
+      }
+
+      // Component to set up data model
+      function DataModelSetup({ children }: { children: ReactNode }) {
+        const { setDataValue } = useDataModelContext()
+        React.useEffect(() => {
+          setDataValue('surface-1', '/form/name', 'John')
+          setDataValue('surface-1', '/form/age', 30)
+        }, [setDataValue])
+        return <>{children}</>
+      }
+
+      const { result } = renderHook(() => useActionContext(), {
+        wrapper: TestWrapper,
+      })
+
+      const action: Action = {
+        name: 'submit',
+        context: [
+          { key: 'userName', value: { path: '/form/name' } },
+          { key: 'userAge', value: { path: '/form/age' } },
+        ],
+      }
+
+      act(() => {
+        result.current.dispatchAction('surface-1', 'button-1', action)
+      })
+
+      expect(onAction).toHaveBeenCalledWith({
+        surfaceId: 'surface-1',
+        name: 'submit',
+        context: { userName: 'John', userAge: 30 },
+        sourceComponentId: 'button-1',
+      })
+    })
+
+    it('should handle action without context', () => {
+      const onAction = vi.fn()
+      const wrapper = createWrapper(onAction)
+
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+
+      const action: Action = {
+        name: 'cancel',
+      }
+
+      act(() => {
+        result.current.dispatchAction('surface-1', 'button-1', action)
+      })
+
+      expect(onAction).toHaveBeenCalledWith({
+        surfaceId: 'surface-1',
+        name: 'cancel',
+        context: {},
+        sourceComponentId: 'button-1',
+      })
+    })
+
+    it('should handle empty context array', () => {
+      const onAction = vi.fn()
+      const wrapper = createWrapper(onAction)
+
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+
+      const action: Action = {
+        name: 'reset',
+        context: [],
+      }
+
+      act(() => {
+        result.current.dispatchAction('surface-1', 'button-1', action)
+      })
+
+      expect(onAction).toHaveBeenCalledWith({
+        surfaceId: 'surface-1',
+        name: 'reset',
+        context: {},
+        sourceComponentId: 'button-1',
+      })
+    })
+
+    it('should warn when no handler is registered', () => {
+      const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      const wrapper = createWrapper() // No onAction
+
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+
+      const action: Action = {
+        name: 'submit',
+      }
+
+      act(() => {
+        result.current.dispatchAction('surface-1', 'button-1', action)
+      })
+
+      expect(consoleWarn).toHaveBeenCalledWith(
+        'A2UI: Action dispatched but no handler is registered'
+      )
+
+      consoleWarn.mockRestore()
+    })
+
+    it('should resolve literal values correctly', () => {
+      const onAction = vi.fn()
+      const wrapper = createWrapper(onAction)
+
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+
+      const action: Action = {
+        name: 'test',
+        context: [
+          { key: 'str', value: { literalString: 'hello' } },
+          { key: 'num', value: { literalNumber: 42 } },
+          { key: 'bool', value: { literalBoolean: true } },
+        ],
+      }
+
+      act(() => {
+        result.current.dispatchAction('surface-1', 'button-1', action)
+      })
+
+      expect(onAction).toHaveBeenCalledWith({
+        surfaceId: 'surface-1',
+        name: 'test',
+        context: { str: 'hello', num: 42, bool: true },
+        sourceComponentId: 'button-1',
+      })
+    })
+  })
+
+  describe('onAction property', () => {
+    it('should return null when no handler is registered', () => {
+      const wrapper = createWrapper()
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+      expect(result.current.onAction).toBeNull()
+    })
+
+    it('should return handler when registered', () => {
+      const handler = vi.fn()
+      const wrapper = createWrapper(handler)
+      const { result } = renderHook(() => useActionContext(), { wrapper })
+      expect(result.current.onAction).toBe(handler)
+    })
+  })
+})
+
+// Import React for the test component
+import React from 'react'

package/src/0.8/contexts/ActionContext.tsx

@@ -0,0 +1,105 @@
+/**
+ * ActionContext - Manages action dispatching for A2UI components.
+ *
+ * Actions are triggered by user interactions (button clicks, form changes, etc.)
+ * and are forwarded to the parent application for handling.
+ */
+
+import {
+  createContext,
+  useContext,
+  useMemo,
+  useCallback,
+  type ReactNode,
+} from 'react'
+import type { Action, ActionPayload, ActionHandler } from '../types'
+import { useDataModelContext } from './DataModelContext'
+import { resolveActionContext } from '../utils/dataBinding'
+
+/**
+ * Action context value interface.
+ */
+export interface ActionContextValue {
+  /** Dispatches an action with resolved context */
+  dispatchAction: (
+    surfaceId: string,
+    componentId: string,
+    action: Action
+  ) => void
+
+  /** The action handler callback (if set) */
+  onAction: ActionHandler | null
+}
+
+/**
+ * Action context for A2UI rendering.
+ */
+export const ActionContext = createContext<ActionContextValue | null>(null)
+
+/**
+ * Props for ActionProvider.
+ */
+export interface ActionProviderProps {
+  /** Callback when an action is dispatched */
+  onAction?: ActionHandler
+  children: ReactNode
+}
+
+/**
+ * Provider component for Action dispatching.
+ */
+export function ActionProvider({ onAction, children }: ActionProviderProps) {
+  const { getDataModel } = useDataModelContext()
+
+  const dispatchAction = useCallback(
+    (surfaceId: string, componentId: string, action: Action) => {
+      if (!onAction) {
+        console.warn('A2UI: Action dispatched but no handler is registered')
+        return
+      }
+
+      // Get the data model for this surface
+      const dataModel = getDataModel(surfaceId)
+
+      // Resolve the action context values
+      const resolvedContext = resolveActionContext(action.context, dataModel)
+
+      // Create the action payload
+      const payload: ActionPayload = {
+        surfaceId,
+        name: action.name,
+        context: resolvedContext,
+        sourceComponentId: componentId,
+      }
+
+      // Call the handler
+      onAction(payload)
+    },
+    [onAction, getDataModel]
+  )
+
+  const value = useMemo<ActionContextValue>(
+    () => ({
+      dispatchAction,
+      onAction: onAction ?? null,
+    }),
+    [dispatchAction, onAction]
+  )
+
+  return (
+    <ActionContext.Provider value={value}>{children}</ActionContext.Provider>
+  )
+}
+
+/**
+ * Hook to access the Action context.
+ *
+ * @throws Error if used outside of ActionProvider
+ */
+export function useActionContext(): ActionContextValue {
+  const context = useContext(ActionContext)
+  if (!context) {
+    throw new Error('useActionContext must be used within an ActionProvider')
+  }
+  return context
+}