@easyops-cn/a2ui-react 0.0.0

package/src/0.8/contexts/ComponentsMapContext.tsx

@@ -0,0 +1,125 @@
+/**
+ * ComponentsMapContext - Context for custom component overrides.
+ *
+ * This context allows users to provide custom component implementations
+ * that override or extend the default component registry.
+ */
+
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ReactNode,
+  type ComponentType,
+} from 'react'
+import type { BaseComponentProps } from '../types'
+
+/**
+ * Type for a component in the components map.
+ */
+export type A2UIComponent = ComponentType<
+  BaseComponentProps & Record<string, unknown>
+>
+
+/**
+ * Map of component type names to React components.
+ */
+export type ComponentsMap = Map<string, A2UIComponent>
+
+/**
+ * Context value for ComponentsMapContext.
+ */
+export interface ComponentsMapContextValue {
+  /** Custom components provided by the user */
+  customComponents: ComponentsMap
+  /** Get a component by type name (custom first, then default) */
+  getComponent: (type: string) => A2UIComponent | undefined
+}
+
+/**
+ * Context for custom component overrides.
+ */
+export const ComponentsMapContext =
+  createContext<ComponentsMapContextValue | null>(null)
+
+/**
+ * Props for ComponentsMapProvider.
+ */
+export interface ComponentsMapProviderProps {
+  /** Custom components to override or extend defaults */
+  components?: ComponentsMap
+  /** Default component registry */
+  defaultComponents: Record<string, A2UIComponent>
+  children: ReactNode
+}
+
+/**
+ * Provider for custom component overrides.
+ *
+ * @example
+ * ```tsx
+ * const customComponents = new Map([
+ *   ['Button', CustomButton],
+ *   ['Switch', CustomSwitch],
+ * ])
+ *
+ * <ComponentsMapProvider components={customComponents} defaultComponents={defaultRegistry}>
+ *   <App />
+ * </ComponentsMapProvider>
+ * ```
+ */
+export function ComponentsMapProvider({
+  components,
+  defaultComponents,
+  children,
+}: ComponentsMapProviderProps) {
+  const value = useMemo<ComponentsMapContextValue>(() => {
+    const customComponents = components ?? new Map()
+
+    const getComponent = (type: string): A2UIComponent | undefined => {
+      // Custom components take precedence over defaults
+      if (customComponents.has(type)) {
+        return customComponents.get(type)
+      }
+      return defaultComponents[type]
+    }
+
+    return {
+      customComponents,
+      getComponent,
+    }
+  }, [components, defaultComponents])
+
+  return (
+    <ComponentsMapContext.Provider value={value}>
+      {children}
+    </ComponentsMapContext.Provider>
+  )
+}
+
+/**
+ * Hook to access the ComponentsMap context.
+ *
+ * @throws Error if used outside of ComponentsMapProvider
+ */
+export function useComponentsMapContext(): ComponentsMapContextValue {
+  const context = useContext(ComponentsMapContext)
+  if (!context) {
+    throw new Error(
+      'useComponentsMapContext must be used within a ComponentsMapProvider'
+    )
+  }
+  return context
+}
+
+/**
+ * Hook to get a component by type name.
+ * Returns custom component if available, otherwise default.
+ *
+ * @param type - The component type name
+ * @returns The component or undefined if not found
+ */
+export function useComponentFromMap(type: string): A2UIComponent | undefined {
+  const { getComponent } = useComponentsMapContext()
+  return getComponent(type)
+}

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

@@ -0,0 +1,335 @@
+/**
+ * DataModelContext Tests
+ *
+ * Tests for the DataModel 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 { DataModelProvider, useDataModelContext } from './DataModelContext'
+import type { ReactNode } from 'react'
+
+describe('DataModelContext', () => {
+  // Helper to render hook with provider
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <DataModelProvider>{children}</DataModelProvider>
+  )
+
+  describe('DataModelProvider', () => {
+    it('should render children', () => {
+      render(
+        <DataModelProvider>
+          <div data-testid="child">Child content</div>
+        </DataModelProvider>
+      )
+      expect(screen.getByTestId('child')).toBeInTheDocument()
+    })
+
+    it('should provide context value', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+      expect(result.current).toBeDefined()
+      expect(result.current.dataModels).toBeInstanceOf(Map)
+    })
+  })
+
+  describe('useDataModelContext', () => {
+    it('should throw error when used outside provider', () => {
+      const consoleError = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {})
+
+      expect(() => {
+        renderHook(() => useDataModelContext())
+      }).toThrow('useDataModelContext must be used within a DataModelProvider')
+
+      consoleError.mockRestore()
+    })
+  })
+
+  describe('initDataModel', () => {
+    it('should initialize empty data model for surface', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+      })
+
+      expect(result.current.getDataModel('surface-1')).toEqual({})
+    })
+
+    it('should not overwrite existing data model', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+        result.current.setDataValue('surface-1', '/name', 'John')
+      })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+      })
+
+      expect(result.current.getDataValue('surface-1', '/name')).toBe('John')
+    })
+
+    it('should initialize multiple surfaces independently', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+        result.current.initDataModel('surface-2')
+      })
+
+      act(() => {
+        result.current.setDataValue('surface-1', '/name', 'John')
+        result.current.setDataValue('surface-2', '/name', 'Jane')
+      })
+
+      expect(result.current.getDataValue('surface-1', '/name')).toBe('John')
+      expect(result.current.getDataValue('surface-2', '/name')).toBe('Jane')
+    })
+  })
+
+  describe('getDataModel', () => {
+    it('should return empty object for non-existent surface', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+      expect(result.current.getDataModel('non-existent')).toEqual({})
+    })
+
+    it('should return data model for existing surface', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+        result.current.updateDataModel('surface-1', '/', {
+          name: 'John',
+          age: 30,
+        })
+      })
+
+      expect(result.current.getDataModel('surface-1')).toEqual({
+        name: 'John',
+        age: 30,
+      })
+    })
+  })
+
+  describe('getDataValue', () => {
+    it('should return undefined for non-existent surface', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+      expect(
+        result.current.getDataValue('non-existent', '/name')
+      ).toBeUndefined()
+    })
+
+    it('should return undefined for non-existent path', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+      })
+
+      expect(result.current.getDataValue('surface-1', '/name')).toBeUndefined()
+    })
+
+    it('should return value at path', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+        result.current.updateDataModel('surface-1', '/', {
+          user: { name: 'John' },
+        })
+      })
+
+      expect(result.current.getDataValue('surface-1', '/user/name')).toBe(
+        'John'
+      )
+    })
+  })
+
+  describe('setDataValue', () => {
+    it('should set value at path', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.setDataValue('surface-1', '/name', 'John')
+      })
+
+      expect(result.current.getDataValue('surface-1', '/name')).toBe('John')
+    })
+
+    it('should create nested path structure', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.setDataValue(
+          'surface-1',
+          '/user/profile/email',
+          'john@example.com'
+        )
+      })
+
+      expect(
+        result.current.getDataValue('surface-1', '/user/profile/email')
+      ).toBe('john@example.com')
+    })
+
+    it('should update existing value', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.setDataValue('surface-1', '/name', 'John')
+      })
+
+      act(() => {
+        result.current.setDataValue('surface-1', '/name', 'Jane')
+      })
+
+      expect(result.current.getDataValue('surface-1', '/name')).toBe('Jane')
+    })
+
+    it('should create surface if not exists', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.setDataValue('new-surface', '/name', 'John')
+      })
+
+      expect(result.current.getDataValue('new-surface', '/name')).toBe('John')
+    })
+  })
+
+  describe('updateDataModel', () => {
+    it('should merge data at root path', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+        result.current.updateDataModel('surface-1', '/', { name: 'John' })
+      })
+
+      act(() => {
+        result.current.updateDataModel('surface-1', '/', { age: 30 })
+      })
+
+      expect(result.current.getDataModel('surface-1')).toEqual({
+        name: 'John',
+        age: 30,
+      })
+    })
+
+    it('should merge data at nested path', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+        result.current.updateDataModel('surface-1', '/user', { name: 'John' })
+      })
+
+      act(() => {
+        result.current.updateDataModel('surface-1', '/user', { age: 30 })
+      })
+
+      expect(result.current.getDataValue('surface-1', '/user')).toEqual({
+        name: 'John',
+        age: 30,
+      })
+    })
+
+    it('should create surface if not exists', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.updateDataModel('new-surface', '/user', { name: 'John' })
+      })
+
+      expect(result.current.getDataValue('new-surface', '/user/name')).toBe(
+        'John'
+      )
+    })
+  })
+
+  describe('deleteDataModel', () => {
+    it('should delete data model for surface', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+        result.current.setDataValue('surface-1', '/name', 'John')
+      })
+
+      act(() => {
+        result.current.deleteDataModel('surface-1')
+      })
+
+      expect(result.current.getDataModel('surface-1')).toEqual({})
+    })
+
+    it('should not affect other surfaces', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+        result.current.initDataModel('surface-2')
+        result.current.setDataValue('surface-1', '/name', 'John')
+        result.current.setDataValue('surface-2', '/name', 'Jane')
+      })
+
+      act(() => {
+        result.current.deleteDataModel('surface-1')
+      })
+
+      expect(result.current.getDataModel('surface-1')).toEqual({})
+      expect(result.current.getDataValue('surface-2', '/name')).toBe('Jane')
+    })
+
+    it('should handle deleting non-existent surface gracefully', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      expect(() => {
+        act(() => {
+          result.current.deleteDataModel('non-existent')
+        })
+      }).not.toThrow()
+    })
+  })
+
+  describe('clearDataModels', () => {
+    it('should clear all data models', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+        result.current.initDataModel('surface-2')
+        result.current.setDataValue('surface-1', '/name', 'John')
+        result.current.setDataValue('surface-2', '/name', 'Jane')
+      })
+
+      act(() => {
+        result.current.clearDataModels()
+      })
+
+      expect(result.current.dataModels.size).toBe(0)
+      expect(result.current.getDataModel('surface-1')).toEqual({})
+      expect(result.current.getDataModel('surface-2')).toEqual({})
+    })
+  })
+
+  describe('dataModels state', () => {
+    it('should provide access to all data models via dataModels property', () => {
+      const { result } = renderHook(() => useDataModelContext(), { wrapper })
+
+      act(() => {
+        result.current.initDataModel('surface-1')
+        result.current.setDataValue('surface-1', '/name', 'John')
+      })
+
+      expect(result.current.dataModels.has('surface-1')).toBe(true)
+      expect(result.current.dataModels.get('surface-1')).toEqual({
+        name: 'John',
+      })
+    })
+  })
+})

package/src/0.8/contexts/DataModelContext.tsx

@@ -0,0 +1,184 @@
+/**
+ * DataModelContext - Manages the data model state for A2UI rendering.
+ *
+ * The data model is a hierarchical key-value store.
+ * Components reference data using paths like "/user/name".
+ */
+
+import {
+  createContext,
+  useContext,
+  useState,
+  useMemo,
+  useCallback,
+  type ReactNode,
+} from 'react'
+import type { DataModel, DataModelValue } from '../types'
+import { getValueByPath, setValueByPath, mergeAtPath } from '../utils/pathUtils'
+
+/**
+ * DataModel context value interface.
+ */
+export interface DataModelContextValue {
+  /** Map of data models by surfaceId */
+  dataModels: Map<string, DataModel>
+
+  /** Updates the data model at a path with merge behavior */
+  updateDataModel: (
+    surfaceId: string,
+    path: string,
+    data: Record<string, unknown>
+  ) => void
+
+  /** Gets a value from the data model */
+  getDataValue: (surfaceId: string, path: string) => DataModelValue | undefined
+
+  /** Sets a value in the data model (used by form inputs) */
+  setDataValue: (surfaceId: string, path: string, value: unknown) => void
+
+  /** Gets the entire data model for a surface */
+  getDataModel: (surfaceId: string) => DataModel
+
+  /** Initializes the data model for a surface */
+  initDataModel: (surfaceId: string) => void
+
+  /** Deletes the data model for a surface */
+  deleteDataModel: (surfaceId: string) => void
+
+  /** Clears all data models */
+  clearDataModels: () => void
+}
+
+/**
+ * DataModel context for A2UI rendering.
+ */
+export const DataModelContext = createContext<DataModelContextValue | null>(
+  null
+)
+
+/**
+ * Props for DataModelProvider.
+ */
+export interface DataModelProviderProps {
+  children: ReactNode
+}
+
+/**
+ * Provider component for DataModel state management.
+ */
+export function DataModelProvider({ children }: DataModelProviderProps) {
+  const [dataModels, setDataModels] = useState<Map<string, DataModel>>(
+    new Map()
+  )
+
+  const updateDataModel = useCallback(
+    (surfaceId: string, path: string, data: Record<string, unknown>) => {
+      setDataModels((prev) => {
+        const next = new Map(prev)
+        const current = next.get(surfaceId) ?? {}
+        const updated = mergeAtPath(current, path, data)
+        next.set(surfaceId, updated)
+        return next
+      })
+    },
+    []
+  )
+
+  const getDataValue = useCallback(
+    (surfaceId: string, path: string): DataModelValue | undefined => {
+      const model = dataModels.get(surfaceId)
+      if (!model) {
+        return undefined
+      }
+      return getValueByPath(model, path)
+    },
+    [dataModels]
+  )
+
+  const setDataValue = useCallback(
+    (surfaceId: string, path: string, value: unknown) => {
+      setDataModels((prev) => {
+        const next = new Map(prev)
+        const current = next.get(surfaceId) ?? {}
+        const updated = setValueByPath(current, path, value)
+        next.set(surfaceId, updated)
+        return next
+      })
+    },
+    []
+  )
+
+  const getDataModel = useCallback(
+    (surfaceId: string): DataModel => {
+      return dataModels.get(surfaceId) ?? {}
+    },
+    [dataModels]
+  )
+
+  const initDataModel = useCallback((surfaceId: string) => {
+    setDataModels((prev) => {
+      if (prev.has(surfaceId)) {
+        return prev
+      }
+      const next = new Map(prev)
+      next.set(surfaceId, {})
+      return next
+    })
+  }, [])
+
+  const deleteDataModel = useCallback((surfaceId: string) => {
+    setDataModels((prev) => {
+      const next = new Map(prev)
+      next.delete(surfaceId)
+      return next
+    })
+  }, [])
+
+  const clearDataModels = useCallback(() => {
+    setDataModels(new Map())
+  }, [])
+
+  const value = useMemo<DataModelContextValue>(
+    () => ({
+      dataModels,
+      updateDataModel,
+      getDataValue,
+      setDataValue,
+      getDataModel,
+      initDataModel,
+      deleteDataModel,
+      clearDataModels,
+    }),
+    [
+      dataModels,
+      updateDataModel,
+      getDataValue,
+      setDataValue,
+      getDataModel,
+      initDataModel,
+      deleteDataModel,
+      clearDataModels,
+    ]
+  )
+
+  return (
+    <DataModelContext.Provider value={value}>
+      {children}
+    </DataModelContext.Provider>
+  )
+}
+
+/**
+ * Hook to access the DataModel context.
+ *
+ * @throws Error if used outside of DataModelProvider
+ */
+export function useDataModelContext(): DataModelContextValue {
+  const context = useContext(DataModelContext)
+  if (!context) {
+    throw new Error(
+      'useDataModelContext must be used within a DataModelProvider'
+    )
+  }
+  return context
+}