Generalize A2UI Actions (v0.9)

specification/v0_9/docs/a2ui_protocol.md

@@ -270,6 +270,53 @@ flowchart TD
 
 ```
 
+### Defining Actions
+
+Interactive components (like `Button`) use an `action` property to define what happens when the user interacts with them. Actions can either trigger an event sent to the server or execute a local client-side function.
+
+#### Server Actions
+
+To send an event to the server, the `action` property is defined as an object with a `name` and an optional `context`.
+
+```json
+{
+  "component": "Button",
+  "text": "Submit",
+  "action": {
+    "name": "submit_form",
+    "context": {
+      "itemId": "123"
+    }
+  }
+}
+```
+
+#### Local Actions
+
+To execute a local function, the `action` property can be defined as a string containing a function call expression, or as an object with a `function` property.
+
+**String Shorthand:**
+
+```json
+{
+  "component": "Button",
+  "text": "Open Link",
+  "action": "openUrl(${/url})"
+}
+```
+
+**Object Definition:**
+
+```json
+{
+  "component": "Button",
+  "text": "Open Link",
+  "action": {
+    "function": "openUrl(${/url})"
+  }
+}
+```
+
 ## Data Model Representation: Binding, Scope, and Interpolation
 
 This section describes how UI components **represent** and reference data from the Data Model. A2UI relies on a strictly defined relationship between the UI structure (Components) and the state (Data Model), defining the mechanics of path resolution, variable scope during iteration, and interpolation.

specification/v0_9/json/common_types.json

@@ -317,6 +317,46 @@
           }
         }
       }
+    },
+    "Action": {
+      "description": "Defines an interaction handler that can either trigger a server-side event or execute a local client-side function.",
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "Triggers a server-side event.",
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "The name of the action to be dispatched to the server."
+            },
+            "context": {
+              "type": "object",
+              "description": "A JSON object containing the key-value pairs for the action context. Values can be literals or paths. Use literal values unless the value must be dynamically bound to the data model. Do NOT use paths for static IDs.",
+              "additionalProperties": {
+                "$ref": "#/$defs/DynamicValue"
+              }
+            }
+          },
+          "required": ["name"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Executes a local client-side function.",
+          "properties": {
+            "function": {
+              "type": "string",
+              "description": "A string specifying the local function to trigger (e.g., 'openUrl(${/url})'). This string can represent nested function calls and data model references."
+            }
+          },
+          "required": ["function"],
+          "additionalProperties": false
+        },
+        {
+          "type": "string",
+          "description": "Shorthand for a local client-side function execution (e.g. 'openUrl(${/url})')."
+        }
+      ]
     }
   }
 }

specification/v0_9/json/standard_catalog.json

@@ -420,20 +420,7 @@
               "description": "Indicates if this button should be styled as the primary action."
             },
             "action": {
-              "type": "object",
-              "description": "The client-side action to be dispatched when the button is clicked. It includes the action's name and an optional context payload.",
-              "properties": {
-                "name": { "type": "string" },
-                "context": {
-                  "type": "object",
-                  "description": "A JSON object containing the key-value pairs for the action context. Values can be literals or paths. Use literal values unless the value must be dynamically bound to the data model. Do NOT use paths for static IDs.",
-                  "additionalProperties": {
-                    "$ref": "common_types.json#/$defs/DynamicValue"
-                  }
-                }
-              },
-              "required": ["name"],
-              "additionalProperties": false
+              "$ref": "common_types.json#/$defs/Action"
             }
           },
           "required": ["component", "child", "action"]