@adecore/intelligent-ui 0.0.0 → 0.21.0

package/src/query.ts

@@ -0,0 +1,121 @@
+import { UI_CATALOG_VERSION } from './catalog.ts';
+import { UiBudget, UiFailure } from './budget.ts';
+import type { UiBlock, UiNode } from './compiler.ts';
+import { copyUiValue, evaluateUiExpression, type UiValue } from './expression.ts';
+import { evaluateUiBlock, uiInputValues, UiState, type UiViewNode } from './runtime.ts';
+
+function findBinding(nodes: readonly UiNode[], id: string, prop: string): string | undefined {
+    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: UiBlock, input: Readonly<Record<string, unknown>> = {}, queries: Readonly<Record<string, unknown>> = {}): 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()) as Record<string, UiValue>;
+    const state = new UiState(block);
+    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 visible = new Set<string>();
+    const visit = (nodes: readonly UiViewNode[]) => {
+        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 as unknown[]).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);
+    if (evaluated.diagnostics.some((diagnostic) => diagnostic.code === 'budget_exceeded')) {
+        throw new UiFailure('budget_exceeded', 'The query inputs exceeded their evaluation budget.');
+    }
+    visit(evaluated.nodes);
+    for (const [key, value] of Object.entries(values)) {
+        if (JSON.stringify(value) !== JSON.stringify(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>> = {}): 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);
+    const query = block.queries[name];
+    return query.expression
+        ? (evaluateUiExpression(query.expression, state.scope(), new UiBudget()) as Record<string, UiValue>)
+        : (copyUiValue(query.args, new UiBudget()) 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 plain = (value: unknown) => (value == null ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value));
+    const text = (nodes: readonly UiViewNode[]): string =>
+        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('');
+    return text(evaluateUiBlock(block, state).nodes).trim() || block.fallback;
+}

package/src/runtime.ts

@@ -11,6 +11,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>>>;
@@ -149,6 +150,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: {},
@@ -240,3 +242,120 @@ 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 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)) {
+                        values[name] = scope[name];
+                    }
+                }
+            }
+            visit(node.children);
+        }
+    };
+    visit(block.nodes);
+    return values;
+}
+
+/* The host supplies its stored block; client data can change only declared input bindings. */
+export function resolveUiChoice(
+    block: UiBlock,
+    choiceId: string,
+    input: Readonly<Record<string, unknown>> = {},
+    queries: Readonly<Record<string, unknown>> = {}
+): 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);
+    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 (JSON.stringify(value) !== JSON.stringify(allowed[name])) {
+            state.set(name, value);
+            changed.add(name);
+        }
+    }
+    const evaluated = evaluateUiBlock(block, state);
+    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 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;
+            }
+            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;
+            }
+            visit(node.children, node.type);
+        }
+    };
+    visit(evaluated.nodes);
+    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

@@ -7,17 +7,28 @@ export function uiCompactCatalog(): string {
             const props = Object.entries(entry.schema.shape)
                 .map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`)
                 .join(',');
-            return `${name}(${props})`;
+            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(): 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()}`;
+    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 uiReferenceText(): string {
-    return Object.entries(UI_GROUPS)
+    const groups = Object.entries(UI_GROUPS)
         .map(([group, definition]) => {
             const components = Object.entries(UI_CATALOG)
                 .filter(([, entry]) => entry.group === group)
@@ -25,11 +36,12 @@ export function uiReferenceText(): string {
                     const props = Object.entries(entry.schema.shape)
                         .map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`)
                         .join(', ');
-                    return `${name}(${props}): ${entry.description}`;
+                    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}`;
 }
 
 export function uiFallbackText(text: string, blocks: readonly UiBlock[]): string {