@businessdash/sdk 0.9.60

package/src/qwik.tsx

@@ -0,0 +1,1234 @@
+/** @jsxImportSource @builder.io/qwik */
+/**
+ * `@businessdash/sdk/qwik` — the `<BiabForm>` drop-in for Qwik / Qwik City.
+ *
+ * Ship mode: SOURCE (.tsx). The consumer's Qwik optimizer compiles this file —
+ * it is never tsc-built into `dist`. Keep it syntactically valid Qwik JSX and
+ * self-consistent against the headless core's PUBLIC contract; do not reach
+ * into anything but `@businessdash/sdk/forms`.
+ *
+ * ─── Architecture ────────────────────────────────────────────────────────────
+ * The headless `createFormController` (`@businessdash/sdk/forms`) owns ALL of the
+ * form's runtime state and behaviour — values, condition-aware visibility,
+ * validation mirrored 1:1 from the BIAB server, multi-step nav + progress,
+ * concurrent-reveal gating, the submit lifecycle, and file uploads. This binding
+ * stays dumb: it
+ *   1. builds the controller (client-side, inside `useVisibleTask$`),
+ *   2. mirrors its `snapshot()` into a Qwik `useStore` on every `subscribe`
+ *      notify (the idiomatic bridge from an external observable into Qwik
+ *      reactivity), and
+ *   3. renders the nested field tree by `type` using the `biab-*` light-DOM
+ *      class convention — the SAME classes the dashboard `FormPreview` renderer
+ *      uses, so a consumer's `biab-*` CSS overrides cascade identically and the
+ *      drop-in reproduces the dashboard preview (animation, multi-step progress
+ *      bar/labels, concurrent reveal, org icon).
+ *
+ * ─── Why a client-side controller + a `submit$` QRL ──────────────────────────
+ * Qwik can't serialize the controller (a closure-over-state observable) across
+ * the resumability boundary, so it is created on the client from a SERIALIZABLE
+ * pre-fetched `schema` (the SSR pattern the Qwik starter already uses with
+ * `routeLoader$`). The bearer key must never enter the client bundle, so the
+ * actual `forms.submit` round-trip is delegated to a `submit$` QRL the consumer
+ * supplies (a `server$` RPC). When a `client` is passed directly (e.g. a public
+ * key in a fully client-rendered app) the controller's own `client.forms.submit`
+ * is used and `submit$` is optional.
+ */
+
+import {
+	component$,
+	type NoSerialize,
+	noSerialize,
+	type QRL,
+	Slot,
+	useSignal,
+	useStore,
+	useVisibleTask$,
+	$,
+} from "@builder.io/qwik";
+
+import type { BiabClient } from "@businessdash/sdk";
+import {
+	type FormCoreField,
+	type FormController,
+	type FormSchema,
+	type FormSnapshot,
+	type FormSubmitOptions,
+	type FormSubmitResult,
+	concurrentRevealCount,
+	createFormController,
+	evalCondition,
+	toSubmissionPayload,
+} from "@businessdash/sdk/forms";
+import {
+	type AutocompleteConfig,
+	resolveFieldAutocomplete,
+} from "./forms-core/autocomplete.js";
+
+/**
+ * A QRL the binding can `await` and call with `(...args)`, accepting BOTH a
+ * plain client `$()` QRL AND a `server$()`-produced `ServerQRL`. `server$`
+ * widens its inner function to `((abort: AbortSignal, ...args) => R) | ((...args)
+ * => R)`, so we mirror that union here — letting consumers pass a `server$` RPC
+ * directly without importing `@builder.io/qwik-city` types into this binding.
+ * The leading `AbortSignal` is injected by the Qwik runtime, never by us.
+ */
+type ServerCompatQRL<Args extends unknown[], R> = QRL<
+	| ((...args: Args) => Promise<R>)
+	| ((abort: AbortSignal, ...args: Args) => Promise<R>)
+	// server$ handlers commonly declare ONLY the first argument (the payload).
+	// Plain function variance would allow that, but QRL's type parameter is
+	// invariant, so the narrower shapes must be named explicitly — without
+	// these, `server$((payload) => …)` from qwik-city ^1.20 fails to assign.
+	| ((first: Args[0]) => Promise<R>)
+	| ((abort: AbortSignal, first: Args[0]) => Promise<R>)
+>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public props — consistent with the other framework bindings.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface BiabFormProps {
+	/**
+	 * Pre-fetched form schema (SSR / `routeLoader$`). PREFERRED on Qwik — it is
+	 * serializable, keeps the bearer key server-side, and renders without a
+	 * client-side flicker. Either `schema` or `client` (+`slug`) is required.
+	 */
+	schema?: FormSchema;
+	/**
+	 * SDK client. Only safe in a fully client-rendered app with a public key —
+	 * it pulls the schema and (unless `submit$` is given) submits from the
+	 * browser. For SSR apps, prefer `schema` + `submit$`.
+	 */
+	client?: BiabClient;
+	/** Form slug. Required with `client` (the pre-fetched `schema` carries its own). */
+	slug?: string;
+
+	/**
+	 * Server-side submit delegate (a `server$` QRL). Receives the re-keyed
+	 * submission payload (output keys) + the merged submit options, and must
+	 * return the SDK's `FormSubmitResult`. This is how the bearer key stays out
+	 * of the client bundle. Optional when a `client` is supplied.
+	 */
+	submit$?: ServerCompatQRL<
+		[payload: Record<string, unknown>, options: FormSubmitOptions],
+		FormSubmitResult
+	>;
+	/**
+	 * Server-side file-upload delegate (a `server$` QRL) for `file_upload`
+	 * fields. Receives the field id + the picked File and must return the SDK's
+	 * `FormFileValue` (`{ storageId, url, name, mimeType, size }`). Required for
+	 * uploads in the SSR (no-client) path. Optional when a `client` is supplied.
+	 */
+	uploadFile$?: ServerCompatQRL<
+		[fieldId: string, file: File],
+		{
+			storageId: string;
+			url: string;
+			name: string;
+			mimeType: string;
+			size: number;
+		}
+	>;
+
+	/** Provenance / recipient passthrough merged into every submit (call wins). */
+	submitOptions?: FormSubmitOptions;
+	/** Convenience: lead-source provenance, folded into `submitOptions.source`. */
+	source?: string;
+	/** Test mode — validate server-side, store nothing, no side effects. */
+	dryRun?: boolean;
+
+	/** Label for the final submit button. Default "Submit". */
+	submitLabel?: string;
+
+	/**
+	 * HTML autofill global switch. Default infers a sensible `autocomplete` token
+	 * per field; `false` emits `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 token.
+	 */
+	fieldAutoComplete?: Record<string, string | boolean>;
+
+	/** Fires with the WHOLE re-keyed payload when local validation passes, before
+	 *  the network round-trip. Read-only hook for analytics / optimistic UI. */
+	onSubmit$?: QRL<(payload: Record<string, unknown>) => void>;
+	/** Fires after a successful submit (`result.ok === true`). */
+	onSuccess$?: QRL<(result: Extract<FormSubmitResult, { ok: true }>) => void>;
+	/** Fires after a failed submit (`result.ok === false`). */
+	onError$?: QRL<(result: Extract<FormSubmitResult, { ok: false }>) => void>;
+
+	/** Extra class on the root `.biab-form`. Both `class` and `className` work. */
+	class?: string;
+	className?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// A serializable mirror of the snapshot. Qwik's `useStore` deep-tracks plain
+// data; the controller's `FormSnapshot` is plain data + nested field trees, so
+// we copy the whole thing in. `result` / `schema` are plain JSON too.
+// ─────────────────────────────────────────────────────────────────────────────
+
+type SnapshotState = { snap: FormSnapshot | null };
+
+/** Read-shape of the signal holding the (client-only) controller. */
+type ControllerRef = { value: FormController | undefined };
+
+/** The resolved server-side upload delegate threaded to `file_upload` fields. */
+type UploadDelegate = BiabFormProps["uploadFile$"];
+
+/**
+ * Build the initial snapshot for SSR from a pre-fetched schema so the fields
+ * render immediately (no client flicker). `createFormController({ schema })` is
+ * a pure synchronous factory — no client / network — and `snapshot()` returns
+ * plain serializable data, which is exactly what Qwik needs to resume.
+ */
+function seedSnapshot(schema: FormSchema | undefined): FormSnapshot | null {
+	if (!schema) return null;
+	const ctrl = createFormController({ schema });
+	// `load()` adopts the pre-fetched schema synchronously (no await needed for
+	// the snapshot to become `ready`), but the synchronous factory already seeds
+	// a valid pre-load snapshot; calling load here keeps status === "ready".
+	void ctrl.load();
+	const snap = ctrl.snapshot();
+	ctrl.destroy();
+	return snap;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Field rendering — a faithful port of the dashboard `FormPreview` per-type
+// switch, using `biab-*` classes (light DOM). Qwik JSX uses `class`, not
+// `className`, and `onInput$` / `onClick$` event QRLs.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Static / layout types that never carry a submitted value (skip the label). */
+const NO_LABEL_TYPES = new Set([
+	"title",
+	"subtitle",
+	"separator",
+	"richtext",
+	"image",
+]);
+
+/** Stable, override-friendly CSS hook for a field (the `data-biab-field` value). */
+function fieldCssKey(field: FormCoreField): string {
+	const explicit =
+		typeof field.outputKey === "string" ? field.outputKey.trim() : "";
+	if (explicit) return explicit;
+	if (typeof field.key === "string" && field.key) return field.key;
+	return field.id;
+}
+
+function classOf(...parts: Array<string | false | null | undefined>): string {
+	return parts.filter(Boolean).join(" ");
+}
+
+function asString(value: unknown): string {
+	return typeof value === "string" ? value : "";
+}
+
+/**
+ * The leaf input for one value-bearing field. Reads/writes through `state.snap`
+ * via the controller's `setValue` / `uploadFile`. Renders by `type` exactly as
+ * the dashboard preview does.
+ */
+const BiabFieldInput = component$<{
+	field: FormCoreField;
+	controllerSig: ControllerRef;
+	state: SnapshotState;
+	uploadFn?: UploadDelegate;
+	acConfig: AutocompleteConfig;
+}>(({ field, controllerSig, state, uploadFn, acConfig }) => {
+	const value = state.snap?.values?.[field.id];
+
+	const set = $((v: unknown) => {
+		controllerSig.value?.setValue(field.id, v);
+	});
+
+	// Resolved HTML autofill token for this field (or `undefined` to omit the
+	// attribute). Honors the global `autoComplete` switch + per-field overrides;
+	// see forms-core/autocomplete.ts.
+	const autoComplete = resolveFieldAutocomplete(field, acConfig);
+
+	switch (field.type) {
+		case "title":
+			return <h2 class="biab-field__title">{field.label || "Untitled"}</h2>;
+		case "subtitle":
+			return <h3 class="biab-field__subtitle">{field.label || ""}</h3>;
+		case "separator":
+			return <hr class="biab-field__separator" />;
+		case "richtext":
+			// `content` is server-sanitized HTML on publish.
+			return field.content ? (
+				<div class="biab-field__richtext" dangerouslySetInnerHTML={field.content} />
+			) : null;
+		case "image":
+			return field.content ? (
+				<img class="biab-field__image" src={field.content} alt={field.label || ""} />
+			) : null;
+
+		case "textarea":
+			return (
+				<textarea
+					class="biab-input biab-textarea"
+					value={asString(value)}
+					placeholder={field.placeholder || ""}
+					rows={4}
+					autocomplete={autoComplete as AutoFill | undefined}
+					onInput$={(_, el) => void set((el as HTMLTextAreaElement).value)}
+				/>
+			);
+
+		case "select":
+			return (
+				<select
+					class="biab-input biab-select"
+					value={asString(value)}
+					onChange$={(_, el) => void set((el as HTMLSelectElement).value)}
+				>
+					<option value="">{field.placeholder || "Select..."}</option>
+					{(field.options ?? []).map((opt) => (
+						<option key={opt} value={opt}>
+							{opt}
+						</option>
+					))}
+				</select>
+			);
+
+		case "radio":
+			return (
+				<div class="biab-radio-group">
+					{(field.options ?? []).map((opt) => (
+						<label class="biab-radio" key={opt}>
+							<input
+								type="radio"
+								name={field.id}
+								value={opt}
+								checked={asString(value) === opt}
+								onChange$={() => void set(opt)}
+							/>
+							<span>{opt}</span>
+						</label>
+					))}
+				</div>
+			);
+
+		case "checkbox": {
+			const arr = Array.isArray(value) ? (value as string[]) : [];
+			return (
+				<div class="biab-checkbox-group">
+					{(field.options ?? []).map((opt) => {
+						const checked = arr.includes(opt);
+						return (
+							<label class="biab-checkbox" key={opt}>
+								<input
+									type="checkbox"
+									checked={checked}
+									onChange$={(_, el) => {
+										const next = (el as HTMLInputElement).checked
+											? [...arr, opt]
+											: arr.filter((x) => x !== opt);
+										void set(next);
+									}}
+								/>
+								<span>{opt}</span>
+							</label>
+						);
+					})}
+				</div>
+			);
+		}
+
+		case "boolean":
+			return (
+				<label class="biab-switch">
+					<input
+						type="checkbox"
+						checked={value === true}
+						onChange$={(_, el) => void set((el as HTMLInputElement).checked)}
+					/>
+					<span class="biab-switch__label">{field.placeholder || "Yes / No"}</span>
+				</label>
+			);
+
+		case "date":
+			return (
+				<input
+					class="biab-input biab-date"
+					type="date"
+					value={asString(value)}
+					onInput$={(_, el) => void set((el as HTMLInputElement).value)}
+				/>
+			);
+
+		case "date_range": {
+			const v =
+				value && typeof value === "object"
+					? (value as { start?: string; end?: string })
+					: { start: "", end: "" };
+			return (
+				<div class="biab-date-range">
+					<label class="biab-date-range__field">
+						<span class="biab-date-range__label">Start</span>
+						<input
+							class="biab-input"
+							type="date"
+							value={v.start ?? ""}
+							onInput$={(_, el) =>
+								void set({ ...v, start: (el as HTMLInputElement).value })
+							}
+						/>
+					</label>
+					<label class="biab-date-range__field">
+						<span class="biab-date-range__label">End</span>
+						<input
+							class="biab-input"
+							type="date"
+							value={v.end ?? ""}
+							onInput$={(_, el) =>
+								void set({ ...v, end: (el as HTMLInputElement).value })
+							}
+						/>
+					</label>
+				</div>
+			);
+		}
+
+		case "time_picker": {
+			const mode = field.timeConfig?.mode ?? "simple";
+			if (mode === "simple") {
+				const step = Math.max(field.timeConfig?.stepMinutes ?? 30, 1);
+				const format = field.timeConfig?.format ?? "12h";
+				const opts: string[] = [];
+				for (let h = 0; h < 24; h++) {
+					for (let m = 0; m < 60; m += step) {
+						opts.push(
+							`${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}`,
+						);
+					}
+				}
+				const fmt = (t: string) => {
+					if (format === "24h") return t;
+					const [hStr, mStr = "00"] = t.split(":");
+					const h = Number(hStr);
+					const ampm = h < 12 ? "AM" : "PM";
+					const h12 = h % 12 === 0 ? 12 : h % 12;
+					return `${h12}:${mStr} ${ampm}`;
+				};
+				return (
+					<select
+						class="biab-input biab-select biab-time"
+						value={asString(value)}
+						onChange$={(_, el) => void set((el as HTMLSelectElement).value)}
+					>
+						<option value="">{field.placeholder || "Select time"}</option>
+						{opts.map((o) => (
+							<option key={o} value={o}>
+								{fmt(o)}
+							</option>
+						))}
+					</select>
+				);
+			}
+			if (mode === "time_block") {
+				const v =
+					value && typeof value === "object"
+						? (value as { start?: string; end?: string })
+						: { start: "", end: "" };
+				return (
+					<div class="biab-time-block">
+						<label class="biab-time-block__field">
+							<span class="biab-time-block__label">Start</span>
+							<input
+								class="biab-input"
+								type="time"
+								value={v.start ?? ""}
+								onInput$={(_, el) =>
+									void set({ ...v, start: (el as HTMLInputElement).value })
+								}
+							/>
+						</label>
+						<label class="biab-time-block__field">
+							<span class="biab-time-block__label">End</span>
+							<input
+								class="biab-input"
+								type="time"
+								value={v.end ?? ""}
+								onInput$={(_, el) =>
+									void set({ ...v, end: (el as HTMLInputElement).value })
+								}
+							/>
+						</label>
+					</div>
+				);
+			}
+			// appointment
+			const v =
+				value && typeof value === "object"
+					? (value as { date?: string; time?: string })
+					: { date: "", time: "" };
+			return (
+				<div class="biab-appointment">
+					<label class="biab-appointment__field">
+						<span class="biab-appointment__label">Date</span>
+						<input
+							class="biab-input"
+							type="date"
+							value={v.date ?? ""}
+							onInput$={(_, el) =>
+								void set({ ...v, date: (el as HTMLInputElement).value })
+							}
+						/>
+					</label>
+					<label class="biab-appointment__field">
+						<span class="biab-appointment__label">Time</span>
+						<input
+							class="biab-input"
+							type="time"
+							value={v.time ?? ""}
+							onInput$={(_, el) =>
+								void set({ ...v, time: (el as HTMLInputElement).value })
+							}
+						/>
+					</label>
+				</div>
+			);
+		}
+
+		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 v = typeof value === "number" ? value : min;
+			const fmt = (n: number) =>
+				unit === "currency" ? `$${n}` : unit === "percent" ? `${n}%` : `${n}`;
+			return (
+				<div class="biab-slider">
+					<div class="biab-slider__scale">
+						<span>{fmt(min)}</span>
+						<span class="biab-slider__value">{fmt(v)}</span>
+						<span>{fmt(max)}</span>
+					</div>
+					<input
+						class="biab-slider__input"
+						type="range"
+						min={min}
+						max={max}
+						step={step}
+						value={v}
+						onInput$={(_, el) => void set(Number((el as HTMLInputElement).value))}
+					/>
+				</div>
+			);
+		}
+
+		case "star_rating": {
+			const max = field.starRatingConfig?.maxStars ?? 5;
+			const v = typeof value === "number" ? value : 0;
+			return (
+				<div class="biab-stars">
+					{Array.from({ length: max }).map((_, i) => (
+						<button
+							key={`${field.id}-star-${i}`}
+							type="button"
+							class={classOf("biab-star", i < v && "biab-star--on")}
+							aria-label={`${i + 1} star${i === 0 ? "" : "s"}`}
+							onClick$={() => void set(i + 1)}
+						>
+							★
+						</button>
+					))}
+				</div>
+			);
+		}
+
+		case "happiness_rating": {
+			const v = typeof value === "number" ? value : -1;
+			const faces = ["😞", "😕", "😐", "🙂", "😄"];
+			return (
+				<div class="biab-happiness">
+					{faces.map((emoji, i) => (
+						<button
+							key={emoji}
+							type="button"
+							class={classOf("biab-happiness__face", i === v && "biab-happiness__face--on")}
+							onClick$={() => void set(i)}
+						>
+							{emoji}
+						</button>
+					))}
+				</div>
+			);
+		}
+
+		case "stepper": {
+			const v = typeof value === "number" ? value : 0;
+			return (
+				<div class="biab-stepper">
+					<button
+						type="button"
+						class="biab-stepper__btn biab-stepper__btn--dec"
+						onClick$={() => void set(v - 1)}
+					>
+						−
+					</button>
+					<span class="biab-stepper__value">{v}</span>
+					<button
+						type="button"
+						class="biab-stepper__btn biab-stepper__btn--inc"
+						onClick$={() => void set(v + 1)}
+					>
+						+
+					</button>
+				</div>
+			);
+		}
+
+		case "color_picker": {
+			const v = asString(value);
+			return (
+				<div class="biab-colors">
+					{(field.options ?? []).map((color) => (
+						<button
+							key={color}
+							type="button"
+							class={classOf("biab-color", v === color && "biab-color--on")}
+							style={{ backgroundColor: color }}
+							title={color}
+							aria-label={color}
+							onClick$={() => void set(color)}
+						/>
+					))}
+				</div>
+			);
+		}
+
+		case "address": {
+			const v = (value && typeof value === "object" ? value : {}) as Record<
+				string,
+				string
+			>;
+			// Per-subfield autofill tokens (street/line2/city/state/zip), suppressed
+			// to "off" when autofill is off for this field (global switch or override).
+			const acOff = autoComplete === "off";
+			const part = (
+				key: string,
+				label: string,
+				ac: string,
+			) => (
+				<label class={classOf("biab-address__field", `biab-address__field--${key}`)}>
+					<span class="biab-address__label">{label}</span>
+					<input
+						class="biab-input"
+						value={v[key] ?? ""}
+						autoComplete={acOff ? "off" : ac}
+						onInput$={(_, el) =>
+							void set({ ...v, [key]: (el as HTMLInputElement).value })
+						}
+					/>
+				</label>
+			);
+			return (
+				<div class="biab-address">
+					{part("line1", "Address Line 1", "street-address")}
+					{part("line2", "Address Line 2", "address-line2")}
+					{part("city", "City", "address-level2")}
+					{part("state", "State", "address-level1")}
+					{part("zip", "Zip", "postal-code")}
+				</div>
+			);
+		}
+
+		case "file_upload": {
+			const files = Array.isArray(value)
+				? (value as Array<{ name: string; size: number; url: string }>)
+				: [];
+			const maxFiles = field.fileConfig?.maxFiles ?? 1;
+			const allowed = field.fileConfig?.allowedTypes;
+			const accept = allowed && allowed.length > 0 ? allowed.join(",") : undefined;
+			const remaining = Math.max(maxFiles - files.length, 0);
+			const uploading = state.snap?.uploading === true;
+			return (
+				<div class="biab-file">
+					<input
+						class="biab-file__input"
+						type="file"
+						multiple={maxFiles > 1}
+						accept={accept}
+						disabled={uploading || remaining === 0}
+						onChange$={async (_, el) => {
+							const picked = (el as HTMLInputElement).files;
+							const ctrl = controllerSig.value;
+							if (!picked || picked.length === 0 || !ctrl) return;
+							const list = Array.from(picked).slice(0, remaining);
+							for (const file of list) {
+								try {
+									if (uploadFn) {
+										// SSR / no-client path: upload via the consumer's `server$`
+										// delegate (bearer key stays server-side), then append the
+										// returned FormFileValue to this field's value array.
+										const uploaded = await uploadFn(field.id, file);
+										const existing = Array.isArray(
+											ctrl.snapshot().values[field.id],
+										)
+											? (ctrl.snapshot().values[field.id] as unknown[])
+											: [];
+										ctrl.setValue(field.id, [...existing, uploaded]);
+									} else {
+										// Client path: the controller uploads via its own SDK client.
+										await ctrl.uploadFile(field.id, file, {
+											filename: file.name,
+										});
+									}
+								} catch {
+									/* controller surfaces upload state; swallow per-file failure */
+								}
+							}
+							(el as HTMLInputElement).value = "";
+						}}
+					/>
+					{uploading ? <span class="biab-file__status">Uploading…</span> : null}
+					{files.length > 0 ? (
+						<ul class="biab-file__list">
+							{files.map((f, idx) => (
+								<li class="biab-file__item" key={`${f.url}-${idx}`}>
+									<span class="biab-file__name">{f.name}</span>
+									<span class="biab-file__size">
+										{Math.round(f.size / 1024)} KB
+									</span>
+								</li>
+							))}
+						</ul>
+					) : null}
+				</div>
+			);
+		}
+
+		case "phone":
+			return (
+				<input
+					class="biab-input biab-phone"
+					type="tel"
+					value={asString(value)}
+					placeholder={
+						field.placeholder ||
+						(field.phoneConfig?.international
+							? "+1 (555) 000-0000"
+							: "(555) 000-0000")
+					}
+					autoComplete={autoComplete}
+					onInput$={(_, el) => void set((el as HTMLInputElement).value)}
+				/>
+			);
+
+		case "email":
+			return (
+				<input
+					class="biab-input biab-email"
+					type="email"
+					value={asString(value)}
+					placeholder={field.placeholder || "you@example.com"}
+					autoComplete={autoComplete}
+					onInput$={(_, el) => void set((el as HTMLInputElement).value)}
+				/>
+			);
+
+		case "number":
+			return (
+				<input
+					class="biab-input biab-number"
+					type="number"
+					value={typeof value === "number" ? value : asString(value)}
+					placeholder={field.placeholder || ""}
+					onInput$={(_, el) => {
+						const raw = (el as HTMLInputElement).value;
+						void set(raw === "" ? "" : Number(raw));
+					}}
+				/>
+			);
+
+		default:
+			return (
+				<input
+					class="biab-input biab-text"
+					type="text"
+					value={asString(value)}
+					placeholder={field.placeholder || ""}
+					autoComplete={autoComplete}
+					onInput$={(_, el) => void set((el as HTMLInputElement).value)}
+				/>
+			);
+	}
+});
+
+/**
+ * One field "row": the `biab-field` wrapper with stable data-attrs + error /
+ * help text, mirroring the dashboard `FieldRow`.
+ */
+const BiabFieldRow = component$<{
+	field: FormCoreField;
+	controllerSig: ControllerRef;
+	state: SnapshotState;
+	uploadFn?: UploadDelegate;
+	acConfig: AutocompleteConfig;
+}>(({ field, controllerSig, state, uploadFn, acConfig }) => {
+	const showLabel = !NO_LABEL_TYPES.has(field.type);
+	const error = state.snap?.errors?.[field.id];
+	return (
+		<div
+			class={classOf(
+				"biab-field",
+				`biab-field--${field.type}`,
+				field.required && "biab-field--required",
+				error && "biab-field--error",
+			)}
+			data-biab-field={fieldCssKey(field)}
+			data-biab-type={field.type}
+		>
+			{showLabel ? (
+				<label class="biab-field__label">
+					{field.label || ""}
+					{field.required ? <span class="biab-field__required">*</span> : null}
+				</label>
+			) : null}
+			<BiabFieldInput
+				field={field}
+				controllerSig={controllerSig}
+				state={state}
+				uploadFn={uploadFn}
+				acConfig={acConfig}
+			/>
+			{error ? <p class="biab-field__error">{error.message}</p> : null}
+			{field.helpText ? (
+				<p class="biab-field__help">{field.helpText}</p>
+			) : null}
+		</div>
+	);
+});
+
+/**
+ * Recursive render of the nested field tree — mirrors `FormPreview.RenderTree`:
+ * `input_group` (with concurrent-reveal gating + optional group label),
+ * `condition_block` (skipped when its rule is false), `or_condition` (two sides
+ * with an OR divider), `flex_row` (inline row), else a `BiabFieldRow`.
+ */
+const BiabRenderTree = component$<{
+	fields: FormCoreField[];
+	controllerSig: ControllerRef;
+	state: SnapshotState;
+	uploadFn?: UploadDelegate;
+	acConfig: AutocompleteConfig;
+	flat?: boolean;
+}>(({ fields, controllerSig, state, uploadFn, acConfig, flat }) => {
+	const data = state.snap?.values ?? {};
+	return (
+		<div class="biab-tree">
+			{fields.map((f) => {
+				if (f.type === "input_group") {
+					const children = (f.children ?? []) as FormCoreField[];
+					const concurrent = f.concurrentReveal === true;
+					const showGroupLabel = f.showGroupLabel === true;
+					const revealCount = concurrent
+						? concurrentRevealCount(children, data)
+						: children.length;
+					const shown = children.slice(0, revealCount);
+					return (
+						<div
+							key={f.id}
+							class={classOf("biab-group", flat && "biab-group--flat")}
+							data-biab-group={fieldCssKey(f)}
+						>
+							{f.label && showGroupLabel ? (
+								<div class="biab-group__label">{f.label}</div>
+							) : null}
+							<BiabRenderTree
+								fields={shown}
+								controllerSig={controllerSig}
+								state={state}
+								uploadFn={uploadFn}
+								acConfig={acConfig}
+							/>
+						</div>
+					);
+				}
+
+				if (f.type === "condition_block") {
+					if (!evalCondition(f.conditionRule, data)) return null;
+					return (
+						<BiabRenderTree
+							key={f.id}
+							fields={(f.children ?? []) as FormCoreField[]}
+							controllerSig={controllerSig}
+							state={state}
+							uploadFn={uploadFn}
+							acConfig={acConfig}
+						/>
+					);
+				}
+
+				if (f.type === "or_condition") {
+					const left = f.children?.[0];
+					const right = f.children?.[1];
+					const error = state.snap?.errors?.[f.id];
+					return (
+						<div
+							key={f.id}
+							class={classOf("biab-or", error && "biab-or--error")}
+							data-biab-or={fieldCssKey(f)}
+						>
+							{f.label ? (
+								<div class="biab-or__label">
+									{f.label}
+									<span class="biab-or__hint">Fill at least one side</span>
+								</div>
+							) : null}
+							<div class="biab-or__grid">
+								<div class="biab-or__side biab-or__side--left">
+									<div class="biab-or__side-label">
+										{f.orConditionConfig?.leftLabel || "Option A"}
+									</div>
+									{left ? (
+										<BiabRenderTree
+											fields={[left]}
+											controllerSig={controllerSig}
+											state={state}
+											uploadFn={uploadFn}
+											acConfig={acConfig}
+										/>
+									) : null}
+								</div>
+								<div class="biab-or__divider">
+									<span class="biab-or__badge">OR</span>
+								</div>
+								<div class="biab-or__side biab-or__side--right">
+									<div class="biab-or__side-label">
+										{f.orConditionConfig?.rightLabel || "Option B"}
+									</div>
+									{right ? (
+										<BiabRenderTree
+											fields={[right]}
+											controllerSig={controllerSig}
+											state={state}
+											uploadFn={uploadFn}
+											acConfig={acConfig}
+										/>
+									) : null}
+								</div>
+							</div>
+							{error ? (
+								<p class="biab-or__error">Fill in at least one side to continue.</p>
+							) : null}
+						</div>
+					);
+				}
+
+				if (f.type === "flex_row") {
+					const children = (f.children ?? []) as FormCoreField[];
+					return (
+						<div key={f.id} class="biab-flex-row">
+							{children.map((child) => (
+								<div class="biab-flex-row__cell" key={child.id}>
+									<BiabFieldRow
+										field={child}
+										controllerSig={controllerSig}
+										state={state}
+										uploadFn={uploadFn}
+										acConfig={acConfig}
+									/>
+								</div>
+							))}
+						</div>
+					);
+				}
+
+				return (
+					<BiabFieldRow
+						key={f.id}
+						field={f}
+						controllerSig={controllerSig}
+						state={state}
+						uploadFn={uploadFn}
+						acConfig={acConfig}
+					/>
+				);
+			})}
+		</div>
+	);
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// <BiabForm> — the drop-in.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const BiabForm = component$<BiabFormProps>((props) => {
+	// The controller lives only on the client (it's a non-serializable closure).
+	// `noSerialize()` tells Qwik to drop it from the resumable state instead of
+	// trying (and failing) to serialize the closure; it is re-created in the
+	// client-only `useVisibleTask$` below.
+	const controllerSig = useSignal<NoSerialize<FormController> | undefined>(
+		undefined,
+	);
+	// Serializable mirror of the controller's snapshot — drives every render.
+	const state = useStore<SnapshotState>(
+		{
+			// Seed from the pre-fetched schema so SSR renders the fields immediately
+			// (no flicker). The controller re-adopts this same schema on the client.
+			snap: seedSnapshot(props.schema),
+		},
+		{ deep: true },
+	);
+
+	// eslint-disable-next-line qwik/no-use-visible-task
+	useVisibleTask$(({ cleanup }) => {
+		// Build the controller client-side. `submit$` / `uploadFile$` keep the
+		// bearer key server-side; the controller's own client is the fallback when
+		// a `client` was passed directly.
+		const submitOptions: FormSubmitOptions = {
+			...props.submitOptions,
+			...(props.source ? { source: props.source } : {}),
+			...(props.dryRun ? { dryRun: true } : {}),
+		};
+
+		const controller = createFormController({
+			...(props.client ? { client: props.client } : {}),
+			...(props.schema ? { schema: props.schema } : {}),
+			...(props.slug ? { slug: props.slug } : {}),
+			submitOptions,
+			onSuccess: (result) => {
+				void props.onSuccess$?.(result);
+			},
+			onError: (result) => {
+				void props.onError$?.(result);
+			},
+		});
+		controllerSig.value = noSerialize(controller);
+
+		// Mirror the snapshot into the reactive store on every notify.
+		const unsubscribe = controller.subscribe((snap) => {
+			state.snap = snap;
+		});
+		// Load (adopts the pre-fetched schema synchronously, or fetches via client).
+		void controller.load().then(() => {
+			state.snap = controller.snapshot();
+		});
+
+		cleanup(() => {
+			unsubscribe();
+			controller.destroy();
+		});
+	});
+
+	const rootClass = classOf("biab-form", props.class, props.className);
+
+	// HTML autofill config threaded to every field input. A plain serializable
+	// object (Qwik-friendly): the global switch + per-field overrides. Mirrors the
+	// React adapter; resolution lives in forms-core/autocomplete.ts.
+	const acConfig: AutocompleteConfig = {
+		...(props.autoComplete !== undefined ? { enabled: props.autoComplete } : {}),
+		...(props.fieldAutoComplete ? { overrides: props.fieldAutoComplete } : {}),
+	};
+
+	// ── Submit handler — routes through `submit$` (server) when present, else the
+	//    controller's own SDK client. Validation + re-keying happen in the core. ──
+	const handleSubmit = $(async () => {
+		const controller = controllerSig.value;
+		if (!controller) return;
+
+		if (props.submit$) {
+			// SSR path: validate + re-key in the core, delegate the round-trip to
+			// the consumer's `server$`. `validate()` publishes inline errors; the
+			// core's `toSubmissionPayload` re-keys id → output key.
+			const missing = controller.validate();
+			if (missing.length > 0) return;
+			const snap = controller.snapshot();
+			// Re-key for the wire via the SAME mapping the core uses on submit
+			// (id → published output key; the server also accepts the legacy id).
+			const payload = toSubmissionPayload(snap.fields, snap.values);
+			void props.onSubmit$?.(payload);
+			const mergedOptions: FormSubmitOptions = {
+				...props.submitOptions,
+				...(props.source ? { source: props.source } : {}),
+				...(props.dryRun ? { dryRun: true } : {}),
+			};
+			const result = await props.submit$(payload, mergedOptions);
+			// Feed the server result back through the store for inline rendering.
+			state.snap = { ...controller.snapshot(), result, submitted: result.ok };
+			if (result.ok) void props.onSuccess$?.(result);
+			else void props.onError$?.(result);
+			return;
+		}
+
+		// Client path: the controller owns validation + the round-trip via its SDK.
+		await controller.submit();
+	});
+
+	const snap = state.snap;
+	if (!snap || snap.status === "loading" || snap.status === "idle") {
+		return (
+			<div class={rootClass} data-biab-status="loading">
+				<Slot name="loading" />
+			</div>
+		);
+	}
+	if (snap.status === "error") {
+		return (
+			<div class={rootClass} data-biab-status="error">
+				<Slot name="error" />
+				<p class="biab-form__load-error">
+					{snap.loadError ?? "Could not load the form."}
+				</p>
+			</div>
+		);
+	}
+
+	const settings = snap.settings;
+	const consecutive = settings.isConsecutive;
+	const showSteps =
+		consecutive &&
+		settings.showProgress &&
+		settings.progressStyle !== "bar" &&
+		snap.stepCount > 1;
+	const showBar =
+		consecutive &&
+		settings.showProgress &&
+		settings.progressStyle === "bar" &&
+		snap.stepCount > 1;
+
+	// Animation entrance class (per dashboard `entranceClass`). "scroll" is left
+	// to the consumer's CSS via the `biab-form--anim-scroll` hook.
+	const animClass =
+		settings.animation === "none" ? "" : `biab-form--anim-${settings.animation}`;
+	const dirClass = snap.forward ? "biab-form--forward" : "biab-form--back";
+
+	if (snap.submitted) {
+		return (
+			<div class={classOf(rootClass, "biab-form--submitted")} data-biab-status="submitted">
+				<Slot name="success" />
+			</div>
+		);
+	}
+
+	return (
+		<div class={rootClass} data-biab-status="ready" data-biab-animation={settings.animation}>
+			{snap.orgIcon ? (
+				<img class="biab-form__org-icon" src={snap.orgIcon} alt="" />
+			) : null}
+
+			{snap.title ? <h2 class="biab-form__title">{snap.title}</h2> : null}
+			{snap.description ? (
+				<p class="biab-form__description">{snap.description}</p>
+			) : null}
+
+			{showSteps ? (
+				<div class="biab-progress biab-progress--steps">
+					<div class="biab-progress__heading">Form Progress</div>
+					<ol class="biab-progress__steps">
+						{snap.steps.map((s, i) => {
+							const head = s[0];
+							const title = head?.stepTitle || head?.label || `Step ${i + 1}`;
+							const done = i < snap.step;
+							const current = i === snap.step;
+							return (
+								<li
+									key={`biab-step-${i}`}
+									class={classOf(
+										"biab-progress__step",
+										current && "biab-progress__step--current",
+										done && "biab-progress__step--done",
+									)}
+								>
+									<span class="biab-progress__marker">{done ? "✓" : i + 1}</span>
+									<span class="biab-progress__title">{title}</span>
+								</li>
+							);
+						})}
+					</ol>
+				</div>
+			) : null}
+
+			{showBar ? (
+				<div class="biab-progress biab-progress--bar">
+					<span class="biab-progress__count">
+						{snap.step + 1} / {snap.stepCount}
+					</span>
+					<div class="biab-progress__track">
+						<div
+							class="biab-progress__fill"
+							style={{ width: `${snap.progressPercent}%` }}
+						/>
+					</div>
+				</div>
+			) : null}
+
+			{snap.errorList.length > 0 ? (
+				<div class="biab-form__errors" role="alert">
+					<div class="biab-form__errors-heading">
+						Please complete the highlighted required field
+						{snap.errorList.length === 1 ? "" : "s"}.
+					</div>
+					<div class="biab-form__errors-list">
+						{snap.errorList.map((e) => e.label).join(", ")}
+					</div>
+				</div>
+			) : null}
+
+			<div class={classOf("biab-form__body", animClass, dirClass)} key={`biab-body-${snap.step}`}>
+				<BiabRenderTree
+					fields={snap.visibleFields}
+					controllerSig={controllerSig}
+					state={state}
+					uploadFn={props.uploadFile$}
+					acConfig={acConfig}
+					flat={consecutive}
+				/>
+			</div>
+
+			{consecutive && snap.stepCount > 1 ? (
+				<div class="biab-nav">
+					<button
+						type="button"
+						class="biab-btn biab-btn--back"
+						disabled={snap.isFirstStep}
+						onClick$={() => controllerSig.value?.back()}
+					>
+						Back
+					</button>
+					{snap.isLastStep ? (
+						<button
+							type="button"
+							class="biab-btn biab-btn--submit"
+							disabled={snap.submitting || snap.uploading}
+							onClick$={handleSubmit}
+						>
+							{snap.submitting ? "Sending…" : props.submitLabel || "Submit"}
+						</button>
+					) : (
+						<button
+							type="button"
+							class="biab-btn biab-btn--next"
+							disabled={!snap.canAdvance}
+							onClick$={() => controllerSig.value?.next()}
+						>
+							Next
+						</button>
+					)}
+				</div>
+			) : (
+				<div class="biab-nav">
+					<button
+						type="button"
+						class="biab-btn biab-btn--submit"
+						disabled={snap.submitting || snap.uploading}
+						onClick$={handleSubmit}
+					>
+						{snap.submitting ? "Sending…" : props.submitLabel || "Submit"}
+					</button>
+				</div>
+			)}
+		</div>
+	);
+});
+
+export default BiabForm;