@easyops-cn/a2ui-react 0.0.0

package/src/0.8/hooks/useA2UIMessageHandler.test.tsx

@@ -0,0 +1,399 @@
+/**
+ * useA2UIMessageHandler Tests
+ *
+ * Tests for the useA2UIMessageHandler hook.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useA2UIMessageHandler } from './useA2UIMessageHandler'
+import { A2UIProvider } from '../contexts/A2UIProvider'
+import { useSurfaceContext } from '../contexts/SurfaceContext'
+import { useDataModelContext } from '../contexts/DataModelContext'
+import type { ReactNode } from 'react'
+import type { A2UIMessage } from '../types'
+
+describe('useA2UIMessageHandler', () => {
+  // Helper to render hook with provider
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <A2UIProvider>{children}</A2UIProvider>
+  )
+
+  describe('processMessage', () => {
+    it('should handle beginRendering message', () => {
+      const { result } = renderHook(
+        () => {
+          const handler = useA2UIMessageHandler()
+          const { getSurface } = useSurfaceContext()
+          const { getDataModel } = useDataModelContext()
+          return { handler, getSurface, getDataModel }
+        },
+        { wrapper }
+      )
+
+      const message: A2UIMessage = {
+        beginRendering: {
+          surfaceId: 'surface-1',
+          root: 'root-component',
+          styles: { font: 'Arial' },
+        },
+      }
+
+      act(() => {
+        result.current.handler.processMessage(message)
+      })
+
+      const surface = result.current.getSurface('surface-1')
+      expect(surface).toBeDefined()
+      expect(surface?.surfaceId).toBe('surface-1')
+      expect(surface?.root).toBe('root-component')
+      expect(surface?.styles?.font).toBe('Arial')
+
+      // Data model should be initialized
+      expect(result.current.getDataModel('surface-1')).toEqual({})
+    })
+
+    it('should handle surfaceUpdate message', () => {
+      const { result } = renderHook(
+        () => {
+          const handler = useA2UIMessageHandler()
+          const { getSurface, getComponent } = useSurfaceContext()
+          return { handler, getSurface, getComponent }
+        },
+        { wrapper }
+      )
+
+      // First init surface
+      act(() => {
+        result.current.handler.processMessage({
+          beginRendering: {
+            surfaceId: 'surface-1',
+            root: 'root',
+          },
+        })
+      })
+
+      // Then update with components
+      const message: A2UIMessage = {
+        surfaceUpdate: {
+          surfaceId: 'surface-1',
+          components: [
+            {
+              id: 'text-1',
+              component: { Text: { text: { literalString: 'Hello' } } },
+            },
+            {
+              id: 'button-1',
+              component: { Button: { action: { name: 'click' } } },
+            },
+          ],
+        },
+      }
+
+      act(() => {
+        result.current.handler.processMessage(message)
+      })
+
+      expect(result.current.getComponent('surface-1', 'text-1')).toBeDefined()
+      expect(result.current.getComponent('surface-1', 'button-1')).toBeDefined()
+    })
+
+    it('should handle surfaceUpdate before beginRendering', () => {
+      const { result } = renderHook(
+        () => {
+          const handler = useA2UIMessageHandler()
+          const { getSurface, getComponent } = useSurfaceContext()
+          return { handler, getSurface, getComponent }
+        },
+        { wrapper }
+      )
+
+      // surfaceUpdate first
+      act(() => {
+        result.current.handler.processMessage({
+          surfaceUpdate: {
+            surfaceId: 'surface-1',
+            components: [{ id: 'text-1', component: { Text: {} } }],
+          },
+        })
+      })
+
+      // Component should exist
+      expect(result.current.getComponent('surface-1', 'text-1')).toBeDefined()
+
+      // Then beginRendering
+      act(() => {
+        result.current.handler.processMessage({
+          beginRendering: {
+            surfaceId: 'surface-1',
+            root: 'text-1',
+          },
+        })
+      })
+
+      // Surface should have root set and component preserved
+      const surface = result.current.getSurface('surface-1')
+      expect(surface?.root).toBe('text-1')
+      expect(result.current.getComponent('surface-1', 'text-1')).toBeDefined()
+    })
+
+    it('should handle dataModelUpdate message', () => {
+      const { result } = renderHook(
+        () => {
+          const handler = useA2UIMessageHandler()
+          const { getDataValue } = useDataModelContext()
+          return { handler, getDataValue }
+        },
+        { wrapper }
+      )
+
+      // Init surface first
+      act(() => {
+        result.current.handler.processMessage({
+          beginRendering: {
+            surfaceId: 'surface-1',
+            root: 'root',
+          },
+        })
+      })
+
+      // Update data model
+      const message: A2UIMessage = {
+        dataModelUpdate: {
+          surfaceId: 'surface-1',
+          path: '/',
+          contents: [
+            { key: 'name', valueString: 'John' },
+            { key: 'age', valueNumber: 30 },
+            { key: 'active', valueBoolean: true },
+          ],
+        },
+      }
+
+      act(() => {
+        result.current.handler.processMessage(message)
+      })
+
+      expect(result.current.getDataValue('surface-1', '/name')).toBe('John')
+      expect(result.current.getDataValue('surface-1', '/age')).toBe(30)
+      expect(result.current.getDataValue('surface-1', '/active')).toBe(true)
+    })
+
+    it('should handle dataModelUpdate with nested path', () => {
+      const { result } = renderHook(
+        () => {
+          const handler = useA2UIMessageHandler()
+          const { getDataValue } = useDataModelContext()
+          return { handler, getDataValue }
+        },
+        { wrapper }
+      )
+
+      act(() => {
+        result.current.handler.processMessage({
+          beginRendering: { surfaceId: 'surface-1', root: 'root' },
+        })
+      })
+
+      act(() => {
+        result.current.handler.processMessage({
+          dataModelUpdate: {
+            surfaceId: 'surface-1',
+            path: '/user',
+            contents: [
+              { key: 'name', valueString: 'John' },
+              { key: 'email', valueString: 'john@example.com' },
+            ],
+          },
+        })
+      })
+
+      expect(result.current.getDataValue('surface-1', '/user/name')).toBe(
+        'John'
+      )
+      expect(result.current.getDataValue('surface-1', '/user/email')).toBe(
+        'john@example.com'
+      )
+    })
+
+    it('should handle dataModelUpdate with default path', () => {
+      const { result } = renderHook(
+        () => {
+          const handler = useA2UIMessageHandler()
+          const { getDataValue } = useDataModelContext()
+          return { handler, getDataValue }
+        },
+        { wrapper }
+      )
+
+      act(() => {
+        result.current.handler.processMessage({
+          beginRendering: { surfaceId: 'surface-1', root: 'root' },
+        })
+      })
+
+      // No path specified - should default to '/'
+      act(() => {
+        result.current.handler.processMessage({
+          dataModelUpdate: {
+            surfaceId: 'surface-1',
+            contents: [{ key: 'name', valueString: 'John' }],
+          },
+        })
+      })
+
+      expect(result.current.getDataValue('surface-1', '/name')).toBe('John')
+    })
+
+    it('should handle deleteSurface message', () => {
+      const { result } = renderHook(
+        () => {
+          const handler = useA2UIMessageHandler()
+          const { getSurface } = useSurfaceContext()
+          const { getDataModel } = useDataModelContext()
+          return { handler, getSurface, getDataModel }
+        },
+        { wrapper }
+      )
+
+      // Create surface
+      act(() => {
+        result.current.handler.processMessage({
+          beginRendering: { surfaceId: 'surface-1', root: 'root' },
+        })
+        result.current.handler.processMessage({
+          dataModelUpdate: {
+            surfaceId: 'surface-1',
+            contents: [{ key: 'name', valueString: 'John' }],
+          },
+        })
+      })
+
+      expect(result.current.getSurface('surface-1')).toBeDefined()
+
+      // Delete surface
+      act(() => {
+        result.current.handler.processMessage({
+          deleteSurface: { surfaceId: 'surface-1' },
+        })
+      })
+
+      expect(result.current.getSurface('surface-1')).toBeUndefined()
+      expect(result.current.getDataModel('surface-1')).toEqual({})
+    })
+
+    it('should handle empty message gracefully', () => {
+      const { result } = renderHook(() => useA2UIMessageHandler(), { wrapper })
+
+      // Should not throw
+      expect(() => {
+        act(() => {
+          result.current.processMessage({} as A2UIMessage)
+        })
+      }).not.toThrow()
+    })
+  })
+
+  describe('processMessages', () => {
+    it('should process multiple messages in order', () => {
+      const { result } = renderHook(
+        () => {
+          const handler = useA2UIMessageHandler()
+          const { getSurface, getComponent } = useSurfaceContext()
+          const { getDataValue } = useDataModelContext()
+          return { handler, getSurface, getComponent, getDataValue }
+        },
+        { wrapper }
+      )
+
+      const messages: A2UIMessage[] = [
+        {
+          beginRendering: { surfaceId: 'surface-1', root: 'root' },
+        },
+        {
+          surfaceUpdate: {
+            surfaceId: 'surface-1',
+            components: [{ id: 'text-1', component: { Text: {} } }],
+          },
+        },
+        {
+          dataModelUpdate: {
+            surfaceId: 'surface-1',
+            contents: [{ key: 'name', valueString: 'John' }],
+          },
+        },
+      ]
+
+      act(() => {
+        result.current.handler.processMessages(messages)
+      })
+
+      expect(result.current.getSurface('surface-1')).toBeDefined()
+      expect(result.current.getComponent('surface-1', 'text-1')).toBeDefined()
+      expect(result.current.getDataValue('surface-1', '/name')).toBe('John')
+    })
+
+    it('should handle empty messages array', () => {
+      const { result } = renderHook(() => useA2UIMessageHandler(), { wrapper })
+
+      expect(() => {
+        act(() => {
+          result.current.processMessages([])
+        })
+      }).not.toThrow()
+    })
+  })
+
+  describe('clear', () => {
+    it('should clear all surfaces and data models', () => {
+      const { result } = renderHook(
+        () => {
+          const handler = useA2UIMessageHandler()
+          const { surfaces } = useSurfaceContext()
+          const { dataModels } = useDataModelContext()
+          return { handler, surfaces, dataModels }
+        },
+        { wrapper }
+      )
+
+      // Create multiple surfaces
+      act(() => {
+        result.current.handler.processMessages([
+          { beginRendering: { surfaceId: 'surface-1', root: 'root' } },
+          { beginRendering: { surfaceId: 'surface-2', root: 'root' } },
+          {
+            dataModelUpdate: {
+              surfaceId: 'surface-1',
+              contents: [{ key: 'name', valueString: 'John' }],
+            },
+          },
+        ])
+      })
+
+      expect(result.current.surfaces.size).toBe(2)
+      expect(result.current.dataModels.size).toBe(2)
+
+      // Clear all
+      act(() => {
+        result.current.handler.clear()
+      })
+
+      expect(result.current.surfaces.size).toBe(0)
+      expect(result.current.dataModels.size).toBe(0)
+    })
+  })
+
+  describe('error handling', () => {
+    it('should throw error when used outside provider', () => {
+      const consoleError = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {})
+
+      expect(() => {
+        renderHook(() => useA2UIMessageHandler())
+      }).toThrow()
+
+      consoleError.mockRestore()
+    })
+  })
+})

package/src/0.8/hooks/useA2UIMessageHandler.ts

@@ -0,0 +1,123 @@
+/**
+ * useA2UIMessageHandler - Hook for processing A2UI messages.
+ */
+
+import { useCallback } from 'react'
+import type { A2UIMessage } from '../types'
+import { useSurfaceContext } from '../contexts/SurfaceContext'
+import { useDataModelContext } from '../contexts/DataModelContext'
+import { contentsToObject } from '../utils/dataBinding'
+
+/**
+ * Return type for the message handler hook.
+ */
+export interface A2UIMessageHandler {
+  /** Processes a single A2UI message */
+  processMessage: (message: A2UIMessage) => void
+
+  /** Processes multiple A2UI messages */
+  processMessages: (messages: A2UIMessage[]) => void
+
+  /** Clears all surfaces and data models */
+  clear: () => void
+}
+
+/**
+ * Hook that returns functions to process A2UI messages.
+ *
+ * @returns Object with processMessage, processMessages, and clear functions
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { processMessage, processMessages, clear } = useA2UIMessageHandler();
+ *
+ *   useEffect(() => {
+ *     // Process initial messages
+ *     processMessages(initialMessages);
+ *
+ *     // Listen for SSE updates
+ *     const handler = (event) => {
+ *       processMessage(event.detail.message);
+ *     };
+ *     window.addEventListener('a2ui-message', handler);
+ *
+ *     return () => {
+ *       window.removeEventListener('a2ui-message', handler);
+ *       clear();
+ *     };
+ *   }, []);
+ * }
+ * ```
+ */
+export function useA2UIMessageHandler(): A2UIMessageHandler {
+  const { initSurface, updateSurface, deleteSurface, clearSurfaces } =
+    useSurfaceContext()
+
+  const { updateDataModel, initDataModel, deleteDataModel, clearDataModels } =
+    useDataModelContext()
+
+  const processMessage = useCallback(
+    (messages: A2UIMessage) => {
+      // Handle beginRendering - marks the surface as ready to render
+      // Note: surfaceUpdate may have already populated components before this
+      if (messages.beginRendering) {
+        const { surfaceId, root, styles } = messages.beginRendering
+        initSurface(surfaceId, root, styles)
+        initDataModel(surfaceId)
+        return
+      }
+
+      // Handle surfaceUpdate
+      if (messages.surfaceUpdate) {
+        const { surfaceId, components } = messages.surfaceUpdate
+        updateSurface(surfaceId, components)
+        return
+      }
+
+      // Handle dataModelUpdate
+      if (messages.dataModelUpdate) {
+        const { surfaceId, path = '/', contents } = messages.dataModelUpdate
+        const data = contentsToObject(contents)
+        updateDataModel(surfaceId, path, data)
+        return
+      }
+
+      // Handle deleteSurface
+      if (messages.deleteSurface) {
+        const { surfaceId } = messages.deleteSurface
+        deleteSurface(surfaceId)
+        deleteDataModel(surfaceId)
+        return
+      }
+    },
+    [
+      initSurface,
+      updateSurface,
+      deleteSurface,
+      initDataModel,
+      updateDataModel,
+      deleteDataModel,
+    ]
+  )
+
+  const processMessages = useCallback(
+    (messages: A2UIMessage[]) => {
+      for (const message of messages) {
+        processMessage(message)
+      }
+    },
+    [processMessage]
+  )
+
+  const clear = useCallback(() => {
+    clearSurfaces()
+    clearDataModels()
+  }, [clearSurfaces, clearDataModels])
+
+  return {
+    processMessage,
+    processMessages,
+    clear,
+  }
+}

package/src/0.8/hooks/useComponent.test.tsx

@@ -0,0 +1,148 @@
+/**
+ * useComponent Tests
+ *
+ * Tests for the useComponent hook.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useComponent } from './useComponent'
+import { SurfaceProvider, useSurfaceContext } from '../contexts/SurfaceContext'
+import type { ReactNode } from 'react'
+import type { ComponentDefinition } from '../types'
+
+describe('useComponent', () => {
+  // Helper to render hook with provider
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <SurfaceProvider>{children}</SurfaceProvider>
+  )
+
+  it('should return undefined for non-existent surface', () => {
+    const { result } = renderHook(
+      () => useComponent('non-existent', 'comp-1'),
+      { wrapper }
+    )
+    expect(result.current).toBeUndefined()
+  })
+
+  it('should return undefined for non-existent component', () => {
+    const { result } = renderHook(
+      () => {
+        const component = useComponent('test-surface', 'non-existent')
+        const { initSurface } = useSurfaceContext()
+        return { component, initSurface }
+      },
+      { wrapper }
+    )
+
+    act(() => {
+      result.current.initSurface('test-surface', 'root')
+    })
+
+    expect(result.current.component).toBeUndefined()
+  })
+
+  it('should return component when it exists', () => {
+    const testComponent: ComponentDefinition = {
+      id: 'text-1',
+      component: { Text: { text: { literalString: 'Hello' } } },
+    }
+
+    const { result } = renderHook(
+      () => {
+        const component = useComponent('test-surface', 'text-1')
+        const { initSurface, updateSurface } = useSurfaceContext()
+        return { component, initSurface, updateSurface }
+      },
+      { wrapper }
+    )
+
+    act(() => {
+      result.current.initSurface('test-surface', 'root')
+      result.current.updateSurface('test-surface', [testComponent])
+    })
+
+    expect(result.current.component).toEqual(testComponent)
+  })
+
+  it('should update when component changes', () => {
+    const { result } = renderHook(
+      () => {
+        const component = useComponent('test-surface', 'text-1')
+        const { initSurface, updateSurface } = useSurfaceContext()
+        return { component, initSurface, updateSurface }
+      },
+      { wrapper }
+    )
+
+    act(() => {
+      result.current.initSurface('test-surface', 'root')
+      result.current.updateSurface('test-surface', [
+        {
+          id: 'text-1',
+          component: { Text: { text: { literalString: 'Hello' } } },
+        },
+      ])
+    })
+
+    expect(result.current.component?.component.Text?.text).toEqual({
+      literalString: 'Hello',
+    })
+
+    // Update component
+    act(() => {
+      result.current.updateSurface('test-surface', [
+        {
+          id: 'text-1',
+          component: { Text: { text: { literalString: 'Updated' } } },
+        },
+      ])
+    })
+
+    expect(result.current.component?.component.Text?.text).toEqual({
+      literalString: 'Updated',
+    })
+  })
+
+  it('should memoize result based on surfaceId and componentId', () => {
+    const { result, rerender } = renderHook(
+      ({ surfaceId, componentId }) => {
+        const component = useComponent(surfaceId, componentId)
+        const { initSurface, updateSurface } = useSurfaceContext()
+        return { component, initSurface, updateSurface }
+      },
+      {
+        wrapper,
+        initialProps: { surfaceId: 'surface-1', componentId: 'comp-1' },
+      }
+    )
+
+    act(() => {
+      result.current.initSurface('surface-1', 'root')
+      result.current.updateSurface('surface-1', [
+        { id: 'comp-1', component: { Text: { text: { literalString: 'A' } } } },
+        { id: 'comp-2', component: { Text: { text: { literalString: 'B' } } } },
+      ])
+    })
+
+    expect(result.current.component?.component.Text?.text).toEqual({
+      literalString: 'A',
+    })
+
+    // Change componentId
+    rerender({ surfaceId: 'surface-1', componentId: 'comp-2' })
+    expect(result.current.component?.component.Text?.text).toEqual({
+      literalString: 'B',
+    })
+  })
+
+  it('should throw error when used outside provider', () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    expect(() => {
+      renderHook(() => useComponent('test', 'comp'))
+    }).toThrow('useSurfaceContext must be used within a SurfaceProvider')
+
+    consoleError.mockRestore()
+  })
+})

package/src/0.8/hooks/useComponent.ts

@@ -0,0 +1,39 @@
+/**
+ * useComponent - Hook to get a component from a Surface.
+ */
+
+import { useMemo } from 'react'
+import type { ComponentDefinition } from '../types'
+import { useSurfaceContext } from '../contexts/SurfaceContext'
+
+/**
+ * Gets a component from a Surface by its ID.
+ *
+ * @param surfaceId - The surface ID
+ * @param componentId - The component ID to look up
+ * @returns The ComponentDefinition, or undefined if not found
+ *
+ * @example
+ * ```tsx
+ * function MyComponent({ surfaceId, componentId }) {
+ *   const component = useComponent(surfaceId, componentId);
+ *
+ *   if (!component) {
+ *     return null;
+ *   }
+ *
+ *   const [type, props] = Object.entries(component.component)[0];
+ *   // Render based on type...
+ * }
+ * ```
+ */
+export function useComponent(
+  surfaceId: string,
+  componentId: string
+): ComponentDefinition | undefined {
+  const { getComponent } = useSurfaceContext()
+
+  return useMemo(() => {
+    return getComponent(surfaceId, componentId)
+  }, [getComponent, surfaceId, componentId])
+}