@keemakr/ui-sdk 1.3.0 → 1.4.0-dev-20261012081643

package/dist/nodes.d.ts

@@ -1,6 +1,6 @@
 import type { ScreenRootNode } from './schema.js';
 /** Every node type the root union admits (KEE-574 item 3). */
-export declare const KNOWN_NODE_TYPES: readonly ["heading", "text", "markdown", "stat", "button", "form", "table", "timeline", "pending_request", "pending_requests", "choice_cards", "progress", "chart", "pagination", "select", "alert", "details", "timestamp", "section", "tabs"];
+export declare const KNOWN_NODE_TYPES: readonly ["heading", "text", "markdown", "stat", "button", "form", "table", "timeline", "pending_request", "pending_requests", "choice_cards", "progress", "chart", "pagination", "select", "alert", "details", "timestamp", "divider", "board", "section", "tabs"];
 export type KnownNodeType = (typeof KNOWN_NODE_TYPES)[number];
 /**
  * The node types that hold child nodes. `section` mounts its children

package/dist/nodes.js

@@ -28,6 +28,8 @@ export const KNOWN_NODE_TYPES = [
     'alert',
     'details',
     'timestamp',
+    'divider',
+    'board',
     'section',
     'tabs',
 ];

package/dist/schema.d.ts

@@ -42,6 +42,8 @@ export declare const buttonSchema: z.ZodObject<{
         secondary: "secondary";
     }>>;
     disabled: z.ZodDefault<z.ZodBoolean>;
+    hint: z.ZodOptional<z.ZodString>;
+    disabledReason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /** A table cell. Dates are ISO 8601; core formats them tenant-locale-aware. */
 export declare const cellSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -94,6 +96,8 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         secondary: "secondary";
     }>>;
     disabled: z.ZodDefault<z.ZodBoolean>;
+    hint: z.ZodOptional<z.ZodString>;
+    disabledReason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"form">;
     key: z.ZodString;
@@ -185,6 +189,8 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     secondary: "secondary";
                 }>>;
                 disabled: z.ZodDefault<z.ZodBoolean>;
+                hint: z.ZodOptional<z.ZodString>;
+                disabledReason: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>], "type">>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
@@ -287,6 +293,12 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     }, z.core.$strip>], "kind">;
     disabled: z.ZodDefault<z.ZodBoolean>;
+    labelPlacement: z.ZodDefault<z.ZodEnum<{
+        above: "above";
+        inline: "inline";
+    }>>;
+    hint: z.ZodOptional<z.ZodString>;
+    disabledReason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"alert">;
     tone: z.ZodDefault<z.ZodEnum<{
@@ -316,6 +328,8 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             secondary: "secondary";
         }>>;
         disabled: z.ZodDefault<z.ZodBoolean>;
+        hint: z.ZodOptional<z.ZodString>;
+        disabledReason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"details">;
@@ -349,6 +363,52 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         relative: "relative";
     }>>;
     label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"divider">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"board">;
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        tone: z.ZodDefault<z.ZodEnum<{
+            success: "success";
+            default: "default";
+            warning: "warning";
+            destructive: "destructive";
+        }>>;
+        cards: z.ZodArray<z.ZodObject<{
+            key: z.ZodString;
+            title: z.ZodString;
+            subtitle: z.ZodOptional<z.ZodString>;
+            values: z.ZodOptional<z.ZodArray<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<{
+                    success: "success";
+                    default: "default";
+                    warning: "warning";
+                    destructive: "destructive";
+                }>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"date">;
+                value: z.ZodISODateTime;
+            }, z.core.$strip>], "kind">>>;
+            onPress: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"action">;
+                action: z.ZodString;
+                input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+                confirm: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"navigate">;
+                screen: z.ZodString;
+                params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$strip>], "kind">>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    empty: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>], "type">;
 type LeafScreenNode = z.infer<typeof leafNodeSchema>;
 type LeafScreenNodeInput = z.input<typeof leafNodeSchema>;
@@ -356,16 +416,18 @@ export type ScreenNode = LeafScreenNode | {
     type: 'section';
     title?: string;
     description?: string;
-    layout: 'stack' | 'grid';
+    layout: 'stack' | 'grid' | 'row';
     columns: number;
+    scroll: boolean;
     children: ScreenNode[];
 };
 type ScreenNodeInput = LeafScreenNodeInput | {
     type: 'section';
     title?: string;
     description?: string;
-    layout: 'stack' | 'grid';
-    columns: number;
+    layout: 'stack' | 'grid' | 'row';
+    columns?: number;
+    scroll?: boolean;
     children: ScreenNodeInput[];
 };
 /**
@@ -437,6 +499,8 @@ export declare const screenTreeSchema: z.ZodObject<{
             secondary: "secondary";
         }>>;
         disabled: z.ZodDefault<z.ZodBoolean>;
+        hint: z.ZodOptional<z.ZodString>;
+        disabledReason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     children: z.ZodArray<z.ZodType<ScreenRootNode, ScreenRootNodeInput, z.core.$ZodTypeInternals<ScreenRootNode, ScreenRootNodeInput>>>;
     refreshSeconds: z.ZodOptional<z.ZodNumber>;
@@ -485,6 +549,8 @@ export declare const screenLoadResponseSchema: z.ZodObject<{
                 secondary: "secondary";
             }>>;
             disabled: z.ZodDefault<z.ZodBoolean>;
+            hint: z.ZodOptional<z.ZodString>;
+            disabledReason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         children: z.ZodArray<z.ZodType<ScreenRootNode, ScreenRootNodeInput, z.core.$ZodTypeInternals<ScreenRootNode, ScreenRootNodeInput>>>;
         refreshSeconds: z.ZodOptional<z.ZodNumber>;

package/dist/schema.js

@@ -41,6 +41,15 @@ export const buttonSchema = z.object({
     variant: z.enum(['primary', 'secondary', 'destructive']).default('secondary'),
     /** Shown but not pressable — a Next button on the last page, an action not yet available. */
     disabled: z.boolean().default(false),
+    /** A short explanation shown next to the button on hover or keyboard focus. */
+    hint: z.string().min(1).max(200).optional(),
+    /**
+     * Why the button is disabled, shown under it while `disabled` is true:
+     * "Kee stopped because the patient asked for a person". Ignored when the
+     * button is enabled. A greyed control that does not say why leaves the
+     * reader guessing.
+     */
+    disabledReason: z.string().min(1).max(200).optional(),
 });
 /** A table cell. Dates are ISO 8601; core formats them tenant-locale-aware. */
 export const cellSchema = z.discriminatedUnion('kind', [
@@ -164,6 +173,16 @@ const selectSchema = z
         .max(100),
     onChange: pressSchema,
     disabled: z.boolean().default(false),
+    /**
+     * Where the label sits. `above` (the default) is a form field. `inline` puts
+     * the label inside the control on the same line, so a row of filters is one
+     * line tall: "Status: Open".
+     */
+    labelPlacement: z.enum(['above', 'inline']).default('above'),
+    /** A short explanation shown next to the select on hover or keyboard focus. */
+    hint: z.string().min(1).max(200).optional(),
+    /** Why the select is disabled, shown under it while `disabled` is true. */
+    disabledReason: z.string().min(1).max(200).optional(),
 })
     .superRefine((node, ctx) => {
     if (node.value !== undefined && !node.options.some((option) => option.value === node.value)) {
@@ -214,6 +233,76 @@ const timestampSchema = z.object({
     /** Shown before the time, muted: "Last contacted". */
     label: z.string().max(80).optional(),
 });
+/**
+ * Cards in columns by stage: a sales pipeline, installs by status, accounts by
+ * health. A card carries a title, an optional subtitle, and up to 3 values that
+ * reuse the table cell kinds (a `date` shows in the viewer's zone, a `badge`
+ * keeps its tone). A card with `onPress` opens a record or calls an action.
+ * Each column shows its card count. Moving a card between columns is not part
+ * of this block yet: call an action from the record instead.
+ */
+const boardSchema = z
+    .object({
+    type: z.literal('board'),
+    columns: z
+        .array(z.object({
+        key: slug,
+        label: z.string().min(1).max(40),
+        /** Colours the column's count: an at-risk stage, a done stage. */
+        tone: tone.default('default'),
+        cards: z
+            .array(z.object({
+            key: z.string().min(1).max(128),
+            title: z.string().min(1).max(120),
+            subtitle: z.string().max(200).optional(),
+            values: z.array(cellSchema).max(3).optional(),
+            onPress: pressSchema.optional(),
+        }))
+            .max(100),
+    }))
+        .min(1)
+        .max(8),
+    /** Shown in a column that has no cards. */
+    empty: z.string().min(1).max(80).default('Nothing here'),
+})
+    .superRefine((node, ctx) => {
+    const columnKeys = new Set();
+    const cardKeys = new Set();
+    let cards = 0;
+    for (const [c, column] of node.columns.entries()) {
+        if (columnKeys.has(column.key)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['columns', c, 'key'],
+                message: `duplicate column key "${column.key}"`,
+            });
+        }
+        columnKeys.add(column.key);
+        for (const [i, card] of column.cards.entries()) {
+            if (cardKeys.has(card.key)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['columns', c, 'cards', i, 'key'],
+                    message: `duplicate card key "${card.key}"`,
+                });
+            }
+            cardKeys.add(card.key);
+        }
+        cards += column.cards.length;
+    }
+    if (cards > 500) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['columns'],
+            message: `a board holds at most 500 cards, got ${cards}`,
+        });
+    }
+});
+/**
+ * A horizontal line that says where one part of a screen ends and the next
+ * begins. It carries no content. Use a `section` when the parts need a title.
+ */
+const dividerSchema = z.object({ type: z.literal('divider') });
 const headingSchema = z.object({ type: z.literal('heading'), text: z.string().max(120) });
 const textSchema = z.object({
     type: z.literal('text'),
@@ -337,6 +426,8 @@ const leafNodeSchema = z.discriminatedUnion('type', [
     alertSchema,
     detailsSchema,
     timestampSchema,
+    dividerSchema,
+    boardSchema,
 ]);
 const MAX_SECTION_DEPTH = 8;
 const nodeSchemas = new Map();
@@ -345,8 +436,20 @@ const sectionBranch = (children) => z.object({
     type: z.literal('section'),
     title: z.string().max(120).optional(),
     description: z.string().max(300).optional(),
-    layout: z.enum(['stack', 'grid']),
-    columns: z.number().int().min(1).max(4),
+    /**
+     * `stack`: one child per line. `grid`: `columns` equal columns. `row`:
+     * children side by side at their own width, wrapping on a narrow screen,
+     * for a filter bar or a pair of buttons that belong together.
+     */
+    layout: z.enum(['stack', 'grid', 'row']),
+    /** Used by `grid` only. */
+    columns: z.number().int().min(1).max(4).default(1),
+    /**
+     * The section scrolls inside itself at a height the renderer chooses, so
+     * that what sits under it stays on screen: a conversation of any length
+     * above its reply box.
+     */
+    scroll: z.boolean().default(false),
     children: z.array(children).max(100),
 });
 const tabsBranch = (children) => z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/ui-sdk",
-  "version": "1.3.0",
+  "version": "1.4.0-dev-20261012081643",
   "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",