@businessdash/sdk 0.9.60

package/src/forms-core/controller.ts

@@ -0,0 +1,922 @@
+/**
+ * createFormController — the framework-agnostic observable store that drives
+ * every `<BiabForm>` binding (React / Vue / Svelte / Solid / Qwik / Angular /
+ * web-component / vanilla).
+ *
+ * It owns ALL of the form's runtime state and behaviour:
+ *   - working values (+ seeded defaults), condition-aware visible fields,
+ *   - field-level validation errors (mirrored from the server's rules),
+ *   - multi-step ("consecutive") navigation + progress,
+ *   - concurrent-reveal gating inside groups,
+ *   - submission lifecycle (submitting / result),
+ *   - file uploads via the SDK.
+ *
+ * Bindings stay dumb: subscribe to `snapshot()`, render by field `type` using
+ * the `biab-*` class convention (light DOM, no shadow root, so consumer CSS
+ * cascades), and call `setValue` / `next` / `back` / `submit` / `uploadFile` /
+ * `reset`. The store is a tiny subscribe/notify observable — no framework
+ * reactivity primitives leak in.
+ *
+ * Data flows entirely through the SDK: it calls `client.forms.schema(slug)` to
+ * load and `client.forms.submit(slug, data, opts)` to submit, so auth, caching,
+ * revalidation, HMAC, retries, and CRM fan-out all stay invisible inside
+ * biab-dev. SSR callers can hand a pre-fetched schema instead of a client.
+ */
+
+import type {
+	FormFieldDef,
+	FormFileValue,
+	FormRenderSettings,
+	FormSchema,
+	FormSubmitResult,
+	FormValidationIssue,
+} from "../sdk.js";
+import {
+	type BusinessFunctionDef,
+	functionsToEvalOptions,
+} from "./business-function.js";
+import { type CalculationConfig, computeCalculation } from "./calculation.js";
+import { FORM_WIDE_MAX_FILES } from "./file-rules.js";
+import type { EvalOptions } from "./formula.js";
+import {
+	concurrentRevealCount,
+	evalCondition,
+	type FormConditionRule,
+	type FormCoreField,
+	type FormData,
+	findMissingRequired,
+	isNodeVisible,
+	type MissingField,
+	seedInitialData,
+	toSubmissionPayload,
+} from "./validation.js";
+
+export type { FormCoreField, FormData, MissingField } from "./validation.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Options
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Per-field validation error surfaced to the binding (`id` → message). */
+export interface FieldError {
+	id: string;
+	label: string;
+	message: string;
+}
+
+/**
+ * A file the visitor picked but hasn't uploaded — uploads are DEFERRED to
+ * `submit()`. A binding stores these in the field's value (an array mixing
+ * `PendingFileValue` + already-uploaded `FormFileValue`); `submit()` flushes
+ * the pending ones to R2, replacing each with its uploaded record. Deferring
+ * means an abandoned form never orphans an object and a failed upload surfaces
+ * as a submit error rather than vanishing.
+ */
+export interface PendingFileValue {
+	pending: true;
+	file: File | Blob;
+	name: string;
+	size: number;
+}
+
+export function isPendingFileValue(v: unknown): v is PendingFileValue {
+	return (
+		!!v && typeof v === "object" && (v as PendingFileValue).pending === true
+	);
+}
+
+/** Walk the field tree and collect every `file_upload` node. */
+function collectFileFields(nodes: FormCoreField[]): FormCoreField[] {
+	const out: FormCoreField[] = [];
+	const walk = (ns: FormCoreField[]) => {
+		for (const n of ns) {
+			if (n.type === "file_upload") out.push(n);
+			const kids = (n as { children?: FormCoreField[] }).children;
+			if (kids) walk(kids);
+		}
+	};
+	walk(nodes);
+	return out;
+}
+
+/** Provenance + recipient passthrough for the underlying `forms.submit`. */
+export interface FormSubmitOptions {
+	submitterEmail?: string;
+	submitterName?: string;
+	/** Validate on the server but store nothing (no side effects). */
+	dryRun?: boolean;
+	/** Lead-source provenance (e.g. "facebook", "google-ads:summer"). */
+	source?: string;
+	referrer?: string;
+	metadata?: Record<string, unknown>;
+}
+
+/**
+ * The slice of the SDK client the form controller actually needs. Any object exposing a
+ * `forms` resource with `schema` / `submit` / `uploadFile` satisfies it — the
+ * full `BiabClient` from `createBiabClient()`, or a thin same-origin proxy that
+ * forwards to `/api/biab/forms/*` (the pattern every starter template uses so the
+ * bearer key never reaches the browser).
+ *
+ * It lives here rather than in `react.tsx` because `forms-core` is the layer
+ * that consumes it — solid, qwik, svelte, vanilla and the custom element all
+ * run this controller, and none of them should reach through React for a type.
+ * `react.tsx` re-exports the name, so the public API is unchanged.
+ */
+export interface BiabFormsClient {
+	forms: {
+		schema(slug: string): Promise<FormSchema>;
+		submit(
+			slug: string,
+			data: Record<string, unknown>,
+			opts?: FormSubmitOptions,
+		): Promise<FormSubmitResult>;
+		uploadFile?(
+			slug: string,
+			fieldId: string,
+			file: File | Blob,
+			opts?: { filename?: string },
+		): Promise<FormFileValue>;
+		/** Open booking slots for an auto-mode `schedule` field. */
+		scheduleSlots?(
+			slug: string,
+			input: { fieldId: string; from: Date; to: Date },
+		): Promise<{ slots: Array<{ startAt: string }> }>;
+	};
+}
+
+/**
+ * `uploadFile` is optional on `BiabFormsClient`, and legitimately so: a
+ * same-origin proxy that forwards only `schema` and `submit` is a valid client,
+ * and that is exactly what the starter templates ship so the bearer key never
+ * reaches the browser. A form with a file field needs more than that.
+ *
+ * Resolving it here turns the failure into one sentence naming the cause, at
+ * the moment of upload. Previously the controller called it unguarded — under
+ * the old typing that was invisible, and a proxy client hit
+ * `client.forms.uploadFile is not a function` from inside a submit handler.
+ */
+function requireUploadFile(client: BiabFormsClient) {
+	const upload = client.forms.uploadFile;
+	if (!upload) {
+		throw new Error(
+			"createFormController: this form has a file field, but the configured client does not implement `forms.uploadFile`.",
+		);
+	}
+	return upload.bind(client.forms);
+}
+
+export interface CreateFormControllerOptions {
+	/**
+	 * The SDK client. Required unless `schema` is supplied (SSR / pre-fetched).
+	 * When both are given, `client` is still used for `submit` / `uploadFile`.
+	 *
+	 * Typed as `BiabFormsClient` — the `forms` surface — rather than the whole
+	 * `BiabClient`, because that is all this controller ever touches. Demanding
+	 * the full client was what forced `client as never` at the React call site:
+	 * the hook resolves a forms-shaped client from a provider or a token, which
+	 * is not a `BiabClient` and never needed to be. A full `BiabClient` still
+	 * satisfies this structurally, so existing callers are unaffected.
+	 */
+	client?: BiabFormsClient;
+	/** Form slug. Required when loading via `client`; optional with a pre-fetched
+	 *  `schema` that already carries its own `slug`. */
+	slug?: string;
+	/**
+	 * Pre-fetched schema (SSR / RSC). When provided, `load()` resolves
+	 * synchronously against it instead of hitting the network. `submit` /
+	 * `uploadFile` still require `client`.
+	 */
+	schema?: FormSchema;
+	/**
+	 * Default submit options merged into every `submit()` call (the call's own
+	 * options win per-key).
+	 */
+	submitOptions?: FormSubmitOptions;
+	/**
+	 * Called after a successful submit (result.ok === true). Fires before the
+	 * final snapshot notify so a binding can read the result in the same tick.
+	 */
+	onSuccess?: (result: Extract<FormSubmitResult, { ok: true }>) => void;
+	/** Called after a failed submit (result.ok === false). */
+	onError?: (result: Extract<FormSubmitResult, { ok: false }>) => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Snapshot — the immutable view a binding renders from. Re-created on each
+// notify; field names are STABLE and load-bearing for all 7 bindings.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type FormStatus = "idle" | "loading" | "ready" | "error";
+
+export interface FormSnapshot {
+	/** Lifecycle of the schema load. `ready` once fields are available. */
+	status: FormStatus;
+	/** Set when `status === "error"` (schema load failed). */
+	loadError: string | null;
+	/** The loaded schema (null until `ready`). */
+	schema: FormSchema | null;
+	/** Flat public field defs from the schema (convenience; the tree is `fields`). */
+	fieldDefs: FormFieldDef[];
+	/** The nested field tree to render (the authoritative render source). */
+	fields: FormCoreField[];
+	/** Resolved render settings (animation / steps / progress) with defaults. */
+	settings: ResolvedFormSettings;
+	/** Org icon URL when the form opted into `showOrgIcon`, else null. */
+	orgIcon: string | null;
+	/** Form title, when present. */
+	title: string | null;
+	/** Form description, when present. */
+	description: string | null;
+
+	/** Working values, keyed by field `id`. */
+	values: FormData;
+	/** Field-level validation errors, keyed by field `id` (for O(1) lookup). */
+	errors: Record<string, FieldError>;
+	/** Ordered list of current errors (same data as `errors`, render-friendly). */
+	errorList: FieldError[];
+
+	/** Steps: each entry is the field subtree for one step. In single-page mode
+	 *  there is exactly one step containing every field. */
+	steps: FormCoreField[][];
+	/** Zero-based index of the active step (clamped to a valid range). */
+	step: number;
+	/** Total number of steps (`steps.length`). */
+	stepCount: number;
+	/** True when on the first step. */
+	isFirstStep: boolean;
+	/** True when on the last step. */
+	isLastStep: boolean;
+	/** The field subtree for the active step (already condition-pruned for the
+	 *  top level — bindings still skip hidden `condition_block`s as they recurse). */
+	visibleFields: FormCoreField[];
+
+	/** 0–1 completion fraction = (step + 1) / stepCount. */
+	progress: number;
+	/** Whole-percent form of `progress` (0–100), convenient for width styles. */
+	progressPercent: number;
+
+	/** True when the active step has no missing-required / regex problems —
+	 *  drives the Next button's disabled state. */
+	canAdvance: boolean;
+	/** True when the WHOLE form passes required/regex checks — drives Submit. */
+	canSubmit: boolean;
+
+	/** Nav direction of the last step change (`true` = forward) — for slide anims. */
+	forward: boolean;
+
+	/** True while a `submit()` round-trip is in flight. */
+	submitting: boolean;
+	/** True while ANY field is uploading a file. */
+	uploading: boolean;
+	/** The most recent submit result (null until the first submit). */
+	result: FormSubmitResult | null;
+	/** True after a successful submit (result.ok === true). */
+	submitted: boolean;
+}
+
+/** Render settings after applying defaults. */
+export interface ResolvedFormSettings {
+	animation: NonNullable<FormRenderSettings["animation"]>;
+	isConsecutive: boolean;
+	showProgress: boolean;
+	progressStyle: NonNullable<FormRenderSettings["progressStyle"]>;
+	/** Warn before abandoning a dirty, unsubmitted form (undefined = off). */
+	exitConfirm?: { enabled?: boolean; message?: string };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Controller surface — the public contract the 7 bindings target verbatim.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface FormController {
+	/** Load (or adopt the pre-fetched) schema and seed initial values. Idempotent:
+	 *  safe to call again to re-fetch. Resolves once the schema is `ready` or
+	 *  `error`. */
+	load(): Promise<void>;
+	/** The current immutable snapshot. Cheap; returns the same object until the
+	 *  next mutation. */
+	snapshot(): FormSnapshot;
+	/** Subscribe to snapshot changes. Returns an unsubscribe fn. The callback is
+	 *  NOT invoked on subscribe — read `snapshot()` for the initial value. */
+	subscribe(callback: (snapshot: FormSnapshot) => void): () => void;
+	/** Set one field's value (keyed by field `id`). Clears that field's error and
+	 *  recomputes condition-driven visibility / advance gating. */
+	setValue(id: string, value: unknown): void;
+	/** Advance to the next step. No-op (and surfaces step errors) when the current
+	 *  step has missing-required / invalid fields, or already on the last step. */
+	next(): void;
+	/** Go back one step. No-op on the first step. */
+	back(): void;
+	/** Jump to a specific step index (clamped). Validates nothing — use for a
+	 *  progress-indicator click-back. */
+	goToStep(index: number): void;
+	/**
+	 * Validate the whole form, then submit via the SDK. Populates `errors` and
+	 * returns early (without a network call) when local validation fails. Always
+	 * resolves to a `FormSubmitResult` (never throws for an expected failure).
+	 */
+	submit(options?: FormSubmitOptions): Promise<FormSubmitResult>;
+	/**
+	 * Upload one file for a `file_upload` field via the SDK, append the resulting
+	 * `FormFileValue` to that field's value array, and return it. Throws on
+	 * plan-gate / transfer failure (mirrors `client.forms.uploadFile`).
+	 */
+	uploadFile(
+		fieldId: string,
+		file: File | Blob,
+		opts?: { filename?: string },
+	): Promise<FormFileValue>;
+	/** Re-run validation against the current values and publish `errors`. Returns
+	 *  the missing/invalid list (empty when valid). */
+	validate(): MissingField[];
+	/** Reset values to seeded defaults, clear errors / result, go to step 0. */
+	reset(): void;
+	/** Stop notifying and drop all subscribers. */
+	destroy(): void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_SETTINGS: ResolvedFormSettings = {
+	animation: "none",
+	isConsecutive: false,
+	showProgress: false,
+	progressStyle: "steps",
+};
+
+function resolveSettings(
+	settings: FormRenderSettings | undefined,
+): ResolvedFormSettings {
+	return {
+		animation: settings?.animation ?? DEFAULT_SETTINGS.animation,
+		isConsecutive: settings?.isConsecutive ?? DEFAULT_SETTINGS.isConsecutive,
+		showProgress: settings?.showProgress ?? DEFAULT_SETTINGS.showProgress,
+		progressStyle: settings?.progressStyle ?? DEFAULT_SETTINGS.progressStyle,
+		...(settings?.exitConfirm ? { exitConfirm: settings.exitConfirm } : {}),
+	};
+}
+
+/**
+ * Compute the step partition. Single-page → one step of all fields; consecutive
+ * → each top-level node is its own step (mirrors FormPreview's `steps`).
+ *
+ * A page whose `conditionRule` is currently false is DROPPED rather than left
+ * empty, so "Next" skips straight past it and the progress indicator loses its
+ * entry. Every renderer reads `stepCount` / `steps` from here, so this one
+ * change gives React, Svelte, Vue, Angular, Solid, Qwik and vanilla the same
+ * behaviour as the dashboard.
+ */
+function computeSteps(
+	fields: FormCoreField[],
+	isConsecutive: boolean,
+	data: FormData,
+): FormCoreField[][] {
+	if (!isConsecutive) return [fields];
+	return fields.filter((f) => isNodeVisible(f, data)).map((f) => [f]);
+}
+
+export function createFormController(
+	options: CreateFormControllerOptions,
+): FormController {
+	if (!options.client && !options.schema) {
+		throw new Error(
+			"createFormController: provide a `client` (with `slug`) or a pre-fetched `schema`.",
+		);
+	}
+	if (options.client && !options.slug && !options.schema?.slug) {
+		throw new Error(
+			"createFormController: `slug` is required when loading via `client`.",
+		);
+	}
+
+	const client = options.client;
+	const slug = options.slug ?? options.schema?.slug ?? "";
+
+	// ── Mutable internal state (never exposed directly) ──────────────────────
+	let status: FormStatus = "idle";
+	let loadError: string | null = null;
+	let schema: FormSchema | null = options.schema ?? null;
+	let fields: FormCoreField[] = [];
+	let settings: ResolvedFormSettings = DEFAULT_SETTINGS;
+	let values: FormData = {};
+	let errors: Record<string, FieldError> = {};
+	let step = 0;
+	let forward = true;
+	let submitting = false;
+	let uploadingCount = 0;
+	let result: FormSubmitResult | null = null;
+	let destroyed = false;
+
+	let cachedSnapshot: FormSnapshot | null = null;
+	const subscribers = new Set<(s: FormSnapshot) => void>();
+
+	// `calculation` field support: derived once per schema adopt.
+	let calcFields: FormCoreField[] = [];
+	let calcFunctionsById: Record<string, BusinessFunctionDef> = {};
+	let calcEvalOptions: EvalOptions = {};
+
+	/** Walk the field tree and collect every `calculation` node. */
+	function collectCalcFields(nodes: FormCoreField[]): FormCoreField[] {
+		const out: FormCoreField[] = [];
+		const walk = (ns: FormCoreField[]) => {
+			for (const n of ns) {
+				if (n.type === "calculation") out.push(n);
+				const kids = (n as { children?: FormCoreField[] }).children;
+				if (kids) walk(kids);
+			}
+		};
+		walk(nodes);
+		return out;
+	}
+
+	/** Recompute every `calculation` field into `vals`. Non-sensitive only — a
+	 *  sensitive function has no published def, so it resolves to null here and
+	 *  the server computes the authoritative value on submit. Idempotent. */
+	function applyCalcs(vals: FormData): FormData {
+		if (calcFields.length === 0) return vals;
+		let changed = false;
+		const next = { ...vals };
+		for (const f of calcFields) {
+			const cfg = (f as { calculationConfig?: CalculationConfig })
+				.calculationConfig;
+			if (!cfg) continue;
+			const r = computeCalculation(cfg, (id) => next[id], {
+				functionsById: calcFunctionsById,
+				evalOptions: calcEvalOptions,
+			});
+			const val = r.ok ? r.value : null;
+			if (JSON.stringify(next[f.id] ?? null) !== JSON.stringify(val ?? null)) {
+				next[f.id] = val;
+				changed = true;
+			}
+		}
+		return changed ? next : vals;
+	}
+
+	// ── Snapshot building ────────────────────────────────────────────────────
+	function buildSnapshot(): FormSnapshot {
+		const steps = computeSteps(fields, settings.isConsecutive, values);
+		const stepCount = Math.max(steps.length, 1);
+		const safeStep = Math.min(Math.max(step, 0), stepCount - 1);
+		const visibleFields = settings.isConsecutive
+			? (steps[safeStep] ?? [])
+			: fields;
+
+		const stepFields = steps[safeStep] ?? [];
+		const canAdvance = findMissingRequired(stepFields, values).length === 0;
+		const canSubmit = findMissingRequired(fields, values).length === 0;
+		const errorList = Object.values(errors);
+		const progress = stepCount > 0 ? (safeStep + 1) / stepCount : 0;
+
+		return {
+			status,
+			loadError,
+			schema,
+			fieldDefs: (schema?.fields ?? []) as FormFieldDef[],
+			fields,
+			settings,
+			orgIcon: schema?.orgIcon ?? null,
+			title: schema?.title ?? null,
+			description: schema?.description ?? null,
+			values,
+			errors,
+			errorList,
+			steps,
+			step: safeStep,
+			stepCount,
+			isFirstStep: safeStep === 0,
+			isLastStep: safeStep === stepCount - 1,
+			visibleFields,
+			progress,
+			progressPercent: Math.round(progress * 100),
+			canAdvance,
+			canSubmit,
+			forward,
+			submitting,
+			uploading: uploadingCount > 0,
+			result,
+			submitted: result?.ok === true,
+		};
+	}
+
+	function notify(): void {
+		if (destroyed) return;
+		cachedSnapshot = buildSnapshot();
+		for (const cb of subscribers) cb(cachedSnapshot);
+	}
+
+	function snapshot(): FormSnapshot {
+		if (!cachedSnapshot) cachedSnapshot = buildSnapshot();
+		return cachedSnapshot;
+	}
+
+	// ── Error helpers ────────────────────────────────────────────────────────
+	function setErrorsFromMissing(missing: MissingField[]): void {
+		const next: Record<string, FieldError> = {};
+		for (const m of missing) {
+			next[m.id] = {
+				id: m.id,
+				label: m.label,
+				message: `${m.label} is required.`,
+			};
+		}
+		errors = next;
+	}
+
+	// ── Field tree extraction ────────────────────────────────────────────────
+	function adoptSchema(loaded: FormSchema): void {
+		schema = loaded;
+		// The published schema's `fields` carries the full nested tree (layout
+		// nodes, condition_block, or_condition, children, output `key`).
+		fields = (loaded.fields ?? []) as unknown as FormCoreField[];
+		settings = resolveSettings(loaded.settings);
+		// Build the calculation context from the schema's (non-sensitive) functions.
+		calcFields = collectCalcFields(fields);
+		calcFunctionsById = {};
+		const bySlug: Record<string, BusinessFunctionDef> = {};
+		for (const fn of loaded.businessFunctions ?? []) {
+			const def = {
+				slug: fn.slug,
+				inputs: fn.inputs,
+				outputs: fn.outputs,
+			} as BusinessFunctionDef;
+			calcFunctionsById[fn.id] = def;
+			bySlug[fn.slug.toUpperCase()] = def;
+		}
+		calcEvalOptions = functionsToEvalOptions(bySlug);
+		values = applyCalcs(seedInitialData(fields));
+		errors = {};
+		step = 0;
+		forward = true;
+		result = null;
+		status = "ready";
+		loadError = null;
+	}
+
+	// ── Public methods ─────────────────────────────────────────────────────
+	async function load(): Promise<void> {
+		// Revive on (re)load. `load()` is idempotent and "safe to call again",
+		// and React StrictMode runs effects mount → cleanup → mount: the cleanup
+		// calls `destroy()` (sets `destroyed = true`), so the remount's `load()`
+		// must reset the flag or it would bail here and the form would hang on
+		// "loading" forever — even after the schema fetch returns 200. A genuine
+		// unmount never calls `load()` again, so reviving here is safe.
+		destroyed = false;
+		// Pre-fetched schema path: adopt synchronously.
+		if (options.schema && status === "idle") {
+			adoptSchema(options.schema);
+			notify();
+			return;
+		}
+		if (!client) {
+			// No client and no (further) schema — nothing to load.
+			if (schema && status !== "ready") {
+				adoptSchema(schema);
+				notify();
+			}
+			return;
+		}
+		status = "loading";
+		loadError = null;
+		notify();
+		try {
+			const loaded = await client.forms.schema(slug);
+			if (destroyed) return;
+			adoptSchema(loaded);
+			notify();
+		} catch (err) {
+			if (destroyed) return;
+			status = "error";
+			loadError =
+				err instanceof Error ? err.message : "Failed to load the form schema.";
+			notify();
+		}
+	}
+
+	function subscribe(callback: (s: FormSnapshot) => void): () => void {
+		subscribers.add(callback);
+		return () => {
+			subscribers.delete(callback);
+		};
+	}
+
+	function setValue(id: string, value: unknown): void {
+		// Recompute calc fields after the change so derived values stay live and
+		// flow into the submission + downstream conditions.
+		values = applyCalcs({ ...values, [id]: value });
+		if (errors[id]) {
+			const { [id]: _removed, ...rest } = errors;
+			errors = rest;
+		}
+		notify();
+	}
+
+	function validate(): MissingField[] {
+		const missing = findMissingRequired(fields, values);
+		setErrorsFromMissing(missing);
+		notify();
+		return missing;
+	}
+
+	function next(): void {
+		const steps = computeSteps(fields, settings.isConsecutive, values);
+		const stepCount = Math.max(steps.length, 1);
+		const safeStep = Math.min(Math.max(step, 0), stepCount - 1);
+		if (safeStep >= stepCount - 1) return;
+		const stepFields = steps[safeStep] ?? [];
+		const missing = findMissingRequired(stepFields, values);
+		if (missing.length > 0) {
+			setErrorsFromMissing(missing);
+			notify();
+			return;
+		}
+		errors = {};
+		forward = true;
+		step = safeStep + 1;
+		notify();
+	}
+
+	function back(): void {
+		const safeStep = Math.max(step, 0);
+		if (safeStep <= 0) return;
+		forward = false;
+		step = safeStep - 1;
+		errors = {};
+		notify();
+	}
+
+	function goToStep(index: number): void {
+		const steps = computeSteps(fields, settings.isConsecutive, values);
+		const stepCount = Math.max(steps.length, 1);
+		const target = Math.min(Math.max(index, 0), stepCount - 1);
+		forward = target >= step;
+		step = target;
+		notify();
+	}
+
+	async function submit(
+		callOptions?: FormSubmitOptions,
+	): Promise<FormSubmitResult> {
+		// Validate the WHOLE form (not just the visible step).
+		const missing = findMissingRequired(fields, values);
+		if (missing.length > 0) {
+			setErrorsFromMissing(missing);
+			const failure: FormSubmitResult = {
+				ok: false,
+				status: 0,
+				reason: "client_validation_failed",
+				message: `Please complete the required field${
+					missing.length === 1 ? "" : "s"
+				}: ${missing.map((m) => m.label).join(", ")}`,
+				issues: missing.map((m) => ({
+					fieldId: m.id,
+					label: m.label,
+					reason: "required" as const,
+					message: `${m.label} is required.`,
+				})),
+			};
+			result = failure;
+			notify();
+			options.onError?.(failure);
+			return failure;
+		}
+
+		if (!client) {
+			const failure: FormSubmitResult = {
+				ok: false,
+				status: 0,
+				reason: "network_error",
+				message:
+					"createFormController: a `client` is required to submit. Pass one in options.",
+			};
+			result = failure;
+			notify();
+			options.onError?.(failure);
+			return failure;
+		}
+
+		// Form-wide file cap — at most FORM_WIDE_MAX_FILES across all file fields.
+		const fileFields = collectFileFields(fields);
+		const totalFiles = fileFields.reduce(
+			(n, f) =>
+				n +
+				(Array.isArray(values[f.id]) ? (values[f.id] as unknown[]).length : 0),
+			0,
+		);
+		if (totalFiles > FORM_WIDE_MAX_FILES) {
+			const over = fileFields.filter(
+				(f) =>
+					Array.isArray(values[f.id]) && (values[f.id] as unknown[]).length > 0,
+			);
+			const issues: FormValidationIssue[] = over.map((f) => ({
+				fieldId: f.id,
+				label: f.label ?? "Files",
+				reason: "max" as const,
+				message: `At most ${FORM_WIDE_MAX_FILES} files total.`,
+			}));
+			setErrorsFromMissing(
+				over.map((f) => ({ id: f.id, label: f.label ?? "Files" })),
+			);
+			const failure: FormSubmitResult = {
+				ok: false,
+				status: 0,
+				reason: "client_validation_failed",
+				message: `Please attach at most ${FORM_WIDE_MAX_FILES} files in total.`,
+				issues,
+			};
+			result = failure;
+			notify();
+			options.onError?.(failure);
+			return failure;
+		}
+
+		errors = {};
+		submitting = true;
+		notify();
+
+		// Flush DEFERRED uploads: every buffered PendingFileValue is uploaded now
+		// and replaced by its FormFileValue. A failed upload aborts the submit and
+		// surfaces as a field error rather than silently dropping the file.
+		const uploadIssues: FormValidationIssue[] = [];
+		for (const f of fileFields) {
+			const arr = Array.isArray(values[f.id])
+				? (values[f.id] as unknown[])
+				: [];
+			const pending = arr.filter(isPendingFileValue);
+			if (pending.length === 0) continue;
+			const done = arr.filter((e) => !isPendingFileValue(e)) as FormFileValue[];
+			for (const p of pending) {
+				try {
+					uploadingCount += 1;
+					notify();
+					done.push(
+						await requireUploadFile(client)(slug, f.id, p.file, {
+							filename: p.name,
+						}),
+					);
+				} catch (err) {
+					uploadIssues.push({
+						fieldId: f.id,
+						label: f.label ?? "Files",
+						reason: "type" as const,
+						message:
+							err instanceof Error
+								? err.message
+								: `Couldn't upload a file for ${f.label}.`,
+					});
+				} finally {
+					uploadingCount = Math.max(uploadingCount - 1, 0);
+				}
+			}
+			values = { ...values, [f.id]: done };
+		}
+		if (uploadIssues.length > 0) {
+			submitting = false;
+			const next: Record<string, FieldError> = {};
+			for (const issue of uploadIssues) {
+				if (issue.fieldId) {
+					next[issue.fieldId] = {
+						id: issue.fieldId,
+						label: issue.label,
+						message: issue.message,
+					};
+				}
+			}
+			errors = next;
+			const failure: FormSubmitResult = {
+				ok: false,
+				status: 0,
+				reason: "network_error",
+				message: "Some files couldn't be uploaded — please retry.",
+				issues: uploadIssues,
+			};
+			result = failure;
+			notify();
+			options.onError?.(failure);
+			return failure;
+		}
+
+		// Re-key by the published output key for the wire contract (server also
+		// accepts the legacy `id`).
+		const payload = toSubmissionPayload(fields, values);
+		const merged: FormSubmitOptions = {
+			...options.submitOptions,
+			...callOptions,
+		};
+		let res: FormSubmitResult;
+		try {
+			res = await client.forms.submit(slug, payload, merged);
+		} catch (err) {
+			// `forms.submit` is designed never to throw for an expected failure;
+			// this guards against an unexpected transport error.
+			res = {
+				ok: false,
+				status: 0,
+				reason: "network_error",
+				message: err instanceof Error ? err.message : "The submission failed.",
+			};
+		}
+		if (destroyed) return res;
+		submitting = false;
+		result = res;
+		// Surface server-side field issues back onto `errors` for inline display.
+		if (!res.ok && res.issues && res.issues.length > 0) {
+			const next: Record<string, FieldError> = {};
+			for (const issue of res.issues) {
+				if (!issue.fieldId) continue;
+				next[issue.fieldId] = {
+					id: issue.fieldId,
+					label: issue.label,
+					message: issue.message,
+				};
+			}
+			errors = next;
+		}
+		notify();
+		if (res.ok) options.onSuccess?.(res);
+		else options.onError?.(res);
+		return res;
+	}
+
+	async function uploadFile(
+		fieldId: string,
+		file: File | Blob,
+		opts?: { filename?: string },
+	): Promise<FormFileValue> {
+		if (!client) {
+			throw new Error(
+				"createFormController: a `client` is required to upload files.",
+			);
+		}
+		uploadingCount += 1;
+		notify();
+		try {
+			const uploaded = await requireUploadFile(client)(
+				slug,
+				fieldId,
+				file,
+				opts,
+			);
+			if (destroyed) return uploaded;
+			const existing = Array.isArray(values[fieldId])
+				? (values[fieldId] as FormFileValue[])
+				: [];
+			values = { ...values, [fieldId]: [...existing, uploaded] };
+			if (errors[fieldId]) {
+				const { [fieldId]: _removed, ...rest } = errors;
+				errors = rest;
+			}
+			return uploaded;
+		} finally {
+			uploadingCount = Math.max(uploadingCount - 1, 0);
+			if (!destroyed) notify();
+		}
+	}
+
+	function reset(): void {
+		values = seedInitialData(fields);
+		errors = {};
+		step = 0;
+		forward = true;
+		result = null;
+		submitting = false;
+		notify();
+	}
+
+	function destroy(): void {
+		destroyed = true;
+		subscribers.clear();
+	}
+
+	// Seed an initial snapshot so `snapshot()` is valid pre-load.
+	cachedSnapshot = buildSnapshot();
+
+	return {
+		load,
+		snapshot,
+		subscribe,
+		setValue,
+		next,
+		back,
+		goToStep,
+		submit,
+		uploadFile,
+		validate,
+		reset,
+		destroy,
+	};
+}
+
+export type { FormConditionRule };
+// Re-export the condition primitives bindings commonly need when they render
+// the tree themselves (e.g. deciding whether to show a condition_block child).
+export {
+	concurrentRevealCount,
+	evalCondition,
+	findMissingRequired,
+	isNodeVisible,
+	seedInitialData,
+};