@easyops-cn/a2ui-react 0.0.0

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

@@ -0,0 +1,334 @@
+/**
+ * useDataBinding Tests
+ *
+ * Tests for the useDataBinding, useDataModel, and useFormBinding hooks.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useDataBinding, useDataModel, useFormBinding } from './useDataBinding'
+import {
+  DataModelProvider,
+  useDataModelContext,
+} from '../contexts/DataModelContext'
+import type { ReactNode } from 'react'
+import type { ValueSource } from '../types'
+
+describe('useDataBinding', () => {
+  // Helper to render hook with provider
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <DataModelProvider>{children}</DataModelProvider>
+  )
+
+  describe('useDataBinding', () => {
+    it('should return default value when source is undefined', () => {
+      const { result } = renderHook(
+        () => useDataBinding<string>('surface-1', undefined, 'default'),
+        { wrapper }
+      )
+      expect(result.current).toBe('default')
+    })
+
+    it('should resolve literalString', () => {
+      const source: ValueSource = { literalString: 'Hello' }
+      const { result } = renderHook(
+        () => useDataBinding<string>('surface-1', source),
+        { wrapper }
+      )
+      expect(result.current).toBe('Hello')
+    })
+
+    it('should resolve literalNumber', () => {
+      const source: ValueSource = { literalNumber: 42 }
+      const { result } = renderHook(
+        () => useDataBinding<number>('surface-1', source),
+        { wrapper }
+      )
+      expect(result.current).toBe(42)
+    })
+
+    it('should resolve literalBoolean', () => {
+      const source: ValueSource = { literalBoolean: true }
+      const { result } = renderHook(
+        () => useDataBinding<boolean>('surface-1', source),
+        { wrapper }
+      )
+      expect(result.current).toBe(true)
+    })
+
+    it('should resolve literalArray', () => {
+      const source: ValueSource = { literalArray: ['a', 'b', 'c'] }
+      const { result } = renderHook(
+        () => useDataBinding<string[]>('surface-1', source),
+        { wrapper }
+      )
+      expect(result.current).toEqual(['a', 'b', 'c'])
+    })
+
+    it('should resolve path reference from data model', () => {
+      const { result } = renderHook(
+        () => {
+          const value = useDataBinding<string>(
+            'surface-1',
+            { path: '/user/name' },
+            ''
+          )
+          const { setDataValue } = useDataModelContext()
+          return { value, setDataValue }
+        },
+        { wrapper }
+      )
+
+      // Initially empty
+      expect(result.current.value).toBe('')
+
+      // Set data
+      act(() => {
+        result.current.setDataValue('surface-1', '/user/name', 'John')
+      })
+
+      expect(result.current.value).toBe('John')
+    })
+
+    it('should return default when path not found', () => {
+      const { result } = renderHook(
+        () =>
+          useDataBinding<string>(
+            'surface-1',
+            { path: '/nonexistent' },
+            'default'
+          ),
+        { wrapper }
+      )
+      expect(result.current).toBe('default')
+    })
+
+    it('should update when data model changes', () => {
+      const { result } = renderHook(
+        () => {
+          const value = useDataBinding<number>(
+            'surface-1',
+            { path: '/count' },
+            0
+          )
+          const { setDataValue } = useDataModelContext()
+          return { value, setDataValue }
+        },
+        { wrapper }
+      )
+
+      expect(result.current.value).toBe(0)
+
+      act(() => {
+        result.current.setDataValue('surface-1', '/count', 10)
+      })
+      expect(result.current.value).toBe(10)
+
+      act(() => {
+        result.current.setDataValue('surface-1', '/count', 20)
+      })
+      expect(result.current.value).toBe(20)
+    })
+
+    it('should throw error when used outside provider', () => {
+      const consoleError = vi
+        .spyOn(console, 'error')
+        .mockImplementation(() => {})
+
+      expect(() => {
+        renderHook(() => useDataBinding('test', undefined))
+      }).toThrow('useDataModelContext must be used within a DataModelProvider')
+
+      consoleError.mockRestore()
+    })
+  })
+
+  describe('useDataModel', () => {
+    it('should return empty object for non-existent surface', () => {
+      const { result } = renderHook(() => useDataModel('non-existent'), {
+        wrapper,
+      })
+      expect(result.current).toEqual({})
+    })
+
+    it('should return data model for surface', () => {
+      const { result } = renderHook(
+        () => {
+          const dataModel = useDataModel('surface-1')
+          const { setDataValue } = useDataModelContext()
+          return { dataModel, setDataValue }
+        },
+        { wrapper }
+      )
+
+      act(() => {
+        result.current.setDataValue('surface-1', '/name', 'John')
+        result.current.setDataValue('surface-1', '/age', 30)
+      })
+
+      expect(result.current.dataModel).toEqual({ name: 'John', age: 30 })
+    })
+
+    it('should update when data model changes', () => {
+      const { result } = renderHook(
+        () => {
+          const dataModel = useDataModel('surface-1')
+          const { setDataValue } = useDataModelContext()
+          return { dataModel, setDataValue }
+        },
+        { wrapper }
+      )
+
+      act(() => {
+        result.current.setDataValue('surface-1', '/name', 'John')
+      })
+
+      expect(result.current.dataModel).toEqual({ name: 'John' })
+
+      act(() => {
+        result.current.setDataValue('surface-1', '/name', 'Jane')
+      })
+
+      expect(result.current.dataModel).toEqual({ name: 'Jane' })
+    })
+  })
+
+  describe('useFormBinding', () => {
+    it('should return value and setter', () => {
+      const { result } = renderHook(
+        () => useFormBinding<string>('surface-1', { path: '/name' }, ''),
+        { wrapper }
+      )
+
+      expect(result.current).toHaveLength(2)
+      expect(typeof result.current[0]).toBe('string')
+      expect(typeof result.current[1]).toBe('function')
+    })
+
+    it('should return default value initially', () => {
+      const { result } = renderHook(
+        () => useFormBinding<string>('surface-1', { path: '/name' }, 'default'),
+        { wrapper }
+      )
+
+      expect(result.current[0]).toBe('default')
+    })
+
+    it('should update data model when setValue is called', () => {
+      const { result } = renderHook(
+        () => {
+          const [value, setValue] = useFormBinding<string>(
+            'surface-1',
+            { path: '/name' },
+            ''
+          )
+          const { getDataValue } = useDataModelContext()
+          return { value, setValue, getDataValue }
+        },
+        { wrapper }
+      )
+
+      act(() => {
+        result.current.setValue('John')
+      })
+
+      expect(result.current.value).toBe('John')
+      expect(result.current.getDataValue('surface-1', '/name')).toBe('John')
+    })
+
+    it('should not update when source is literal', () => {
+      const { result } = renderHook(
+        () => {
+          const [value, setValue] = useFormBinding<string>(
+            'surface-1',
+            { literalString: 'constant' },
+            ''
+          )
+          const { getDataModel } = useDataModelContext()
+          return { value, setValue, getDataModel }
+        },
+        { wrapper }
+      )
+
+      expect(result.current.value).toBe('constant')
+
+      // Try to set value - should not throw but also not update
+      act(() => {
+        result.current.setValue('new value')
+      })
+
+      // Value should still be the literal
+      expect(result.current.value).toBe('constant')
+    })
+
+    it('should not update when source is undefined', () => {
+      const { result } = renderHook(
+        () => {
+          const [value, setValue] = useFormBinding<string>(
+            'surface-1',
+            undefined,
+            'default'
+          )
+          return { value, setValue }
+        },
+        { wrapper }
+      )
+
+      expect(result.current.value).toBe('default')
+
+      // Try to set value - should not throw
+      act(() => {
+        result.current.setValue('new value')
+      })
+
+      // Value should still be default
+      expect(result.current.value).toBe('default')
+    })
+
+    it('should work with different value types', () => {
+      // Number
+      const { result: numberResult } = renderHook(
+        () => useFormBinding<number>('surface-1', { path: '/count' }, 0),
+        { wrapper }
+      )
+
+      act(() => {
+        numberResult.current[1](42)
+      })
+      expect(numberResult.current[0]).toBe(42)
+
+      // Boolean
+      const { result: boolResult } = renderHook(
+        () => useFormBinding<boolean>('surface-2', { path: '/active' }, false),
+        { wrapper }
+      )
+
+      act(() => {
+        boolResult.current[1](true)
+      })
+      expect(boolResult.current[0]).toBe(true)
+    })
+
+    it('should reflect external data model changes', () => {
+      const { result } = renderHook(
+        () => {
+          const [value, setValue] = useFormBinding<string>(
+            'surface-1',
+            { path: '/name' },
+            ''
+          )
+          const { setDataValue } = useDataModelContext()
+          return { value, setValue, setDataValue }
+        },
+        { wrapper }
+      )
+
+      // Set via external setDataValue
+      act(() => {
+        result.current.setDataValue('surface-1', '/name', 'External')
+      })
+
+      expect(result.current.value).toBe('External')
+    })
+  })
+})

package/src/0.8/hooks/useDataBinding.ts

@@ -0,0 +1,99 @@
+/**
+ * useDataBinding - Hook for resolving data bindings in components.
+ */
+
+import { useMemo } from 'react'
+import type { ValueSource, DataModel } from '../types'
+import { useDataModelContext } from '../contexts/DataModelContext'
+import { resolveValue } from '../utils/dataBinding'
+
+/**
+ * Resolves a ValueSource to its actual value.
+ *
+ * @param surfaceId - The surface ID for data model lookup
+ * @param source - The value source (literal or path reference)
+ * @param defaultValue - Default value if source is undefined or path not found
+ * @returns The resolved value
+ *
+ * @example
+ * ```tsx
+ * function TextComponent({ surfaceId, text }) {
+ *   const textValue = useDataBinding<string>(surfaceId, text, '');
+ *   return <span>{textValue}</span>;
+ * }
+ * ```
+ */
+export function useDataBinding<T = unknown>(
+  surfaceId: string,
+  source: ValueSource | undefined,
+  defaultValue?: T
+): T {
+  const { getDataModel } = useDataModelContext()
+
+  return useMemo(() => {
+    const dataModel = getDataModel(surfaceId)
+    return resolveValue<T>(source, dataModel, defaultValue)
+  }, [getDataModel, surfaceId, source, defaultValue])
+}
+
+/**
+ * Gets the full data model for a surface.
+ * Useful for components that need access to multiple values.
+ *
+ * @param surfaceId - The surface ID
+ * @returns The data model for this surface
+ */
+export function useDataModel(surfaceId: string): DataModel {
+  const { getDataModel } = useDataModelContext()
+
+  return useMemo(() => {
+    return getDataModel(surfaceId)
+  }, [getDataModel, surfaceId])
+}
+
+/**
+ * Hook for two-way data binding in form components.
+ * Returns both the current value and a setter function.
+ *
+ * @param surfaceId - The surface ID
+ * @param source - The value source (must be a path reference for setting)
+ * @param defaultValue - Default value if not found
+ * @returns Tuple of [value, setValue]
+ *
+ * @example
+ * ```tsx
+ * function TextFieldComponent({ surfaceId, text }) {
+ *   const [value, setValue] = useFormBinding<string>(surfaceId, text, '');
+ *
+ *   return (
+ *     <input
+ *       value={value}
+ *       onChange={(e) => setValue(e.target.value)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function useFormBinding<T = unknown>(
+  surfaceId: string,
+  source: ValueSource | undefined,
+  defaultValue?: T
+): [T, (value: T) => void] {
+  const { getDataModel, setDataValue } = useDataModelContext()
+
+  const value = useMemo(() => {
+    const dataModel = getDataModel(surfaceId)
+    return resolveValue<T>(source, dataModel, defaultValue)
+  }, [getDataModel, surfaceId, source, defaultValue])
+
+  const setValue = useMemo(() => {
+    return (newValue: T) => {
+      // Only path references can be updated
+      if (source && 'path' in source) {
+        setDataValue(surfaceId, source.path, newValue)
+      }
+    }
+  }, [setDataValue, surfaceId, source])
+
+  return [value, setValue]
+}

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

@@ -0,0 +1,83 @@
+/**
+ * useDispatchAction Tests
+ *
+ * Tests for the useDispatchAction hooks.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useDispatchAction } from './useDispatchAction'
+import { ActionProvider } from '../contexts/ActionContext'
+import { DataModelProvider } from '../contexts/DataModelContext'
+import type { ReactNode } from 'react'
+import type { Action, ActionPayload } from '../types'
+
+describe('useDispatchAction', () => {
+  // Helper to create wrapper with providers
+  const createWrapper =
+    (onAction?: (action: ActionPayload) => void) =>
+    ({ children }: { children: ReactNode }) => (
+      <DataModelProvider>
+        <ActionProvider onAction={onAction}>{children}</ActionProvider>
+      </DataModelProvider>
+    )
+
+  it('should return dispatch function', () => {
+    const wrapper = createWrapper()
+    const { result } = renderHook(() => useDispatchAction(), { wrapper })
+    expect(typeof result.current).toBe('function')
+  })
+
+  it('should dispatch action with correct payload', () => {
+    const onAction = vi.fn()
+    const wrapper = createWrapper(onAction)
+
+    const { result } = renderHook(() => useDispatchAction(), { wrapper })
+
+    const action: Action = {
+      name: 'submit',
+      context: [{ key: 'type', value: { literalString: 'form' } }],
+    }
+
+    act(() => {
+      result.current('surface-1', 'button-1', action)
+    })
+
+    expect(onAction).toHaveBeenCalledWith({
+      surfaceId: 'surface-1',
+      name: 'submit',
+      context: { type: 'form' },
+      sourceComponentId: 'button-1',
+    })
+  })
+
+  it('should dispatch action without context', () => {
+    const onAction = vi.fn()
+    const wrapper = createWrapper(onAction)
+
+    const { result } = renderHook(() => useDispatchAction(), { wrapper })
+
+    const action: Action = { name: 'cancel' }
+
+    act(() => {
+      result.current('surface-1', 'button-1', action)
+    })
+
+    expect(onAction).toHaveBeenCalledWith({
+      surfaceId: 'surface-1',
+      name: 'cancel',
+      context: {},
+      sourceComponentId: 'button-1',
+    })
+  })
+
+  it('should throw error when used outside provider', () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    expect(() => {
+      renderHook(() => useDispatchAction())
+    }).toThrow('useActionContext must be used within an ActionProvider')
+
+    consoleError.mockRestore()
+  })
+})

package/src/0.8/hooks/useDispatchAction.ts

@@ -0,0 +1,35 @@
+/**
+ * useDispatchAction - Hook for dispatching actions from components.
+ */
+
+import type { Action } from '../types'
+import { useActionContext } from '../contexts/ActionContext'
+
+/**
+ * Returns a function to dispatch actions.
+ *
+ * @returns A function that dispatches actions
+ *
+ * @example
+ * ```tsx
+ * function ButtonComponent({ surfaceId, componentId, action }) {
+ *   const dispatchAction = useDispatchAction();
+ *
+ *   const handleClick = () => {
+ *     if (action) {
+ *       dispatchAction(surfaceId, componentId, action);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleClick}>Click me</button>;
+ * }
+ * ```
+ */
+export function useDispatchAction(): (
+  surfaceId: string,
+  componentId: string,
+  action: Action
+) => void {
+  const { dispatchAction } = useActionContext()
+  return dispatchAction
+}

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

@@ -0,0 +1,114 @@
+/**
+ * useSurface Tests
+ *
+ * Tests for the useSurface hook.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useSurface } from './useSurface'
+import { SurfaceProvider, useSurfaceContext } from '../contexts/SurfaceContext'
+import type { ReactNode } from 'react'
+
+describe('useSurface', () => {
+  // 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(() => useSurface('non-existent'), { wrapper })
+    expect(result.current).toBeUndefined()
+  })
+
+  it('should return surface when it exists', () => {
+    // Custom wrapper that initializes a surface
+    const TestWrapper = ({ children }: { children: ReactNode }) => (
+      <SurfaceProvider>
+        <SurfaceInitializer>{children}</SurfaceInitializer>
+      </SurfaceProvider>
+    )
+
+    function SurfaceInitializer({ children }: { children: ReactNode }) {
+      const { initSurface } = useSurfaceContext()
+      React.useEffect(() => {
+        initSurface('test-surface', 'root-component', { font: 'Arial' })
+      }, [initSurface])
+      return <>{children}</>
+    }
+
+    const { result } = renderHook(() => useSurface('test-surface'), {
+      wrapper: TestWrapper,
+    })
+
+    expect(result.current).toBeDefined()
+    expect(result.current?.surfaceId).toBe('test-surface')
+    expect(result.current?.root).toBe('root-component')
+    expect(result.current?.styles?.font).toBe('Arial')
+  })
+
+  it('should update when surface changes', () => {
+    const { result } = renderHook(
+      () => {
+        const surface = useSurface('test-surface')
+        const { initSurface, updateSurface } = useSurfaceContext()
+        return { surface, initSurface, updateSurface }
+      },
+      { wrapper }
+    )
+
+    // Initially undefined
+    expect(result.current.surface).toBeUndefined()
+
+    // Initialize surface
+    act(() => {
+      result.current.initSurface('test-surface', 'root')
+    })
+
+    expect(result.current.surface).toBeDefined()
+    expect(result.current.surface?.root).toBe('root')
+
+    // Update surface with components
+    act(() => {
+      result.current.updateSurface('test-surface', [
+        { id: 'comp-1', component: { Text: {} } },
+      ])
+    })
+
+    expect(result.current.surface?.components.size).toBe(1)
+  })
+
+  it('should memoize result based on surfaceId', () => {
+    const { result, rerender } = renderHook(
+      ({ surfaceId }) => {
+        const surface = useSurface(surfaceId)
+        const { initSurface } = useSurfaceContext()
+        return { surface, initSurface }
+      },
+      { wrapper, initialProps: { surfaceId: 'surface-1' } }
+    )
+
+    act(() => {
+      result.current.initSurface('surface-1', 'root-1')
+      result.current.initSurface('surface-2', 'root-2')
+    })
+
+    expect(result.current.surface?.root).toBe('root-1')
+
+    // Change surfaceId
+    rerender({ surfaceId: 'surface-2' })
+    expect(result.current.surface?.root).toBe('root-2')
+  })
+
+  it('should throw error when used outside provider', () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    expect(() => {
+      renderHook(() => useSurface('test'))
+    }).toThrow('useSurfaceContext must be used within a SurfaceProvider')
+
+    consoleError.mockRestore()
+  })
+})
+
+import React from 'react'

package/src/0.8/hooks/useSurface.ts

@@ -0,0 +1,34 @@
+/**
+ * useSurface - Hook to get a Surface by ID.
+ */
+
+import { useMemo } from 'react'
+import type { Surface } from '../types'
+import { useSurfaceContext } from '../contexts/SurfaceContext'
+
+/**
+ * Gets a Surface by its ID.
+ *
+ * @param surfaceId - The surface ID to look up
+ * @returns The Surface, or undefined if not found
+ *
+ * @example
+ * ```tsx
+ * function MySurface({ surfaceId }) {
+ *   const surface = useSurface(surfaceId);
+ *
+ *   if (!surface) {
+ *     return <div>Surface not found</div>;
+ *   }
+ *
+ *   return <ComponentRenderer surfaceId={surfaceId} componentId={surface.root} />;
+ * }
+ * ```
+ */
+export function useSurface(surfaceId: string): Surface | undefined {
+  const { surfaces } = useSurfaceContext()
+
+  return useMemo(() => {
+    return surfaces.get(surfaceId)
+  }, [surfaces, surfaceId])
+}