@adecore/intelligent-ui 0.21.0 → 0.21.1

package/src/runtime.ts

@@ -1,7 +1,9 @@
-import { copyUiValue, evaluateUiExpression, type UiExpression, type UiValue } from './expression.ts';
+import { copyUiValue, evaluateUiExpression, sameUiValue, type UiExpression, type UiValue } from './expression.ts';
 import { UiBudget, UiFailure, type UiLimits } from './budget.ts';
 import { isUiComponent, UI_CATALOG, UI_CATALOG_VERSION } from './catalog.ts';
 import { type UiBlock, type UiNode } from './compiler.ts';
+import { uiActionProp, uiActionTarget, uiLocalState } from './actions.ts';
+import { uiCompiledNodes, uiVisibleInputs } from './inputs.ts';
 import { uiDiagnostic, type UiDiagnostic } from './syntax.ts';
 
 export interface UiBinding<Value> {
@@ -19,6 +21,8 @@ export interface UiViewNode<Props = Record<string, unknown>> {
     complete: boolean;
     fallback: string;
     error?: string;
+    // Runs the node's state action; present only on a component that has one.
+    onAction?(): void;
 }
 
 export interface UiEvaluation {
@@ -34,19 +38,21 @@ export class UiState {
     private querySignatures: Record<string, string> = Object.create(null);
     private readonly listeners = new Set<() => void>();
     private revision = 0;
+    private readonly limits: Partial<UiLimits>;
 
-    constructor(block: UiBlock) {
+    constructor(block: UiBlock, limits: Partial<UiLimits> = {}) {
+        this.limits = limits;
         this.sync(block);
     }
 
     sync(block: UiBlock): void {
-        const defaults = copyUiValue(block.defaults) as Record<string, UiValue>;
+        const defaults = copyUiValue(block.defaults, new UiBudget(this.limits)) as Record<string, UiValue>;
         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;
             }
         }
@@ -78,14 +84,14 @@ export class UiState {
     }
 
     scope(): Readonly<Record<string, UiValue>> {
-        return copyUiValue({ ...this.values, ...this.queries }) as Record<string, UiValue>;
+        return copyUiValue({ ...this.values, ...this.queries }, new UiBudget(this.limits)) as Record<string, UiValue>;
     }
 
     set(name: string, value: unknown): void {
         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.');
@@ -98,29 +104,19 @@ 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: UiExpression): void {
-        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) as Record<string, UiValue>;
+        const target = uiActionTarget(action, (name) => Object.hasOwn(this.defaults, name));
+        if (target === null) {
+            this.values = copyUiValue(this.defaults, new UiBudget(this.limits)) as Record<string, UiValue>;
             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]);
         }
     }
 
@@ -165,8 +161,11 @@ export function evaluateUiBlock(block: UiBlock, state = new UiState(block), limi
                 throw new UiFailure(node.error ?? 'unknown_catalog', 'This part uses an unsupported UI definition.');
             }
             const props: Record<string, UiValue> = copyUiValue(node.props, budget) as Record<string, UiValue>;
+            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) {
@@ -205,7 +204,7 @@ export function evaluateUiBlock(block: UiBlock, state = new UiState(block), limi
             }
             const bindings: Record<string, UiBinding<unknown>> = 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] = {
@@ -222,6 +221,23 @@ export function evaluateUiBlock(block: UiBlock, state = new UiState(block), limi
                 };
             }
             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];
         } catch (error) {
@@ -252,15 +268,28 @@ export interface UiChoiceSelection {
 export function uiInputValues(block: UiBlock, state: UiState): Record<string, UiValue> {
     const scope = state.scope();
     const values: Record<string, UiValue> = Object.create(null);
+    const local = uiLocalState(block);
+    const actionTarget = (action: UiExpression): string | null => {
+        try {
+            return uiActionTarget(action, local);
+        } catch {
+            return null;
+        }
+    };
     const visit = (nodes: readonly UiNode[]) => {
         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);
         }
@@ -269,18 +298,19 @@ export function uiInputValues(block: UiBlock, state: UiState): Record<string, Ui
     return values;
 }
 
-/* The host supplies its stored block; client data can change only declared input bindings. */
+/* The host supplies its stored block; client data can change only declared inputs and Button targets. */
 export function resolveUiChoice(
     block: UiBlock,
     choiceId: string,
     input: Readonly<Record<string, unknown>> = {},
-    queries: Readonly<Record<string, unknown>> = {}
+    queries: Readonly<Record<string, unknown>> = {},
+    limits: Partial<UiLimits> = {}
 ): UiChoiceSelection {
     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()) as Record<string, UiValue>;
-    const state = new UiState(block);
+    const values = copyUiValue(input, new UiBudget(limits)) as Record<string, UiValue>;
+    const state = new UiState(block, limits);
     for (const [name, value] of Object.entries(queries)) {
         state.setQuery(name, value, block);
     }
@@ -290,25 +320,17 @@ export function resolveUiChoice(
         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<string>();
     let choice: UiViewNode | undefined;
-    const written = new Map<string, UiNode>();
-    const remember = (nodes: readonly UiNode[]) => {
-        for (const node of nodes) {
-            written.set(node.id, node);
-            remember(node.children);
-        }
-    };
-    remember(block.nodes);
+    const written = uiCompiledNodes(block.nodes);
     const visit = (nodes: readonly UiViewNode[], parent?: string) => {
         for (const node of nodes) {
             const source = written.get(node.sourceId ?? node.id);
@@ -318,18 +340,6 @@ export function resolveUiChoice(
             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 as unknown[]).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;
             }
@@ -337,6 +347,7 @@ export function resolveUiChoice(
         }
     };
     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/src/text.ts

@@ -1,47 +1,54 @@
 import { UI_CATALOG, UI_GROUPS } from './catalog.ts';
+import { uiPropList } from './prop-list.ts';
 import { UI_FENCE_LANGUAGE, type UiBlock } from './compiler.ts';
 
 export function uiCompactCatalog(): string {
     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 interface UiTextOptions {
+    // The info string the host's compiler looks for; `UI_FENCE_LANGUAGE` without one.
+    fenceLanguage?: string;
+}
+
+function uiSyntax(language: string): string {
+    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.`;
+}
+
+function uiExample(language: string): string {
+    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(): string {
-    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`;
+export function uiSessionNote({ fenceLanguage = UI_FENCE_LANGUAGE }: UiTextOptions = {}): string {
+    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(): string {
+export function uiReferenceText({ fenceLanguage = UI_FENCE_LANGUAGE }: UiTextOptions = {}): string {
     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: string, blocks: readonly UiBlock[]): string {