@easyops-cn/a2ui-react 0.0.1 → 0.0.3

package/dist/0.8/contexts/ActionContext.d.ts

@@ -0,0 +1,33 @@
+import { ReactNode } from 'react';
+import { Action, ActionHandler } from '../types';
+/**
+ * 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 declare const ActionContext: import('react').Context<ActionContextValue | null>;
+/**
+ * Props for ActionProvider.
+ */
+export interface ActionProviderProps {
+    /** Callback when an action is dispatched */
+    onAction?: ActionHandler;
+    children: ReactNode;
+}
+/**
+ * Provider component for Action dispatching.
+ */
+export declare function ActionProvider({ onAction, children }: ActionProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the Action context.
+ *
+ * @throws Error if used outside of ActionProvider
+ */
+export declare function useActionContext(): ActionContextValue;

package/dist/0.8/contexts/ActionContext.js

@@ -0,0 +1,41 @@
+import { jsx as m } from "react/jsx-runtime";
+import { createContext as x, useContext as C, useCallback as p, useMemo as f } from "react";
+import { useDataModelContext as v } from "./DataModelContext.js";
+import { resolveActionContext as A } from "../utils/dataBinding.js";
+const s = x(null);
+function P({ onAction: t, children: c }) {
+  const { getDataModel: o } = v(), e = p(
+    (n, a, r) => {
+      if (!t) {
+        console.warn("A2UI: Action dispatched but no handler is registered");
+        return;
+      }
+      const u = o(n), d = A(r.context, u), l = {
+        surfaceId: n,
+        name: r.name,
+        context: d,
+        sourceComponentId: a
+      };
+      t(l);
+    },
+    [t, o]
+  ), i = f(
+    () => ({
+      dispatchAction: e,
+      onAction: t ?? null
+    }),
+    [e, t]
+  );
+  return /* @__PURE__ */ m(s.Provider, { value: i, children: c });
+}
+function g() {
+  const t = C(s);
+  if (!t)
+    throw new Error("useActionContext must be used within an ActionProvider");
+  return t;
+}
+export {
+  s as ActionContext,
+  P as ActionProvider,
+  g as useActionContext
+};

package/dist/0.8/contexts/ActionContext.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * ActionContext Tests
+ *
+ * Tests for the Action context provider and hook.
+ */
+export {};

package/dist/0.8/contexts/ComponentsMapContext.d.ts

@@ -0,0 +1,63 @@
+import { ReactNode, ComponentType } from 'react';
+import { 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 declare const ComponentsMapContext: import('react').Context<ComponentsMapContextValue | 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 declare function ComponentsMapProvider({ components, defaultComponents, children, }: ComponentsMapProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the ComponentsMap context.
+ *
+ * @throws Error if used outside of ComponentsMapProvider
+ */
+export declare function useComponentsMapContext(): ComponentsMapContextValue;
+/**
+ * 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 declare function useComponentFromMap(type: string): A2UIComponent | undefined;

package/dist/0.8/contexts/ComponentsMapContext.js

@@ -0,0 +1,21 @@
+import { jsx as s } from "react/jsx-runtime";
+import { createContext as u, useMemo as p } from "react";
+const c = u(null);
+function x({
+  components: n,
+  defaultComponents: e,
+  children: r
+}) {
+  const m = p(() => {
+    const o = n ?? /* @__PURE__ */ new Map();
+    return {
+      customComponents: o,
+      getComponent: (t) => o.has(t) ? o.get(t) : e[t]
+    };
+  }, [n, e]);
+  return /* @__PURE__ */ s(c.Provider, { value: m, children: r });
+}
+export {
+  c as ComponentsMapContext,
+  x as ComponentsMapProvider
+};

package/dist/0.8/contexts/DataModelContext.d.ts

@@ -0,0 +1,43 @@
+import { ReactNode } from 'react';
+import { DataModel, DataModelValue } from '../types';
+/**
+ * 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 declare const DataModelContext: import('react').Context<DataModelContextValue | null>;
+/**
+ * Props for DataModelProvider.
+ */
+export interface DataModelProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provider component for DataModel state management.
+ */
+export declare function DataModelProvider({ children }: DataModelProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the DataModel context.
+ *
+ * @throws Error if used outside of DataModelProvider
+ */
+export declare function useDataModelContext(): DataModelContextValue;

package/dist/0.8/contexts/DataModelContext.js

@@ -0,0 +1,86 @@
+import { jsx as C } from "react/jsx-runtime";
+import { createContext as P, useContext as f, useState as V, useCallback as a, useMemo as v } from "react";
+import { mergeAtPath as b, getValueByPath as y, setValueByPath as B } from "../utils/pathUtils.js";
+const g = P(
+  null
+);
+function E({ children: u }) {
+  const [r, s] = V(
+    /* @__PURE__ */ new Map()
+  ), M = a(
+    (t, n, e) => {
+      s((c) => {
+        const o = new Map(c), l = o.get(t) ?? {}, d = b(l, n, e);
+        return o.set(t, d), o;
+      });
+    },
+    []
+  ), i = a(
+    (t, n) => {
+      const e = r.get(t);
+      if (e)
+        return y(e, n);
+    },
+    [r]
+  ), D = a(
+    (t, n, e) => {
+      s((c) => {
+        const o = new Map(c), l = o.get(t) ?? {}, d = B(l, n, e);
+        return o.set(t, d), o;
+      });
+    },
+    []
+  ), x = a(
+    (t) => r.get(t) ?? {},
+    [r]
+  ), p = a((t) => {
+    s((n) => {
+      if (n.has(t))
+        return n;
+      const e = new Map(n);
+      return e.set(t, {}), e;
+    });
+  }, []), m = a((t) => {
+    s((n) => {
+      const e = new Map(n);
+      return e.delete(t), e;
+    });
+  }, []), w = a(() => {
+    s(/* @__PURE__ */ new Map());
+  }, []), h = v(
+    () => ({
+      dataModels: r,
+      updateDataModel: M,
+      getDataValue: i,
+      setDataValue: D,
+      getDataModel: x,
+      initDataModel: p,
+      deleteDataModel: m,
+      clearDataModels: w
+    }),
+    [
+      r,
+      M,
+      i,
+      D,
+      x,
+      p,
+      m,
+      w
+    ]
+  );
+  return /* @__PURE__ */ C(g.Provider, { value: h, children: u });
+}
+function S() {
+  const u = f(g);
+  if (!u)
+    throw new Error(
+      "useDataModelContext must be used within a DataModelProvider"
+    );
+  return u;
+}
+export {
+  g as DataModelContext,
+  E as DataModelProvider,
+  S as useDataModelContext
+};

package/dist/0.8/contexts/DataModelContext.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * DataModelContext Tests
+ *
+ * Tests for the DataModel context provider and hook.
+ */
+export {};

package/dist/0.8/contexts/SurfaceContext.d.ts

@@ -0,0 +1,45 @@
+import { ReactNode } from 'react';
+import { Surface, ComponentDefinition, SurfaceStyles } from '../types';
+/**
+ * Surface context value interface.
+ */
+export interface SurfaceContextValue {
+    /** Map of all surfaces by surfaceId */
+    surfaces: Map<string, Surface>;
+    /**
+     * Initializes a surface with root and styles.
+     * If the surface already exists, preserves existing components.
+     * Called when beginRendering message is received.
+     */
+    initSurface: (surfaceId: string, root: string, styles?: SurfaceStyles) => void;
+    /** Updates components in a surface */
+    updateSurface: (surfaceId: string, components: ComponentDefinition[]) => void;
+    /** Deletes a surface */
+    deleteSurface: (surfaceId: string) => void;
+    /** Gets a surface by ID */
+    getSurface: (surfaceId: string) => Surface | undefined;
+    /** Gets a component from a surface */
+    getComponent: (surfaceId: string, componentId: string) => ComponentDefinition | undefined;
+    /** Clears all surfaces */
+    clearSurfaces: () => void;
+}
+/**
+ * Surface context for A2UI rendering.
+ */
+export declare const SurfaceContext: import('react').Context<SurfaceContextValue | null>;
+/**
+ * Props for SurfaceProvider.
+ */
+export interface SurfaceProviderProps {
+    children: ReactNode;
+}
+/**
+ * Provider component for Surface state management.
+ */
+export declare function SurfaceProvider({ children }: SurfaceProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the Surface context.
+ *
+ * @throws Error if used outside of SurfaceProvider
+ */
+export declare function useSurfaceContext(): SurfaceContextValue;

package/dist/0.8/contexts/SurfaceContext.js

@@ -0,0 +1,88 @@
+import { jsx as P } from "react/jsx-runtime";
+import { createContext as b, useContext as h, useState as j, useCallback as s, useMemo as k } from "react";
+const C = b(null);
+function q({ children: a }) {
+  const [o, f] = j(/* @__PURE__ */ new Map()), i = s(
+    (e, n, t) => {
+      f((c) => {
+        const p = c.get(e), r = new Map(c);
+        return r.set(e, {
+          surfaceId: e,
+          root: n,
+          components: p?.components ?? /* @__PURE__ */ new Map(),
+          styles: t
+        }), r;
+      });
+    },
+    []
+  ), m = s(
+    (e, n) => {
+      f((t) => {
+        const c = t.get(e);
+        if (!c) {
+          const u = {
+            surfaceId: e,
+            root: "",
+            components: /* @__PURE__ */ new Map()
+          };
+          for (const l of n)
+            u.components.set(l.id, l);
+          const g = new Map(t);
+          return g.set(e, u), g;
+        }
+        const p = new Map(t), r = new Map(c.components);
+        for (const u of n)
+          r.set(u.id, u);
+        return p.set(e, {
+          ...c,
+          components: r
+        }), p;
+      });
+    },
+    []
+  ), w = s((e) => {
+    f((n) => {
+      const t = new Map(n);
+      return t.delete(e), t;
+    });
+  }, []), x = s(
+    (e) => o.get(e),
+    [o]
+  ), S = s(
+    (e, n) => o.get(e)?.components.get(n),
+    [o]
+  ), M = s(() => {
+    f(/* @__PURE__ */ new Map());
+  }, []), d = k(
+    () => ({
+      surfaces: o,
+      initSurface: i,
+      updateSurface: m,
+      deleteSurface: w,
+      getSurface: x,
+      getComponent: S,
+      clearSurfaces: M
+    }),
+    [
+      o,
+      i,
+      m,
+      w,
+      x,
+      S,
+      M
+    ]
+  );
+  return /* @__PURE__ */ P(C.Provider, { value: d, children: a });
+}
+function y() {
+  const a = h(C);
+  if (!a)
+    throw new Error("useSurfaceContext must be used within a SurfaceProvider");
+  return a;
+}
+export {
+  C as SurfaceContext,
+  q as SurfaceProvider,
+  y as useSurfaceContext
+};

package/dist/0.8/contexts/SurfaceContext.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SurfaceContext Tests
+ *
+ * Tests for the Surface context provider and hook.
+ */
+export {};

package/dist/0.8/hooks/useA2UIMessageHandler.d.ts

@@ -0,0 +1,41 @@
+import { A2UIMessage } from '../types';
+/**
+ * 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 declare function useA2UIMessageHandler(): A2UIMessageHandler;

package/dist/0.8/hooks/useA2UIMessageHandler.js

@@ -0,0 +1,54 @@
+import { useCallback as c } from "react";
+import { useSurfaceContext as I } from "../contexts/SurfaceContext.js";
+import { useDataModelContext as U } from "../contexts/DataModelContext.js";
+import { contentsToObject as b } from "../utils/dataBinding.js";
+function g() {
+  const { initSurface: n, updateSurface: d, deleteSurface: u, clearSurfaces: f } = I(), { updateDataModel: s, initDataModel: l, deleteDataModel: i, clearDataModels: p } = U(), o = c(
+    (t) => {
+      if (t.beginRendering) {
+        const { surfaceId: e, root: r, styles: a } = t.beginRendering;
+        n(e, r, a), l(e);
+        return;
+      }
+      if (t.surfaceUpdate) {
+        const { surfaceId: e, components: r } = t.surfaceUpdate;
+        d(e, r);
+        return;
+      }
+      if (t.dataModelUpdate) {
+        const { surfaceId: e, path: r = "/", contents: a } = t.dataModelUpdate, D = b(a);
+        s(e, r, D);
+        return;
+      }
+      if (t.deleteSurface) {
+        const { surfaceId: e } = t.deleteSurface;
+        u(e), i(e);
+        return;
+      }
+    },
+    [
+      n,
+      d,
+      u,
+      l,
+      s,
+      i
+    ]
+  ), M = c(
+    (t) => {
+      for (const e of t)
+        o(e);
+    },
+    [o]
+  ), S = c(() => {
+    f(), p();
+  }, [f, p]);
+  return {
+    processMessage: o,
+    processMessages: M,
+    clear: S
+  };
+}
+export {
+  g as useA2UIMessageHandler
+};

package/dist/0.8/hooks/useA2UIMessageHandler.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * useA2UIMessageHandler Tests
+ *
+ * Tests for the useA2UIMessageHandler hook.
+ */
+export {};

package/{src/0.8/hooks/useComponent.ts → dist/0.8/hooks/useComponent.d.ts}

@@ -1,11 +1,4 @@
-/**
- * useComponent - Hook to get a component from a Surface.
- */
-
-import { useMemo } from 'react'
-import type { ComponentDefinition } from '../types'
-import { useSurfaceContext } from '../contexts/SurfaceContext'
-
+import { ComponentDefinition } from '../types';
 /**
  * Gets a component from a Surface by its ID.
  *
@@ -27,13 +20,4 @@ import { useSurfaceContext } from '../contexts/SurfaceContext'
  * }
  * ```
  */
-export function useComponent(
-  surfaceId: string,
-  componentId: string
-): ComponentDefinition | undefined {
-  const { getComponent } = useSurfaceContext()
-
-  return useMemo(() => {
-    return getComponent(surfaceId, componentId)
-  }, [getComponent, surfaceId, componentId])
-}
+export declare function useComponent(surfaceId: string, componentId: string): ComponentDefinition | undefined;

package/dist/0.8/hooks/useComponent.js

@@ -0,0 +1,9 @@
+import { useMemo as r } from "react";
+import { useSurfaceContext as n } from "../contexts/SurfaceContext.js";
+function p(o, t) {
+  const { getComponent: e } = n();
+  return r(() => e(o, t), [e, o, t]);
+}
+export {
+  p as useComponent
+};

package/dist/0.8/hooks/useComponent.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * useComponent Tests
+ *
+ * Tests for the useComponent hook.
+ */
+export {};

package/dist/0.8/hooks/useDataBinding.d.ts

@@ -0,0 +1,50 @@
+import { ValueSource, DataModel } from '../types';
+/**
+ * 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 declare function useDataBinding<T = unknown>(surfaceId: string, source: ValueSource | undefined, defaultValue?: T): T;
+/**
+ * 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 declare function useDataModel(surfaceId: string): DataModel;
+/**
+ * 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 declare function useFormBinding<T = unknown>(surfaceId: string, source: ValueSource | undefined, defaultValue?: T): [T, (value: T) => void];

package/dist/0.8/hooks/useDataBinding.js

@@ -0,0 +1,28 @@
+import { useMemo as i } from "react";
+import { useDataModelContext as l } from "../contexts/DataModelContext.js";
+import { resolveValue as m } from "../utils/dataBinding.js";
+function s(n, t, o) {
+  const { getDataModel: e } = l();
+  return i(() => {
+    const a = e(n);
+    return m(t, a, o);
+  }, [e, n, t, o]);
+}
+function u(n) {
+  const { getDataModel: t } = l();
+  return i(() => t(n), [t, n]);
+}
+function h(n, t, o) {
+  const { getDataModel: e, setDataValue: a } = l(), M = i(() => {
+    const r = e(n);
+    return m(t, r, o);
+  }, [e, n, t, o]), D = i(() => (r) => {
+    t && "path" in t && a(n, t.path, r);
+  }, [a, n, t]);
+  return [M, D];
+}
+export {
+  s as useDataBinding,
+  u as useDataModel,
+  h as useFormBinding
+};

package/dist/0.8/hooks/useDataBinding.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * useDataBinding Tests
+ *
+ * Tests for the useDataBinding, useDataModel, and useFormBinding hooks.
+ */
+export {};