@easyops-cn/a2ui-react 0.0.0

package/src/0.8/index.ts

@@ -0,0 +1,38 @@
+/**
+ * A2UI React Renderer - Public API
+ *
+ * This is the main entry point for the A2UI React renderer library.
+ * Import from '@easyops-cn/a2ui-react/0.8'
+ *
+ * @example
+ * ```tsx
+ * import { A2UIRender, A2UIMessage, A2UIAction } from '@easyops-cn/a2ui-react/0.8'
+ *
+ * function App() {
+ *   const messages: A2UIMessage[] = [...]
+ *   const handleAction = (action: A2UIAction) => {
+ *     console.log('Action:', action)
+ *   }
+ *   return <A2UIRender messages={messages} onAction={handleAction} />
+ * }
+ * ```
+ */
+
+// ============ Types ============
+
+export type {
+  A2UIMessage,
+  ActionPayload as A2UIAction,
+  Action,
+  ValueSource,
+} from './types'
+
+// ============ Components ============
+
+export { A2UIRender } from './A2UIRender'
+export { ComponentRenderer } from './components/ComponentRenderer'
+
+// ============ Hooks ============
+
+export { useDispatchAction } from './hooks/useDispatchAction'
+export { useDataBinding, useFormBinding } from './hooks/useDataBinding'

package/src/0.8/schemas/client_to_server.json

@@ -0,0 +1,50 @@
+{
+  "title": "A2UI (Agent to UI) Client-to-Server Event Schema",
+  "description": "Describes a JSON payload for a client-to-server event message.",
+  "type": "object",
+  "minProperties": 1,
+  "maxProperties": 1,
+  "properties": {
+    "userAction": {
+      "type": "object",
+      "description": "Reports a user-initiated action from a component.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The name of the action, taken from the component's action.name property."
+        },
+        "surfaceId": {
+          "type": "string",
+          "description": "The id of the surface where the event originated."
+        },
+        "sourceComponentId": {
+          "type": "string",
+          "description": "The id of the component that triggered the event."
+        },
+        "timestamp": {
+          "type": "string",
+          "format": "date-time",
+          "description": "An ISO 8601 timestamp of when the event occurred."
+        },
+        "context": {
+          "type": "object",
+          "description": "A JSON object containing the key-value pairs from the component's action.context, after resolving all data bindings.",
+          "additionalProperties": true
+        }
+      },
+      "required": [
+        "name",
+        "surfaceId",
+        "sourceComponentId",
+        "timestamp",
+        "context"
+      ]
+    },
+    "error": {
+      "type": "object",
+      "description": "Reports a client-side error. The content is flexible.",
+      "additionalProperties": true
+    }
+  },
+  "oneOf": [{ "required": ["userAction"] }, { "required": ["error"] }]
+}

package/src/0.8/schemas/server_to_client.json

@@ -0,0 +1,148 @@
+{
+  "title": "A2UI Message Schema",
+  "description": "Describes a JSON payload for an A2UI (Agent to UI) message, which is used to dynamically construct and update user interfaces. A message MUST contain exactly ONE of the action properties: 'beginRendering', 'surfaceUpdate', 'dataModelUpdate', or 'deleteSurface'.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "beginRendering": {
+      "type": "object",
+      "description": "Signals the client to begin rendering a surface with a root component and specific styles.",
+      "additionalProperties": false,
+      "properties": {
+        "surfaceId": {
+          "type": "string",
+          "description": "The unique identifier for the UI surface to be rendered."
+        },
+        "catalogId": {
+          "type": "string",
+          "description": "The identifier of the component catalog to use for this surface. If omitted, the client MUST default to the standard catalog for this A2UI version (a2ui.org:standard_catalog_0_8_0)."
+        },
+        "root": {
+          "type": "string",
+          "description": "The ID of the root component to render."
+        },
+        "styles": {
+          "type": "object",
+          "description": "Styling information for the UI.",
+          "additionalProperties": true
+        }
+      },
+      "required": ["root", "surfaceId"]
+    },
+    "surfaceUpdate": {
+      "type": "object",
+      "description": "Updates a surface with a new set of components.",
+      "additionalProperties": false,
+      "properties": {
+        "surfaceId": {
+          "type": "string",
+          "description": "The unique identifier for the UI surface to be updated. If you are adding a new surface this *must* be a new, unique identified that has never been used for any existing surfaces shown."
+        },
+        "components": {
+          "type": "array",
+          "description": "A list containing all UI components for the surface.",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "description": "Represents a *single* component in a UI widget tree. This component could be one of many supported types.",
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "The unique identifier for this component."
+              },
+              "weight": {
+                "type": "number",
+                "description": "The relative weight of this component within a Row or Column. This corresponds to the CSS 'flex-grow' property. Note: this may ONLY be set when the component is a direct descendant of a Row or Column."
+              },
+              "component": {
+                "type": "object",
+                "description": "A wrapper object that MUST contain exactly one key, which is the name of the component type. The value is an object containing the properties for that specific component.",
+                "additionalProperties": true
+              }
+            },
+            "required": ["id", "component"]
+          }
+        }
+      },
+      "required": ["surfaceId", "components"]
+    },
+    "dataModelUpdate": {
+      "type": "object",
+      "description": "Updates the data model for a surface.",
+      "additionalProperties": false,
+      "properties": {
+        "surfaceId": {
+          "type": "string",
+          "description": "The unique identifier for the UI surface this data model update applies to."
+        },
+        "path": {
+          "type": "string",
+          "description": "An optional path to a location within the data model (e.g., '/user/name'). If omitted, or set to '/', the entire data model will be replaced."
+        },
+        "contents": {
+          "type": "array",
+          "description": "An array of data entries. Each entry must contain a 'key' and exactly one corresponding typed 'value*' property.",
+          "items": {
+            "type": "object",
+            "description": "A single data entry. Exactly one 'value*' property should be provided alongside the key.",
+            "additionalProperties": false,
+            "properties": {
+              "key": {
+                "type": "string",
+                "description": "The key for this data entry."
+              },
+              "valueString": {
+                "type": "string"
+              },
+              "valueNumber": {
+                "type": "number"
+              },
+              "valueBoolean": {
+                "type": "boolean"
+              },
+              "valueMap": {
+                "description": "Represents a map as an adjacency list.",
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "description": "One entry in the map. Exactly one 'value*' property should be provided alongside the key.",
+                  "additionalProperties": false,
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "valueString": {
+                      "type": "string"
+                    },
+                    "valueNumber": {
+                      "type": "number"
+                    },
+                    "valueBoolean": {
+                      "type": "boolean"
+                    }
+                  },
+                  "required": ["key"]
+                }
+              }
+            },
+            "required": ["key"]
+          }
+        }
+      },
+      "required": ["contents", "surfaceId"]
+    },
+    "deleteSurface": {
+      "type": "object",
+      "description": "Signals the client to delete the surface identified by 'surfaceId'.",
+      "additionalProperties": false,
+      "properties": {
+        "surfaceId": {
+          "type": "string",
+          "description": "The unique identifier for the UI surface to be deleted."
+        }
+      },
+      "required": ["surfaceId"]
+    }
+  }
+}