@adecore/intelligent-ui 0.0.0 → 0.21.1

package/dist/stream.js

@@ -0,0 +1,56 @@
+import { UiCompiler } from './compiler.js';
+export const UI_STREAM_INTERVAL_MS = 250;
+export class UiStream {
+    compiler;
+    options;
+    pending = null;
+    timer = null;
+    lastCompiledAt = -Infinity;
+    closed = false;
+    constructor(options) {
+        this.options = options;
+        this.compiler = new UiCompiler(options);
+    }
+    update(text, latestAttachment) {
+        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, latestAttachment) {
+        this.dispose();
+        const blocks = this.compiler.compile(text, { final: true, latestAttachment });
+        this.compiler.clear();
+        return blocks;
+    }
+    dispose() {
+        this.closed = true;
+        if (this.timer !== null) {
+            this.options.clock.clearTimeout(this.timer.handle);
+            this.timer = null;
+        }
+        this.pending = null;
+        this.compiler.clear();
+    }
+    flush() {
+        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/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,32 +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(',');
-        return `${name}(${props})`;
+        const props = uiPropList(entry).join(',');
+        return `${name}${props ? `: ${props}` : ''}`;
     })
         .join(' · ');
 }
-export function uiSessionNote() {
-    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()}`;
+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() {
-    return Object.entries(UI_GROUPS)
+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(', ');
-            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, blocks) {
     let result = '';

package/package.json

@@ -1,84 +1,99 @@
 {
-    "name": "@adecore/intelligent-ui",
-    "version": "0.0.0",
-    "description": "A streaming UI catalog, compiler and bounded expression interpreter without a framework or DOM.",
-    "license": "FSL-1.1-MIT",
-    "author": "Bas Milius",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/basmilius/adecore.git",
-        "directory": "packages/intelligent-ui"
+  "name": "@adecore/intelligent-ui",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/basmilius/adecore.git",
+    "directory": "packages/intelligent-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/basmilius/adecore/issues"
+  },
+  "homepage": "https://adecore.dev/intelligent-ui/",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/fixtures"
+  ],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
-    "bugs": {
-        "url": "https://github.com/basmilius/adecore/issues"
+    "./links": {
+      "source": "./src/links.ts",
+      "types": "./dist/links.d.ts",
+      "default": "./dist/links.js"
     },
-    "homepage": "https://adecore.dev/intelligent-ui/",
-    "type": "module",
-    "sideEffects": false,
-    "files": [
-        "dist",
-        "src",
-        "!src/**/*.test.ts",
-        "!src/fixtures"
-    ],
-    "exports": {
-        ".": {
-            "source": "./src/index.ts",
-            "types": "./dist/index.d.ts",
-            "default": "./dist/index.js"
-        },
-        "./catalog": {
-            "source": "./src/catalog.ts",
-            "types": "./dist/catalog.d.ts",
-            "default": "./dist/catalog.js"
-        },
-        "./budget": {
-            "source": "./src/budget.ts",
-            "types": "./dist/budget.d.ts",
-            "default": "./dist/budget.js"
-        },
-        "./expression": {
-            "source": "./src/expression.ts",
-            "types": "./dist/expression.d.ts",
-            "default": "./dist/expression.js"
-        },
-        "./syntax": {
-            "source": "./src/syntax.ts",
-            "types": "./dist/syntax.d.ts",
-            "default": "./dist/syntax.js"
-        },
-        "./compiler": {
-            "source": "./src/compiler.ts",
-            "types": "./dist/compiler.d.ts",
-            "default": "./dist/compiler.js"
-        },
-        "./runtime": {
-            "source": "./src/runtime.ts",
-            "types": "./dist/runtime.d.ts",
-            "default": "./dist/runtime.js"
-        },
-        "./protocol": {
-            "source": "./src/protocol.ts",
-            "types": "./dist/protocol.d.ts",
-            "default": "./dist/protocol.js"
-        },
-        "./text": {
-            "source": "./src/text.ts",
-            "types": "./dist/text.d.ts",
-            "default": "./dist/text.js"
-        }
+    "./query": {
+      "source": "./src/query.ts",
+      "types": "./dist/query.d.ts",
+      "default": "./dist/query.js"
     },
-    "scripts": {
-        "build": "bun scripts/build.ts",
-        "typecheck": "tsc --noEmit",
-        "test": "bun test --conditions=source"
+    "./catalog": {
+      "source": "./src/catalog.ts",
+      "types": "./dist/catalog.d.ts",
+      "default": "./dist/catalog.js"
     },
-    "devDependencies": {
-        "@types/bun": "^1.4.2",
-        "@types/node": "^24.13.6",
-        "typescript": "^7.0.2"
+    "./budget": {
+      "source": "./src/budget.ts",
+      "types": "./dist/budget.d.ts",
+      "default": "./dist/budget.js"
     },
-    "dependencies": {
-        "zod": "^4.6.5"
+    "./expression": {
+      "source": "./src/expression.ts",
+      "types": "./dist/expression.d.ts",
+      "default": "./dist/expression.js"
+    },
+    "./syntax": {
+      "source": "./src/syntax.ts",
+      "types": "./dist/syntax.d.ts",
+      "default": "./dist/syntax.js"
+    },
+    "./compiler": {
+      "source": "./src/compiler.ts",
+      "types": "./dist/compiler.d.ts",
+      "default": "./dist/compiler.js"
+    },
+    "./runtime": {
+      "source": "./src/runtime.ts",
+      "types": "./dist/runtime.d.ts",
+      "default": "./dist/runtime.js"
+    },
+    "./protocol": {
+      "source": "./src/protocol.ts",
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    },
+    "./text": {
+      "source": "./src/text.ts",
+      "types": "./dist/text.d.ts",
+      "default": "./dist/text.js"
+    },
+    "./stream": {
+      "source": "./src/stream.ts",
+      "types": "./dist/stream.d.ts",
+      "default": "./dist/stream.js"
     }
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test --conditions=source"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.2",
+    "@types/node": "^24.13.6",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  }
 }

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');
 }