@businessdash/sdk 0.9.60

package/src/vue/BiabForm.vue

@@ -0,0 +1,1538 @@
+<script setup lang="ts">
+/**
+ * <BiabForm> — Vue 3 drop-in binding for the headless `@businessdash/sdk/forms`
+ * core. Ship mode: SOURCE (.vue). The consumer's Vite/Nuxt toolchain compiles
+ * this single-file component; biab-dev does NOT pre-build it.
+ *
+ * It is a faithful port of the dashboard renderer (`FormPreview.tsx`): the same
+ * per-field rendering by `type`, the same `condition_block` / `or_condition`
+ * evaluation, the same multi-step ("consecutive") nav + progress bar/steps, the
+ * same concurrent-reveal gating, default seeding, and form-settings application
+ * (animation, showProgress/progressStyle, showOrgIcon + org icon). Everything
+ * renders into LIGHT DOM (no shadow root) using the `biab-*` CSS class +
+ * `data-biab-*` attribute conventions, so a consumer's own CSS cascades 1:1
+ * with the dashboard preview.
+ *
+ * All runtime state + behaviour lives in `createFormController` (values,
+ * errors, steps, visibility, submit lifecycle, file uploads). This component is
+ * a thin reactive shell: it subscribes to `controller.snapshot()` via a
+ * `shallowRef` and tears the subscription down on `onScopeDispose`.
+ *
+ * Two submit paths, picked automatically:
+ *   • `client` given  → the controller submits through the SDK
+ *     (`client.forms.submit`) — auth/caching/HMAC/CRM fan-out stay invisible.
+ *   • `onSubmit` given → the controller validates locally, then hands the
+ *     re-keyed wire payload to your callback (e.g. POST it to your own
+ *     server proxy, the pattern Nuxt/SSR uses to keep the bearer key off the
+ *     client). `onSuccess` / `onError` still fire.
+ *
+ * The recursive field-tree renderer is declared as a local render-function
+ * component (`BiabFieldTree`) right here in `<script setup>` so the whole
+ * binding stays ONE self-contained `.vue` file (the SOURCE ship-mode contract)
+ * while still supporting self-reference for nested groups / conditions.
+ */
+
+import type { BiabClient } from "@businessdash/sdk";
+import {
+	concurrentRevealCount,
+	createFormController,
+	evalCondition,
+	type FieldError,
+	fetchIconNames,
+	filterIconNames,
+	type FormController,
+	type FormCoreField,
+	type FormData,
+	type FormSchema,
+	type FormSnapshot,
+	type FormSubmitOptions,
+	type FormSubmitResult,
+	iconUrl,
+	shouldSearchOptions,
+} from "@businessdash/sdk/forms";
+
+import {
+	type AutocompleteConfig,
+	resolveFieldAutocomplete,
+} from "../forms-core/autocomplete.js";
+import {
+	computed,
+	defineComponent,
+	h,
+	inject,
+	onMounted,
+	onScopeDispose,
+	type PropType,
+	ref,
+	shallowRef,
+	watch,
+} from "vue";
+
+import { BIAB_CLIENT_KEY } from "./index";
+
+// ─── Props / emits ────────────────────────────────────────────────────────────
+
+type SuccessResult = Extract<FormSubmitResult, { ok: true }>;
+type FailureResult = Extract<FormSubmitResult, { ok: false }>;
+
+const props = withDefaults(
+	defineProps<{
+		/** Form slug — required when loading/submitting via an SDK `client`. With a
+		 *  pre-fetched `schema` the slug is read from `schema.slug` if omitted. */
+		slug?: string;
+		/** Pre-fetched schema (SSR / RSC). Adopted synchronously — no network. When
+		 *  given without a `client`, pair it with `onSubmit` to post the payload
+		 *  through your own server proxy. */
+		schema?: FormSchema;
+		/** SDK client. Optional — falls back to a `provide(BIAB_CLIENT_KEY, …)` /
+		 *  `<BiabProvider>` ancestor. Browser-only: never pass a server-bound key in
+		 *  a client-rendered tree (use `schema` + `onSubmit` instead). */
+		client?: BiabClient;
+		/** Submit-options merged into every submit (the call's own options win). */
+		submitOptions?: FormSubmitOptions;
+		/** Validate on the server, store nothing (no side effects). */
+		dryRun?: boolean;
+		/** Recipient passthrough forwarded to the underlying submit. */
+		submitterEmail?: string;
+		submitterName?: string;
+		/** Submit button label (live mode). */
+		submitLabel?: string;
+		/**
+		 * Custom submit. When provided, the controller validates locally and then
+		 * this receives the re-keyed wire payload (keyed by each field's output
+		 * `key`). Return a `FormSubmitResult` to drive success/error UI precisely,
+		 * or resolve/throw — a thrown error surfaces as a `network_error` failure.
+		 * This is how SSR consumers submit without shipping the bearer key.
+		 */
+		onSubmit?: (
+			payload: FormData,
+			opts: FormSubmitOptions,
+		) => void | FormSubmitResult | Promise<void | FormSubmitResult>;
+		/** Class(es) merged onto the root `.biab-form` element. */
+		class?: unknown;
+		/** Alias for `class` (cross-framework parity). */
+		className?: string;
+		/** Hide the built-in success card and let the parent render via `@success`. */
+		hideSuccess?: boolean;
+		/**
+		 * Global HTML autofill switch. Defaults to inferring a token per field
+		 * (so an email field gets `autocomplete="email"`, etc.). Pass `false`
+		 * (template: `:auto-complete="false"`) to emit `autocomplete="off"` on
+		 * every value-bearing input.
+		 */
+		autoComplete?: boolean;
+		/**
+		 * Per-field autofill overrides keyed by field id: a literal token, `true`
+		 * (infer), or `false` (off). Wins over `autoComplete` and any schema-level
+		 * token. Template: `:field-auto-complete="{ … }"`.
+		 */
+		fieldAutoComplete?: Record<string, string | boolean>;
+	}>(),
+	{
+		submitLabel: "Submit",
+	},
+);
+
+const emit = defineEmits<{
+	(e: "success", result: SuccessResult): void;
+	(e: "error", result: FailureResult): void;
+	(e: "submit", result: FormSubmitResult): void;
+}>();
+
+// ─── Resolve the client (prop → injected provider) ──────────────────────────────
+
+const injectedClient = inject(BIAB_CLIENT_KEY, null);
+const resolvedClient = computed<BiabClient | undefined>(
+	() => props.client ?? injectedClient ?? undefined,
+);
+
+// ─── Submit-option assembly ─────────────────────────────────────────────────────
+
+function mergedSubmitOptions(): FormSubmitOptions {
+	const opts: FormSubmitOptions = { ...props.submitOptions };
+	if (props.dryRun) opts.dryRun = true;
+	if (props.submitterEmail) opts.submitterEmail = props.submitterEmail;
+	if (props.submitterName) opts.submitterName = props.submitterName;
+	return opts;
+}
+
+// ─── Controller wiring ─────────────────────────────────────────────────────────
+
+/**
+ * Build a controller for the current schema/client. We pass the SDK client only
+ * when there's no `onSubmit` override — with an override we own the network call
+ * and the controller stays client-free (so it never tries to fetch the schema or
+ * submit itself). When a `schema` is supplied we always adopt it synchronously.
+ */
+function buildController(): FormController {
+	const useOwnSubmit = typeof props.onSubmit === "function";
+	return createFormController({
+		client: useOwnSubmit ? undefined : resolvedClient.value,
+		slug: props.slug ?? props.schema?.slug,
+		schema: props.schema,
+		submitOptions: mergedSubmitOptions(),
+		onSuccess: (result) => {
+			emit("success", result);
+			emit("submit", result);
+		},
+		onError: (result) => {
+			emit("error", result);
+			emit("submit", result);
+		},
+	});
+}
+
+// `onSubmit` results aren't tracked by the controller (it never ran), so keep a
+// local mirror for the success/error UI in that path. Declared before the
+// controller wiring so the `watch`/expose closures reference an initialized ref.
+const ownResult = shallowRef<FormSubmitResult | null>(null);
+
+let controller: FormController = buildController();
+const snap = shallowRef<FormSnapshot>(controller.snapshot());
+let unsubscribe: (() => void) | null = null;
+
+function attach(c: FormController): void {
+	unsubscribe = c.subscribe((s) => {
+		// A fresh snapshot object per notify + shallowRef => Vue re-renders.
+		snap.value = s;
+	});
+	snap.value = c.snapshot();
+	void c.load();
+}
+
+attach(controller);
+
+// Re-create the controller when the schema, client, slug, or submit-mode changes.
+watch(
+	() => [props.schema, resolvedClient.value, props.slug, typeof props.onSubmit],
+	() => {
+		unsubscribe?.();
+		controller.destroy();
+		ownResult.value = null;
+		controller = buildController();
+		attach(controller);
+	},
+);
+
+onMounted(() => {
+	// SSR adopts the schema in setup; this covers a schema that arrives later.
+	if (snap.value.status === "idle") void controller.load();
+});
+
+onScopeDispose(() => {
+	unsubscribe?.();
+	controller.destroy();
+});
+
+// ─── Submit (client path OR onSubmit override) ─────────────────────────────────
+
+async function handleSubmit(callOpts?: FormSubmitOptions): Promise<void> {
+	const merged: FormSubmitOptions = { ...mergedSubmitOptions(), ...callOpts };
+
+	// Override path: validate locally, then hand the wire payload to the parent.
+	if (typeof props.onSubmit === "function") {
+		const missing = controller.validate();
+		if (missing.length > 0) return; // errors already published to the snapshot
+		const wire = toWirePayload(snap.value.fields, snap.value.values);
+		let result: FormSubmitResult;
+		try {
+			const r = await props.onSubmit(wire, merged);
+			result =
+				r && typeof r === "object" && "ok" in r
+					? (r as FormSubmitResult)
+					: {
+							ok: true,
+							status: 200,
+							...(merged.dryRun ? { dryRun: true } : {}),
+						};
+		} catch (err) {
+			result = {
+				ok: false,
+				status: 0,
+				reason: "network_error",
+				message:
+					err instanceof Error ? err.message : "The submission failed.",
+			};
+		}
+		ownResult.value = result;
+		if (result.ok) {
+			emit("success", result);
+			emit("submit", result);
+		} else {
+			emit("error", result);
+			emit("submit", result);
+		}
+		return;
+	}
+
+	// Client path: the controller submits through the SDK.
+	await controller.submit(merged);
+}
+
+const effectiveResult = computed<FormSubmitResult | null>(
+	() => ownResult.value ?? snap.value.result,
+);
+const effectiveSubmitted = computed(() => effectiveResult.value?.ok === true);
+
+// ─── Imperative API exposed to template refs ────────────────────────────────────
+
+defineExpose({
+	submit: (opts?: FormSubmitOptions) => handleSubmit(opts),
+	reset: () => {
+		ownResult.value = null;
+		controller.reset();
+	},
+	validate: () => controller.validate(),
+	next: () => controller.next(),
+	back: () => controller.back(),
+	snapshot: () => controller.snapshot(),
+});
+
+// ─── id → output-key re-keying (mirrors core toSubmissionPayload) ───────────────
+function toWirePayload(fields: FormCoreField[], data: FormData): FormData {
+	const idToKey = new Map<string, string>();
+	const walk = (nodes: FormCoreField[]) => {
+		for (const f of nodes) {
+			if (f.id && f.key) idToKey.set(f.id, f.key);
+			if (f.children) walk(f.children);
+		}
+	};
+	walk(fields);
+	const out: FormData = {};
+	for (const [id, value] of Object.entries(data)) {
+		out[idToKey.get(id) ?? id] = value;
+	}
+	return out;
+}
+
+// ─── File-upload bridge (controller owns the SDK call + value append) ───────────
+async function onFilePick(fieldId: string, ev: Event): Promise<void> {
+	const input = ev.target as HTMLInputElement;
+	const picked = input.files;
+	if (!picked || picked.length === 0) return;
+	const files = Array.isArray(snap.value.values[fieldId])
+		? (snap.value.values[fieldId] as unknown[])
+		: [];
+	// Determine remaining slots from the field's maxFiles (best-effort UX cap).
+	const field = flatFind(snap.value.fields, fieldId);
+	const maxFiles = field?.fileConfig?.maxFiles ?? 1;
+	const slots = Math.max(maxFiles - files.length, 0);
+	const list = Array.from(picked).slice(0, slots);
+	try {
+		for (const file of list) {
+			await controller.uploadFile(fieldId, file, { filename: file.name });
+		}
+	} finally {
+		input.value = "";
+	}
+}
+
+function removeFile(fieldId: string, idx: number): void {
+	const arr = Array.isArray(snap.value.values[fieldId])
+		? (snap.value.values[fieldId] as unknown[])
+		: [];
+	controller.setValue(
+		fieldId,
+		arr.filter((_, i) => i !== idx),
+	);
+}
+
+function flatFind(
+	nodes: FormCoreField[],
+	id: string,
+): FormCoreField | undefined {
+	for (const f of nodes) {
+		if (f.id === id) return f;
+		if (f.children) {
+			const hit = flatFind(f.children, id);
+			if (hit) return hit;
+		}
+	}
+	return undefined;
+}
+
+// ─── Render-state derivations (mirror FormPreview) ──────────────────────────────
+
+const showStepsProgress = computed(
+	() =>
+		snap.value.settings.isConsecutive &&
+		snap.value.settings.showProgress &&
+		snap.value.settings.progressStyle !== "bar" &&
+		snap.value.stepCount > 1,
+);
+const showBarProgress = computed(
+	() =>
+		snap.value.settings.isConsecutive &&
+		snap.value.settings.showProgress &&
+		snap.value.settings.progressStyle === "bar" &&
+		snap.value.stepCount > 1,
+);
+const isConsecutive = computed(() => snap.value.settings.isConsecutive);
+const isMultiStep = computed(
+	() => isConsecutive.value && snap.value.stepCount > 1,
+);
+
+/** Entrance animation class for the active step (directional slide). */
+const entranceClass = computed(() => {
+	const a = snap.value.settings.animation;
+	const fwd = snap.value.forward;
+	switch (a) {
+		case "fade":
+			return "biab-anim biab-anim--fade";
+		case "scale":
+			return "biab-anim biab-anim--scale";
+		case "slide":
+			return fwd
+				? "biab-anim biab-anim--slide-fwd"
+				: "biab-anim biab-anim--slide-back";
+		default:
+			return "";
+	}
+});
+
+function stepTitle(step: FormCoreField[], i: number): string {
+	const f = step[0];
+	return (
+		(typeof f?.stepTitle === "string" && f.stepTitle) ||
+		(typeof f?.label === "string" && f.label) ||
+		`Step ${i + 1}`
+	);
+}
+
+const rootClass = computed(() => ["biab-form", props.className, props.class]);
+const submitDisabled = computed(
+	() => snap.value.submitting || snap.value.uploading,
+);
+
+// ─── Autofill config threaded to the field renderer ─────────────────────────────
+// Mirrors the React adapter: a global `enabled` switch plus per-field `overrides`.
+// `resolveFieldAutocomplete(field, config)` turns this into the final token (or
+// `undefined` to omit the attribute) per input. See forms-core/autocomplete.ts.
+const autocompleteConfig = computed<AutocompleteConfig>(() => ({
+	...(props.autoComplete !== undefined ? { enabled: props.autoComplete } : {}),
+	...(props.fieldAutoComplete ? { overrides: props.fieldAutoComplete } : {}),
+}));
+
+// ─── Context bag handed to the recursive renderer ───────────────────────────────
+type FieldCtx = {
+	values: FormData;
+	errors: Record<string, FieldError>;
+	setValue: (id: string, v: unknown) => void;
+	uploadFile: (id: string, ev: Event) => void;
+	removeFile: (id: string, idx: number) => void;
+	autocomplete: AutocompleteConfig;
+};
+const fieldCtx = computed<FieldCtx>(() => ({
+	values: snap.value.values,
+	errors: snap.value.errors,
+	setValue: (id, v) => controller.setValue(id, v),
+	uploadFile: (id, ev) => void onFilePick(id, ev),
+	removeFile,
+	autocomplete: autocompleteConfig.value,
+}));
+
+// ─── icon_select / image_input shared state ─────────────────────────────────
+// Declared here (setup scope) so the recursive field-tree component below closes
+// over them, the same way it closes over `controller`.
+
+/** Current search text in an icon picker. */
+const iconQuery = ref("");
+/** Lazily-fetched icon-name index — ~1,600 entries that change only when Lucide
+ *  does, so it's fetched once per mount and never bundled. */
+const iconIndex = ref<string[]>([]);
+let iconIndexRequested = false;
+
+async function loadIconIndex(): Promise<void> {
+	if (iconIndexRequested) return;
+	iconIndexRequested = true;
+	// Resolves to [] on failure — an empty grid is recoverable, a thrown error
+	// during render is not.
+	iconIndex.value = await fetchIconNames();
+}
+
+/** Which side of an `image_input` the visitor is on, per field id. */
+const imageModes = ref<Record<string, "upload" | "url">>({});
+
+// ─── BiabFieldTree — recursive render-function component (FormPreview port) ──────
+
+const STATIC_NO_LABEL = new Set(["title", "subtitle", "separator", "richtext"]);
+
+function cssKey(f: FormCoreField): string {
+	const explicit = typeof f.outputKey === "string" ? f.outputKey.trim() : "";
+	return explicit || f.key || f.id;
+}
+
+const BiabFieldTree = defineComponent({
+	name: "BiabFieldTree",
+	props: {
+		nodes: { type: Array as PropType<FormCoreField[]>, required: true },
+		flat: { type: Boolean, default: false },
+		ctx: { type: Object as PropType<FieldCtx>, required: true },
+	},
+	setup(p) {
+		const renderInput = (f: FormCoreField) => {
+			const id = f.id;
+			const value = p.ctx.values[id];
+			const set = (v: unknown) => p.ctx.setValue(id, v);
+			// Resolved HTML autofill token for this field (or `undefined` to omit
+			// the attribute). Honors the global `autoComplete` switch + per-field
+			// overrides; mirrors the React adapter. Vue drops `undefined` attrs.
+			const autocomplete = resolveFieldAutocomplete(f, p.ctx.autocomplete);
+
+			switch (f.type) {
+				case "title":
+					return h("h2", { class: "biab-field__title" }, f.label || "");
+				case "subtitle":
+					return h("h3", { class: "biab-field__subtitle" }, f.label || "");
+				case "separator":
+					return h("hr", { class: "biab-field__separator" });
+				case "richtext":
+					return f.content
+						? h("div", {
+								class: "biab-field__richtext",
+								innerHTML: String(f.content),
+							})
+						: null;
+				case "image": {
+					const cfg =
+						(f.imageConfig as
+							| {
+									src?: string;
+									alt?: string;
+									width?: number;
+									height?: number;
+							  }
+							| undefined) ?? {};
+					return cfg.src
+						? h("img", {
+								class: "biab-field__image",
+								src: cfg.src,
+								alt: cfg.alt || "",
+								style: {
+									width: cfg.width ? `${cfg.width}px` : "auto",
+									height: cfg.height ? `${cfg.height}px` : "auto",
+									maxWidth: "100%",
+								},
+							})
+						: null;
+				}
+				case "textarea": {
+					const cfg =
+						(f.textareaConfig as
+							| { rows?: number; resizable?: boolean }
+							| undefined) ?? {};
+					return h("textarea", {
+						autocomplete,
+						class: "biab-textarea biab-field__control",
+						value: typeof value === "string" ? value : "",
+						placeholder: f.placeholder || "",
+						rows: cfg.rows ?? 4,
+						style: { resize: cfg.resizable ? "vertical" : "none" },
+						onInput: (e: Event) =>
+							set((e.target as HTMLTextAreaElement).value),
+					});
+				}
+				case "select": {
+					const opts = f.options ?? [];
+					// ComboBox card, or a list long enough that scrolling is worse.
+					// `input list` + `datalist` = native typeahead, no JS, no styling
+					// opinion — which is the SDK's contract.
+					if (
+						shouldSearchOptions(
+							opts.length,
+							(f as { display?: string }).display,
+						)
+					) {
+						const listId = `biab-list-${f.id}`;
+						// A wrapper rather than a fragment: `renderInput` is typed to one
+						// VNode, and `<datalist>` renders nothing visually anyway.
+						return h("div", { class: "biab-combobox-wrap" }, [
+							h("input", {
+								class: "biab-input biab-combobox biab-field__control",
+								type: "text",
+								list: listId,
+								placeholder: f.placeholder || "Search…",
+								value: typeof value === "string" ? value : "",
+								onInput: (e: Event) =>
+									set((e.target as HTMLInputElement).value),
+							}),
+							h(
+								"datalist",
+								{ id: listId },
+								opts.map((opt) => h("option", { key: opt, value: opt })),
+							),
+						]);
+					}
+					return h(
+						"select",
+						{
+							class: "biab-input biab-field__control",
+							value: typeof value === "string" ? value : "",
+							onChange: (e: Event) =>
+								set((e.target as HTMLSelectElement).value),
+						},
+						[
+							h("option", { value: "" }, f.placeholder || "Select..."),
+							...opts.map((opt) => h("option", { key: opt, value: opt }, opt)),
+						],
+					);
+				}
+				case "icon_select": {
+					// The value is an icon NAME; art resolves against the platform's
+					// icon route so no icon library ships in the SDK bundle.
+					const curated = (
+						f as { iconConfig?: { allowedIcons?: string[] } }
+					).iconConfig?.allowedIcons;
+					const names =
+						curated && curated.length > 0 ? curated : iconIndex.value;
+					if (
+						(!curated || curated.length === 0) &&
+						iconIndex.value.length === 0
+					) {
+						void loadIconIndex();
+					}
+					const selected = typeof value === "string" ? value : "";
+					return h("div", { class: "biab-iconselect" }, [
+						h("input", {
+							class: "biab-input biab-iconselect__search",
+							type: "text",
+							placeholder: f.placeholder || "Search icons…",
+							value: iconQuery.value,
+							onInput: (e: Event) => {
+								iconQuery.value = (e.target as HTMLInputElement).value;
+							},
+						}),
+						selected
+							? h("span", { class: "biab-iconselect__current" }, [
+									h("img", {
+										src: iconUrl(selected),
+										alt: selected,
+										width: 16,
+										height: 16,
+									}),
+									h(
+										"button",
+										{
+											type: "button",
+											class: "biab-iconselect__clear",
+											onClick: () => set(""),
+										},
+										"×",
+									),
+								])
+							: null,
+						h(
+							"div",
+							{ class: "biab-iconselect__grid" },
+							filterIconNames(names, iconQuery.value).map((name) =>
+								h(
+									"button",
+									{
+										key: name,
+										type: "button",
+										class: `biab-iconselect__item${
+											selected === name ? " is-selected" : ""
+										}`,
+										title: name,
+										"aria-label": name,
+										"aria-pressed": selected === name,
+										onClick: () => set(name),
+									},
+									[
+										h("img", {
+											src: iconUrl(name),
+											alt: "",
+											width: 16,
+											height: 16,
+										}),
+									],
+								),
+							),
+						),
+					]);
+				}
+				case "image_input": {
+					// One image, either source; the value is a plain URL string.
+					const cfg =
+						(
+							f as {
+								imageInputConfig?: {
+									allowedTypes?: string[];
+									maxSize?: number;
+									showPreview?: boolean;
+									sources?: "both" | "upload" | "url";
+								};
+							}
+						).imageInputConfig ?? {};
+					const sources = cfg.sources ?? "both";
+					const url = typeof value === "string" ? value : "";
+					const mode = imageModes.value[f.id] ?? "upload";
+					return h("div", { class: "biab-imageinput" }, [
+						sources === "both"
+							? h(
+									"div",
+									{ class: "biab-imageinput__modes" },
+									(["upload", "url"] as const).map((m) =>
+										h(
+											"button",
+											{
+												key: m,
+												type: "button",
+												class: `biab-imageinput__mode${
+													mode === m ? " is-active" : ""
+												}`,
+												"aria-pressed": mode === m,
+												onClick: () => {
+													imageModes.value = {
+														...imageModes.value,
+														[f.id]: m,
+													};
+												},
+											},
+											m === "upload" ? "Upload" : "Paste URL",
+										),
+									),
+								)
+							: null,
+						mode === "upload" && sources !== "url"
+							? h("input", {
+									class: "biab-input biab-imageinput__file",
+									type: "file",
+									accept: (cfg.allowedTypes ?? ["image/*"]).join(","),
+									onChange: (e: Event) => {
+										const file = (e.target as HTMLInputElement).files?.[0];
+										if (!file) return;
+										if (file.size > (cfg.maxSize ?? 5) * 1024 * 1024) return;
+										void controller
+											.uploadFile(f.id, file, { filename: file.name })
+											.then((up) => {
+												const u = (up as { url?: string } | undefined)?.url;
+												if (u) set(u);
+											})
+											.catch(() => undefined);
+									},
+								})
+							: h("input", {
+									class: "biab-input biab-imageinput__url",
+									type: "url",
+									placeholder:
+										f.placeholder || "https://example.com/image.png",
+									value: url,
+									onInput: (e: Event) =>
+										set((e.target as HTMLInputElement).value),
+								}),
+						cfg.showPreview !== false && url
+							? h("img", {
+									class: "biab-imageinput__preview",
+									src: url,
+									alt: "",
+								})
+							: null,
+					]);
+				}
+				case "radio":
+					return h(
+						"div",
+						{ class: "biab-field__radio-group" },
+						(f.options ?? []).map((opt) =>
+							h("label", { key: opt, class: "biab-field__radio" }, [
+								h("input", {
+									type: "radio",
+									name: id,
+									value: opt,
+									checked: value === opt,
+									onChange: () => set(opt),
+								}),
+								h("span", opt),
+							]),
+						),
+					);
+				case "checkbox": {
+					const arr = Array.isArray(value) ? (value as string[]) : [];
+					return h(
+						"div",
+						{ class: "biab-field__checkbox-group" },
+						(f.options ?? []).map((opt) =>
+							h("label", { key: opt, class: "biab-field__checkbox" }, [
+								h("input", {
+									type: "checkbox",
+									checked: arr.includes(opt),
+									onChange: (e: Event) => {
+										const c = (e.target as HTMLInputElement).checked;
+										set(
+											c ? [...arr, opt] : arr.filter((x) => x !== opt),
+										);
+									},
+								}),
+								h("span", opt),
+							]),
+						),
+					);
+				}
+				case "boolean":
+					return h("label", { class: "biab-field__switch" }, [
+						h("input", {
+							type: "checkbox",
+							checked: Boolean(value),
+							onChange: (e: Event) =>
+								set((e.target as HTMLInputElement).checked),
+						}),
+						h("span", f.placeholder || "Yes / No"),
+					]);
+				case "date":
+					return h("input", {
+						type: "date",
+						class: "biab-input biab-field__control",
+						value: typeof value === "string" ? value : "",
+						onInput: (e: Event) =>
+							set((e.target as HTMLInputElement).value),
+					});
+				case "time_picker": {
+					const mode = f.timeConfig?.mode ?? "simple";
+					if (mode === "simple") {
+						const step = Math.max(f.timeConfig?.stepMinutes ?? 30, 1);
+						const fmt = f.timeConfig?.format ?? "12h";
+						const opts: { v: string; l: string }[] = [];
+						for (let hh = 0; hh < 24; hh++) {
+							for (let mm = 0; mm < 60; mm += step) {
+								const v = `${String(hh).padStart(2, "0")}:${String(
+									mm,
+								).padStart(2, "0")}`;
+								let l = v;
+								if (fmt !== "24h") {
+									const ap = hh < 12 ? "AM" : "PM";
+									const h12 = hh % 12 === 0 ? 12 : hh % 12;
+									l = `${h12}:${String(mm).padStart(2, "0")} ${ap}`;
+								}
+								opts.push({ v, l });
+							}
+						}
+						return h(
+							"select",
+							{
+								class: "biab-input biab-field__control",
+								value: typeof value === "string" ? value : "",
+								onChange: (e: Event) =>
+									set((e.target as HTMLSelectElement).value),
+							},
+							[
+								h("option", { value: "" }, f.placeholder || "Select time"),
+								...opts.map((o) =>
+									h("option", { key: o.v, value: o.v }, o.l),
+								),
+							],
+						);
+					}
+					const struct =
+						value && typeof value === "object" && !Array.isArray(value)
+							? (value as Record<string, string>)
+							: {};
+					const partA = mode === "time_block" ? "start" : "date";
+					const partB = mode === "time_block" ? "end" : "time";
+					const typeA = mode === "time_block" ? "time" : "date";
+					return h("div", { class: "biab-field__grid-2" }, [
+						h("div", {}, [
+							h(
+								"label",
+								{ class: "biab-field__sublabel" },
+								mode === "time_block" ? "Start" : "Date",
+							),
+							h("input", {
+								type: typeA,
+								class: "biab-input",
+								value: struct[partA] ?? "",
+								onInput: (e: Event) =>
+									set({
+										...struct,
+										[partA]: (e.target as HTMLInputElement).value,
+									}),
+							}),
+						]),
+						h("div", {}, [
+							h(
+								"label",
+								{ class: "biab-field__sublabel" },
+								mode === "time_block" ? "End" : "Time",
+							),
+							h("input", {
+								type: "time",
+								class: "biab-input",
+								value: struct[partB] ?? "",
+								onInput: (e: Event) =>
+									set({
+										...struct,
+										[partB]: (e.target as HTMLInputElement).value,
+									}),
+							}),
+						]),
+					]);
+				}
+				case "date_range": {
+					const struct =
+						value && typeof value === "object" && !Array.isArray(value)
+							? (value as Record<string, string>)
+							: {};
+					return h("div", { class: "biab-field__grid-2" }, [
+						h("div", {}, [
+							h("label", { class: "biab-field__sublabel" }, "Start"),
+							h("input", {
+								type: "date",
+								class: "biab-input",
+								value: struct.start ?? "",
+								onInput: (e: Event) =>
+									set({
+										...struct,
+										start: (e.target as HTMLInputElement).value,
+									}),
+							}),
+						]),
+						h("div", {}, [
+							h("label", { class: "biab-field__sublabel" }, "End"),
+							h("input", {
+								type: "date",
+								class: "biab-input",
+								value: struct.end ?? "",
+								onInput: (e: Event) =>
+									set({
+										...struct,
+										end: (e.target as HTMLInputElement).value,
+									}),
+							}),
+						]),
+					]);
+				}
+				case "slider": {
+					const min = f.sliderConfig?.min ?? 0;
+					const max = f.sliderConfig?.max ?? 100;
+					const stepv = f.sliderConfig?.step ?? 1;
+					const unit = f.sliderConfig?.unit;
+					const fmt = (n: number) =>
+						unit === "currency"
+							? `$${n}`
+							: unit === "percent"
+								? `${n}%`
+								: `${n}`;
+					const v = typeof value === "number" ? value : min;
+					return h("div", { class: "biab-field__slider" }, [
+						h("div", { class: "biab-field__slider-scale" }, [
+							h("span", fmt(min)),
+							h("span", { class: "biab-field__slider-value" }, fmt(v)),
+							h("span", fmt(max)),
+						]),
+						h("input", {
+							type: "range",
+							class: "biab-field__slider-input",
+							min,
+							max,
+							step: stepv,
+							value: v,
+							onInput: (e: Event) =>
+								set(Number((e.target as HTMLInputElement).value)),
+						}),
+					]);
+				}
+				case "star_rating": {
+					const max = f.starRatingConfig?.maxStars ?? 5;
+					const v = typeof value === "number" ? value : 0;
+					return h(
+						"div",
+						{ class: "biab-field__stars" },
+						Array.from({ length: max }).map((_, i) =>
+							h(
+								"button",
+								{
+									key: i,
+									type: "button",
+									class: ["biab-field__star", i < v ? "is-on" : ""],
+									onClick: () => set(i + 1),
+								},
+								"★",
+							),
+						),
+					);
+				}
+				case "happiness_rating": {
+					const v = typeof value === "number" ? value : -1;
+					return h(
+						"div",
+						{ class: "biab-field__happiness" },
+						["😞", "😕", "😐", "🙂", "😄"].map((emoji, i) =>
+							h(
+								"button",
+								{
+									key: emoji,
+									type: "button",
+									class: ["biab-field__happy", i === v ? "is-on" : ""],
+									onClick: () => set(i),
+								},
+								emoji,
+							),
+						),
+					);
+				}
+				case "stepper": {
+					const v = typeof value === "number" ? value : 0;
+					return h("div", { class: "biab-field__stepper" }, [
+						h(
+							"button",
+							{
+								type: "button",
+								class: "biab-btn biab-btn--ghost biab-field__stepper-btn",
+								onClick: () => set(v - 1),
+							},
+							"−",
+						),
+						h(
+							"span",
+							{ class: "biab-field__stepper-value" },
+							String(v),
+						),
+						h(
+							"button",
+							{
+								type: "button",
+								class: "biab-btn biab-btn--ghost biab-field__stepper-btn",
+								onClick: () => set(v + 1),
+							},
+							"+",
+						),
+					]);
+				}
+				case "address": {
+					const a =
+						value && typeof value === "object" && !Array.isArray(value)
+							? (value as Record<string, string>)
+							: {};
+					// Per-subfield autofill tokens, suppressed to "off" when autofill
+					// is off for this field (global switch or per-field override).
+					const acOff = autocomplete === "off";
+					const part = (
+						k: string,
+						label: string,
+						ac: string,
+						full = false,
+					) =>
+						h(
+							"div",
+							{
+								class: full
+									? "biab-field__addr-full"
+									: "biab-field__addr-half",
+							},
+							[
+								h("label", { class: "biab-field__sublabel" }, label),
+								h("input", {
+									autocomplete: acOff ? "off" : ac,
+									class: "biab-input",
+									value: a[k] ?? "",
+									onInput: (e: Event) =>
+										set({
+											...a,
+											[k]: (e.target as HTMLInputElement).value,
+										}),
+								}),
+							],
+						);
+					return h("div", { class: "biab-field__address" }, [
+						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),
+					]);
+				}
+				case "color_picker": {
+					const v = typeof value === "string" ? value : "";
+					return h(
+						"div",
+						{ class: "biab-field__colors" },
+						(f.options ?? []).map((color) =>
+							h("button", {
+								key: color,
+								type: "button",
+								class: ["biab-field__color", v === color ? "is-on" : ""],
+								style: { backgroundColor: color },
+								title: color,
+								onClick: () => set(color),
+							}),
+						),
+					);
+				}
+				case "file_upload": {
+					const files = Array.isArray(value)
+						? (value as { name: string; size: number }[])
+						: [];
+					const maxFiles = f.fileConfig?.maxFiles ?? 1;
+					const allowed = f.fileConfig?.allowedTypes;
+					const remaining = Math.max(maxFiles - files.length, 0);
+					return h("div", { class: "biab-field__file" }, [
+						h("input", {
+							type: "file",
+							class: "biab-field__file-input",
+							multiple: maxFiles > 1,
+							accept:
+								allowed && allowed.length
+									? allowed.join(",")
+									: undefined,
+							disabled: remaining === 0,
+							onChange: (e: Event) => p.ctx.uploadFile(id, e),
+						}),
+						files.length
+							? h(
+									"ul",
+									{ class: "biab-field__file-list" },
+									files.map((file, idx) =>
+										h(
+											"li",
+											{ key: idx, class: "biab-field__file-item" },
+											[
+												h(
+													"span",
+													{ class: "biab-field__file-name" },
+													file.name,
+												),
+												h(
+													"span",
+													{ class: "biab-field__file-size" },
+													`${Math.round(file.size / 1024)} KB`,
+												),
+												h(
+													"button",
+													{
+														type: "button",
+														class: "biab-field__file-remove",
+														"aria-label": "Remove file",
+														onClick: () => p.ctx.removeFile(id, idx),
+													},
+													"✕",
+												),
+											],
+										),
+									),
+								)
+							: null,
+					]);
+				}
+				case "phone":
+					return h("input", {
+						autocomplete,
+						type: "tel",
+						class: "biab-input biab-field__control",
+						value: typeof value === "string" ? value : "",
+						placeholder:
+							f.placeholder ||
+							(f.phoneConfig?.international
+								? "+1 (555) 000-0000"
+								: "(555) 000-0000"),
+						onInput: (e: Event) =>
+							set((e.target as HTMLInputElement).value),
+					});
+				case "email":
+					return h("input", {
+						autocomplete,
+						type: "email",
+						class: "biab-input biab-field__control",
+						value: typeof value === "string" ? value : "",
+						placeholder: f.placeholder || "you@example.com",
+						onInput: (e: Event) =>
+							set((e.target as HTMLInputElement).value),
+					});
+				case "number":
+					return h("input", {
+						type: "number",
+						class: "biab-input biab-field__control",
+						value:
+							typeof value === "number"
+								? value
+								: typeof value === "string"
+									? value
+									: "",
+						placeholder: f.placeholder || "",
+						onInput: (e: Event) => {
+							const raw = (e.target as HTMLInputElement).value;
+							set(raw === "" ? "" : Number(raw));
+						},
+					});
+				default:
+					return h("input", {
+						autocomplete,
+						class: "biab-input biab-field__control",
+						value: typeof value === "string" ? value : "",
+						placeholder: f.placeholder || "",
+						onInput: (e: Event) =>
+							set((e.target as HTMLInputElement).value),
+					});
+			}
+		};
+
+		const renderFieldRow = (f: FormCoreField) => {
+			const errored = Boolean(p.ctx.errors[f.id]);
+			const showLabel = !STATIC_NO_LABEL.has(f.type);
+			return h(
+				"div",
+				{
+					"data-field-id": f.id,
+					"data-biab-field": cssKey(f),
+					"data-biab-type": f.type,
+					class: [
+						"biab-field",
+						`biab-field--${f.type}`,
+						f.required ? "biab-field--required" : "",
+						errored ? "biab-field--error" : "",
+					],
+				},
+				[
+					showLabel
+						? h("label", { class: "biab-field__label biab-label" }, [
+								f.label || "",
+								f.required
+									? h("span", { class: "biab-field__required" }, " *")
+									: null,
+							])
+						: null,
+					renderInput(f),
+					errored
+						? h(
+								"p",
+								{ class: "biab-field__error" },
+								p.ctx.errors[f.id]?.message ?? "This field is required.",
+							)
+						: null,
+					f.helpText
+						? h("p", { class: "biab-field__help" }, f.helpText)
+						: null,
+				],
+			);
+		};
+
+		const renderNode = (f: FormCoreField): ReturnType<typeof h> | null => {
+			// input_group
+			if (f.type === "input_group") {
+				const children = (f.children ?? []) as FormCoreField[];
+				const concurrent = f.concurrentReveal === true;
+				const reveal = concurrent
+					? concurrentRevealCount(children, p.ctx.values)
+					: children.length;
+				const shown = concurrent ? children.slice(0, reveal) : children;
+				return h(
+					"div",
+					{
+						key: f.id,
+						"data-biab-group": cssKey(f),
+						class: ["biab-group", p.flat ? "biab-group--flat" : ""],
+					},
+					[
+						f.label && f.showGroupLabel === true
+							? h("div", { class: "biab-group__label" }, f.label)
+							: null,
+						h(BiabFieldTree, {
+							nodes: shown,
+							flat: p.flat,
+							ctx: p.ctx,
+						}),
+					],
+				);
+			}
+			// condition_block
+			if (f.type === "condition_block") {
+				if (!evalCondition(f.conditionRule, p.ctx.values)) return null;
+				return h(BiabFieldTree, {
+					key: f.id,
+					nodes: (f.children ?? []) as FormCoreField[],
+					flat: p.flat,
+					ctx: p.ctx,
+				});
+			}
+			// or_condition
+			if (f.type === "or_condition") {
+				const left = f.children?.[0];
+				const right = f.children?.[1];
+				const errored = Boolean(p.ctx.errors[f.id]);
+				const cfg =
+					(f.orConditionConfig as
+						| { leftLabel?: string; rightLabel?: string }
+						| undefined) ?? {};
+				return h(
+					"div",
+					{
+						key: f.id,
+						class: ["biab-or", errored ? "biab-or--error" : ""],
+						"data-biab-field": cssKey(f),
+					},
+					[
+						f.label
+							? h("div", { class: "biab-or__label" }, [
+									f.label,
+									h(
+										"span",
+										{ class: "biab-or__hint" },
+										" Fill at least one side",
+									),
+								])
+							: null,
+						h("div", { class: "biab-or__grid" }, [
+							h("div", { class: "biab-or__side" }, [
+								h(
+									"div",
+									{ class: "biab-or__side-label" },
+									cfg.leftLabel || "Option A",
+								),
+								left
+									? h(BiabFieldTree, {
+											nodes: [left],
+											flat: p.flat,
+											ctx: p.ctx,
+										})
+									: null,
+							]),
+							h(
+								"div",
+								{ class: "biab-or__divider" },
+								h("span", "OR"),
+							),
+							h("div", { class: "biab-or__side" }, [
+								h(
+									"div",
+									{ class: "biab-or__side-label" },
+									cfg.rightLabel || "Option B",
+								),
+								right
+									? h(BiabFieldTree, {
+											nodes: [right],
+											flat: p.flat,
+											ctx: p.ctx,
+										})
+									: null,
+							]),
+						]),
+						errored
+							? h(
+									"p",
+									{ class: "biab-or__error" },
+									"Fill in at least one side to continue.",
+								)
+							: null,
+					],
+				);
+			}
+			// flex_row
+			if (f.type === "flex_row") {
+				const cfg =
+					(f.flexConfig as
+						| { justify?: string; align?: string; gap?: number }
+						| undefined) ?? {};
+				const justify = cfg.justify ?? "start";
+				const align = cfg.align ?? "center";
+				return h(
+					"div",
+					{
+						key: f.id,
+						class: [
+							"biab-flex-row",
+							`biab-flex-row--justify-${justify}`,
+							`biab-flex-row--align-${align}`,
+						],
+						style: { gap: `${cfg.gap ?? 12}px` },
+					},
+					(f.children ?? []).map((child) =>
+						h(
+							"div",
+							{ key: child.id, class: "biab-flex-row__item" },
+							renderFieldRow(child as FormCoreField),
+						),
+					),
+				);
+			}
+			// leaf field
+			return renderFieldRow(f);
+		};
+
+		return () =>
+			h(
+				"div",
+				{ class: "biab-tree" },
+				p.nodes.map((n) => renderNode(n)),
+			);
+	},
+});
+</script>
+
+<template>
+	<!-- Loading / idle gate -->
+	<div
+		v-if="snap.status === 'loading' || snap.status === 'idle'"
+		class="biab-form biab-form--loading"
+	>
+		<slot name="loading">
+			<p class="biab-form__loading">Loading form…</p>
+		</slot>
+	</div>
+
+	<!-- Schema-load error gate -->
+	<div v-else-if="snap.status === 'error'" class="biab-form biab-form--error">
+		<slot name="error" :message="snap.loadError">
+			<p class="biab-form__load-error">
+				{{ snap.loadError ?? "This form could not be loaded." }}
+			</p>
+		</slot>
+	</div>
+
+	<!-- Success card -->
+	<div
+		v-else-if="effectiveSubmitted && !hideSuccess"
+		:class="rootClass"
+		data-biab-state="submitted"
+	>
+		<slot name="success" :result="effectiveResult">
+			<div class="biab-form__success">
+				<h2 class="biab-form__success-title">
+					{{ snap.title ?? "Thank you" }}
+				</h2>
+				<p class="biab-form__success-body">Your submission was received.</p>
+			</div>
+		</slot>
+	</div>
+
+	<!-- The form -->
+	<div v-else :class="rootClass" style="position: relative">
+		<!-- Org icon -->
+		<img
+			v-if="snap.orgIcon"
+			:src="snap.orgIcon"
+			alt=""
+			class="biab-form__org-icon"
+			style="position: absolute; right: 0; top: 0"
+		/>
+
+		<!-- Title / description -->
+		<div v-if="snap.title || snap.description" class="biab-form__header">
+			<h2 v-if="snap.title" class="biab-form__title">{{ snap.title }}</h2>
+			<p v-if="snap.description" class="biab-form__description">
+				{{ snap.description }}
+			</p>
+		</div>
+
+		<!-- Progress: labeled steps -->
+		<div v-if="showStepsProgress" class="biab-progress biab-progress--steps">
+			<div class="biab-progress__heading">Form Progress</div>
+			<div class="biab-progress__track">
+				<template v-for="(s, i) in snap.steps" :key="`progress-${i}`">
+					<div
+						v-if="i > 0"
+						class="biab-progress__connector"
+						:class="{ 'is-done': i <= snap.step }"
+					/>
+					<div class="biab-progress__step">
+						<span
+							class="biab-progress__dot"
+							:class="{
+								'is-current': i === snap.step,
+								'is-done': i < snap.step,
+							}"
+						>
+							<span v-if="i < snap.step">✓</span>
+							<span v-else>{{ i + 1 }}</span>
+						</span>
+						<span
+							class="biab-progress__label"
+							:class="{ 'is-current': i === snap.step }"
+							>{{ stepTitle(s, i) }}</span
+						>
+					</div>
+				</template>
+			</div>
+		</div>
+
+		<!-- Progress: thin bar -->
+		<div v-if="showBarProgress" class="biab-progress biab-progress--bar">
+			<span class="biab-progress__count"
+				>{{ snap.step + 1 }} / {{ snap.stepCount }}</span
+			>
+			<div class="biab-progress__bar-track">
+				<div
+					class="biab-progress__bar-fill"
+					:style="{ width: `${snap.progressPercent}%` }"
+				/>
+			</div>
+		</div>
+
+		<!-- Form-level error summary -->
+		<div
+			v-if="snap.errorList.length > 0"
+			class="biab-form__errors"
+			role="alert"
+		>
+			<div class="biab-form__errors-title">
+				Please complete the highlighted required field{{
+					snap.errorList.length === 1 ? "" : "s"
+				}}.
+			</div>
+			<div class="biab-form__errors-list">
+				{{ snap.errorList.map((er) => er.label).join(", ") }}
+			</div>
+		</div>
+
+		<!-- Field tree for the active step (single-page = all fields) -->
+		<div :key="`step-${snap.step}`" :class="entranceClass">
+			<BiabFieldTree
+				:nodes="snap.visibleFields"
+				:flat="isConsecutive"
+				:ctx="fieldCtx"
+			/>
+		</div>
+
+		<!-- Navigation -->
+		<div v-if="isMultiStep" class="biab-nav">
+			<button
+				type="button"
+				class="biab-btn biab-btn--back"
+				:disabled="snap.isFirstStep"
+				@click="controller.back()"
+			>
+				Back
+			</button>
+			<button
+				v-if="!snap.isLastStep"
+				type="button"
+				class="biab-btn biab-btn--next"
+				:disabled="!snap.canAdvance"
+				@click="controller.next()"
+			>
+				Next
+			</button>
+			<button
+				v-else
+				type="button"
+				class="biab-btn biab-btn--submit"
+				:disabled="submitDisabled"
+				@click="handleSubmit()"
+			>
+				{{ snap.submitting ? "Sending…" : submitLabel }}
+			</button>
+		</div>
+
+		<div v-else class="biab-nav">
+			<button
+				type="button"
+				class="biab-btn biab-btn--submit"
+				:disabled="submitDisabled"
+				@click="handleSubmit()"
+			>
+				{{ snap.submitting ? "Sending…" : submitLabel }}
+			</button>
+		</div>
+
+		<!-- Inline failure message (non-validation, e.g. network / plan gate) -->
+		<p
+			v-if="
+				effectiveResult &&
+				!effectiveResult.ok &&
+				snap.errorList.length === 0
+			"
+			class="biab-form__submit-error"
+			role="alert"
+		>
+			{{ effectiveResult.message }}
+		</p>
+	</div>
+</template>