@adecore/intelligent-ui 0.25.1 → 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';
@@ -124,7 +126,7 @@ export declare const UI_CATALOG: {
     };
     readonly Event: {
         readonly group: 'status';
-        readonly description: 'One event at a time or date; children are the title.';
+        readonly description: 'One event at a time or date; children are the title. at is HH:MM[:SS], YYYY-MM-DD, or YYYY-MM-DDTHH:MM[:SS] with an optional Z or ±HH:MM.';
         readonly schema: z.ZodObject<{
             at: z.ZodString;
             tone: z.ZodOptional<z.ZodEnum<{
@@ -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

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import { parseUiEventTime } from './event-time.js';
 import { uiPropList } from './prop-list.js';
 export const UI_CATALOG_VERSION = 1;
 export const UiToneSchema = z.enum(['neutral', 'info', 'success', 'warning', 'danger']);
@@ -39,25 +38,28 @@ 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: {
         group: 'status',
-        description: 'One event at a time or date; children are the title.',
+        description: 'One event at a time or date; children are the title. at is HH:MM[:SS], YYYY-MM-DD, or YYYY-MM-DDTHH:MM[:SS] with an optional Z or ±HH:MM.',
         schema: z.strictObject({
-            at: text.refine((value) => parseUiEventTime(value) !== null, 'At must be HH:MM, YYYY-MM-DD or an ISO date-time.'),
+            at: text,
             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: {
@@ -67,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',
@@ -99,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',
@@ -127,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: {
@@ -151,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: {
@@ -167,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: {
@@ -195,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/compiler.js

@@ -1,6 +1,7 @@
 import { safeKey, UI_LIMITS, UiBudget, UiFailure } from './budget.js';
 import { isUiComponent, UI_CATALOG, UI_CATALOG_VERSION } from './catalog.js';
 import { uiActionProp, uiActionTarget, uiLocalState } from './actions.js';
+import { unreadableEventTime } from './event-warning.js';
 import { uiNodeFallback, uiPlainText } from './fallback.js';
 import { evaluateUiExpression, sameUiValue } from './expression.js';
 import { parseUiSyntax, uiDiagnostic } from './syntax.js';
@@ -241,6 +242,10 @@ export function compileUiBlock(source, options) {
                     throw new UiFailure('invalid_props', parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '));
                 }
             }
+            const unreadable = !unresolved && syntax.complete && syntax.type === 'Event' ? unreadableEventTime(evaluated.at) : null;
+            if (unreadable !== null) {
+                diagnose(unreadable, syntax.start, syntax.end, syntax.id);
+            }
             // The catalog promises six series, one per chart color; more still reach the values a person can open.
             if (!unresolved && syntax.complete && syntax.type === 'Chart' && chartSeries(evaluated.data) > CHART_SERIES) {
                 diagnose(new UiFailure('too_many_series', `Chart draws up to ${CHART_SERIES} numeric series; the rest are only in its values.`), syntax.start, syntax.end, syntax.id);

package/dist/event-time.d.ts

@@ -2,5 +2,6 @@ export interface UiEventTime {
     kind: 'time' | 'date' | 'datetime';
     date: Date;
     written: boolean;
+    seconds: boolean;
 }
 export declare function parseUiEventTime(at: string): UiEventTime | null;

package/dist/event-time.js

@@ -1,4 +1,4 @@
-const EVENT_TIME = /^(?:(\d{2}):(\d{2})|(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?)$/;
+const EVENT_TIME = /^(?:(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?|(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?)$/;
 function validClock(hour, minute, second = 0) {
     return hour <= 23 && minute <= 59 && second <= 59;
 }
@@ -11,17 +11,23 @@ function zoneOffset(zone) {
     const offset = (zone[0] === '-' ? -1 : 1) * (hours * 60 + minutes);
     return minutes > 59 || offset < -12 * 60 || offset > 14 * 60 ? null : offset;
 }
-/* The moment an Event's `at` names, or null when it is no `HH:MM`, `YYYY-MM-DD` or ISO date-time with an optional offset. */
+/* The moment an Event's `at` names, or null when it is no `HH:MM[:SS]`, `YYYY-MM-DD` or ISO date-time with an optional offset. */
 export function parseUiEventTime(at) {
     const match = EVENT_TIME.exec(at);
     if (match === null) {
         return null;
     }
-    const [, clockHour, clockMinute, year, month, day, hour, minute, second, zone] = match.map((part) => part);
+    const [, clockHour, clockMinute, clockSecond, year, month, day, hour, minute, second, zone] = match.map((part) => part);
     if (clockHour !== undefined) {
         // The day is not shown for a time, so any day will do.
-        return validClock(Number(clockHour), Number(clockMinute))
-            ? { kind: 'time', date: new Date(Date.UTC(2000, 0, 1, Number(clockHour), Number(clockMinute))), written: true }
+        const clockSeconds = Number(clockSecond ?? 0);
+        return validClock(Number(clockHour), Number(clockMinute), clockSeconds)
+            ? {
+                kind: 'time',
+                date: new Date(Date.UTC(2000, 0, 1, Number(clockHour), Number(clockMinute), clockSeconds)),
+                written: true,
+                seconds: clockSecond !== undefined
+            }
             : null;
     }
     const [y, m, d] = [Number(year), Number(month), Number(day)];
@@ -30,15 +36,15 @@ export function parseUiEventTime(at) {
         return null;
     }
     if (hour === undefined) {
-        return { kind: 'date', date: calendar, written: true };
+        return { kind: 'date', date: calendar, written: true, seconds: false };
     }
     const [h, min, sec] = [Number(hour), Number(minute), Number(second ?? 0)];
     if (!validClock(h, min, sec)) {
         return null;
     }
     if (zone === undefined) {
-        return { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec)), written: true };
+        return { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec)), written: true, seconds: false };
     }
     const offset = zoneOffset(zone);
-    return offset === null ? null : { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec) - offset * 60000), written: false };
+    return offset === null ? null : { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec) - offset * 60000), written: false, seconds: false };
 }

package/dist/event-warning.d.ts

@@ -0,0 +1,2 @@
+import { UiFailure } from './budget.ts';
+export declare function unreadableEventTime(at: unknown): UiFailure | null;

package/dist/event-warning.js

@@ -0,0 +1,10 @@
+import { UiFailure } from './budget.js';
+import { parseUiEventTime } from './event-time.js';
+/* The warning for an Event whose `at` cannot be read, or null when it can. The Event still draws, with `at` as written. */
+export function unreadableEventTime(at) {
+    if (typeof at !== 'string' || parseUiEventTime(at) !== null) {
+        return null;
+    }
+    const shown = at.length > 40 ? `${at.slice(0, 40)}...` : at;
+    return new UiFailure('unreadable_time', `Event at="${shown}" is not HH:MM[:SS], YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS] with an optional Z or ±HH:MM, so it is shown as written.`);
+}

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/protocol.d.ts

@@ -7,6 +7,7 @@ export declare const UiDiagnosticSchema: z.ZodObject<{
     start: z.ZodNumber;
     end: z.ZodNumber;
     nodeId: z.ZodOptional<z.ZodString>;
+    severity: z.ZodOptional<z.ZodLiteral<"warning">>;
 }, z.core.$strip>;
 export declare const UiBlockSchema: z.ZodType<UiBlock>;
 export declare const UiBlocksSchema: z.ZodArray<z.ZodType<UiBlock, unknown, z.core.$ZodTypeInternals<UiBlock, unknown>>>;

package/dist/protocol.js

@@ -20,7 +20,8 @@ export const UiDiagnosticSchema = z.object({
     message: z.string(),
     start: position,
     end: position,
-    nodeId: z.string().optional()
+    nodeId: z.string().optional(),
+    severity: z.literal('warning').optional()
 });
 export const UiBlockSchema = z.object({
     id: z.string(),

package/dist/runtime.js

@@ -4,6 +4,7 @@ import { isUiComponent, UI_CATALOG, UI_CATALOG_VERSION } from './catalog.js';
 import {} from './compiler.js';
 import { uiActionProp, uiActionTarget, uiLocalState } from './actions.js';
 import { uiCompiledNodes, uiVisibleInputs } from './inputs.js';
+import { unreadableEventTime } from './event-warning.js';
 import { uiDiagnostic } from './syntax.js';
 export class UiState {
     id = '';
@@ -150,6 +151,14 @@ export function evaluateUiBlock(block, state = new UiState(block), limits = {})
                 throw new UiFailure('invalid_props', parsed.error.issues.map((issue) => issue.message).join('; '));
             }
             view.props = parsed.data;
+            const unreadable = node.complete && node.type === 'Event' ? unreadableEventTime(props.at) : null;
+            // The compiler already warned about a time it could read from the source; this one waited on an Each or a query.
+            if (unreadable !== null &&
+                ![...block.diagnostics, ...result.diagnostics].some((item) => item.code === 'unreadable_time' && item.nodeId === node.id)) {
+                if (result.diagnostics.length < budget.limits.diagnostics) {
+                    result.diagnostics.push(uiDiagnostic(unreadable, node.start, node.end, node.id));
+                }
+            }
             if (node.type === 'Show') {
                 return props.when ? children(node.children, variables, depth + 1, suffix) : [];
             }

package/dist/syntax.d.ts

@@ -6,6 +6,7 @@ export interface UiDiagnostic {
     start: number;
     end: number;
     nodeId?: string;
+    severity?: 'warning';
 }
 export interface UiSyntaxNode {
     id: string;

package/dist/syntax.js

@@ -1,8 +1,11 @@
 import { safeKey, UiBudget, UiFailure } from './budget.js';
 import { parseUiExpression } from './expression.js';
+const WARNING_CODES = new Set(['refused_prop', 'too_many_series', 'too_many_children', 'unreadable_time']);
 export function uiDiagnostic(error, start, end, nodeId) {
+    const code = error instanceof UiFailure ? error.code : 'invalid_syntax';
     return {
-        code: error instanceof UiFailure ? error.code : 'invalid_syntax',
+        code,
+        ...(WARNING_CODES.has(code) ? { severity: 'warning' } : {}),
         message: error instanceof Error ? error.message : 'Invalid UI syntax.',
         start,
         end,

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.1",
+  "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

@@ -1,5 +1,4 @@
 import { z } from 'zod';
-import { parseUiEventTime } from './event-time.ts';
 import { uiPropList } from './prop-list.ts';
 
 export const UI_CATALOG_VERSION = 1;
@@ -44,25 +43,29 @@ 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: {
         group: 'status',
-        description: 'One event at a time or date; children are the title.',
+        description:
+            'One event at a time or date; children are the title. at is HH:MM[:SS], YYYY-MM-DD, or YYYY-MM-DDTHH:MM[:SS] with an optional Z or ±HH:MM.',
         schema: z.strictObject({
-            at: text.refine((value) => parseUiEventTime(value) !== null, 'At must be HH:MM, YYYY-MM-DD or an ISO date-time.'),
+            at: text,
             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/compiler.ts

@@ -1,6 +1,7 @@
 import { safeKey, UI_LIMITS, UiBudget, UiFailure, type UiLimits } from './budget.ts';
 import { isUiComponent, UI_CATALOG, UI_CATALOG_VERSION } from './catalog.ts';
 import { uiActionProp, uiActionTarget, uiLocalState } from './actions.ts';
+import { unreadableEventTime } from './event-warning.ts';
 import { uiNodeFallback, uiPlainText } from './fallback.ts';
 import { evaluateUiExpression, sameUiValue, type UiExpression, type UiValue } from './expression.ts';
 import { parseUiSyntax, uiDiagnostic, type UiDiagnostic, type UiSyntaxNode } from './syntax.ts';
@@ -312,6 +313,10 @@ export function compileUiBlock(source: string, options: UiCompileOptions): UiBlo
                     throw new UiFailure('invalid_props', parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; '));
                 }
             }
+            const unreadable = !unresolved && syntax.complete && syntax.type === 'Event' ? unreadableEventTime(evaluated.at) : null;
+            if (unreadable !== null) {
+                diagnose(unreadable, syntax.start, syntax.end, syntax.id);
+            }
             // The catalog promises six series, one per chart color; more still reach the values a person can open.
             if (!unresolved && syntax.complete && syntax.type === 'Chart' && chartSeries(evaluated.data) > CHART_SERIES) {
                 diagnose(

package/src/event-time.ts

@@ -1,10 +1,13 @@
-const EVENT_TIME = /^(?:(\d{2}):(\d{2})|(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?)$/;
+const EVENT_TIME =
+    /^(?:(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?|(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-]\d{2}:\d{2})?)?)$/;
 
 export interface UiEventTime {
     kind: 'time' | 'date' | 'datetime';
     date: Date;
     // True when the text gave no offset: `date` then holds the parts as written in UTC, to be written in UTC, so no zone or clock change moves them. False is a real instant, to be written in the reader's zone.
     written: boolean;
+    // True for a lone time that wrote seconds (`14:05:30`), which then shows them. A date-time shows its minutes only.
+    seconds: boolean;
 }
 
 function validClock(hour: number, minute: number, second = 0): boolean {
@@ -21,17 +24,23 @@ function zoneOffset(zone: string): number | null {
     return minutes > 59 || offset < -12 * 60 || offset > 14 * 60 ? null : offset;
 }
 
-/* The moment an Event's `at` names, or null when it is no `HH:MM`, `YYYY-MM-DD` or ISO date-time with an optional offset. */
+/* The moment an Event's `at` names, or null when it is no `HH:MM[:SS]`, `YYYY-MM-DD` or ISO date-time with an optional offset. */
 export function parseUiEventTime(at: string): UiEventTime | null {
     const match = EVENT_TIME.exec(at);
     if (match === null) {
         return null;
     }
-    const [, clockHour, clockMinute, year, month, day, hour, minute, second, zone] = match.map((part) => part as string | undefined);
+    const [, clockHour, clockMinute, clockSecond, year, month, day, hour, minute, second, zone] = match.map((part) => part as string | undefined);
     if (clockHour !== undefined) {
         // The day is not shown for a time, so any day will do.
-        return validClock(Number(clockHour), Number(clockMinute))
-            ? { kind: 'time', date: new Date(Date.UTC(2000, 0, 1, Number(clockHour), Number(clockMinute))), written: true }
+        const clockSeconds = Number(clockSecond ?? 0);
+        return validClock(Number(clockHour), Number(clockMinute), clockSeconds)
+            ? {
+                  kind: 'time',
+                  date: new Date(Date.UTC(2000, 0, 1, Number(clockHour), Number(clockMinute), clockSeconds)),
+                  written: true,
+                  seconds: clockSecond !== undefined
+              }
             : null;
     }
     const [y, m, d] = [Number(year), Number(month), Number(day)];
@@ -40,15 +49,15 @@ export function parseUiEventTime(at: string): UiEventTime | null {
         return null;
     }
     if (hour === undefined) {
-        return { kind: 'date', date: calendar, written: true };
+        return { kind: 'date', date: calendar, written: true, seconds: false };
     }
     const [h, min, sec] = [Number(hour), Number(minute), Number(second ?? 0)];
     if (!validClock(h, min, sec)) {
         return null;
     }
     if (zone === undefined) {
-        return { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec)), written: true };
+        return { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec)), written: true, seconds: false };
     }
     const offset = zoneOffset(zone);
-    return offset === null ? null : { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec) - offset * 60000), written: false };
+    return offset === null ? null : { kind: 'datetime', date: new Date(Date.UTC(y, m - 1, d, h, min, sec) - offset * 60000), written: false, seconds: false };
 }

package/src/event-warning.ts

@@ -0,0 +1,14 @@
+import { UiFailure } from './budget.ts';
+import { parseUiEventTime } from './event-time.ts';
+
+/* The warning for an Event whose `at` cannot be read, or null when it can. The Event still draws, with `at` as written. */
+export function unreadableEventTime(at: unknown): UiFailure | null {
+    if (typeof at !== 'string' || parseUiEventTime(at) !== null) {
+        return null;
+    }
+    const shown = at.length > 40 ? `${at.slice(0, 40)}...` : at;
+    return new UiFailure(
+        'unreadable_time',
+        `Event at="${shown}" is not HH:MM[:SS], YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS] with an optional Z or ±HH:MM, so it is shown as written.`
+    );
+}

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/protocol.ts

@@ -26,7 +26,8 @@ export const UiDiagnosticSchema = z.object({
     message: z.string(),
     start: position,
     end: position,
-    nodeId: z.string().optional()
+    nodeId: z.string().optional(),
+    severity: z.literal('warning').optional()
 });
 
 export const UiBlockSchema: z.ZodType<UiBlock> = z.object({

package/src/runtime.ts

@@ -4,6 +4,7 @@ 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 { unreadableEventTime } from './event-warning.ts';
 import { uiDiagnostic, type UiDiagnostic } from './syntax.ts';
 
 export interface UiBinding<Value> {
@@ -185,6 +186,16 @@ export function evaluateUiBlock(block: UiBlock, state = new UiState(block), limi
                 throw new UiFailure('invalid_props', parsed.error.issues.map((issue) => issue.message).join('; '));
             }
             view.props = parsed.data;
+            const unreadable = node.complete && node.type === 'Event' ? unreadableEventTime(props.at) : null;
+            // The compiler already warned about a time it could read from the source; this one waited on an Each or a query.
+            if (
+                unreadable !== null &&
+                ![...block.diagnostics, ...result.diagnostics].some((item) => item.code === 'unreadable_time' && item.nodeId === node.id)
+            ) {
+                if (result.diagnostics.length < budget.limits.diagnostics) {
+                    result.diagnostics.push(uiDiagnostic(unreadable, node.start, node.end, node.id));
+                }
+            }
             if (node.type === 'Show') {
                 return props.when ? children(node.children, variables, depth + 1, suffix) : [];
             }

package/src/syntax.ts

@@ -7,6 +7,8 @@ export interface UiDiagnostic {
     start: number;
     end: number;
     nodeId?: string;
+    // Only a warning says so: the part it names still drew. Absent means an error, a part that could not be drawn.
+    severity?: 'warning';
 }
 
 export interface UiSyntaxNode {
@@ -29,9 +31,13 @@ export interface UiSyntax {
     diagnostics: UiDiagnostic[];
 }
 
+const WARNING_CODES = new Set(['refused_prop', 'too_many_series', 'too_many_children', 'unreadable_time']);
+
 export function uiDiagnostic(error: unknown, start: number, end: number, nodeId?: string): UiDiagnostic {
+    const code = error instanceof UiFailure ? error.code : 'invalid_syntax';
     return {
-        code: error instanceof UiFailure ? error.code : 'invalid_syntax',
+        code,
+        ...(WARNING_CODES.has(code) ? { severity: 'warning' as const } : {}),
         message: error instanceof Error ? error.message : 'Invalid UI syntax.',
         start,
         end,

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 {