@@ -133,45 +133,38 @@ def render(
133133components INSIDE the template card use paths WITHOUT leading slash.
134134Do NOT use "/items/0/name" or "/items/{@key}/name" — just "name".
135135
136- DATA MODEL:
137- The "data" key in the tool args is a plain JSON object that initializes the surface
138- data model. Components bound to paths (e.g. "value": { "path": "/form/name" })
139- read from and write to this data model. Examples:
140- For forms: "data": { "form": { "name": "Alice", "email": "" } }
141- For lists: "data": { "items": [{"name": "Product A"}, {"name": "Product B"}] }
142- For mixed: "data": { "form": { "query": "" }, "results": [...] }
143-
144- FORMS AND TWO-WAY DATA BINDING:
145- To create editable forms, bind input components to data model paths using { "path": "..." }.
146- The client automatically writes user input back to the data model at the bound path.
147- CRITICAL: Using a literal value (e.g. "value": "") makes the field READ-ONLY.
148- You MUST use { "path": "..." } to make inputs editable.
149-
150- All input components use "value" as the binding property:
151- - TextField: "value": { "path": "/form/fieldName" }
152- - CheckBox: "value": { "path": "/form/isChecked" }
153- - Slider: "value": { "path": "/form/sliderVal" }
154- - DateTimeInput: "value": { "path": "/form/date" }
155- - ChoicePicker: "value": { "path": "/form/choices" }
156-
157- To retrieve form values when a button is clicked, include "context" with path references
158- in the button's action. Paths are resolved to their current values at click time:
159- "action": { "event": { "name": "submit", "context": { "userName": { "path": "/form/name" } } } }
160-
161- To pre-fill form values, pass initial data via the "data" tool argument:
162- "data": { "form": { "name": "Markus" } }
163-
164- FORM EXAMPLE (editable text field with pre-filled value + submit button):
165- "components": [
166- { "id": "root", "component": "Card", "child": "form-col" },
167- { "id": "form-col", "component": "Column", "children": ["name-field", "submit-row"] },
168- { "id": "name-field", "component": "TextField", "label": "Name", "value": { "path": "/form/name" } },
169- { "id": "submit-row", "component": "Row", "justify": "end", "children": ["submit-btn"] },
170- { "id": "submit-btn", "component": "Button", "child": "btn-text", "variant": "primary",
171- "action": { "event": { "name": "submit", "context": { "userName": { "path": "/form/name" } } } } },
172- { "id": "btn-text", "component": "Text", "text": "Submit" }
173- ],
174- "data": { "form": { "name": "Markus" } }"""
136+ COMPONENT VALUES — DEFAULT RULE:
137+ Use inline literal values for ALL component properties. Pass strings, numbers,
138+ arrays, and objects directly on the component. Do NOT use { "path": "..." }
139+ objects unless the property's schema explicitly allows it (see exception below).
140+ CRITICAL: USING { "path": "..." } ON A PROPERTY THAT DOES NOT DECLARE PATH
141+ SUPPORT IN ITS SCHEMA WILL CAUSE A RUNTIME CRASH AND BREAK THE ENTIRE UI.
142+ ALWAYS CHECK THE COMPONENT SCHEMA FIRST — IF THE PROPERTY ONLY ACCEPTS A
143+ PLAIN TYPE, YOU MUST USE A LITERAL VALUE.
144+ VERY IMPORTANT: THE APPLICATION WILL BREAK IF YOU DO NOT FOLLOW THIS RULE!
145+
146+ For example, a chart's "data" must always be an inline array:
147+ "data": [{"label": "Jan", "value": 100}, {"label": "Feb", "value": 200}]
148+ A metric's "value" must always be an inline string:
149+ "value": "$1,200"
150+
151+ PATH BINDING EXCEPTION — SCHEMA-DRIVEN:
152+ A few properties accept { "path": "/some/path" } as an alternative to a literal
153+ value. You can identify these in the Available Components schema: the property
154+ will list BOTH a literal type AND an object-with-path option. If a property only
155+ shows a single type (string, number, array, etc.), it does NOT support path
156+ binding — use a literal value only.
157+
158+ Path binding is typically used for editable form inputs so the client can write
159+ user input back to the data model. When building forms:
160+ - Bind input "value" to a data model path: "value": { "path": "/form/name" }
161+ - Pre-fill via the "data" tool argument: "data": { "form": { "name": "Alice" } }
162+ - Capture values on submit via button action context:
163+ "action": { "event": { "name": "submit", "context": { "name": { "path": "/form/name" } } } }
164+
165+ REPEATING CONTENT uses a structural children format (not the same as value binding):
166+ children: { componentId: "card-id", path: "/items" }
167+ Components inside templates use RELATIVE paths (no leading slash): { "path": "name" }."""
175168
176169DEFAULT_DESIGN_GUIDELINES = """\
177170
0 commit comments