@keemakr/ui-sdk 1.6.0-dev-20261027202014 → 1.6.0-dev-20261027204717

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { UI_SCHEMA_VERSION, pressSchema, chatPressSchema, valuePressSchema, NAVIGATE_OPENS, buttonSchema, cellSchema, tableCellSchema, dateFormatSchema, nodeSchema, screenPresentationSchema, screenTreeSchema, actionResultSchema, screenLoadRequestSchema, screenLoadResponseSchema, screenActionRequestSchema, interfaceFamilySchema, surfaceDefinitionSchema, surfaceSchema, screenRegistrationSchema, uiManifestSchema, jobIdSchema, jobStatusSchema, screenJobRequestSchema, mediaPathSchema, seekPointSchema, seekPressSchema, BADGE_COUNT_MAX, surfaceBadgeSchema, screenBadgesRequestSchema, screenBadgesResponseSchema, TABS_MAX, } from './schema.js';
+export { UI_SCHEMA_VERSION, pressSchema, chatPressSchema, valuePressSchema, NAVIGATE_OPENS, buttonSchema, cellSchema, factCellSchema, tableCellSchema, dateFormatSchema, nodeSchema, screenPresentationSchema, screenTreeSchema, actionResultSchema, screenLoadRequestSchema, screenLoadResponseSchema, screenActionRequestSchema, interfaceFamilySchema, surfaceDefinitionSchema, surfaceSchema, screenRegistrationSchema, uiManifestSchema, jobIdSchema, jobStatusSchema, screenJobRequestSchema, mediaPathSchema, seekPointSchema, seekPressSchema, BADGE_COUNT_MAX, surfaceBadgeSchema, screenBadgesRequestSchema, screenBadgesResponseSchema, TABS_MAX, } from './schema.js';
 export type { Press, ChatPress, SeekPress, SeekPoint, ValuePress, NavigatePress, NavigateOpen, ScreenPresentation, ScreenNode, ScreenRootNode, ScreenTree, ActionResult, InterfaceFamily, SurfaceDefinition, Surface, ScreenRegistration, UiManifest, ScreenTreeInput, ActionResultInput, JobStatus, JobStatusInput, SurfaceBadge, SurfaceBadgeInput, ScreenBadgesRequest, ScreenBadgesResponse, } from './schema.js';
 export { BADGE_DISPLAY_MAX, answerBadges, badgeSpokenLabel, badgeText, defineBadges, parseScreenBadges, } from './badges.js';
 export type { BadgesHandler } from './badges.js';

package/dist/index.js

@@ -6,7 +6,7 @@
 //                    platform components, proxies load/action with a grant
 //
 // Module code never ships to the browser. UI is data, not code.
-export { UI_SCHEMA_VERSION, pressSchema, chatPressSchema, valuePressSchema, NAVIGATE_OPENS, buttonSchema, cellSchema, tableCellSchema, dateFormatSchema, nodeSchema, screenPresentationSchema, screenTreeSchema, actionResultSchema, screenLoadRequestSchema, screenLoadResponseSchema, screenActionRequestSchema, interfaceFamilySchema, surfaceDefinitionSchema, surfaceSchema, screenRegistrationSchema, uiManifestSchema, jobIdSchema, jobStatusSchema, screenJobRequestSchema, mediaPathSchema, seekPointSchema, seekPressSchema, BADGE_COUNT_MAX, surfaceBadgeSchema, screenBadgesRequestSchema, screenBadgesResponseSchema, TABS_MAX, } from './schema.js';
+export { UI_SCHEMA_VERSION, pressSchema, chatPressSchema, valuePressSchema, NAVIGATE_OPENS, buttonSchema, cellSchema, factCellSchema, tableCellSchema, dateFormatSchema, nodeSchema, screenPresentationSchema, screenTreeSchema, actionResultSchema, screenLoadRequestSchema, screenLoadResponseSchema, screenActionRequestSchema, interfaceFamilySchema, surfaceDefinitionSchema, surfaceSchema, screenRegistrationSchema, uiManifestSchema, jobIdSchema, jobStatusSchema, screenJobRequestSchema, mediaPathSchema, seekPointSchema, seekPressSchema, BADGE_COUNT_MAX, surfaceBadgeSchema, screenBadgesRequestSchema, screenBadgesResponseSchema, TABS_MAX, } from './schema.js';
 export { BADGE_DISPLAY_MAX, answerBadges, badgeSpokenLabel, badgeText, defineBadges, parseScreenBadges, } from './badges.js';
 export { CHART_POINTS_MAX, thinChart, thinnedIndices } from './chart.js';
 export { TABS_MAX_1_4_0, foldTabs, onlyTabParamsDiffer, openingTab, tabParamsOf } from './tabs.js';

package/dist/negotiate.d.ts

@@ -75,8 +75,12 @@ import type { ChatPress, ScreenRootNode, ScreenTree } from './schema.js';
  *     (newer than any published release; core's own renderer draws it). An older parse strips it,
  *     so without it the action becomes a `button` with the same label and press, last in the
  *     section, and the reader can still go where it led. A full section drops it.
+ *   - `facts.meter`: a `meter` cell as a calendar entry's `details` value or a header `meta` value
+ *     (newer than any published release; core's own renderer draws it). An older parse refuses it,
+ *     so without it the meter becomes a `text` cell with its value label ("Intake 3/5"). Header
+ *     facts a client draws as one line (no `header.meta`) are written the same way.
  */
-export type UiFeature = 'breadcrumbs' | 'button.disabled' | 'section.row' | 'form.field_kinds' | 'form.confirm' | 'press.chat' | 'form.radio' | 'table.cells' | 'header.meta' | 'tabs.many' | 'choice.action' | 'markdown.links' | 'form.disabled' | 'press.seek' | 'edit.inline' | 'timeline.time_tag' | 'stat.bar' | 'section.action';
+export type UiFeature = 'breadcrumbs' | 'button.disabled' | 'section.row' | 'form.field_kinds' | 'form.confirm' | 'press.chat' | 'form.radio' | 'table.cells' | 'header.meta' | 'tabs.many' | 'choice.action' | 'markdown.links' | 'form.disabled' | 'press.seek' | 'edit.inline' | 'timeline.time_tag' | 'stat.bar' | 'section.action' | 'facts.meter';
 /** The node types and features one ui-sdk release, or one client, draws. */
 export interface NodeSet {
     /** For messages: "ui-sdk 1.4.0", "mobile 0.2.5". */
@@ -113,7 +117,7 @@ export declare const UI_SDK_SNAPSHOTS: {
     readonly current: {
         readonly name: "ui-sdk (this package)";
         readonly nodes: readonly ["heading", "text", "markdown", "stat", "button", "form", "table", "timeline", "pending_request", "pending_requests", "choice_cards", "progress", "chart", "section", "tabs", "pagination", "select", "alert", "details", "timestamp", "divider", "board", "link", "tags", "toggle", "segmented", "progress_bar", "conversation", "composer", "calendar", "image", "video", "stacked_bar", "heatmap", "audio"];
-        readonly features: readonly ["breadcrumbs", "button.disabled", "section.row", "form.field_kinds", "form.confirm", "press.chat", "form.radio", "table.cells", "header.meta", "tabs.many", "choice.action", "markdown.links", "form.disabled", "press.seek", "edit.inline", "timeline.time_tag", "stat.bar", "section.action"];
+        readonly features: readonly ["breadcrumbs", "button.disabled", "section.row", "form.field_kinds", "form.confirm", "press.chat", "form.radio", "table.cells", "header.meta", "tabs.many", "choice.action", "markdown.links", "form.disabled", "press.seek", "edit.inline", "timeline.time_tag", "stat.bar", "section.action", "facts.meter"];
     };
 };
 export type UiSdkSnapshot = keyof typeof UI_SDK_SNAPSHOTS;

package/dist/negotiate.js

@@ -20,7 +20,7 @@
 // (tests/sdk/ui-negotiation.test.ts) fails until the current snapshot matches KNOWN_NODE_TYPES,
 // until every node type has a fallback, and until every sample tree, negotiated for every row,
 // parses with that row's published schema with no safety field lost.
-import { foldTableCell, isNewerTableCell } from './cells.js';
+import { foldTableCell, isNewerTableCell, meterLabel } from './cells.js';
 import { conformTree } from './conform.js';
 import { withoutScreenLinks } from './markdown-links.js';
 import { pageRangeLabel } from './pager.js';
@@ -52,6 +52,7 @@ const ALL_FEATURES = [
     'timeline.time_tag',
     'stat.bar',
     'section.action',
+    'facts.meter',
 ];
 /** The nodes of ui-sdk 1.1.0 and 1.2.0 (one schema). */
 const NODES_1_1_0 = [
@@ -400,6 +401,22 @@ export function negotiateTree(tree, set) {
                 return features.has('choice.action') ? node : foldChoiceActions(node, path, fallbacks);
             case 'timeline':
                 return features.has('timeline.time_tag') ? node : foldTimeAndTag(node, path, fallbacks);
+            case 'calendar': {
+                if (features.has('facts.meter'))
+                    return node;
+                let changed = false;
+                const events = node.events.map((event, i) => {
+                    if (!event.details)
+                        return event;
+                    const at = `${path}.events[${i}].details`;
+                    const details = foldFactMeters(event.details, at, 'calendar', fallbacks);
+                    if (details === event.details)
+                        return event;
+                    changed = true;
+                    return { ...event, details };
+                });
+                return changed ? { ...node, events } : node;
+            }
             case 'markdown': {
                 if (features.has('markdown.links'))
                     return node;
@@ -501,6 +518,11 @@ export function negotiateTree(tree, set) {
                 delete next.actions;
         }
     }
+    if (tree.meta && features.has('header.meta') && !features.has('facts.meter')) {
+        const meta = foldFactMeters(tree.meta, 'meta', 'header', fallbacks);
+        if (meta !== tree.meta)
+            next = { ...next, meta };
+    }
     // Before the breadcrumbs fold, so a trail line (which says where the screen sits) lands above it.
     if ((tree.badges || tree.meta) && !features.has('header.meta')) {
         const line = headerFactsLine(tree, zone);
@@ -621,6 +643,21 @@ export function foldChoiceActions(node, path, fallbacks) {
     });
     return { ...node, choices };
 }
+/**
+ * Facts with each `meter` value as a `text` cell of its value label, for a client that draws no
+ * meter outside a table (`facts.meter`). The same array when there is none.
+ */
+function foldFactMeters(facts, path, type, fallbacks) {
+    let changed = false;
+    const folded = facts.map((fact, i) => {
+        if (fact.value.kind !== 'meter')
+            return fact;
+        changed = true;
+        fallbacks.push({ path: `${path}[${i}].value`, type, reason: 'facts.meter', as: 'folded' });
+        return { ...fact, value: { kind: 'text', value: meterLabel(fact.value) } };
+    });
+    return changed ? folded : facts;
+}
 /**
  * A section with its `action` moved into its body as a last `button`, for a client that does not
  * draw the action on the title line (`section.action`). Dropped when the section is full.
@@ -1091,6 +1128,8 @@ const TONE_WORD = {
     destructive: 'Error',
 };
 function cellText(cell, timeZone) {
+    if (cell.kind === 'meter')
+        return meterLabel(cell);
     return cell.kind === 'date' ? formatMoment(cell.value, 'datetime', timeZone) : cell.value;
 }
 /**

package/dist/schema.d.ts

@@ -250,8 +250,8 @@ export declare const cellSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>], "kind">;
 /**
  * A table cell: every value cell kind, plus `sparkline` and `meter`, and a
- * `secondary` line on `text` and `badge`. Table cells only: a `details` row, a
- * board card and a calendar entry keep `cellSchema`.
+ * `secondary` line on `text` and `badge`. Table cells only: a `details` row and a board card
+ * keep `cellSchema`; a calendar entry's details and the header's meta take `factCellSchema`.
  *
  * Neither a sparkline nor a meter is sortable by itself: the renderer never
  * reorders rows, so a sortable column of them sorts by whatever the module
@@ -320,6 +320,55 @@ export declare const tableCellSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>>;
     valueLabel: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "kind">;
+/**
+ * A fact's value: a value cell, or a meter ("Intake 3/5"). A calendar entry's `details` and the
+ * screen header's `meta` take it. A client that draws no meter there gets a `text` cell with the
+ * meter's value label (negotiate.ts, `facts.meter`).
+ */
+export declare const factCellSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"text">;
+    value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"badge">;
+    value: z.ZodString;
+    tone: z.ZodDefault<z.ZodEnum<{
+        default: "default";
+        success: "success";
+        warning: "warning";
+        destructive: "destructive";
+        info: "info";
+        accent: "accent";
+    }>>;
+    outline: z.ZodOptional<z.ZodBoolean>;
+    dot: z.ZodOptional<z.ZodBoolean>;
+    hint: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"date">;
+    value: z.ZodISODateTime;
+    dateFormat: z.ZodOptional<z.ZodObject<{
+        weekday: z.ZodOptional<z.ZodBoolean>;
+        year: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            always: "always";
+            never: "never";
+        }>>;
+        hour12: z.ZodOptional<z.ZodBoolean>;
+        locale: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"meter">;
+    value: z.ZodNumber;
+    max: z.ZodDefault<z.ZodNumber>;
+    tone: z.ZodDefault<z.ZodEnum<{
+        default: "default";
+        success: "success";
+        warning: "warning";
+        destructive: "destructive";
+        info: "info";
+        accent: "accent";
+    }>>;
+    valueLabel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
 /**
  * A file inside the module's own runtime: "patients/p-17/scan.jpg". Never a
  * URL. Core fetches it from the runtime's GET /screens/media/<path> with the
@@ -1698,6 +1747,19 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     hour12: z.ZodOptional<z.ZodBoolean>;
                     locale: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"meter">;
+                value: z.ZodNumber;
+                max: z.ZodDefault<z.ZodNumber>;
+                tone: z.ZodDefault<z.ZodEnum<{
+                    default: "default";
+                    success: "success";
+                    warning: "warning";
+                    destructive: "destructive";
+                    info: "info";
+                    accent: "accent";
+                }>>;
+                valueLabel: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>], "kind">;
         }, z.core.$strip>>>;
         actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -2090,6 +2152,19 @@ export declare const screenTreeSchema: z.ZodObject<{
                 hour12: z.ZodOptional<z.ZodBoolean>;
                 locale: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"meter">;
+            value: z.ZodNumber;
+            max: z.ZodDefault<z.ZodNumber>;
+            tone: z.ZodDefault<z.ZodEnum<{
+                default: "default";
+                success: "success";
+                warning: "warning";
+                destructive: "destructive";
+                info: "info";
+                accent: "accent";
+            }>>;
+            valueLabel: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>], "kind">;
     }, z.core.$strip>>>;
     breadcrumbs: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -2318,6 +2393,19 @@ export declare const actionResultSchema: z.ZodObject<{
                     hour12: z.ZodOptional<z.ZodBoolean>;
                     locale: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"meter">;
+                value: z.ZodNumber;
+                max: z.ZodDefault<z.ZodNumber>;
+                tone: z.ZodDefault<z.ZodEnum<{
+                    default: "default";
+                    success: "success";
+                    warning: "warning";
+                    destructive: "destructive";
+                    info: "info";
+                    accent: "accent";
+                }>>;
+                valueLabel: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>], "kind">;
         }, z.core.$strip>>>;
         breadcrumbs: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -2539,6 +2627,19 @@ export declare const jobStatusSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                         hour12: z.ZodOptional<z.ZodBoolean>;
                         locale: z.ZodOptional<z.ZodString>;
                     }, z.core.$strip>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"meter">;
+                    value: z.ZodNumber;
+                    max: z.ZodDefault<z.ZodNumber>;
+                    tone: z.ZodDefault<z.ZodEnum<{
+                        default: "default";
+                        success: "success";
+                        warning: "warning";
+                        destructive: "destructive";
+                        info: "info";
+                        accent: "accent";
+                    }>>;
+                    valueLabel: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>], "kind">;
             }, z.core.$strip>>>;
             breadcrumbs: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -2750,6 +2851,19 @@ export declare const screenLoadResponseSchema: z.ZodObject<{
                     hour12: z.ZodOptional<z.ZodBoolean>;
                     locale: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"meter">;
+                value: z.ZodNumber;
+                max: z.ZodDefault<z.ZodNumber>;
+                tone: z.ZodDefault<z.ZodEnum<{
+                    default: "default";
+                    success: "success";
+                    warning: "warning";
+                    destructive: "destructive";
+                    info: "info";
+                    accent: "accent";
+                }>>;
+                valueLabel: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>], "kind">;
         }, z.core.$strip>>>;
         breadcrumbs: z.ZodOptional<z.ZodArray<z.ZodObject<{

package/dist/schema.js

@@ -297,6 +297,17 @@ export const cellSchema = z.discriminatedUnion('kind', [
     badgeCellSchema,
     dateCellSchema,
 ]);
+/** A bar of `value` out of `max`, its value always written beside it. */
+const meterCellSchema = z.object({
+    kind: z.literal('meter'),
+    /** A value past `max` draws a full bar; say so in `valueLabel`. */
+    value: z.number().min(0),
+    max: z.number().positive().default(100),
+    /** The bar's colour. */
+    tone: tone.default('default'),
+    /** Drawn beside the bar: "72%", "36 of 50". Without it, the percent of `max`. */
+    valueLabel: z.string().min(1).max(40).optional(),
+});
 /**
  * A muted second line under a table cell's value, one line, cut short with an
  * ellipsis when it does not fit: an account's city and tier under its name, the
@@ -305,8 +316,8 @@ export const cellSchema = z.discriminatedUnion('kind', [
 const cellSecondary = z.string().min(1).max(200).optional();
 /**
  * A table cell: every value cell kind, plus `sparkline` and `meter`, and a
- * `secondary` line on `text` and `badge`. Table cells only: a `details` row, a
- * board card and a calendar entry keep `cellSchema`.
+ * `secondary` line on `text` and `badge`. Table cells only: a `details` row and a board card
+ * keep `cellSchema`; a calendar entry's details and the header's meta take `factCellSchema`.
  *
  * Neither a sparkline nor a meter is sortable by itself: the renderer never
  * reorders rows, so a sortable column of them sorts by whatever the module
@@ -330,16 +341,18 @@ export const tableCellSchema = z.discriminatedUnion('kind', [
         /** What the line says, in words: "Usage down 18% in 30 days". Required. */
         label: z.string().min(1).max(120),
     }),
-    z.object({
-        kind: z.literal('meter'),
-        /** A value past `max` draws a full bar; say so in `valueLabel`. */
-        value: z.number().min(0),
-        max: z.number().positive().default(100),
-        /** The bar's colour. */
-        tone: tone.default('default'),
-        /** Drawn beside the bar: "72%", "36 of 50". Without it, the percent of `max`. */
-        valueLabel: z.string().min(1).max(40).optional(),
-    }),
+    meterCellSchema,
+]);
+/**
+ * A fact's value: a value cell, or a meter ("Intake 3/5"). A calendar entry's `details` and the
+ * screen header's `meta` take it. A client that draws no meter there gets a `text` cell with the
+ * meter's value label (negotiate.ts, `facts.meter`).
+ */
+export const factCellSchema = z.discriminatedUnion('kind', [
+    textCellSchema,
+    badgeCellSchema,
+    dateCellSchema,
+    meterCellSchema,
 ]);
 /**
  * Cards to choose from, or a list of things to act on (a My Day action list). Each card is a
@@ -855,8 +868,9 @@ const calendarSchema = z
         /** Colours the entry: a confirmed visit, an unconfirmed one, a no-show. */
         tone: tone.default('default'),
         subtitle: z.string().max(200).optional(),
+        /** Drawn in the entry's panel. A `meter` value shows progress: "Intake 3/5". */
         details: z
-            .array(z.object({ label: z.string().min(1).max(80), value: cellSchema }))
+            .array(z.object({ label: z.string().min(1).max(80), value: factCellSchema }))
             .max(12)
             .optional(),
         actions: z.array(buttonSchema).max(4).optional(),
@@ -2496,12 +2510,13 @@ export const screenTreeSchema = z
     /**
      * Up to eight facts drawn as a compact row under the title (and its
      * description): ARR, renewal date, reps, NPS. Each value is a cell, so a
-     * `date` follows the screen's `timeZone` and `dateFormat` and a `badge`
-     * keeps its tone. A renderer draws them as a description list (term and
-     * value) that wraps on a narrow screen.
+     * `date` follows the screen's `timeZone` and `dateFormat`, a `badge`
+     * keeps its tone and a `meter` draws its bar ("Onboarding 3/5"). A renderer
+     * draws them as a description list (term and value) that wraps on a narrow
+     * screen.
      */
     meta: z
-        .array(z.object({ label: z.string().min(1).max(40), value: cellSchema }))
+        .array(z.object({ label: z.string().min(1).max(40), value: factCellSchema }))
         .min(1)
         .max(8)
         .optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/ui-sdk",
-  "version": "1.6.0-dev-20261027202014",
+  "version": "1.6.0-dev-20261027204717",
   "description": "Product screens for keemakr marketplace modules: a versioned, server-driven UI tree schema plus defineScreen() handlers. Module code never ships to the browser — keemakr-core validates the tree and renders it with platform components.",
   "license": "MIT",
   "type": "module",