@businessdash/sdk 0.9.60

package/src/solid.tsx

@@ -0,0 +1,1466 @@
+/**
+ * `@businessdash/sdk/solid` — the `<BiabForm>` drop-in for SolidJS.
+ *
+ * Ship mode: SOURCE (.tsx). This file is published as-is and compiled by the
+ * consumer's Solid/JSX toolchain (vite-plugin-solid / babel-preset-solid). It is
+ * NOT tsc-compiled inside biab-dev, so it has zero build artifact here.
+ *
+ * It is a thin, idiomatic Solid view over the framework-agnostic headless core
+ * (`createFormController`, exported from `@businessdash/sdk/forms`). All runtime
+ * behaviour — values, errors, condition-aware visibility, multi-step nav,
+ * concurrent-reveal gating, submit lifecycle, file uploads — lives in the core.
+ * The binding only:
+ *
+ *   1. Bridges the controller's subscribe/snapshot observable into Solid
+ *      reactivity with `from()` (the canonical "external store → Signal" adapter).
+ *   2. Renders the snapshot's nested field tree by `type` using the `biab-*`
+ *      light-DOM class convention (no shadow root) so the consumer's own CSS
+ *      cascades onto every field.
+ *   3. Applies the published `schema.settings` (animation, multi-step + progress
+ *      bar/steps, concurrent reveal) and the org icon, so the drop-in reproduces
+ *      the dashboard's form preview 1:1.
+ *
+ * Data flows entirely through the SDK client (auth, caching, revalidation, HMAC,
+ * retries, CRM fan-out all stay invisible). SSR / RSC callers can hand a
+ * pre-fetched `schema` instead of a `client`.
+ *
+ * @module
+ */
+
+import type { JSX } from "solid-js";
+import {
+	type Accessor,
+	For,
+	Match,
+	Show,
+	Switch,
+	createContext,
+	createMemo,
+	createSignal,
+	createUniqueId,
+	from,
+	onCleanup,
+	onMount,
+	useContext,
+} from "solid-js";
+
+import type {
+	BiabClient,
+	FormFileValue,
+	FormSchema,
+	FormSubmitResult,
+} from "./sdk.js";
+import {
+	type CreateFormControllerOptions,
+	type FieldError,
+	type FormController,
+	type FormCoreField,
+	type FormSnapshot,
+	type FormSubmitOptions,
+	concurrentRevealCount,
+	createFormController,
+	evalCondition,
+} from "./forms-core/index.js";
+import {
+	type AutocompleteConfig,
+	resolveFieldAutocomplete,
+} from "./forms-core/autocomplete.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Client context — optional Provider-based DI so a tree of `<BiabForm>`s can
+// share one client instead of threading `client` through every prop.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const BiabClientContext = createContext<Accessor<BiabClient | undefined>>();
+
+export interface BiabProviderProps {
+	/** The SDK client shared with descendant `<BiabForm>`s. */
+	client: BiabClient;
+	children?: JSX.Element;
+}
+
+/**
+ * Provide a single `BiabClient` to a subtree. Any descendant `<BiabForm>` that
+ * doesn't get its own `client` prop falls back to this one. Optional — passing
+ * `client` directly to `<BiabForm>` works without a provider.
+ */
+export function BiabProvider(props: BiabProviderProps): JSX.Element {
+	const value = createMemo(() => props.client);
+	return (
+		<BiabClientContext.Provider value={value}>
+			{props.children}
+		</BiabClientContext.Provider>
+	);
+}
+
+/** Read the client supplied by the nearest `<BiabProvider>` (or `undefined`). */
+export function useBiabClient(): BiabClient | undefined {
+	const ctx = useContext(BiabClientContext);
+	return ctx?.();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// createFormStore — bridge a FormController into a reactive Solid accessor.
+//
+// `from()` adopts the controller's subscribe/notify observable; we seed it with
+// the current `snapshot()` so the accessor is valid synchronously (the core does
+// NOT replay on subscribe). The returned accessor re-runs any tracking scope on
+// every notify. Disposes the controller on cleanup.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface BiabFormStore {
+	/** Reactive snapshot accessor — read it inside JSX / memos to track changes. */
+	snapshot: Accessor<FormSnapshot>;
+	/** The underlying controller (imperative escape hatch). */
+	controller: FormController;
+}
+
+/**
+ * Create a controller-backed reactive store. Kicks off `load()` on mount (so
+ * SSR-adopted schemas stay synchronous and client loads fire once), and tears
+ * the controller down on cleanup. Use this when you want the headless behaviour
+ * but your own markup; `<BiabForm>` uses it internally.
+ */
+export function createFormStore(
+	options: CreateFormControllerOptions,
+): BiabFormStore {
+	const controller = createFormController(options);
+
+	// `from` wraps the subscribe contract: it calls subscribe(setter) and returns
+	// an accessor. We pre-seed with snapshot() because the core never replays on
+	// subscribe, so the very first read must not be undefined.
+	const tracked = from<FormSnapshot>((set) => {
+		set(controller.snapshot());
+		return controller.subscribe(set);
+	});
+	// `from` accessors are `T | undefined` until the first emit; the seed above
+	// makes that window empty, but narrow it for callers regardless.
+	const snapshot: Accessor<FormSnapshot> = () =>
+		tracked() ?? controller.snapshot();
+
+	onMount(() => {
+		void controller.load();
+	});
+	onCleanup(() => controller.destroy());
+
+	return { snapshot, controller };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CSS-hook helpers — mirror the dashboard renderer's `data-biab-*` attributes so
+// org overrides written against the dashboard preview also target this drop-in.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** camelCase a label into a stable object-key slug (mirrors output-keys.ts). */
+function slugifyLabel(raw: string): string {
+	const words = raw
+		.replace(/[^a-zA-Z0-9]+/g, " ")
+		.trim()
+		.split(/\s+/)
+		.filter(Boolean);
+	if (words.length === 0) return "";
+	const key = words
+		.map((w, i) =>
+			i === 0
+				? w.toLowerCase()
+				: w.charAt(0).toUpperCase() + w.slice(1).toLowerCase(),
+		)
+		.join("");
+	return /^[0-9]/.test(key) ? `_${key}` : key;
+}
+
+/**
+ * The `data-biab-field` value: a published `key`, else an explicit `outputKey`,
+ * else a camelCase slug of the label, else the id. Lets orgs target one field.
+ */
+function fieldCssKey(field: FormCoreField): string {
+	const published = typeof field.key === "string" ? field.key.trim() : "";
+	if (published) return published;
+	const explicit =
+		typeof field.outputKey === "string" ? field.outputKey.trim() : "";
+	if (explicit) return explicit;
+	const label = typeof field.label === "string" ? field.label.trim() : "";
+	return (label && slugifyLabel(label)) || field.id;
+}
+
+const STATIC_NO_LABEL = new Set(["title", "subtitle", "separator", "richtext"]);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FieldInput — render one value-bearing field by `type`. Solid-idiomatic: each
+// `case` reads `props.value` reactively (the parent passes a live accessor) and
+// writes back via `props.set`. Mirrors FormPreview's `FieldInput`.
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface FieldInputProps {
+	field: FormCoreField;
+	value: Accessor<unknown>;
+	set: (next: unknown) => void;
+	uploadFile?: (file: File, filename?: string) => Promise<FormFileValue>;
+	uploading: Accessor<boolean>;
+	/** Resolve the HTML autofill token for this field (or `undefined` to omit). */
+	autocomplete?: (field: FormCoreField) => string | undefined;
+}
+
+function asString(v: unknown): string {
+	return typeof v === "string" ? v : "";
+}
+
+function FieldInput(props: FieldInputProps): JSX.Element {
+	const t = () => props.field.type;
+	const field = () => props.field;
+	// Resolved HTML autofill token for this field (or undefined to omit the
+	// attribute). Honors the global `<BiabForm autoComplete>` switch and per-field
+	// overrides; see forms-core/autocomplete.ts.
+	const ac = () => props.autocomplete?.(props.field);
+
+	return (
+		<Switch
+			fallback={
+				<input
+					class="biab-input"
+					type="text"
+					placeholder={field().placeholder ?? ""}
+					value={asString(props.value())}
+					onInput={(e) => props.set(e.currentTarget.value)}
+					autocomplete={ac()}
+				/>
+			}
+		>
+			<Match when={t() === "title"}>
+				<h2 class="biab-field__title">{field().label || "Untitled"}</h2>
+			</Match>
+			<Match when={t() === "subtitle"}>
+				<h3 class="biab-field__subtitle">{field().label || ""}</h3>
+			</Match>
+			<Match when={t() === "separator"}>
+				<hr class="biab-field__separator" />
+			</Match>
+			<Match when={t() === "richtext"}>
+				{/* The published content is org-authored; render it as plain text to
+				    keep the binding free of an HTML-sanitizer dependency. Consumers
+				    needing rich HTML can override this field via the `field` slot. */}
+				<div class="biab-field__richtext">{field().content ?? ""}</div>
+			</Match>
+			<Match when={t() === "image"}>
+				<Show when={(field().imageConfig as { src?: string })?.src}>
+					{(src) => (
+						<img
+							class="biab-field__image"
+							src={src()}
+							alt={(field().imageConfig as { alt?: string })?.alt ?? ""}
+						/>
+					)}
+				</Show>
+			</Match>
+
+			<Match when={t() === "textarea"}>
+				<textarea
+					class="biab-textarea"
+					placeholder={field().placeholder ?? ""}
+					rows={(field().textareaConfig as { rows?: number })?.rows ?? 4}
+					value={asString(props.value())}
+					onInput={(e) => props.set(e.currentTarget.value)}
+					autocomplete={ac()}
+				/>
+			</Match>
+
+			<Match when={t() === "select"}>
+				<select
+					class="biab-input biab-select"
+					value={asString(props.value())}
+					onChange={(e) => props.set(e.currentTarget.value)}
+				>
+					<option value="" disabled>
+						{field().placeholder || "Select..."}
+					</option>
+					<For each={field().options ?? []}>
+						{(opt) => <option value={opt}>{opt}</option>}
+					</For>
+				</select>
+			</Match>
+
+			<Match when={t() === "radio"}>
+				<div class="biab-radio-group">
+					<For each={field().options ?? []}>
+						{(opt) => {
+							const id = `${field().id}-${opt}`;
+							return (
+								<label class="biab-radio" for={id}>
+									<input
+										type="radio"
+										id={id}
+										name={field().id}
+										value={opt}
+										checked={asString(props.value()) === opt}
+										onChange={() => props.set(opt)}
+									/>
+									<span class="biab-radio__label">{opt}</span>
+								</label>
+							);
+						}}
+					</For>
+				</div>
+			</Match>
+
+			<Match when={t() === "checkbox"}>
+				<div class="biab-checkbox-group">
+					<For each={field().options ?? []}>
+						{(opt) => {
+							const arr = () =>
+								Array.isArray(props.value())
+									? (props.value() as string[])
+									: [];
+							return (
+								<label class="biab-checkbox">
+									<input
+										type="checkbox"
+										value={opt}
+										checked={arr().includes(opt)}
+										onChange={(e) => {
+											const cur = arr();
+											props.set(
+												e.currentTarget.checked
+													? [...cur, opt]
+													: cur.filter((x) => x !== opt),
+											);
+										}}
+									/>
+									<span class="biab-checkbox__label">{opt}</span>
+								</label>
+							);
+						}}
+					</For>
+				</div>
+			</Match>
+
+			<Match when={t() === "boolean"}>
+				<label class="biab-switch">
+					<input
+						type="checkbox"
+						checked={props.value() === true}
+						onChange={(e) => props.set(e.currentTarget.checked)}
+					/>
+					<span class="biab-switch__label">
+						{field().placeholder || "Yes / No"}
+					</span>
+				</label>
+			</Match>
+
+			<Match when={t() === "date"}>
+				<input
+					class="biab-input"
+					type="date"
+					value={asString(props.value())}
+					onInput={(e) => props.set(e.currentTarget.value)}
+				/>
+			</Match>
+
+			<Match when={t() === "email"}>
+				<input
+					class="biab-input"
+					type="email"
+					placeholder={field().placeholder || "you@example.com"}
+					value={asString(props.value())}
+					onInput={(e) => props.set(e.currentTarget.value)}
+					autocomplete={ac()}
+				/>
+			</Match>
+
+			<Match when={t() === "phone"}>
+				<div class="biab-phone">
+					<Show when={(field().phoneConfig as { showFlags?: boolean })?.showFlags}>
+						<span class="biab-phone__flag" aria-hidden="true">
+							🇺🇸
+						</span>
+					</Show>
+					<input
+						class="biab-input"
+						type="tel"
+						placeholder={
+							field().placeholder ||
+							((field().phoneConfig as { international?: boolean })?.international
+								? "+1 (555) 000-0000"
+								: "(555) 000-0000")
+						}
+						value={asString(props.value())}
+						onInput={(e) => props.set(e.currentTarget.value)}
+						autocomplete={ac()}
+					/>
+				</div>
+			</Match>
+
+			<Match when={t() === "number"}>
+				<input
+					class="biab-input"
+					type="number"
+					placeholder={field().placeholder ?? ""}
+					value={
+						typeof props.value() === "number"
+							? (props.value() as number)
+							: asString(props.value())
+					}
+					onInput={(e) =>
+						props.set(
+							e.currentTarget.value === ""
+								? ""
+								: Number(e.currentTarget.value),
+						)
+					}
+				/>
+			</Match>
+
+			<Match when={t() === "color_picker"}>
+				<div class="biab-color-group">
+					<For each={field().options ?? []}>
+						{(color) => (
+							<button
+								type="button"
+								class="biab-color-swatch"
+								classList={{
+									"biab-color-swatch--selected":
+										asString(props.value()) === color,
+								}}
+								style={{ "background-color": color }}
+								title={color}
+								onClick={() => props.set(color)}
+							/>
+						)}
+					</For>
+				</div>
+			</Match>
+
+			<Match when={t() === "slider"}>
+				{(() => {
+					const cfg = () =>
+						(field().sliderConfig ?? {}) as {
+							min?: number;
+							max?: number;
+							step?: number;
+							unit?: string;
+						};
+					const min = () => cfg().min ?? 0;
+					const max = () => cfg().max ?? 100;
+					const cur = () =>
+						typeof props.value() === "number"
+							? (props.value() as number)
+							: min();
+					const fmt = (n: number) =>
+						cfg().unit === "currency"
+							? `$${n}`
+							: cfg().unit === "percent"
+								? `${n}%`
+								: `${n}`;
+					return (
+						<div class="biab-slider">
+							<div class="biab-slider__scale">
+								<span>{fmt(min())}</span>
+								<span class="biab-slider__value">{fmt(cur())}</span>
+								<span>{fmt(max())}</span>
+							</div>
+							<input
+								type="range"
+								min={min()}
+								max={max()}
+								step={cfg().step ?? 1}
+								value={cur()}
+								onInput={(e) => props.set(Number(e.currentTarget.value))}
+							/>
+						</div>
+					);
+				})()}
+			</Match>
+
+			<Match when={t() === "stepper"}>
+				{(() => {
+					const cur = () =>
+						typeof props.value() === "number" ? (props.value() as number) : 0;
+					return (
+						<div class="biab-stepper">
+							<button
+								type="button"
+								class="biab-stepper__btn"
+								onClick={() => props.set(cur() - 1)}
+							>
+								−
+							</button>
+							<span class="biab-stepper__value">{cur()}</span>
+							<button
+								type="button"
+								class="biab-stepper__btn"
+								onClick={() => props.set(cur() + 1)}
+							>
+								+
+							</button>
+						</div>
+					);
+				})()}
+			</Match>
+
+			<Match when={t() === "star_rating"}>
+				{(() => {
+					const maxStars = () =>
+						(field().starRatingConfig as { maxStars?: number })?.maxStars ?? 5;
+					const cur = () =>
+						typeof props.value() === "number" ? (props.value() as number) : 0;
+					return (
+						<div class="biab-stars">
+							<For each={Array.from({ length: maxStars() })}>
+								{(_, i) => (
+									<button
+										type="button"
+										class="biab-stars__star"
+										classList={{ "biab-stars__star--on": i() < cur() }}
+										aria-label={`${i() + 1} star`}
+										onClick={() => props.set(i() + 1)}
+									>
+										★
+									</button>
+								)}
+							</For>
+						</div>
+					);
+				})()}
+			</Match>
+
+			<Match when={t() === "happiness_rating"}>
+				{(() => {
+					const cur = () =>
+						typeof props.value() === "number" ? (props.value() as number) : -1;
+					const emojis = ["😞", "😕", "😐", "🙂", "😄"];
+					return (
+						<div class="biab-happiness">
+							<For each={emojis}>
+								{(emoji, i) => (
+									<button
+										type="button"
+										class="biab-happiness__face"
+										classList={{ "biab-happiness__face--on": i() === cur() }}
+										onClick={() => props.set(i())}
+									>
+										{emoji}
+									</button>
+								)}
+							</For>
+						</div>
+					);
+				})()}
+			</Match>
+
+			<Match when={t() === "time_picker"}>
+				{(() => {
+					const cfg = () =>
+						(field().timeConfig ?? {}) as {
+							mode?: "simple" | "time_block" | "appointment";
+							format?: "12h" | "24h";
+							stepMinutes?: number;
+						};
+					const mode = () => cfg().mode ?? "simple";
+					return (
+						<Switch>
+							<Match when={mode() === "simple"}>
+								{(() => {
+									const step = () => Math.max(cfg().stepMinutes ?? 30, 1);
+									const opts = createMemo(() => {
+										const out: string[] = [];
+										for (let h = 0; h < 24; h++) {
+											for (let m = 0; m < 60; m += step()) {
+												out.push(
+													`${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}`,
+												);
+											}
+										}
+										return out;
+									});
+									const label = (tt: string) => {
+										if (cfg().format === "24h") return tt;
+										const [hStr, mStr = "00"] = tt.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"
+											value={asString(props.value())}
+											onChange={(e) => props.set(e.currentTarget.value)}
+										>
+											<option value="" disabled>
+												{field().placeholder || "Select time"}
+											</option>
+											<For each={opts()}>
+												{(o) => <option value={o}>{label(o)}</option>}
+											</For>
+										</select>
+									);
+								})()}
+							</Match>
+							<Match when={mode() === "time_block"}>
+								{(() => {
+									const v = () =>
+										(props.value() &&
+										typeof props.value() === "object"
+											? (props.value() as { start?: string; end?: string })
+											: { start: "", end: "" });
+									return (
+										<div class="biab-time-block">
+											<label class="biab-subfield">
+												<span class="biab-subfield__label">Start</span>
+												<input
+													class="biab-input"
+													type="time"
+													value={v().start ?? ""}
+													onInput={(e) =>
+														props.set({ ...v(), start: e.currentTarget.value })
+													}
+												/>
+											</label>
+											<label class="biab-subfield">
+												<span class="biab-subfield__label">End</span>
+												<input
+													class="biab-input"
+													type="time"
+													value={v().end ?? ""}
+													onInput={(e) =>
+														props.set({ ...v(), end: e.currentTarget.value })
+													}
+												/>
+											</label>
+										</div>
+									);
+								})()}
+							</Match>
+							<Match when={mode() === "appointment"}>
+								{(() => {
+									const v = () =>
+										(props.value() &&
+										typeof props.value() === "object"
+											? (props.value() as { date?: string; time?: string })
+											: { date: "", time: "" });
+									return (
+										<div class="biab-appointment">
+											<label class="biab-subfield">
+												<span class="biab-subfield__label">Date</span>
+												<input
+													class="biab-input"
+													type="date"
+													value={v().date ?? ""}
+													onInput={(e) =>
+														props.set({ ...v(), date: e.currentTarget.value })
+													}
+												/>
+											</label>
+											<label class="biab-subfield">
+												<span class="biab-subfield__label">Time</span>
+												<input
+													class="biab-input"
+													type="time"
+													value={v().time ?? ""}
+													onInput={(e) =>
+														props.set({ ...v(), time: e.currentTarget.value })
+													}
+												/>
+											</label>
+										</div>
+									);
+								})()}
+							</Match>
+						</Switch>
+					);
+				})()}
+			</Match>
+
+			<Match when={t() === "date_range"}>
+				{(() => {
+					const v = () =>
+						(props.value() && typeof props.value() === "object"
+							? (props.value() as { start?: string; end?: string })
+							: { start: "", end: "" });
+					return (
+						<div class="biab-date-range">
+							<label class="biab-subfield">
+								<span class="biab-subfield__label">Start</span>
+								<input
+									class="biab-input"
+									type="date"
+									value={v().start ?? ""}
+									onInput={(e) =>
+										props.set({ ...v(), start: e.currentTarget.value })
+									}
+								/>
+							</label>
+							<label class="biab-subfield">
+								<span class="biab-subfield__label">End</span>
+								<input
+									class="biab-input"
+									type="date"
+									value={v().end ?? ""}
+									onInput={(e) =>
+										props.set({ ...v(), end: e.currentTarget.value })
+									}
+								/>
+							</label>
+						</div>
+					);
+				})()}
+			</Match>
+
+			<Match when={t() === "address"}>
+				{(() => {
+					const v = () =>
+						(props.value() && typeof props.value() === "object"
+							? (props.value() as Record<string, string>)
+							: {}) as Record<string, string>;
+					// Fixed per-subfield autofill tokens, suppressed to "off" when the
+					// field's resolved token is "off" (global switch or per-field override).
+					const acOff = () => ac() === "off";
+					const subAc = (token: string) => (acOff() ? "off" : token);
+					const part = (k: string, label: string, token: string) => (
+						<label class="biab-subfield">
+							<span class="biab-subfield__label">{label}</span>
+							<input
+								class="biab-input"
+								value={v()[k] ?? ""}
+								onInput={(e) =>
+									props.set({ ...v(), [k]: e.currentTarget.value })
+								}
+								autocomplete={subAc(token)}
+							/>
+						</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>
+					);
+				})()}
+			</Match>
+
+			<Match when={t() === "file_upload"}>
+				{(() => {
+					const files = () =>
+						Array.isArray(props.value())
+							? (props.value() as FormFileValue[])
+							: [];
+					const cfg = () =>
+						(field().fileConfig ?? {}) as {
+							allowedTypes?: string[];
+							maxFiles?: number;
+							maxSize?: number;
+						};
+					const maxFiles = () => cfg().maxFiles ?? 1;
+					const remaining = () => Math.max(maxFiles() - files().length, 0);
+					const accept = () =>
+						cfg().allowedTypes && cfg().allowedTypes.length > 0
+							? cfg().allowedTypes.join(",")
+							: undefined;
+					let inputRef: HTMLInputElement | undefined;
+					const [localError, setLocalError] = createSignal<string | null>(null);
+
+					const pick = async (list: FileList | null) => {
+						if (!list || list.length === 0) return;
+						if (!props.uploadFile) return;
+						setLocalError(null);
+						const allowed = cfg().allowedTypes;
+						const maxSizeMb = cfg().maxSize;
+						const chosen = Array.from(list).slice(0, remaining());
+						if (allowed && allowed.length > 0) {
+							const bad = chosen.find((f) => !allowed.includes(f.type));
+							if (bad) {
+								setLocalError(`File type not allowed: ${bad.type || bad.name}`);
+								return;
+							}
+						}
+						if (typeof maxSizeMb === "number" && maxSizeMb > 0) {
+							const tooBig = chosen.find(
+								(f) => f.size > maxSizeMb * 1024 * 1024,
+							);
+							if (tooBig) {
+								setLocalError(
+									`"${tooBig.name}" exceeds ${maxSizeMb} MB limit.`,
+								);
+								return;
+							}
+						}
+						try {
+							for (const f of chosen) {
+								// The controller appends each uploaded record to the field
+								// value, so we don't merge here — just trigger the upload.
+								await props.uploadFile(f, f.name);
+							}
+						} catch (err) {
+							setLocalError(
+								err instanceof Error ? err.message : "Upload failed.",
+							);
+						} finally {
+							if (inputRef) inputRef.value = "";
+						}
+					};
+
+					return (
+						<div class="biab-file">
+							<input
+								ref={inputRef}
+								type="file"
+								class="biab-file__input"
+								multiple={maxFiles() > 1}
+								accept={accept()}
+								style={{ display: "none" }}
+								onChange={(e) => void pick(e.currentTarget.files)}
+							/>
+							<button
+								type="button"
+								class="biab-file__trigger"
+								disabled={props.uploading() || remaining() === 0 || !props.uploadFile}
+								onClick={() => inputRef?.click()}
+							>
+								<Show
+									when={!props.uploading()}
+									fallback={<span>Uploading…</span>}
+								>
+									<Show
+										when={remaining() > 0}
+										fallback={
+											<span>
+												Maximum {maxFiles()} file{maxFiles() === 1 ? "" : "s"}{" "}
+												reached
+											</span>
+										}
+									>
+										<span>Click to upload</span>
+									</Show>
+								</Show>
+							</button>
+							<Show when={localError()}>
+								<p class="biab-file__error">{localError()}</p>
+							</Show>
+							<Show when={files().length > 0}>
+								<ul class="biab-file__list">
+									<For each={files()}>
+										{(f, i) => (
+											<li class="biab-file__item">
+												<span class="biab-file__name">{f.name}</span>
+												<span class="biab-file__size">
+													{Math.round(f.size / 1024)} KB
+												</span>
+												<button
+													type="button"
+													class="biab-file__remove"
+													aria-label="Remove file"
+													onClick={() =>
+														props.set(
+															files().filter((_, idx) => idx !== i()),
+														)
+													}
+												>
+													×
+												</button>
+											</li>
+										)}
+									</For>
+								</ul>
+							</Show>
+						</div>
+					);
+				})()}
+			</Match>
+		</Switch>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FieldRow — a value-bearing field plus its label / required marker / error /
+// help text. Mirrors FormPreview's `FieldRow` + its `data-biab-*` hooks.
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface RenderCtx {
+	snapshot: Accessor<FormSnapshot>;
+	setValue: (id: string, value: unknown) => void;
+	upload: (fieldId: string, file: File, filename?: string) => Promise<FormFileValue>;
+	/** Optional consumer render override, per field. */
+	fieldSlot?: (args: FieldSlotArgs) => JSX.Element;
+	/** Resolve the HTML autofill token for a field (or `undefined` to omit). */
+	autocomplete: (field: FormCoreField) => string | undefined;
+}
+
+export interface FieldSlotArgs {
+	field: FormCoreField;
+	value: unknown;
+	error: FieldError | undefined;
+	setValue: (value: unknown) => void;
+}
+
+function FieldRow(props: { field: FormCoreField; ctx: RenderCtx }): JSX.Element {
+	const field = () => props.field;
+	const value = () => props.ctx.snapshot().values[field().id];
+	const error = () => props.ctx.snapshot().errors[field().id];
+	const showLabel = () => !STATIC_NO_LABEL.has(field().type);
+
+	return (
+		<Show
+			when={!props.ctx.fieldSlot}
+			fallback={props.ctx.fieldSlot?.({
+				field: field(),
+				value: value(),
+				error: error(),
+				setValue: (v) => props.ctx.setValue(field().id, v),
+			})}
+		>
+			<div
+				data-field-id={field().id}
+				data-biab-field={fieldCssKey(field())}
+				data-biab-type={field().type}
+				class="biab-field"
+				classList={{
+					[`biab-field--${field().type}`]: true,
+					"biab-field--required": field().required === true,
+					"biab-field--error": Boolean(error()),
+				}}
+			>
+				<Show when={showLabel() && (field().label || field().required)}>
+					<label class="biab-field__label">
+						{field().label || ""}
+						<Show when={field().required}>
+							<span class="biab-field__required"> *</span>
+						</Show>
+					</label>
+				</Show>
+				<FieldInput
+					field={field()}
+					value={value}
+					set={(v) => props.ctx.setValue(field().id, v)}
+					uploadFile={(file, filename) =>
+						props.ctx.upload(field().id, file, filename)
+					}
+					uploading={() => props.ctx.snapshot().uploading}
+					autocomplete={props.ctx.autocomplete}
+				/>
+				<Show when={error()}>
+					{(e) => <p class="biab-field__error">{e().message}</p>}
+				</Show>
+				<Show when={field().helpText}>
+					<p class="biab-field__help">{field().helpText}</p>
+				</Show>
+			</div>
+		</Show>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RenderTree — the recursive layout walk: input_group (+ concurrent reveal),
+// condition_block, or_condition, flex_row, leaf fields. Mirrors FormPreview's
+// `RenderTree` and uses the SAME `biab-*` hooks. `flat` drops the group border
+// in consecutive mode (each step IS already a group).
+// ─────────────────────────────────────────────────────────────────────────────
+
+function RenderTree(props: {
+	fields: FormCoreField[];
+	ctx: RenderCtx;
+	flat?: boolean;
+}): JSX.Element {
+	return (
+		<div class="biab-tree">
+			<For each={props.fields}>
+				{(node) => (
+					<Switch fallback={<FieldRow field={node} ctx={props.ctx} />}>
+						<Match when={node.type === "input_group"}>
+							{(() => {
+								const children = () => node.children ?? [];
+								const concurrent = () => node.concurrentReveal === true;
+								const revealCount = () =>
+									concurrent()
+										? concurrentRevealCount(
+												children(),
+												props.ctx.snapshot().values,
+											)
+										: children().length;
+								return (
+									<div
+										data-biab-group={fieldCssKey(node)}
+										class="biab-group"
+										classList={{ "biab-group--bordered": !props.flat }}
+									>
+										<Show
+											when={node.label && node.showGroupLabel === true}
+										>
+											<div class="biab-group__label">{node.label}</div>
+										</Show>
+										<Show
+											when={concurrent()}
+											fallback={
+												<RenderTree fields={children()} ctx={props.ctx} />
+											}
+										>
+											<For each={children().slice(0, revealCount())}>
+												{(child) => (
+													<div class="biab-group__reveal">
+														<RenderTree
+															fields={[child]}
+															ctx={props.ctx}
+														/>
+													</div>
+												)}
+											</For>
+										</Show>
+									</div>
+								);
+							})()}
+						</Match>
+
+						<Match when={node.type === "condition_block"}>
+							<Show
+								when={evalCondition(
+									node.conditionRule,
+									props.ctx.snapshot().values,
+								)}
+							>
+								<RenderTree fields={node.children ?? []} ctx={props.ctx} />
+							</Show>
+						</Match>
+
+						<Match when={node.type === "or_condition"}>
+							{(() => {
+								const left = () => node.children?.[0];
+								const right = () => node.children?.[1];
+								const errored = () =>
+									Boolean(props.ctx.snapshot().errors[node.id]);
+								const cfg = () =>
+									(node.orConditionConfig ?? {}) as {
+										leftLabel?: string;
+										rightLabel?: string;
+									};
+								return (
+									<div
+										class="biab-or"
+										classList={{ "biab-or--error": errored() }}
+									>
+										<Show when={node.label}>
+											<div class="biab-or__label">
+												{node.label}
+												<span class="biab-or__hint">Fill at least one side</span>
+											</div>
+										</Show>
+										<div class="biab-or__grid">
+											<div class="biab-or__side">
+												<div class="biab-or__side-label">
+													{cfg().leftLabel || "Option A"}
+												</div>
+												<Show when={left()}>
+													{(l) => (
+														<RenderTree fields={[l()]} ctx={props.ctx} />
+													)}
+												</Show>
+											</div>
+											<div class="biab-or__divider">
+												<span class="biab-or__badge">OR</span>
+											</div>
+											<div class="biab-or__side">
+												<div class="biab-or__side-label">
+													{cfg().rightLabel || "Option B"}
+												</div>
+												<Show when={right()}>
+													{(r) => (
+														<RenderTree fields={[r()]} ctx={props.ctx} />
+													)}
+												</Show>
+											</div>
+										</div>
+										<Show when={errored()}>
+											<p class="biab-or__error">
+												Fill in at least one side to continue.
+											</p>
+										</Show>
+									</div>
+								);
+							})()}
+						</Match>
+
+						<Match when={node.type === "flex_row"}>
+							<div class="biab-flex-row">
+								<For each={node.children ?? []}>
+									{(child) => (
+										<div class="biab-flex-row__cell">
+											<FieldRow field={child} ctx={props.ctx} />
+										</div>
+									)}
+								</For>
+							</div>
+						</Match>
+					</Switch>
+				)}
+			</For>
+		</div>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Progress — labeled "steps" or thin "bar". Mirrors FormPreview's two indicators.
+// ─────────────────────────────────────────────────────────────────────────────
+
+function StepProgress(props: { snapshot: Accessor<FormSnapshot> }): JSX.Element {
+	const steps = () => props.snapshot().steps;
+	const current = () => props.snapshot().step;
+	return (
+		<div class="biab-progress biab-progress--steps">
+			<div class="biab-progress__title">Form Progress</div>
+			<div class="biab-progress__track">
+				<For each={steps()}>
+					{(s, i) => {
+						const head = () => s[0];
+						const title = () =>
+							head()?.stepTitle || head()?.label || `Step ${i() + 1}`;
+						const done = () => i() < current();
+						const isCurrent = () => i() === current();
+						return (
+							<>
+								<Show when={i() > 0}>
+									<div
+										class="biab-progress__line"
+										classList={{
+											"biab-progress__line--filled": i() <= current(),
+										}}
+									/>
+								</Show>
+								<div class="biab-progress__node">
+									<span
+										class="biab-progress__dot"
+										classList={{
+											"biab-progress__dot--current": isCurrent(),
+											"biab-progress__dot--done": done(),
+										}}
+									>
+										{done() ? "✓" : i() + 1}
+									</span>
+									<span
+										class="biab-progress__step-label"
+										classList={{
+											"biab-progress__step-label--current": isCurrent(),
+										}}
+									>
+										{title()}
+									</span>
+								</div>
+							</>
+						);
+					}}
+				</For>
+			</div>
+		</div>
+	);
+}
+
+function BarProgress(props: { snapshot: Accessor<FormSnapshot> }): JSX.Element {
+	return (
+		<div class="biab-progress biab-progress--bar">
+			<span class="biab-progress__count">
+				{props.snapshot().step + 1} / {props.snapshot().stepCount}
+			</span>
+			<div class="biab-progress__bar-track">
+				<div
+					class="biab-progress__bar-fill"
+					style={{ width: `${props.snapshot().progressPercent}%` }}
+				/>
+			</div>
+		</div>
+	);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// <BiabForm> — the drop-in component.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface BiabFormProps {
+	/** Form slug — required unless a pre-fetched `schema` is supplied. */
+	slug?: string;
+	/** Pre-fetched schema (SSR / RSC). Adopted synchronously by the controller. */
+	schema?: FormSchema;
+	/** SDK client. Optional when a `<BiabProvider>` supplies one, or when only
+	 *  rendering a pre-fetched `schema` without submitting. */
+	client?: BiabClient;
+	/** Submit-button text on the final step. */
+	submitLabel?: string;
+	/** Validate on the server but store nothing (no side effects). */
+	dryRun?: boolean;
+	/** Default submit options merged into every submit (call opts still win). */
+	submitOptions?: FormSubmitOptions;
+	/** Fired with the raw result on EVERY submit (success or failure). */
+	onSubmit?: (result: FormSubmitResult) => void;
+	/** Fired only on a successful submit. */
+	onSuccess?: (result: Extract<FormSubmitResult, { ok: true }>) => void;
+	/** Fired only on a failed submit. */
+	onError?: (result: Extract<FormSubmitResult, { ok: false }>) => void;
+	/** Per-field render override; return your own markup for any field. */
+	field?: (args: FieldSlotArgs) => JSX.Element;
+	/** Global HTML autofill switch. Defaults to inferring a token per field;
+	 *  `false` emits `autocomplete="off"` on every input. Override individual
+	 *  fields with `fieldAutoComplete`. */
+	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>;
+	/** Extra class on the form root (alias: `className`). */
+	class?: string;
+	className?: string;
+	style?: JSX.CSSProperties | string;
+}
+
+/**
+ * `<BiabForm slug="contact" client={client} />` — a complete, themeable form for
+ * a published BIAB form. Loads the schema, renders the field tree, validates
+ * locally (mirroring the server), handles multi-step nav + progress + concurrent
+ * reveal + file uploads, and submits through the SDK.
+ *
+ * All visual classes are `biab-*` on light DOM, so consumer CSS cascades. The
+ * component ships no styles of its own.
+ */
+export function BiabForm(props: BiabFormProps): JSX.Element {
+	const providerClient = useBiabClient();
+	const resolvedClient = () => props.client ?? providerClient;
+	const formId = createUniqueId();
+
+	const store = createFormStore({
+		...(resolvedClient() ? { client: resolvedClient() } : {}),
+		...(props.slug ? { slug: props.slug } : {}),
+		...(props.schema ? { schema: props.schema } : {}),
+		submitOptions: {
+			...props.submitOptions,
+			...(props.dryRun ? { dryRun: true } : {}),
+		},
+		onSuccess: (result) => {
+			props.onSuccess?.(result);
+			props.onSubmit?.(result);
+		},
+		onError: (result) => {
+			props.onError?.(result);
+			props.onSubmit?.(result);
+		},
+	});
+
+	const snap = store.snapshot;
+	const settings = () => snap().settings;
+	const isConsecutive = () => settings().isConsecutive;
+	const multiStep = () => isConsecutive() && snap().stepCount > 1;
+
+	// Global + per-field HTML autofill config, built from props and resolved per
+	// field at render time. See forms-core/autocomplete.ts.
+	const autocompleteConfig = createMemo<AutocompleteConfig>(() => ({
+		...(props.autoComplete !== undefined ? { enabled: props.autoComplete } : {}),
+		...(props.fieldAutoComplete ? { overrides: props.fieldAutoComplete } : {}),
+	}));
+
+	const ctx: RenderCtx = {
+		snapshot: snap,
+		setValue: (id, value) => store.controller.setValue(id, value),
+		upload: (fieldId, file, filename) =>
+			store.controller.uploadFile(fieldId, file, filename ? { filename } : undefined),
+		autocomplete: (field) =>
+			resolveFieldAutocomplete(field, autocompleteConfig()),
+		...(props.field ? { fieldSlot: props.field } : {}),
+	};
+
+	const handleSubmit = (e: Event) => {
+		e.preventDefault();
+		void store.controller.submit();
+	};
+
+	const rootClass = () =>
+		["biab-form", props.class, props.className].filter(Boolean).join(" ");
+
+	// Entrance-animation class for the active step (slide is directional).
+	const animClass = () => {
+		const a = settings().animation;
+		const forward = snap().forward;
+		switch (a) {
+			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-forward"
+					: "biab-anim biab-anim--slide-back";
+			case "scroll":
+				return "biab-anim biab-anim--scroll";
+			default:
+				return "";
+		}
+	};
+
+	return (
+		<Switch>
+			{/* Loading / error / empty guards mirror the controller's status. */}
+			<Match when={snap().status === "loading"}>
+				<div class="biab-form biab-form--loading" aria-busy="true">
+					Loading…
+				</div>
+			</Match>
+			<Match when={snap().status === "error"}>
+				<div class="biab-form biab-form--error" role="alert">
+					{snap().loadError ?? "Failed to load the form."}
+				</div>
+			</Match>
+			<Match when={snap().status === "ready"}>
+				<form
+					id={formId}
+					class={rootClass()}
+					style={props.style}
+					onSubmit={handleSubmit}
+					novalidate
+				>
+					{/* Org icon (showOrgIcon) — top-right corner mark. */}
+					<Show when={snap().orgIcon}>
+						{(icon) => (
+							<img class="biab-form__org-icon" src={icon()} alt="" />
+						)}
+					</Show>
+
+					{/* Title / description from the schema. */}
+					<Show when={snap().title || snap().description}>
+						<div class="biab-form__header">
+							<Show when={snap().title}>
+								<h2 class="biab-form__title">{snap().title}</h2>
+							</Show>
+							<Show when={snap().description}>
+								<p class="biab-form__description">{snap().description}</p>
+							</Show>
+						</div>
+					</Show>
+
+					{/* Multi-step progress indicator. */}
+					<Show when={multiStep() && settings().showProgress}>
+						<Show
+							when={settings().progressStyle === "bar"}
+							fallback={<StepProgress snapshot={snap} />}
+						>
+							<BarProgress snapshot={snap} />
+						</Show>
+					</Show>
+
+					{/* Form-level error summary. */}
+					<Show when={snap().errorList.length > 0}>
+						<div 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>
+					</Show>
+
+					{/* The field tree for the active step (single-page = all fields).
+					    Keyed on step index so the entrance animation re-runs per step. */}
+					<Show
+						when={settings().animation === "scroll"}
+						fallback={
+							<div class={animClass()} data-step={snap().step}>
+								<RenderTree
+									fields={snap().visibleFields}
+									ctx={ctx}
+									flat={isConsecutive()}
+								/>
+							</div>
+						}
+					>
+						<div class="biab-form__scroll">
+							<For each={snap().visibleFields}>
+								{(vf) => (
+									<div class="biab-anim biab-anim--scroll">
+										<RenderTree
+											fields={[vf]}
+											ctx={ctx}
+											flat={isConsecutive()}
+										/>
+									</div>
+								)}
+							</For>
+						</div>
+					</Show>
+
+					{/* Navigation / submit. */}
+					<Show
+						when={multiStep()}
+						fallback={
+							<div class="biab-nav">
+								<button
+									type="submit"
+									class="biab-btn biab-btn--submit"
+									disabled={snap().submitting}
+								>
+									{snap().submitting
+										? "Submitting…"
+										: (props.submitLabel ?? "Submit")}
+								</button>
+							</div>
+						}
+					>
+						<div class="biab-nav biab-nav--steps">
+							<button
+								type="button"
+								class="biab-btn biab-btn--back"
+								disabled={snap().isFirstStep}
+								onClick={() => store.controller.back()}
+							>
+								Back
+							</button>
+							<Show
+								when={snap().isLastStep}
+								fallback={
+									<button
+										type="button"
+										class="biab-btn biab-btn--next"
+										disabled={!snap().canAdvance}
+										onClick={() => store.controller.next()}
+									>
+										Next
+									</button>
+								}
+							>
+								<button
+									type="submit"
+									class="biab-btn biab-btn--submit"
+									disabled={snap().submitting}
+								>
+									{snap().submitting
+										? "Submitting…"
+										: (props.submitLabel ?? "Submit")}
+								</button>
+							</Show>
+						</div>
+					</Show>
+
+					{/* Success state. */}
+					<Show when={snap().submitted}>
+						<div class="biab-form__success" role="status">
+							Thanks — your response was received.
+						</div>
+					</Show>
+				</form>
+			</Match>
+		</Switch>
+	);
+}
+
+// Re-export the core types a consumer commonly annotates against, so they can
+// import everything they need from `@businessdash/sdk/solid` alone.
+export type {
+	BiabClient,
+	FormSchema,
+	FormSubmitResult,
+	FormFileValue,
+} from "./sdk.js";
+export type {
+	FieldError,
+	FormController,
+	FormCoreField,
+	FormSnapshot,
+	FormSubmitOptions,
+} from "./forms-core/index.js";
+export { createFormController } from "./forms-core/index.js";