@adecore/intelligent-ui 0.21.0 → 0.21.1

package/dist/links.js

@@ -7,6 +7,7 @@ export const UiLinkTargetSchema = z.discriminatedUnion('type', [
     z.object({ type: z.literal('Commit'), sha: z.string().regex(/^[a-f\d]{7,64}$/i) }).strict(),
     z.object({ type: z.literal('Node'), id: z.string().min(1).max(256) }).strict()
 ]);
+// `state` is a frozen set: native clients validate these payloads whole, so a new state would fail them.
 export const UiLinkResolutionSchema = z.object({
     state: z.enum(['chip', 'plain']),
     target: UiLinkTargetSchema.optional(),
@@ -17,10 +18,12 @@ export const UiLinkResolutionSchema = z.object({
     conflicted: z.boolean().optional(),
     relativePath: z.string().optional(),
     label: z.string().optional(),
+    // A code that names the reason across versions; open, so a new one fails nobody.
+    code: z.string().optional(),
     reason: z.string().optional()
 });
-export function uiLinkTargets(block, input = {}, queries = {}) {
-    const state = uiValidatedState(block, input, queries);
+export function uiLinkTargets(block, input = {}, queries = {}, limits = {}) {
+    const state = uiValidatedState(block, input, queries, limits);
     const targets = Object.create(null);
     const visit = (nodes) => {
         for (const node of nodes) {
@@ -34,6 +37,6 @@ export function uiLinkTargets(block, input = {}, queries = {}) {
             visit(node.children);
         }
     };
-    visit(evaluateUiBlock(block, state).nodes);
+    visit(evaluateUiBlock(block, state, limits).nodes);
     return targets;
 }

package/dist/prop-list.d.ts

@@ -0,0 +1,7 @@
+import type { z } from 'zod';
+export declare function uiPropList(entry: {
+    readonly schema: {
+        readonly shape: Readonly<Record<string, z.ZodType>>;
+    };
+    readonly action?: string;
+}): string[];

package/dist/prop-list.js

@@ -0,0 +1,5 @@
+/* The props a catalog entry accepts, its action first and an optional one marked with `?`. */
+export function uiPropList(entry) {
+    const props = Object.entries(entry.schema.shape).map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`);
+    return entry.action ? [entry.action, ...props] : props;
+}

package/dist/query.d.ts

@@ -1,6 +1,7 @@
+import { type UiLimits } from './budget.ts';
 import type { UiBlock } from './compiler.ts';
 import { type UiValue } from './expression.ts';
 import { UiState } from './runtime.ts';
-export declare function uiValidatedState(block: UiBlock, input?: Readonly<Record<string, unknown>>, queries?: Readonly<Record<string, unknown>>): UiState;
-export declare function uiQueryArguments(block: UiBlock, name: string, input?: Readonly<Record<string, unknown>>): Record<string, UiValue>;
+export declare function uiValidatedState(block: UiBlock, input?: Readonly<Record<string, unknown>>, queries?: Readonly<Record<string, unknown>>, limits?: Partial<UiLimits>): UiState;
+export declare function uiQueryArguments(block: UiBlock, name: string, input?: Readonly<Record<string, unknown>>, limits?: Partial<UiLimits>): Record<string, UiValue>;
 export declare function uiQueryFallback(block: UiBlock, queries: Readonly<Record<string, unknown>>): string;

package/dist/query.js

@@ -1,25 +1,15 @@
 import { UI_CATALOG_VERSION } from './catalog.js';
 import { UiBudget, UiFailure } from './budget.js';
-import { copyUiValue, evaluateUiExpression } from './expression.js';
+import { uiVisibleInputs } from './inputs.js';
+import { uiNodeFallback } from './fallback.js';
+import { copyUiValue, evaluateUiExpression, sameUiValue } from './expression.js';
 import { evaluateUiBlock, uiInputValues, UiState } from './runtime.js';
-function findBinding(nodes, id, prop) {
-    for (const node of nodes) {
-        if (node.id === id) {
-            return node.bindings[prop];
-        }
-        const found = findBinding(node.children, id, prop);
-        if (found) {
-            return found;
-        }
-    }
-    return undefined;
-}
-export function uiValidatedState(block, input = {}, queries = {}) {
+export function uiValidatedState(block, input = {}, queries = {}, limits = {}) {
     if (!block.complete || block.catalogVersion !== UI_CATALOG_VERSION) {
         throw new UiFailure('invalid_block', 'Only completed supported blocks can resolve input.');
     }
-    const values = copyUiValue(input, new UiBudget());
-    const state = new UiState(block);
+    const values = copyUiValue(input, new UiBudget(limits));
+    const state = new UiState(block, limits);
     for (const [name, value] of Object.entries(queries)) {
         state.setQuery(name, value, block);
     }
@@ -30,86 +20,33 @@ export function uiValidatedState(block, input = {}, queries = {}) {
         }
         state.set(key, value);
     }
-    const visible = new Set();
-    const visit = (nodes) => {
-        for (const node of nodes) {
-            if (node.error || !node.complete) {
-                continue;
-            }
-            let valid = true;
-            if (node.type === 'Segmented') {
-                valid = node.children.some((option) => option.type === 'Option' && !option.error && option.props.value === node.props.value);
-            }
-            if (node.type === 'Checklist') {
-                const options = node.children.filter((item) => item.type === 'Item' && !item.error).map((item) => item.props.value);
-                valid = node.props.value.every((value) => options.includes(value));
-            }
-            if (valid) {
-                for (const [key, binding] of Object.entries(node.bindings)) {
-                    const original = findBinding(block.nodes, node.sourceId ?? node.id, key);
-                    if (original && binding) {
-                        visible.add(original);
-                    }
-                }
-            }
-            visit(node.children);
-        }
-    };
-    const evaluated = evaluateUiBlock(block, state);
+    const evaluated = evaluateUiBlock(block, state, limits);
     if (evaluated.diagnostics.some((diagnostic) => diagnostic.code === 'budget_exceeded')) {
         throw new UiFailure('budget_exceeded', 'The query inputs exceeded their evaluation budget.');
     }
-    visit(evaluated.nodes);
+    const visible = uiVisibleInputs(block, evaluated.nodes, state.scope());
     for (const [key, value] of Object.entries(values)) {
-        if (JSON.stringify(value) !== JSON.stringify(allowed[key]) && !visible.has(key)) {
+        if (!sameUiValue(value, allowed[key]) && !visible.has(key)) {
             throw new UiFailure('invalid_value', 'An input value is outside the visible control’s allowed values.');
         }
     }
     return state;
 }
-export function uiQueryArguments(block, name, input = {}) {
+export function uiQueryArguments(block, name, input = {}, limits = {}) {
     if (!Object.hasOwn(block.queries, name)) {
         throw new UiFailure('invalid_query', 'This block does not declare that query.');
     }
-    const state = uiValidatedState(block, input);
+    const state = uiValidatedState(block, input, {}, limits);
     const query = block.queries[name];
     return query.expression
-        ? evaluateUiExpression(query.expression, state.scope(), new UiBudget())
-        : copyUiValue(query.args, new UiBudget());
+        ? evaluateUiExpression(query.expression, state.scope(), new UiBudget(limits))
+        : copyUiValue(query.args, new UiBudget(limits));
 }
 export function uiQueryFallback(block, queries) {
     const state = new UiState(block);
     for (const [name, value] of Object.entries(queries)) {
         state.setQuery(name, value, block);
     }
-    const plain = (value) => (value == null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value));
-    const text = (nodes) => nodes
-        .map((node) => {
-        if (node.error) {
-            return node.fallback;
-        }
-        if (node.type === '$text') {
-            return plain(node.props.text);
-        }
-        const props = node.props;
-        const children = text(node.children);
-        if (node.type === 'Stat') {
-            return `${plain(props.label)}: ${plain(props.value)}${props.unit ? ` ${plain(props.unit)}` : ''}\n`;
-        }
-        if (node.type === 'Table') {
-            return `${plain(props.rows)}\n`;
-        }
-        if (node.type === 'Chart') {
-            return `${plain(props.data)}\n`;
-        }
-        if (node.type === 'Source') {
-            return `${plain(props.label)}: ${plain(props.url)}\n`;
-        }
-        if (node.type === 'Image') {
-            return node.fallback;
-        }
-        return `${(props.label ?? props.title) ? `${plain(props.label ?? props.title)}: ` : ''}${plain(props.path ?? props.sha ?? (node.type === 'Node' ? props.id : null))}${children}${props.context ? `\n${plain(props.context)}` : ''}${node.type === 'Tag' ? '' : '\n'}`;
-    })
-        .join('');
+    const text = (nodes) => nodes.map((node) => (node.error ? node.fallback : uiNodeFallback(node.type, node.props, text(node.children)))).join('');
     return text(evaluateUiBlock(block, state).nodes).trim() || block.fallback;
 }

package/dist/runtime.d.ts

@@ -16,6 +16,7 @@ export interface UiViewNode<Props = Record<string, unknown>> {
     complete: boolean;
     fallback: string;
     error?: string;
+    onAction?(): void;
 }
 export interface UiEvaluation {
     nodes: UiViewNode[];
@@ -29,7 +30,8 @@ export declare class UiState {
     private querySignatures;
     private readonly listeners;
     private revision;
-    constructor(block: UiBlock);
+    private readonly limits;
+    constructor(block: UiBlock, limits?: Partial<UiLimits>);
     sync(block: UiBlock): void;
     snapshot(): number;
     subscribe(listener: () => void): () => void;
@@ -46,4 +48,4 @@ export interface UiChoiceSelection {
     values: Record<string, UiValue>;
 }
 export declare function uiInputValues(block: UiBlock, state: UiState): Record<string, UiValue>;
-export declare function resolveUiChoice(block: UiBlock, choiceId: string, input?: Readonly<Record<string, unknown>>, queries?: Readonly<Record<string, unknown>>): UiChoiceSelection;
+export declare function resolveUiChoice(block: UiBlock, choiceId: string, input?: Readonly<Record<string, unknown>>, queries?: Readonly<Record<string, unknown>>, limits?: Partial<UiLimits>): UiChoiceSelection;

package/dist/runtime.js

@@ -1,7 +1,9 @@
-import { copyUiValue, evaluateUiExpression } from './expression.js';
+import { copyUiValue, evaluateUiExpression, sameUiValue } from './expression.js';
 import { UiBudget, UiFailure } from './budget.js';
 import { isUiComponent, UI_CATALOG, UI_CATALOG_VERSION } from './catalog.js';
 import {} from './compiler.js';
+import { uiActionProp, uiActionTarget, uiLocalState } from './actions.js';
+import { uiCompiledNodes, uiVisibleInputs } from './inputs.js';
 import { uiDiagnostic } from './syntax.js';
 export class UiState {
     id = '';
@@ -11,17 +13,19 @@ export class UiState {
     querySignatures = Object.create(null);
     listeners = new Set();
     revision = 0;
-    constructor(block) {
+    limits;
+    constructor(block, limits = {}) {
+        this.limits = limits;
         this.sync(block);
     }
     sync(block) {
-        const defaults = copyUiValue(block.defaults);
+        const defaults = copyUiValue(block.defaults, new UiBudget(this.limits));
         if (this.id !== block.id) {
             this.values = Object.create(null);
             this.queries = Object.create(null);
         }
         for (const [name, value] of Object.entries(defaults)) {
-            if (this.id !== block.id || !Object.hasOwn(this.defaults, name) || JSON.stringify(this.defaults[name]) !== JSON.stringify(value)) {
+            if (this.id !== block.id || !Object.hasOwn(this.defaults, name) || !sameUiValue(this.defaults[name], value)) {
                 this.values[name] = value;
             }
         }
@@ -50,13 +54,13 @@ export class UiState {
         return () => this.listeners.delete(listener);
     }
     scope() {
-        return copyUiValue({ ...this.values, ...this.queries });
+        return copyUiValue({ ...this.values, ...this.queries }, new UiBudget(this.limits));
     }
     set(name, value) {
         if (!Object.hasOwn(this.defaults, name)) {
             throw new UiFailure('refused_binding', 'Only declared local state can be changed.');
         }
-        const next = copyUiValue(value);
+        const next = copyUiValue(value, new UiBudget(this.limits));
         const initial = this.defaults[name];
         if (Array.isArray(next) !== Array.isArray(initial) || typeof next !== typeof initial || (next === null) !== (initial === null)) {
             throw new UiFailure('invalid_value', 'The state type cannot change.');
@@ -68,30 +72,20 @@ export class UiState {
         if (block.id !== this.id || !Object.hasOwn(block.queries, name) || this.querySignatures[name] !== JSON.stringify(block.queries[name])) {
             throw new UiFailure('refused_query', 'The query must belong to this block.');
         }
-        this.queries[name] = copyUiValue(value);
+        this.queries[name] = copyUiValue(value, new UiBudget(this.limits));
         this.changed();
     }
     run(action) {
-        if (action.kind !== 'call' || !['Set', 'Reset'].includes(action.name)) {
-            throw new UiFailure('refused_action', 'Expected @Set or @Reset.');
-        }
-        if (action.name === 'Reset' && action.args.length === 0) {
-            this.values = copyUiValue(this.defaults);
+        const target = uiActionTarget(action, (name) => Object.hasOwn(this.defaults, name));
+        if (target === null) {
+            this.values = copyUiValue(this.defaults, new UiBudget(this.limits));
             this.changed();
-            return;
-        }
-        const reference = action.args[0];
-        if (!reference || reference.kind !== 'reference' || !Object.hasOwn(this.defaults, reference.name)) {
-            throw new UiFailure('refused_binding', 'The action needs a local state variable.');
-        }
-        if (action.name === 'Set' && action.args.length === 2) {
-            this.set(reference.name, evaluateUiExpression(action.args[1], this.scope()));
         }
-        else if (action.name === 'Reset' && action.args.length === 1) {
-            this.set(reference.name, this.defaults[reference.name]);
+        else if (action.kind === 'call' && action.name === 'Set') {
+            this.set(target, evaluateUiExpression(action.args[1], this.scope(), new UiBudget(this.limits)));
         }
         else {
-            throw new UiFailure('refused_action', 'Invalid state action arguments.');
+            this.set(target, this.defaults[target]);
         }
     }
     changed() {
@@ -134,8 +128,11 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
                 throw new UiFailure(node.error ?? 'unknown_catalog', 'This part uses an unsupported UI definition.');
             }
             const props = copyUiValue(node.props, budget);
+            const actionProp = uiActionProp(node.type);
             for (const [key, expression] of Object.entries(node.expressions)) {
-                props[key] = evaluateUiExpression(expression, variables, budget);
+                if (key !== actionProp) {
+                    props[key] = evaluateUiExpression(expression, variables, budget);
+                }
             }
             if (node.type === '$text') {
                 if (typeof props.text !== 'string' && typeof props.text !== 'number' && typeof props.text !== 'boolean' && props.text !== null) {
@@ -174,7 +171,7 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
             }
             const bindings = Object.create(null);
             for (const [key, name] of Object.entries(node.bindings)) {
-                if (!('binding' in entry) || entry.binding !== key || !Object.hasOwn(block.defaults, name) || Object.hasOwn(block.queries, name)) {
+                if (!('binding' in entry) || entry.binding !== key || !uiLocalState(block)(name)) {
                     throw new UiFailure('refused_binding', 'The binding must target declared local input state.');
                 }
                 bindings[key] = {
@@ -191,6 +188,24 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
                 };
             }
             view.bindings = bindings;
+            const action = actionProp === undefined ? undefined : node.expressions[actionProp];
+            if (action) {
+                uiActionTarget(action, uiLocalState(block));
+                view.onAction = () => {
+                    if (!node.complete || props.disabled === true) {
+                        return;
+                    }
+                    try {
+                        state.run(action);
+                    }
+                    catch (error) {
+                        // An action that cannot apply to the current state leaves it as it was.
+                        if (!(error instanceof UiFailure)) {
+                            throw error;
+                        }
+                    }
+                };
+            }
             view.children = children(node.children, variables, depth + 1, suffix);
             return [view];
         }
@@ -216,15 +231,29 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
 export function uiInputValues(block, state) {
     const scope = state.scope();
     const values = Object.create(null);
+    const local = uiLocalState(block);
+    const actionTarget = (action) => {
+        try {
+            return uiActionTarget(action, local);
+        }
+        catch {
+            return null;
+        }
+    };
     const visit = (nodes) => {
         for (const node of nodes) {
             if (isUiComponent(node.type) && !node.error && node.complete) {
                 const entry = UI_CATALOG[node.type];
                 for (const [prop, name] of Object.entries(node.bindings)) {
-                    if ('binding' in entry && entry.binding === prop && Object.hasOwn(block.defaults, name) && !Object.hasOwn(block.queries, name)) {
+                    if ('binding' in entry && entry.binding === prop && local(name)) {
                         values[name] = scope[name];
                     }
                 }
+                const actionProp = uiActionProp(node.type);
+                const target = actionProp && node.expressions[actionProp] ? actionTarget(node.expressions[actionProp]) : null;
+                if (target !== null) {
+                    values[target] = scope[target];
+                }
             }
             visit(node.children);
         }
@@ -232,13 +261,13 @@ export function uiInputValues(block, state) {
     visit(block.nodes);
     return values;
 }
-/* The host supplies its stored block; client data can change only declared input bindings. */
-export function resolveUiChoice(block, choiceId, input = {}, queries = {}) {
+/* The host supplies its stored block; client data can change only declared inputs and Button targets. */
+export function resolveUiChoice(block, choiceId, input = {}, queries = {}, limits = {}) {
     if (!block.complete || block.catalogVersion !== UI_CATALOG_VERSION) {
         throw new UiFailure('refused_choice', 'Only a completed supported block can send a choice.');
     }
-    const values = copyUiValue(input, new UiBudget());
-    const state = new UiState(block);
+    const values = copyUiValue(input, new UiBudget(limits));
+    const state = new UiState(block, limits);
     for (const [name, value] of Object.entries(queries)) {
         state.setQuery(name, value, block);
     }
@@ -248,25 +277,17 @@ export function resolveUiChoice(block, choiceId, input = {}, queries = {}) {
         if (!Object.hasOwn(allowed, name)) {
             throw new UiFailure('refused_binding', 'Only declared input bindings can be submitted.');
         }
-        if (JSON.stringify(value) !== JSON.stringify(allowed[name])) {
+        if (!sameUiValue(value, allowed[name])) {
             state.set(name, value);
             changed.add(name);
         }
     }
-    const evaluated = evaluateUiBlock(block, state);
+    const evaluated = evaluateUiBlock(block, state, limits);
     if (evaluated.diagnostics.some((diagnostic) => diagnostic.code === 'budget_exceeded')) {
         throw new UiFailure('budget_exceeded', 'The choice exceeded its evaluation budget.');
     }
-    const validInputs = new Set();
     let choice;
-    const written = new Map();
-    const remember = (nodes) => {
-        for (const node of nodes) {
-            written.set(node.id, node);
-            remember(node.children);
-        }
-    };
-    remember(block.nodes);
+    const written = uiCompiledNodes(block.nodes);
     const visit = (nodes, parent) => {
         for (const node of nodes) {
             const source = written.get(node.sourceId ?? node.id);
@@ -276,19 +297,6 @@ export function resolveUiChoice(block, choiceId, input = {}, queries = {}) {
             if (node.error || !node.complete) {
                 continue;
             }
-            let valid = true;
-            if (node.type === 'Segmented') {
-                valid = node.children.some((option) => option.type === 'Option' && !option.error && option.props.value === node.props.value);
-            }
-            else if (node.type === 'Checklist') {
-                const options = node.children.filter((item) => item.type === 'Item' && !item.error).map((item) => item.props.value);
-                valid = node.props.value.every((value) => options.includes(value));
-            }
-            if (valid && source) {
-                for (const prop of Object.keys(node.bindings)) {
-                    validInputs.add(source.bindings[prop]);
-                }
-            }
             if (node.id === choiceId && node.type === 'Choice' && parent === 'Choices' && node.props.disabled !== true) {
                 choice = node;
             }
@@ -296,6 +304,7 @@ export function resolveUiChoice(block, choiceId, input = {}, queries = {}) {
         }
     };
     visit(evaluated.nodes);
+    const validInputs = uiVisibleInputs(block, evaluated.nodes, state.scope());
     if ([...changed].some((name) => !validInputs.has(name))) {
         throw new UiFailure('invalid_value', 'An input value is outside the visible control’s allowed values.');
     }

package/dist/text.d.ts

@@ -1,5 +1,8 @@
 import { type UiBlock } from './compiler.ts';
 export declare function uiCompactCatalog(): string;
-export declare function uiSessionNote(): string;
-export declare function uiReferenceText(): string;
+export interface UiTextOptions {
+    fenceLanguage?: string;
+}
+export declare function uiSessionNote({ fenceLanguage }?: UiTextOptions): string;
+export declare function uiReferenceText({ fenceLanguage }?: UiTextOptions): string;
 export declare function uiFallbackText(text: string, blocks: readonly UiBlock[]): string;

package/dist/text.js

@@ -1,43 +1,44 @@
 import { UI_CATALOG, UI_GROUPS } from './catalog.js';
+import { uiPropList } from './prop-list.js';
 import { UI_FENCE_LANGUAGE } from './compiler.js';
 export function uiCompactCatalog() {
     return Object.entries(UI_CATALOG)
         .map(([name, entry]) => {
-        const props = Object.entries(entry.schema.shape)
-            .map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`)
-            .join(',');
+        const props = uiPropList(entry).join(',');
         return `${name}${props ? `: ${props}` : ''}`;
     })
         .join(' · ');
 }
-const UI_SYNTAX = `Write XML-like component tags inside a fenced ${UI_FENCE_LANGUAGE} block. Put text between opening and closing tags; empty components end with />. Quote string props; put numbers, booleans and expressions in braces.`;
-const UI_EXAMPLE = [
-    '```' + UI_FENCE_LANGUAGE,
-    '$enabled = false',
-    '<Summary badge="Draft">Release overview</Summary>',
-    '<Stats><Stat label="Tests" value={42}/></Stats>',
-    '<Switch value={$enabled}>Notify me</Switch>',
-    '<Choices><Choice context="Review the release overview">Continue</Choice></Choices>',
-    '```'
-].join('\n');
-export function uiSessionNote() {
-    return `${UI_SYNTAX} Prose outside. Only named catalog props, no styling. $name = literal JSON; input value={$name}; braced expressions: @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show/Each control children. Choice labels and precise context stay visible and send once. Image: attachment or generated="latest", never URL/path. No code execution. State resets on reload. Catalog (? means optional props): ${uiCompactCatalog()}\nExample:\n${UI_EXAMPLE}\n`;
+function uiSyntax(language) {
+    return `Write XML-like component tags inside a fenced ${language} block. Put text between opening and closing tags; empty components end with />. Quote string props; put numbers, booleans and expressions in braces.`;
 }
-export function uiReferenceText() {
+function uiExample(language) {
+    return [
+        '```' + language,
+        '$enabled = false',
+        '<Summary badge="Draft">Release overview</Summary>',
+        '<Stats><Stat label="Tests" value={42}/></Stats>',
+        '<Switch value={$enabled}>Notify me</Switch>',
+        '<Choices><Choice context="Review the release overview">Continue</Choice></Choices>',
+        '```'
+    ].join('\n');
+}
+export function uiSessionNote({ fenceLanguage = UI_FENCE_LANGUAGE } = {}) {
+    return `${uiSyntax(fenceLanguage)} Prose outside. Only named catalog props, no styling. $name = literal JSON; input value={$name}; Button action={@Set($name, literal)}, {@Reset($name)} or {@Reset()} changes local state only; braced expressions: @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show/Each control children. Choice labels and precise context stay visible and send once. Image: attachment or generated="latest", never URL/path. No code execution. State resets on reload. Catalog (? means optional props): ${uiCompactCatalog()}\nExample:\n${uiExample(fenceLanguage)}\n`;
+}
+export function uiReferenceText({ fenceLanguage = UI_FENCE_LANGUAGE } = {}) {
     const groups = Object.entries(UI_GROUPS)
         .map(([group, definition]) => {
         const components = Object.entries(UI_CATALOG)
             .filter(([, entry]) => entry.group === group)
             .map(([name, entry]) => {
-            const props = Object.entries(entry.schema.shape)
-                .map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`)
-                .join(', ');
+            const props = uiPropList(entry).join(', ');
             return `${name}: ${entry.description}${props ? ` Props: ${props}.` : ''}`;
         });
         return [definition.description, definition.rules, ...components].join('\n');
     })
         .join('\n\n');
-    return `${UI_SYNTAX}\nExample:\n${UI_EXAMPLE}\n\n${groups}`;
+    return `${uiSyntax(fenceLanguage)}\nExample:\n${uiExample(fenceLanguage)}\n\n${groups}`;
 }
 export function uiFallbackText(text, blocks) {
     let result = '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/intelligent-ui",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "A streaming UI catalog, compiler and bounded expression interpreter without a framework or DOM.",
   "license": "FSL-1.1-MIT",
   "author": "Bas Milius",

package/src/actions.ts

@@ -0,0 +1,39 @@
+import { UiFailure } from './budget.ts';
+import { isUiComponent, UI_CATALOG } from './catalog.ts';
+import type { UiBlock } from './compiler.ts';
+import type { UiExpression } from './expression.ts';
+
+/* The prop of a component that holds a state action, kept unevaluated, instead of a value. */
+export function uiActionProp(type: string): string | undefined {
+    if (!isUiComponent(type)) {
+        return undefined;
+    }
+    const entry = UI_CATALOG[type];
+    return 'action' in entry ? entry.action : undefined;
+}
+
+/*
+ * The variable an action writes, or null for `@Reset()`, which restores them all. Throws for anything
+ * but `@Set($name, value)`, `@Reset($name)` and `@Reset()` on a variable that `local` accepts.
+ */
+export function uiActionTarget(action: UiExpression, local: (name: string) => boolean): string | null {
+    if (action.kind !== 'call' || (action.name !== 'Set' && action.name !== 'Reset')) {
+        throw new UiFailure('refused_action', 'Expected @Set or @Reset.');
+    }
+    if (action.name === 'Reset' && action.args.length === 0) {
+        return null;
+    }
+    if (action.args.length !== (action.name === 'Set' ? 2 : 1)) {
+        throw new UiFailure('refused_action', 'Invalid state action arguments.');
+    }
+    const reference = action.args[0];
+    if (reference.kind !== 'reference' || !local(reference.name)) {
+        throw new UiFailure('refused_binding', 'The action needs a local state variable.');
+    }
+    return reference.name;
+}
+
+/* Whether `name` is local state of the block: declared with a default and never a query. */
+export function uiLocalState(block: Pick<UiBlock, 'defaults' | 'queries'>): (name: string) => boolean {
+    return (name) => Object.hasOwn(block.defaults, name) && !Object.hasOwn(block.queries, name);
+}

package/src/catalog.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { uiPropList } from './prop-list.ts';
 
 export const UI_CATALOG_VERSION = 1;
 export const UiToneSchema = z.enum(['neutral', 'info', 'success', 'warning', 'danger']);
@@ -21,7 +22,10 @@ export const UI_GROUPS = {
         rules: 'Image accepts a chat attachment or generated="latest", never a URL or a local path.'
     },
     links: { description: 'Refer to a host-owned resource.', rules: 'Targets are checked by the host. No arbitrary navigation or file reads.' },
-    inputs: { description: 'Change local block state.', rules: 'Bind value={$name}. State stays local until a Choice sends visible context.' },
+    inputs: {
+        description: 'Change local block state.',
+        rules: 'Bind value={$name}. A Button sets a literal with action={@Set($name, value)} or restores a default with {@Reset($name)} or {@Reset()}. State stays local until a Choice sends visible context.'
+    },
     choices: {
         description: 'Ask the person to pick a next step.',
         rules: 'Give a short label and precise visible context. A Choice sends once after streaming ends.'
@@ -120,6 +124,12 @@ export const UI_CATALOG = {
     },
     Segmented: { group: 'inputs', description: 'Choose one local value.', schema: z.strictObject({ value: scalar }), children: ['Option'], binding: 'value' },
     Option: { group: 'inputs', description: 'One local alternative.', schema: z.strictObject({ value: scalar }), parent: 'Segmented' },
+    Button: {
+        group: 'inputs',
+        description: 'Run one local state action when pressed; children are the label.',
+        schema: z.strictObject({ disabled: z.boolean().optional() }),
+        action: 'action'
+    },
     Show: { group: 'inputs', description: 'Show children when the condition is true.', schema: z.strictObject({ when: z.boolean() }) },
     Each: {
         group: 'inputs',
@@ -144,12 +154,6 @@ export function isUiComponent(name: string): name is UiComponentName {
 
 export function uiCatalogText(): string {
     return Object.entries(UI_CATALOG)
-        .map(([name, entry]) => {
-            const shape = entry.schema.shape;
-            const props = Object.entries(shape)
-                .map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`)
-                .join(', ');
-            return `${name}(${props}): ${entry.description}`;
-        })
+        .map(([name, entry]) => `${name}(${uiPropList(entry).join(', ')}): ${entry.description}`)
         .join('\n');
 }