@adecore/intelligent-ui 0.25.2 → 0.25.3

package/dist/catalog.d.ts

@@ -91,6 +91,7 @@ export declare const UI_CATALOG: {
             value: z.ZodOptional<z.ZodNumber>;
             max: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>;
+        readonly text: 'label';
     };
     readonly Steps: {
         readonly group: 'status';
@@ -112,6 +113,7 @@ export declare const UI_CATALOG: {
             detail: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
         readonly parent: 'Steps';
+        readonly text: 'label';
     };
     readonly Timeline: {
         readonly group: 'status';
@@ -137,6 +139,7 @@ export declare const UI_CATALOG: {
             detail: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
         readonly parent: 'Timeline';
+        readonly text: 'title';
     };
     readonly Stats: {
         readonly group: 'data';
@@ -175,6 +178,7 @@ export declare const UI_CATALOG: {
             label: z.ZodString;
         }, z.core.$strict>;
         readonly parent: 'EntityList';
+        readonly text: 'value';
     };
     readonly Table: {
         readonly group: 'data';
@@ -260,6 +264,8 @@ export declare const UI_CATALOG: {
             generated: z.ZodOptional<z.ZodLiteral<"latest">>;
             alt: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
+        readonly needs: 'attachment|generated';
+        readonly text: 'caption';
     };
     readonly Gallery: {
         readonly group: 'content';
@@ -280,6 +286,7 @@ export declare const UI_CATALOG: {
             beforeLabel: z.ZodOptional<z.ZodString>;
             afterLabel: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
+        readonly text: 'caption';
     };
     readonly Map: {
         readonly group: 'places';
@@ -305,6 +312,8 @@ export declare const UI_CATALOG: {
             value: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
         }, z.core.$strict>;
         readonly parent: 'Map';
+        readonly needs: 'lat lon|address';
+        readonly text: 'name';
     };
     readonly Sources: {
         readonly group: 'content';
@@ -366,6 +375,7 @@ export declare const UI_CATALOG: {
             value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
         }, z.core.$strict>;
         readonly parent: 'Checklist';
+        readonly text: 'label';
     };
     readonly Switch: {
         readonly group: 'inputs';
@@ -374,6 +384,7 @@ export declare const UI_CATALOG: {
             value: z.ZodBoolean;
         }, z.core.$strict>;
         readonly binding: 'value';
+        readonly text: 'label';
     };
     readonly Slider: {
         readonly group: 'inputs';
@@ -386,6 +397,7 @@ export declare const UI_CATALOG: {
             unit: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
         readonly binding: 'value';
+        readonly text: 'label';
     };
     readonly Segmented: {
         readonly group: 'inputs';
@@ -404,6 +416,7 @@ export declare const UI_CATALOG: {
         }, z.core.$strict>;
         readonly children: readonly ['Option'];
         readonly binding: 'value';
+        readonly text: 'label';
     };
     readonly Option: {
         readonly group: 'inputs';
@@ -412,6 +425,7 @@ export declare const UI_CATALOG: {
             value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
         }, z.core.$strict>;
         readonly parent: readonly ['Segmented', 'Select'];
+        readonly text: 'label';
     };
     readonly TextField: {
         readonly group: 'inputs';
@@ -422,6 +436,7 @@ export declare const UI_CATALOG: {
             placeholder: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
         readonly binding: 'value';
+        readonly text: 'label';
     };
     readonly Button: {
         readonly group: 'inputs';
@@ -430,6 +445,7 @@ export declare const UI_CATALOG: {
             disabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>;
         readonly action: 'action';
+        readonly text: 'label';
     };
     readonly Show: {
         readonly group: 'inputs';
@@ -461,6 +477,7 @@ export declare const UI_CATALOG: {
             disabled: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>;
         readonly parent: 'Choices';
+        readonly text: 'label';
     };
 };
 export type UiGroupName = keyof typeof UI_GROUPS;

package/dist/catalog.js

@@ -38,14 +38,16 @@ export const UI_CATALOG = {
     Progress: {
         group: 'status',
         description: 'Progress with a label; omit value for indeterminate progress.',
-        schema: z.strictObject({ value: number.nonnegative().optional(), max: number.positive().optional() })
+        schema: z.strictObject({ value: number.nonnegative().optional(), max: number.positive().optional() }),
+        text: 'label'
     },
     Steps: { group: 'status', description: 'An ordered sequence of steps.', schema: empty, children: ['Step'] },
     Step: {
         group: 'status',
         description: 'One step in a sequence.',
         schema: z.strictObject({ state: z.enum(['done', 'running', 'pending', 'failed', 'skipped']), detail: text.optional() }),
-        parent: 'Steps'
+        parent: 'Steps',
+        text: 'label'
     },
     Timeline: { group: 'status', description: 'Events in time order.', schema: empty, children: ['Event'], count: { min: 1 } },
     Event: {
@@ -56,7 +58,8 @@ export const UI_CATALOG = {
             tone,
             detail: text.optional()
         }),
-        parent: 'Timeline'
+        parent: 'Timeline',
+        text: 'title'
     },
     Stats: { group: 'data', description: 'A small set of key numbers.', schema: empty, children: ['Stat'] },
     Stat: {
@@ -66,7 +69,7 @@ export const UI_CATALOG = {
         parent: 'Stats'
     },
     EntityList: { group: 'data', description: 'Labeled facts about an entity.', schema: empty, children: ['Entry'] },
-    Entry: { group: 'data', description: 'One labeled fact.', schema: z.strictObject({ label: text }), parent: 'EntityList' },
+    Entry: { group: 'data', description: 'One labeled fact.', schema: z.strictObject({ label: text }), parent: 'EntityList', text: 'value' },
     Table: { group: 'data', description: 'Rows with named columns.', schema: z.strictObject({ rows }), children: ['Column'] },
     Column: {
         group: 'data',
@@ -98,13 +101,16 @@ export const UI_CATALOG = {
         description: 'A chat attachment with an optional caption.',
         schema: z
             .strictObject({ attachment: name.optional(), generated: z.literal('latest').optional(), alt: text.optional() })
-            .refine((props) => Boolean(props.attachment) !== Boolean(props.generated), 'Choose attachment or generated, exclusively.')
+            .refine((props) => Boolean(props.attachment) !== Boolean(props.generated), 'Choose attachment or generated, exclusively.'),
+        needs: 'attachment|generated',
+        text: 'caption'
     },
     Gallery: { group: 'content', description: 'A grid of images with captions; at most 24.', schema: empty, children: ['Image'], count: { min: 1, max: 24 } },
     Compare: {
         group: 'content',
         description: 'Two chat attachments in one frame with a handle to wipe between them; children are the caption.',
-        schema: z.strictObject({ before: name, after: name, beforeLabel: text.optional(), afterLabel: text.optional() })
+        schema: z.strictObject({ before: name, after: name, beforeLabel: text.optional(), afterLabel: text.optional() }),
+        text: 'caption'
     },
     Map: {
         group: 'places',
@@ -126,7 +132,9 @@ export const UI_CATALOG = {
             value: scalar.optional()
         })
             .refine((props) => (props.lat === undefined) === (props.lon === undefined) && (props.lat !== undefined || props.address !== undefined), 'Give lat with lon, or an address.'),
-        parent: 'Map'
+        parent: 'Map',
+        needs: 'lat lon|address',
+        text: 'name'
     },
     Sources: { group: 'content', description: 'Numbered sources without preloading.', schema: empty, children: ['Source'] },
     Source: {
@@ -150,15 +158,16 @@ export const UI_CATALOG = {
         children: ['Item'],
         binding: 'value'
     },
-    Item: { group: 'inputs', description: 'One selectable value.', schema: z.strictObject({ value: scalar }), parent: 'Checklist' },
-    Switch: { group: 'inputs', description: 'A local boolean.', schema: z.strictObject({ value: z.boolean() }), binding: 'value' },
+    Item: { group: 'inputs', description: 'One selectable value.', schema: z.strictObject({ value: scalar }), parent: 'Checklist', text: 'label' },
+    Switch: { group: 'inputs', description: 'A local boolean.', schema: z.strictObject({ value: z.boolean() }), binding: 'value', text: 'label' },
     Slider: {
         group: 'inputs',
         description: 'A local number in a range.',
         schema: z
             .strictObject({ value: number, min: number, max: number, step: number.positive().optional(), unit: text.optional() })
             .refine((props) => props.min < props.max && props.value >= props.min && props.value <= props.max, 'Value must lie within an increasing range.'),
-        binding: 'value'
+        binding: 'value',
+        text: 'label'
     },
     Segmented: { group: 'inputs', description: 'Choose one local value.', schema: z.strictObject({ value: scalar }), children: ['Option'], binding: 'value' },
     Select: {
@@ -166,22 +175,31 @@ export const UI_CATALOG = {
         description: 'Choose one local value from a dropdown, for more or longer options than Segmented holds; the text beside its Options is its label.',
         schema: z.strictObject({ value: scalar }),
         children: ['Option'],
-        binding: 'value'
+        binding: 'value',
+        text: 'label'
+    },
+    Option: {
+        group: 'inputs',
+        description: 'One local alternative.',
+        schema: z.strictObject({ value: scalar }),
+        parent: ['Segmented', 'Select'],
+        text: 'label'
     },
-    Option: { group: 'inputs', description: 'One local alternative.', schema: z.strictObject({ value: scalar }), parent: ['Segmented', 'Select'] },
     TextField: {
         group: 'inputs',
         description: 'A line of local text up to maxLength characters (256 without one, at most 1024); children are the label.',
         schema: z
             .strictObject({ value: text, maxLength: z.number().int().min(1).max(1024).optional(), placeholder: text.max(128).optional() })
             .refine((props) => props.value.length <= (props.maxLength ?? 256), 'Value must not be longer than maxLength.'),
-        binding: 'value'
+        binding: 'value',
+        text: 'label'
     },
     Button: {
         group: 'inputs',
         description: 'Run one local state action when pressed; children are the label.',
         schema: z.strictObject({ disabled: z.boolean().optional() }),
-        action: 'action'
+        action: 'action',
+        text: 'label'
     },
     Show: { group: 'inputs', description: 'Show children when the condition is true.', schema: z.strictObject({ when: z.boolean() }) },
     Each: {
@@ -194,7 +212,8 @@ export const UI_CATALOG = {
         group: 'choices',
         description: 'Send its label and visible context once.',
         schema: z.strictObject({ context: text.optional(), primary: z.boolean().optional(), disabled: z.boolean().optional() }),
-        parent: 'Choices'
+        parent: 'Choices',
+        text: 'label'
     }
 };
 export function isUiComponent(name) {

package/dist/prop-list.d.ts

@@ -5,3 +5,11 @@ export declare function uiPropList(entry: {
     };
     readonly action?: string;
 }): string[];
+export declare function uiRequirement(name: string, entry: {
+    readonly schema: {
+        readonly shape: Readonly<Record<string, z.ZodType>>;
+    };
+    readonly action?: string;
+    readonly needs?: string;
+    readonly text?: string;
+}): string;

package/dist/prop-list.js

@@ -3,3 +3,11 @@ export function uiPropList(entry) {
     const props = Object.entries(entry.schema.shape).map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`);
     return entry.action ? [entry.action, ...props] : props;
 }
+/* What a component needs in the compact note: the props it cannot do without and, when its text is not the plain content, what that text is. */
+export function uiRequirement(name, entry) {
+    const required = entry.needs ??
+        uiPropList(entry)
+            .filter((prop) => !prop.endsWith('?'))
+            .join(' ');
+    return `${name}${required ? ` ${required}` : ''}${entry.text ? ` (text: ${entry.text})` : ''}`;
+}

package/dist/text.js

@@ -1,5 +1,5 @@
 import { UI_CATALOG, UI_GROUPS } from './catalog.js';
-import { uiPropList } from './prop-list.js';
+import { uiPropList, uiRequirement } from './prop-list.js';
 import { UI_FENCE_LANGUAGE } from './compiler.js';
 export function uiCompactCatalog() {
     return Object.entries(UI_CATALOG)
@@ -25,12 +25,12 @@ function uiExample(language) {
 function uiGroupComponents(group) {
     return Object.entries(UI_CATALOG).filter(([, entry]) => entry.group === group);
 }
-/* One line per group with the names of its components, for a host that hands the props out per group. */
+/* One line per group with its components and what each needs, for a host that hands the optional props out per group. */
 function uiGroupNames(detailHint) {
     const lines = Object.keys(UI_GROUPS).map((group) => `${group}: ${uiGroupComponents(group)
-        .map(([name]) => name)
+        .map(([name, entry]) => uiRequirement(name, entry))
         .join(', ')}`);
-    return `Components by group${detailHint ? ` (${detailHint})` : ''}:\n${lines.join('\n')}`;
+    return `Components by group${detailHint ? ` (${detailHint})` : ''}, required props (text: words between the tags):\n${lines.join('\n')}`;
 }
 export function uiSessionNote({ fenceLanguage = UI_FENCE_LANGUAGE, catalog = 'props', detailHint } = {}) {
     const components = catalog === 'names' ? uiGroupNames(detailHint) : `Catalog (? means optional props): ${uiCompactCatalog()}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/intelligent-ui",
-  "version": "0.25.2",
+  "version": "0.25.3",
   "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

@@ -43,14 +43,16 @@ export const UI_CATALOG = {
     Progress: {
         group: 'status',
         description: 'Progress with a label; omit value for indeterminate progress.',
-        schema: z.strictObject({ value: number.nonnegative().optional(), max: number.positive().optional() })
+        schema: z.strictObject({ value: number.nonnegative().optional(), max: number.positive().optional() }),
+        text: 'label'
     },
     Steps: { group: 'status', description: 'An ordered sequence of steps.', schema: empty, children: ['Step'] },
     Step: {
         group: 'status',
         description: 'One step in a sequence.',
         schema: z.strictObject({ state: z.enum(['done', 'running', 'pending', 'failed', 'skipped']), detail: text.optional() }),
-        parent: 'Steps'
+        parent: 'Steps',
+        text: 'label'
     },
     Timeline: { group: 'status', description: 'Events in time order.', schema: empty, children: ['Event'], count: { min: 1 } },
     Event: {
@@ -62,7 +64,8 @@ export const UI_CATALOG = {
             tone,
             detail: text.optional()
         }),
-        parent: 'Timeline'
+        parent: 'Timeline',
+        text: 'title'
     },
     Stats: { group: 'data', description: 'A small set of key numbers.', schema: empty, children: ['Stat'] },
     Stat: {
@@ -72,7 +75,7 @@ export const UI_CATALOG = {
         parent: 'Stats'
     },
     EntityList: { group: 'data', description: 'Labeled facts about an entity.', schema: empty, children: ['Entry'] },
-    Entry: { group: 'data', description: 'One labeled fact.', schema: z.strictObject({ label: text }), parent: 'EntityList' },
+    Entry: { group: 'data', description: 'One labeled fact.', schema: z.strictObject({ label: text }), parent: 'EntityList', text: 'value' },
     Table: { group: 'data', description: 'Rows with named columns.', schema: z.strictObject({ rows }), children: ['Column'] },
     Column: {
         group: 'data',
@@ -104,13 +107,16 @@ export const UI_CATALOG = {
         description: 'A chat attachment with an optional caption.',
         schema: z
             .strictObject({ attachment: name.optional(), generated: z.literal('latest').optional(), alt: text.optional() })
-            .refine((props) => Boolean(props.attachment) !== Boolean(props.generated), 'Choose attachment or generated, exclusively.')
+            .refine((props) => Boolean(props.attachment) !== Boolean(props.generated), 'Choose attachment or generated, exclusively.'),
+        needs: 'attachment|generated',
+        text: 'caption'
     },
     Gallery: { group: 'content', description: 'A grid of images with captions; at most 24.', schema: empty, children: ['Image'], count: { min: 1, max: 24 } },
     Compare: {
         group: 'content',
         description: 'Two chat attachments in one frame with a handle to wipe between them; children are the caption.',
-        schema: z.strictObject({ before: name, after: name, beforeLabel: text.optional(), afterLabel: text.optional() })
+        schema: z.strictObject({ before: name, after: name, beforeLabel: text.optional(), afterLabel: text.optional() }),
+        text: 'caption'
     },
     Map: {
         group: 'places',
@@ -136,7 +142,9 @@ export const UI_CATALOG = {
                 (props) => (props.lat === undefined) === (props.lon === undefined) && (props.lat !== undefined || props.address !== undefined),
                 'Give lat with lon, or an address.'
             ),
-        parent: 'Map'
+        parent: 'Map',
+        needs: 'lat lon|address',
+        text: 'name'
     },
     Sources: { group: 'content', description: 'Numbered sources without preloading.', schema: empty, children: ['Source'] },
     Source: {
@@ -160,15 +168,16 @@ export const UI_CATALOG = {
         children: ['Item'],
         binding: 'value'
     },
-    Item: { group: 'inputs', description: 'One selectable value.', schema: z.strictObject({ value: scalar }), parent: 'Checklist' },
-    Switch: { group: 'inputs', description: 'A local boolean.', schema: z.strictObject({ value: z.boolean() }), binding: 'value' },
+    Item: { group: 'inputs', description: 'One selectable value.', schema: z.strictObject({ value: scalar }), parent: 'Checklist', text: 'label' },
+    Switch: { group: 'inputs', description: 'A local boolean.', schema: z.strictObject({ value: z.boolean() }), binding: 'value', text: 'label' },
     Slider: {
         group: 'inputs',
         description: 'A local number in a range.',
         schema: z
             .strictObject({ value: number, min: number, max: number, step: number.positive().optional(), unit: text.optional() })
             .refine((props) => props.min < props.max && props.value >= props.min && props.value <= props.max, 'Value must lie within an increasing range.'),
-        binding: 'value'
+        binding: 'value',
+        text: 'label'
     },
     Segmented: { group: 'inputs', description: 'Choose one local value.', schema: z.strictObject({ value: scalar }), children: ['Option'], binding: 'value' },
     Select: {
@@ -176,22 +185,31 @@ export const UI_CATALOG = {
         description: 'Choose one local value from a dropdown, for more or longer options than Segmented holds; the text beside its Options is its label.',
         schema: z.strictObject({ value: scalar }),
         children: ['Option'],
-        binding: 'value'
+        binding: 'value',
+        text: 'label'
+    },
+    Option: {
+        group: 'inputs',
+        description: 'One local alternative.',
+        schema: z.strictObject({ value: scalar }),
+        parent: ['Segmented', 'Select'],
+        text: 'label'
     },
-    Option: { group: 'inputs', description: 'One local alternative.', schema: z.strictObject({ value: scalar }), parent: ['Segmented', 'Select'] },
     TextField: {
         group: 'inputs',
         description: 'A line of local text up to maxLength characters (256 without one, at most 1024); children are the label.',
         schema: z
             .strictObject({ value: text, maxLength: z.number().int().min(1).max(1024).optional(), placeholder: text.max(128).optional() })
             .refine((props) => props.value.length <= (props.maxLength ?? 256), 'Value must not be longer than maxLength.'),
-        binding: 'value'
+        binding: 'value',
+        text: 'label'
     },
     Button: {
         group: 'inputs',
         description: 'Run one local state action when pressed; children are the label.',
         schema: z.strictObject({ disabled: z.boolean().optional() }),
-        action: 'action'
+        action: 'action',
+        text: 'label'
     },
     Show: { group: 'inputs', description: 'Show children when the condition is true.', schema: z.strictObject({ when: z.boolean() }) },
     Each: {
@@ -204,7 +222,8 @@ export const UI_CATALOG = {
         group: 'choices',
         description: 'Send its label and visible context once.',
         schema: z.strictObject({ context: text.optional(), primary: z.boolean().optional(), disabled: z.boolean().optional() }),
-        parent: 'Choices'
+        parent: 'Choices',
+        text: 'label'
     }
 } as const;
 

package/src/prop-list.ts

@@ -5,3 +5,21 @@ export function uiPropList(entry: { readonly schema: { readonly shape: Readonly<
     const props = Object.entries(entry.schema.shape).map(([key, schema]) => `${key}${schema.isOptional() ? '?' : ''}`);
     return entry.action ? [entry.action, ...props] : props;
 }
+
+/* What a component needs in the compact note: the props it cannot do without and, when its text is not the plain content, what that text is. */
+export function uiRequirement(
+    name: string,
+    entry: {
+        readonly schema: { readonly shape: Readonly<Record<string, z.ZodType>> };
+        readonly action?: string;
+        readonly needs?: string;
+        readonly text?: string;
+    }
+): string {
+    const required =
+        entry.needs ??
+        uiPropList(entry)
+            .filter((prop) => !prop.endsWith('?'))
+            .join(' ');
+    return `${name}${required ? ` ${required}` : ''}${entry.text ? ` (text: ${entry.text})` : ''}`;
+}

package/src/text.ts

@@ -1,5 +1,5 @@
 import { UI_CATALOG, UI_GROUPS, type UiGroupName } from './catalog.ts';
-import { uiPropList } from './prop-list.ts';
+import { uiPropList, uiRequirement } from './prop-list.ts';
 import { UI_FENCE_LANGUAGE, type UiBlock } from './compiler.ts';
 
 export function uiCompactCatalog(): string {
@@ -39,15 +39,15 @@ function uiGroupComponents(group: string) {
     return Object.entries(UI_CATALOG).filter(([, entry]) => entry.group === group);
 }
 
-/* One line per group with the names of its components, for a host that hands the props out per group. */
+/* One line per group with its components and what each needs, for a host that hands the optional props out per group. */
 function uiGroupNames(detailHint: string | undefined): string {
     const lines = Object.keys(UI_GROUPS).map(
         (group) =>
             `${group}: ${uiGroupComponents(group)
-                .map(([name]) => name)
+                .map(([name, entry]) => uiRequirement(name, entry))
                 .join(', ')}`
     );
-    return `Components by group${detailHint ? ` (${detailHint})` : ''}:\n${lines.join('\n')}`;
+    return `Components by group${detailHint ? ` (${detailHint})` : ''}, required props (text: words between the tags):\n${lines.join('\n')}`;
 }
 
 export function uiSessionNote({ fenceLanguage = UI_FENCE_LANGUAGE, catalog = 'props', detailHint }: UiTextOptions = {}): string {