@businessdash/sdk 0.9.60

package/src/vanilla.ts

@@ -0,0 +1,1290 @@
+/**
+ * `@businessdash/sdk/vanilla` — framework-free imperative DOM binding for `<BiabForm>`.
+ *
+ * `mountBiabForm(elOrSelector, opts)` mounts a fully-rendered, schema-driven form
+ * into any DOM node. It owns nothing of the form's logic — all of that lives in
+ * the headless `createFormController` core (`@businessdash/sdk/forms`). This binding
+ * is the "render layer": it subscribes to the controller's `snapshot()` and, on
+ * every notify, rebuilds the form's DOM by walking `snapshot.visibleFields` and
+ * dispatching per field `type`. It is a faithful port of the dashboard renderer
+ * (`FormPreview.tsx`) so a drop-in `<biab-form>` reproduces the builder preview.
+ *
+ * Rendering rules (kept identical to the dashboard):
+ *   - Light DOM, no shadow root, so the consumer's CSS cascades straight in.
+ *   - Stable `biab-*` class hooks + `data-biab-*` attributes on every node.
+ *   - Applies `schema.settings`: animation (none/fade/slide/scale/scroll),
+ *     multi-step ("consecutive") nav, progress bar/steps, concurrent-reveal
+ *     gating inside groups, plus the org icon when `showOrgIcon` is set.
+ *   - condition_block / or_condition / input_group / flex_row layout nodes are
+ *     walked exactly as the core's validation helpers expect.
+ *
+ * Compiled to dist (plain TS, no JSX). The web-component binding
+ * (`@businessdash/sdk/element`) wraps this same `mountBiabForm`.
+ */
+
+import {
+	type AutocompleteConfig,
+	resolveFieldAutocomplete,
+} from "./forms-core/autocomplete.js";
+import {
+	type CreateFormControllerOptions,
+	concurrentRevealCount,
+	createFormController,
+	evalCondition,
+	type FormController,
+	type FormCoreField,
+	type FormData,
+	type FormSnapshot,
+	type FormSubmitOptions,
+} from "./forms-core/index.js";
+import type {
+	BiabClient,
+	FormFileValue,
+	FormSchema,
+	FormSubmitResult,
+} from "./sdk.js";
+
+// Re-export the core so consumers can reach the controller through this subpath.
+export * from "./forms-core/index.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public mount options — the consistent component API across every binding.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface MountBiabFormOptions {
+	/** The SDK client. Required unless `schema` is supplied (SSR / pre-fetched).
+	 *  Still used for `submit` / `uploadFile` when both are given. */
+	client?: BiabClient;
+	/** Form slug. Required when loading via `client`. */
+	slug?: string;
+	/** Pre-fetched schema (SSR). `load()` adopts it synchronously. */
+	schema?: FormSchema;
+	/** Label for the final submit button. Default "Submit". */
+	submitLabel?: string;
+	/** Validate on the server but store nothing (no side effects). */
+	dryRun?: boolean;
+	/** Extra class(es) added to the root `.biab-form` element. */
+	class?: string;
+	/** Alias for `class` — accepted for cross-framework parity. */
+	className?: string;
+	/** Default submit options merged into every submit (call opts win). */
+	submitOptions?: FormSubmitOptions;
+	/** Global HTML autofill switch. Omit to infer a sensible `autocomplete`
+	 *  token per field; `false` emits `autocomplete="off"` on every input. */
+	autoComplete?: boolean;
+	/** Per-field autofill overrides keyed by field id: a literal token,
+	 *  `true` (infer), or `false` (off). Wins over the global switch. */
+	fieldAutoComplete?: Record<string, string | boolean>;
+	/** Fired with the working values when the user submits (before the network
+	 *  round-trip is mapped to a result). Convenience for simple consumers. */
+	onSubmit?: (data: FormData) => void;
+	/** Fired after a successful submit. */
+	onSuccess?: (result: Extract<FormSubmitResult, { ok: true }>) => void;
+	/** Fired after a failed submit. */
+	onError?: (result: Extract<FormSubmitResult, { ok: false }>) => void;
+}
+
+/** Handle returned by `mountBiabForm` — drive or tear down the mounted form. */
+export interface BiabFormInstance {
+	/** The underlying headless controller (advanced use). */
+	controller: FormController;
+	/** Re-fetch (or re-adopt) the schema and re-render. */
+	reload(): Promise<void>;
+	/** Programmatically submit (same as clicking the submit button). */
+	submit(options?: FormSubmitOptions): Promise<FormSubmitResult>;
+	/** Reset values / errors / step and re-render. */
+	reset(): void;
+	/** Unsubscribe, stop the controller, and clear the host element. */
+	destroy(): void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tiny DOM helpers (no framework, no deps).
+// ─────────────────────────────────────────────────────────────────────────────
+
+type Attrs = Record<string, string | number | boolean | null | undefined>;
+type Child = Node | string | null | undefined | false;
+
+function el(
+	tag: string,
+	attrs: Attrs = {},
+	children: Child[] = [],
+): HTMLElement {
+	const node = document.createElement(tag);
+	for (const [k, v] of Object.entries(attrs)) {
+		if (v == null || v === false) continue;
+		if (k === "class") node.className = String(v);
+		else if (v === true) node.setAttribute(k, "");
+		else node.setAttribute(k, String(v));
+	}
+	for (const child of children) {
+		if (child == null || child === false) continue;
+		node.append(
+			typeof child === "string" ? document.createTextNode(child) : child,
+		);
+	}
+	return node;
+}
+
+function classNames(
+	...parts: Array<string | false | null | undefined>
+): string {
+	return parts.filter(Boolean).join(" ");
+}
+
+/** Escape a value for use inside a `[data-field-id="…"]` attribute selector. */
+function cssEscape(value: string): string {
+	const cssApi = (globalThis as { CSS?: { escape?: (v: string) => string } })
+		.CSS;
+	if (cssApi && typeof cssApi.escape === "function")
+		return cssApi.escape(value);
+	// Field ids are UUIDs/slugs, but quote-escape defensively as a fallback.
+	return value.replace(/["\\]/g, "\\$&");
+}
+
+/** Stable, override-friendly CSS hook for a field (mirrors FormPreview.fieldCssKey).
+ *  Prefers the published output `key`, else the field id. */
+function fieldCssKey(field: FormCoreField): string {
+	const explicit =
+		(typeof field.outputKey === "string" && field.outputKey.trim()) ||
+		(typeof field.key === "string" && field.key.trim());
+	return explicit || field.id;
+}
+
+const NO_LABEL_TYPES = new Set(["title", "subtitle", "separator", "richtext"]);
+
+/** tw-style entrance class hook for the active step (consumer CSS animates these).
+ *  Matches the `biab-anim--*` convention so orgs can target each animation. */
+function animClass(animation: string, forward: boolean): string {
+	switch (animation) {
+		case "fade":
+			return "biab-anim biab-anim--fade";
+		case "scale":
+			return "biab-anim biab-anim--scale";
+		case "slide":
+			return forward
+				? "biab-anim biab-anim--slide biab-anim--slide-forward"
+				: "biab-anim biab-anim--slide biab-anim--slide-back";
+		default:
+			return "";
+	}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-field input rendering — dispatch by `type`, port of FormPreview.FieldInput.
+// Each input writes back to the controller via `set(value)`.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Set `autocomplete` only when a token is defined (omit the attribute on
+ *  `undefined`, never emit `autocomplete=""`). Mirrors the React renderer. */
+function setAutocomplete(el: HTMLElement, token: string | undefined): void {
+	if (token !== undefined) el.setAttribute("autocomplete", token);
+}
+
+function renderFieldInput(
+	field: FormCoreField,
+	snapshot: FormSnapshot,
+	set: (value: unknown) => void,
+	upload: (file: File) => void,
+	autoComplete: string | undefined,
+): HTMLElement | null {
+	const value = snapshot.values[field.id];
+	const str = typeof value === "string" ? value : "";
+	// Address composite suppresses its fixed sub-field tokens to "off" when the
+	// field's resolved token is "off" (global switch or per-field override).
+	const acOff = autoComplete === "off";
+
+	switch (field.type) {
+		case "title":
+			return el("h2", { class: "biab-field__title" }, [
+				field.label || "Untitled",
+			]);
+		case "subtitle":
+			return el("h3", { class: "biab-field__subtitle" }, [field.label || ""]);
+		case "separator":
+			return el("hr", { class: "biab-field__separator" });
+		case "richtext": {
+			if (!field.content) return null;
+			const div = el("div", { class: "biab-field__richtext biab-prose" });
+			// The published `content` is server-sanitized HTML.
+			div.innerHTML = field.content;
+			return div;
+		}
+		case "image": {
+			const cfg = (field["imageConfig"] ?? {}) as {
+				src?: string;
+				alt?: string;
+				width?: number;
+				height?: number;
+			};
+			if (!cfg.src) return null;
+			return el("img", {
+				class: "biab-field__image",
+				src: cfg.src,
+				alt: cfg.alt || "",
+				...(cfg.width ? { width: cfg.width } : {}),
+				...(cfg.height ? { height: cfg.height } : {}),
+			});
+		}
+		case "textarea": {
+			const cfg = (field["textareaConfig"] ?? {}) as {
+				rows?: number;
+				resizable?: boolean;
+			};
+			const node = el("textarea", {
+				class: classNames(
+					"biab-textarea",
+					cfg.resizable === false && "biab-textarea--fixed",
+				),
+				rows: cfg.rows ?? 4,
+				placeholder: field.placeholder || "",
+			}) as HTMLTextAreaElement;
+			setAutocomplete(node, autoComplete);
+			node.value = str;
+			node.addEventListener("input", () => set(node.value));
+			return node;
+		}
+		case "select": {
+			const node = el("select", { class: "biab-select" }) as HTMLSelectElement;
+			node.append(
+				el("option", { value: "" }, [field.placeholder || "Select..."]),
+			);
+			for (const opt of field.options ?? []) {
+				node.append(el("option", { value: opt }, [opt]));
+			}
+			node.value = str;
+			node.addEventListener("change", () => set(node.value));
+			return node;
+		}
+		case "radio": {
+			const wrap = el("div", { class: "biab-radio-group" });
+			for (const opt of field.options ?? []) {
+				const id = `${field.id}-${opt}`;
+				const input = el("input", {
+					class: "biab-radio",
+					type: "radio",
+					name: field.id,
+					id,
+					value: opt,
+				}) as HTMLInputElement;
+				input.checked = str === opt;
+				input.addEventListener("change", () => set(opt));
+				wrap.append(
+					el("label", { class: "biab-radio-option", for: id }, [
+						input,
+						el("span", {}, [opt]),
+					]),
+				);
+			}
+			return wrap;
+		}
+		case "checkbox": {
+			const arr = Array.isArray(value) ? (value as string[]) : [];
+			const wrap = el("div", { class: "biab-checkbox-group" });
+			for (const opt of field.options ?? []) {
+				const input = el("input", {
+					class: "biab-checkbox",
+					type: "checkbox",
+					value: opt,
+				}) as HTMLInputElement;
+				input.checked = arr.includes(opt);
+				input.addEventListener("change", () => {
+					const next = input.checked
+						? [...arr, opt]
+						: arr.filter((x) => x !== opt);
+					set(next);
+				});
+				wrap.append(
+					el("label", { class: "biab-checkbox-option" }, [
+						input,
+						el("span", {}, [opt]),
+					]),
+				);
+			}
+			return wrap;
+		}
+		case "boolean": {
+			const input = el("input", {
+				class: "biab-switch",
+				type: "checkbox",
+			}) as HTMLInputElement;
+			input.checked = value === true;
+			input.addEventListener("change", () => set(input.checked));
+			return el("label", { class: "biab-boolean" }, [
+				input,
+				el("span", { class: "biab-boolean__label" }, [
+					field.placeholder || "Yes / No",
+				]),
+			]);
+		}
+		case "date": {
+			const node = el("input", {
+				class: "biab-input",
+				type: "date",
+			}) as HTMLInputElement;
+			node.value = str;
+			node.addEventListener("input", () => set(node.value));
+			return node;
+		}
+		case "email": {
+			const node = el("input", {
+				class: "biab-input",
+				type: "email",
+				placeholder: field.placeholder || "you@example.com",
+			}) as HTMLInputElement;
+			setAutocomplete(node, autoComplete);
+			node.value = str;
+			node.addEventListener("input", () => set(node.value));
+			return node;
+		}
+		case "phone": {
+			const wrap = el("div", { class: "biab-phone" });
+			if (field.phoneConfig?.showFlags) {
+				wrap.append(
+					el("span", { class: "biab-phone__flag", "aria-hidden": "true" }, [
+						"\u{1F1FA}\u{1F1F8}",
+					]),
+				);
+			}
+			const node = el("input", {
+				class: "biab-input",
+				type: "tel",
+				placeholder:
+					field.placeholder ||
+					(field.phoneConfig?.international
+						? "+1 (555) 000-0000"
+						: "(555) 000-0000"),
+			}) as HTMLInputElement;
+			setAutocomplete(node, autoComplete);
+			node.value = str;
+			node.addEventListener("input", () => set(node.value));
+			wrap.append(node);
+			return wrap;
+		}
+		case "number": {
+			const node = el("input", {
+				class: "biab-input",
+				type: "number",
+				placeholder: field.placeholder || "",
+			}) as HTMLInputElement;
+			node.value = typeof value === "number" ? String(value) : str;
+			node.addEventListener("input", () => {
+				set(node.value === "" ? "" : Number(node.value));
+			});
+			return node;
+		}
+		case "stepper": {
+			const v = typeof value === "number" ? value : 0;
+			const out = el("span", { class: "biab-stepper__value" }, [String(v)]);
+			const minus = el(
+				"button",
+				{ class: "biab-btn biab-btn--ghost biab-stepper__btn", type: "button" },
+				["−"],
+			);
+			const plus = el(
+				"button",
+				{ class: "biab-btn biab-btn--ghost biab-stepper__btn", type: "button" },
+				["+"],
+			);
+			minus.addEventListener("click", () => set(v - 1));
+			plus.addEventListener("click", () => set(v + 1));
+			return el("div", { class: "biab-stepper" }, [minus, out, plus]);
+		}
+		case "slider": {
+			const min = field.sliderConfig?.min ?? 0;
+			const max = field.sliderConfig?.max ?? 100;
+			const step = field.sliderConfig?.step ?? 1;
+			const unit = field.sliderConfig?.unit;
+			const fmt = (n: number) =>
+				unit === "currency" ? `$${n}` : unit === "percent" ? `${n}%` : `${n}`;
+			const v = typeof value === "number" ? value : min;
+			const readout = el("span", { class: "biab-slider__value" }, [fmt(v)]);
+			const input = el("input", {
+				class: "biab-slider",
+				type: "range",
+				min,
+				max,
+				step,
+			}) as HTMLInputElement;
+			input.value = String(v);
+			input.addEventListener("input", () => {
+				const n = Number(input.value);
+				readout.textContent = fmt(n);
+				set(n);
+			});
+			return el("div", { class: "biab-slider-wrap" }, [
+				el("div", { class: "biab-slider__scale" }, [
+					el("span", {}, [fmt(min)]),
+					readout,
+					el("span", {}, [fmt(max)]),
+				]),
+				input,
+			]);
+		}
+		case "star_rating": {
+			const max = field.starRatingConfig?.maxStars ?? 5;
+			const v = typeof value === "number" ? value : 0;
+			const wrap = el("div", { class: "biab-stars" });
+			for (let i = 0; i < max; i++) {
+				const btn = el(
+					"button",
+					{
+						class: classNames("biab-star", i < v && "biab-star--filled"),
+						type: "button",
+						"aria-label": `${i + 1} star${i === 0 ? "" : "s"}`,
+					},
+					["★"],
+				);
+				btn.addEventListener("click", () => set(i + 1));
+				wrap.append(btn);
+			}
+			return wrap;
+		}
+		case "happiness_rating": {
+			const v = typeof value === "number" ? value : -1;
+			const wrap = el("div", { class: "biab-happiness" });
+			["\u{1F61E}", "\u{1F615}", "\u{1F610}", "\u{1F642}", "\u{1F604}"].forEach(
+				(emoji, i) => {
+					const btn = el(
+						"button",
+						{
+							class: classNames(
+								"biab-happiness__face",
+								i === v && "biab-happiness__face--active",
+							),
+							type: "button",
+						},
+						[emoji],
+					);
+					btn.addEventListener("click", () => set(i));
+					wrap.append(btn);
+				},
+			);
+			return wrap;
+		}
+		case "color_picker": {
+			const v = str;
+			const wrap = el("div", { class: "biab-colors" });
+			for (const color of field.options ?? []) {
+				const btn = el("button", {
+					class: classNames(
+						"biab-color",
+						v === color && "biab-color--selected",
+					),
+					type: "button",
+					title: color,
+					style: `background-color:${color}`,
+				});
+				btn.addEventListener("click", () => set(color));
+				wrap.append(btn);
+			}
+			return wrap;
+		}
+		case "date_range": {
+			const v =
+				value && typeof value === "object"
+					? (value as { start?: string; end?: string })
+					: { start: "", end: "" };
+			return twoField(
+				"Start",
+				v.start ?? "",
+				"End",
+				v.end ?? "",
+				"date",
+				(start, end) => set({ ...v, start, end }),
+			);
+		}
+		case "time_picker": {
+			const mode = field.timeConfig?.mode ?? "simple";
+			if (mode === "simple") {
+				const format = field.timeConfig?.format ?? "12h";
+				const step = Math.max(field.timeConfig?.stepMinutes ?? 30, 1);
+				const node = el("select", {
+					class: "biab-select",
+				}) as HTMLSelectElement;
+				node.append(
+					el("option", { value: "" }, [field.placeholder || "Select time"]),
+				);
+				for (let h = 0; h < 24; h++) {
+					for (let m = 0; m < 60; m += step) {
+						const t = `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}`;
+						const ampm = h < 12 ? "AM" : "PM";
+						const h12 = h % 12 === 0 ? 12 : h % 12;
+						const label =
+							format === "24h"
+								? t
+								: `${h12}:${String(m).padStart(2, "0")} ${ampm}`;
+						node.append(el("option", { value: t }, [label]));
+					}
+				}
+				node.value = str;
+				node.addEventListener("change", () => set(node.value));
+				return node;
+			}
+			if (mode === "time_block") {
+				const v =
+					value && typeof value === "object"
+						? (value as { start?: string; end?: string })
+						: { start: "", end: "" };
+				return twoField(
+					"Start",
+					v.start ?? "",
+					"End",
+					v.end ?? "",
+					"time",
+					(start, end) => set({ ...v, start, end }),
+				);
+			}
+			const v =
+				value && typeof value === "object"
+					? (value as { date?: string; time?: string })
+					: { date: "", time: "" };
+			return twoField(
+				"Date",
+				v.date ?? "",
+				"Time",
+				v.time ?? "",
+				["date", "time"],
+				(date, time) => set({ ...v, date, time }),
+			);
+		}
+		case "address": {
+			const v = (value && typeof value === "object" ? value : {}) as Record<
+				string,
+				string
+			>;
+			const grid = el("div", { class: "biab-address" });
+			// Fixed per-sub-field autofill tokens, suppressed to "off" when the
+			// composite's resolved token is "off". Mirrors the React renderer.
+			const part = (
+				key: string,
+				label: string,
+				token: string,
+				full = false,
+			) => {
+				const input = el("input", { class: "biab-input" }) as HTMLInputElement;
+				setAutocomplete(input, acOff ? "off" : token);
+				input.value = v[key] ?? "";
+				input.addEventListener("input", () =>
+					set({ ...v, [key]: input.value }),
+				);
+				return el(
+					"label",
+					{
+						class: classNames(
+							"biab-address__field",
+							full && "biab-address__field--full",
+						),
+					},
+					[el("span", { class: "biab-address__label" }, [label]), input],
+				);
+			};
+			grid.append(
+				part("line1", "Address Line 1", "street-address", true),
+				part("line2", "Address Line 2", "address-line2", true),
+				part("city", "City", "address-level2"),
+				part("state", "State", "address-level1"),
+				part("zip", "Zip", "postal-code", true),
+			);
+			return grid;
+		}
+		case "file_upload": {
+			const files = Array.isArray(value) ? (value as FormFileValue[]) : [];
+			const maxFiles = field.fileConfig?.maxFiles ?? 1;
+			const allowed = field.fileConfig?.allowedTypes;
+			const remaining = Math.max(maxFiles - files.length, 0);
+			const wrap = el("div", { class: "biab-file" });
+
+			const input = el("input", {
+				class: "biab-file__input",
+				type: "file",
+				...(maxFiles > 1 ? { multiple: true } : {}),
+				...(allowed && allowed.length > 0 ? { accept: allowed.join(",") } : {}),
+				style: "display:none",
+			}) as HTMLInputElement;
+			input.addEventListener("change", () => {
+				const picked = input.files;
+				if (picked) {
+					for (const f of Array.from(picked).slice(0, remaining)) upload(f);
+				}
+				input.value = "";
+			});
+
+			const trigger = el(
+				"button",
+				{
+					class: "biab-file__trigger",
+					type: "button",
+					...(snapshot.uploading || remaining === 0 ? { disabled: true } : {}),
+				},
+				[
+					snapshot.uploading
+						? "Uploading…"
+						: remaining === 0
+							? `Maximum ${maxFiles} file${maxFiles === 1 ? "" : "s"} reached`
+							: `Click to upload${maxFiles > 1 ? ` (up to ${remaining} more)` : ""}`,
+				],
+			);
+			trigger.addEventListener("click", () => input.click());
+			wrap.append(input, trigger);
+
+			if (files.length > 0) {
+				const list = el("ul", { class: "biab-file__list" });
+				files.forEach((f, idx) => {
+					const remove = el(
+						"button",
+						{
+							class: "biab-file__remove",
+							type: "button",
+							"aria-label": "Remove file",
+						},
+						["✕"],
+					);
+					remove.addEventListener("click", () =>
+						set(files.filter((_, i) => i !== idx)),
+					);
+					list.append(
+						el("li", { class: "biab-file__item" }, [
+							el("span", { class: "biab-file__name" }, [f.name]),
+							el("span", { class: "biab-file__size" }, [
+								`${Math.round(f.size / 1024)} KB`,
+							]),
+							remove,
+						]),
+					);
+				});
+				wrap.append(list);
+			}
+			return wrap;
+		}
+		default: {
+			const node = el("input", {
+				class: "biab-input",
+				type: "text",
+				placeholder: field.placeholder || "",
+			}) as HTMLInputElement;
+			setAutocomplete(node, autoComplete);
+			node.value = str;
+			node.addEventListener("input", () => set(node.value));
+			return node;
+		}
+	}
+}
+
+/** Two side-by-side labelled inputs (used for date_range / time_block / appointment). */
+function twoField(
+	leftLabel: string,
+	leftValue: string,
+	rightLabel: string,
+	rightValue: string,
+	type: string | [string, string],
+	onChange: (left: string, right: string) => void,
+): HTMLElement {
+	const [lt, rt] = Array.isArray(type) ? type : [type, type];
+	const left = el("input", {
+		class: "biab-input",
+		type: lt,
+	}) as HTMLInputElement;
+	const right = el("input", {
+		class: "biab-input",
+		type: rt,
+	}) as HTMLInputElement;
+	left.value = leftValue;
+	right.value = rightValue;
+	left.addEventListener("input", () => onChange(left.value, right.value));
+	right.addEventListener("input", () => onChange(left.value, right.value));
+	return el("div", { class: "biab-grid biab-grid--2" }, [
+		el("label", { class: "biab-grid__cell" }, [
+			el("span", { class: "biab-grid__label" }, [leftLabel]),
+			left,
+		]),
+		el("label", { class: "biab-grid__cell" }, [
+			el("span", { class: "biab-grid__label" }, [rightLabel]),
+			right,
+		]),
+	]);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Field row + tree walk — port of FormPreview.FieldRow / RenderTree.
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface RenderCtx {
+	snapshot: FormSnapshot;
+	setValue: (id: string, value: unknown) => void;
+	upload: (fieldId: string, file: File) => void;
+	/** Global + per-field autofill config, threaded from the mount options. */
+	autocompleteConfig: AutocompleteConfig;
+}
+
+function renderFieldRow(
+	field: FormCoreField,
+	ctx: RenderCtx,
+	flat: boolean,
+): HTMLElement {
+	const errored = Boolean(ctx.snapshot.errors[field.id]);
+	const showLabel = !NO_LABEL_TYPES.has(field.type);
+	const children: Child[] = [];
+
+	if (showLabel && field.label) {
+		children.push(
+			el("label", { class: "biab-field__label" }, [
+				field.label,
+				field.required
+					? el("span", { class: "biab-field__required" }, [" *"])
+					: null,
+			]),
+		);
+	}
+
+	const input = renderFieldInput(
+		field,
+		ctx.snapshot,
+		(v) => ctx.setValue(field.id, v),
+		(file) => ctx.upload(field.id, file),
+		resolveFieldAutocomplete(field, ctx.autocompleteConfig),
+	);
+	if (input) children.push(input);
+
+	if (errored) {
+		children.push(
+			el("p", { class: "biab-field__error" }, [
+				ctx.snapshot.errors[field.id]?.message ?? "This field is required.",
+			]),
+		);
+	}
+	if (field.helpText) {
+		children.push(el("p", { class: "biab-field__help" }, [field.helpText]));
+	}
+
+	// `flat` is accepted for signature parity with the group renderer; rows look
+	// the same flat or nested.
+	void flat;
+	return el(
+		"div",
+		{
+			class: classNames(
+				"biab-field",
+				`biab-field--${field.type}`,
+				field.required && "biab-field--required",
+				errored && "biab-field--error",
+			),
+			"data-field-id": field.id,
+			"data-biab-field": fieldCssKey(field),
+			"data-biab-type": field.type,
+		},
+		children,
+	);
+}
+
+/** Recursively render a list of fields, handling every layout/condition node. */
+function renderTree(
+	fields: FormCoreField[],
+	ctx: RenderCtx,
+	flat: boolean,
+): HTMLElement {
+	const container = el("div", { class: "biab-tree" });
+
+	for (const field of fields) {
+		if (field.type === "input_group") {
+			const groupChildren = (field.children ?? []) as FormCoreField[];
+			const concurrent = field.concurrentReveal === true;
+			const revealCount = concurrent
+				? concurrentRevealCount(groupChildren, ctx.snapshot.values)
+				: groupChildren.length;
+			const visible = concurrent
+				? groupChildren.slice(0, revealCount)
+				: groupChildren;
+			const groupNode = el(
+				"div",
+				{
+					class: classNames(
+						"biab-group",
+						flat ? "biab-group--flat" : "biab-group--card",
+					),
+					"data-biab-group": fieldCssKey(field),
+				},
+				[],
+			);
+			if (field.label && field.showGroupLabel === true) {
+				groupNode.append(
+					el("div", { class: "biab-group__label" }, [field.label]),
+				);
+			}
+			groupNode.append(renderTree(visible, ctx, flat));
+			container.append(groupNode);
+			continue;
+		}
+
+		if (field.type === "condition_block") {
+			if (!evalCondition(field.conditionRule, ctx.snapshot.values)) continue;
+			container.append(
+				renderTree((field.children ?? []) as FormCoreField[], ctx, flat),
+			);
+			continue;
+		}
+
+		if (field.type === "or_condition") {
+			const errored = Boolean(ctx.snapshot.errors[field.id]);
+			const left = field.children?.[0];
+			const right = field.children?.[1];
+			const box = el(
+				"div",
+				{ class: classNames("biab-or", errored && "biab-or--error") },
+				[],
+			);
+			if (field.label) {
+				box.append(
+					el("div", { class: "biab-or__label" }, [
+						field.label,
+						el("span", { class: "biab-or__hint" }, [" Fill at least one side"]),
+					]),
+				);
+			}
+			const grid = el("div", { class: "biab-or__grid" }, [
+				el("div", { class: "biab-or__side" }, [
+					el("div", { class: "biab-or__side-label" }, [
+						field.orConditionConfig?.leftLabel || "Option A",
+					]),
+					left ? renderTree([left], ctx, flat) : null,
+				]),
+				el("div", { class: "biab-or__divider" }, [
+					el("span", { class: "biab-or__badge" }, ["OR"]),
+				]),
+				el("div", { class: "biab-or__side" }, [
+					el("div", { class: "biab-or__side-label" }, [
+						field.orConditionConfig?.rightLabel || "Option B",
+					]),
+					right ? renderTree([right], ctx, flat) : null,
+				]),
+			]);
+			box.append(grid);
+			if (errored) {
+				box.append(
+					el("p", { class: "biab-or__error" }, [
+						"Fill in at least one side to continue.",
+					]),
+				);
+			}
+			container.append(box);
+			continue;
+		}
+
+		if (field.type === "flex_row") {
+			const row = el("div", { class: "biab-flex-row" }, []);
+			for (const child of (field.children ?? []) as FormCoreField[]) {
+				row.append(
+					el("div", { class: "biab-flex-row__cell" }, [
+						renderFieldRow(child, ctx, flat),
+					]),
+				);
+			}
+			container.append(row);
+			continue;
+		}
+
+		container.append(renderFieldRow(field, ctx, flat));
+	}
+
+	return container;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Progress indicators — port of FormPreview's steps / bar variants.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function renderProgress(
+	snapshot: FormSnapshot,
+	onJump: (i: number) => void,
+): HTMLElement | null {
+	const { settings, steps, step, stepCount } = snapshot;
+	if (!settings.isConsecutive || !settings.showProgress || stepCount <= 1)
+		return null;
+
+	if (settings.progressStyle === "bar") {
+		const fill = el("div", { class: "biab-progress__fill" });
+		fill.style.width = `${((step + 1) / stepCount) * 100}%`;
+		return el("div", { class: "biab-progress biab-progress--bar" }, [
+			el("span", { class: "biab-progress__count" }, [
+				`${step + 1} / ${stepCount}`,
+			]),
+			el("div", { class: "biab-progress__track" }, [fill]),
+		]);
+	}
+
+	const track = el("div", { class: "biab-progress__steps" });
+	steps.forEach((s, i) => {
+		const f = s[0];
+		const title =
+			(typeof f?.stepTitle === "string" && f.stepTitle) ||
+			f?.label ||
+			`Step ${i + 1}`;
+		const done = i < step;
+		const current = i === step;
+		if (i > 0) {
+			track.append(
+				el("div", {
+					class: classNames(
+						"biab-progress__line",
+						i <= step && "biab-progress__line--done",
+					),
+				}),
+			);
+		}
+		const dot = el(
+			"span",
+			{
+				class: classNames(
+					"biab-progress__dot",
+					current && "biab-progress__dot--current",
+					done && "biab-progress__dot--done",
+				),
+			},
+			[done ? "✓" : String(i + 1)],
+		);
+		const stepNode = el(
+			"button",
+			{
+				class: classNames(
+					"biab-progress__step",
+					current && "biab-progress__step--current",
+				),
+				type: "button",
+			},
+			[dot, el("span", { class: "biab-progress__title" }, [title])],
+		);
+		stepNode.addEventListener("click", () => onJump(i));
+		track.append(stepNode);
+	});
+
+	return el("div", { class: "biab-progress biab-progress--steps" }, [
+		el("div", { class: "biab-progress__heading" }, ["Form Progress"]),
+		track,
+	]);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// mountBiabForm — wire a controller to a host element and render reactively.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function resolveHost(elOrSelector: Element | string): HTMLElement {
+	const host =
+		typeof elOrSelector === "string"
+			? document.querySelector(elOrSelector)
+			: elOrSelector;
+	if (!host) {
+		throw new Error(
+			`mountBiabForm: no element found for ${typeof elOrSelector === "string" ? `selector "${elOrSelector}"` : "the provided node"}.`,
+		);
+	}
+	return host as HTMLElement;
+}
+
+export function mountBiabForm(
+	elOrSelector: Element | string,
+	opts: MountBiabFormOptions,
+): BiabFormInstance {
+	const host = resolveHost(elOrSelector);
+	const extraClass = opts.class ?? opts.className;
+
+	// HTML autofill config built from the mount options, threaded to every field.
+	const autocompleteConfig: AutocompleteConfig = {
+		...(opts.autoComplete !== undefined ? { enabled: opts.autoComplete } : {}),
+		...(opts.fieldAutoComplete ? { overrides: opts.fieldAutoComplete } : {}),
+	};
+
+	const controllerOptions: CreateFormControllerOptions = {
+		...(opts.client ? { client: opts.client } : {}),
+		...(opts.slug ? { slug: opts.slug } : {}),
+		...(opts.schema ? { schema: opts.schema } : {}),
+		...(opts.submitOptions ? { submitOptions: opts.submitOptions } : {}),
+		...(opts.onSuccess ? { onSuccess: opts.onSuccess } : {}),
+		...(opts.onError ? { onError: opts.onError } : {}),
+	};
+	const controller = createFormController(controllerOptions);
+
+	const doSubmit = (
+		callOpts?: FormSubmitOptions,
+	): Promise<FormSubmitResult> => {
+		opts.onSubmit?.(controller.snapshot().values);
+		const merged: FormSubmitOptions = {
+			...(opts.dryRun ? { dryRun: true } : {}),
+			...callOpts,
+		};
+		return controller.submit(merged);
+	};
+
+	/** Swap the host's content, preserving focus + caret across the rebuild.
+	 *  Every notify re-renders the whole tree (conditions / reveal change which
+	 *  fields exist), which would otherwise steal focus mid-typing. We re-locate
+	 *  the focused input by its owning field row + ordinal and restore the caret. */
+	function swap(root: HTMLElement): void {
+		const active = document.activeElement;
+		let restore: {
+			fieldId: string;
+			index: number;
+			start: number | null;
+			end: number | null;
+		} | null = null;
+		if (
+			active &&
+			host.contains(active) &&
+			(active instanceof HTMLInputElement ||
+				active instanceof HTMLTextAreaElement ||
+				active instanceof HTMLSelectElement)
+		) {
+			const row = active.closest("[data-field-id]") as HTMLElement | null;
+			const fieldId = row?.getAttribute("data-field-id");
+			if (fieldId && row) {
+				const inputs = Array.from(
+					row.querySelectorAll("input, textarea, select"),
+				);
+				const index = inputs.indexOf(active);
+				const canCaret =
+					active instanceof HTMLInputElement ||
+					active instanceof HTMLTextAreaElement;
+				restore = {
+					fieldId,
+					index,
+					start: canCaret ? active.selectionStart : null,
+					end: canCaret ? active.selectionEnd : null,
+				};
+			}
+		}
+
+		host.replaceChildren(root);
+
+		if (restore) {
+			const row = host.querySelector(
+				`[data-field-id="${cssEscape(restore.fieldId)}"]`,
+			);
+			const inputs = row
+				? Array.from(row.querySelectorAll("input, textarea, select"))
+				: [];
+			const next = inputs[restore.index] as HTMLElement | undefined;
+			if (next) {
+				next.focus();
+				if (
+					restore.start != null &&
+					(next instanceof HTMLInputElement ||
+						next instanceof HTMLTextAreaElement)
+				) {
+					try {
+						next.setSelectionRange(restore.start, restore.end ?? restore.start);
+					} catch {
+						// `setSelectionRange` throws on input types that don't support it
+						// (e.g. number / email / date) — focus alone is enough there.
+					}
+				}
+			}
+		}
+	}
+
+	function render(snapshot: FormSnapshot): void {
+		const root = el("div", {
+			class: classNames("biab-form", extraClass),
+			"data-biab-status": snapshot.status,
+		});
+
+		// Org icon (when the form opted into showOrgIcon).
+		if (snapshot.orgIcon) {
+			root.append(
+				el("img", {
+					class: "biab-form__org-icon",
+					src: snapshot.orgIcon,
+					alt: "",
+				}),
+			);
+		}
+
+		// Loading / error states.
+		if (snapshot.status === "loading" || snapshot.status === "idle") {
+			root.append(el("div", { class: "biab-form__loading" }, ["Loading…"]));
+			swap(root);
+			return;
+		}
+		if (snapshot.status === "error") {
+			root.append(
+				el("div", { class: "biab-form__error" }, [
+					snapshot.loadError || "Could not load this form.",
+				]),
+			);
+			swap(root);
+			return;
+		}
+
+		// Submitted confirmation.
+		if (snapshot.submitted) {
+			root.append(
+				el("div", { class: "biab-form__success" }, [
+					el("p", { class: "biab-form__success-title" }, [
+						"Thanks — we got it.",
+					]),
+				]),
+			);
+			swap(root);
+			return;
+		}
+
+		// Header (title / description).
+		if (snapshot.title || snapshot.description) {
+			const header = el("div", { class: "biab-form__header" }, []);
+			if (snapshot.title)
+				header.append(
+					el("h2", { class: "biab-form__title" }, [snapshot.title]),
+				);
+			if (snapshot.description) {
+				header.append(
+					el("p", { class: "biab-form__description" }, [snapshot.description]),
+				);
+			}
+			root.append(header);
+		}
+
+		// Progress indicator.
+		const progress = renderProgress(snapshot, (i) => controller.goToStep(i));
+		if (progress) root.append(progress);
+
+		// Error summary banner.
+		if (snapshot.errorList.length > 0) {
+			root.append(
+				el("div", { class: "biab-form__error-summary" }, [
+					el("div", { class: "biab-form__error-summary-title" }, [
+						`Please complete the highlighted required field${snapshot.errorList.length === 1 ? "" : "s"}.`,
+					]),
+					el("div", { class: "biab-form__error-summary-list" }, [
+						snapshot.errorList.map((e) => e.label).join(", "),
+					]),
+				]),
+			);
+		}
+
+		const ctx: RenderCtx = {
+			snapshot,
+			setValue: (id, v) => controller.setValue(id, v),
+			upload: (fieldId, file) => {
+				void controller.uploadFile(fieldId, file);
+			},
+			autocompleteConfig,
+		};
+
+		// Field tree (animation-wrapped active step).
+		const flat = snapshot.settings.isConsecutive;
+		const stepWrap = el("div", {
+			class: animClass(snapshot.settings.animation, snapshot.forward),
+			"data-biab-step": String(snapshot.step),
+		});
+		if (snapshot.settings.animation === "scroll") {
+			// Reveal each top-level field on scroll. Class is the hook; CSS owns the
+			// transition. We add the visible state once it intersects.
+			for (const vf of snapshot.visibleFields) {
+				const reveal = el("div", { class: "biab-reveal" }, [
+					renderTree([vf], ctx, flat),
+				]);
+				stepWrap.append(reveal);
+				observeReveal(reveal);
+			}
+		} else {
+			stepWrap.append(renderTree(snapshot.visibleFields, ctx, flat));
+		}
+		root.append(stepWrap);
+
+		// Navigation / submit.
+		root.append(renderNav(snapshot));
+
+		swap(root);
+	}
+
+	function renderNav(snapshot: FormSnapshot): HTMLElement {
+		const submitLabel = opts.submitLabel ?? "Submit";
+
+		if (snapshot.settings.isConsecutive && snapshot.stepCount > 1) {
+			const back = el(
+				"button",
+				{
+					class: "biab-btn biab-btn--ghost biab-btn--back",
+					type: "button",
+					...(snapshot.isFirstStep ? { disabled: true } : {}),
+				},
+				["Back"],
+			);
+			back.addEventListener("click", () => controller.back());
+
+			let advance: HTMLElement;
+			if (!snapshot.isLastStep) {
+				advance = el(
+					"button",
+					{
+						class: "biab-btn biab-btn--next",
+						type: "button",
+						...(snapshot.canAdvance ? {} : { disabled: true }),
+					},
+					["Next"],
+				);
+				advance.addEventListener("click", () => controller.next());
+			} else {
+				advance = el(
+					"button",
+					{
+						class: "biab-btn biab-btn--submit",
+						type: "button",
+						...(snapshot.submitting ? { disabled: true } : {}),
+					},
+					[snapshot.submitting ? "Sending…" : submitLabel],
+				);
+				advance.addEventListener("click", () => void doSubmit());
+			}
+			return el("div", { class: "biab-nav" }, [back, advance]);
+		}
+
+		const submit = el(
+			"button",
+			{
+				class: "biab-btn biab-btn--submit",
+				type: "button",
+				...(snapshot.submitting ? { disabled: true } : {}),
+			},
+			[snapshot.submitting ? "Sending…" : submitLabel],
+		);
+		submit.addEventListener("click", () => void doSubmit());
+		return el("div", { class: "biab-nav" }, [submit]);
+	}
+
+	const unsubscribe = controller.subscribe(render);
+	// Initial paint + load (load() notifies, which re-renders).
+	render(controller.snapshot());
+	void controller.load();
+
+	return {
+		controller,
+		reload: () => controller.load(),
+		submit: doSubmit,
+		reset: () => controller.reset(),
+		destroy: () => {
+			unsubscribe();
+			controller.destroy();
+			host.replaceChildren();
+		},
+	};
+}
+
+/** Add the `biab-reveal--shown` hook once an element scrolls into view (scroll anim). */
+function observeReveal(node: HTMLElement): void {
+	if (typeof IntersectionObserver === "undefined") {
+		node.classList.add("biab-reveal--shown");
+		return;
+	}
+	const obs = new IntersectionObserver(
+		(entries) => {
+			for (const entry of entries) {
+				if (entry.isIntersecting) {
+					node.classList.add("biab-reveal--shown");
+					obs.disconnect();
+					break;
+				}
+			}
+		},
+		{ threshold: 0.15, rootMargin: "0px 0px -8% 0px" },
+	);
+	obs.observe(node);
+}