@a2ui-sdk/react 0.0.0

package/dist/0.9/contexts/SurfaceContext.js

@@ -0,0 +1,118 @@
+import { jsx as P } from "react/jsx-runtime";
+import { createContext as b, useContext as A, useState as U, useCallback as a, useMemo as $ } from "react";
+import { setValueByPath as y } from "../utils/pathUtils.js";
+const C = b(null);
+function z({ children: f }) {
+  const [r, s] = U(/* @__PURE__ */ new Map()), i = a((e, n) => {
+    s((t) => {
+      if (t.has(e))
+        return console.error(
+          `[A2UI 0.9] Surface "${e}" already exists. Ignoring createSurface.`
+        ), t;
+      const o = new Map(t);
+      return o.set(e, {
+        surfaceId: e,
+        catalogId: n,
+        components: /* @__PURE__ */ new Map(),
+        dataModel: {},
+        created: !0
+      }), o;
+    });
+  }, []), p = a(
+    (e, n) => {
+      s((t) => {
+        const o = t.get(e);
+        if (!o)
+          return console.warn(
+            `[A2UI 0.9] updateComponents called for non-existent surface "${e}". Components will be buffered until createSurface is received.`
+          ), t;
+        const c = new Map(t), u = new Map(o.components);
+        for (const d of n)
+          u.set(d.id, d);
+        return c.set(e, {
+          ...o,
+          components: u
+        }), c;
+      });
+    },
+    []
+  ), l = a(
+    (e, n, t) => {
+      s((o) => {
+        const c = o.get(e);
+        if (!c)
+          return console.warn(
+            `[A2UI 0.9] updateDataModel called for non-existent surface "${e}".`
+          ), o;
+        const u = new Map(o), d = n ?? "/", D = y(
+          c.dataModel,
+          d,
+          t
+        );
+        return u.set(e, {
+          ...c,
+          dataModel: D
+        }), u;
+      });
+    },
+    []
+  ), m = a((e) => {
+    s((n) => {
+      const t = new Map(n);
+      return t.delete(e), t;
+    });
+  }, []), M = a(
+    (e) => r.get(e),
+    [r]
+  ), x = a(
+    (e, n) => r.get(e)?.components.get(n),
+    [r]
+  ), w = a(
+    (e) => r.get(e)?.dataModel ?? {},
+    [r]
+  ), S = a(
+    (e, n, t) => {
+      l(e, n, t);
+    },
+    [l]
+  ), g = a(() => {
+    s(/* @__PURE__ */ new Map());
+  }, []), h = $(
+    () => ({
+      surfaces: r,
+      createSurface: i,
+      updateComponents: p,
+      updateDataModel: l,
+      deleteSurface: m,
+      getSurface: M,
+      getComponent: x,
+      getDataModel: w,
+      setDataValue: S,
+      clearSurfaces: g
+    }),
+    [
+      r,
+      i,
+      p,
+      l,
+      m,
+      M,
+      x,
+      w,
+      S,
+      g
+    ]
+  );
+  return /* @__PURE__ */ P(C.Provider, { value: h, children: f });
+}
+function B() {
+  const f = A(C);
+  if (!f)
+    throw new Error("useSurfaceContext must be used within a SurfaceProvider");
+  return f;
+}
+export {
+  C as SurfaceContext,
+  z as SurfaceProvider,
+  B as useSurfaceContext
+};

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

@@ -0,0 +1,44 @@
+import { A2UIMessage } from '@a2ui-sdk/types/0.9';
+/**
+ * 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 buffered messages */
+    clear: () => void;
+}
+/**
+ * Hook that returns functions to process A2UI 0.9 messages.
+ *
+ * Messages received before createSurface are buffered and applied
+ * when createSurface is received.
+ *
+ * @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(JSON.parse(event.data));
+ *     };
+ *     eventSource.addEventListener('message', handler);
+ *
+ *     return () => {
+ *       eventSource.close();
+ *       clear();
+ *     };
+ *   }, []);
+ * }
+ * ```
+ */
+export declare function useA2UIMessageHandler(): A2UIMessageHandler;

package/dist/0.9/hooks/useA2UIMessageHandler.js

@@ -0,0 +1,87 @@
+import { useRef as S, useCallback as a } from "react";
+import { useSurfaceContext as D } from "../contexts/SurfaceContext.js";
+function x() {
+  const {
+    createSurface: p,
+    updateComponents: o,
+    updateDataModel: u,
+    deleteSurface: l,
+    clearSurfaces: i
+  } = D(), n = S(/* @__PURE__ */ new Map()), c = S(/* @__PURE__ */ new Set()), M = a(
+    (t) => {
+      const e = n.current.get(t);
+      if (!(!e || e.length === 0)) {
+        for (const r of e)
+          if ("updateComponents" in r)
+            o(t, r.updateComponents.components);
+          else if ("updateDataModel" in r) {
+            const { path: d, value: m } = r.updateDataModel;
+            u(t, d, m);
+          }
+        n.current.delete(t);
+      }
+    },
+    [o, u]
+  ), s = a(
+    (t, e) => {
+      const r = n.current.get(t) ?? [];
+      n.current.set(t, [...r, e]);
+    },
+    []
+  ), f = a(
+    (t) => {
+      if ("createSurface" in t) {
+        const { surfaceId: e, catalogId: r } = t.createSurface;
+        p(e, r), c.current.add(e), M(e);
+        return;
+      }
+      if ("updateComponents" in t) {
+        const { surfaceId: e, components: r } = t.updateComponents;
+        if (!c.current.has(e)) {
+          s(e, t);
+          return;
+        }
+        o(e, r);
+        return;
+      }
+      if ("updateDataModel" in t) {
+        const { surfaceId: e, path: r, value: d } = t.updateDataModel;
+        if (!c.current.has(e)) {
+          s(e, t);
+          return;
+        }
+        u(e, r, d);
+        return;
+      }
+      if ("deleteSurface" in t) {
+        const { surfaceId: e } = t.deleteSurface;
+        l(e), c.current.delete(e), n.current.delete(e);
+        return;
+      }
+    },
+    [
+      p,
+      o,
+      u,
+      l,
+      M,
+      s
+    ]
+  ), C = a(
+    (t) => {
+      for (const e of t)
+        f(e);
+    },
+    [f]
+  ), h = a(() => {
+    i(), n.current.clear(), c.current.clear();
+  }, [i]);
+  return {
+    processMessage: f,
+    processMessages: C,
+    clear: h
+  };
+}
+export {
+  x as useA2UIMessageHandler
+};

package/dist/0.9/hooks/useComponent.d.ts

@@ -0,0 +1,23 @@
+import { Component } from '@a2ui-sdk/types/0.9';
+/**
+ * Gets a component from a Surface by its ID.
+ *
+ * @param surfaceId - The surface ID
+ * @param componentId - The component ID to look up
+ * @returns The Component, or undefined if not found
+ *
+ * @example
+ * ```tsx
+ * function MyComponent({ surfaceId, componentId }) {
+ *   const component = useComponent(surfaceId, componentId);
+ *
+ *   if (!component) {
+ *     return null;
+ *   }
+ *
+ *   // Use component.component to get the type ("Text", "Button", etc.)
+ *   // All other properties are available directly on the component
+ * }
+ * ```
+ */
+export declare function useComponent(surfaceId: string, componentId: string): Component | undefined;

package/dist/0.9/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.9/hooks/useDataBinding.d.ts

@@ -0,0 +1,59 @@
+import { DynamicValue, DynamicString, DataModel, FormBindableValue } from '@a2ui-sdk/types/0.9';
+/**
+ * Resolves a DynamicValue to its actual value.
+ *
+ * @param surfaceId - The surface ID for data model lookup
+ * @param source - The dynamic value (literal or path binding)
+ * @param defaultValue - Default value if source is undefined or path not found
+ * @returns The resolved value
+ *
+ * @example
+ * ```tsx
+ * function TextComponent({ surfaceId, component }) {
+ *   const textValue = useDataBinding<string>(surfaceId, component.text, '');
+ *   return <span>{textValue}</span>;
+ * }
+ * ```
+ */
+export declare function useDataBinding<T = unknown>(surfaceId: string, source: DynamicValue | undefined, defaultValue?: T): T;
+/**
+ * Resolves a DynamicString to a string value.
+ *
+ * @param surfaceId - The surface ID for data model lookup
+ * @param source - The dynamic string value
+ * @param defaultValue - Default value if source is undefined or path not found
+ * @returns The resolved string
+ */
+export declare function useStringBinding(surfaceId: string, source: DynamicString | undefined, defaultValue?: string): string;
+/**
+ * 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 dynamic value (must be a path binding for setting)
+ * @param defaultValue - Default value if not found
+ * @returns Tuple of [value, setValue]
+ *
+ * @example
+ * ```tsx
+ * function TextFieldComponent({ surfaceId, component }) {
+ *   const [value, setValue] = useFormBinding<string>(surfaceId, component.value, '');
+ *
+ *   return (
+ *     <input
+ *       value={value}
+ *       onChange={(e) => setValue(e.target.value)}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function useFormBinding<T = unknown>(surfaceId: string, source: FormBindableValue | undefined, defaultValue?: T): [T, (value: T) => void];

package/dist/0.9/hooks/useDataBinding.js

@@ -0,0 +1,43 @@
+import { useMemo as r, useCallback as D } from "react";
+import { useSurfaceContext as s } from "../contexts/SurfaceContext.js";
+import { useScope as g } from "../contexts/ScopeContext.js";
+import { resolveString as d, resolveValue as h, isPathBinding as c } from "../utils/dataBinding.js";
+function S(n, t, a) {
+  const { getDataModel: e } = s(), { basePath: i } = g();
+  return r(() => {
+    const o = e(n);
+    return h(t, o, i, a);
+  }, [e, n, t, i, a]);
+}
+function v(n, t, a = "") {
+  const { getDataModel: e } = s(), { basePath: i } = g();
+  return r(() => {
+    const o = e(n);
+    return d(t, o, i, a);
+  }, [e, n, t, i, a]);
+}
+function $(n) {
+  const { getDataModel: t } = s();
+  return r(() => t(n), [t, n]);
+}
+function x(n, t, a) {
+  const { getDataModel: e, setDataValue: i } = s(), { basePath: o } = g(), l = r(() => {
+    const p = e(n);
+    return h(t, p, o, a);
+  }, [e, n, t, o, a]), m = D(
+    (p) => {
+      if (c(t)) {
+        const M = t.path.startsWith("/") ? t.path : o ? `${o}/${t.path}` : `/${t.path}`;
+        i(n, M, p);
+      }
+    },
+    [i, n, t, o]
+  );
+  return [l, m];
+}
+export {
+  S as useDataBinding,
+  $ as useDataModel,
+  x as useFormBinding,
+  v as useStringBinding
+};

package/dist/0.9/hooks/useDispatchAction.d.ts

@@ -0,0 +1,22 @@
+import { Action } from '@a2ui-sdk/types/0.9';
+/**
+ * Returns a function to dispatch actions.
+ *
+ * @returns A function that dispatches actions
+ *
+ * @example
+ * ```tsx
+ * function ButtonComponent({ surfaceId, component }) {
+ *   const dispatchAction = useDispatchAction();
+ *
+ *   const handleClick = () => {
+ *     if (component.action) {
+ *       dispatchAction(surfaceId, component.id, component.action);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleClick}>Click me</button>;
+ * }
+ * ```
+ */
+export declare function useDispatchAction(): (surfaceId: string, componentId: string, action: Action) => void;

package/dist/0.9/hooks/useDispatchAction.js

@@ -0,0 +1,17 @@
+import { useCallback as a } from "react";
+import { useActionContext as i } from "../contexts/ActionContext.js";
+import { useSurfaceContext as m } from "../contexts/SurfaceContext.js";
+import { useScope as p } from "../contexts/ScopeContext.js";
+function h() {
+  const { dispatchAction: t } = i(), { getDataModel: o } = m(), { basePath: e } = p();
+  return a(
+    (c, n, r) => {
+      const s = o(c);
+      t(c, n, r, s, e);
+    },
+    [t, o, e]
+  );
+}
+export {
+  h as useDispatchAction
+};

package/dist/0.9/hooks/useValidation.d.ts

@@ -0,0 +1,25 @@
+import { CheckRule, ValidationResult } from '@a2ui-sdk/types/0.9';
+import { ValidationFunction } from '../utils/validation';
+/**
+ * Hook for evaluating validation checks on a component.
+ *
+ * @param surfaceId - The surface ID for data model lookup
+ * @param checks - Array of check rules to evaluate
+ * @param customFunctions - Optional custom validation functions
+ * @returns ValidationResult with valid flag and error messages
+ *
+ * @example
+ * ```tsx
+ * function TextFieldComponent({ surfaceId, component }) {
+ *   const { valid, errors } = useValidation(surfaceId, component.checks);
+ *
+ *   return (
+ *     <div>
+ *       <input className={!valid ? 'error' : ''} />
+ *       {errors.map(err => <span key={err} className="error">{err}</span>)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useValidation(surfaceId: string, checks: CheckRule[] | undefined, customFunctions?: Record<string, ValidationFunction>): ValidationResult;

package/dist/0.9/hooks/useValidation.js

@@ -0,0 +1,14 @@
+import { useMemo as n } from "react";
+import { useSurfaceContext as i } from "../contexts/SurfaceContext.js";
+import { useScope as p } from "../contexts/ScopeContext.js";
+import { evaluateChecks as u } from "../utils/validation.js";
+function M(o, t, e) {
+  const { getDataModel: r } = i(), { basePath: a } = p();
+  return n(() => {
+    const m = r(o);
+    return u(t, m, a, e);
+  }, [r, o, t, a, e]);
+}
+export {
+  M as useValidation
+};

package/dist/0.9/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A2UI 0.9 React Renderer - Public API
+ *
+ * This is the main entry point for the A2UI 0.9 React renderer library.
+ * Import from '@a2ui-sdk/react/0.9'
+ *
+ * @example
+ * ```tsx
+ * import { A2UIProvider, A2UIRenderer, A2UIMessage, A2UIAction } from '@a2ui-sdk/react/0.9'
+ *
+ * function App() {
+ *   const messages: A2UIMessage[] = [...]
+ *   const handleAction = (action: A2UIAction) => {
+ *     console.log('Action:', action)
+ *   }
+ *   return (
+ *     <A2UIProvider messages={messages} onAction={handleAction}>
+ *       <A2UIRenderer />
+ *     </A2UIProvider>
+ *   )
+ * }
+ * ```
+ */
+export type { A2UIMessage, CreateSurfacePayload, UpdateComponentsPayload, UpdateDataModelPayload, DeleteSurfacePayload, Component, TextComponent, ImageComponent, IconComponent, VideoComponent, AudioPlayerComponent, DividerComponent, RowComponent, ColumnComponent, ListComponent, CardComponent, TabsComponent, ModalComponent, ButtonComponent, TextFieldComponent, CheckBoxComponent, ChoicePickerComponent, SliderComponent, DateTimeInputComponent, DynamicValue, DynamicString, DynamicNumber, DynamicBoolean, DynamicStringList, ChildList, TemplateBinding, Action, ActionPayload as A2UIAction, ActionHandler, CheckRule, Checkable, ValidationResult, ScopeValue, DataModel, } from '@a2ui-sdk/types/0.9';
+export type { A2UIProviderProps, ComponentsMap } from './contexts/A2UIProvider';
+export type { A2UIRendererProps } from './A2UIRenderer';
+export { A2UIProvider } from './contexts/A2UIProvider';
+export { A2UIRenderer } from './A2UIRenderer';
+export { ComponentRenderer } from './components/ComponentRenderer';
+export { useDispatchAction } from './hooks/useDispatchAction';
+export { useDataBinding, useFormBinding, useStringBinding, useDataModel, } from './hooks/useDataBinding';
+export { useValidation } from './hooks/useValidation';
+export { useSurfaceContext } from './contexts/SurfaceContext';
+export { useScope, useScopeBasePath } from './contexts/ScopeContext';
+export { validationFunctions, evaluateChecks, evaluateCheckRule, type ValidationFunction, type EvaluationContext, } from './utils/validation';

package/dist/0.9/index.js

@@ -0,0 +1,26 @@
+import { A2UIProvider as r } from "./contexts/A2UIProvider.js";
+import { A2UIRenderer as n } from "./A2UIRenderer.js";
+import { ComponentRenderer as i } from "./components/ComponentRenderer.js";
+import { useDispatchAction as p } from "./hooks/useDispatchAction.js";
+import { useDataBinding as m, useDataModel as f, useFormBinding as x, useStringBinding as d } from "./hooks/useDataBinding.js";
+import { useValidation as l } from "./hooks/useValidation.js";
+import { useSurfaceContext as h } from "./contexts/SurfaceContext.js";
+import { useScope as B, useScopeBasePath as C } from "./contexts/ScopeContext.js";
+import { evaluateCheckRule as A, evaluateChecks as D, validationFunctions as R } from "./utils/validation.js";
+export {
+  r as A2UIProvider,
+  n as A2UIRenderer,
+  i as ComponentRenderer,
+  A as evaluateCheckRule,
+  D as evaluateChecks,
+  m as useDataBinding,
+  f as useDataModel,
+  p as useDispatchAction,
+  x as useFormBinding,
+  B as useScope,
+  C as useScopeBasePath,
+  d as useStringBinding,
+  h as useSurfaceContext,
+  l as useValidation,
+  R as validationFunctions
+};

package/dist/0.9/utils/dataBinding.d.ts

@@ -0,0 +1,126 @@
+import { DynamicValue, DynamicString, DataModel, FormBindableValue } from '@a2ui-sdk/types/0.9';
+/**
+ * Type guard to check if a value is a path binding.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a path binding object
+ *
+ * @example
+ * isPathBinding({ path: "/user/name" });  // true
+ * isPathBinding("literal");               // false
+ * isPathBinding({ call: "required" });    // false
+ */
+export declare function isPathBinding(value: FormBindableValue | undefined | null): value is {
+    path: string;
+};
+/**
+ * Type guard to check if a value is a function call.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a function call object
+ */
+export declare function isFunctionCall(value: FormBindableValue | undefined | null): value is {
+    call: string;
+    args?: Record<string, DynamicValue>;
+};
+/**
+ * Gets the path from a dynamic value, or undefined if it's not a path binding.
+ *
+ * @param value - The dynamic value
+ * @returns The path string or undefined
+ */
+export declare function getBindingPath(value: FormBindableValue | undefined | null): string | undefined;
+/**
+ * Resolves a dynamic value to its actual value.
+ *
+ * Resolution order:
+ * 1. If value is a path binding object → resolve from data model
+ * 2. If value is a function call → return undefined (function calls not evaluated here)
+ * 3. Otherwise → return literal value
+ *
+ * @param value - The dynamic value (literal, path binding, or function call)
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @param defaultValue - Default value if undefined or path not found
+ * @returns The resolved value
+ *
+ * @example
+ * // Literal values
+ * resolveValue("Hello", {});        // "Hello"
+ * resolveValue(42, {});             // 42
+ * resolveValue(true, {});           // true
+ *
+ * // Path bindings
+ * const model = { user: { name: "John" } };
+ * resolveValue({ path: "/user/name" }, model);           // "John"
+ * resolveValue({ path: "name" }, model, "/user");        // "John" (relative)
+ * resolveValue({ path: "/nonexistent" }, model, null, "default"); // "default"
+ */
+export declare function resolveValue<T = unknown>(value: FormBindableValue | undefined | null, dataModel: DataModel, basePath?: string | null, defaultValue?: T): T;
+/**
+ * Resolves a DynamicString value to a string.
+ * This is a convenience wrapper for string values.
+ *
+ * Supports interpolation: if the string contains `${...}` expressions,
+ * they will be replaced with values from the data model.
+ *
+ * @param value - The dynamic string value
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @param defaultValue - Default value if undefined or path not found
+ * @returns The resolved string
+ *
+ * @example
+ * // Simple string
+ * resolveString("Hello", {});  // "Hello"
+ *
+ * // Path binding
+ * resolveString({ path: "/user/name" }, { user: { name: "John" } });  // "John"
+ *
+ * // Interpolation
+ * resolveString("Hello, ${/user/name}!", { user: { name: "John" } });  // "Hello, John!"
+ */
+export declare function resolveString(value: DynamicString | undefined | null, dataModel: DataModel, basePath?: string | null, defaultValue?: string): string;
+/**
+ * Resolves a dynamic number value.
+ *
+ * @param value - The dynamic number value
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @param defaultValue - Default value if undefined or path not found
+ * @returns The resolved number
+ */
+export declare function resolveNumber(value: number | {
+    path: string;
+} | undefined | null, dataModel: DataModel, basePath?: string | null, defaultValue?: number): number;
+/**
+ * Resolves a dynamic boolean value.
+ *
+ * @param value - The dynamic boolean value
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @param defaultValue - Default value if undefined or path not found
+ * @returns The resolved boolean
+ */
+export declare function resolveBoolean(value: boolean | {
+    path: string;
+} | undefined | null, dataModel: DataModel, basePath?: string | null, defaultValue?: boolean): boolean;
+/**
+ * Resolves action context values to a plain object.
+ * All path bindings are resolved to their actual values.
+ *
+ * @param context - Object with dynamic values
+ * @param dataModel - The data model for path lookups
+ * @param basePath - Optional base path for relative path resolution
+ * @returns A plain object with resolved context values
+ *
+ * @example
+ * const context = {
+ *   name: { path: "/user/name" },
+ *   action: "submit",
+ *   count: 42
+ * };
+ * resolveContext(context, { user: { name: "John" } });
+ * // Returns: { name: "John", action: "submit", count: 42 }
+ */
+export declare function resolveContext(context: Record<string, DynamicValue> | undefined, dataModel: DataModel, basePath?: string | null): Record<string, unknown>;