a2ui-react 0.2.1 → 0.3.0

package/README.md

@@ -20,12 +20,31 @@ yarn add a2ui-react
 
 ## Setup
 
-Import the default theme CSS in your app entry point:
+### 1. Configure Tailwind v4 (Critical)
+
+Add the `@source` directive to your CSS so Tailwind scans the component classes:
+
+```css
+@import 'tailwindcss';
+@source "../node_modules/a2ui-react/dist";
+```
+
+Without this, Tailwind v4 won't scan node_modules and components render unstyled.
+
+### 2. Import Theme CSS
+
+Import the theme CSS in your app entry point:
 
 ```tsx
 import 'a2ui-react/theme.css'
 ```
 
+> **Vite users**: If the import doesn't resolve, copy the CSS locally:
+> ```bash
+> cp node_modules/a2ui-react/dist/theme.css src/a2ui-theme.css
+> ```
+> Then import `'./a2ui-theme.css'` instead.
+
 Or if using your own Tailwind setup, ensure your CSS includes the [shadcn/ui theme variables](https://ui.shadcn.com/docs/theming).
 
 ## Quick Start
@@ -193,7 +212,45 @@ function App() {
 ## Requirements
 
 - React 18.0.0+ or React 19.0.0+
-- Tailwind CSS (for styling)
+- Tailwind CSS v4 (for styling)
+
+## Important Notes
+
+### Component ID Format
+
+The `id` must be present both in the update wrapper AND inside the component object:
+
+```tsx
+// ✅ Correct
+{
+  id: 'greeting',
+  component: {
+    type: 'Text',
+    id: 'greeting',  // Required inside component
+    content: 'Hello!'
+  }
+}
+
+// ❌ Won't work - missing id inside component
+{
+  id: 'greeting',
+  component: {
+    type: 'Text',
+    content: 'Hello!'
+  }
+}
+```
+
+### a2ui-go Compatibility
+
+If using [a2ui-go](https://github.com/burka/a2ui-go) as your backend, you'll need to transform messages:
+
+| a2ui-go format | a2ui-react format |
+|----------------|-------------------|
+| `surfaceUpdate.components` | `surfaceUpdate.updates` |
+| `{"id":"x", "Text":{...}}` | `{"id":"x", "component":{"type":"Text",...}}` |
+| `text` field | `content` field |
+| `usageHint` field | `style` field |
 
 ## License
 

package/dist/index.js

@@ -168,6 +168,32 @@ var c = {
     ...props
   })
 };
+function isV09Format(update) {
+  return typeof update.component === "string";
+}
+function normalizeComponentUpdate(update) {
+  if (isV09Format(update)) {
+    const { id, component: type, ...rest } = update;
+    return { id, type, ...rest };
+  }
+  const component = update.component;
+  if (!component.id) {
+    component.id = update.id;
+  }
+  if (component.type === "Text") {
+    const textComponent = component;
+    if (textComponent.content && !textComponent.text) {
+      textComponent.text = textComponent.content;
+    }
+  }
+  return component;
+}
+function getTextContent(component) {
+  return component.text ?? component.content ?? "";
+}
+function getComponentsArray(msg) {
+  return msg.components ?? msg.updates ?? [];
+}
 var MessageParseError = class extends Error {
   constructor(message) {
     super(message);
@@ -200,6 +226,17 @@ function validateBeginRendering(msg) {
     throw new MessageParseError("beginRendering.style must be an object if provided");
   }
 }
+function validateComponentUpdate(update, context) {
+  if (!isObject(update)) {
+    throw new MessageParseError(`${context}[] must be objects`);
+  }
+  if (!isNonEmptyString(update.id)) {
+    throw new MessageParseError(`${context}[].id must be a non-empty string`);
+  }
+  if (typeof update.component !== "string" && !isObject(update.component)) {
+    throw new MessageParseError(`${context}[].component must be a string (v0.9) or object (legacy)`);
+  }
+}
 function validateSurfaceUpdate(msg) {
   if (!isObject(msg)) {
     throw new MessageParseError("surfaceUpdate must be an object");
@@ -207,19 +244,12 @@ function validateSurfaceUpdate(msg) {
   if (!isNonEmptyString(msg.surfaceId)) {
     throw new MessageParseError("surfaceUpdate.surfaceId must be a non-empty string");
   }
-  if (!isArray(msg.updates)) {
-    throw new MessageParseError("surfaceUpdate.updates must be an array");
+  const components = msg.updates ?? msg.components;
+  if (!isArray(components)) {
+    throw new MessageParseError("surfaceUpdate.updates (or .components) must be an array");
   }
-  for (const update of msg.updates) {
-    if (!isObject(update)) {
-      throw new MessageParseError("surfaceUpdate.updates[] must be objects");
-    }
-    if (!isNonEmptyString(update.id)) {
-      throw new MessageParseError("surfaceUpdate.updates[].id must be a non-empty string");
-    }
-    if (!isObject(update.component)) {
-      throw new MessageParseError("surfaceUpdate.updates[].component must be an object");
-    }
+  for (const update of components) {
+    validateComponentUpdate(update, "surfaceUpdate.updates");
   }
 }
 function validateDataModelUpdate(msg) {
@@ -283,15 +313,7 @@ function validateUpdateComponents(msg) {
     throw new MessageParseError("updateComponents.components must be an array");
   }
   for (const component of msg.components) {
-    if (!isObject(component)) {
-      throw new MessageParseError("updateComponents.components[] must be objects");
-    }
-    if (!isNonEmptyString(component.id)) {
-      throw new MessageParseError("updateComponents.components[].id must be a non-empty string");
-    }
-    if (!isObject(component.component)) {
-      throw new MessageParseError("updateComponents.components[].component must be an object");
-    }
+    validateComponentUpdate(component, "updateComponents.components");
   }
 }
 function validateUpdateDataModel(msg) {
@@ -622,15 +644,9 @@ function processMessage(message, store) {
       data: {}
     });
   } else if (isUpdateComponentsMessage(message) || isSurfaceUpdateMessage(message)) {
-    let surfaceId;
-    let componentUpdates;
-    if (isUpdateComponentsMessage(message)) {
-      surfaceId = message.updateComponents.surfaceId;
-      componentUpdates = message.updateComponents.components;
-    } else {
-      surfaceId = message.surfaceUpdate.surfaceId;
-      componentUpdates = message.surfaceUpdate.updates;
-    }
+    const payload = isUpdateComponentsMessage(message) ? message.updateComponents : message.surfaceUpdate;
+    const surfaceId = payload.surfaceId;
+    const componentUpdates = getComponentsArray(payload);
     const surface = store.getSurface(surfaceId);
     if (!surface) {
       console.warn(`Surface not found for update: ${surfaceId}`);
@@ -638,7 +654,8 @@ function processMessage(message, store) {
     }
     const updatedComponents = { ...surface.components };
     for (const update of componentUpdates) {
-      updatedComponents[update.id] = update.component;
+      const component = normalizeComponentUpdate(update);
+      updatedComponents[update.id] = component;
     }
     surface.components = updatedComponents;
     store.setSurface(surfaceId, { ...surface });
@@ -6054,7 +6071,7 @@ var AnimatedTextOverride = {
   type: "Text",
   render: ({ component, data }) => {
     const className = styleClasses6[component.style || "body"] || styleClasses6.body;
-    let content = component.content;
+    let content = getTextContent(component);
     if (component.dataPath) {
       const value = data.get(component.dataPath);
       if (value !== void 0) {
@@ -7541,8 +7558,9 @@ var ImageRenderer = {
 var TextRenderer = {
   type: "Text",
   render: ({ component, data }) => {
-    const { content, style = "body", dataPath } = component;
-    const displayContent = dataPath ? data.get(dataPath) ?? content : content;
+    const { style = "body", dataPath } = component;
+    const textContent = getTextContent(component);
+    const displayContent = dataPath ? data.get(dataPath) ?? textContent : textContent;
     const styleMap = {
       h1: { tag: "h1", className: "text-4xl font-bold" },
       h2: { tag: "h2", className: "text-3xl font-semibold" },
@@ -7586,7 +7604,7 @@ var TextRenderer = {
               component: {
                 type: "Text",
                 id: "h1",
-                content: "Heading 1 - Large Title",
+                text: "Heading 1 - Large Title",
                 style: "h1"
               }
             },
@@ -7595,7 +7613,7 @@ var TextRenderer = {
               component: {
                 type: "Text",
                 id: "h2",
-                content: "Heading 2 - Section Title",
+                text: "Heading 2 - Section Title",
                 style: "h2"
               }
             },
@@ -7604,7 +7622,7 @@ var TextRenderer = {
               component: {
                 type: "Text",
                 id: "h3",
-                content: "Heading 3 - Subsection",
+                text: "Heading 3 - Subsection",
                 style: "h3"
               }
             },
@@ -7613,7 +7631,7 @@ var TextRenderer = {
               component: {
                 type: "Text",
                 id: "h4",
-                content: "Heading 4 - Component Title",
+                text: "Heading 4 - Component Title",
                 style: "h4"
               }
             },
@@ -7622,7 +7640,7 @@ var TextRenderer = {
               component: {
                 type: "Text",
                 id: "h5",
-                content: "Heading 5 - Small Title",
+                text: "Heading 5 - Small Title",
                 style: "h5"
               }
             },
@@ -7631,7 +7649,7 @@ var TextRenderer = {
               component: {
                 type: "Text",
                 id: "body",
-                content: "Body text paragraph with regular content and default styling.",
+                text: "Body text paragraph with regular content and default styling.",
                 style: "body"
               }
             },
@@ -7640,7 +7658,7 @@ var TextRenderer = {
               component: {
                 type: "Text",
                 id: "caption",
-                content: "Caption text - muted and small",
+                text: "Caption text - muted and small",
                 style: "caption"
               }
             }