@adecore/intelligent-ui 0.0.0 → 0.21.1

package/src/query.ts

@@ -0,0 +1,67 @@
+import { UI_CATALOG_VERSION } from './catalog.ts';
+import { UiBudget, UiFailure, type UiLimits } from './budget.ts';
+import type { UiBlock } from './compiler.ts';
+import { uiVisibleInputs } from './inputs.ts';
+import { uiNodeFallback } from './fallback.ts';
+import { copyUiValue, evaluateUiExpression, sameUiValue, type UiValue } from './expression.ts';
+import { evaluateUiBlock, uiInputValues, UiState, type UiViewNode } from './runtime.ts';
+
+export function uiValidatedState(
+    block: UiBlock,
+    input: Readonly<Record<string, unknown>> = {},
+    queries: Readonly<Record<string, unknown>> = {},
+    limits: Partial<UiLimits> = {}
+): UiState {
+    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(limits)) as Record<string, UiValue>;
+    const state = new UiState(block, limits);
+    for (const [name, value] of Object.entries(queries)) {
+        state.setQuery(name, value, block);
+    }
+    const allowed = uiInputValues(block, state);
+    for (const [key, value] of Object.entries(values)) {
+        if (!Object.hasOwn(allowed, key)) {
+            throw new UiFailure('refused_binding', 'Only declared input bindings can be submitted.');
+        }
+        state.set(key, value);
+    }
+    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.');
+    }
+    const visible = uiVisibleInputs(block, evaluated.nodes, state.scope());
+    for (const [key, value] of Object.entries(values)) {
+        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: UiBlock,
+    name: string,
+    input: Readonly<Record<string, unknown>> = {},
+    limits: Partial<UiLimits> = {}
+): Record<string, UiValue> {
+    if (!Object.hasOwn(block.queries, name)) {
+        throw new UiFailure('invalid_query', 'This block does not declare that query.');
+    }
+    const state = uiValidatedState(block, input, {}, limits);
+    const query = block.queries[name];
+    return query.expression
+        ? (evaluateUiExpression(query.expression, state.scope(), new UiBudget(limits)) as Record<string, UiValue>)
+        : (copyUiValue(query.args, new UiBudget(limits)) as Record<string, UiValue>);
+}
+
+export function uiQueryFallback(block: UiBlock, queries: Readonly<Record<string, unknown>>): string {
+    const state = new UiState(block);
+    for (const [name, value] of Object.entries(queries)) {
+        state.setQuery(name, value, block);
+    }
+    const text = (nodes: readonly UiViewNode[]): string =>
+        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/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> {
@@ -11,6 +13,7 @@ export interface UiBinding<Value> {
 
 export interface UiViewNode<Props = Record<string, unknown>> {
     id: string;
+    sourceId?: string;
     type: string;
     props: Props;
     bindings: Readonly<Record<string, UiBinding<unknown>>>;
@@ -18,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 {
@@ -33,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;
             }
         }
@@ -77,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.');
@@ -97,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]);
         }
     }
 
@@ -149,6 +146,7 @@ export function evaluateUiBlock(block: UiBlock, state = new UiState(block), limi
     const visit = (node: UiNode, variables: Readonly<Record<string, UiValue>>, depth: number, suffix = ''): UiViewNode[] => {
         const view: UiViewNode = {
             id: `${node.id}${suffix}`,
+            sourceId: node.id,
             type: node.type,
             props: {},
             bindings: {},
@@ -163,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) {
@@ -203,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] = {
@@ -220,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) {
@@ -240,3 +258,115 @@ export function evaluateUiBlock(block: UiBlock, state = new UiState(block), limi
     }
     return result;
 }
+
+export interface UiChoiceSelection {
+    label: string;
+    context: string;
+    values: Record<string, UiValue>;
+}
+
+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 && 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);
+        }
+    };
+    visit(block.nodes);
+    return values;
+}
+
+/* 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>> = {},
+    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(limits)) as Record<string, UiValue>;
+    const state = new UiState(block, limits);
+    for (const [name, value] of Object.entries(queries)) {
+        state.setQuery(name, value, block);
+    }
+    const allowed = uiInputValues(block, state);
+    const changed = new Set<string>();
+    for (const [name, value] of Object.entries(values)) {
+        if (!Object.hasOwn(allowed, name)) {
+            throw new UiFailure('refused_binding', 'Only declared input bindings can be submitted.');
+        }
+        if (!sameUiValue(value, allowed[name])) {
+            state.set(name, value);
+            changed.add(name);
+        }
+    }
+    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.');
+    }
+    let choice: UiViewNode | undefined;
+    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);
+            if (node.error && source && Object.values(source.bindings).some((name) => changed.has(name))) {
+                throw new UiFailure('invalid_value', 'An input value does not match its control.');
+            }
+            if (node.error || !node.complete) {
+                continue;
+            }
+            if (node.id === choiceId && node.type === 'Choice' && parent === 'Choices' && node.props.disabled !== true) {
+                choice = node;
+            }
+            visit(node.children, node.type);
+        }
+    };
+    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.');
+    }
+    if (!choice) {
+        throw new UiFailure('refused_choice', 'This choice is not available in the current block.');
+    }
+    const text = (nodes: readonly UiViewNode[]): string =>
+        nodes.map((node) => (node.type === '$text' ? String(node.props.text ?? '') : text(node.children))).join('');
+    const hasError = (nodes: readonly UiViewNode[]): boolean => nodes.some((node) => node.error !== undefined || hasError(node.children));
+    if (hasError(choice.children)) {
+        throw new UiFailure('refused_choice', 'The choice label could not be fully read.');
+    }
+    const label = text(choice.children).replace(/\s+/g, ' ').trim();
+    if (!label) {
+        throw new UiFailure('refused_choice', 'A choice needs a visible label.');
+    }
+    return {
+        label,
+        values: uiInputValues(block, state),
+        context: typeof choice.props.context === 'string' && choice.props.context.trim() ? choice.props.context : label
+    };
+}

package/src/stream.ts

@@ -0,0 +1,78 @@
+import { UiCompiler, type UiBlock, type UiCompilerOptions } from './compiler.ts';
+
+export const UI_STREAM_INTERVAL_MS = 250;
+
+export interface UiStreamClock {
+    now(): number;
+    setTimeout(run: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+
+export interface UiStreamPreview {
+    textLength: number;
+    blocks: UiBlock[];
+}
+
+export interface UiStreamOptions extends UiCompilerOptions {
+    clock: UiStreamClock;
+    emit(preview: UiStreamPreview): void;
+}
+
+export class UiStream {
+    private readonly compiler: UiCompiler;
+    private readonly options: UiStreamOptions;
+    private pending: { text: string; latestAttachment?: string } | null = null;
+    private timer: { handle: unknown } | null = null;
+    private lastCompiledAt = -Infinity;
+    private closed = false;
+
+    constructor(options: UiStreamOptions) {
+        this.options = options;
+        this.compiler = new UiCompiler(options);
+    }
+
+    update(text: string, latestAttachment?: string): void {
+        if (this.closed) {
+            return;
+        }
+        this.pending = { text, latestAttachment };
+        if (this.timer !== null) {
+            return;
+        }
+        const delay = Math.max(0, UI_STREAM_INTERVAL_MS - (this.options.clock.now() - this.lastCompiledAt));
+        if (delay === 0) {
+            this.flush();
+        } else {
+            this.timer = { handle: this.options.clock.setTimeout(() => this.flush(), delay) };
+        }
+    }
+
+    finish(text: string, latestAttachment?: string): UiBlock[] {
+        this.dispose();
+        const blocks = this.compiler.compile(text, { final: true, latestAttachment });
+        this.compiler.clear();
+        return blocks;
+    }
+
+    dispose(): void {
+        this.closed = true;
+        if (this.timer !== null) {
+            this.options.clock.clearTimeout(this.timer.handle);
+            this.timer = null;
+        }
+        this.pending = null;
+        this.compiler.clear();
+    }
+
+    private flush(): void {
+        this.timer = null;
+        const pending = this.pending;
+        if (pending === null || this.closed) {
+            return;
+        }
+        this.pending = null;
+        this.lastCompiledAt = this.options.clock.now();
+        const blocks = this.compiler.compile(pending.text, { latestAttachment: pending.latestAttachment });
+        this.options.emit({ textLength: pending.text.length, blocks });
+    }
+}

package/src/text.ts

@@ -1,35 +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(',');
-            return `${name}(${props})`;
+            const props = uiPropList(entry).join(',');
+            return `${name}${props ? `: ${props}` : ''}`;
         })
         .join(' · ');
 }
 
-export function uiSessionNote(): string {
-    return `For a result, comparison or choice that benefits from an interface, put a fenced ${UI_FENCE_LANGUAGE} block in your final reply, with explanation outside it. Use catalog tags with named props; no layout, style or color props. State: $name = literal JSON on a line above the tags. Bind local inputs with value={$name}; use braced expressions and @Count, @Filter(list,row,predicate), @Sum, @Join, @Round. Show(when) and Each(items,as) control children. End decisions with Choices; each Choice has a short label and precise context shown to the person. Image takes a chat attachment or generated="latest", never a URL or path. No executable code. Local state resets on reload. ${uiCompactCatalog()}`;
+export interface UiTextOptions {
+    // The info string the host's compiler looks for; `UI_FENCE_LANGUAGE` without one.
+    fenceLanguage?: string;
 }
 
-export function uiReferenceText(): string {
-    return Object.entries(UI_GROUPS)
+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({ 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({ 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(', ');
-                    return `${name}(${props}): ${entry.description}`;
+                    const props = uiPropList(entry).join(', ');
+                    return `${name}: ${entry.description}${props ? ` Props: ${props}.` : ''}`;
                 });
             return [definition.description, definition.rules, ...components].join('\n');
         })
         .join('\n\n');
+    return `${uiSyntax(fenceLanguage)}\nExample:\n${uiExample(fenceLanguage)}\n\n${groups}`;
 }
 
 export function uiFallbackText(text: string, blocks: readonly UiBlock[]): string {