@businessdash/sdk 0.9.60

package/src/angular/biab-form.component.ts

@@ -0,0 +1,1443 @@
+/**
+ * `@businessdash/sdk/angular` — `<biab-form>` drop-in Angular component.
+ *
+ * Ship mode: SOURCE. This file is a single standalone Angular component shipped
+ * as plain `.ts` (no ng-packagr / APF) and compiled by the CONSUMER's Angular
+ * toolchain. It targets Angular v17+ idioms — standalone-by-default, `input()` /
+ * `output()` signals, `inject()`, native control flow (`@if` / `@for` /
+ * `@switch`), and host bindings in the decorator `host` object — so it slots
+ * into a modern Angular app with zero NgModule wiring.
+ *
+ * It is a thin, idiomatic skin over the framework-agnostic
+ * `createFormController` headless core (`@businessdash/sdk/forms`). All form runtime
+ * state and behaviour — values, condition-aware visibility, validation,
+ * multi-step nav + progress, concurrent reveal, submission + file uploads — live
+ * in the core. This component:
+ *
+ *   1. Creates a controller from `slug` + an injected/`@Input` `BiabClient` (or
+ *      a pre-fetched `schema` for SSR).
+ *   2. Mirrors the controller's `snapshot()` into a single Angular `signal`,
+ *      re-publishing on every `subscribe` notify (so OnPush change detection
+ *      fires precisely when the form state changes).
+ *   3. Renders the FULL nested field tree from `snapshot.visibleFields` using
+ *      the `biab-*` light-DOM class convention (no shadow root), so the org's
+ *      own CSS cascades exactly as it does on the dashboard renderer.
+ *   4. Applies `schema.settings` — animation, multi-step + progress
+ *      (bar/steps), concurrent reveal, and the org icon — so the drop-in
+ *      reproduces the dashboard preview 1:1.
+ *
+ * Rendering is a faithful port of the dashboard's `FormPreview.tsx` field-by-
+ * field renderer, mapped onto Angular template control flow. Because the tree is
+ * recursive (`input_group` / `condition_block` / `or_condition` / `flex_row`
+ * with children), the component renders itself recursively via the private
+ * `<biab-form-node>` sub-component below — the public surface stays a single
+ * `<biab-form>` tag.
+ */
+
+import {
+	ChangeDetectionStrategy,
+	Component,
+	DestroyRef,
+	InjectionToken,
+	Input,
+	type OnInit,
+	computed,
+	inject,
+	input,
+	output,
+	signal,
+} from "@angular/core";
+
+import {
+	type BiabClient,
+	type FieldError,
+	type FormController,
+	type FormCoreField,
+	type FormSchema,
+	type FormSnapshot,
+	type FormSubmitOptions,
+	type FormSubmitResult,
+	concurrentRevealCount,
+	createFormController,
+	evalCondition,
+	fetchIconNames,
+	filterIconNames,
+	iconUrl,
+	shouldSearchOptions,
+} from "@businessdash/sdk/forms";
+
+import {
+	type AutocompleteConfig,
+	resolveFieldAutocomplete,
+} from "../forms-core/autocomplete.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// DI — provide a shared BiabClient app-wide so consumers don't repeat it on
+// every `<biab-form>`. Mirrors the React `<DashboardProvider>` ergonomics but
+// uses Angular's idiomatic InjectionToken + provider helper.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Optional DI token carrying the shared {@link BiabClient}. Provide it once at
+ * the app root (e.g. via {@link provideBiabClient}) and every `<biab-form>`
+ * picks it up automatically — no `[client]` binding required. A `[client]`
+ * input still wins per-instance when both are present.
+ */
+export const BIAB_CLIENT = new InjectionToken<BiabClient>("BIAB_CLIENT");
+
+/**
+ * Provider helper for the application config. Drop into `bootstrapApplication`'s
+ * `providers` (or a route's `providers`) so `<biab-form slug="…">` works with no
+ * per-instance `[client]`:
+ *
+ * ```ts
+ * bootstrapApplication(App, {
+ *   providers: [provideBiabClient(myBiabClient)],
+ * });
+ * ```
+ */
+export function provideBiabClient(client: BiabClient) {
+	return { provide: BIAB_CLIENT, useValue: client };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Recursive field-tree renderer — one node + its subtree. Private to the module;
+// the public API is only `<biab-form>`. Faithful port of FormPreview's
+// `RenderTree` + `FieldRow` + `FieldInput`, using the same `biab-*` classes and
+// `data-biab-*` hooks so org CSS targets the same selectors as the dashboard.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Stable CSS hook for a field (the `data-biab-field` value): explicit key →
+ *  camelCase label slug → id. Mirrors FormPreview's `fieldCssKey`. */
+function fieldCssKey(field: FormCoreField): string {
+	const explicit =
+		(typeof field.key === "string" && field.key.trim()) ||
+		(typeof field.outputKey === "string" && field.outputKey.trim()) ||
+		"";
+	if (explicit) return explicit;
+	const lbl = (field.label ?? "").trim();
+	if (lbl) {
+		const slug = lbl
+			.replace(/[^a-zA-Z0-9]+/g, " ")
+			.trim()
+			.split(/\s+/)
+			.filter(Boolean)
+			.map((w, i) =>
+				i === 0
+					? w.toLowerCase()
+					: w.charAt(0).toUpperCase() + w.slice(1).toLowerCase(),
+			)
+			.join("");
+		if (slug) return /^[0-9]/.test(slug) ? `_${slug}` : slug;
+	}
+	return field.id;
+}
+
+const NO_LABEL_TYPES = new Set(["title", "subtitle", "separator", "richtext"]);
+
+@Component({
+	selector: "biab-form-node",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	template: `
+		@switch (field.type) {
+			@case ("input_group") {
+				<div class="biab-group" [attr.data-biab-group]="cssKey()">
+					@if (field.label && field.showGroupLabel) {
+						<div class="biab-group__label">{{ field.label }}</div>
+					}
+					@for (child of revealedChildren(); track child.id) {
+						<biab-form-node
+							[field]="child"
+							[values]="values"
+							[errors]="errors"
+							[autocompleteConfig]="autocompleteConfig"
+							(valueChange)="valueChange.emit($event)"
+							(fileSelected)="fileSelected.emit($event)"
+							(imageSelected)="imageSelected.emit($event)"
+						/>
+					}
+				</div>
+			}
+			@case ("condition_block") {
+				@if (conditionPasses()) {
+					@for (child of children(); track child.id) {
+						<biab-form-node
+							[field]="child"
+							[values]="values"
+							[errors]="errors"
+							[autocompleteConfig]="autocompleteConfig"
+							(valueChange)="valueChange.emit($event)"
+							(fileSelected)="fileSelected.emit($event)"
+							(imageSelected)="imageSelected.emit($event)"
+						/>
+					}
+				}
+			}
+			@case ("or_condition") {
+				<div
+					class="biab-or"
+					[class.biab-or--error]="isErrored()"
+					[attr.data-biab-or]="cssKey()"
+				>
+					@if (field.label) {
+						<div class="biab-or__label">
+							{{ field.label }}
+							<span class="biab-or__hint">Fill at least one side</span>
+						</div>
+					}
+					<div class="biab-or__grid">
+						<div class="biab-or__side">
+							<div class="biab-or__side-label">
+								{{ orLeftLabel() }}
+							</div>
+							@if (children()[0]; as left) {
+								<biab-form-node
+									[field]="left"
+									[values]="values"
+									[errors]="errors"
+									[autocompleteConfig]="autocompleteConfig"
+									(valueChange)="valueChange.emit($event)"
+									(fileSelected)="fileSelected.emit($event)"
+							(imageSelected)="imageSelected.emit($event)"
+								/>
+							}
+						</div>
+						<div class="biab-or__divider"><span>OR</span></div>
+						<div class="biab-or__side">
+							<div class="biab-or__side-label">
+								{{ orRightLabel() }}
+							</div>
+							@if (children()[1]; as right) {
+								<biab-form-node
+									[field]="right"
+									[values]="values"
+									[errors]="errors"
+									[autocompleteConfig]="autocompleteConfig"
+									(valueChange)="valueChange.emit($event)"
+									(fileSelected)="fileSelected.emit($event)"
+							(imageSelected)="imageSelected.emit($event)"
+								/>
+							}
+						</div>
+					</div>
+					@if (isErrored()) {
+						<p class="biab-field__error">Fill in at least one side to continue.</p>
+					}
+				</div>
+			}
+			@case ("flex_row") {
+				<div class="biab-flex-row">
+					@for (child of children(); track child.id) {
+						<div class="biab-flex-row__cell">
+							<biab-form-node
+								[field]="child"
+								[values]="values"
+								[errors]="errors"
+								[autocompleteConfig]="autocompleteConfig"
+								(valueChange)="valueChange.emit($event)"
+								(fileSelected)="fileSelected.emit($event)"
+							(imageSelected)="imageSelected.emit($event)"
+							/>
+						</div>
+					}
+				</div>
+			}
+			@default {
+				<!-- Leaf field row -->
+				<div
+					class="biab-field"
+					[class]="rowClass()"
+					[attr.data-field-id]="field.id"
+					[attr.data-biab-field]="cssKey()"
+					[attr.data-biab-type]="field.type"
+				>
+					@if (showLabel()) {
+						<label class="biab-field__label" [for]="field.id">
+							{{ field.label || "" }}
+							@if (field.required) {
+								<span class="biab-field__required">*</span>
+							}
+						</label>
+					}
+
+					@switch (field.type) {
+						@case ("title") {
+							<h2 class="biab-field__title">{{ field.label || "Untitled" }}</h2>
+						}
+						@case ("subtitle") {
+							<h3 class="biab-field__subtitle">{{ field.label || "" }}</h3>
+						}
+						@case ("separator") {
+							<hr class="biab-field__separator" />
+						}
+						@case ("richtext") {
+							<!-- content is org-authored HTML; the host page is trusted same-origin.
+							     Sanitize upstream if you accept untrusted form authors. -->
+							<div class="biab-field__richtext" [innerHTML]="field.content || ''"></div>
+						}
+						@case ("image") {
+							@if (imageSrc()) {
+								<img class="biab-field__image" [src]="imageSrc()" alt="" />
+							}
+						}
+						@case ("textarea") {
+							<textarea
+								class="biab-input biab-input--textarea"
+								[id]="field.id"
+								[value]="stringValue()"
+								[placeholder]="field.placeholder || ''"
+								[rows]="3"
+								[attr.autocomplete]="autoComplete()"
+								(input)="onInput($event)"
+							></textarea>
+						}
+						@case ("select") {
+							@if (searchableOptions()) {
+								<!-- ComboBox card, or a list long enough that scrolling it is
+								     the worse default. A list attribute plus a datalist gives
+								     native typeahead: no JS, no styling opinion. -->
+								<input
+									class="biab-input biab-combobox"
+									type="text"
+									[id]="field.id"
+									[attr.list]="'biab-list-' + field.id"
+									[placeholder]="field.placeholder || 'Search…'"
+									[value]="stringValue()"
+									(input)="onInput($event)"
+								/>
+								<datalist [id]="'biab-list-' + field.id">
+									@for (opt of field.options || []; track opt) {
+										<option [value]="opt"></option>
+									}
+								</datalist>
+							} @else {
+								<select
+									class="biab-input biab-input--select"
+									[id]="field.id"
+									[value]="stringValue()"
+									(change)="onInput($event)"
+								>
+									<option value="">{{ field.placeholder || "Select…" }}</option>
+									@for (opt of field.options || []; track opt) {
+										<option [value]="opt">{{ opt }}</option>
+									}
+								</select>
+							}
+						}
+						@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. -->
+							<div class="biab-iconselect">
+								<input
+									class="biab-input biab-iconselect__search"
+									type="text"
+									[placeholder]="field.placeholder || 'Search icons…'"
+									[value]="iconQuery()"
+									(input)="onIconQuery($event)"
+								/>
+								@if (stringValue()) {
+									<span class="biab-iconselect__current">
+										<img
+											[src]="iconSrc(stringValue())"
+											[alt]="stringValue()"
+											width="16"
+											height="16"
+										/>
+										<button
+											type="button"
+											class="biab-iconselect__clear"
+											(click)="setIconValue('')"
+										>
+											×
+										</button>
+									</span>
+								}
+								<div class="biab-iconselect__grid">
+									@for (name of visibleIcons(); track name) {
+										<button
+											type="button"
+											class="biab-iconselect__item"
+											[class.is-selected]="stringValue() === name"
+											[title]="name"
+											[attr.aria-label]="name"
+											[attr.aria-pressed]="stringValue() === name"
+											(click)="setIconValue(name)"
+										>
+											<img [src]="iconSrc(name)" alt="" width="16" height="16" />
+										</button>
+									}
+								</div>
+							</div>
+						}
+						@case ("image_input") {
+							<!-- One image, either source; the value is a plain URL string. -->
+							<div class="biab-imageinput">
+								@if (imageSources() === "both") {
+									<div class="biab-imageinput__modes">
+										<button
+											type="button"
+											class="biab-imageinput__mode"
+											[class.is-active]="imageMode() === 'upload'"
+											[attr.aria-pressed]="imageMode() === 'upload'"
+											(click)="setImageMode('upload')"
+										>
+											Upload
+										</button>
+										<button
+											type="button"
+											class="biab-imageinput__mode"
+											[class.is-active]="imageMode() === 'url'"
+											[attr.aria-pressed]="imageMode() === 'url'"
+											(click)="setImageMode('url')"
+										>
+											Paste URL
+										</button>
+									</div>
+								}
+								@if (imageMode() === "upload" && imageSources() !== "url") {
+									<input
+										class="biab-input biab-imageinput__file"
+										type="file"
+										[attr.accept]="imageAccept()"
+										(change)="onImagePick($event)"
+									/>
+								} @else {
+									<input
+										class="biab-input biab-imageinput__url"
+										type="url"
+										[placeholder]="
+											field.placeholder || 'https://example.com/image.png'
+										"
+										[value]="stringValue()"
+										(input)="onInput($event)"
+									/>
+								}
+								@if (showImagePreview() && stringValue()) {
+									<img
+										class="biab-imageinput__preview"
+										[src]="stringValue()"
+										alt=""
+									/>
+								}
+							</div>
+						}
+						@case ("radio") {
+							<div class="biab-input biab-input--radio">
+								@for (opt of field.options || []; track opt) {
+									<label class="biab-radio__item">
+										<input
+											type="radio"
+											[name]="field.id"
+											[value]="opt"
+											[checked]="stringValue() === opt"
+											(change)="setValue(opt)"
+										/>
+										<span>{{ opt }}</span>
+									</label>
+								}
+							</div>
+						}
+						@case ("checkbox") {
+							<div class="biab-input biab-input--checkbox">
+								@for (opt of field.options || []; track opt) {
+									<label class="biab-checkbox__item">
+										<input
+											type="checkbox"
+											[value]="opt"
+											[checked]="checkboxChecked(opt)"
+											(change)="toggleCheckbox(opt, $event)"
+										/>
+										<span>{{ opt }}</span>
+									</label>
+								}
+							</div>
+						}
+						@case ("boolean") {
+							<label class="biab-input biab-input--boolean">
+								<input
+									type="checkbox"
+									[checked]="booleanValue()"
+									(change)="onBoolean($event)"
+								/>
+								<span>{{ field.placeholder || "Yes / No" }}</span>
+							</label>
+						}
+						@case ("date") {
+							<input
+								class="biab-input biab-input--date"
+								type="date"
+								[id]="field.id"
+								[value]="stringValue()"
+								(input)="onInput($event)"
+							/>
+						}
+						@case ("email") {
+							<input
+								class="biab-input biab-input--email"
+								type="email"
+								[id]="field.id"
+								[value]="stringValue()"
+								[placeholder]="field.placeholder || 'you@example.com'"
+								[attr.autocomplete]="autoComplete()"
+								(input)="onInput($event)"
+							/>
+						}
+						@case ("phone") {
+							<input
+								class="biab-input biab-input--phone"
+								type="tel"
+								[id]="field.id"
+								[value]="stringValue()"
+								[placeholder]="phonePlaceholder()"
+								[attr.autocomplete]="autoComplete()"
+								(input)="onInput($event)"
+							/>
+						}
+						@case ("number") {
+							<input
+								class="biab-input biab-input--number"
+								type="number"
+								[id]="field.id"
+								[value]="numberInputValue()"
+								[placeholder]="field.placeholder || ''"
+								(input)="onNumber($event)"
+							/>
+						}
+						@case ("stepper") {
+							<div class="biab-input biab-input--stepper">
+								<button type="button" class="biab-btn biab-stepper__dec" (click)="bumpStepper(-1)">
+									−
+								</button>
+								<span class="biab-stepper__value">{{ numberValue() }}</span>
+								<button type="button" class="biab-btn biab-stepper__inc" (click)="bumpStepper(1)">
+									+
+								</button>
+							</div>
+						}
+						@case ("slider") {
+							<div class="biab-input biab-input--slider">
+								<div class="biab-slider__readout">
+									<span>{{ sliderFmt(sliderMin()) }}</span>
+									<span class="biab-slider__current">{{ sliderFmt(numberValue()) }}</span>
+									<span>{{ sliderFmt(sliderMax()) }}</span>
+								</div>
+								<input
+									type="range"
+									[min]="sliderMin()"
+									[max]="sliderMax()"
+									[step]="sliderStep()"
+									[value]="numberValue()"
+									(input)="onNumber($event)"
+								/>
+							</div>
+						}
+						@case ("star_rating") {
+							<div class="biab-input biab-input--stars">
+								@for (i of starIndexes(); track i) {
+									<button
+										type="button"
+										class="biab-star"
+										[class.biab-star--on]="i < numberValue()"
+										(click)="setValue(i + 1)"
+										[attr.aria-label]="i + 1 + ' stars'"
+									>
+										★
+									</button>
+								}
+							</div>
+						}
+						@case ("happiness_rating") {
+							<div class="biab-input biab-input--happiness">
+								@for (face of happinessFaces(); track $index) {
+									<button
+										type="button"
+										class="biab-happiness__face"
+										[class.biab-happiness__face--on]="$index === numberValue()"
+										(click)="setValue($index)"
+									>
+										{{ face }}
+									</button>
+								}
+							</div>
+						}
+						@case ("color_picker") {
+							<div class="biab-input biab-input--colors">
+								@for (color of field.options || []; track color) {
+									<button
+										type="button"
+										class="biab-color"
+										[class.biab-color--on]="stringValue() === color"
+										[style.backgroundColor]="color"
+										[title]="color"
+										(click)="setValue(color)"
+									></button>
+								}
+							</div>
+						}
+						@case ("date_range") {
+							<div class="biab-input biab-input--date-range">
+								<label class="biab-subfield">
+									<span>Start</span>
+									<input type="date" [value]="rangeStart()" (input)="onRange('start', $event)" />
+								</label>
+								<label class="biab-subfield">
+									<span>End</span>
+									<input type="date" [value]="rangeEnd()" (input)="onRange('end', $event)" />
+								</label>
+							</div>
+						}
+						@case ("time_picker") {
+							@switch (timeMode()) {
+								@case ("time_block") {
+									<div class="biab-input biab-input--time-block">
+										<label class="biab-subfield">
+											<span>Start</span>
+											<input type="time" [value]="rangeStart()" (input)="onRange('start', $event)" />
+										</label>
+										<label class="biab-subfield">
+											<span>End</span>
+											<input type="time" [value]="rangeEnd()" (input)="onRange('end', $event)" />
+										</label>
+									</div>
+								}
+								@case ("appointment") {
+									<div class="biab-input biab-input--appointment">
+										<label class="biab-subfield">
+											<span>Date</span>
+											<input type="date" [value]="apptDate()" (input)="onAppt('date', $event)" />
+										</label>
+										<label class="biab-subfield">
+											<span>Time</span>
+											<input type="time" [value]="apptTime()" (input)="onAppt('time', $event)" />
+										</label>
+									</div>
+								}
+								@default {
+									<input
+										class="biab-input biab-input--time"
+										type="time"
+										[value]="stringValue()"
+										(input)="onInput($event)"
+									/>
+								}
+							}
+						}
+						@case ("address") {
+							<div class="biab-input biab-input--address">
+								<label class="biab-subfield biab-subfield--full">
+									<span>Address Line 1</span>
+									<input
+										[value]="addrField('line1')"
+										[attr.autocomplete]="addrAutoComplete('street-address')"
+										(input)="onAddr('line1', $event)"
+									/>
+								</label>
+								<label class="biab-subfield biab-subfield--full">
+									<span>Address Line 2</span>
+									<input
+										[value]="addrField('line2')"
+										[attr.autocomplete]="addrAutoComplete('address-line2')"
+										(input)="onAddr('line2', $event)"
+									/>
+								</label>
+								<label class="biab-subfield">
+									<span>City</span>
+									<input
+										[value]="addrField('city')"
+										[attr.autocomplete]="addrAutoComplete('address-level2')"
+										(input)="onAddr('city', $event)"
+									/>
+								</label>
+								<label class="biab-subfield">
+									<span>State</span>
+									<input
+										[value]="addrField('state')"
+										[attr.autocomplete]="addrAutoComplete('address-level1')"
+										(input)="onAddr('state', $event)"
+									/>
+								</label>
+								<label class="biab-subfield biab-subfield--full">
+									<span>Zip</span>
+									<input
+										[value]="addrField('zip')"
+										[attr.autocomplete]="addrAutoComplete('postal-code')"
+										(input)="onAddr('zip', $event)"
+									/>
+								</label>
+							</div>
+						}
+						@case ("file_upload") {
+							<div class="biab-input biab-input--file">
+								<input
+									type="file"
+									[multiple]="fileMultiple()"
+									[accept]="fileAccept()"
+									(change)="onFile($event)"
+								/>
+								@if (fileList().length) {
+									<ul class="biab-file__list">
+										@for (f of fileList(); track f.storageId) {
+											<li class="biab-file__item">{{ f.name }}</li>
+										}
+									</ul>
+								}
+							</div>
+						}
+						@default {
+							<!-- text and any plain-text input -->
+							<input
+								class="biab-input biab-input--text"
+								type="text"
+								[id]="field.id"
+								[value]="stringValue()"
+								[placeholder]="field.placeholder || ''"
+								[attr.autocomplete]="autoComplete()"
+								(input)="onInput($event)"
+							/>
+						}
+					}
+
+					@if (isErrored()) {
+						<p class="biab-field__error">{{ errorMessage() }}</p>
+					}
+					@if (field.helpText) {
+						<p class="biab-field__help">{{ field.helpText }}</p>
+					}
+				</div>
+			}
+		}
+	`,
+})
+export class BiabFormNodeComponent {
+	/** The field (subtree root) to render. */
+	@Input({ required: true }) field!: FormCoreField;
+	/** Working values, keyed by field id (the snapshot's `values`). */
+	@Input({ required: true }) values!: Record<string, unknown>;
+	/** Field-level errors, keyed by field id (the snapshot's `errors`). */
+	@Input({ required: true }) errors!: Record<string, FieldError>;
+	/** Autofill config threaded from `<biab-form>` (global switch + per-field
+	 *  overrides). Drives the `autocomplete` attribute on value-bearing inputs. */
+	@Input() autocompleteConfig: AutocompleteConfig = {};
+
+	/** Emits `{ id, value }` when a leaf field changes. */
+	readonly valueChange = output<{ id: string; value: unknown }>();
+	/** Emits when a file is chosen for a `file_upload` field. */
+	readonly fileSelected = output<{ fieldId: string; file: File }>();
+	/**
+	 * Emits when an image is chosen for an `image_input` field. Separate from
+	 * `fileSelected` because the host handles it differently: a file upload is
+	 * appended to the field's array, whereas an image resolves to a single URL
+	 * STRING that replaces the value.
+	 */
+	readonly imageSelected = output<{ fieldId: string; file: File }>();
+
+	// ── Derived view helpers (kept as plain getters; the parent re-binds inputs
+	//    on every snapshot, which triggers OnPush CD with fresh references). ──
+
+	cssKey(): string {
+		return fieldCssKey(this.field);
+	}
+
+	/** Resolved HTML autofill token for this field, or `null` to omit the
+	 *  attribute (Angular's `[attr.autocomplete]` drops it on `null`). Honors the
+	 *  global switch, per-field overrides, and schema token; see
+	 *  forms-core/autocomplete.ts. */
+	autoComplete(): string | null {
+		return resolveFieldAutocomplete(this.field, this.autocompleteConfig) ?? null;
+	}
+
+	/** Whether autofill is forced off for this field — used to suppress the
+	 *  fixed address sub-field tokens to "off". */
+	autoCompleteOff(): boolean {
+		return this.autoComplete() === "off";
+	}
+
+	/** Fixed token for an address composite sub-field, suppressed to "off" when
+	 *  the field's resolved token is "off". */
+	addrAutoComplete(token: string): string {
+		return this.autoCompleteOff() ? "off" : token;
+	}
+
+	children(): FormCoreField[] {
+		return (this.field.children ?? []) as FormCoreField[];
+	}
+
+	/** input_group concurrent-reveal gating (mirrors FormPreview). */
+	revealedChildren(): FormCoreField[] {
+		const kids = this.children();
+		if (this.field.concurrentReveal !== true) return kids;
+		const count = concurrentRevealCount(kids, this.values);
+		return kids.slice(0, count);
+	}
+
+	conditionPasses(): boolean {
+		return evalCondition(this.field.conditionRule, this.values);
+	}
+
+	orLeftLabel(): string {
+		return this.field.orConditionConfig?.leftLabel || "Option A";
+	}
+	orRightLabel(): string {
+		return this.field.orConditionConfig?.rightLabel || "Option B";
+	}
+
+	showLabel(): boolean {
+		return !NO_LABEL_TYPES.has(this.field.type);
+	}
+
+	rowClass(): string {
+		const parts = [`biab-field--${this.field.type}`];
+		if (this.field.required) parts.push("biab-field--required");
+		if (this.isErrored()) parts.push("biab-field--error");
+		return parts.join(" ");
+	}
+
+	isErrored(): boolean {
+		return Boolean(this.errors[this.field.id]);
+	}
+	errorMessage(): string {
+		return this.errors[this.field.id]?.message ?? "This field is required.";
+	}
+
+	// ── Value coercion helpers ──
+	private raw(): unknown {
+		return this.values[this.field.id];
+	}
+	stringValue(): string {
+		const v = this.raw();
+		return typeof v === "string" ? v : "";
+	}
+	numberValue(): number {
+		const v = this.raw();
+		return typeof v === "number" ? v : 0;
+	}
+	numberInputValue(): string {
+		const v = this.raw();
+		if (typeof v === "number") return String(v);
+		return typeof v === "string" ? v : "";
+	}
+	booleanValue(): boolean {
+		return this.raw() === true;
+	}
+
+	setValue(value: unknown): void {
+		this.valueChange.emit({ id: this.field.id, value });
+	}
+
+	onInput(event: Event): void {
+		const target = event.target as HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+		this.setValue(target.value);
+	}
+	onNumber(event: Event): void {
+		const target = event.target as HTMLInputElement;
+		this.setValue(target.value === "" ? "" : Number(target.value));
+	}
+	onBoolean(event: Event): void {
+		this.setValue((event.target as HTMLInputElement).checked);
+	}
+
+	// ── select / combobox ──
+
+	/** Does this dropdown offer search? The ComboBox card forces it on; any list
+	 *  long enough gets it anyway. */
+	searchableOptions(): boolean {
+		return shouldSearchOptions(
+			(this.field.options ?? []).length,
+			(this.field as { display?: string }).display,
+		);
+	}
+
+	// ── icon_select ──
+	// The value is an icon NAME. Art resolves against the platform's icon route
+	// rather than bundling an icon set, and the name index is fetched lazily —
+	// ~1,600 entries that change only when Lucide does. A curated
+	// `iconConfig.allowedIcons` skips the fetch entirely.
+
+	readonly iconQuery = signal("");
+	private readonly iconIndex = signal<string[]>([]);
+	private iconIndexRequested = false;
+
+	onIconQuery(event: Event): void {
+		this.iconQuery.set((event.target as HTMLInputElement).value);
+	}
+
+	/** Distinct from `setValue` only so the template reads clearly at the call
+	 *  site; icons are set by click, not by an input event. */
+	setIconValue(name: string): void {
+		this.setValue(name);
+	}
+
+	iconSrc(name: string): string {
+		return iconUrl(name);
+	}
+
+	visibleIcons(): string[] {
+		const curated =
+			(this.field as { iconConfig?: { allowedIcons?: string[] } }).iconConfig
+				?.allowedIcons ?? [];
+		if (curated.length > 0) {
+			return filterIconNames(curated, this.iconQuery());
+		}
+		if (!this.iconIndexRequested) {
+			this.iconIndexRequested = true;
+			// Resolves to [] on failure — an empty grid is recoverable.
+			void fetchIconNames().then((names) => this.iconIndex.set(names));
+		}
+		return filterIconNames(this.iconIndex(), this.iconQuery());
+	}
+
+	// ── image_input ──
+	// One image, from an upload OR a pasted URL; the submitted value is a plain
+	// URL string either way.
+
+	private readonly imageModeSignal = signal<"upload" | "url">("upload");
+
+	private imageCfg(): {
+		allowedTypes?: string[];
+		maxSize?: number;
+		showPreview?: boolean;
+		sources?: "both" | "upload" | "url";
+	} {
+		return (
+			(
+				this.field as {
+					imageInputConfig?: {
+						allowedTypes?: string[];
+						maxSize?: number;
+						showPreview?: boolean;
+						sources?: "both" | "upload" | "url";
+					};
+				}
+			).imageInputConfig ?? {}
+		);
+	}
+
+	imageSources(): "both" | "upload" | "url" {
+		return this.imageCfg().sources ?? "both";
+	}
+	imageMode(): "upload" | "url" {
+		// An upload-only or url-only field has no toggle, so honour the config
+		// rather than the local mode signal.
+		const sources = this.imageSources();
+		if (sources !== "both") return sources;
+		return this.imageModeSignal();
+	}
+	setImageMode(mode: "upload" | "url"): void {
+		this.imageModeSignal.set(mode);
+	}
+	imageAccept(): string {
+		return (this.imageCfg().allowedTypes ?? ["image/*"]).join(",");
+	}
+	showImagePreview(): boolean {
+		return this.imageCfg().showPreview !== false;
+	}
+
+	/** Emits the picked file; the host uploads it and writes back the URL. */
+	onImagePick(event: Event): void {
+		const file = (event.target as HTMLInputElement).files?.[0];
+		if (!file) return;
+		const maxMb = this.imageCfg().maxSize ?? 5;
+		if (file.size > maxMb * 1024 * 1024) return;
+		this.imageSelected.emit({ fieldId: this.field.id, file });
+	}
+
+	// ── checkbox (multi) ──
+	private checkboxArray(): string[] {
+		const v = this.raw();
+		return Array.isArray(v) ? (v as string[]) : [];
+	}
+	checkboxChecked(opt: string): boolean {
+		return this.checkboxArray().includes(opt);
+	}
+	toggleCheckbox(opt: string, event: Event): void {
+		const checked = (event.target as HTMLInputElement).checked;
+		const arr = this.checkboxArray();
+		const next = checked ? [...arr, opt] : arr.filter((x) => x !== opt);
+		this.setValue(next);
+	}
+
+	// ── stepper ──
+	bumpStepper(delta: number): void {
+		this.setValue(this.numberValue() + delta);
+	}
+
+	// ── slider ──
+	sliderMin(): number {
+		return this.field.sliderConfig?.min ?? 0;
+	}
+	sliderMax(): number {
+		return this.field.sliderConfig?.max ?? 100;
+	}
+	sliderStep(): number {
+		return this.field.sliderConfig?.step ?? 1;
+	}
+	sliderFmt(n: number): string {
+		const unit = this.field.sliderConfig?.unit;
+		if (unit === "currency") return `$${n}`;
+		if (unit === "percent") return `${n}%`;
+		return `${n}`;
+	}
+
+	// ── ratings ──
+	starIndexes(): number[] {
+		const max = this.field.starRatingConfig?.maxStars ?? 5;
+		return Array.from({ length: max }, (_, i) => i);
+	}
+	happinessFaces(): string[] {
+		return ["😞", "😕", "😐", "🙂", "😄"];
+	}
+
+	// ── date_range / time_block ──
+	private rangeObj(): { start?: string; end?: string } {
+		const v = this.raw();
+		return v && typeof v === "object" ? (v as { start?: string; end?: string }) : {};
+	}
+	rangeStart(): string {
+		return this.rangeObj().start ?? "";
+	}
+	rangeEnd(): string {
+		return this.rangeObj().end ?? "";
+	}
+	onRange(part: "start" | "end", event: Event): void {
+		const value = (event.target as HTMLInputElement).value;
+		this.setValue({ ...this.rangeObj(), [part]: value });
+	}
+
+	// ── time_picker (appointment) ──
+	timeMode(): "simple" | "time_block" | "appointment" {
+		return this.field.timeConfig?.mode ?? "simple";
+	}
+	private apptObj(): { date?: string; time?: string } {
+		const v = this.raw();
+		return v && typeof v === "object" ? (v as { date?: string; time?: string }) : {};
+	}
+	apptDate(): string {
+		return this.apptObj().date ?? "";
+	}
+	apptTime(): string {
+		return this.apptObj().time ?? "";
+	}
+	onAppt(part: "date" | "time", event: Event): void {
+		const value = (event.target as HTMLInputElement).value;
+		this.setValue({ ...this.apptObj(), [part]: value });
+	}
+
+	// ── address ──
+	private addrObj(): Record<string, string> {
+		const v = this.raw();
+		return v && typeof v === "object" ? (v as Record<string, string>) : {};
+	}
+	addrField(key: string): string {
+		return this.addrObj()[key] ?? "";
+	}
+	onAddr(key: string, event: Event): void {
+		const value = (event.target as HTMLInputElement).value;
+		this.setValue({ ...this.addrObj(), [key]: value });
+	}
+
+	// ── phone ──
+	phonePlaceholder(): string {
+		if (this.field.placeholder) return this.field.placeholder;
+		return this.field.phoneConfig?.international === true
+			? "+1 (555) 000-0000"
+			: "(555) 000-0000";
+	}
+
+	// ── image ──
+	imageSrc(): string {
+		const cfg = (this.field as { imageConfig?: { src?: string } }).imageConfig;
+		return cfg?.src ?? "";
+	}
+
+	// ── file_upload ──
+	fileMultiple(): boolean {
+		return (this.field.fileConfig?.maxFiles ?? 1) > 1;
+	}
+	fileAccept(): string {
+		const types = this.field.fileConfig?.allowedTypes;
+		return types && types.length > 0 ? types.join(",") : "";
+	}
+	fileList(): Array<{ storageId: string; name: string }> {
+		const v = this.raw();
+		return Array.isArray(v) ? (v as Array<{ storageId: string; name: string }>) : [];
+	}
+	onFile(event: Event): void {
+		const input = event.target as HTMLInputElement;
+		const file = input.files?.[0];
+		if (file) this.fileSelected.emit({ fieldId: this.field.id, file });
+		// Clear the input so re-picking the same file fires `change` again.
+		input.value = "";
+	}
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public component — `<biab-form>`. Owns the controller, mirrors its snapshot
+// into a signal, and orchestrates steps / progress / submit. Renders each
+// visible top-level node via `<biab-form-node>`.
+// ─────────────────────────────────────────────────────────────────────────────
+
+@Component({
+	selector: "biab-form",
+	changeDetection: ChangeDetectionStrategy.OnPush,
+	imports: [BiabFormNodeComponent],
+	host: {
+		class: "biab-form",
+		"[class.biab-form--submitting]": "snapshot().submitting",
+		"[class.biab-form--submitted]": "snapshot().submitted",
+		"[attr.data-biab-animation]": "snapshot().settings.animation",
+	},
+	template: `
+		@let snap = snapshot();
+
+		@if (snap.orgIcon) {
+			<img class="biab-form__org-icon" [src]="snap.orgIcon" alt="" />
+		}
+
+		@switch (snap.status) {
+			@case ("loading") {
+				<div class="biab-form__loading">Loading…</div>
+			}
+			@case ("error") {
+				<div class="biab-form__load-error">
+					{{ snap.loadError || "Couldn't load this form." }}
+				</div>
+			}
+			@default {
+				@if (snap.submitted) {
+					<div class="biab-form__success">
+						{{ successMessage() }}
+					</div>
+				} @else {
+					<form
+						class="biab-form__body"
+						[attr.data-biab-step]="snap.step"
+						(ngSubmit)="onSubmit()"
+					>
+						@if (showSteps()) {
+							<div class="biab-progress biab-progress--steps">
+								<div class="biab-progress__title">Form Progress</div>
+								<ol class="biab-progress__list">
+									@for (s of snap.steps; track $index; let i = $index) {
+										<li
+											class="biab-progress__step"
+											[class.biab-progress__step--current]="i === snap.step"
+											[class.biab-progress__step--done]="i < snap.step"
+										>
+											<span class="biab-progress__index">
+												{{ i < snap.step ? "✓" : i + 1 }}
+											</span>
+											<span class="biab-progress__label">{{ stepTitle(s, i) }}</span>
+										</li>
+									}
+								</ol>
+							</div>
+						}
+
+						@if (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>
+							</div>
+						}
+
+						@if (snap.errorList.length) {
+							<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">
+									{{ errorLabels() }}
+								</div>
+							</div>
+						}
+
+						<div class="biab-form__fields" [attr.data-biab-direction]="snap.forward ? 'forward' : 'back'">
+							@for (node of snap.visibleFields; track node.id) {
+								<biab-form-node
+									[field]="node"
+									[values]="snap.values"
+									[errors]="snap.errors"
+									[autocompleteConfig]="autocompleteConfig()"
+									(valueChange)="onValueChange($event)"
+									(fileSelected)="onFileSelected($event)"
+									(imageSelected)="onImageSelected($event)"
+								/>
+							}
+						</div>
+
+						<div class="biab-nav">
+							@if (isMultiStep()) {
+								<button
+									type="button"
+									class="biab-btn biab-btn--back"
+									[disabled]="snap.isFirstStep"
+									(click)="back()"
+								>
+									Back
+								</button>
+							}
+							@if (isMultiStep() && !snap.isLastStep) {
+								<button
+									type="button"
+									class="biab-btn biab-btn--next"
+									[disabled]="!snap.canAdvance"
+									(click)="next()"
+								>
+									Next
+								</button>
+							} @else {
+								<button
+									type="submit"
+									class="biab-btn biab-btn--submit"
+									[disabled]="snap.submitting || snap.uploading"
+								>
+									{{ snap.submitting ? "Sending…" : submitLabel() }}
+								</button>
+							}
+						</div>
+
+						@if (failureMessage()) {
+							<p class="biab-form__submit-error" role="alert">{{ failureMessage() }}</p>
+						}
+					</form>
+				}
+			}
+		}
+	`,
+})
+export class BiabFormComponent implements OnInit {
+	private readonly destroyRef = inject(DestroyRef);
+	/** App-wide client from DI (optional). A `[client]` input wins over it. */
+	private readonly injectedClient = inject(BIAB_CLIENT, { optional: true });
+
+	// ── Inputs (signal inputs; the public, framework-consistent surface) ──
+
+	/** Form slug to load via the client. Required unless `[schema]` is supplied. */
+	readonly slug = input<string | undefined>(undefined);
+	/** Pre-fetched schema (SSR / proxy). When set, the controller adopts it
+	 *  synchronously and skips the network load. `[client]` is still needed to
+	 *  submit / upload. */
+	readonly schema = input<FormSchema | undefined>(undefined);
+	/** Per-instance client override. Falls back to the DI-provided client. */
+	readonly client = input<BiabClient | undefined>(undefined);
+	/** Submit button label (final step). Defaults to "Submit". */
+	readonly submitLabel = input<string>("Submit");
+	/** Validate-only submit: nothing is stored, no side effects. */
+	readonly dryRun = input<boolean>(false);
+	/** Default submit options merged into every submit (call opts win). */
+	readonly submitOptions = input<FormSubmitOptions | undefined>(undefined);
+	/** Extra class string appended to the host (alias `className` for parity). */
+	readonly className = input<string>("");
+	/** Global autofill switch. Default (undefined) infers a sensible
+	 *  `autocomplete` token per field (name/email/tel/address/…); `false` emits
+	 *  `autocomplete="off"` on every value-bearing input. Bind `[autoComplete]`. */
+	readonly autoComplete = input<boolean | undefined>(undefined);
+	/** Per-field autofill overrides keyed by field id: a literal token, `true`
+	 *  (infer), or `false` (off). Wins over `autoComplete` and any schema token.
+	 *  Bind `[fieldAutoComplete]`. */
+	readonly fieldAutoComplete = input<Record<string, string | boolean> | undefined>(
+		undefined,
+	);
+
+	// ── Outputs (framework-consistent: onSubmit / onSuccess / onError) ──
+
+	/** Fires with the raw {@link FormSubmitResult} after every submit attempt. */
+	readonly submitResult = output<FormSubmitResult>();
+	/** Fires only on a successful submit. */
+	readonly success = output<Extract<FormSubmitResult, { ok: true }>>();
+	/** Fires only on a failed submit. */
+	readonly error = output<Extract<FormSubmitResult, { ok: false }>>();
+
+	// ── Snapshot signal — single source of truth for the template ──
+	readonly snapshot = signal<FormSnapshot>(EMPTY_SNAPSHOT);
+
+	/** Autofill config threaded to the field tree, derived from the
+	 *  `autoComplete` / `fieldAutoComplete` inputs (mirrors react.tsx). */
+	readonly autocompleteConfig = computed<AutocompleteConfig>(() => {
+		const enabled = this.autoComplete();
+		const overrides = this.fieldAutoComplete();
+		return {
+			...(enabled !== undefined ? { enabled } : {}),
+			...(overrides ? { overrides } : {}),
+		};
+	});
+
+	private controller: FormController | null = null;
+
+	// Resolve the effective client: per-instance input → DI token.
+	private resolveClient(): BiabClient | undefined {
+		return this.client() ?? this.injectedClient ?? undefined;
+	}
+
+	ngOnInit(): void {
+		const client = this.resolveClient();
+		const schema = this.schema();
+		const slug = this.slug();
+
+		const controller = createFormController({
+			...(client ? { client } : {}),
+			...(slug ? { slug } : {}),
+			...(schema ? { schema } : {}),
+			...(this.submitOptions() ? { submitOptions: this.submitOptions() } : {}),
+			onSuccess: (result) => this.success.emit(result),
+			onError: (result) => this.error.emit(result),
+		});
+		this.controller = controller;
+
+		// Seed the initial snapshot, then keep the signal in lockstep with the
+		// controller's notify stream. `subscribe` is NOT called on subscribe, so
+		// we pull the current snapshot explicitly first.
+		this.snapshot.set(controller.snapshot());
+		const unsubscribe = controller.subscribe((next) => this.snapshot.set(next));
+
+		this.destroyRef.onDestroy(() => {
+			unsubscribe();
+			controller.destroy();
+		});
+
+		void controller.load();
+	}
+
+	// ── Settings-derived view flags ──
+	private settings() {
+		return this.snapshot().settings;
+	}
+	isMultiStep(): boolean {
+		return this.settings().isConsecutive && this.snapshot().stepCount > 1;
+	}
+	showSteps(): boolean {
+		const s = this.settings();
+		return (
+			this.isMultiStep() && s.showProgress && s.progressStyle !== "bar"
+		);
+	}
+	showBar(): boolean {
+		const s = this.settings();
+		return this.isMultiStep() && s.showProgress && s.progressStyle === "bar";
+	}
+
+	stepTitle(step: FormCoreField[], index: number): string {
+		const first = step[0];
+		return first?.stepTitle || first?.label || `Step ${index + 1}`;
+	}
+
+	errorLabels(): string {
+		return this.snapshot()
+			.errorList.map((e) => e.label)
+			.join(", ");
+	}
+
+	successMessage(): string {
+		const result = this.snapshot().result;
+		if (result?.ok && result.dryRun) return "Looks good — this was a dry run.";
+		return "Thanks — we got your submission.";
+	}
+
+	failureMessage(): string {
+		const result = this.snapshot().result;
+		if (result && !result.ok && result.reason !== "client_validation_failed") {
+			return result.message;
+		}
+		return "";
+	}
+
+	// ── Controller delegation ──
+	onValueChange(change: { id: string; value: unknown }): void {
+		this.controller?.setValue(change.id, change.value);
+	}
+
+	async onFileSelected(picked: { fieldId: string; file: File }): Promise<void> {
+		try {
+			await this.controller?.uploadFile(picked.fieldId, picked.file, {
+				filename: picked.file.name,
+			});
+		} catch {
+			// uploadFile throws on plan-gate/transfer error; the snapshot's
+			// `uploading` flag resets in its finally. Surfacing a per-field upload
+			// error is left to the org's CSS / a future enhancement.
+		}
+	}
+
+	/**
+	 * `image_input` — upload, then store the resulting URL as the field's value.
+	 * Unlike `file_upload` (whose value is an array of file records), an image
+	 * input's value is a single URL STRING, so the upload result replaces it.
+	 */
+	async onImageSelected(picked: { fieldId: string; file: File }): Promise<void> {
+		try {
+			const uploaded = await this.controller?.uploadFile(
+				picked.fieldId,
+				picked.file,
+				{ filename: picked.file.name },
+			);
+			const url = (uploaded as { url?: string } | undefined)?.url;
+			if (url) this.controller?.setValue(picked.fieldId, url);
+		} catch {
+			// Same posture as onFileSelected — the snapshot resets `uploading`.
+		}
+	}
+
+	next(): void {
+		this.controller?.next();
+	}
+	back(): void {
+		this.controller?.back();
+	}
+
+	async onSubmit(): Promise<void> {
+		if (!this.controller) return;
+		const opts: FormSubmitOptions = {
+			...this.submitOptions(),
+			...(this.dryRun() ? { dryRun: true } : {}),
+		};
+		const result = await this.controller.submit(opts);
+		this.submitResult.emit(result);
+	}
+}
+
+// A valid pre-load snapshot so the template never reads `null`. Mirrors the
+// controller's own seeded `buildSnapshot()` defaults.
+const EMPTY_SNAPSHOT: FormSnapshot = {
+	status: "idle",
+	loadError: null,
+	schema: null,
+	fieldDefs: [],
+	fields: [],
+	settings: {
+		animation: "none",
+		isConsecutive: false,
+		showProgress: false,
+		progressStyle: "steps",
+	},
+	orgIcon: null,
+	title: null,
+	description: null,
+	values: {},
+	errors: {},
+	errorList: [],
+	steps: [[]],
+	step: 0,
+	stepCount: 1,
+	isFirstStep: true,
+	isLastStep: true,
+	visibleFields: [],
+	progress: 0,
+	progressPercent: 0,
+	canAdvance: true,
+	canSubmit: true,
+	forward: true,
+	submitting: false,
+	uploading: false,
+	result: null,
+	submitted: false,
+};