@a2ui-sdk/react 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @a2ui-sdk/react
 
-React implementation for rendering A2UI protocol. This package provides React components and hooks for integrating A2UI surfaces into your application.
+React implementation for rendering A2UI protocol. This package provides React components and hooks for integrating A2UI renderer into your application.
 
 ## Installation
 
@@ -220,6 +220,7 @@ import {
   useSurfaceContext,
   useScope,
   useScopeBasePath,
+  useA2UIMessageHandler,
 
   // Context Providers & Hooks
   ActionProvider,
@@ -245,6 +246,7 @@ import {
   type ValidationResult,
   type ScopeValue,
   type DataModel,
+  type A2UIMessageHandler,
 } from '@a2ui-sdk/react/0.9'
 ```
 
@@ -268,6 +270,7 @@ import {
   useDataModelContext,
   useScope,
   useScopeBasePath,
+  useA2UIMessageHandler,
 
   // Context Providers & Hooks
   ActionProvider,
@@ -282,6 +285,7 @@ import {
   type Action,
   type ValueSource,
   type ScopeValue,
+  type A2UIMessageHandler,
 } from '@a2ui-sdk/react/0.8'
 ```
 
@@ -294,8 +298,92 @@ import { v0_8, v0_9 } from '@a2ui-sdk/react'
 const { A2UIProvider, A2UIRenderer } = v0_9
 ```
 
+## Incremental Message Handling
+
+**New in v0.8 & v0.9**: For applications that receive messages incrementally (e.g., via WebSocket or SSE), you can use the `useA2UIMessageHandler` hook to push new messages without clearing state. This preserves user edits.
+
+### Problem
+
+When using the `messages` prop on `A2UIProvider`, changing the messages array causes the provider to clear all state and reprocess from scratch. This loses user edits:
+
+```tsx
+// ❌ This loses user edits when new messages arrive
+function App() {
+  const [messages, setMessages] = useState<A2UIMessage[]>([])
+
+  useEffect(() => {
+    const ws = new WebSocket('ws://example.com')
+    ws.onmessage = (event) => {
+      const newMessage = JSON.parse(event.data)
+      setMessages((prev) => [...prev, newMessage]) // Triggers full clear & reprocess!
+    }
+  }, [])
+
+  return (
+    <A2UIProvider messages={messages}>
+      <A2UIRenderer onAction={handleAction} />
+    </A2UIProvider>
+  )
+}
+```
+
+### Solution
+
+Use `useA2UIMessageHandler` hook to process messages incrementally:
+
+```tsx
+import {
+  A2UIProvider,
+  A2UIRenderer,
+  useA2UIMessageHandler,
+  type A2UIMessage,
+  type A2UIAction,
+} from '@a2ui-sdk/react/0.8' // or '@a2ui-sdk/react/0.9'
+
+function App() {
+  const handleAction = (action: A2UIAction) => {
+    console.log('Action:', action)
+  }
+
+  return (
+    <A2UIProvider>
+      <MessageHandler>
+        <A2UIRenderer onAction={handleAction} />
+      </MessageHandler>
+    </A2UIProvider>
+  )
+}
+
+function MessageHandler({ children }: { children: React.ReactNode }) {
+  const { processMessage } = useA2UIMessageHandler()
+
+  useEffect(() => {
+    // Listen for incremental updates
+    const ws = new WebSocket('ws://example.com')
+    ws.onmessage = (event) => {
+      const newMessage = JSON.parse(event.data)
+      processMessage(newMessage) // Incremental - preserves user edits!
+    }
+
+    return () => ws.close()
+  }, [processMessage])
+
+  return <>{children}</>
+}
+```
+
+The `useA2UIMessageHandler` hook returns:
+
+- **`processMessage(message: A2UIMessage)`**: Process a single message incrementally
+- **`processMessages(messages: A2UIMessage[])`**: Process multiple messages in order
+- **`clear()`**: Clear all surfaces and state (rarely needed)
+
 ## Hooks
 
+### useA2UIMessageHandler
+
+See [Incremental Message Handling](#incremental-message-handling) above for usage details.
+
 ### useDataBinding
 
 Resolves a dynamic value from the data model:

package/dist/0.8/components/interactive/CheckBoxComponent.js

@@ -1,27 +1,28 @@
-import { jsxs as l, jsx as t } from "react/jsx-runtime";
-import { memo as p, useCallback as C } from "react";
-import { useDataBinding as d, useFormBinding as x } from "../../hooks/useDataBinding.js";
-import { Checkbox as k } from "../../../components/ui/checkbox.js";
-import { Label as f } from "../../../components/ui/label.js";
-import { cn as b } from "../../../lib/utils.js";
-const g = p(function({
+import { jsxs as p, jsx as m } from "react/jsx-runtime";
+import { memo as x, useCallback as C } from "react";
+import { useDataBinding as k, useFormBinding as d } from "../../hooks/useDataBinding.js";
+import { useScopeBasePath as f } from "../../contexts/ScopeContext.js";
+import { Checkbox as b } from "../../../components/ui/checkbox.js";
+import { Label as g } from "../../../components/ui/label.js";
+import { cn as u } from "../../../lib/utils.js";
+const B = x(function({
   surfaceId: e,
-  componentId: m,
-  label: r,
-  value: s
+  componentId: o,
+  label: s,
+  value: a
 }) {
-  const o = d(e, r, ""), [i, n] = x(e, s, !1), a = C(
-    (h) => {
-      n(h);
+  const c = k(e, s, ""), [i, t] = d(e, a, !1), r = f(), h = C(
+    (l) => {
+      t(l);
     },
-    [n]
-  ), c = `checkbox-${m}`;
-  return /* @__PURE__ */ l("div", { className: b("flex items-center gap-3"), children: [
-    /* @__PURE__ */ t(k, { id: c, checked: i, onCheckedChange: a }),
-    o && /* @__PURE__ */ t(f, { htmlFor: c, className: "cursor-pointer", children: o })
+    [t]
+  ), n = r ? `checkbox-${o}-${r.replace(/\//g, "-")}` : `checkbox-${o}`;
+  return /* @__PURE__ */ p("div", { className: u("flex items-center gap-3"), children: [
+    /* @__PURE__ */ m(b, { id: n, checked: i, onCheckedChange: h }),
+    c && /* @__PURE__ */ m(g, { htmlFor: n, className: "cursor-pointer", children: c })
   ] });
 });
-g.displayName = "A2UI.CheckBox";
+B.displayName = "A2UI.CheckBox";
 export {
-  g as CheckBoxComponent
+  B as CheckBoxComponent
 };

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

@@ -5,8 +5,12 @@ import { Catalog } from '../standard-catalog';
  * Props for A2UIProvider.
  */
 export interface A2UIProviderProps {
-    /** Array of A2UI messages to render */
-    messages: A2UIMessage[];
+    /**
+     * Array of A2UI messages to render.
+     * When this prop changes, all state is cleared and messages are reprocessed.
+     * For incremental updates, use useA2UIMessageHandler hook inside the provider.
+     */
+    messages?: A2UIMessage[];
     /**
      * Catalog containing components and functions.
      * Use `standardCatalog` from '@a2ui-sdk/react/0.8/standard-catalog' as base.

package/dist/0.8/contexts/A2UIProvider.js

@@ -1,27 +1,26 @@
-import { jsx as o, Fragment as i } from "react/jsx-runtime";
-import { useEffect as s } from "react";
-import { SurfaceProvider as a } from "./SurfaceContext.js";
-import { DataModelProvider as f } from "./DataModelContext.js";
-import { ComponentsMapProvider as c } from "./ComponentsMapContext.js";
-import { useA2UIMessageHandler as m } from "../hooks/useA2UIMessageHandler.js";
-import { standardCatalog as p } from "../standard-catalog/index.js";
-function d({
+import { jsx as o, Fragment as n } from "react/jsx-runtime";
+import { useEffect as f } from "react";
+import { SurfaceProvider as c } from "./SurfaceContext.js";
+import { DataModelProvider as a } from "./DataModelContext.js";
+import { ComponentsMapProvider as m } from "./ComponentsMapContext.js";
+import { useA2UIMessageHandler as p } from "../hooks/useA2UIMessageHandler.js";
+import { standardCatalog as d } from "../standard-catalog/index.js";
+function l({
   messages: r,
-  children: n
+  children: t
 }) {
-  const { processMessages: e, clear: t } = m();
-  return s(() => {
-    t(), r && r.length > 0 && e(r);
-  }, [r, e, t]), /* @__PURE__ */ o(i, { children: n });
+  const { processMessages: e, clear: i } = p();
+  return f(() => {
+    r !== void 0 && (i(), r && r.length > 0 && e(r));
+  }, [r, i, e]), /* @__PURE__ */ o(n, { children: t });
 }
-function A({
+function C({
   messages: r,
-  catalog: n,
+  catalog: t,
   children: e
 }) {
-  const t = r ?? [];
-  return /* @__PURE__ */ o(a, { children: /* @__PURE__ */ o(f, { children: /* @__PURE__ */ o(c, { components: (n ?? p).components, children: /* @__PURE__ */ o(d, { messages: t, children: e }) }) }) });
+  return /* @__PURE__ */ o(c, { children: /* @__PURE__ */ o(a, { children: /* @__PURE__ */ o(m, { components: (t ?? d).components, children: /* @__PURE__ */ o(l, { messages: r, children: e }) }) }) });
 }
 export {
-  A as A2UIProvider
+  C as A2UIProvider
 };

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

@@ -21,9 +21,6 @@ export interface A2UIMessageHandler {
  *   const { processMessage, processMessages, clear } = useA2UIMessageHandler();
  *
  *   useEffect(() => {
- *     // Process initial messages
- *     processMessages(initialMessages);
- *
  *     // Listen for SSE updates
  *     const handler = (event) => {
  *       processMessage(event.detail.message);

package/dist/0.8/index.d.ts

@@ -45,3 +45,5 @@ export { useDataBinding, useFormBinding } from './hooks/useDataBinding';
 export { useSurfaceContext } from './contexts/SurfaceContext';
 export { useDataModelContext } from './contexts/DataModelContext';
 export { ActionProvider, useActionContext } from './contexts/ActionContext';
+export { useA2UIMessageHandler } from './hooks/useA2UIMessageHandler';
+export type { A2UIMessageHandler } from './hooks/useA2UIMessageHandler';

package/dist/0.8/index.js

@@ -1,22 +1,24 @@
 import { A2UIProvider as r } from "./contexts/A2UIProvider.js";
 import { A2UIRenderer as n } from "./A2UIRenderer.js";
-import { ComponentRenderer as m } from "./components/ComponentRenderer.js";
-import { standardCatalog as a } from "./standard-catalog/index.js";
-import { useDispatchAction as i } from "./hooks/useDispatchAction.js";
-import { useDataBinding as s, useFormBinding as u } from "./hooks/useDataBinding.js";
-import { useSurfaceContext as A } from "./contexts/SurfaceContext.js";
+import { ComponentRenderer as a } from "./components/ComponentRenderer.js";
+import { standardCatalog as p } from "./standard-catalog/index.js";
+import { useDispatchAction as s } from "./hooks/useDispatchAction.js";
+import { useDataBinding as i, useFormBinding as u } from "./hooks/useDataBinding.js";
+import { useSurfaceContext as c } from "./contexts/SurfaceContext.js";
 import { useDataModelContext as g } from "./contexts/DataModelContext.js";
-import { ActionProvider as l, useActionContext as v } from "./contexts/ActionContext.js";
+import { ActionProvider as D, useActionContext as I } from "./contexts/ActionContext.js";
+import { useA2UIMessageHandler as v } from "./hooks/useA2UIMessageHandler.js";
 export {
   r as A2UIProvider,
   n as A2UIRenderer,
-  l as ActionProvider,
-  m as ComponentRenderer,
-  a as standardCatalog,
-  v as useActionContext,
-  s as useDataBinding,
+  D as ActionProvider,
+  a as ComponentRenderer,
+  p as standardCatalog,
+  v as useA2UIMessageHandler,
+  I as useActionContext,
+  i as useDataBinding,
   g as useDataModelContext,
-  i as useDispatchAction,
+  s as useDispatchAction,
   u as useFormBinding,
-  A as useSurfaceContext
+  c as useSurfaceContext
 };

package/dist/0.9/components/interactive/CheckBoxComponent.js

@@ -1,45 +1,46 @@
 import { jsxs as m, jsx as e } from "react/jsx-runtime";
-import { memo as v, useCallback as g } from "react";
-import { useStringBinding as u, useFormBinding as b } from "../../hooks/useDataBinding.js";
-import { useValidation as B } from "../../hooks/useValidation.js";
-import { Checkbox as N } from "../../../components/ui/checkbox.js";
-import { Label as j } from "../../../components/ui/label.js";
-import { cn as y } from "../../../lib/utils.js";
-const F = v(function({
+import { memo as u, useCallback as v } from "react";
+import { useStringBinding as b, useFormBinding as B } from "../../hooks/useDataBinding.js";
+import { useValidation as N } from "../../hooks/useValidation.js";
+import { useScopeBasePath as $ } from "../../contexts/ScopeContext.js";
+import { Checkbox as j } from "../../../components/ui/checkbox.js";
+import { Label as y } from "../../../components/ui/label.js";
+import { cn as F } from "../../../lib/utils.js";
+const P = u(function({
   surfaceId: o,
-  componentId: s,
-  label: a,
+  componentId: r,
+  label: h,
   value: d,
-  checks: h,
-  weight: t
+  checks: p,
+  weight: c
 }) {
-  const r = u(o, a, ""), [p, i] = b(
+  const i = b(o, h, ""), [x, n] = B(
     o,
     d,
     !1
-  ), { valid: x, errors: c } = B(o, h), f = g(
-    (n) => {
-      i(n);
+  ), { valid: f, errors: s } = N(o, p), a = $(), C = v(
+    (t) => {
+      n(t);
     },
-    [i]
-  ), l = `checkbox-${s}`, C = t ? { flexGrow: t } : void 0;
-  return /* @__PURE__ */ m("div", { className: y("flex flex-col gap-1"), style: C, children: [
+    [n]
+  ), l = a ? `checkbox-${r}-${a.replace(/\//g, "-")}` : `checkbox-${r}`, k = c ? { flexGrow: c } : void 0;
+  return /* @__PURE__ */ m("div", { className: F("flex flex-col gap-1"), style: k, children: [
     /* @__PURE__ */ m("div", { className: "flex items-center gap-3", children: [
       /* @__PURE__ */ e(
-        N,
+        j,
         {
           id: l,
-          checked: p,
-          onCheckedChange: f,
-          "aria-invalid": !x
+          checked: x,
+          onCheckedChange: C,
+          "aria-invalid": !f
         }
       ),
-      r && /* @__PURE__ */ e(j, { htmlFor: l, className: "cursor-pointer", children: r })
+      i && /* @__PURE__ */ e(y, { htmlFor: l, className: "cursor-pointer", children: i })
     ] }),
-    c.length > 0 && /* @__PURE__ */ e("div", { className: "text-sm text-destructive ml-6", children: c.map((n, k) => /* @__PURE__ */ e("p", { children: n }, k)) })
+    s.length > 0 && /* @__PURE__ */ e("div", { className: "text-sm text-destructive ml-6", children: s.map((t, g) => /* @__PURE__ */ e("p", { children: t }, g)) })
   ] });
 });
-F.displayName = "A2UI.CheckBox";
+P.displayName = "A2UI.CheckBox";
 export {
-  F as CheckBoxComponent
+  P as CheckBoxComponent
 };

package/dist/0.9/contexts/A2UIProvider.d.ts

@@ -5,8 +5,12 @@ import { Catalog } from '../standard-catalog';
  * Props for A2UIProvider.
  */
 export interface A2UIProviderProps {
-    /** Array of A2UI messages to render */
-    messages: A2UIMessage[];
+    /**
+     * Array of A2UI messages to render.
+     * When this prop changes, all state is cleared and messages are reprocessed.
+     * For incremental updates, use useA2UIMessageHandler hook inside the provider.
+     */
+    messages?: A2UIMessage[];
     /**
      * Catalog containing components and functions.
      * Use `standardCatalog` from '@a2ui-sdk/react/0.9/standard-catalog' as base.

package/dist/0.9/contexts/A2UIProvider.js

@@ -1,26 +1,25 @@
-import { jsx as t, Fragment as s } from "react/jsx-runtime";
+import { jsx as e, Fragment as i } from "react/jsx-runtime";
 import { useEffect as f } from "react";
-import { SurfaceProvider as a } from "./SurfaceContext.js";
-import { ComponentsMapProvider as c } from "./ComponentsMapContext.js";
-import { useA2UIMessageHandler as i } from "../hooks/useA2UIMessageHandler.js";
-import { standardCatalog as m } from "../standard-catalog/index.js";
-function p({
+import { SurfaceProvider as c } from "./SurfaceContext.js";
+import { ComponentsMapProvider as a } from "./ComponentsMapContext.js";
+import { useA2UIMessageHandler as m } from "../hooks/useA2UIMessageHandler.js";
+import { standardCatalog as p } from "../standard-catalog/index.js";
+function d({
   messages: o,
-  children: n
+  children: t
 }) {
-  const { processMessages: r, clear: e } = i();
+  const { processMessages: r, clear: n } = m();
   return f(() => {
-    e(), o && o.length > 0 && r(o);
-  }, [o, r, e]), /* @__PURE__ */ t(s, { children: n });
+    o !== void 0 && (n(), o && o.length > 0 && r(o));
+  }, [o, n, r]), /* @__PURE__ */ e(i, { children: t });
 }
-function P({
+function M({
   messages: o,
-  catalog: n,
+  catalog: t,
   children: r
 }) {
-  const e = o ?? [];
-  return /* @__PURE__ */ t(a, { children: /* @__PURE__ */ t(c, { components: (n ?? m).components, children: /* @__PURE__ */ t(p, { messages: e, children: r }) }) });
+  return /* @__PURE__ */ e(c, { children: /* @__PURE__ */ e(a, { components: (t ?? p).components, children: /* @__PURE__ */ e(d, { messages: o, children: r }) }) });
 }
 export {
-  P as A2UIProvider
+  M as A2UIProvider
 };

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

@@ -24,9 +24,6 @@ export interface A2UIMessageHandler {
  *   const { processMessage, processMessages, clear } = useA2UIMessageHandler();
  *
  *   useEffect(() => {
- *     // Process initial messages
- *     processMessages(initialMessages);
- *
  *     // Listen for SSE updates
  *     const handler = (event) => {
  *       processMessage(JSON.parse(event.data));

package/dist/0.9/index.d.ts

@@ -35,3 +35,5 @@ export { useValidation } from './hooks/useValidation';
 export { useSurfaceContext } from './contexts/SurfaceContext';
 export { useScope, useScopeBasePath } from './contexts/ScopeContext';
 export { ActionProvider, useActionContext } from './contexts/ActionContext';
+export { useA2UIMessageHandler } from './hooks/useA2UIMessageHandler';
+export type { A2UIMessageHandler } from './hooks/useA2UIMessageHandler';

package/dist/0.9/index.js

@@ -1,27 +1,29 @@
 import { A2UIProvider as r } from "./contexts/A2UIProvider.js";
 import { A2UIRenderer as n } from "./A2UIRenderer.js";
-import { ComponentRenderer as a } from "./components/ComponentRenderer.js";
-import { standardCatalog as s } from "./standard-catalog/index.js";
+import { ComponentRenderer as s } from "./components/ComponentRenderer.js";
+import { standardCatalog as p } from "./standard-catalog/index.js";
 import { useDispatchAction as x } from "./hooks/useDispatchAction.js";
 import { useDataBinding as f, useDataModel as u, useFormBinding as c, useStringBinding as g } from "./hooks/useDataBinding.js";
-import { useValidation as B } from "./hooks/useValidation.js";
-import { useSurfaceContext as S } from "./contexts/SurfaceContext.js";
-import { useScope as D, useScopeBasePath as P } from "./contexts/ScopeContext.js";
-import { ActionProvider as v, useActionContext as I } from "./contexts/ActionContext.js";
+import { useValidation as l } from "./hooks/useValidation.js";
+import { useSurfaceContext as C } from "./contexts/SurfaceContext.js";
+import { useScope as D, useScopeBasePath as I } from "./contexts/ScopeContext.js";
+import { ActionProvider as U, useActionContext as h } from "./contexts/ActionContext.js";
+import { useA2UIMessageHandler as M } from "./hooks/useA2UIMessageHandler.js";
 export {
   r as A2UIProvider,
   n as A2UIRenderer,
-  v as ActionProvider,
-  a as ComponentRenderer,
-  s as standardCatalog,
-  I as useActionContext,
+  U as ActionProvider,
+  s as ComponentRenderer,
+  p as standardCatalog,
+  M as useA2UIMessageHandler,
+  h as useActionContext,
   f as useDataBinding,
   u as useDataModel,
   x as useDispatchAction,
   c as useFormBinding,
   D as useScope,
-  P as useScopeBasePath,
+  I as useScopeBasePath,
   g as useStringBinding,
-  S as useSurfaceContext,
-  B as useValidation
+  C as useSurfaceContext,
+  l as useValidation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2ui-sdk/react",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A2UI SDK for React",
   "homepage": "https://a2ui-sdk.js.org/",
   "repository": {
@@ -66,8 +66,8 @@
     "vitest": "^4.0.16"
   },
   "dependencies": {
-    "@a2ui-sdk/types": "0.3.0",
-    "@a2ui-sdk/utils": "0.3.0",
+    "@a2ui-sdk/types": "0.4.0",
+    "@a2ui-sdk/utils": "0.4.0",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-label": "^2.1.8",