@keemakr/ui-sdk 1.6.0-dev-20261029104555 → 1.6.0-dev-20261029112042

package/dist/negotiate.d.ts

@@ -73,6 +73,10 @@ import type { ChatPress, ScreenRootNode, ScreenTree } from './schema.js';
  *     published release; core's own renderer draws it). An older parse strips it without a sign,
  *     so without it the bar's legend ("Red 8 · Amber 13 · Green 29") is written into the tile's
  *     `hint`, after any hint it had, and the bar is dropped.
+ *   - `stat.sparkline`: a stat tile's `sparkline`, a small trend line in the tile (newer than any
+ *     published release; core's own renderer draws it). An older parse strips it without a sign,
+ *     so without it the line is dropped on purpose and the fallback list says so. The tile keeps
+ *     its number; the line carried no exact value.
  *   - `section.action`: a section's `action`, a press drawn at the right end of its title line
  *     (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
@@ -94,7 +98,7 @@ import type { ChatPress, ScreenRootNode, ScreenTree } from './schema.js';
  *     button included (never left as muted text, which would read as a label), and a row, card,
  *     entry or image stays but is no longer pressable.
  */
-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' | 'form.show_when' | 'press.focus';
+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' | 'stat.sparkline' | 'section.action' | 'facts.meter' | 'form.show_when' | 'press.focus';
 /** 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". */
@@ -131,7 +135,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", "document"];
-        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", "form.show_when", "press.focus"];
+        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", "stat.sparkline", "section.action", "facts.meter", "form.show_when", "press.focus"];
     };
 };
 export type UiSdkSnapshot = keyof typeof UI_SDK_SNAPSHOTS;

package/dist/negotiate.js

@@ -52,6 +52,7 @@ const ALL_FEATURES = [
     'edit.inline',
     'timeline.time_tag',
     'stat.bar',
+    'stat.sparkline',
     'section.action',
     'facts.meter',
     'form.show_when',
@@ -407,10 +408,21 @@ export function negotiateTree(tree, set) {
                 return changed ? { ...form, fields } : form;
             }
             case 'stat': {
-                if (!node.bar || features.has('stat.bar'))
-                    return node;
+                let stat = node;
+                if (stat.sparkline && !features.has('stat.sparkline')) {
+                    fallbacks.push({
+                        path: `${path}.sparkline`,
+                        type: 'stat',
+                        reason: 'stat.sparkline',
+                        as: 'dropped',
+                    });
+                    const { sparkline: _sparkline, ...rest } = stat;
+                    stat = rest;
+                }
+                if (!stat.bar || features.has('stat.bar'))
+                    return stat;
                 fallbacks.push({ path, type: 'stat', reason: 'stat.bar', as: 'folded' });
-                const { bar, ...tile } = node;
+                const { bar, ...tile } = stat;
                 const { legend } = stackedBarParts({ label: node.label, ...bar });
                 return {
                     ...tile,

package/dist/schema.d.ts

@@ -318,7 +318,6 @@ export declare const tableCellSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         locale: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
-    kind: z.ZodLiteral<"sparkline">;
     values: z.ZodArray<z.ZodNumber>;
     tone: z.ZodDefault<z.ZodEnum<{
         default: "default";
@@ -329,6 +328,7 @@ export declare const tableCellSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         accent: "accent";
     }>>;
     label: z.ZodString;
+    kind: z.ZodLiteral<"sparkline">;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"meter">;
     value: z.ZodNumber;
@@ -525,6 +525,18 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strip>>;
         max: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    sparkline: z.ZodOptional<z.ZodObject<{
+        values: z.ZodArray<z.ZodNumber>;
+        tone: z.ZodDefault<z.ZodEnum<{
+            default: "default";
+            success: "success";
+            warning: "warning";
+            destructive: "destructive";
+            info: "info";
+            accent: "accent";
+        }>>;
+        label: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"button">;
     label: z.ZodString;
@@ -757,7 +769,6 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 locale: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>;
         }, z.core.$strip>, z.ZodObject<{
-            kind: z.ZodLiteral<"sparkline">;
             values: z.ZodArray<z.ZodNumber>;
             tone: z.ZodDefault<z.ZodEnum<{
                 default: "default";
@@ -768,6 +779,7 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 accent: "accent";
             }>>;
             label: z.ZodString;
+            kind: z.ZodLiteral<"sparkline">;
         }, z.core.$strip>, z.ZodObject<{
             kind: z.ZodLiteral<"meter">;
             value: z.ZodNumber;
@@ -931,6 +943,18 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     }, z.core.$strip>>;
                     max: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>>;
+                sparkline: z.ZodOptional<z.ZodObject<{
+                    values: z.ZodArray<z.ZodNumber>;
+                    tone: z.ZodDefault<z.ZodEnum<{
+                        default: "default";
+                        success: "success";
+                        warning: "warning";
+                        destructive: "destructive";
+                        info: "info";
+                        accent: "accent";
+                    }>>;
+                    label: z.ZodString;
+                }, z.core.$strip>>;
             }, z.core.$strip>, z.ZodObject<{
                 type: z.ZodLiteral<"button">;
                 label: z.ZodString;

package/dist/schema.js

@@ -337,6 +337,15 @@ const meterCellSchema = z.object({
  * reason under a health badge.
  */
 const cellSecondary = z.string().min(1).max(200).optional();
+/** A trend line with no axis: a table's `sparkline` cell, or a stat tile's `sparkline`. */
+const sparklineFields = {
+    /** The points, oldest first: 30 days of usage. */
+    values: z.array(z.number()).min(2).max(60),
+    /** The line's colour. */
+    tone: tone.default('default'),
+    /** What the line says, in words: "Usage down 18% in 30 days". Required. */
+    label: z.string().min(1).max(120),
+};
 /**
  * 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 and a board card
@@ -355,15 +364,7 @@ export const tableCellSchema = z.discriminatedUnion('kind', [
     textCellSchema.extend({ secondary: cellSecondary }),
     badgeCellSchema.extend({ secondary: cellSecondary }),
     dateCellSchema,
-    z.object({
-        kind: z.literal('sparkline'),
-        /** The points, oldest first: 30 days of usage. */
-        values: z.array(z.number()).min(2).max(60),
-        /** The line's colour. */
-        tone: tone.default('default'),
-        /** 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('sparkline'), ...sparklineFields }),
     meterCellSchema,
 ]);
 /**
@@ -1585,22 +1586,27 @@ const markdownSchema = z.object({
 });
 /**
  * A number with its label: a KPI tile. All of `tone`, `trend`, `onPress`,
- * `selected` and `bar` are optional; a renderer that does not know them draws `label`,
+ * `selected`, `bar` and `sparkline` are optional; a renderer that does not know them draws `label`,
  * `value` and `hint` as before.
  *
- * - `tone` colours the tile for a red, amber or green count. The label must
- *   still say what the number is: colour is never the only signal.
+ * - `tone` colours the tile for a red, amber or green count: a coloured edge, and
+ *   the label drawn as a tinted pill with a dot. The label must still say what
+ *   the number is: colour is never the only signal.
  * - `trend` is the change since the last period, drawn as an arrow and its
  *   text ("↑ +12% vs last week"). `good` says which way is good, so a falling
- *   complaint count reads green; without it the trend is neutral.
+ *   complaint count reads green; without it the trend is neutral. A value that
+ *   starts with its own arrow ("▲ 2 pts") is drawn as written, with no second one.
  * - `onPress` makes the tile a button: open the list behind the number, or
  *   filter the list below it.
  * - `selected` is for a tile that filters: set it on every tile of the group,
- *   true on the active one. It is drawn as pressed and said as pressed.
+ *   true on the active one. It is drawn as pressed, ringed in the tile's tone,
+ *   and said as pressed.
  * - `bar` is a small bar split into coloured parts under the value, the shape
  *   of a `stacked_bar`'s segments: Book health 50, Red 8 · Amber 13 · Green 29.
  *   The stat's `label` names it. A segment takes no press: the tile is one
  *   control, and `onPress` is its press.
+ * - `sparkline` is a small trend line in the tile, the shape of a table's
+ *   sparkline cell: 30 days of usage. Its `label` says what the line says.
  */
 const statSchema = z
     .object({
@@ -1629,6 +1635,7 @@ const statSchema = z
         max: z.number().finite().positive().optional(),
     })
         .optional(),
+    sparkline: z.object(sparklineFields).optional(),
 })
     .superRefine((node, ctx) => {
     if (node.bar)

package/dist/stat.d.ts

@@ -7,8 +7,11 @@ export interface StatTrendLike {
 /** Whether a trend is good news, bad news, or neither. */
 export type StatTrendFeel = 'good' | 'bad' | 'neutral';
 export interface StatTrend {
-    /** The arrow drawn before the text: ↑, ↓ or →. Never the only signal. */
-    arrow: '↑' | '↓' | '→';
+    /**
+     * The arrow drawn before the text: ↑, ↓ or →. Never the only signal. Empty when the value
+     * starts with an arrow of its own ("▲ 2 pts"): the value is drawn as written.
+     */
+    arrow: '↑' | '↓' | '→' | '';
     /** good: drawn in the success colour; bad: in the destructive colour; neutral: muted. */
     feel: StatTrendFeel;
     /** What is drawn after the arrow: "+12% vs last week". */
@@ -19,6 +22,7 @@ export interface StatTrend {
 /**
  * How to draw a tile's trend. A flat trend, or one without `good`, is neutral.
  * The spoken text drops a leading sign from the value ("+12%" is said "up 12%"),
- * because the direction already says it.
+ * because the direction already says it. A value that starts with its own arrow
+ * ("▲ 2 pts") gets no second one, and its arrow is not said either.
  */
 export declare function statTrend(trend: StatTrendLike): StatTrend;

package/dist/stat.js

@@ -4,10 +4,13 @@
 // reads green on web and red on the phone.
 const ARROW = { up: '↑', down: '↓', flat: '→' };
 const WORD = { up: 'up', down: 'down', flat: 'no change' };
+/** An arrow the author wrote at the start of the value ("▲ 2 pts"), and the space after it. */
+const OWN_ARROW = /^[↑↓→←↗↘▲▼△▽▴▾⬆⬇]\s*/u;
 /**
  * How to draw a tile's trend. A flat trend, or one without `good`, is neutral.
  * The spoken text drops a leading sign from the value ("+12%" is said "up 12%"),
- * because the direction already says it.
+ * because the direction already says it. A value that starts with its own arrow
+ * ("▲ 2 pts") gets no second one, and its arrow is not said either.
  */
 export function statTrend(trend) {
     const feel = !trend.good || trend.direction === 'flat'
@@ -16,10 +19,11 @@ export function statTrend(trend) {
             ? 'good'
             : 'bad';
     const text = trend.label ? `${trend.value} ${trend.label}` : trend.value;
-    const amount = trend.value.replace(/^[+\-−]\s*/, '');
+    const ownArrow = OWN_ARROW.test(trend.value);
+    const amount = trend.value.replace(OWN_ARROW, '').replace(/^[+\-−]\s*/, '');
     const said = [WORD[trend.direction], amount, trend.label].filter(Boolean).join(' ');
     return {
-        arrow: ARROW[trend.direction],
+        arrow: ownArrow ? '' : ARROW[trend.direction],
         feel,
         text,
         spoken: feel === 'neutral' ? said : `${said}, ${feel}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/ui-sdk",
-  "version": "1.6.0-dev-20261029104555",
+  "version": "1.6.0-dev-20261029112042",
   "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",