@keemakr/ui-sdk 1.5.0 → 1.6.0-dev-20261026104018

package/README.md

@@ -120,3 +120,121 @@ calls the module runtime. Availability controls UI placement. Existing authentic
 still control who may enter Dashboard or a Kee client.
 
 See [`examples/campaigns`](./examples/campaigns) for one complete in-memory example.
+
+## 6. Check that each app can draw your screen
+
+An app parses a screen with the ui-sdk inside the sdk it was built with, frozen the day it shipped,
+and it does not draw every node. Before core sends a screen, it reads the app from `X-Kee-Client`
+and fits the screen to that app:
+
+- each node the app cannot draw becomes a `text` or `markdown` line that says what the node said
+  (a pager, a select or an alert button stops being pressable); times in that line are written in
+  the screen's `timeZone` (the Company's when your screen names none, a calendar's own first),
+  and in UTC only when there is no zone;
+- a value the app's parse refuses is folded to one it takes (an `info` or `accent` tone becomes
+  `default`; a date field's `min` and `max` are dropped), or the node becomes its text line;
+- a control whose safety the app would lose (a form's `submit.confirm`, a `disabled` flag) becomes
+  "Open this in the web app to finish this step.", or is dropped from its list of controls, so
+  nothing acts without asking.
+
+A table cell no released app draws yet (a `sparkline`, a `meter`, a `secondary` line under a text
+or badge cell) reaches every app as a plain text cell: the sparkline's `label`, the meter's
+`valueLabel` or percent, and no second line.
+
+Every value the app refuses is fitted, however many there are: a 500-row table with an `info`
+badge in each row reaches the app as a 500-row table with `default` badges. Only a screen nothing
+can fit becomes one line.
+
+| App                 | Parses with  | Draws                                                                                    |
+| ------------------- | ------------ | ---------------------------------------------------------------------------------------- |
+| web (0.1.0, 0.2.0)  | ui-sdk 1.4.0 | Every node, breadcrumbs, disabled buttons, row sections, every field kind, form confirms |
+| mobile 0.2.0        | ui-sdk 1.1.0 | The 15 nodes of 1.1.0, and none of those features                                        |
+| mobile 0.2.3 and on | ui-sdk 1.4.0 | The 15 nodes of 1.1.0, breadcrumbs, disabled buttons, every field kind, form confirms    |
+| desktop             | (floor)      | Renders no module screens                                                                |
+| no `X-Kee-Client`   | this package | Keemakr's own web app: every node, as sent                                               |
+
+On dev and stage (never in production), a web build that installed the @dev sdk channel says
+it parses this package (`web/0.2.0+abc1234.ui-current`) and gets every node as sent, so a new node
+can be tried on the dev web app before a stable sdk carries it (`CHANNEL_BUILDS`,
+`nodeSetForClaim`). Production web builds get the row above.
+
+`CLIENT_RELEASES` holds the full table. Test against it with the testkit:
+
+```ts
+import { assertDrawableOn, renderForClients } from '@keemakr/ui-sdk/testkit';
+
+// Fails, naming each node and client, when a target client would get a fallback.
+assertDrawableOn(await screen.load(ctx), ['web']);
+
+// Accept the fallback, and assert on the tree that client gets.
+const [mobile] = assertDrawableOn(tree, ['mobile'], { allowFallback: true });
+```
+
+With no targets, the testkit checks every app that renders module screens (web and mobile). An app
+named alone is checked at every release it has, so `['mobile']` covers mobile 0.2.0 as well as the
+newest build.
+
+## 7. Return the new screen from an action
+
+An action runs on your runtime, and by default the client then asks core to load the screen
+again: two more round trips before the person sees the change. An action can return the screen
+itself, as `load` would return it now, for the same screen and the same params the action ran
+with:
+
+```ts
+export default defineScreen({
+  load: async (ctx, params) => buildScreen(ctx, params),
+  actions: {
+    approve: async (ctx, input, params) => {
+      await approve(ctx, input);
+      return { toast: 'Approved', tree: await buildScreen(ctx, params) };
+    },
+  },
+});
+```
+
+- A client that knows `tree` draws it and does not call `load`. A client built before this field
+  ignores it and reloads, because `refresh` stays `true`. Send `tree` and leave `refresh` alone.
+- `navigate` wins over `tree`. To show another page of the screen, return `navigate`, as before.
+- Core sends the tree through the same checks as a loaded one: every node the client cannot draw
+  becomes a fallback (section 6), and the cards for `pending_request` slots come beside it in
+  `pendingRequests`. Test the tree with `assertDrawableOn(result.tree, ['web'])`.
+- A tree that does not validate is dropped, and the client reloads: the action has already run, so core does not fail it for a tree that only saves a reload.
+- When core answers a retried action from its log, it sends no tree, and the client reloads.
+
+## 8. Show a live count beside a menu entry
+
+A surface can show a count beside its name in the side menu ("My Day 21", "Accounts 8 red"). Opt
+in on the surface:
+
+```ts
+export default defineSurface({ label: 'Accounts', badge: true, availableOn: ['client'] });
+```
+
+Then answer `POST /screens/badges` in your screens channel, behind the same grant check as
+`/screens/:screen/load`. Core sends the opted-in surfaces the person may open, and keeps only
+those in your answer:
+
+```ts
+import { answerBadges, defineBadges } from '@keemakr/ui-sdk';
+
+const badges = defineBadges(async (ctx, surfaces) => ({
+  'my-day': { count: await countMyDay(ctx) },
+  accounts: { count: 8, tone: 'destructive', label: '8 red' },
+}));
+
+POST('/screens/badges', async (req) => {
+  const auth = await authorize(req);
+  if (!auth.ok) return auth.res;
+  const { status, body } = await answerBadges(badges, auth.ctx, await bodyOf(req));
+  return json(status, body);
+}),
+```
+
+- `count` is a whole number from 0 to 999999. A menu draws more than 999 as "999+", and draws
+  nothing for 0 unless you give a `label`.
+- `label` (up to 24 characters) is drawn in place of the count and read out after the name
+  ("Accounts, 8 red"). Put the meaning in it: `tone` only colours it.
+- Core asks about once a minute per person, waits about two seconds, and draws no badge when you
+  are slow, fail, or have no such route (404). Answer from stored state.
+- A person's own screen action makes their next menu read ask again sooner.

package/dist/badges.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Menu badges: a live count beside a side-menu entry ("My Day 21", "Accounts 8 red").
+ *
+ * A surface opts in with `badge: true` in its surface.ts. While a person's menu is open, core asks
+ * the module once for all of its opted-in surfaces that person may open:
+ *
+ *   POST {runtime}/screens/badges   { surfaces: ['my-day', 'accounts'] }
+ *   -> { badges: { 'my-day': { count: 21 }, accounts: { count: 8, tone: 'destructive', label: '8 red' } } }
+ *
+ * with the same grant a screen load carries (the person, their role, the install's scopes). Core
+ * waits about two seconds, keeps the answer for a minute per person, and draws no badge when the
+ * module is slow, fails or has no such route (404). One module's failure never touches another's
+ * badges or the menu itself.
+ *
+ * This file is the shared half: the module answers with `answerBadges`, core reads the answer with
+ * `parseScreenBadges`, and every menu writes and speaks a badge with `badgeText` and
+ * `badgeSpokenLabel`, so they all say the same.
+ */
+import { type SurfaceBadge, type SurfaceBadgeInput } from './schema.js';
+/** The most a menu draws as a bare count; above it the badge reads "999+". */
+export declare const BADGE_DISPLAY_MAX = 999;
+/**
+ * Answers the badges route. `surfaces` is what core asked for: the opted-in surfaces the person
+ * may open. Return a badge for each surface that has one; leave a surface out (or return null) for
+ * no badge. Answer from stored state, fast: core gives up after about two seconds.
+ */
+export type BadgesHandler<Ctx> = (ctx: Ctx, surfaces: string[]) => Record<string, SurfaceBadgeInput | null | undefined> | Promise<Record<string, SurfaceBadgeInput | null | undefined>>;
+/** Identity function, for inference: `export default defineBadges(async (ctx, surfaces) => …)`. */
+export declare function defineBadges<Ctx = unknown>(handler: BadgesHandler<Ctx>): BadgesHandler<Ctx>;
+/**
+ * Keep the badges core asked for that validate. Null when `payload` is not a badges answer at all.
+ * An entry that does not validate is dropped on its own; it never costs the other badges.
+ */
+export declare function parseScreenBadges(payload: unknown, asked: readonly string[]): Record<string, SurfaceBadge> | null;
+/**
+ * Run a badges handler for one request body, and return what to send back. Use it in the module's
+ * screens channel:
+ *
+ *   POST('/screens/badges', async (req) => {
+ *     const auth = await authorize(req);           // the same grant check as /screens/:screen/load
+ *     if (!auth.ok) return auth.res;
+ *     const { status, body } = await answerBadges(badges, auth.ctx, await bodyOf(req));
+ *     return json(status, body);
+ *   }),
+ *
+ * A badge that does not validate is dropped and named in the log, so the author sees it here.
+ */
+export declare function answerBadges<Ctx>(handler: BadgesHandler<Ctx>, ctx: Ctx, body: unknown): Promise<{
+    status: 200;
+    body: {
+        badges: Record<string, SurfaceBadge>;
+    };
+} | {
+    status: 400 | 500;
+    body: {
+        error: string;
+    };
+}>;
+/**
+ * The text a menu draws: the module's label when it gave one, else the count ("999+" above 999).
+ * Null when there is nothing to draw: a count of 0 with no label.
+ */
+export declare function badgeText(badge: Pick<SurfaceBadge, 'count' | 'label'>): string | null;
+/** What a screen reader says for the menu entry: "Accounts, 8 red", "My Day, 21". */
+export declare function badgeSpokenLabel(surfaceLabel: string, badge: Pick<SurfaceBadge, 'count' | 'label'> | null | undefined): string;

package/dist/badges.js

@@ -0,0 +1,96 @@
+/**
+ * Menu badges: a live count beside a side-menu entry ("My Day 21", "Accounts 8 red").
+ *
+ * A surface opts in with `badge: true` in its surface.ts. While a person's menu is open, core asks
+ * the module once for all of its opted-in surfaces that person may open:
+ *
+ *   POST {runtime}/screens/badges   { surfaces: ['my-day', 'accounts'] }
+ *   -> { badges: { 'my-day': { count: 21 }, accounts: { count: 8, tone: 'destructive', label: '8 red' } } }
+ *
+ * with the same grant a screen load carries (the person, their role, the install's scopes). Core
+ * waits about two seconds, keeps the answer for a minute per person, and draws no badge when the
+ * module is slow, fails or has no such route (404). One module's failure never touches another's
+ * badges or the menu itself.
+ *
+ * This file is the shared half: the module answers with `answerBadges`, core reads the answer with
+ * `parseScreenBadges`, and every menu writes and speaks a badge with `badgeText` and
+ * `badgeSpokenLabel`, so they all say the same.
+ */
+import { BADGE_COUNT_MAX, screenBadgesRequestSchema, surfaceBadgeSchema, } from './schema.js';
+/** The most a menu draws as a bare count; above it the badge reads "999+". */
+export const BADGE_DISPLAY_MAX = 999;
+/** Identity function, for inference: `export default defineBadges(async (ctx, surfaces) => …)`. */
+export function defineBadges(handler) {
+    return handler;
+}
+/**
+ * Keep the badges core asked for that validate. Null when `payload` is not a badges answer at all.
+ * An entry that does not validate is dropped on its own; it never costs the other badges.
+ */
+export function parseScreenBadges(payload, asked) {
+    if (typeof payload !== 'object' || payload === null)
+        return null;
+    const badges = payload.badges;
+    if (typeof badges !== 'object' || badges === null || Array.isArray(badges))
+        return null;
+    const out = {};
+    for (const key of new Set(asked)) {
+        if (!Object.prototype.hasOwnProperty.call(badges, key))
+            continue;
+        const parsed = surfaceBadgeSchema.safeParse(badges[key]);
+        if (parsed.success)
+            out[key] = parsed.data;
+    }
+    return out;
+}
+/**
+ * Run a badges handler for one request body, and return what to send back. Use it in the module's
+ * screens channel:
+ *
+ *   POST('/screens/badges', async (req) => {
+ *     const auth = await authorize(req);           // the same grant check as /screens/:screen/load
+ *     if (!auth.ok) return auth.res;
+ *     const { status, body } = await answerBadges(badges, auth.ctx, await bodyOf(req));
+ *     return json(status, body);
+ *   }),
+ *
+ * A badge that does not validate is dropped and named in the log, so the author sees it here.
+ */
+export async function answerBadges(handler, ctx, body) {
+    const request = screenBadgesRequestSchema.safeParse(body ?? {});
+    if (!request.success)
+        return { status: 400, body: { error: 'invalid badges request' } };
+    const surfaces = request.data.surfaces;
+    let answered;
+    try {
+        answered = (await handler(ctx, surfaces)) ?? {};
+    }
+    catch (e) {
+        console.error('[screens] badges handler threw:', e);
+        return { status: 500, body: { error: 'badges failed' } };
+    }
+    const badges = parseScreenBadges({ badges: answered }, surfaces) ?? {};
+    for (const key of surfaces) {
+        if (answered[key] != null && !badges[key]) {
+            console.warn(`[screens] badges: the badge for "${key}" does not validate and was dropped ` +
+                `(count: a whole number from 0 to ${BADGE_COUNT_MAX}; label: 1 to 24 characters).`);
+        }
+    }
+    return { status: 200, body: { badges } };
+}
+/**
+ * The text a menu draws: the module's label when it gave one, else the count ("999+" above 999).
+ * Null when there is nothing to draw: a count of 0 with no label.
+ */
+export function badgeText(badge) {
+    if (badge.label)
+        return badge.label;
+    if (badge.count <= 0)
+        return null;
+    return badge.count > BADGE_DISPLAY_MAX ? `${BADGE_DISPLAY_MAX}+` : String(badge.count);
+}
+/** What a screen reader says for the menu entry: "Accounts, 8 red", "My Day, 21". */
+export function badgeSpokenLabel(surfaceLabel, badge) {
+    const text = badge ? badgeText(badge) : null;
+    return text ? `${surfaceLabel}, ${text}` : surfaceLabel;
+}

package/dist/build.js

@@ -27,7 +27,7 @@ function literalValue(expression) {
         return false;
     if (ts.isArrayLiteralExpression(value))
         return value.elements.map(literalValue);
-    throw new Error('surface.ts values must be string or array literals');
+    throw new Error('surface.ts values must be string, boolean or array literals');
 }
 /** A dataset declaration also takes numbers and objects. Still literal only. */
 function declarationValue(expression) {
@@ -177,7 +177,7 @@ async function readSurfaceDefinition(path) {
         }
         raw[name.text] = literalValue(property.initializer);
     }
-    const allowed = new Set(['label', 'icon', 'description', 'availableOn']);
+    const allowed = new Set(['label', 'icon', 'description', 'badge', 'availableOn']);
     for (const key of Object.keys(raw)) {
         if (!allowed.has(key))
             throw new Error(`${path}: unknown surface property "${key}"`);

package/dist/cells.d.ts

@@ -0,0 +1,31 @@
+type MeterCell = {
+    kind: 'meter';
+    value: number;
+    max: number;
+    valueLabel?: string;
+};
+/** How full a meter's bar is, 0 to 100. A value past `max` is a full bar. */
+export declare function meterPercent(cell: Pick<MeterCell, 'value' | 'max'>): number;
+/**
+ * The text drawn beside a meter's bar, always: its `valueLabel`, or the percent of `max`
+ * ("120%" when past it, so the text says what the full bar cannot).
+ */
+export declare function meterLabel(cell: Pick<MeterCell, 'value' | 'max' | 'valueLabel'>): string;
+type AnyCell = {
+    kind: string;
+} & Record<string, unknown>;
+/**
+ * A table cell as a client that draws no sparkline, meter or second line gets it (the
+ * `table.cells` feature in negotiate.ts):
+ *   sparkline         -> text: its `label`
+ *   meter             -> text: its `valueLabel`, or the percent of `max`
+ *   text or badge     -> the same cell, its `secondary` line dropped
+ * Any other cell is returned as is.
+ */
+export declare function foldTableCell<C extends AnyCell>(cell: C): C | {
+    kind: 'text';
+    value: string;
+};
+/** True when a client without `table.cells` would get this cell changed. */
+export declare function isNewerTableCell(cell: AnyCell): boolean;
+export {};

package/dist/cells.js

@@ -0,0 +1,45 @@
+// Table cells that draw more than a word: a sparkline, a meter, a second line (UI-09).
+//
+// Every renderer says the same words for them, so they live here: the meter's text beside its
+// bar, how full the bar is, and the plain text cell a client that cannot draw them gets.
+/** How full a meter's bar is, 0 to 100. A value past `max` is a full bar. */
+export function meterPercent(cell) {
+    if (!(cell.max > 0))
+        return 0;
+    return Math.min(100, Math.max(0, (cell.value / cell.max) * 100));
+}
+/**
+ * The text drawn beside a meter's bar, always: its `valueLabel`, or the percent of `max`
+ * ("120%" when past it, so the text says what the full bar cannot).
+ */
+export function meterLabel(cell) {
+    if (cell.valueLabel)
+        return cell.valueLabel;
+    if (!(cell.max > 0))
+        return `${cell.value}`;
+    return `${Math.round((cell.value / cell.max) * 100)}%`;
+}
+/**
+ * A table cell as a client that draws no sparkline, meter or second line gets it (the
+ * `table.cells` feature in negotiate.ts):
+ *   sparkline         -> text: its `label`
+ *   meter             -> text: its `valueLabel`, or the percent of `max`
+ *   text or badge     -> the same cell, its `secondary` line dropped
+ * Any other cell is returned as is.
+ */
+export function foldTableCell(cell) {
+    if (cell.kind === 'sparkline')
+        return { kind: 'text', value: String(cell.label) };
+    if (cell.kind === 'meter') {
+        return { kind: 'text', value: meterLabel(cell) };
+    }
+    if ('secondary' in cell) {
+        const { secondary: _secondary, ...rest } = cell;
+        return rest;
+    }
+    return cell;
+}
+/** True when a client without `table.cells` would get this cell changed. */
+export function isNewerTableCell(cell) {
+    return cell.kind === 'sparkline' || cell.kind === 'meter' || 'secondary' in cell;
+}

package/dist/chart.d.ts

@@ -0,0 +1,20 @@
+/** The most categories a chart takes, and so the most values in each series. */
+export declare const CHART_POINTS_MAX = 120;
+/**
+ * `limit` evenly spaced indices out of `count`, first and last included, in order. All of them
+ * when `count` is not above `limit`.
+ */
+export declare function thinnedIndices(count: number, limit: number): number[];
+/** The chart fields that hold one entry per category. */
+interface ChartPoints {
+    categories: string[];
+    series: Array<{
+        values: number[];
+    }>;
+}
+/**
+ * The chart with at most `limit` categories, each series keeping the value of every category it
+ * keeps. Everything else on the chart is kept as it is. The input is not touched.
+ */
+export declare function thinChart<T extends ChartPoints>(chart: T, limit: number): T;
+export {};

package/dist/chart.js

@@ -0,0 +1,38 @@
+// How many points a chart series holds, and how a longer chart is cut down for an app that takes
+// fewer (UI-05).
+//
+// A chart takes up to 120 points per series: 90 days plus margin, so an adoption screen can show
+// DAU, WAU and MAU over the last 90 days. Released apps parse with ui-sdk 1.1.0 or 1.4.0, which
+// refuse more than 50, and a refused chart would cost the app the whole chart. So core sends such
+// an app the chart thinned to 50 evenly spaced points instead (conform.ts). The first and the last
+// point are always kept: the start of the range and today.
+/** The most categories a chart takes, and so the most values in each series. */
+export const CHART_POINTS_MAX = 120;
+/**
+ * `limit` evenly spaced indices out of `count`, first and last included, in order. All of them
+ * when `count` is not above `limit`.
+ */
+export function thinnedIndices(count, limit) {
+    if (count <= limit)
+        return Array.from({ length: count }, (_, index) => index);
+    if (limit <= 1)
+        return [count - 1];
+    return Array.from({ length: limit }, (_, slot) => Math.round((slot * (count - 1)) / (limit - 1)));
+}
+/**
+ * The chart with at most `limit` categories, each series keeping the value of every category it
+ * keeps. Everything else on the chart is kept as it is. The input is not touched.
+ */
+export function thinChart(chart, limit) {
+    if (chart.categories.length <= limit)
+        return chart;
+    const keep = thinnedIndices(chart.categories.length, limit);
+    return {
+        ...chart,
+        categories: keep.map((index) => chart.categories[index]),
+        series: chart.series.map((series) => ({
+            ...series,
+            values: keep.map((index) => series.values[index]),
+        })),
+    };
+}

package/dist/conform.d.ts

@@ -0,0 +1,21 @@
+import type { z } from 'zod';
+import type { Fallback } from './negotiate.js';
+type Json = Record<string, unknown>;
+export interface ConformOptions {
+    /** The node's own fallback (negotiate.ts `fallbackNode`). */
+    fallback: (node: unknown) => Json;
+    /** The line that replaces a control whose safety field this app would lose. */
+    safetyText: string;
+    /** The line that replaces a node whose own fallback this app still refuses. */
+    genericText: string;
+}
+export interface Conformed {
+    tree: Json;
+    fallbacks: Fallback[];
+}
+/**
+ * The tree as `parser` takes it, with every change listed. The input is not touched. Each change
+ * keeps the tree valid against this package's own schema.
+ */
+export declare function conformTree(tree: unknown, parser: z.ZodType, options: ConformOptions): Conformed;
+export {};