@adecore/intelligent-ui 0.23.1 → 0.24.0

package/dist/catalog.d.ts

@@ -34,8 +34,8 @@ export declare const UI_GROUPS: {
         readonly 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.';
     };
     readonly choices: {
-        readonly description: 'Offer optional next steps after a finished answer.';
-        readonly rules: 'Never ask for information or a decision needed before acting: use your own question tool if you have one, otherwise ask in prose. Give a short label and precise visible context. A Choice sends once after streaming ends.';
+        readonly description: 'Offer shortcuts after finished work that the person may ignore.';
+        readonly rules: 'Never a question your turn waits on (a missing fact, a decision, a go-ahead for work you would otherwise do): ask that with your own question tool if you have one, otherwise in prose. Give a short label and precise visible context. A Choice sends once after streaming ends.';
     };
 };
 export declare const UI_CATALOG: {
@@ -355,7 +355,7 @@ export declare const UI_CATALOG: {
     };
     readonly Choices: {
         readonly group: 'choices';
-        readonly description: 'Optional next steps after a finished answer.';
+        readonly description: 'Shortcuts after finished work, never a question you wait on.';
         readonly schema: z.ZodObject<{}, z.core.$strict>;
         readonly children: readonly ['Choice'];
     };

package/dist/catalog.js

@@ -23,8 +23,8 @@ export const UI_GROUPS = {
         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: 'Offer optional next steps after a finished answer.',
-        rules: 'Never ask for information or a decision needed before acting: use your own question tool if you have one, otherwise ask in prose. Give a short label and precise visible context. A Choice sends once after streaming ends.'
+        description: 'Offer shortcuts after finished work that the person may ignore.',
+        rules: 'Never a question your turn waits on (a missing fact, a decision, a go-ahead for work you would otherwise do): ask that with your own question tool if you have one, otherwise in prose. Give a short label and precise visible context. A Choice sends once after streaming ends.'
     }
 };
 export const UI_CATALOG = {
@@ -131,7 +131,7 @@ export const UI_CATALOG = {
         description: 'Repeat children over local data.',
         schema: z.strictObject({ items: z.array(z.unknown()).max(1000), as: name.regex(/^[A-Za-z_][A-Za-z_\d]*$/) })
     },
-    Choices: { group: 'choices', description: 'Optional next steps after a finished answer.', schema: empty, children: ['Choice'] },
+    Choices: { group: 'choices', description: 'Shortcuts after finished work, never a question you wait on.', schema: empty, children: ['Choice'] },
     Choice: {
         group: 'choices',
         description: 'Send its label and visible context once.',

package/dist/query.d.ts

@@ -3,5 +3,5 @@ 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>>, 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 uiQueryArguments(block: UiBlock, name: string, input?: Readonly<Record<string, unknown>>, limits?: Partial<UiLimits>, queries?: Readonly<Record<string, unknown>>): Record<string, UiValue>;
 export declare function uiQueryFallback(block: UiBlock, queries: Readonly<Record<string, unknown>>): string;

package/dist/query.js

@@ -32,11 +32,16 @@ export function uiValidatedState(block, input = {}, queries = {}, limits = {}) {
     }
     return state;
 }
-export function uiQueryArguments(block, name, input = {}, limits = {}) {
+/*
+ * `queries` are the readings the person saw, so an input chosen from options a query read is checked
+ * against them; without them such an input only passes as its default. The arguments themselves read
+ * only local state.
+ */
+export function uiQueryArguments(block, name, input = {}, limits = {}, queries = {}) {
     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 state = uiValidatedState(block, input, queries, limits);
     const query = block.queries[name];
     return query.expression
         ? evaluateUiExpression(query.expression, state.scope(), new UiBudget(limits))

package/dist/text.js

@@ -19,12 +19,11 @@ function uiExample(language) {
         '<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. Choices only offer optional next steps after a finished answer; ask for information or a decision needed before acting with your own question tool if you have one, otherwise in prose. 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`;
+    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. Choices are shortcuts after finished work that the person may ignore. When your turn would end waiting on the person (a missing fact, a decision, a go-ahead for work you would otherwise do), ask with your own question tool if you have one, otherwise in prose, never with Choices. 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/intelligent-ui",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "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/catalog.ts

@@ -27,8 +27,8 @@ export const UI_GROUPS = {
         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: 'Offer optional next steps after a finished answer.',
-        rules: 'Never ask for information or a decision needed before acting: use your own question tool if you have one, otherwise ask in prose. Give a short label and precise visible context. A Choice sends once after streaming ends.'
+        description: 'Offer shortcuts after finished work that the person may ignore.',
+        rules: 'Never a question your turn waits on (a missing fact, a decision, a go-ahead for work you would otherwise do): ask that with your own question tool if you have one, otherwise in prose. Give a short label and precise visible context. A Choice sends once after streaming ends.'
     }
 } as const;
 
@@ -136,7 +136,7 @@ export const UI_CATALOG = {
         description: 'Repeat children over local data.',
         schema: z.strictObject({ items: z.array(z.unknown()).max(1000), as: name.regex(/^[A-Za-z_][A-Za-z_\d]*$/) })
     },
-    Choices: { group: 'choices', description: 'Optional next steps after a finished answer.', schema: empty, children: ['Choice'] },
+    Choices: { group: 'choices', description: 'Shortcuts after finished work, never a question you wait on.', schema: empty, children: ['Choice'] },
     Choice: {
         group: 'choices',
         description: 'Send its label and visible context once.',

package/src/query.ts

@@ -40,16 +40,22 @@ export function uiValidatedState(
     return state;
 }
 
+/*
+ * `queries` are the readings the person saw, so an input chosen from options a query read is checked
+ * against them; without them such an input only passes as its default. The arguments themselves read
+ * only local state.
+ */
 export function uiQueryArguments(
     block: UiBlock,
     name: string,
     input: Readonly<Record<string, unknown>> = {},
-    limits: Partial<UiLimits> = {}
+    limits: Partial<UiLimits> = {},
+    queries: 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, {}, limits);
+    const state = uiValidatedState(block, input, queries, limits);
     const query = block.queries[name];
     return query.expression
         ? (evaluateUiExpression(query.expression, state.scope(), new UiBudget(limits)) as Record<string, UiValue>)

package/src/text.ts

@@ -27,13 +27,12 @@ function uiExample(language: string): string {
         '<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. Choices only offer optional next steps after a finished answer; ask for information or a decision needed before acting with your own question tool if you have one, otherwise in prose. 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`;
+    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. Choices are shortcuts after finished work that the person may ignore. When your turn would end waiting on the person (a missing fact, a decision, a go-ahead for work you would otherwise do), ask with your own question tool if you have one, otherwise in prose, never with Choices. 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 {