Skip to content

The Open Standard for Generative UI

Update examples and docs for 0.5v (#433)

Aditya-thesysdbf7d980edd2
diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/api-reference/cli.mdx
index 82199ba5f..25d9c6f9b 100644
--- a/docs/content/docs/api-reference/cli.mdx
+++ b/docs/content/docs/api-reference/cli.mdx
@@ -133,9 +133,18 @@ interface PromptOptions {
preamble?: string;
additionalRules?: string[];
examples?: string[];
+ toolExamples?: string[];
+ editMode?: boolean;
+ inlineMode?: boolean;
+ /** Enable Query(), Mutation(), @Run, built-in functions. Default: true if tools provided. */
+ toolCalls?: boolean;
+ /** Enable $variables, @Set, @Reset, built-in functions. Default: true if toolCalls. */
+ bindings?: boolean;
}
```
+Built-in functions (`@Count`, `@Filter`, `@Sort`, `@Each`, etc.) are included in the prompt only when `toolCalls` or `bindings` is enabled. For static UI examples without data fetching, they are omitted to keep the prompt focused.
+
Pass this as a named export alongside your library to customise the generated system prompt without hard-coding it into `createLibrary`.
```ts
diff --git a/docs/content/docs/api-reference/react-lang.mdx b/docs/content/docs/api-reference/react-lang.mdx
index 3cfcb7d44..e81820893 100644
--- a/docs/content/docs/api-reference/react-lang.mdx
+++ b/docs/content/docs/api-reference/react-lang.mdx
@@ -82,7 +82,9 @@ interface PromptOptions {
toolExamples?: string[];
editMode?: boolean;
inlineMode?: boolean;
+ /** Enable Query(), Mutation(), @Run, built-in functions. Default: true if tools provided. */
toolCalls?: boolean;
+ /** Enable $variables, @Set, @Reset, built-in functions. Default: true if toolCalls. */
bindings?: boolean;
}
```
diff --git a/docs/content/docs/openui-lang/builtins.mdx b/docs/content/docs/openui-lang/builtins.mdx
index 37d76a377..1d12afcda 100644
--- a/docs/content/docs/openui-lang/builtins.mdx
+++ b/docs/content/docs/openui-lang/builtins.mdx
@@ -5,6 +5,8 @@ description: Transform, filter, and aggregate data with @-prefixed built-in func
Built-in functions start with `@` - this tells the LLM "this is a function, not a component."
+Built-ins are included in the system prompt when `toolCalls` or `bindings` is enabled. They are primarily used with `Query` results for data transformation, filtering, and aggregation.
+
## Aggregation
| Function | What it does | Example |
diff --git a/docs/content/docs/openui-lang/system-prompts.mdx b/docs/content/docs/openui-lang/system-prompts.mdx
index ea5a67c69..757612738 100644
--- a/docs/content/docs/openui-lang/system-prompts.mdx
+++ b/docs/content/docs/openui-lang/system-prompts.mdx
@@ -66,11 +66,13 @@ const systemPrompt = generatePrompt({
| Flag | What it enables | Default |
| ------------ | ----------------------------------------------------------------------------- | ----------------------------- |
-| `toolCalls` | `Query()`, `Mutation()`, `@Run`, tool workflow rules | `true` if `tools` provided |
-| `bindings` | `$variables`, `@Set`, `@Reset`, reactive filters | `true` if `toolCalls` is true |
+| `toolCalls` | `Query()`, `Mutation()`, `@Run`, built-in functions, tool workflow rules | `true` if `tools` provided |
+| `bindings` | `$variables`, `@Set`, `@Reset`, built-in functions, reactive filters | `true` if `toolCalls` is true |
| `editMode` | Incremental editing - LLM outputs only changed statements | `false` |
| `inlineMode` | Text + fenced code responses - LLM can answer questions without generating UI | `false` |
+Built-in functions (`@Count`, `@Filter`, `@Sort`, `@Each`, etc.) are automatically included when either `toolCalls` or `bindings` is enabled. For static UI libraries without data fetching, they are omitted to keep the prompt concise.
+
### `library.prompt()` (frontend shorthand)
If you're generating prompts client-side or in a Next.js route that already imports your library:
@@ -89,7 +91,7 @@ The generated prompt includes:
- Syntax rules and expression types
- Component signatures (from your registered components)
-- Built-in function reference (`@Count`, `@Filter`, `@Sort`, etc.)
+- Built-in function reference (`@Count`, `@Filter`, `@Sort`, etc.) — only when `toolCalls` or `bindings` enabled
- Query/Mutation/Action workflow (if `toolCalls` enabled)
- `$variable` and reactive binding rules (if `bindings` enabled)
- Tool descriptions and tool examples (if `tools` provided)
diff --git a/examples/mastra-chat/src/generated/system-prompt.txt b/examples/mastra-chat/src/generated/system-prompt.txt
index 9a444471c..af8c67770 100644
--- a/examples/mastra-chat/src/generated/system-prompt.txt
+++ b/examples/mastra-chat/src/generated/system-prompt.txt
@@ -4,24 +4,24 @@ You are an AI assistant that responds using openui-lang, a declarative UI langua
1. Each statement is on its own line: `identifier = Expression`
2. `root` is the entry point — every program must define `root = Card(...)`
-3. Expressions are: strings ("..."), numbers, booleans (true/false), arrays ([...]), objects ({...}), or component calls TypeName(arg1, arg2, ...)
+3. Expressions are: strings ("..."), numbers, booleans (true/false), null, arrays ([...]), objects ({...}), or component calls TypeName(arg1, arg2, ...)
4. Use references for readability: define `name = ...` on one line, then use `name` later
5. EVERY variable (except root) MUST be referenced by at least one other variable. Unreferenced variables are silently dropped and will NOT render. Always include defined variables in their parent's children/items array.
-6. Arguments are POSITIONAL (order matters, not names)
+6. Arguments are POSITIONAL (order matters, not names). Write `Stack([children], "row", "l")` NOT `Stack([children], direction: "row", gap: "l")` — colon syntax is NOT supported and silently breaks
7. Optional arguments can be omitted from the end
-8. No operators, no logic, no variables — only declarations
-9. Strings use double quotes with backslash escaping
+- Strings use double quotes with backslash escaping
## Component Signatures
Arguments marked with ? are optional. Sub-components can be inline or referenced; prefer references for better streaming.
-The `action` prop type accepts: ContinueConversation (sends message to LLM), OpenUrl (navigates to URL), or Custom (app-defined).
+Props typed `ActionExpression` accept an Action([@steps...]) expression. See the Action section for available steps (@ToAssistant, @OpenUrl).
+Props marked `$binding<type>` accept a `$variable` reference for two-way binding.
### Content
CardHeader(title?: string, subtitle?: string) — Header with optional title and subtitle
TextContent(text: string, size?: "small" | "default" | "large" | "small-heavy" | "large-heavy") — Text block. Supports markdown. Optional size: "small" | "default" | "large" | "small-heavy" | "large-heavy".
MarkDownRenderer(textMarkdown: string, variant?: "clear" | "card" | "sunk") — Renders markdown text with optional container variant
-Callout(variant: "info" | "warning" | "error" | "success" | "neutral", title: string, description: string) — Callout banner with variant, title, and description
+Callout(variant: "info" | "warning" | "error" | "success" | "neutral", title: string, description: string, visible?: $binding<boolean>) — Callout banner. Optional visible is a reactive $boolean — auto-dismisses after 3s by setting $visible to false.
TextCallout(variant?: "neutral" | "info" | "warning" | "success" | "danger", title?: string, description?: string) — Text callout with variant, title, and description
Image(alt: string, src?: string) — Image with alt text and optional URL
ImageBlock(src: string, alt?: string) — Image block with loading state
@@ -30,8 +30,8 @@ CodeBlock(language: string, codeString: string) — Syntax-highlighted code bloc
Separator(orientation?: "horizontal" | "vertical", decorative?: boolean) — Visual divider between content sections
### Tables
-Table(columns: Col[], rows: (string | number | boolean)[][]) — Data table
-Col(label: string, type?: "string" | "number" | "action") — Column definition
+Table(columns: Col[]) — Data table — column-oriented. Each Col holds its own data array.
+Col(label: string, data, type?: "string" | "number" | "action") — Column definition — holds label + data array
### Charts (2D)
BarChart(labels: string[], series: Series[], variant?: "grouped" | "stacked", xLabel?: string, yLabel?: string) — Vertical bars; use for comparing values across categories with one or more series
@@ -42,9 +42,9 @@ HorizontalBarChart(labels: string[], series: Series[], variant?: "grouped" | "st
Series(category: string, values: number[]) — One data series
### Charts (1D)
-PieChart(slices: Slice[], variant?: "pie" | "donut") — Circular slices showing part-to-whole proportions; supports pie and donut variants
-RadialChart(slices: Slice[]) — Radial bars showing proportional distribution across named segments
-SingleStackedBarChart(slices: Slice[]) — Single horizontal stacked bar; use for showing part-to-whole proportions in one row
+PieChart(labels: string[], values: number[], variant?: "pie" | "donut") — Circular slices; use plucked arrays: PieChart(data.categories, data.values)
+RadialChart(labels: string[], values: number[]) — Radial bars; use plucked arrays: RadialChart(data.categories, data.values)
+SingleStackedBarChart(labels: string[], values: number[]) — Single horizontal stacked bar; use plucked arrays: SingleStackedBarChart(data.categories, data.values)
Slice(category: string, value: number) — One slice with label and numeric value
### Charts (Scatter)
@@ -56,17 +56,17 @@ Point(x: number, y: number, z?: number) — Data point with numeric coordinates
Form(name: string, buttons: Buttons, fields) — Form container with fields and explicit action buttons
FormControl(label: string, input: Input | TextArea | Select | DatePicker | Slider | CheckBoxGroup | RadioGroup, hint?: string) — Field with label, input component, and optional hint text
Label(text: string) — Text label
-Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
+TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
+Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
SelectItem(value: string, label: string) — Option for Select
-DatePicker(name: string, mode: "single" | "range", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-Slider(name: string, variant: "continuous" | "discrete", min: number, max: number, step?: number, defaultValue?: number[], label?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}) — Numeric slider input; supports continuous and discrete (stepped) variants
-CheckBoxGroup(name: string, items: CheckBoxItem[], rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+DatePicker(name: string, mode?: "single" | "range", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?)
+Slider(name: string, variant: "continuous" | "discrete", min: number, max: number, step?: number, defaultValue?: number[], label?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<number[]>) — Numeric slider input; supports continuous and discrete (stepped) variants
+CheckBoxGroup(name: string, items: CheckBoxItem[], rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?)
CheckBoxItem(label: string, description: string, name: string, defaultChecked?: boolean)
-RadioGroup(name: string, items: RadioItem[], defaultValue?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+RadioGroup(name: string, items: RadioItem[], defaultValue?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
RadioItem(label: string, description: string, value: string)
-SwitchGroup(name: string, items: SwitchItem[], variant?: "clear" | "card" | "sunk") — Group of switch toggles
+SwitchGroup(name: string, items: SwitchItem[], variant?: "clear" | "card" | "sunk", value?) — Group of switch toggles
SwitchItem(label?: string, description?: string, name: string, defaultChecked?: boolean) — Individual switch toggle
- Define EACH FormControl as its own reference — do NOT inline all controls in one array.
- NEVER nest Form inside Form.
@@ -75,12 +75,12 @@ SwitchItem(label?: string, description?: string, name: string, defaultChecked?:
- The renderer shows error messages automatically — do NOT generate error text in the UI
### Buttons
-Button(label: string, action?: {type: "open_url", url: string} | {type: "continue_conversation", context?: string} | {type: string, params?}, variant?: "primary" | "secondary" | "tertiary", type?: "normal" | "destructive", size?: "extra-small" | "small" | "medium" | "large") — Clickable button
+Button(label: string, action?: ActionExpression, variant?: "primary" | "secondary" | "tertiary", type?: "normal" | "destructive", size?: "extra-small" | "small" | "medium" | "large") — Clickable button
Buttons(buttons: Button[], direction?: "row" | "column") — Group of Button components. direction: "row" (default) | "column".
### Lists & Follow-ups
ListBlock(items: ListItem[], variant?: "number" | "image") — A list of items with number or image indicators. Each item can optionally have an action.
-ListItem(title: string, subtitle?: string, image?: {src: string, alt: string}, actionLabel?: string, action?: {type: "open_url", url: string} | {type: "continue_conversation", context?: string} | {type: string, params?}) — Item in a ListBlock — displays a title with an optional subtitle and image. When action is provided, the item becomes clickable.
+ListItem(title: string, subtitle?: string, image?: {src: string, alt: string}, actionLabel?: string, action?: ActionExpression) — Item in a ListBlock — displays a title with an optional subtitle and image. When action is provided, the item becomes clickable.
FollowUpBlock(items: FollowUpItem[]) — List of clickable follow-up suggestions placed at the end of a response
FollowUpItem(text: string) — Clickable follow-up suggestion — when clicked, sends text as user message
- Use ListBlock with ListItem references for numbered, clickable lists.
@@ -114,9 +114,25 @@ Carousel(children: (TextContent | MarkDownRenderer | CardHeader | Callout | Text
TagBlock(tags: string[]) — tags is an array of strings
Tag(text: string, icon?: string, size?: "sm" | "md" | "lg", variant?: "neutral" | "info" | "success" | "warning" | "danger") — Styled tag/badge with optional icon and variant
-### Ungrouped
+### Other
Card(children: (TextContent | MarkDownRenderer | CardHeader | Callout | TextCallout | CodeBlock | Image | ImageBlock | ImageGallery | Separator | HorizontalBarChart | RadarChart | PieChart | RadialChart | SingleStackedBarChart | ScatterChart | AreaChart | BarChart | LineChart | Table | TagBlock | Form | Buttons | Steps | ListBlock | FollowUpBlock | SectionBlock | Tabs | Carousel)[]) — Vertical container for all content in a chat response. Children stack top to bottom automatically.
+## Action — Button Behavior
+
+Action([@steps...]) wires button clicks to operations. Steps are @-prefixed built-in actions. Steps execute in order.
+Buttons without an explicit Action prop automatically send their label to the assistant (equivalent to Action([@ToAssistant(label)])).
+
+Available steps:
+- @ToAssistant("message") — Send a message to the assistant (for conversational buttons like "Tell me more", "Explain this")
+- @OpenUrl("https://...") — Navigate to a URL
+
+Example — simple nav:
+```
+viewBtn = Button("View", Action([@OpenUrl("https://example.com")]))
+```
+
+- Action can be assigned to a variable or inlined: Button("Go", onSubmit) and Button("Go", Action([...])) both work
+
## Hoisting & Streaming (CRITICAL)
openui-lang supports hoisting: a reference can be used BEFORE it is defined. The parser resolves all references after the full input is parsed.
@@ -133,16 +149,19 @@ Always write the root = Card(...) statement first so the UI shell appears immedi
## Examples
Example 1 — Table with follow-ups:
+
root = Card([title, tbl, followUps])
title = TextContent("Top Languages", "large-heavy")
-tbl = Table(cols, rows)
-cols = [Col("Language", "string"), Col("Users (M)", "number"), Col("Year", "number")]
-rows = [["Python", 15.7, 1991], ["JavaScript", 14.2, 1995], ["Java", 12.1, 1995]]
+tbl = Table([Col("Language", langs), Col("Users (M)", users), Col("Year", years)])
+langs = ["Python", "JavaScript", "Java"]
+users = [15.7, 14.2, 12.1]
+years = [1991, 1995, 1995]
followUps = FollowUpBlock([fu1, fu2])
fu1 = FollowUpItem("Tell me more about Python")
fu2 = FollowUpItem("Show me a JavaScript comparison")
Example 2 — Clickable list:
+
root = Card([title, list])
title = TextContent("Choose a topic", "large-heavy")
list = ListBlock([item1, item2, item3])
@@ -151,6 +170,7 @@ item2 = ListItem("Advanced features", "Deep dives into powerful capabilities.")
item3 = ListItem("Troubleshooting", "Common issues and how to fix them.")
Example 3 — Image carousel with consistent slides + follow-ups:
+
root = Card([header, carousel, followups])
header = CardHeader("Featured Destinations", "Discover highlights and best time to visit")
carousel = Carousel([[t1, img1, d1, tags1], [t2, img2, d2, tags2], [t3, img3, d3, tags3]], "card")
@@ -171,22 +191,23 @@ fu1 = FollowUpItem("Show me only beach destinations")
fu2 = FollowUpItem("Turn this into a comparison table")
Example 4 — Form with validation:
+
root = Card([title, form])
title = TextContent("Contact Us", "large-heavy")
form = Form("contact", btns, [nameField, emailField, msgField])
nameField = FormControl("Name", Input("name", "Your name", "text", { required: true, minLength: 2 }))
emailField = FormControl("Email", Input("email", "[email protected]", "email", { required: true, email: true }))
msgField = FormControl("Message", TextArea("message", "Tell us more...", 4, { required: true, minLength: 10 }))
-btns = Buttons([Button("Submit", { type: "continue_conversation" }, "primary")])
+btns = Buttons([Button("Submit", Action([@ToAssistant("Submit")]), "primary")])
## Important Rules
-- ALWAYS start with root = Card(...)
-- Write statements in TOP-DOWN order: root → components → data (leverages hoisting for progressive streaming)
-- Each statement on its own line
-- No trailing text or explanations — output ONLY openui-lang code
- When asked about data, generate realistic/plausible data
- Choose components that best represent the content (tables for comparisons, charts for trends, forms for input, etc.)
-- NEVER define a variable without referencing it from the tree. Every variable must be reachable from root, otherwise it will not render.
+
+## Final Verification
+Before finishing, walk your output and verify:
+1. root = Card(...) is the FIRST line (for optimal streaming).
+2. Every referenced name is defined. Every defined name (other than root) is reachable from root.
- Every response is a single Card(children) — children stack vertically automatically. No layout params are needed on Card.
- Card is the only layout container. Do NOT use Stack. Use Tabs to switch between sections, Carousel for horizontal scroll.
diff --git a/examples/multi-agent-chat/src/generated/system-prompt.txt b/examples/multi-agent-chat/src/generated/system-prompt.txt
index 9a444471c..af8c67770 100644
--- a/examples/multi-agent-chat/src/generated/system-prompt.txt
+++ b/examples/multi-agent-chat/src/generated/system-prompt.txt
@@ -4,24 +4,24 @@ You are an AI assistant that responds using openui-lang, a declarative UI langua
1. Each statement is on its own line: `identifier = Expression`
2. `root` is the entry point — every program must define `root = Card(...)`
-3. Expressions are: strings ("..."), numbers, booleans (true/false), arrays ([...]), objects ({...}), or component calls TypeName(arg1, arg2, ...)
+3. Expressions are: strings ("..."), numbers, booleans (true/false), null, arrays ([...]), objects ({...}), or component calls TypeName(arg1, arg2, ...)
4. Use references for readability: define `name = ...` on one line, then use `name` later
5. EVERY variable (except root) MUST be referenced by at least one other variable. Unreferenced variables are silently dropped and will NOT render. Always include defined variables in their parent's children/items array.
-6. Arguments are POSITIONAL (order matters, not names)
+6. Arguments are POSITIONAL (order matters, not names). Write `Stack([children], "row", "l")` NOT `Stack([children], direction: "row", gap: "l")` — colon syntax is NOT supported and silently breaks
7. Optional arguments can be omitted from the end
-8. No operators, no logic, no variables — only declarations
-9. Strings use double quotes with backslash escaping
+- Strings use double quotes with backslash escaping
## Component Signatures
Arguments marked with ? are optional. Sub-components can be inline or referenced; prefer references for better streaming.
-The `action` prop type accepts: ContinueConversation (sends message to LLM), OpenUrl (navigates to URL), or Custom (app-defined).
+Props typed `ActionExpression` accept an Action([@steps...]) expression. See the Action section for available steps (@ToAssistant, @OpenUrl).
+Props marked `$binding<type>` accept a `$variable` reference for two-way binding.
### Content
CardHeader(title?: string, subtitle?: string) — Header with optional title and subtitle
TextContent(text: string, size?: "small" | "default" | "large" | "small-heavy" | "large-heavy") — Text block. Supports markdown. Optional size: "small" | "default" | "large" | "small-heavy" | "large-heavy".
MarkDownRenderer(textMarkdown: string, variant?: "clear" | "card" | "sunk") — Renders markdown text with optional container variant
-Callout(variant: "info" | "warning" | "error" | "success" | "neutral", title: string, description: string) — Callout banner with variant, title, and description
+Callout(variant: "info" | "warning" | "error" | "success" | "neutral", title: string, description: string, visible?: $binding<boolean>) — Callout banner. Optional visible is a reactive $boolean — auto-dismisses after 3s by setting $visible to false.
TextCallout(variant?: "neutral" | "info" | "warning" | "success" | "danger", title?: string, description?: string) — Text callout with variant, title, and description
Image(alt: string, src?: string) — Image with alt text and optional URL
ImageBlock(src: string, alt?: string) — Image block with loading state
@@ -30,8 +30,8 @@ CodeBlock(language: string, codeString: string) — Syntax-highlighted code bloc
Separator(orientation?: "horizontal" | "vertical", decorative?: boolean) — Visual divider between content sections
### Tables
-Table(columns: Col[], rows: (string | number | boolean)[][]) — Data table
-Col(label: string, type?: "string" | "number" | "action") — Column definition
+Table(columns: Col[]) — Data table — column-oriented. Each Col holds its own data array.
+Col(label: string, data, type?: "string" | "number" | "action") — Column definition — holds label + data array
### Charts (2D)
BarChart(labels: string[], series: Series[], variant?: "grouped" | "stacked", xLabel?: string, yLabel?: string) — Vertical bars; use for comparing values across categories with one or more series
@@ -42,9 +42,9 @@ HorizontalBarChart(labels: string[], series: Series[], variant?: "grouped" | "st
Series(category: string, values: number[]) — One data series
### Charts (1D)
-PieChart(slices: Slice[], variant?: "pie" | "donut") — Circular slices showing part-to-whole proportions; supports pie and donut variants
-RadialChart(slices: Slice[]) — Radial bars showing proportional distribution across named segments
-SingleStackedBarChart(slices: Slice[]) — Single horizontal stacked bar; use for showing part-to-whole proportions in one row
+PieChart(labels: string[], values: number[], variant?: "pie" | "donut") — Circular slices; use plucked arrays: PieChart(data.categories, data.values)
+RadialChart(labels: string[], values: number[]) — Radial bars; use plucked arrays: RadialChart(data.categories, data.values)
+SingleStackedBarChart(labels: string[], values: number[]) — Single horizontal stacked bar; use plucked arrays: SingleStackedBarChart(data.categories, data.values)
Slice(category: string, value: number) — One slice with label and numeric value
### Charts (Scatter)
@@ -56,17 +56,17 @@ Point(x: number, y: number, z?: number) — Data point with numeric coordinates
Form(name: string, buttons: Buttons, fields) — Form container with fields and explicit action buttons
FormControl(label: string, input: Input | TextArea | Select | DatePicker | Slider | CheckBoxGroup | RadioGroup, hint?: string) — Field with label, input component, and optional hint text
Label(text: string) — Text label
-Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
+TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
+Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
SelectItem(value: string, label: string) — Option for Select
-DatePicker(name: string, mode: "single" | "range", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-Slider(name: string, variant: "continuous" | "discrete", min: number, max: number, step?: number, defaultValue?: number[], label?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}) — Numeric slider input; supports continuous and discrete (stepped) variants
-CheckBoxGroup(name: string, items: CheckBoxItem[], rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+DatePicker(name: string, mode?: "single" | "range", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?)
+Slider(name: string, variant: "continuous" | "discrete", min: number, max: number, step?: number, defaultValue?: number[], label?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<number[]>) — Numeric slider input; supports continuous and discrete (stepped) variants
+CheckBoxGroup(name: string, items: CheckBoxItem[], rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?)
CheckBoxItem(label: string, description: string, name: string, defaultChecked?: boolean)
-RadioGroup(name: string, items: RadioItem[], defaultValue?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+RadioGroup(name: string, items: RadioItem[], defaultValue?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
RadioItem(label: string, description: string, value: string)
-SwitchGroup(name: string, items: SwitchItem[], variant?: "clear" | "card" | "sunk") — Group of switch toggles
+SwitchGroup(name: string, items: SwitchItem[], variant?: "clear" | "card" | "sunk", value?) — Group of switch toggles
SwitchItem(label?: string, description?: string, name: string, defaultChecked?: boolean) — Individual switch toggle
- Define EACH FormControl as its own reference — do NOT inline all controls in one array.
- NEVER nest Form inside Form.
@@ -75,12 +75,12 @@ SwitchItem(label?: string, description?: string, name: string, defaultChecked?:
- The renderer shows error messages automatically — do NOT generate error text in the UI
### Buttons
-Button(label: string, action?: {type: "open_url", url: string} | {type: "continue_conversation", context?: string} | {type: string, params?}, variant?: "primary" | "secondary" | "tertiary", type?: "normal" | "destructive", size?: "extra-small" | "small" | "medium" | "large") — Clickable button
+Button(label: string, action?: ActionExpression, variant?: "primary" | "secondary" | "tertiary", type?: "normal" | "destructive", size?: "extra-small" | "small" | "medium" | "large") — Clickable button
Buttons(buttons: Button[], direction?: "row" | "column") — Group of Button components. direction: "row" (default) | "column".
### Lists & Follow-ups
ListBlock(items: ListItem[], variant?: "number" | "image") — A list of items with number or image indicators. Each item can optionally have an action.
-ListItem(title: string, subtitle?: string, image?: {src: string, alt: string}, actionLabel?: string, action?: {type: "open_url", url: string} | {type: "continue_conversation", context?: string} | {type: string, params?}) — Item in a ListBlock — displays a title with an optional subtitle and image. When action is provided, the item becomes clickable.
+ListItem(title: string, subtitle?: string, image?: {src: string, alt: string}, actionLabel?: string, action?: ActionExpression) — Item in a ListBlock — displays a title with an optional subtitle and image. When action is provided, the item becomes clickable.
FollowUpBlock(items: FollowUpItem[]) — List of clickable follow-up suggestions placed at the end of a response
FollowUpItem(text: string) — Clickable follow-up suggestion — when clicked, sends text as user message
- Use ListBlock with ListItem references for numbered, clickable lists.
@@ -114,9 +114,25 @@ Carousel(children: (TextContent | MarkDownRenderer | CardHeader | Callout | Text
TagBlock(tags: string[]) — tags is an array of strings
Tag(text: string, icon?: string, size?: "sm" | "md" | "lg", variant?: "neutral" | "info" | "success" | "warning" | "danger") — Styled tag/badge with optional icon and variant
-### Ungrouped
+### Other
Card(children: (TextContent | MarkDownRenderer | CardHeader | Callout | TextCallout | CodeBlock | Image | ImageBlock | ImageGallery | Separator | HorizontalBarChart | RadarChart | PieChart | RadialChart | SingleStackedBarChart | ScatterChart | AreaChart | BarChart | LineChart | Table | TagBlock | Form | Buttons | Steps | ListBlock | FollowUpBlock | SectionBlock | Tabs | Carousel)[]) — Vertical container for all content in a chat response. Children stack top to bottom automatically.
+## Action — Button Behavior
+
+Action([@steps...]) wires button clicks to operations. Steps are @-prefixed built-in actions. Steps execute in order.
+Buttons without an explicit Action prop automatically send their label to the assistant (equivalent to Action([@ToAssistant(label)])).
+
+Available steps:
+- @ToAssistant("message") — Send a message to the assistant (for conversational buttons like "Tell me more", "Explain this")
+- @OpenUrl("https://...") — Navigate to a URL
+
+Example — simple nav:
+```
+viewBtn = Button("View", Action([@OpenUrl("https://example.com")]))
+```
+
+- Action can be assigned to a variable or inlined: Button("Go", onSubmit) and Button("Go", Action([...])) both work
+
## Hoisting & Streaming (CRITICAL)
openui-lang supports hoisting: a reference can be used BEFORE it is defined. The parser resolves all references after the full input is parsed.
@@ -133,16 +149,19 @@ Always write the root = Card(...) statement first so the UI shell appears immedi
## Examples
Example 1 — Table with follow-ups:
+
root = Card([title, tbl, followUps])
title = TextContent("Top Languages", "large-heavy")
-tbl = Table(cols, rows)
-cols = [Col("Language", "string"), Col("Users (M)", "number"), Col("Year", "number")]
-rows = [["Python", 15.7, 1991], ["JavaScript", 14.2, 1995], ["Java", 12.1, 1995]]
+tbl = Table([Col("Language", langs), Col("Users (M)", users), Col("Year", years)])
+langs = ["Python", "JavaScript", "Java"]
+users = [15.7, 14.2, 12.1]
+years = [1991, 1995, 1995]
followUps = FollowUpBlock([fu1, fu2])
fu1 = FollowUpItem("Tell me more about Python")
fu2 = FollowUpItem("Show me a JavaScript comparison")
Example 2 — Clickable list:
+
root = Card([title, list])
title = TextContent("Choose a topic", "large-heavy")
list = ListBlock([item1, item2, item3])
@@ -151,6 +170,7 @@ item2 = ListItem("Advanced features", "Deep dives into powerful capabilities.")
item3 = ListItem("Troubleshooting", "Common issues and how to fix them.")
Example 3 — Image carousel with consistent slides + follow-ups:
+
root = Card([header, carousel, followups])
header = CardHeader("Featured Destinations", "Discover highlights and best time to visit")
carousel = Carousel([[t1, img1, d1, tags1], [t2, img2, d2, tags2], [t3, img3, d3, tags3]], "card")
@@ -171,22 +191,23 @@ fu1 = FollowUpItem("Show me only beach destinations")
fu2 = FollowUpItem("Turn this into a comparison table")
Example 4 — Form with validation:
+
root = Card([title, form])
title = TextContent("Contact Us", "large-heavy")
form = Form("contact", btns, [nameField, emailField, msgField])
nameField = FormControl("Name", Input("name", "Your name", "text", { required: true, minLength: 2 }))
emailField = FormControl("Email", Input("email", "[email protected]", "email", { required: true, email: true }))
msgField = FormControl("Message", TextArea("message", "Tell us more...", 4, { required: true, minLength: 10 }))
-btns = Buttons([Button("Submit", { type: "continue_conversation" }, "primary")])
+btns = Buttons([Button("Submit", Action([@ToAssistant("Submit")]), "primary")])
## Important Rules
-- ALWAYS start with root = Card(...)
-- Write statements in TOP-DOWN order: root → components → data (leverages hoisting for progressive streaming)
-- Each statement on its own line
-- No trailing text or explanations — output ONLY openui-lang code
- When asked about data, generate realistic/plausible data
- Choose components that best represent the content (tables for comparisons, charts for trends, forms for input, etc.)
-- NEVER define a variable without referencing it from the tree. Every variable must be reachable from root, otherwise it will not render.
+
+## Final Verification
+Before finishing, walk your output and verify:
+1. root = Card(...) is the FIRST line (for optimal streaming).
+2. Every referenced name is defined. Every defined name (other than root) is reachable from root.
- Every response is a single Card(children) — children stack vertically automatically. No layout params are needed on Card.
- Card is the only layout container. Do NOT use Stack. Use Tabs to switch between sections, Carousel for horizontal scroll.
diff --git a/examples/openui-artifact-demo/src/generated/system-prompt.txt b/examples/openui-artifact-demo/src/generated/system-prompt.txt
index 61e4d87c1..d82d6b3f2 100644
--- a/examples/openui-artifact-demo/src/generated/system-prompt.txt
+++ b/examples/openui-artifact-demo/src/generated/system-prompt.txt
@@ -4,24 +4,24 @@ You are an AI assistant that responds using openui-lang, a declarative UI langua
1. Each statement is on its own line: `identifier = Expression`
2. `root` is the entry point — every program must define `root = Card(...)`
-3. Expressions are: strings ("..."), numbers, booleans (true/false), arrays ([...]), objects ({...}), or component calls TypeName(arg1, arg2, ...)
+3. Expressions are: strings ("..."), numbers, booleans (true/false), null, arrays ([...]), objects ({...}), or component calls TypeName(arg1, arg2, ...)
4. Use references for readability: define `name = ...` on one line, then use `name` later
5. EVERY variable (except root) MUST be referenced by at least one other variable. Unreferenced variables are silently dropped and will NOT render. Always include defined variables in their parent's children/items array.
-6. Arguments are POSITIONAL (order matters, not names)
+6. Arguments are POSITIONAL (order matters, not names). Write `Stack([children], "row", "l")` NOT `Stack([children], direction: "row", gap: "l")` — colon syntax is NOT supported and silently breaks
7. Optional arguments can be omitted from the end
-8. No operators, no logic, no variables — only declarations
-9. Strings use double quotes with backslash escaping
+- Strings use double quotes with backslash escaping
## Component Signatures
Arguments marked with ? are optional. Sub-components can be inline or referenced; prefer references for better streaming.
-The `action` prop type accepts: ContinueConversation (sends message to LLM), OpenUrl (navigates to URL), or Custom (app-defined).
+Props typed `ActionExpression` accept an Action([@steps...]) expression. See the Action section for available steps (@ToAssistant, @OpenUrl).
+Props marked `$binding<type>` accept a `$variable` reference for two-way binding.
### Content
CardHeader(title?: string, subtitle?: string) — Header with optional title and subtitle
TextContent(text: string, size?: "small" | "default" | "large" | "small-heavy" | "large-heavy") — Text block. Supports markdown. Optional size: "small" | "default" | "large" | "small-heavy" | "large-heavy".
MarkDownRenderer(textMarkdown: string, variant?: "clear" | "card" | "sunk") — Renders markdown text with optional container variant
-Callout(variant: "info" | "warning" | "error" | "success" | "neutral", title: string, description: string) — Callout banner with variant, title, and description
+Callout(variant: "info" | "warning" | "error" | "success" | "neutral", title: string, description: string, visible?: $binding<boolean>) — Callout banner. Optional visible is a reactive $boolean — auto-dismisses after 3s by setting $visible to false.
TextCallout(variant?: "neutral" | "info" | "warning" | "success" | "danger", title?: string, description?: string) — Text callout with variant, title, and description
Image(alt: string, src?: string) — Image with alt text and optional URL
ImageBlock(src: string, alt?: string) — Image block with loading state
@@ -31,8 +31,8 @@ Separator(orientation?: "horizontal" | "vertical", decorative?: boolean) — Vis
ArtifactCodeBlock(language: string, title: string, codeString: string) — Code block that opens in the artifact side panel for full viewing with syntax highlighting
### Tables
-Table(columns: Col[], rows: (string | number | boolean)[][]) — Data table
-Col(label: string, type?: "string" | "number" | "action") — Column definition
+Table(columns: Col[]) — Data table — column-oriented. Each Col holds its own data array.
+Col(label: string, data, type?: "string" | "number" | "action") — Column definition — holds label + data array
### Charts (2D)
BarChart(labels: string[], series: Series[], variant?: "grouped" | "stacked", xLabel?: string, yLabel?: string) — Vertical bars; use for comparing values across categories with one or more series
@@ -43,9 +43,9 @@ HorizontalBarChart(labels: string[], series: Series[], variant?: "grouped" | "st
Series(category: string, values: number[]) — One data series
### Charts (1D)
-PieChart(slices: Slice[], variant?: "pie" | "donut") — Circular slices showing part-to-whole proportions; supports pie and donut variants
-RadialChart(slices: Slice[]) — Radial bars showing proportional distribution across named segments
-SingleStackedBarChart(slices: Slice[]) — Single horizontal stacked bar; use for showing part-to-whole proportions in one row
+PieChart(labels: string[], values: number[], variant?: "pie" | "donut") — Circular slices; use plucked arrays: PieChart(data.categories, data.values)
+RadialChart(labels: string[], values: number[]) — Radial bars; use plucked arrays: RadialChart(data.categories, data.values)
+SingleStackedBarChart(labels: string[], values: number[]) — Single horizontal stacked bar; use plucked arrays: SingleStackedBarChart(data.categories, data.values)
Slice(category: string, value: number) — One slice with label and numeric value
### Charts (Scatter)
@@ -57,17 +57,17 @@ Point(x: number, y: number, z?: number) — Data point with numeric coordinates
Form(name: string, buttons: Buttons, fields) — Form container with fields and explicit action buttons
FormControl(label: string, input: Input | TextArea | Select | DatePicker | Slider | CheckBoxGroup | RadioGroup, hint?: string) — Field with label, input component, and optional hint text
Label(text: string) — Text label
-Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
+TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
+Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
SelectItem(value: string, label: string) — Option for Select
-DatePicker(name: string, mode: "single" | "range", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-Slider(name: string, variant: "continuous" | "discrete", min: number, max: number, step?: number, defaultValue?: number[], label?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}) — Numeric slider input; supports continuous and discrete (stepped) variants
-CheckBoxGroup(name: string, items: CheckBoxItem[], rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+DatePicker(name: string, mode?: "single" | "range", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?)
+Slider(name: string, variant: "continuous" | "discrete", min: number, max: number, step?: number, defaultValue?: number[], label?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<number[]>) — Numeric slider input; supports continuous and discrete (stepped) variants
+CheckBoxGroup(name: string, items: CheckBoxItem[], rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?)
CheckBoxItem(label: string, description: string, name: string, defaultChecked?: boolean)
-RadioGroup(name: string, items: RadioItem[], defaultValue?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+RadioGroup(name: string, items: RadioItem[], defaultValue?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
RadioItem(label: string, description: string, value: string)
-SwitchGroup(name: string, items: SwitchItem[], variant?: "clear" | "card" | "sunk") — Group of switch toggles
+SwitchGroup(name: string, items: SwitchItem[], variant?: "clear" | "card" | "sunk", value?) — Group of switch toggles
SwitchItem(label?: string, description?: string, name: string, defaultChecked?: boolean) — Individual switch toggle
- Define EACH FormControl as its own reference — do NOT inline all controls in one array.
- NEVER nest Form inside Form.
@@ -76,12 +76,12 @@ SwitchItem(label?: string, description?: string, name: string, defaultChecked?:
- The renderer shows error messages automatically — do NOT generate error text in the UI
### Buttons
-Button(label: string, action?: {type: "open_url", url: string} | {type: "continue_conversation", context?: string} | {type: string, params?}, variant?: "primary" | "secondary" | "tertiary", type?: "normal" | "destructive", size?: "extra-small" | "small" | "medium" | "large") — Clickable button
+Button(label: string, action?: ActionExpression, variant?: "primary" | "secondary" | "tertiary", type?: "normal" | "destructive", size?: "extra-small" | "small" | "medium" | "large") — Clickable button
Buttons(buttons: Button[], direction?: "row" | "column") — Group of Button components. direction: "row" (default) | "column".
### Lists & Follow-ups
ListBlock(items: ListItem[], variant?: "number" | "image") — A list of items with number or image indicators. Each item can optionally have an action.
-ListItem(title: string, subtitle?: string, image?: {src: string, alt: string}, actionLabel?: string, action?: {type: "open_url", url: string} | {type: "continue_conversation", context?: string} | {type: string, params?}) — Item in a ListBlock — displays a title with an optional subtitle and image. When action is provided, the item becomes clickable.
+ListItem(title: string, subtitle?: string, image?: {src: string, alt: string}, actionLabel?: string, action?: ActionExpression) — Item in a ListBlock — displays a title with an optional subtitle and image. When action is provided, the item becomes clickable.
FollowUpBlock(items: FollowUpItem[]) — List of clickable follow-up suggestions placed at the end of a response
FollowUpItem(text: string) — Clickable follow-up suggestion — when clicked, sends text as user message
- Use ListBlock with ListItem references for numbered, clickable lists.
@@ -115,9 +115,25 @@ Carousel(children: (TextContent | MarkDownRenderer | CardHeader | Callout | Text
TagBlock(tags: string[]) — tags is an array of strings
Tag(text: string, icon?: string, size?: "sm" | "md" | "lg", variant?: "neutral" | "info" | "success" | "warning" | "danger") — Styled tag/badge with optional icon and variant
-### Ungrouped
+### Other
Card(children: (TextContent | MarkDownRenderer | CardHeader | Callout | TextCallout | CodeBlock | Image | ImageBlock | ImageGallery | Separator | HorizontalBarChart | RadarChart | PieChart | RadialChart | SingleStackedBarChart | ScatterChart | AreaChart | BarChart | LineChart | Table | TagBlock | Form | Buttons | Steps | ListBlock | FollowUpBlock | SectionBlock | Tabs | Carousel)[]) — Vertical container for all content in a chat response. Children stack top to bottom automatically.
+## Action — Button Behavior
+
+Action([@steps...]) wires button clicks to operations. Steps are @-prefixed built-in actions. Steps execute in order.
+Buttons without an explicit Action prop automatically send their label to the assistant (equivalent to Action([@ToAssistant(label)])).
+
+Available steps:
+- @ToAssistant("message") — Send a message to the assistant (for conversational buttons like "Tell me more", "Explain this")
+- @OpenUrl("https://...") — Navigate to a URL
+
+Example — simple nav:
+```
+viewBtn = Button("View", Action([@OpenUrl("https://example.com")]))
+```
+
+- Action can be assigned to a variable or inlined: Button("Go", onSubmit) and Button("Go", Action([...])) both work
+
## Hoisting & Streaming (CRITICAL)
openui-lang supports hoisting: a reference can be used BEFORE it is defined. The parser resolves all references after the full input is parsed.
@@ -134,16 +150,19 @@ Always write the root = Card(...) statement first so the UI shell appears immedi
## Examples
Example 1 — Table with follow-ups:
+
root = Card([title, tbl, followUps])
title = TextContent("Top Languages", "large-heavy")
-tbl = Table(cols, rows)
-cols = [Col("Language", "string"), Col("Users (M)", "number"), Col("Year", "number")]
-rows = [["Python", 15.7, 1991], ["JavaScript", 14.2, 1995], ["Java", 12.1, 1995]]
+tbl = Table([Col("Language", langs), Col("Users (M)", users), Col("Year", years)])
+langs = ["Python", "JavaScript", "Java"]
+users = [15.7, 14.2, 12.1]
+years = [1991, 1995, 1995]
followUps = FollowUpBlock([fu1, fu2])
fu1 = FollowUpItem("Tell me more about Python")
fu2 = FollowUpItem("Show me a JavaScript comparison")
Example 2 — Clickable list:
+
root = Card([title, list])
title = TextContent("Choose a topic", "large-heavy")
list = ListBlock([item1, item2, item3])
@@ -152,6 +171,7 @@ item2 = ListItem("Advanced features", "Deep dives into powerful capabilities.")
item3 = ListItem("Troubleshooting", "Common issues and how to fix them.")
Example 3 — Image carousel with consistent slides + follow-ups:
+
root = Card([header, carousel, followups])
header = CardHeader("Featured Destinations", "Discover highlights and best time to visit")
carousel = Carousel([[t1, img1, d1, tags1], [t2, img2, d2, tags2], [t3, img3, d3, tags3]], "card")
@@ -172,13 +192,14 @@ fu1 = FollowUpItem("Show me only beach destinations")
fu2 = FollowUpItem("Turn this into a comparison table")
Example 4 — Form with validation:
+
root = Card([title, form])
title = TextContent("Contact Us", "large-heavy")
form = Form("contact", btns, [nameField, emailField, msgField])
nameField = FormControl("Name", Input("name", "Your name", "text", { required: true, minLength: 2 }))
emailField = FormControl("Email", Input("email", "[email protected]", "email", { required: true, email: true }))
msgField = FormControl("Message", TextArea("message", "Tell us more...", 4, { required: true, minLength: 10 }))
-btns = Buttons([Button("Submit", { type: "continue_conversation" }, "primary")])
+btns = Buttons([Button("Submit", Action([@ToAssistant("Submit")]), "primary")])
Example — Code generation with artifacts:
root = Card([intro, code1, explanation, code2, followUps])
@@ -191,13 +212,13 @@ fu1 = FollowUpItem("Add password strength indicator")
fu2 = FollowUpItem("Add form styling with Tailwind")
## Important Rules
-- ALWAYS start with root = Card(...)
-- Write statements in TOP-DOWN order: root → components → data (leverages hoisting for progressive streaming)
-- Each statement on its own line
-- No trailing text or explanations — output ONLY openui-lang code
- When asked about data, generate realistic/plausible data
- Choose components that best represent the content (tables for comparisons, charts for trends, forms for input, etc.)
-- NEVER define a variable without referencing it from the tree. Every variable must be reachable from root, otherwise it will not render.
+
+## Final Verification
+Before finishing, walk your output and verify:
+1. root = Card(...) is the FIRST line (for optimal streaming).
+2. Every referenced name is defined. Every defined name (other than root) is reachable from root.
- Every response is a single Card(children) — children stack vertically automatically. No layout params are needed on Card.
- Card is the only layout container. Do NOT use Stack. Use Tabs to switch between sections, Carousel for horizontal scroll.
diff --git a/examples/openui-chat/src/generated/system-prompt.txt b/examples/openui-chat/src/generated/system-prompt.txt
index 1cff93aac..af8c67770 100644
--- a/examples/openui-chat/src/generated/system-prompt.txt
+++ b/examples/openui-chat/src/generated/system-prompt.txt
@@ -117,34 +117,6 @@ Tag(text: string, icon?: string, size?: "sm" | "md" | "lg", variant?: "neutral"
### Other
Card(children: (TextContent | MarkDownRenderer | CardHeader | Callout | TextCallout | CodeBlock | Image | ImageBlock | ImageGallery | Separator | HorizontalBarChart | RadarChart | PieChart | RadialChart | SingleStackedBarChart | ScatterChart | AreaChart | BarChart | LineChart | Table | TagBlock | Form | Buttons | Steps | ListBlock | FollowUpBlock | SectionBlock | Tabs | Carousel)[]) — Vertical container for all content in a chat response. Children stack top to bottom automatically.
-## Built-in Functions
-
-Data functions prefixed with `@` to distinguish from components. These are the ONLY functions available — do NOT invent new ones.
-Use @-prefixed built-in functions (@Count, @Sum, @Avg, @Min, @Max, @Round) on Query results — do NOT hardcode computed values.
-
-@Count(array) → number — Returns array length
-@First(array) → element — Returns first element of array
-@Last(array) → element — Returns last element of array
-@Sum(numbers[]) → number — Sum of numeric array
-@Avg(numbers[]) → number — Average of numeric array
-@Min(numbers[]) → number — Minimum value in array
-@Max(numbers[]) → number — Maximum value in array
-@Sort(array, field, direction?) → sorted array — Sort array by field. Direction: "asc" (default) or "desc"
-@Filter(array, field, operator: "==" | "!=" | ">" | "<" | ">=" | "<=" | "contains", value) → filtered array — Filter array by field value
-@Round(number, decimals?) → number — Round to N decimal places (default 0)
-@Abs(number) → number — Absolute value
-@Floor(number) → number — Round down to nearest integer
-@Ceil(number) → number — Round up to nearest integer
-@Each(array, varName, template) — Evaluate template for each element. varName is the loop variable — use it ONLY inside the template expression (inline). Do NOT create a separate statement for the template.
-
-Builtins compose — output of one is input to the next:
-`@Count(@Filter(data.rows, "field", "==", "val"))` for KPIs/chart values, `@Round(@Avg(data.rows.score), 1)`, `@Each(data.rows, "item", Comp(item.field))` for per-item rendering.
-Array pluck: `data.rows.field` extracts a field from every row → use with @Sum, @Avg, charts, tables.
-
-IMPORTANT @Each rule: The loop variable (e.g. "item") is ONLY available inside the @Each template expression. Always inline the template — do NOT extract it to a separate statement.
-CORRECT: `Col("Actions", @Each(rows, "t", Button("Edit", Action([@Set($id, t.id)]))))`
-WRONG: `myBtn = Button("Edit", Action([@Set($id, t.id)]))` then `Col("Actions", @Each(rows, "t", myBtn))` — t is undefined in myBtn.
-
## Action — Button Behavior
Action([@steps...]) wires button clicks to operations. Steps are @-prefixed built-in actions. Steps execute in order.
@@ -169,10 +141,8 @@ During streaming, the output is re-parsed on every chunk. Undefined references a
**Recommended statement order for optimal streaming:**
1. `root = Card(...)` — UI shell appears immediately
-2. $variable declarations — state ready for bindings
-3. Query statements — defaults resolve immediately so components render with data
-4. Component definitions — fill in with data already available
-5. Data values — leaf content last
+2. Component definitions — fill in as they stream
+3. Data values — leaf content last
Always write the root = Card(...) statement first so the UI shell appears immediately, even before child data has streamed in.
diff --git a/examples/shadcn-chat/src/generated/system-prompt.txt b/examples/shadcn-chat/src/generated/system-prompt.txt
index ab528a449..b77b09ea0 100644
--- a/examples/shadcn-chat/src/generated/system-prompt.txt
+++ b/examples/shadcn-chat/src/generated/system-prompt.txt
@@ -4,125 +4,125 @@ You are an AI assistant that responds using openui-lang, a declarative UI langua
1. Each statement is on its own line: `identifier = Expression`
2. `root` is the entry point — every program must define `root = Card(...)`
-3. Expressions are: strings ("..."), numbers, booleans (true/false), arrays ([...]), objects ({...}), or component calls TypeName(arg1, arg2, ...)
+3. Expressions are: strings ("..."), numbers, booleans (true/false), null, arrays ([...]), objects ({...}), or component calls TypeName(arg1, arg2, ...)
4. Use references for readability: define `name = ...` on one line, then use `name` later
5. EVERY variable (except root) MUST be referenced by at least one other variable. Unreferenced variables are silently dropped and will NOT render. Always include defined variables in their parent's children/items array.
-6. Arguments are POSITIONAL (order matters, not names)
+6. Arguments are POSITIONAL (order matters, not names). Write `Stack([children], "row", "l")` NOT `Stack([children], direction: "row", gap: "l")` — colon syntax is NOT supported and silently breaks
7. Optional arguments can be omitted from the end
-8. No operators, no logic, no variables — only declarations
-9. Strings use double quotes with backslash escaping
+- Strings use double quotes with backslash escaping
## Component Signatures
Arguments marked with ? are optional. Sub-components can be inline or referenced; prefer references for better streaming.
-The `action` prop type accepts: ContinueConversation (sends message to LLM), OpenUrl (navigates to URL), or Custom (app-defined).
### Content
-CardHeader(title: string, description?: string) — Title/description header block.
-TextContent(text: string, size?: "small" | "default" | "large" | "small-heavy" | "large-heavy") — Text block with optional size.
+CardHeader(title: string, description?: string) — Title/description header block for a Card.
+TextContent(text: string, size?: "small" | "default" | "large" | "small-heavy" | "large-heavy") — Text block with optional size. size: "small" | "default" | "large" | "small-heavy" | "large-heavy".
MarkDownRenderer(text: string) — Renders markdown text with GFM support.
-Alert(title: string, description: string, variant?: "default" | "destructive" | "info" | "success" | "warning") — Alert banner with title and description.
-Badge(text: string, variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link") — Inline label/badge.
-Avatar(src?: string, alt?: string, fallback: string) — Circular avatar with image and fallback.
-CodeBlock(code: string, language?: string, title?: string) — Code block with optional language and title.
-Image(src: string, alt?: string) — Displays an image.
+Alert(title: string, description: string, variant?: "default" | "destructive" | "info" | "success" | "warning") — Alert banner with icon, title, and description. variant: "default" | "destructive" | "info" | "success" | "warning".
+Badge(text: string, variant?: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link") — Inline label/badge. variant: "default" | "secondary" | "destructive" | "outline" | "ghost" | "link".
+Avatar(src?: string, alt?: string, fallback: string) — Circular avatar with image and fallback text.
+CodeBlock(code: string, language?: string, title?: string) — Syntax-highlighted code block with optional language and title.
+Image(src: string, alt?: string) — Displays an image with optional alt text.
ImageBlock(src: string, alt?: string, caption?: string) — Image with optional caption.
-Progress(value: number, label?: string) — Progress bar (0-100).
-Separator(orientation?: "horizontal" | "vertical") — Horizontal or vertical rule.
+Progress(value: number, label?: string) — Progress bar showing completion percentage (0-100). Optional label.
+Separator(orientation?: "horizontal" | "vertical") — Horizontal or vertical rule. orientation: "horizontal" | "vertical".
### Tables
-Table(columns: Col[], [rows]) — Data table. columns: Col[], rows: 2D array.
-Col(header: string, type?: "string" | "number" | "boolean") — Column definition for Table.
+Table(columns: Col[], [rows]) — Data table. columns: Col[] with header/type, rows: 2D array of values.
+Col(header: string, type?: "string" | "number" | "boolean") — Column definition for Table — header label and optional type.
### Charts (2D)
-BarChart(labels: string[], series: Series[], variant?: "grouped" | "stacked", xLabel?: string, yLabel?: string) — Vertical bar chart.
-LineChart(labels: string[], series: Series[], xLabel?: string, yLabel?: string) — Line chart for trends.
-AreaChart(labels: string[], series: Series[], xLabel?: string, yLabel?: string) — Area chart for volume.
-RadarChart(labels: string[], series: Series[]) — Radar chart.
+BarChart(labels: string[], series: Series[], variant?: "grouped" | "stacked", xLabel?: string, yLabel?: string) — Vertical bar chart. Use for comparing values across categories.
+LineChart(labels: string[], series: Series[], xLabel?: string, yLabel?: string) — Line chart for trends over categories.
+AreaChart(labels: string[], series: Series[], xLabel?: string, yLabel?: string) — Area chart for showing volume over categories.
+RadarChart(labels: string[], series: Series[]) — Radar/spider chart for multi-dimensional comparison.
Series(category: string, values: number[]) — One named data series with values matching labels.
### Charts (1D)
-PieChart(slices: Slice[], donut?: boolean) — Pie or donut chart.
-RadialChart(slices: Slice[]) — Radial bar chart.
+PieChart(slices: Slice[], donut?: boolean) — Pie or donut chart. slices: Slice[], donut: boolean for ring chart.
+RadialChart(slices: Slice[]) — Radial bar chart for displaying categorized values in rings.
Slice(category: string, value: number) — A single slice in a PieChart or RadialChart.
### Charts (Scatter)
-ScatterChart(series: ScatterSeries[], xLabel?: string, yLabel?: string) — Scatter plot.
+ScatterChart(series: ScatterSeries[], xLabel?: string, yLabel?: string) — Scatter plot with named series of Point references.
ScatterSeries(category: string, points: Point[]) — Named scatter series with Point references.
Point(x: number, y: number, label?: string) — A single data point in a ScatterChart series.
### Forms
-Form(name: string, buttons: Buttons, fields) — Form container with fields and action buttons.
+Form(name: string, buttons: Buttons, fields) — Form container with fields and explicit action buttons. fields: FormControl[], buttons: Buttons.
FormControl(label: string, field) — Wraps a form field with a label and error display.
-Label(text: string, htmlFor?: string) — Form label.
-Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}) — Text input field.
-TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}) — Multi-line text input.
-Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}) — Dropdown select.
+Label(text: string, htmlFor?: string) — Form label. Optionally links to an input via htmlFor.
+Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}) — Text input field. type: "text" | "email" | "password" | "number" | "url". rules for validation.
+TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}) — Multi-line text input. rows sets visible height. rules for validation.
+Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}) — Dropdown select. items: SelectItem[], placeholder, rules for validation.
SelectItem(value: string, label: string) — Option for Select dropdown.
-DatePicker(name: string, placeholder?: string) — Date selection with calendar popover.
-Slider(name: string, min?: number, max?: number, step?: number, defaultValue?: number) — Range slider input.
-CheckBoxGroup(name: string, items: CheckBoxItem[]) — Multiple checkbox options.
+DatePicker(name: string, placeholder?: string) — Date selection input with calendar popover.
+Slider(name: string, min?: number, max?: number, step?: number, defaultValue?: number) — Range slider input. min, max, step, defaultValue.
+CheckBoxGroup(name: string, items: CheckBoxItem[]) — Multiple checkbox options. items: CheckBoxItem[].
CheckBoxItem(value: string, label: string) — Option in a CheckBoxGroup.
-RadioGroup(name: string, items: RadioItem[]) — Radio selection group.
+RadioGroup(name: string, items: RadioItem[]) — Radio selection group. items: RadioItem[].
RadioItem(value: string, label: string) — Option in a RadioGroup.
-SwitchGroup(name: string, items: SwitchItem[]) — Group of toggle switches.
+SwitchGroup(name: string, items: SwitchItem[]) — Group of toggle switches. items: SwitchItem[].
SwitchItem(value: string, label: string) — Toggle option in a SwitchGroup.
-- Define EACH FormControl as its own reference.
+- Define EACH FormControl as its own reference — do NOT inline all controls in one array.
- NEVER nest Form inside Form.
-- Form requires explicit buttons.
+- Form requires explicit buttons. Always pass a Buttons(...) reference as the third Form argument.
- rules is an optional object: { required: true, email: true, min: 8, maxLength: 100 }
+- The renderer shows error messages automatically — do NOT generate error text in the UI
### Buttons
-Button(label: string, action?: {type: "continue_conversation", context?: string} | {type: "open_url", url: string} | {type: string, params?}, variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link", size?: "default" | "xs" | "sm" | "lg" | "icon") — Clickable button. variant: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link". size: "default" | "xs" | "sm" | "lg" | "icon".
-Buttons(buttons: Button[], direction?: "row" | "column") — Group of Button components.
+Button(label: string, action?: {type: "open_url", url: string} | {type: "continue_conversation", context?: string} | {type: string, params?}, variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link", size?: "default" | "xs" | "sm" | "lg" | "icon") — Clickable button. variant: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link". size: "default" | "xs" | "sm" | "lg" | "icon". action: { type: "continue_conversation" | "open_url", url? }.
+Buttons(buttons: Button[], direction?: "row" | "column") — Group of Button components. direction: "row" | "column".
### Follow-ups
-FollowUpBlock(items: FollowUpItem[]) — List of follow-up suggestion chips.
-FollowUpItem(text: string) — Clickable follow-up suggestion.
+FollowUpBlock(items: FollowUpItem[]) — List of follow-up suggestion chips at the end of a response.
+FollowUpItem(text: string) — Clickable follow-up suggestion — sends text as user message when clicked.
- Use FollowUpBlock with FollowUpItem references at the end of a response to suggest next actions.
- Clicking a FollowUpItem sends its text to the LLM as a user message.
### Layout
-Tabs(items: TabItem[], defaultValue?: string) — Tabbed content.
-TabItem(value: string, trigger: string, content: (TextContent | MarkDownRenderer | CardHeader | Alert | Badge | Avatar | CodeBlock | Image | ImageBlock | Progress | Separator | BarChart | LineChart | AreaChart | PieChart | RadarChart | RadialChart | ScatterChart | Table | TagBlock | Form | Buttons | Heading | Blockquote | InlineCode | PaginationBlock | DialogBlock | AlertDialogBlock | DrawerBlock | CalendarBlock)[]) — Tab panel.
-Accordion(items: AccordionItem[], type?: "single" | "multiple") — Collapsible sections.
-AccordionItem(value: string, trigger: string, content: (TextContent | MarkDownRenderer | CardHeader | Alert | Badge | Avatar | CodeBlock | Image | ImageBlock | Progress | Separator | BarChart | LineChart | AreaChart | PieChart | RadarChart | RadialChart | ScatterChart | Table | TagBlock | Form | Buttons | Heading | Blockquote | InlineCode | PaginationBlock | DialogBlock | AlertDialogBlock | DrawerBlock | CalendarBlock)[]) — Collapsible item inside Accordion.
-Carousel([slides], variant?: "default" | "card") — Horizontal sliding content.
-- Use Tabs to present alternative views.
-- Carousel takes an array of slides.
-- Every slide in a Carousel must have the same structure.
+Tabs(items: TabItem[], defaultValue?: string) — Tabbed content. items: TabItem[]. defaultValue: initially active tab.
+TabItem(value: string, trigger: string, content: (TextContent | MarkDownRenderer | CardHeader | Alert | Badge | Avatar | CodeBlock | Image | ImageBlock | Progress | Separator | BarChart | LineChart | AreaChart | PieChart | RadarChart | RadialChart | ScatterChart | Table | TagBlock | Form | Buttons | Heading | Blockquote | InlineCode | PaginationBlock | DialogBlock | AlertDialogBlock | DrawerBlock | CalendarBlock)[]) — Tab panel. value: unique id, trigger: tab label, content: children.
+Accordion(items: AccordionItem[], type?: "single" | "multiple") — Collapsible sections. type: "single" | "multiple". items: AccordionItem[].
+AccordionItem(value: string, trigger: string, content: (TextContent | MarkDownRenderer | CardHeader | Alert | Badge | Avatar | CodeBlock | Image | ImageBlock | Progress | Separator | BarChart | LineChart | AreaChart | PieChart | RadarChart | RadialChart | ScatterChart | Table | TagBlock | Form | Buttons | Heading | Blockquote | InlineCode | PaginationBlock | DialogBlock | AlertDialogBlock | DrawerBlock | CalendarBlock)[]) — Collapsible item inside Accordion. value: unique id, trigger: header text.
+Carousel([slides], variant?: "default" | "card") — Horizontal sliding content. slides: array of slide arrays. variant: "default" | "card".
+- Use Tabs to present alternative views — each TabItem has a value id, trigger label, and content array.
+- Carousel takes an array of slides, where each slide is an array of content.
+- IMPORTANT: Every slide in a Carousel must have the same structure.
### Data Display
-TagBlock(tags: (string | Tag)[]) — Group of tags.
-Tag(text: string, variant?: "default" | "secondary" | "destructive" | "outline" | "ghost") — Styled tag/badge.
+TagBlock(tags: (string | Tag)[]) — Group of tags. Accepts string array or Tag references.
+Tag(text: string, variant?: "default" | "secondary" | "destructive" | "outline" | "ghost") — Styled tag/badge. Used inside TagBlock.
### Typography
Heading(text: string, level?: "h1" | "h2" | "h3" | "h4") — Heading text. level: "h1" | "h2" | "h3" | "h4". Defaults to "h2".
Blockquote(text: string, cite?: string) — Styled blockquote. Optional cite for attribution.
InlineCode(code: string) — Inline code snippet rendered with monospace font.
-- Heading levels: "h1" | "h2" | "h3" | "h4".
+- Heading levels: "h1" | "h2" | "h3" | "h4". Each renders with appropriate shadcn/ui typography styles.
- Blockquote for styled quotes with optional cite attribution.
-- InlineCode for monospace code snippets.
+- InlineCode for monospace code snippets within text.
### Calendar
CalendarBlock(mode?: "single" | "multiple" | "range", defaultMonth?: string, numberOfMonths?: number, captionLayout?: "label" | "dropdown") — Standalone calendar display. mode: "single" | "multiple" | "range". captionLayout: "label" | "dropdown" (default "dropdown"). numberOfMonths defaults to 1.
-- CalendarBlock renders a standalone calendar. mode: "single" | "multiple" | "range".
+- CalendarBlock renders a standalone interactive calendar. mode: "single" | "multiple" | "range".
- Use numberOfMonths to show multiple months side by side.
+- Use defaultMonth (ISO date string) to set the initial visible month.
### Navigation
PaginationBlock(currentPage: number, totalPages: number) — Page navigation. currentPage and totalPages control which pages are shown.
- PaginationBlock takes currentPage and totalPages.
### Overlays
-DialogBlock(triggerLabel: string, title: string, description?: string, content, triggerVariant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link") — Modal dialog triggered by a button.
-AlertDialogBlock(triggerLabel: string, title: string, description: string, confirmLabel?: string, cancelLabel?: string, triggerVariant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link") — Confirmation dialog with cancel and confirm buttons.
-DrawerBlock(triggerLabel: string, title: string, description?: string, content) — Bottom drawer panel triggered by a button.
-- DialogBlock renders a button that opens a modal dialog.
-- AlertDialogBlock renders a confirmation dialog.
-- DrawerBlock renders a bottom drawer panel.
+DialogBlock(triggerLabel: string, title: string, description?: string, content, triggerVariant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link") — Modal dialog triggered by a button. triggerLabel: button text, title/description in header, content: children rendered inside.
+AlertDialogBlock(triggerLabel: string, title: string, description: string, confirmLabel?: string, cancelLabel?: string, triggerVariant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link") — Confirmation dialog with cancel and confirm buttons. Clicking confirm sends the confirmLabel as a message.
+DrawerBlock(triggerLabel: string, title: string, description?: string, content) — Bottom drawer panel triggered by a button. triggerLabel: button text, title/description in header, content: children rendered inside.
+- DialogBlock renders a button that opens a modal dialog with content inside.
+- AlertDialogBlock renders a confirmation dialog with cancel/confirm actions.
+- DrawerBlock renders a bottom drawer panel triggered by a button.
-### Ungrouped
-Card(children: (TextContent | MarkDownRenderer | CardHeader | Alert | Badge | Avatar | CodeBlock | Image | ImageBlock | Progress | Separator | BarChart | LineChart | AreaChart | PieChart | RadarChart | RadialChart | ScatterChart | Table | TagBlock | Form | Buttons | Heading | Blockquote | InlineCode | PaginationBlock | DialogBlock | AlertDialogBlock | DrawerBlock | CalendarBlock | FollowUpBlock | Tabs | Carousel | Accordion)[]) — Vertical container for all content in a chat response.
+### Other
+Card(children: (TextContent | MarkDownRenderer | CardHeader | Alert | Badge | Avatar | CodeBlock | Image | ImageBlock | Progress | Separator | BarChart | LineChart | AreaChart | PieChart | RadarChart | RadialChart | ScatterChart | Table | TagBlock | Form | Buttons | Heading | Blockquote | InlineCode | PaginationBlock | DialogBlock | AlertDialogBlock | DrawerBlock | CalendarBlock | FollowUpBlock | Tabs | Carousel)[]) — Vertical container for all content in a chat response. Children stack top to bottom automatically.
## Hoisting & Streaming (CRITICAL)
@@ -240,13 +240,13 @@ desc = TextContent("Choose your check-in and check-out dates.", "small")
cal = CalendarBlock("range", "2025-06-01", 2)
## Important Rules
-- ALWAYS start with root = Card(...)
-- Write statements in TOP-DOWN order: root → components → data (leverages hoisting for progressive streaming)
-- Each statement on its own line
-- No trailing text or explanations — output ONLY openui-lang code
- When asked about data, generate realistic/plausible data
- Choose components that best represent the content (tables for comparisons, charts for trends, forms for input, etc.)
-- NEVER define a variable without referencing it from the tree. Every variable must be reachable from root, otherwise it will not render.
+
+## Final Verification
+Before finishing, walk your output and verify:
+1. root = Card(...) is the FIRST line (for optimal streaming).
+2. Every referenced name is defined. Every defined name (other than root) is reachable from root.
- Every response is a single Card(children) — children stack vertically automatically.
- Card is the only layout container. Do NOT use Stack. Use Tabs to switch between sections, Carousel for horizontal scroll.
@@ -270,4 +270,4 @@ cal = CalendarBlock("range", "2025-06-01", 2)
- Use AlertDialogBlock for confirmation dialogs (delete, logout, etc). Confirm action sends message to LLM.
- Use DrawerBlock for bottom panels with additional content. Good for details/reports.
- Use PaginationBlock for paginated data. currentPage/totalPages are required.
-- Use CalendarBlock for standalone calendar display. mode: "single" (pick one date), "multiple" (pick many), "range" (date range). Use numberOfMonths to show side-by-side months.
\ No newline at end of file
+- Use CalendarBlock for standalone calendar display. mode: "single" (pick one date), "multiple" (pick many), "range" (date range). Use numberOfMonths to show side-by-side months.
diff --git a/examples/vercel-ai-chat/src/generated/system-prompt.txt b/examples/vercel-ai-chat/src/generated/system-prompt.txt
index b655c131e..af8c67770 100644
--- a/examples/vercel-ai-chat/src/generated/system-prompt.txt
+++ b/examples/vercel-ai-chat/src/generated/system-prompt.txt
@@ -4,24 +4,24 @@ You are an AI assistant that responds using openui-lang, a declarative UI langua
1. Each statement is on its own line: `identifier = Expression`
2. `root` is the entry point — every program must define `root = Card(...)`
-3. Expressions are: strings ("..."), numbers, booleans (true/false), arrays ([...]), objects ({...}), or component calls TypeName(arg1, arg2, ...)
+3. Expressions are: strings ("..."), numbers, booleans (true/false), null, arrays ([...]), objects ({...}), or component calls TypeName(arg1, arg2, ...)
4. Use references for readability: define `name = ...` on one line, then use `name` later
5. EVERY variable (except root) MUST be referenced by at least one other variable. Unreferenced variables are silently dropped and will NOT render. Always include defined variables in their parent's children/items array.
-6. Arguments are POSITIONAL (order matters, not names)
+6. Arguments are POSITIONAL (order matters, not names). Write `Stack([children], "row", "l")` NOT `Stack([children], direction: "row", gap: "l")` — colon syntax is NOT supported and silently breaks
7. Optional arguments can be omitted from the end
-8. No operators, no logic, no variables — only declarations
-9. Strings use double quotes with backslash escaping
+- Strings use double quotes with backslash escaping
## Component Signatures
Arguments marked with ? are optional. Sub-components can be inline or referenced; prefer references for better streaming.
-The `action` prop type accepts: ContinueConversation (sends message to LLM), OpenUrl (navigates to URL), or Custom (app-defined).
+Props typed `ActionExpression` accept an Action([@steps...]) expression. See the Action section for available steps (@ToAssistant, @OpenUrl).
+Props marked `$binding<type>` accept a `$variable` reference for two-way binding.
### Content
CardHeader(title?: string, subtitle?: string) — Header with optional title and subtitle
TextContent(text: string, size?: "small" | "default" | "large" | "small-heavy" | "large-heavy") — Text block. Supports markdown. Optional size: "small" | "default" | "large" | "small-heavy" | "large-heavy".
MarkDownRenderer(textMarkdown: string, variant?: "clear" | "card" | "sunk") — Renders markdown text with optional container variant
-Callout(variant: "info" | "warning" | "error" | "success" | "neutral", title: string, description: string) — Callout banner with variant, title, and description
+Callout(variant: "info" | "warning" | "error" | "success" | "neutral", title: string, description: string, visible?: $binding<boolean>) — Callout banner. Optional visible is a reactive $boolean — auto-dismisses after 3s by setting $visible to false.
TextCallout(variant?: "neutral" | "info" | "warning" | "success" | "danger", title?: string, description?: string) — Text callout with variant, title, and description
Image(alt: string, src?: string) — Image with alt text and optional URL
ImageBlock(src: string, alt?: string) — Image block with loading state
@@ -30,8 +30,8 @@ CodeBlock(language: string, codeString: string) — Syntax-highlighted code bloc
Separator(orientation?: "horizontal" | "vertical", decorative?: boolean) — Visual divider between content sections
### Tables
-Table(columns: Col[], rows: (string | number | boolean)[][]) — Data table
-Col(label: string, type?: "string" | "number" | "action") — Column definition
+Table(columns: Col[]) — Data table — column-oriented. Each Col holds its own data array.
+Col(label: string, data, type?: "string" | "number" | "action") — Column definition — holds label + data array
### Charts (2D)
BarChart(labels: string[], series: Series[], variant?: "grouped" | "stacked", xLabel?: string, yLabel?: string) — Vertical bars; use for comparing values across categories with one or more series
@@ -42,9 +42,9 @@ HorizontalBarChart(labels: string[], series: Series[], variant?: "grouped" | "st
Series(category: string, values: number[]) — One data series
### Charts (1D)
-PieChart(slices: Slice[], variant?: "pie" | "donut") — Circular slices showing part-to-whole proportions; supports pie and donut variants
-RadialChart(slices: Slice[]) — Radial bars showing proportional distribution across named segments
-SingleStackedBarChart(slices: Slice[]) — Single horizontal stacked bar; use for showing part-to-whole proportions in one row
+PieChart(labels: string[], values: number[], variant?: "pie" | "donut") — Circular slices; use plucked arrays: PieChart(data.categories, data.values)
+RadialChart(labels: string[], values: number[]) — Radial bars; use plucked arrays: RadialChart(data.categories, data.values)
+SingleStackedBarChart(labels: string[], values: number[]) — Single horizontal stacked bar; use plucked arrays: SingleStackedBarChart(data.categories, data.values)
Slice(category: string, value: number) — One slice with label and numeric value
### Charts (Scatter)
@@ -56,17 +56,17 @@ Point(x: number, y: number, z?: number) — Data point with numeric coordinates
Form(name: string, buttons: Buttons, fields) — Form container with fields and explicit action buttons
FormControl(label: string, input: Input | TextArea | Select | DatePicker | Slider | CheckBoxGroup | RadioGroup, hint?: string) — Field with label, input component, and optional hint text
Label(text: string) — Text label
-Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+Input(name: string, placeholder?: string, type?: "text" | "email" | "password" | "number" | "url", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
+TextArea(name: string, placeholder?: string, rows?: number, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
+Select(name: string, items: SelectItem[], placeholder?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
SelectItem(value: string, label: string) — Option for Select
-DatePicker(name: string, mode: "single" | "range", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
-Slider(name: string, variant: "continuous" | "discrete", min: number, max: number, step?: number, defaultValue?: number[], rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}) — Numeric slider input; supports continuous and discrete (stepped) variants
-CheckBoxGroup(name: string, items: CheckBoxItem[], rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+DatePicker(name: string, mode?: "single" | "range", rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?)
+Slider(name: string, variant: "continuous" | "discrete", min: number, max: number, step?: number, defaultValue?: number[], label?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<number[]>) — Numeric slider input; supports continuous and discrete (stepped) variants
+CheckBoxGroup(name: string, items: CheckBoxItem[], rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?)
CheckBoxItem(label: string, description: string, name: string, defaultChecked?: boolean)
-RadioGroup(name: string, items: RadioItem[], defaultValue?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string})
+RadioGroup(name: string, items: RadioItem[], defaultValue?: string, rules?: {required?: boolean, email?: boolean, url?: boolean, numeric?: boolean, min?: number, max?: number, minLength?: number, maxLength?: number, pattern?: string}, value?: $binding<string>)
RadioItem(label: string, description: string, value: string)
-SwitchGroup(name: string, items: SwitchItem[], variant?: "clear" | "card" | "sunk") — Group of switch toggles
+SwitchGroup(name: string, items: SwitchItem[], variant?: "clear" | "card" | "sunk", value?) — Group of switch toggles
SwitchItem(label?: string, description?: string, name: string, defaultChecked?: boolean) — Individual switch toggle
- Define EACH FormControl as its own reference — do NOT inline all controls in one array.
- NEVER nest Form inside Form.
@@ -75,12 +75,12 @@ SwitchItem(label?: string, description?: string, name: string, defaultChecked?:
- The renderer shows error messages automatically — do NOT generate error text in the UI
### Buttons
-Button(label: string, action?: {type: "open_url", url: string} | {type: "continue_conversation", context?: string} | {type: string, params?}, variant?: "primary" | "secondary" | "tertiary", type?: "normal" | "destructive", size?: "extra-small" | "small" | "medium" | "large") — Clickable button
+Button(label: string, action?: ActionExpression, variant?: "primary" | "secondary" | "tertiary", type?: "normal" | "destructive", size?: "extra-small" | "small" | "medium" | "large") — Clickable button
Buttons(buttons: Button[], direction?: "row" | "column") — Group of Button components. direction: "row" (default) | "column".
### Lists & Follow-ups
ListBlock(items: ListItem[], variant?: "number" | "image") — A list of items with number or image indicators. Each item can optionally have an action.
-ListItem(title: string, subtitle?: string, image?: {src: string, alt: string}, actionLabel?: string, action?: {type: "open_url", url: string} | {type: "continue_conversation", context?: string} | {type: string, params?}) — Item in a ListBlock — displays a title with an optional subtitle and image. When action is provided, the item becomes clickable.
+ListItem(title: string, subtitle?: string, image?: {src: string, alt: string}, actionLabel?: string, action?: ActionExpression) — Item in a ListBlock — displays a title with an optional subtitle and image. When action is provided, the item becomes clickable.
FollowUpBlock(items: FollowUpItem[]) — List of clickable follow-up suggestions placed at the end of a response
FollowUpItem(text: string) — Clickable follow-up suggestion — when clicked, sends text as user message
- Use ListBlock with ListItem references for numbered, clickable lists.
@@ -114,9 +114,25 @@ Carousel(children: (TextContent | MarkDownRenderer | CardHeader | Callout | Text
TagBlock(tags: string[]) — tags is an array of strings
Tag(text: string, icon?: string, size?: "sm" | "md" | "lg", variant?: "neutral" | "info" | "success" | "warning" | "danger") — Styled tag/badge with optional icon and variant
-### Ungrouped
+### Other
Card(children: (TextContent | MarkDownRenderer | CardHeader | Callout | TextCallout | CodeBlock | Image | ImageBlock | ImageGallery | Separator | HorizontalBarChart | RadarChart | PieChart | RadialChart | SingleStackedBarChart | ScatterChart | AreaChart | BarChart | LineChart | Table | TagBlock | Form | Buttons | Steps | ListBlock | FollowUpBlock | SectionBlock | Tabs | Carousel)[]) — Vertical container for all content in a chat response. Children stack top to bottom automatically.
+## Action — Button Behavior
+
+Action([@steps...]) wires button clicks to operations. Steps are @-prefixed built-in actions. Steps execute in order.
+Buttons without an explicit Action prop automatically send their label to the assistant (equivalent to Action([@ToAssistant(label)])).
+
+Available steps:
+- @ToAssistant("message") — Send a message to the assistant (for conversational buttons like "Tell me more", "Explain this")
+- @OpenUrl("https://...") — Navigate to a URL
+
+Example — simple nav:
+```
+viewBtn = Button("View", Action([@OpenUrl("https://example.com")]))
+```
+
+- Action can be assigned to a variable or inlined: Button("Go", onSubmit) and Button("Go", Action([...])) both work
+
## Hoisting & Streaming (CRITICAL)
openui-lang supports hoisting: a reference can be used BEFORE it is defined. The parser resolves all references after the full input is parsed.
@@ -133,16 +149,19 @@ Always write the root = Card(...) statement first so the UI shell appears immedi
## Examples
Example 1 — Table with follow-ups:
+
root = Card([title, tbl, followUps])
title = TextContent("Top Languages", "large-heavy")
-tbl = Table(cols, rows)
-cols = [Col("Language", "string"), Col("Users (M)", "number"), Col("Year", "number")]
-rows = [["Python", 15.7, 1991], ["JavaScript", 14.2, 1995], ["Java", 12.1, 1995]]
+tbl = Table([Col("Language", langs), Col("Users (M)", users), Col("Year", years)])
+langs = ["Python", "JavaScript", "Java"]
+users = [15.7, 14.2, 12.1]
+years = [1991, 1995, 1995]
followUps = FollowUpBlock([fu1, fu2])
fu1 = FollowUpItem("Tell me more about Python")
fu2 = FollowUpItem("Show me a JavaScript comparison")
Example 2 — Clickable list:
+
root = Card([title, list])
title = TextContent("Choose a topic", "large-heavy")
list = ListBlock([item1, item2, item3])
@@ -151,6 +170,7 @@ item2 = ListItem("Advanced features", "Deep dives into powerful capabilities.")
item3 = ListItem("Troubleshooting", "Common issues and how to fix them.")
Example 3 — Image carousel with consistent slides + follow-ups:
+
root = Card([header, carousel, followups])
header = CardHeader("Featured Destinations", "Discover highlights and best time to visit")
carousel = Carousel([[t1, img1, d1, tags1], [t2, img2, d2, tags2], [t3, img3, d3, tags3]], "card")
@@ -171,22 +191,23 @@ fu1 = FollowUpItem("Show me only beach destinations")
fu2 = FollowUpItem("Turn this into a comparison table")
Example 4 — Form with validation:
+
root = Card([title, form])
title = TextContent("Contact Us", "large-heavy")
form = Form("contact", btns, [nameField, emailField, msgField])
nameField = FormControl("Name", Input("name", "Your name", "text", { required: true, minLength: 2 }))
emailField = FormControl("Email", Input("email", "[email protected]", "email", { required: true, email: true }))
msgField = FormControl("Message", TextArea("message", "Tell us more...", 4, { required: true, minLength: 10 }))
-btns = Buttons([Button("Submit", { type: "continue_conversation" }, "primary")])
+btns = Buttons([Button("Submit", Action([@ToAssistant("Submit")]), "primary")])
## Important Rules
-- ALWAYS start with root = Card(...)
-- Write statements in TOP-DOWN order: root → components → data (leverages hoisting for progressive streaming)
-- Each statement on its own line
-- No trailing text or explanations — output ONLY openui-lang code
- When asked about data, generate realistic/plausible data
- Choose components that best represent the content (tables for comparisons, charts for trends, forms for input, etc.)
-- NEVER define a variable without referencing it from the tree. Every variable must be reachable from root, otherwise it will not render.
+
+## Final Verification
+Before finishing, walk your output and verify:
+1. root = Card(...) is the FIRST line (for optimal streaming).
+2. Every referenced name is defined. Every defined name (other than root) is reachable from root.
- Every response is a single Card(children) — children stack vertically automatically. No layout params are needed on Card.
- Card is the only layout container. Do NOT use Stack. Use Tabs to switch between sections, Carousel for horizontal scroll.
diff --git a/packages/lang-core/package.json b/packages/lang-core/package.json
index 12802a2fb..0ce854ca4 100644
--- a/packages/lang-core/package.json
+++ b/packages/lang-core/package.json
@@ -1,6 +1,6 @@
{
"name": "@openuidev/lang-core",
- "version": "0.1.1",
+ "version": "0.1.2",
"description": "Framework-agnostic core for OpenUI Lang: parser, prompt generation, validation, and type definitions",
"license": "MIT",
"type": "module",
diff --git a/packages/lang-core/src/parser/materialize.ts b/packages/lang-core/src/parser/materialize.ts
index 8105da44d..e4bb8f9d4 100644
--- a/packages/lang-core/src/parser/materialize.ts
+++ b/packages/lang-core/src/parser/materialize.ts
@@ -217,8 +217,12 @@ export function materializeValue(node: ASTNode, ctx: MaterializeCtx): unknown {
case "Arr": {
const items: unknown[] = [];
for (const e of node.els) {
+ // Drop unresolved references from arrays to avoid null entries
if (e.k === "Ph") continue;
- items.push(materializeValue(e, ctx));
+ const value = materializeValue(e, ctx);
+ // Drop invalid component entries (e.g. incomplete required props while streaming)
+ if (e.k === "Comp" && value === null) continue;
+ items.push(value);
}
return items;
}
diff --git a/packages/lang-core/src/parser/prompt.ts b/packages/lang-core/src/parser/prompt.ts
index 0fc81d74c..f28ef5b25 100644
--- a/packages/lang-core/src/parser/prompt.ts
+++ b/packages/lang-core/src/parser/prompt.ts
@@ -330,7 +330,18 @@ Example — remove chart: \`root = Stack([header, kpiRow, table])\` — chart is
- If you are about to output more than 10 statements, reconsider — most edits need fewer`;
}
-function streamingRules(rootName: string): string {
+function streamingRules(rootName: string, flags: { supportsExpressions: boolean }): string {
+ const steps = [`1. \`root = ${rootName}(...)\` — UI shell appears immediately`];
+ if (flags.supportsExpressions) {
+ steps.push("2. $variable declarations — state ready for bindings");
+ steps.push("3. Query statements — defaults resolve immediately so components render with data");
+ steps.push("4. Component definitions — fill in with data already available");
+ steps.push("5. Data values — leaf content last");
+ } else {
+ steps.push("2. Component definitions — fill in as they stream");
+ steps.push("3. Data values — leaf content last");
+ }
+
return `## Hoisting & Streaming (CRITICAL)
openui-lang supports hoisting: a reference can be used BEFORE it is defined. The parser resolves all references after the full input is parsed.
@@ -338,11 +349,7 @@ openui-lang supports hoisting: a reference can be used BEFORE it is defined. The
During streaming, the output is re-parsed on every chunk. Undefined references are temporarily unresolved and appear once their definitions stream in. This creates a progressive top-down reveal — structure first, then data fills in.
**Recommended statement order for optimal streaming:**
-1. \`root = ${rootName}(...)\` — UI shell appears immediately
-2. $variable declarations — state ready for bindings
-3. Query statements — defaults resolve immediately so components render with data
-4. Component definitions — fill in with data already available
-5. Data values — leaf content last
+${steps.join("\n")}
Always write the root = ${rootName}(...) statement first so the UI shell appears immediately, even before child data has streamed in.`;
}
@@ -513,25 +520,35 @@ function renderToolsSection(tools: (string | ToolSpec)[]): string {
// ─── Component signatures ───────────────────────────────────────────────────
-function generateComponentSignatures(spec: PromptSpec): string {
- const toolCalls = spec.toolCalls ?? !!spec.tools?.length;
- const bindings = spec.bindings ?? toolCalls;
- const allSteps = [
- toolCalls ? "@Run" : "",
- "@ToAssistant",
- "@OpenUrl",
- bindings ? "@Set" : "",
- bindings ? "@Reset" : "",
- ].filter(Boolean);
- const actionHint = `Props typed \`ActionExpression\` accept an Action([@steps...]) expression. See the Action section for available steps (${allSteps.join(", ")}).`;
-
+function generateComponentSignatures(
+ spec: PromptSpec,
+ flags: { toolCalls: boolean; bindings: boolean; usesActionExpression: boolean },
+): string {
const lines = [
"## Component Signatures",
"",
"Arguments marked with ? are optional. Sub-components can be inline or referenced; prefer references for better streaming.",
- actionHint,
- "Props marked `$binding<type>` accept a `$variable` reference for two-way binding.",
];
+ if (flags.usesActionExpression) {
+ const allSteps = [
+ flags.toolCalls ? "@Run" : "",
+ "@ToAssistant",
+ "@OpenUrl",
+ flags.bindings ? "@Set" : "",
+ flags.bindings ? "@Reset" : "",
+ ].filter(Boolean);
+ lines.push(
+ `Props typed \`ActionExpression\` accept an Action([@steps...]) expression. See the Action section for available steps (${allSteps.join(", ")}).`,
+ );
+ }
+ const usesBindings =
+ flags.bindings || Object.values(spec.components).some((c) => c.signature?.includes("$binding"));
+ if (usesBindings) {
+ lines.push("Props marked `$binding<type>` accept a `$variable` reference for two-way binding.");
+ }
+
+ const formatSig = (comp: { signature: string; description?: string }) =>
+ comp.description ? `${comp.signature} — ${comp.description}` : comp.signature;
if (spec.componentGroups?.length) {
const grouped = new Set<string>();
@@ -542,7 +559,7 @@ function generateComponentSignatures(spec: PromptSpec): string {
const comp = spec.components[name];
if (!comp) continue;
grouped.add(name);
- lines.push(comp.description ? `${comp.signature} — ${comp.description}` : comp.signature);
+ lines.push(formatSig(comp));
}
if (group.notes?.length) {
for (const note of group.notes) lines.push(note);
@@ -553,13 +570,13 @@ function generateComponentSignatures(spec: PromptSpec): string {
lines.push("", "### Other");
for (const name of ungrouped) {
const comp = spec.components[name];
- lines.push(comp.description ? `${comp.signature} — ${comp.description}` : comp.signature);
+ lines.push(formatSig(comp));
}
}
} else {
lines.push("");
for (const [, comp] of Object.entries(spec.components)) {
- lines.push(comp.description ? `${comp.signature} — ${comp.description}` : comp.signature);
+ lines.push(formatSig(comp));
}
}
return lines.join("\n");
@@ -576,17 +593,24 @@ export function generatePrompt(spec: PromptSpec): string {
const bindings = spec.bindings ?? toolCalls;
const supportsExpressions = toolCalls || bindings;
+ // Detect component-level feature usage
+ const usesActionExpression = Object.values(spec.components).some((c) =>
+ c.signature?.includes("ActionExpression"),
+ );
+
const parts: string[] = [];
parts.push(spec.preamble ?? PREAMBLE);
parts.push("");
parts.push(syntaxRules(rootName, { supportsExpressions, bindings }));
parts.push("");
- parts.push(generateComponentSignatures(spec));
+ parts.push(generateComponentSignatures(spec, { toolCalls, bindings, usesActionExpression }));
- // Built-in functions — always included
- parts.push("");
- parts.push(builtinFunctionsSection());
+ // Built-in functions — only when expressions are enabled (Query/reactive state)
+ if (supportsExpressions) {
+ parts.push("");
+ parts.push(builtinFunctionsSection());
+ }
// Query + Mutation sections
if (toolCalls) {
@@ -596,9 +620,11 @@ export function generatePrompt(spec: PromptSpec): string {
parts.push(mutationSection());
}
- // Action section — always included (ToAssistant, OpenUrl always; @Run/@Set/@Reset gated)
- parts.push("");
- parts.push(actionSection({ toolCalls, bindings }));
+ // Action section — only when components use ActionExpression (v0.5 action syntax)
+ if (usesActionExpression) {
+ parts.push("");
+ parts.push(actionSection({ toolCalls, bindings }));
+ }
// Interactive filters (needs both toolCalls and bindings)
if (toolCalls && bindings) {
@@ -619,7 +645,7 @@ export function generatePrompt(spec: PromptSpec): string {
}
parts.push("");
- parts.push(streamingRules(rootName));
+ parts.push(streamingRules(rootName, { supportsExpressions }));
// Append both examples and toolExamples when both are present
const allExamples = [...(spec.examples ?? []), ...(spec.toolExamples ?? [])];
diff --git a/packages/react-lang/src/context.ts b/packages/react-lang/src/context.ts
index 7aeddfd2c..f2dcf6cf6 100644
--- a/packages/react-lang/src/context.ts
+++ b/packages/react-lang/src/context.ts
@@ -15,7 +15,7 @@ export interface OpenUIContextValue {
/**
* Trigger an action. Accepts either:
* - ActionPlan (v0.5): runs steps sequentially (Run, Set, ToAssistant, OpenUrl)
- * - Legacy action config (v0.4): { type?: string, params?: Record<string, any> }
+ * - Legacy action config (v0.1): { type?: string, params?: Record<string, any> }
* - Nothing: fires ContinueConversation with the label
*/
triggerAction: (
diff --git a/packages/react-lang/src/hooks/useOpenUIState.ts b/packages/react-lang/src/hooks/useOpenUIState.ts
index cfff2de8c..d81694386 100644
--- a/packages/react-lang/src/hooks/useOpenUIState.ts
+++ b/packages/react-lang/src/hooks/useOpenUIState.ts
@@ -283,11 +283,11 @@ export function useOpenUIState(
const formPayload = getFormPayload(formName);
const { onAction: handler } = propsRef.current;
- // Legacy action config path (v0.4 compat) — { type?, params? }
+ // Legacy action config path (v0.1 compat) — { type?, params? }
if (action && !("steps" in action)) {
const actionType = action.type || BuiltinActionType.ContinueConversation;
const params = { ...(action.params || {}) };
- // v0.4 compat — url and context were top-level, not in params
+ // v0.1 compat — url and context were top-level, not in params
if ((action as any).url) params.url = (action as any).url;
if ((action as any).context) params.context = (action as any).context;
handler?.({
diff --git a/packages/react-ui/src/genui-lib/Button/index.tsx b/packages/react-ui/src/genui-lib/Button/index.tsx
index 6f2023a63..3a146c697 100644
--- a/packages/react-ui/src/genui-lib/Button/index.tsx
+++ b/packages/react-ui/src/genui-lib/Button/index.tsx
@@ -40,17 +40,21 @@ export const Button = defineComponent({
disabled={isStreaming}
onClick={() => {
const action = props.action as ActionPlan | undefined;
+ const variant = (props.variant as string) || "primary";
- // Validate form for primary buttons with mutation/ToAssistant steps
- if (action?.steps && formValidation) {
- const variant = (props.variant as string) || "primary";
- if (variant === "primary") {
+ // Validate form for primary buttons before firing action
+ if (formValidation && variant === "primary") {
+ if (action?.steps) {
+ // v0.5 ActionPlan — validate if any step is ToAssistant or mutation
const needsValidation = action.steps.some(
(s) =>
s.type === ACTION_STEPS.ToAssistant ||
(s.type === ACTION_STEPS.Run && s.refType === "mutation"),
);
if (needsValidation && !formValidation.validateForm()) return;
+ } else {
+ // v0.1 legacy or no action — always validate for primary buttons
+ if (!formValidation.validateForm()) return;
}
}