@businessdash/sdk 0.9.60

package/src/forms-core/validation.ts

@@ -0,0 +1,1037 @@
+/**
+ * Framework-agnostic, isomorphic form validation + condition evaluation.
+ *
+ * Zero UI deps, zero React, zero DOM. This is the single source of truth every
+ * `<BiabForm>` binding (React / Vue / Svelte / Solid / Qwik / Angular / Element /
+ * vanilla) shares. It is a faithful port of three existing BIAB modules so the
+ * client never disagrees with the server:
+ *
+ *   - `src/server/forms/validate.ts`           — isEmpty / validateValue /
+ *                                                 evalCondition / findMissingRequired
+ *   - `src/app/.../builder/FormPreview.tsx`     — seedInitialData / concurrentRevealCount /
+ *                                                 the or_condition + condition_block walk
+ *   - `biab-dev/src/sdk.ts` validateFormSubmission — the wire-level submission check
+ *
+ * The schema published by `client.forms.schema(slug)` carries the FULL nested
+ * field tree (layout nodes, `condition_block`, `or_condition`, `input_group`,
+ * `flex_row` with `children`, plus the resolved output `key` on each
+ * value-bearing field). These helpers walk that tree, NOT the flattened
+ * `FormFieldDef[]` view.
+ */
+
+import { getEmailDomain, isConsumerEmailDomain } from "./email-domains.js";
+import {
+	baseUnitFor,
+	isMeasurementCategory,
+	isUnitInCategory,
+	unitsForCategory,
+} from "./units.js";
+import { isValidUsZip } from "./us-states.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Structural field type — the nested tree shape the published schema carries.
+// (A superset of the SDK's flat `FormFieldDef`; mirrors the server `FormField`.)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A condition clause: one operator (+ optional target value) on a field. */
+export interface FormConditionClause {
+	operator: string;
+	value?: string;
+}
+
+/** A field's `conditionRule` — supports the modern multi-clause form and the
+ *  legacy single `{ operator, value }` form (read as one clause). */
+export interface FormConditionRule {
+	fieldId?: string;
+	operator?: string;
+	value?: string;
+	clauses?: FormConditionClause[];
+	/** How clauses combine: "all" (default, AND) or "any" (OR). This was missing
+	 *  from the type, so a rule the builder saved as "ANY of" silently evaluated
+	 *  as "ALL of" once it rendered through the SDK. */
+	match?: "all" | "any";
+	/** Collection pickers store record IDS — compare THIS column of the chosen
+	 *  record instead ("__label__" = the displayed label). Resolved by surfaces
+	 *  that load the picker's options; unresolved falls back to the raw value. */
+	matchField?: string;
+}
+
+/**
+ * Structural view of a form field as it arrives on the wire from
+ * `client.forms.schema()`. Deliberately permissive: every binding renders by
+ * `type`, reads the value-bearing fields, and treats the rest as layout. This
+ * mirrors the server `FormField` + the builder's `FieldX`.
+ */
+export interface FormCoreField {
+	id: string;
+	/** Stable output key for the submission payload (preferred over `id`). */
+	key?: string;
+	type: string;
+	label?: string | null;
+	/** Explicit HTML `autocomplete` token for this field (e.g. "email",
+	 *  "given-name", "off"). Overrides the SDK's inference. Optional / forward-
+	 *  compatible — set by the form builder when present. */
+	autocomplete?: string;
+	required?: boolean;
+	/** Consent semantic for boolean fields — the value must be `true` to submit
+	 *  (independent of the toggle/checkbox `display`). */
+	mustBeTrue?: boolean;
+	/**
+	 * Render variant for a field whose validated type stays the same:
+	 * boolean → toggle/checkbox, checkbox group → dropdown, select → combobox
+	 * (the searchable "ComboBox" palette card). Display-only — never affects the
+	 * submitted value or its validation.
+	 */
+	display?: "toggle" | "checkbox" | "dropdown" | "combobox";
+	/** select / radio / checkbox: accept a free-text "Other…" value outside
+	 *  `options` (the options whitelist isn't enforced when on). */
+	allowCustom?: boolean;
+	placeholder?: string;
+	helpText?: string;
+	options?: string[];
+	defaultValue?: string | boolean | number | null;
+	content?: string;
+	stepTitle?: string;
+	outputKey?: string | null;
+	regexPattern?: string;
+	concurrentReveal?: boolean;
+	showGroupLabel?: boolean;
+	children?: FormCoreField[] | null;
+	conditionRule?: FormConditionRule;
+	validation?: { min?: number; max?: number };
+	sliderConfig?: { min?: number; max?: number; step?: number; unit?: string };
+	starRatingConfig?: { maxStars?: number; defaultValue?: number };
+	fileConfig?: { allowedTypes?: string[]; maxFiles?: number; maxSize?: number };
+	/** `icon_select`: which icons may be picked, and the grid width. The value is
+	 *  the icon's kebab-case name. */
+	iconConfig?: {
+		set?: "lucide";
+		allowedIcons?: string[];
+		columns?: number;
+	};
+	/** `image_input`: upload OR paste a URL — the value is one URL string. */
+	imageInputConfig?: {
+		allowedTypes?: string[];
+		maxSize?: number;
+		showPreview?: boolean;
+		sources?: "both" | "upload" | "url";
+	};
+	phoneConfig?: { international?: boolean; showFlags?: boolean };
+	timeConfig?: {
+		mode?: "simple" | "time_block" | "appointment";
+		format?: "12h" | "24h";
+		stepMinutes?: number;
+	};
+	orConditionConfig?: { leftLabel?: string; rightLabel?: string };
+	/** choice_cards: icon + label options. `single` = radio (value is the chosen
+	 *  label string); `multi` = checkbox (value is a string[] of chosen labels).
+	 *  Options can also carry richer card content (image/price/etc.) — purely
+	 *  display + metadata; the submitted value is always the `label`. */
+	choiceConfig?: {
+		mode?: "single" | "multi";
+		options?: Array<{
+			label: string;
+			icon?: string;
+			imageUrl?: string;
+			price?: string;
+			description?: string;
+			productId?: string;
+			href?: string;
+		}>;
+	};
+	/** bullet_list display element: "bullets" = optional title + plain bullets;
+	 *  "details" = icon + heading + description per point. Carries no value. */
+	listConfig?: {
+		variant?: "bullets" | "details";
+		title?: string;
+		items?: Array<{ text: string; description?: string; icon?: string }>;
+	};
+	/** table display element: columns (header/type/align) + rows of cells. A
+	 *  "check" column renders ✓/– from a truthy/falsy cell. Carries no value. */
+	tableConfig?: {
+		columns?: Array<{
+			header: string;
+			type?: "text" | "check";
+			align?: "left" | "center" | "right";
+		}>;
+		rows?: Array<{ cells: string[] }>;
+		highlightColumn?: number;
+	};
+	/** multi_populator repeater: value is an array of instance records (each keyed
+	 *  by the child field ids). `maxInstances` caps the count (default 10). */
+	populatorConfig?: {
+		maxInstances?: number;
+		minInstances?: number;
+		addButtonLabel?: string;
+		itemLabel?: string;
+	};
+	/** measurement field: number + unit. Value is { value, unit, base, baseUnit }. */
+	unitConfig?: {
+		category?: string;
+		units?: string[];
+		mode?: "select" | "fixed";
+		defaultUnit?: string;
+		outputUnit?: string;
+		allowDecimal?: boolean;
+	};
+	/** number field: when false, only whole numbers are accepted. */
+	allowDecimal?: boolean;
+	/** number field: when false, negatives are rejected (enforce >= 0). */
+	allowNegative?: boolean;
+	/** currency field config. */
+	currencyConfig?: {
+		currency?: string;
+		symbol?: string;
+		allowNegative?: boolean;
+		allowDecimal?: boolean;
+	};
+	// Forward-compat: tolerate any extra config keys the builder ships later.
+	[key: string]: unknown;
+}
+
+/** A submission's working data — keyed by field `id` internally. */
+export type FormData = Record<string, unknown>;
+
+/** A required-field gap, surfaced to the UI for inline error display. */
+export interface MissingField {
+	id: string;
+	label: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shared constants — kept in sync with validate.ts / FormPreview / output-keys.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Local part @ domain . TLD (TLD ≥ 2 chars). Mirrors validate.ts EMAIL_RE. */
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/;
+/** An icon name: lowercase kebab-case slug. Mirrors validate.ts ICON_NAME_RE. */
+const ICON_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Valid web address. Mirrors validate.ts URL_RE. */
+const URL_RE =
+	/^(https?:\/\/)?([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}(?::\d{1,5})?(?:[/?#]\S*)?$/i;
+/** A hex color: #rgb or #rrggbb. Mirrors validate.ts HEX_COLOR_RE. */
+const HEX_COLOR_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+
+const MAX_STRING_LEN = 50_000;
+const MAX_ARRAY_LEN = 500;
+const MAX_PHONE_LEN = 64;
+const MAX_DATE_LEN = 64;
+const MAX_ADDRESS_FIELD_LEN = 512;
+const MAX_FILE_FIELD_LEN = 4096;
+
+/**
+ * Pure layout / static / grouping types that never carry a submitted value.
+ * Mirrors `STATIC_OR_LAYOUT` in validate.ts + FormPreview (note: numeric
+ * "stepper" IS value-bearing, so it stays in this skip-set for the tree walk
+ * but is still validated when it carries a value).
+ */
+const STATIC_OR_LAYOUT = new Set([
+	"title",
+	"subtitle",
+	"separator",
+	"flex_row",
+	"input_group",
+	"condition_block",
+	"or_condition",
+	"image",
+	"richtext",
+	"body_text",
+	"bullet_list",
+	"table",
+	"stepper",
+	// `calculation` is computed server-side, never user-input → skip validation.
+	"calculation",
+]);
+
+/** Containers whose own id never holds a value (their children do). */
+const STEP_CONTAINERS = new Set([
+	"input_group",
+	"condition_block",
+	"or_condition",
+]);
+
+/** Static elements that carry no value AND get no seeded default. */
+const NO_SEED_STATIC = new Set([
+	"title",
+	"subtitle",
+	"separator",
+	"image",
+	"richtext",
+	"body_text",
+	"bullet_list",
+	"table",
+	// computed on submit — never seeded with a user default.
+	"calculation",
+]);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// isEmpty — per-type "is this answered?" rule. Mirrors validate.ts isEmpty.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** True when a field's value should be treated as missing for required checks. */
+export function isEmpty(field: FormCoreField, value: unknown): boolean {
+	switch (field.type) {
+		case "checkbox":
+		case "tags":
+			return !Array.isArray(value) || value.length === 0;
+		case "multi_populator":
+			return (
+				!Array.isArray(value) ||
+				!value.some(
+					(inst) =>
+						inst != null &&
+						typeof inst === "object" &&
+						Object.values(inst as Record<string, unknown>).some(
+							(v) =>
+								!(
+									v === undefined ||
+									v === null ||
+									v === "" ||
+									(Array.isArray(v) && v.length === 0)
+								),
+						),
+				)
+			);
+		case "measurement": {
+			const mv = value as { value?: unknown } | undefined;
+			return !mv || typeof mv.value !== "number";
+		}
+		case "url": {
+			const v = value as { url?: unknown } | undefined;
+			return !v || typeof v.url !== "string" || v.url === "";
+		}
+		case "choice_cards":
+			return field.choiceConfig?.mode === "multi"
+				? !Array.isArray(value) || value.length === 0
+				: typeof value !== "string" || value === "";
+		case "boolean":
+			// mustBeTrue (consent) → empty unless exactly `true`; otherwise answered
+			// by either choice (an optional yes/no can stay "no" and still submit).
+			return field.mustBeTrue ? value !== true : typeof value !== "boolean";
+		case "file_upload":
+			return !Array.isArray(value) || value.length === 0;
+		case "schedule": {
+			const s = (value ?? {}) as {
+				slotStartAt?: unknown;
+				asap?: boolean;
+				days?: unknown[];
+				times?: unknown[];
+			};
+			return !(
+				(typeof s.slotStartAt === "string" && s.slotStartAt.length > 0) ||
+				s.asap === true ||
+				(Array.isArray(s.days) && s.days.length > 0) ||
+				(Array.isArray(s.times) && s.times.length > 0)
+			);
+		}
+		case "date_range": {
+			const v = value as { start?: string; end?: string } | undefined;
+			return !v?.start || !v.end;
+		}
+		case "address": {
+			const v = value as
+				| { line1?: string; city?: string; state?: string; zip?: string }
+				| undefined;
+			return !v?.line1 || !v.city || !v.state || !v.zip;
+		}
+		case "time_picker": {
+			const mode = field.timeConfig?.mode ?? "simple";
+			if (mode === "time_block") {
+				const v = value as { start?: string; end?: string } | undefined;
+				return !v?.start || !v.end;
+			}
+			if (mode === "appointment") {
+				const v = value as { date?: string; time?: string } | undefined;
+				return !v?.date || !v.time;
+			}
+			return value === undefined || value === null || value === "";
+		}
+		case "star_rating":
+		case "happiness_rating":
+			return typeof value !== "number" || value <= 0;
+		default:
+			return value === undefined || value === null || value === "";
+	}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// validateValue — per-value type / constraint check. Mirrors validate.ts.
+// Returns an error reason string, or null when the value conforms. Empty values
+// pass here (required-ness is checked separately).
+// ─────────────────────────────────────────────────────────────────────────────
+
+function regexFail(field: FormCoreField, value: string): string | null {
+	const pattern = field.regexPattern;
+	if (!pattern) return null;
+	try {
+		if (!new RegExp(pattern).test(value)) return "regex";
+	} catch {
+		// A broken stored pattern shouldn't block a submission.
+	}
+	return null;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** True when every leaf is a bounded primitive (no nesting). */
+function onlyBoundedPrimitives(
+	obj: Record<string, unknown>,
+	maxLen: number,
+): boolean {
+	for (const v of Object.values(obj)) {
+		if (v == null) continue;
+		if (typeof v === "string") {
+			if (v.length > maxLen) return false;
+			continue;
+		}
+		if (typeof v === "number" || typeof v === "boolean") continue;
+		return false;
+	}
+	return true;
+}
+
+/**
+ * Validate one value against its field definition. Returns an error reason
+ * (`"type"`, `"format"`, `"min"`, `"max"`, `"options"`, `"regex"`), or null when
+ * the value conforms. Lenient where the renderer's output is ambiguous (numeric
+ * fields accept numeric strings) so legitimate live submissions never break.
+ * Faithful port of `validateValue` in src/server/forms/validate.ts.
+ */
+export function validateValue(
+	field: FormCoreField,
+	value: unknown,
+): string | null {
+	if (value === undefined || value === null || value === "") return null;
+	const opts = Array.isArray(field.options) ? field.options : null;
+
+	switch (field.type) {
+		case "email": {
+			if (typeof value !== "string") return "type";
+			if (value.length > MAX_STRING_LEN) return "max";
+			if (!EMAIL_RE.test(value)) return "format";
+			if (
+				(field as { emailConfig?: { businessOnly?: boolean } }).emailConfig
+					?.businessOnly &&
+				isConsumerEmailDomain(getEmailDomain(value) ?? "")
+			) {
+				return "business_email";
+			}
+			return null;
+		}
+		case "url": {
+			// Value object: { url, verified } (verified is stamped server-side).
+			if (!isPlainObject(value)) return "type";
+			const u = value["url"];
+			if (u === undefined || u === null || u === "") return null;
+			if (typeof u !== "string") return "type";
+			if (u.length > MAX_STRING_LEN) return "max";
+			if (!URL_RE.test(u.trim())) return "format";
+			const verified = value["verified"];
+			if (
+				verified !== undefined &&
+				verified !== "unverified" &&
+				verified !== "safe" &&
+				verified !== "unsafe"
+			) {
+				return "options";
+			}
+			return onlyBoundedPrimitives(value, MAX_STRING_LEN) ? null : "type";
+		}
+		case "phone": {
+			if (typeof value !== "string") return "type";
+			if (value.length > MAX_PHONE_LEN) return "max";
+			const rx = regexFail(field, value);
+			if (rx) return rx;
+			const digits = value.replace(/\D/g, "");
+			if (field.phoneConfig?.international === true) {
+				return digits.length >= 7 && digits.length <= 15 ? null : "format";
+			}
+			const national =
+				digits.length === 11 && digits.startsWith("1")
+					? digits.slice(1)
+					: digits;
+			return national.length === 10 ? null : "format";
+		}
+		case "number":
+		case "slider":
+		case "stepper": {
+			const n =
+				typeof value === "number"
+					? value
+					: typeof value === "string" &&
+							value.trim() !== "" &&
+							!Number.isNaN(Number(value))
+						? Number(value)
+						: Number.NaN;
+			if (Number.isNaN(n)) return "type";
+			if (
+				field.type === "number" &&
+				field.allowDecimal === false &&
+				!Number.isInteger(n)
+			)
+				return "format";
+			// number "allow negative" off → enforce >= 0.
+			if (
+				field.type === "number" &&
+				(field as { allowNegative?: boolean }).allowNegative === false &&
+				n < 0
+			)
+				return "min";
+			const min = field.validation?.min ?? field.sliderConfig?.min;
+			const max = field.validation?.max ?? field.sliderConfig?.max;
+			if (typeof min === "number" && n < min) return "min";
+			if (typeof max === "number" && n > max) return "max";
+			return null;
+		}
+		case "star_rating":
+		case "happiness_rating": {
+			if (typeof value !== "number") return "type";
+			const maxStars = field.starRatingConfig?.maxStars ?? 5;
+			if (value < 0 || value > maxStars + 0.0001) return "max";
+			return null;
+		}
+		case "boolean":
+			return typeof value === "boolean" ? null : "type";
+		case "select":
+		case "radio":
+			if (typeof value !== "string") return "type";
+			if (value.length > MAX_STRING_LEN) return "max";
+			if (opts && !field.allowCustom && !opts.includes(value)) return "options";
+			return null;
+		case "color_picker":
+			// A color is a hex value — presets and the "Other" custom picker both
+			// emit one, so validate the format rather than options membership.
+			if (typeof value !== "string") return "type";
+			if (value !== "" && !HEX_COLOR_RE.test(value)) return "format";
+			return null;
+		case "icon_select": {
+			// An icon NAME (kebab-case slug), e.g. "cloud-sun". Checked as a slug
+			// rather than against a pinned icon manifest, matching the server —
+			// the set can grow without either side needing a release.
+			if (typeof value !== "string") return "type";
+			if (value === "") return null;
+			if (value.length > 64) return "max";
+			if (!ICON_NAME_RE.test(value)) return "format";
+			const allowed = (field as { iconConfig?: { allowedIcons?: string[] } })
+				.iconConfig?.allowedIcons;
+			if (allowed && allowed.length > 0 && !allowed.includes(value)) {
+				return "options";
+			}
+			return null;
+		}
+		case "image_input":
+			// One image URL, whether uploaded or pasted. A plain string — unlike
+			// `url`, which carries a { url, verified } object.
+			if (typeof value !== "string") return "type";
+			if (value === "") return null;
+			if (value.length > MAX_STRING_LEN) return "max";
+			if (!URL_RE.test(value.trim())) return "format";
+			return null;
+		case "tags": {
+			// Free-text tag array — string items, no fixed options list.
+			if (!Array.isArray(value)) return "type";
+			if (value.length > MAX_ARRAY_LEN) return "max";
+			for (const v of value) {
+				if (typeof v !== "string") return "type";
+				if (v.length > MAX_STRING_LEN) return "max";
+			}
+			return null;
+		}
+		case "checkbox": {
+			if (!Array.isArray(value)) return "type";
+			if (value.length > MAX_ARRAY_LEN) return "max";
+			for (const v of value) {
+				if (typeof v !== "string") return "type";
+				if (opts && !field.allowCustom && !opts.includes(v)) return "options";
+			}
+			return null;
+		}
+		case "currency": {
+			if (typeof value !== "number" || Number.isNaN(value)) return "type";
+			if (field.currencyConfig?.allowNegative !== true && value < 0)
+				return "format";
+			if (
+				field.currencyConfig?.allowDecimal === false &&
+				!Number.isInteger(value)
+			)
+				return "format";
+			return null;
+		}
+		case "measurement": {
+			if (typeof value !== "object" || value === null || Array.isArray(value))
+				return "type";
+			const mv = value as { value?: unknown; unit?: unknown };
+			if (mv.value === "" || mv.value === undefined || mv.value === null)
+				return null;
+			if (typeof mv.value !== "number" || Number.isNaN(mv.value)) return "type";
+			if (typeof mv.unit !== "string") return "type";
+			const cat = field.unitConfig?.category;
+			if (cat && isMeasurementCategory(cat) && !isUnitInCategory(mv.unit, cat))
+				return "options";
+			if (
+				field.unitConfig?.allowDecimal === false &&
+				!Number.isInteger(mv.value)
+			)
+				return "format";
+			return null;
+		}
+		case "multi_populator": {
+			// Lenient client check (the server validates each instance deeply):
+			// must be an array within the instance cap.
+			if (!Array.isArray(value)) return "type";
+			const max = field.populatorConfig?.maxInstances ?? 10;
+			if (value.length > Math.min(max, MAX_ARRAY_LEN)) return "max";
+			return null;
+		}
+		case "choice_cards": {
+			const labels = (field.choiceConfig?.options ?? []).map((o) => o.label);
+			if (field.choiceConfig?.mode === "multi") {
+				if (!Array.isArray(value)) return "type";
+				if (value.length > MAX_ARRAY_LEN) return "max";
+				for (const v of value) {
+					if (typeof v !== "string") return "type";
+					if (labels.length && !labels.includes(v)) return "options";
+				}
+				return null;
+			}
+			if (typeof value !== "string") return "type";
+			if (value.length > MAX_STRING_LEN) return "max";
+			if (labels.length && !labels.includes(value)) return "options";
+			return null;
+		}
+		case "file_upload": {
+			if (!Array.isArray(value)) return "type";
+			const maxFiles = Math.min(
+				field.fileConfig?.maxFiles ?? MAX_ARRAY_LEN,
+				MAX_ARRAY_LEN,
+			);
+			if (value.length > maxFiles) return "max";
+			for (const item of value) {
+				if (!isPlainObject(item)) return "type";
+				if (!onlyBoundedPrimitives(item, MAX_FILE_FIELD_LEN)) return "type";
+			}
+			return null;
+		}
+		case "date_range": {
+			if (!isPlainObject(value)) return "type";
+			return onlyBoundedPrimitives(value, MAX_DATE_LEN) ? null : "type";
+		}
+		case "time_picker": {
+			const mode = field.timeConfig?.mode ?? "simple";
+			if (mode === "simple") {
+				if (typeof value !== "string") return "type";
+				return value.length > MAX_DATE_LEN ? "max" : null;
+			}
+			if (!isPlainObject(value)) return "type";
+			return onlyBoundedPrimitives(value, MAX_DATE_LEN) ? null : "type";
+		}
+		case "address": {
+			if (!isPlainObject(value)) return "type";
+			if (!onlyBoundedPrimitives(value, MAX_ADDRESS_FIELD_LEN)) return "type";
+			// ZIP, when present, must be a US ZIP (5 digits or ZIP+4) — numbers only.
+			const zip = (value as { zip?: unknown }).zip;
+			if (typeof zip === "string" && !isValidUsZip(zip)) return "format";
+			return null;
+		}
+		case "schedule": {
+			// Availability value: { asap?, days?: string[], times?: string[], notes? }.
+			// Auto value: { slotStartAt: <ISO> } (the chosen instant-booking slot).
+			if (!isPlainObject(value)) return "type";
+			const s = value as {
+				slotStartAt?: unknown;
+				asap?: unknown;
+				days?: unknown;
+				times?: unknown;
+				notes?: unknown;
+			};
+			if (s.slotStartAt !== undefined) {
+				if (typeof s.slotStartAt !== "string") return "type";
+				if (s.slotStartAt.length > MAX_DATE_LEN) return "max";
+				if (Number.isNaN(Date.parse(s.slotStartAt))) return "format";
+			}
+			if (s.asap !== undefined && typeof s.asap !== "boolean") return "type";
+			for (const key of ["days", "times"] as const) {
+				const arr = s[key];
+				if (arr === undefined) continue;
+				if (!Array.isArray(arr)) return "type";
+				if (arr.length > MAX_ARRAY_LEN) return "max";
+				for (const item of arr) {
+					if (typeof item !== "string") return "type";
+					if (item.length > MAX_DATE_LEN) return "max";
+				}
+			}
+			if (s.notes !== undefined) {
+				if (typeof s.notes !== "string") return "type";
+				if (s.notes.length > MAX_STRING_LEN) return "max";
+			}
+			return null;
+		}
+		default: {
+			// text / textarea / date / and any plain-text input.
+			if (typeof value === "number" || typeof value === "boolean") return null;
+			if (typeof value !== "string") return "type";
+			if (value.length > MAX_STRING_LEN) return "max";
+			return regexFail(field, value);
+		}
+	}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Condition evaluation — condition_block + or_condition. Mirrors validate.ts.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function evalClause(value: unknown, operator: string, target: string): boolean {
+	switch (operator) {
+		case "eq":
+			return String(value ?? "") === target;
+		case "neq":
+			return String(value ?? "") !== target;
+		case "contains":
+			return String(value ?? "")
+				.toLowerCase()
+				.includes(target.toLowerCase());
+		case "gt":
+			return Number(value) > Number(target);
+		case "lt":
+			return Number(value) < Number(target);
+		case "is_empty":
+			return value === undefined || value === null || value === "";
+		case "is_not_empty":
+			return value !== undefined && value !== null && value !== "";
+		default:
+			return true;
+	}
+}
+
+/**
+ * A condition passes when its field satisfies ALL clauses (AND). Back-compat: a
+ * legacy single `{ operator, value }` rule is read as one clause. An absent rule
+ * (or one without a `fieldId`) passes. Faithful port of `evalCondition`.
+ */
+export function evalCondition(
+	rule: FormConditionRule | undefined,
+	data: FormData,
+): boolean {
+	if (!rule?.fieldId) return true;
+	const clauses =
+		rule.clauses && rule.clauses.length > 0
+			? rule.clauses
+			: rule.operator
+				? [{ operator: rule.operator, value: rule.value }]
+				: [];
+	if (clauses.length === 0) return true;
+	const value = data[rule.fieldId];
+	const test = (c: { operator: string; value?: string | undefined }) =>
+		evalClause(value, c.operator, c.value ?? "");
+	// `match: "any"` is OR across clauses. This used to always AND, so a rule the
+	// builder saved as "ANY of" behaved as "ALL of" once it rendered through the
+	// SDK — the dashboard and a consumer's site disagreed about the same form.
+	return rule.match === "any" ? clauses.some(test) : clauses.every(test);
+}
+
+/**
+ * Is a gating container currently visible?
+ *
+ * `condition_block` has always gated on its rule. `input_group` now does too:
+ * at the root of a consecutive form a group IS a page, so a rule there makes the
+ * whole page conditional. Every other type is unconditionally visible — a stray
+ * rule on a text field is ignored rather than hiding it.
+ */
+export function isNodeVisible(
+	node: { type?: string; conditionRule?: FormConditionRule },
+	data: FormData,
+): boolean {
+	if (node.type !== "condition_block" && node.type !== "input_group") {
+		return true;
+	}
+	return evalCondition(node.conditionRule, data);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tree walks — subtreeHasValue / findMissingRequired / concurrentRevealCount.
+// Mirrors FormPreview.tsx exactly so the binding matches the dashboard renderer.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Recurse a subtree; report whether any non-static leaf has a non-empty value.
+ *  Used by `or_condition` to detect which side the user chose. */
+function subtreeHasValue(nodes: FormCoreField[], data: FormData): boolean {
+	for (const f of nodes) {
+		if (f.type === "condition_block") {
+			if (!evalCondition(f.conditionRule, data)) continue;
+			if (f.children && subtreeHasValue(f.children, data)) return true;
+			continue;
+		}
+		if (
+			f.type === "or_condition" ||
+			f.type === "input_group" ||
+			f.type === "flex_row"
+		) {
+			// Stale data behind a hidden group must not decide an or_condition
+			// branch — as far as the visitor is concerned it holds nothing.
+			if (!isNodeVisible(f, data)) continue;
+			if (f.children && subtreeHasValue(f.children, data)) return true;
+			continue;
+		}
+		if (STATIC_OR_LAYOUT.has(f.type)) continue;
+		if (f.id && !isEmpty(f, data[f.id])) return true;
+	}
+	return false;
+}
+
+/**
+ * Returns the required fields that haven't been filled in, evaluated under the
+ * current condition state. A `condition_block` whose rule is false is skipped
+ * with its children; an `or_condition` requires at least one side filled, then
+ * recurses only into filled sides. Non-empty text/number values must also
+ * satisfy the field's regex pattern. Faithful port of FormPreview's
+ * `findMissingRequired`.
+ */
+export function findMissingRequired(
+	fields: FormCoreField[],
+	data: FormData,
+): MissingField[] {
+	const missing: MissingField[] = [];
+	// `scope` is the data context: the whole submission, or one instance record
+	// inside a multi_populator.
+	const walk = (nodes: FormCoreField[], scope: FormData) => {
+		for (const f of nodes) {
+			if (f.type === "condition_block") {
+				if (!evalCondition(f.conditionRule, scope)) continue;
+				if (f.children) walk(f.children, scope);
+				continue;
+			}
+			if (f.type === "or_condition") {
+				// Up to N branches (sides). At least one must be filled; then every
+				// filled branch is walked for its own required fields.
+				const children = f.children ?? [];
+				const filled = children.map((c) => subtreeHasValue([c], scope));
+				if (children.length > 0 && !filled.some(Boolean)) {
+					missing.push({
+						id: f.id,
+						label: f.label || "Either side required",
+					});
+					continue;
+				}
+				children.forEach((c, i) => {
+					if (filled[i]) walk([c], scope);
+				});
+				continue;
+			}
+			if (f.type === "input_group" || f.type === "flex_row") {
+				// A conditional PAGE that isn't showing requires nothing — the
+				// visitor never saw it, so it must not block Next or Submit.
+				if (!isNodeVisible(f, scope)) continue;
+				if (f.children) walk(f.children, scope);
+				continue;
+			}
+			if (f.type === "multi_populator") {
+				const raw = scope[f.id];
+				const instances = (Array.isArray(raw) ? raw : []).filter(
+					(x): x is FormData =>
+						x != null && typeof x === "object" && !Array.isArray(x),
+				);
+				const nonEmpty = instances.filter((inst) =>
+					Object.values(inst).some(
+						(v) =>
+							!(
+								v === undefined ||
+								v === null ||
+								v === "" ||
+								(Array.isArray(v) && v.length === 0)
+							),
+					),
+				);
+				if (f.required && nonEmpty.length === 0) {
+					missing.push({
+						id: f.id,
+						label: f.label || "At least one entry required",
+					});
+					continue;
+				}
+				for (const inst of nonEmpty) walk(f.children ?? [], inst);
+				continue;
+			}
+			if (STATIC_OR_LAYOUT.has(f.type)) continue;
+			if ((f.required || f.mustBeTrue) && f.id && isEmpty(f, scope[f.id])) {
+				missing.push({ id: f.id, label: f.label || "Untitled" });
+			} else if (f.id && (f.type === "text" || f.type === "number")) {
+				const pattern = f.regexPattern;
+				const v = String(scope[f.id] ?? "");
+				if (pattern && v) {
+					try {
+						if (!new RegExp(pattern).test(v)) {
+							missing.push({ id: f.id, label: f.label || "Invalid format" });
+						}
+					} catch {
+						/* ignore an invalid pattern */
+					}
+				}
+			}
+		}
+	};
+	walk(fields, data);
+	return missing;
+}
+
+/**
+ * For a "concurrent questions" group: how many leading children to reveal. Shows
+ * every already-satisfied child plus the first unsatisfied one (the active
+ * question), so each required field gates the next. Optional/empty fields count
+ * as satisfied. Faithful port of FormPreview's `concurrentRevealCount`.
+ */
+export function concurrentRevealCount(
+	children: FormCoreField[],
+	data: FormData,
+): number {
+	for (let i = 0; i < children.length; i++) {
+		const child = children[i];
+		if (child && findMissingRequired([child], data).length > 0) return i + 1;
+	}
+	return children.length;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// seedInitialData — walk the tree once, seed every input's id with a default.
+// Mirrors FormPreview's seedInitialData + defaultValueFor.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function defaultValueFor(field: FormCoreField): unknown {
+	switch (field.type) {
+		case "checkbox":
+		case "tags":
+			return [];
+		case "choice_cards":
+			return field.choiceConfig?.mode === "multi" ? [] : "";
+		case "multi_populator":
+			return [{}];
+		case "measurement": {
+			const cat = isMeasurementCategory(field.unitConfig?.category)
+				? field.unitConfig.category
+				: "length";
+			const units = unitsForCategory(cat);
+			const unit = field.unitConfig?.defaultUnit ?? units[0] ?? "";
+			return { value: "", unit, baseUnit: baseUnitFor(cat) };
+		}
+		case "boolean":
+			return field.defaultValue === true;
+		case "number":
+		case "stepper":
+		case "slider":
+		case "star_rating":
+		case "happiness_rating":
+			return 0;
+		case "date_range":
+			return { start: "", end: "" };
+		case "time_picker": {
+			const mode = field.timeConfig?.mode ?? "simple";
+			if (mode === "time_block") return { start: "", end: "" };
+			if (mode === "appointment") return { date: "", time: "" };
+			return "";
+		}
+		default:
+			return typeof field.defaultValue === "string" ? field.defaultValue : "";
+	}
+}
+
+/**
+ * Walk the field tree once and seed every value-bearing input's id with a
+ * type-appropriate default. Static/layout/container nodes are skipped so no
+ * UUID-keyed empty string leaks into the payload (which the server would reject
+ * as an unknown field). Faithful port of FormPreview's `seedInitialData`.
+ */
+export function seedInitialData(fields: FormCoreField[]): FormData {
+	const out: FormData = {};
+	const walk = (nodes: FormCoreField[]) => {
+		for (const f of nodes) {
+			// A populator is value-bearing (array of instances); its children live
+			// inside that array, so seed its value and DON'T hoist children up.
+			if (f.type === "multi_populator") {
+				if (f.id) out[f.id] = defaultValueFor(f);
+				continue;
+			}
+			if (
+				f.id &&
+				!NO_SEED_STATIC.has(f.type) &&
+				!STEP_CONTAINERS.has(f.type) &&
+				f.type !== "flex_row"
+			) {
+				out[f.id] = defaultValueFor(f);
+			}
+			if (f.children) walk(f.children);
+		}
+	};
+	walk(fields);
+	return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Submission-key remapping — id ⇆ output key. Lets the controller emit a
+// payload keyed by the published `key` (preferred wire contract) while working
+// internally by `id`. The server accepts either (back-compat).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Flat list of value-bearing fields (depth-first, document order). */
+export function flattenValueFields(fields: FormCoreField[]): FormCoreField[] {
+	const out: FormCoreField[] = [];
+	const walk = (nodes: FormCoreField[]) => {
+		for (const f of nodes) {
+			// A populator is a single array-valued field; its children are nested in
+			// the array, not top-level — include it but don't descend.
+			if (f.type === "multi_populator") {
+				if (f.id) out.push(f);
+				continue;
+			}
+			if (!STATIC_OR_LAYOUT.has(f.type) && f.id) out.push(f);
+			// "stepper" is in STATIC_OR_LAYOUT for the layout-skip semantics but is a
+			// value-bearing numeric input — include it explicitly.
+			else if (f.type === "stepper" && f.id) out.push(f);
+			if (f.children) walk(f.children);
+		}
+	};
+	walk(fields);
+	return out;
+}
+
+/**
+ * Re-key working data (keyed by field `id`) to the published output `key` for
+ * the wire payload. Fields without a published `key` keep their `id`. Only
+ * value-bearing fields present in `data` are emitted.
+ */
+export function toSubmissionPayload(
+	fields: FormCoreField[],
+	data: FormData,
+): FormData {
+	const remapScope = (
+		scopeFields: FormCoreField[],
+		scopeData: FormData,
+	): FormData => {
+		const byId = new Map(
+			flattenValueFields(scopeFields).map((field) => [field.id, field]),
+		);
+		const out: FormData = {};
+
+		for (const [id, inputValue] of Object.entries(scopeData)) {
+			const field = byId.get(id);
+			if (!field) {
+				out[id] = inputValue;
+				continue;
+			}
+
+			let value = inputValue;
+			if (field.type === "multi_populator" && Array.isArray(inputValue)) {
+				value = inputValue.map((instance) =>
+					instance && typeof instance === "object" && !Array.isArray(instance)
+						? remapScope(field.children ?? [], instance as FormData)
+						: instance,
+				);
+			}
+			out[field.key ?? id] = value;
+		}
+
+		return out;
+	};
+
+	return remapScope(fields, data);
+}