@keemakr/ui-sdk 1.6.0-dev-20261027223028 → 1.6.0-dev-20261027224017

package/dist/form.d.ts

@@ -18,6 +18,51 @@ export declare function localInputToIso(local: string): string;
 export declare function initialDraft(field: FormFieldLike): FormDraft;
 /** What the module receives for a field. See the form schema for each kind. */
 export declare function postedValue(field: Pick<FormFieldLike, 'kind'>, draft: FormDraft): string | number | boolean | string[] | null;
+/** When a field is on show: a test of what another field of the form posts (schema `showWhen`). */
+export interface ShowWhen {
+    field: string;
+    includes?: string;
+    notIncludes?: string;
+    equals?: string | number | boolean;
+}
+/** What a form field needs for the show and required rules. */
+export interface FormFieldRule {
+    name: string;
+    label: string;
+    required?: boolean;
+    showWhen?: ShowWhen;
+}
+/** The form as it stands: what it posts, what it hides, the shown required fields left empty. */
+export interface FormState {
+    input: Record<string, unknown>;
+    hidden: ReadonlySet<string>;
+    missing: FormFieldRule[];
+}
+/**
+ * Apply the show and required rules to what the form posts, keyed by field name: a hidden
+ * field's value is left out and it is never missing; a shown field is missing when it is required
+ * and empty. Keys that are not fields (a send's static `input`) pass through.
+ */
+export declare function formState(fields: readonly FormFieldRule[], posted: Readonly<Record<string, unknown>>): FormState;
+export type FormInputCheck = {
+    ok: true;
+    input: Record<string, unknown>;
+} | {
+    ok: false;
+    issue: string;
+};
+/**
+ * What an action received from a form, checked against the form as the module drew it: the value
+ * of a field `showWhen` hides is dropped, and a shown required field that is empty is refused.
+ * Run it in the action. A client can post anything, and a client that draws no `showWhen` shows
+ * every field as optional. Pass `validate: false` for a send that skips the required check (a
+ * "Save draft"); hidden values are still dropped.
+ */
+export declare function checkFormInput(form: {
+    fields: readonly FormFieldRule[];
+}, input: Readonly<Record<string, unknown>>, options?: {
+    validate?: boolean;
+}): FormInputCheck;
 /**
  * The options of a `searchable` multiselect in drawing order: the `pinned` ones first, always on
  * show, then the rest whose label holds the query (any case). Pass the values that were ticked when
@@ -48,16 +93,21 @@ interface SendLike {
     action: string;
     confirm?: string;
     disabled?: boolean;
+    disabledUntilValid?: boolean;
     disabledReason?: string;
 }
-/** Every send button of a form in drawing order: `submit` first, then `secondary`. */
+/**
+ * Every send button of a form in drawing order: `submit` first, then `secondary`. `valid` says
+ * whether every shown required field is filled (`formState(...).missing` is empty); a send with
+ * `disabledUntilValid` is disabled while it is not.
+ */
 export declare function formSubmits(form: {
     submit: SendLike;
     secondary?: ReadonlyArray<SendLike & {
         input?: Record<string, unknown>;
         validate?: boolean;
     }>;
-}): FormSubmit[];
+}, valid?: boolean): FormSubmit[];
 /**
  * The send a submit of the form presses, or null when it must not post: the button the reader
  * pressed (`at`, its index in `formSubmits`), or the primary for Enter in a field. A disabled send

package/dist/form.js

@@ -51,6 +51,54 @@ export function postedValue(field, draft) {
             return typeof draft === 'string' ? draft : '';
     }
 }
+/** True when the field is on show, given what the form posts, keyed by field name. */
+function fieldShown(field, posted) {
+    const when = field.showWhen;
+    if (!when)
+        return true;
+    const value = posted[when.field];
+    const list = Array.isArray(value) ? value : [];
+    if (when.includes !== undefined)
+        return list.includes(when.includes);
+    if (when.notIncludes !== undefined)
+        return !list.includes(when.notIncludes);
+    return value === when.equals;
+}
+/** Empty, as a required field may not be: nothing, blank text, no items, an unticked checkbox. */
+function isEmpty(value) {
+    return (value === undefined ||
+        value === null ||
+        value === false ||
+        (typeof value === 'string' && value.trim() === '') ||
+        (Array.isArray(value) && value.length === 0));
+}
+/**
+ * Apply the show and required rules to what the form posts, keyed by field name: a hidden
+ * field's value is left out and it is never missing; a shown field is missing when it is required
+ * and empty. Keys that are not fields (a send's static `input`) pass through.
+ */
+export function formState(fields, posted) {
+    const hidden = new Set(fields.filter((f) => !fieldShown(f, posted)).map((f) => f.name));
+    return {
+        input: Object.fromEntries(Object.entries(posted).filter(([name]) => !hidden.has(name))),
+        hidden,
+        missing: fields.filter((f) => f.required && !hidden.has(f.name) && isEmpty(posted[f.name])),
+    };
+}
+/**
+ * What an action received from a form, checked against the form as the module drew it: the value
+ * of a field `showWhen` hides is dropped, and a shown required field that is empty is refused.
+ * Run it in the action. A client can post anything, and a client that draws no `showWhen` shows
+ * every field as optional. Pass `validate: false` for a send that skips the required check (a
+ * "Save draft"); hidden values are still dropped.
+ */
+export function checkFormInput(form, input, options = {}) {
+    const state = formState(form.fields, input);
+    const missing = options.validate === false ? undefined : state.missing[0];
+    return missing
+        ? { ok: false, issue: `${missing.label} is required` }
+        : { ok: true, input: state.input };
+}
 /**
  * The options of a `searchable` multiselect in drawing order: the `pinned` ones first, always on
  * show, then the rest whose label holds the query (any case). Pass the values that were ticked when
@@ -63,14 +111,17 @@ export function searchableOptions(options, pinned, query) {
     const rest = options.filter((o) => !pinned.includes(o.value) && o.label.toLocaleLowerCase().includes(needle));
     return [...top, ...rest];
 }
-/** Every send button of a form in drawing order: `submit` first, then `secondary`. */
-export function formSubmits(form) {
+/**
+ * Every send button of a form in drawing order: `submit` first, then `secondary`. `valid` says
+ * whether every shown required field is filled (`formState(...).missing` is empty); a send with
+ * `disabledUntilValid` is disabled while it is not.
+ */
+export function formSubmits(form, valid = true) {
     // A reason is only for a disabled send, as on a button: an enabled one says nothing.
-    const state = ({ disabled, disabledReason, ...rest }) => ({
-        ...rest,
-        disabled: disabled === true,
-        ...(disabled && disabledReason ? { disabledReason } : {}),
-    });
+    const state = ({ disabled, disabledUntilValid, disabledReason, ...rest }) => {
+        const off = disabled === true || (disabledUntilValid === true && !valid);
+        return { ...rest, disabled: off, ...(off && disabledReason ? { disabledReason } : {}) };
+    };
     return [
         { ...state(form.submit), validate: true, primary: true },
         ...(form.secondary ?? []).map(({ validate, ...more }) => ({

package/dist/index.d.ts

@@ -21,8 +21,8 @@ export { PLAYBACK_RATES, SEEK_AT_MAX, formatPlayhead, isSeekPress, nextPlaybackR
 export type { PlaybackRate, PlayerKey, SeekReference } from './player.js';
 export { heatmapCellText, heatmapIntensity, heatmapMixPercent, heatmapRange, heatmapStrong, } from './heatmap.js';
 export type { HeatmapLike, HeatmapRange } from './heatmap.js';
-export { chosenSubmit, formPress, formSubmits, initialDraft, isoToLocalInput, localInputToIso, postedValue, searchableOptions, } from './form.js';
-export type { FormDraft, FormFieldKind, FormFieldLike, FormSubmit } from './form.js';
+export { checkFormInput, chosenSubmit, formPress, formState, formSubmits, initialDraft, isoToLocalInput, localInputToIso, postedValue, searchableOptions, } from './form.js';
+export type { FormDraft, FormFieldKind, FormFieldLike, FormFieldRule, FormInputCheck, FormState, FormSubmit, ShowWhen, } from './form.js';
 export { stackedBarParts, stackedBarValue } from './stacked-bar.js';
 export type { StackedBarLike, StackedBarParts, StackedBarSegmentPart } from './stacked-bar.js';
 export { statTrend } from './stat.js';

package/dist/index.js

@@ -21,7 +21,7 @@ export { PUBLISHED_PARSERS } from './published/index.js';
 export { MEDIA_CONTENT_TYPES, mediaContentType, mediaPathOf } from './media.js';
 export { PLAYBACK_RATES, SEEK_AT_MAX, formatPlayhead, isSeekPress, nextPlaybackRate, playbackRateLabel, playheadWords, seekTarget, seeksIn, } from './player.js';
 export { heatmapCellText, heatmapIntensity, heatmapMixPercent, heatmapRange, heatmapStrong, } from './heatmap.js';
-export { chosenSubmit, formPress, formSubmits, initialDraft, isoToLocalInput, localInputToIso, postedValue, searchableOptions, } from './form.js';
+export { checkFormInput, chosenSubmit, formPress, formState, formSubmits, initialDraft, isoToLocalInput, localInputToIso, postedValue, searchableOptions, } from './form.js';
 export { stackedBarParts, stackedBarValue } from './stacked-bar.js';
 export { statTrend } from './stat.js';
 export { createSectionMemory, sectionBadge, sectionCollapsible, sectionColumnWeights, sectionGridTemplate, sectionScrollHeight, } from './section.js';

package/dist/negotiate.d.ts

@@ -79,8 +79,15 @@ import type { ChatPress, ScreenRootNode, ScreenTree } from './schema.js';
  *     (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.
+ *   - `form.show_when`: a form field's `showWhen`, drawn only while another field holds a value
+ *     and required only then (newer than any published release; core's own renderer draws it).
+ *     An older parse strips it, so the field would be drawn always and keep its `required`,
+ *     blocking every post where it should be hidden. Without it, the field is drawn always and
+ *     is optional: a safe superset, and the module's `checkFormInput` still refuses an empty
+ *     shown required field. A send's `disabledUntilValid` needs no fold: an older parse strips it,
+ *     and the send stays pressable with the browser's required check in front of it.
  */
-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';
+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';
 /** 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". */
@@ -117,7 +124,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"];
+        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"];
     };
 };
 export type UiSdkSnapshot = keyof typeof UI_SDK_SNAPSHOTS;

package/dist/negotiate.js

@@ -53,6 +53,7 @@ const ALL_FEATURES = [
     'stat.bar',
     'section.action',
     'facts.meter',
+    'form.show_when',
 ];
 /** The nodes of ui-sdk 1.1.0 and 1.2.0 (one schema). */
 const NODES_1_1_0 = [
@@ -360,7 +361,8 @@ export function negotiateTree(tree, set) {
                     return form;
                 const kinds = features.has('form.field_kinds');
                 const radio = features.has('form.radio');
-                if (kinds && radio)
+                const showWhen = features.has('form.show_when');
+                if (kinds && radio && showWhen)
                     return form;
                 let changed = false;
                 const fields = form.fields.map((field, index) => {
@@ -382,6 +384,11 @@ export function negotiateTree(tree, set) {
                         next = foldFormField(next);
                         fold('form.field_kinds');
                     }
+                    if (!showWhen && next.showWhen) {
+                        const { showWhen: _showWhen, ...always } = next;
+                        next = { ...always, required: false };
+                        fold('form.show_when');
+                    }
                     return next;
                 });
                 return changed ? { ...form, fields } : form;

package/dist/published/v1.4.0/schema.d.ts

@@ -119,8 +119,8 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             list: "list";
             select: "select";
             checkbox: "checkbox";
-            textarea: "textarea";
             multiselect: "multiselect";
+            textarea: "textarea";
             combobox: "combobox";
         }>;
         name: z.ZodString;

package/dist/schema.d.ts

@@ -574,8 +574,8 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             list: "list";
             select: "select";
             checkbox: "checkbox";
-            textarea: "textarea";
             multiselect: "multiselect";
+            textarea: "textarea";
             combobox: "combobox";
             radio: "radio";
         }>;
@@ -597,6 +597,12 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         min: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
         max: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
         step: z.ZodOptional<z.ZodNumber>;
+        showWhen: z.ZodOptional<z.ZodObject<{
+            field: z.ZodString;
+            includes: z.ZodOptional<z.ZodString>;
+            notIncludes: z.ZodOptional<z.ZodString>;
+            equals: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     layout: z.ZodOptional<z.ZodEnum<{
         stack: "stack";
@@ -607,6 +613,7 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         action: z.ZodString;
         confirm: z.ZodOptional<z.ZodString>;
         disabled: z.ZodOptional<z.ZodBoolean>;
+        disabledUntilValid: z.ZodOptional<z.ZodBoolean>;
         disabledReason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     secondary: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -616,6 +623,7 @@ declare const leafNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         confirm: z.ZodOptional<z.ZodString>;
         validate: z.ZodOptional<z.ZodBoolean>;
         disabled: z.ZodOptional<z.ZodBoolean>;
+        disabledUntilValid: z.ZodOptional<z.ZodBoolean>;
         disabledReason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     onChange: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/schema.js

@@ -1618,6 +1618,29 @@ const statSchema = z
         });
     }
 });
+/**
+ * What is wrong with a form field's `showWhen`, or null: it names another field of the form that
+ * has no `showWhen` of its own (no chains, so no loops), with exactly one test, and the test fits
+ * that field's kind.
+ */
+function showWhenIssue(name, when, fields) {
+    const target = fields.find((field) => field.name === when.field);
+    if (!target || target.name === name)
+        return `showWhen names no other field "${when.field}"`;
+    if (target.showWhen)
+        return `showWhen names "${when.field}", which has a showWhen of its own`;
+    const tests = [when.includes, when.notIncludes, when.equals].filter((t) => t !== undefined);
+    if (tests.length !== 1)
+        return 'showWhen takes exactly one of includes, notIncludes, equals';
+    const many = target.kind === 'multiselect' || target.kind === 'list';
+    if (many && when.equals !== undefined) {
+        return `a ${target.kind} is tested with includes or notIncludes`;
+    }
+    if (!many && when.equals === undefined) {
+        return `includes and notIncludes test a multiselect or list, not a ${target.kind}`;
+    }
+    return null;
+}
 /** A real YYYY-MM-DD calendar day: `2026-02-30` is refused. */
 function isCalendarDate(text) {
     if (!/^\d{4}-\d{2}-\d{2}$/.test(text))
@@ -1732,6 +1755,26 @@ const leafNodeSchema = z.discriminatedUnion('type', [
             max: z.union([z.number().finite(), z.string().max(40)]).optional(),
             /** The step of a number field. */
             step: z.number().finite().positive().optional(),
+            /**
+             * Show the field only while another field of the form holds a value: a "Why not?"
+             * box while a suggested form is unticked. `includes` and `notIncludes` test a
+             * multiselect or list for one value; `equals` tests any other kind against what it
+             * posts (a string, a number, or true or false for a checkbox). Exactly one of the
+             * three. The other field may not have a `showWhen` of its own.
+             *
+             * A hidden field is not drawn, not posted and not required; a shown field keeps its
+             * own `required`. Check the posted input in the action with `checkFormInput`: a
+             * client can post anything, and a client that draws no `showWhen` shows the field
+             * always, as optional.
+             */
+            showWhen: z
+                .object({
+                field: slug,
+                includes: z.string().max(500).optional(),
+                notIncludes: z.string().max(500).optional(),
+                equals: z.union([z.string().max(500), z.number().finite(), z.boolean()]).optional(),
+            })
+                .optional(),
         }))
             .max(30),
         /**
@@ -1753,7 +1796,16 @@ const leafNodeSchema = z.discriminatedUnion('type', [
              * still refuse what it is not ready for. Default false.
              */
             disabled: z.boolean().optional(),
-            /** Why it is disabled, tied to it and read on focus, as a button's is. Ignored when enabled. */
+            /**
+             * Disabled, as `disabled` is, while any shown required field is empty: "Send forms"
+             * until every unticked suggested form has a reason. A client that does not know it draws
+             * the send pressable, and the browser's required check still stops the post.
+             */
+            disabledUntilValid: z.boolean().optional(),
+            /**
+             * Why it is disabled, tied to it and read on focus, as a button's is. Shown while
+             * `disabled`, or while `disabledUntilValid` holds the send back; ignored otherwise.
+             */
             disabledReason: z.string().min(1).max(200).optional(),
         }),
         /**
@@ -1780,7 +1832,9 @@ const leafNodeSchema = z.discriminatedUnion('type', [
             validate: z.boolean().optional(),
             /** Shown but not pressable, as `submit.disabled` is. Default false. */
             disabled: z.boolean().optional(),
-            /** Why it is disabled, as `submit.disabledReason` is. Ignored when enabled. */
+            /** As `submit.disabledUntilValid`. Not with `validate: false`. */
+            disabledUntilValid: z.boolean().optional(),
+            /** Why it is disabled, as `submit.disabledReason` is. */
             disabledReason: z.string().min(1).max(200).optional(),
         }))
             .max(3)
@@ -1836,6 +1890,13 @@ const leafNodeSchema = z.discriminatedUnion('type', [
         }
         const labels = new Set([node.submit.label]);
         for (const [i, more] of (node.secondary ?? []).entries()) {
+            if (more.disabledUntilValid && more.validate === false) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['secondary', i, 'disabledUntilValid'],
+                    message: 'a send with validate: false cannot wait for the form to be valid',
+                });
+            }
             if (labels.has(more.label)) {
                 ctx.addIssue({
                     code: 'custom',
@@ -1856,6 +1917,11 @@ const leafNodeSchema = z.discriminatedUnion('type', [
                 });
             }
             names.add(field.name);
+            if (field.showWhen) {
+                const issue = showWhenIssue(field.name, field.showWhen, node.fields);
+                if (issue)
+                    ctx.addIssue({ code: 'custom', path: at('showWhen'), message: issue });
+            }
             const needsOptions = ['select', 'multiselect', 'combobox', 'radio'].includes(field.kind);
             if (needsOptions && !field.options?.length) {
                 ctx.addIssue({

package/package.json

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