@rokkit/forms 1.7.0 → 1.8.0

package/dist/lib/elements.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The input type for a field: an explicit renderer, then a non-basic format (`email`, `date`…),
+ * then its schema type — a bounded number is a range, a string with choices a select. May set
+ * `props.options` from an enum.
+ * @param {Record<string, any>} props
+ * @returns {string}
+ */
+export function resolveInputType(props: Record<string, any>): string;
+/**
+ * The FormElements for the given layout elements (a step's, or a flat layout's).
+ *
+ * A field hidden by `showWhen` has no element. If building throws — a layout scope the schema
+ * does not know is one way — the whole layout falls back to plain text inputs rather than
+ * rendering nothing.
+ *
+ * @param {Object[]} layoutElements
+ * @param {ElementContext} ctx
+ */
+export function buildElements(layoutElements: Object[], ctx: ElementContext): any;
+/**
+ * Layout + schema + state → the `FormElement`s a `FormRenderer` draws. Pure: everything it needs
+ * arrives in `ctx`, so it is testable without a FormBuilder and derivable as one `$derived`.
+ */
+export type ElementContext = {
+    schema: Object;
+    /**
+     * - the whole layout (the fallback path renders all of it)
+     */
+    layout: Object;
+    data: Record<string, unknown>;
+    value: (path: string) => unknown;
+    /**
+     * - validation message for a field
+     */
+    message: (path: string) => Object | null;
+    dirty: (path: string) => boolean;
+    /**
+     * - fold lookup state into props
+     */
+    applyLookup: (path: string, props: Object) => void;
+};
+export type FormElement = {
+    /**
+     * - JSON Pointer path (e.g., '#/email', '#/user/name')
+     */
+    scope: string;
+    /**
+     * - Input type (text, number, range, checkbox, select, etc.)
+     */
+    type: string;
+    /**
+     * - Current value from data
+     */
+    value: any;
+    /**
+     * - Whether to use custom child snippet (from layout)
+     */
+    override: boolean;
+    /**
+     * - Merged properties from schema + layout + validation
+     */
+    props: {
+        label?: string | undefined;
+        description?: string | undefined;
+        placeholder?: string | undefined;
+        required?: boolean | undefined;
+        min?: number | undefined;
+        max?: number | undefined;
+        message?: {
+            /**
+             * - Message state: 'error', 'warning', 'info', 'success'
+             */
+            state?: string | undefined;
+            /**
+             * - Message text content
+             */
+            text?: string | undefined;
+        } | undefined;
+        dirty?: boolean | undefined;
+    };
+};

package/dist/lib/elements.js

@@ -0,0 +1,196 @@
+/**
+ * Layout + schema + state → the `FormElement`s a `FormRenderer` draws. Pure: everything it needs
+ * arrives in `ctx`, so it is testable without a FormBuilder and derivable as one `$derived`.
+ *
+ * @typedef {Object} ElementContext
+ * @property {Object} schema
+ * @property {Object} layout - the whole layout (the fallback path renders all of it)
+ * @property {Record<string, unknown>} data
+ * @property {(path: string) => unknown} value
+ * @property {(path: string) => Object | null} message - validation message for a field
+ * @property {(path: string) => boolean} dirty
+ * @property {(path: string, props: Object) => void} applyLookup - fold lookup state into props
+ */
+/**
+ * @typedef {Object} FormElement
+ * @property {string} scope - JSON Pointer path (e.g., '#/email', '#/user/name')
+ * @property {string} type - Input type (text, number, range, checkbox, select, etc.)
+ * @property {any} value - Current value from data
+ * @property {boolean} override - Whether to use custom child snippet (from layout)
+ * @property {Object} props - Merged properties from schema + layout + validation
+ * @property {string} [props.label] - Display label (from layout)
+ * @property {string} [props.description] - Help text (from layout)
+ * @property {string} [props.placeholder] - Placeholder text (from layout)
+ * @property {boolean} [props.required] - Required flag (from schema)
+ * @property {number} [props.min] - Minimum value (from schema)
+ * @property {number} [props.max] - Maximum value (from schema)
+ * @property {Object} [props.message] - Validation message object
+ * @property {string} [props.message.state] - Message state: 'error', 'warning', 'info', 'success'
+ * @property {string} [props.message.text] - Message text content
+ * @property {boolean} [props.dirty] - Whether field value differs from initial
+ */
+
+import { getSchemaWithLayout } from './fields.js'
+import { evaluateCondition } from './conditions.js'
+
+/** Schema types with a fixed input type. */
+const SCHEMA_TYPE_MAP = { boolean: 'checkbox', array: 'array' }
+
+const pathOf = (scope) => scope.replace(/^#\//, '')
+
+function stringInputType(props) {
+	if (!props.enum && !props.options) return 'text'
+	// A select reads `options`; an enum is the options when none are given.
+	if (Array.isArray(props.enum) && !props.options) props.options = props.enum
+	return 'select'
+}
+
+function schemaInputType(props) {
+	if (props.type === 'number' || props.type === 'integer') {
+		return props.min !== undefined && props.max !== undefined ? 'range' : 'number'
+	}
+	if (props.type === 'string') return stringInputType(props)
+	return SCHEMA_TYPE_MAP[props.type] ?? 'text'
+}
+
+/**
+ * The input type for a field: an explicit renderer, then a non-basic format (`email`, `date`…),
+ * then its schema type — a bounded number is a range, a string with choices a select. May set
+ * `props.options` from an enum.
+ * @param {Record<string, any>} props
+ * @returns {string}
+ */
+export function resolveInputType(props) {
+	if (props.renderer) return props.renderer
+	if (props.format && !['text', 'number'].includes(props.format)) return props.format
+	return schemaInputType(props)
+}
+
+/** A display element (`display-*`): its own type, its bound value, no input. */
+function displayElement(layoutEl, ctx) {
+	const { type, scope: rawScope, ...props } = layoutEl
+	const scope = rawScope ?? null
+	const value = scope ? ctx.value(pathOf(scope)) : null
+	return { type, scope, value, override: false, props }
+}
+
+/** An unscoped element — a separator, a spacer, a heading. */
+function unscopedElement(layoutEl) {
+	const { type, ...props } = layoutEl
+	return { type: type ?? 'separator', scope: null, value: null, override: false, props }
+}
+
+function groupElement(element, path, scope, ctx) {
+	const children = element.elements.map((child) => fieldElement(child, ctx, path))
+	const {
+		key: _key,
+		elements: _elements,
+		override: _override,
+		props: groupProps,
+		...topLevel
+	} = element
+	return {
+		scope,
+		type: 'group',
+		value: ctx.value(path),
+		override: element.override || false,
+		props: { ...topLevel, ...groupProps, elements: children, message: ctx.message(path) }
+	}
+}
+
+function readonlyElement(element, path, scope, ctx) {
+	return {
+		scope,
+		type: 'info',
+		value: ctx.value(path),
+		override: element.override || false,
+		props: { ...element.props, type: 'info', message: ctx.message(path) }
+	}
+}
+
+function inputElement(element, path, scope, ctx) {
+	// `override` is authored on the LAYOUT element, and getSchemaWithLayout folds unknown layout
+	// keys into `props` — read only from `element.override` it was always false and the child
+	// snippet never rendered. Take it from either place; keep it out of the input's props.
+	const { override: propsOverride, ...props } = element.props ?? {}
+	const type = resolveInputType(props)
+	const finalProps = { ...props, type, message: ctx.message(path), dirty: ctx.dirty(path) }
+	ctx.applyLookup(path, finalProps)
+	return {
+		scope,
+		type,
+		value: ctx.value(path),
+		override: element.override || propsOverride || false,
+		props: finalProps
+	}
+}
+
+/** A combined schema+layout element → FormElement. Null for one without a key. */
+function fieldElement(element, ctx, parentPath = '') {
+	/* v8 ignore start -- unreachable: every element arrives from getSchemaWithLayout's output,
+	   which combinedByKey keeps only when keyed and whose group children are keyed too. Kept as
+	   the guard FormBuilder always had. `ignore next` does not fire on a one-line `if`. */
+	if (!element.key) return null
+	/* v8 ignore stop */
+	const path = parentPath ? `${parentPath}/${element.key}` : element.key
+	const scope = `#/${path}`
+	if (element.elements) return groupElement(element, path, scope, ctx)
+	if (element.props.readonly) return readonlyElement(element, path, scope, ctx)
+	return inputElement(element, path, scope, ctx)
+}
+
+/** The schema-merged element for each scoped, non-display layout element, by field key. */
+function combinedByKey(layoutElements, ctx) {
+	const elements = layoutElements.filter((el) => el.scope && !el.type?.startsWith('display-'))
+	const combined = getSchemaWithLayout(ctx.schema, { ...ctx.layout, elements })
+	return new Map((combined.elements ?? []).filter((el) => el.key).map((el) => [el.key, el]))
+}
+
+function scopedElement(layoutEl, combined, ctx) {
+	if (layoutEl.showWhen && !evaluateCondition(layoutEl.showWhen, ctx.data)) return null
+	const merged = combined.get(pathOf(layoutEl.scope).split('/').pop())
+	return merged ? fieldElement(merged, ctx) : null
+}
+
+function layoutElement(layoutEl, combined, ctx) {
+	if (layoutEl.type?.startsWith('display-')) return displayElement(layoutEl, ctx)
+	if (!layoutEl.scope) return unscopedElement(layoutEl)
+	return scopedElement(layoutEl, combined, ctx)
+}
+
+/** Last resort when building fails: every scoped layout element as a plain text input. */
+function plainElements(ctx) {
+	return (ctx.layout.elements ?? [])
+		.filter((el) => el.scope)
+		.map(({ scope, label, override = false, ...layoutProps }) => {
+			const path = pathOf(scope)
+			const props = {
+				label: label || path,
+				...layoutProps,
+				message: ctx.message(path),
+				dirty: ctx.dirty(path),
+				type: 'text'
+			}
+			return { scope, type: 'text', value: ctx.value(path), override, props }
+		})
+}
+
+/**
+ * The FormElements for the given layout elements (a step's, or a flat layout's).
+ *
+ * A field hidden by `showWhen` has no element. If building throws — a layout scope the schema
+ * does not know is one way — the whole layout falls back to plain text inputs rather than
+ * rendering nothing.
+ *
+ * @param {Object[]} layoutElements
+ * @param {ElementContext} ctx
+ */
+export function buildElements(layoutElements, ctx) {
+	try {
+		const combined = combinedByKey(layoutElements, ctx)
+		return layoutElements.map((el) => layoutElement(el, combined, ctx)).filter(Boolean)
+	} catch (error) {
+		console.warn('Failed to build elements:', error) // eslint-disable-line no-console
+		return plainElements(ctx)
+	}
+}

package/dist/lib/schema.d.ts

@@ -5,3 +5,16 @@
  * @returns {import('../types').DataSchema}
  */
 export function deriveSchemaFromValue(data: any): import("../types").DataSchema;
+/**
+ * A field's schema by slash path (`'addr/city'`), or null.
+ *
+ * Each step looks in the current schema's `properties` first — how JSON Schema nests an object's
+ * fields — and falls back to the key directly on it, the flat form some schemas here use
+ * (`properties.a.b`). `properties` first, so a nested field named like a schema keyword (`type`)
+ * resolves to the field, not to its parent's keyword.
+ *
+ * @param {Object | null | undefined} schema
+ * @param {string} path
+ * @returns {Object | null}
+ */
+export function schemaAt(schema: Object | null | undefined, path: string): Object | null;

package/dist/lib/schema.js

@@ -29,3 +29,30 @@ export function deriveSchemaFromValue(data) {
 	}
 	return schema
 }
+
+const isSchemaObject = (value) => Boolean(value) && typeof value === 'object'
+
+/** One step down: the JSON Schema child, else the flat one. */
+function childSchema(parent, key) {
+	if (!isSchemaObject(parent)) return undefined
+	return parent.properties?.[key] ?? parent[key]
+}
+
+/**
+ * A field's schema by slash path (`'addr/city'`), or null.
+ *
+ * Each step looks in the current schema's `properties` first — how JSON Schema nests an object's
+ * fields — and falls back to the key directly on it, the flat form some schemas here use
+ * (`properties.a.b`). `properties` first, so a nested field named like a schema keyword (`type`)
+ * resolves to the field, not to its parent's keyword.
+ *
+ * @param {Object | null | undefined} schema
+ * @param {string} path
+ * @returns {Object | null}
+ */
+export function schemaAt(schema, path) {
+	// The root's own keys are the schema's keywords, never fields: only its `properties` count.
+	let current = schema?.properties?.[path.split('/')[0]]
+	for (const key of path.split('/').slice(1)) current = childSchema(current, key)
+	return isSchemaObject(current) ? current : null
+}

package/dist/lib/state/FormDefinition.svelte.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What the form IS: its schema (the fields and their rules) and its layout (how they are
+ * arranged), each derivable from the other or from the data.
+ *
+ * The setters carry the derivation rules, so a caller can set either at any time:
+ * - a schema set explicitly is the source of truth for which fields exist — a layout that was
+ *   only ever derived (perhaps from empty data) is re-derived from it; an explicit, non-empty
+ *   layout is kept;
+ * - a null schema derives from the current data;
+ * - a null layout derives from the schema when it declares fields — so declared fields render
+ *   even when the data starts as `{}`, the norm for LLM-generated and reset forms — else from
+ *   the data.
+ */
+export class FormDefinition {
+    /**
+     * @param {import('./FormValues.svelte.js').FormValues} values
+     * @param {Object|null} schema
+     * @param {Object|null} layout
+     */
+    constructor(values: import("./FormValues.svelte.js").FormValues, schema: Object | null, layout: Object | null);
+    set schema(value: {});
+    get schema(): {};
+    set layout(value: {});
+    get layout(): {};
+    /** Schema merged with the layout's scoped elements. */
+    get combined(): any;
+    /** The schema of one field by slash path, or null — see `schemaAt`. */
+    fieldSchema(path: any): Object | null;
+    /** A field's display label: its layout element's label, then title, then the path itself. */
+    fieldLabel(path: any): any;
+    #private;
+}

package/dist/lib/state/FormDefinition.svelte.js

@@ -0,0 +1,83 @@
+import { deriveSchemaFromValue, schemaAt } from '../schema.js'
+import { deriveLayoutFromValue, deriveLayoutFromSchema } from '../layout.js'
+import { getSchemaWithLayout } from '../fields.js'
+
+const hasFields = (schema) =>
+	Boolean(
+		schema &&
+		typeof schema === 'object' &&
+		schema.properties &&
+		typeof schema.properties === 'object' &&
+		Object.keys(schema.properties).length > 0
+	)
+
+const hasElements = (layout) =>
+	Boolean(layout && Array.isArray(layout.elements) && layout.elements.length > 0)
+
+/**
+ * What the form IS: its schema (the fields and their rules) and its layout (how they are
+ * arranged), each derivable from the other or from the data.
+ *
+ * The setters carry the derivation rules, so a caller can set either at any time:
+ * - a schema set explicitly is the source of truth for which fields exist — a layout that was
+ *   only ever derived (perhaps from empty data) is re-derived from it; an explicit, non-empty
+ *   layout is kept;
+ * - a null schema derives from the current data;
+ * - a null layout derives from the schema when it declares fields — so declared fields render
+ *   even when the data starts as `{}`, the norm for LLM-generated and reset forms — else from
+ *   the data.
+ */
+export class FormDefinition {
+	#values
+	#schema = $state({})
+	#layout = $state({})
+
+	/**
+	 * @param {import('./FormValues.svelte.js').FormValues} values
+	 * @param {Object|null} schema
+	 * @param {Object|null} layout
+	 */
+	constructor(values, schema, layout) {
+		this.#values = values
+		this.schema = schema
+		this.layout = layout
+	}
+
+	get schema() {
+		return this.#schema
+	}
+	set schema(value) {
+		this.#schema = value ?? deriveSchemaFromValue(this.#values.data)
+		if (!hasElements(this.#layout)) this.#layout = deriveLayoutFromSchema(this.#schema)
+	}
+
+	get layout() {
+		return this.#layout
+	}
+	set layout(value) {
+		if (value) {
+			this.#layout = value
+			return
+		}
+		this.#layout = hasFields(this.#schema)
+			? deriveLayoutFromSchema(this.#schema)
+			: deriveLayoutFromValue(this.#values.data)
+	}
+
+	/** Schema merged with the layout's scoped elements. */
+	get combined() {
+		const elements = (this.#layout?.elements ?? []).filter((el) => el.scope)
+		return getSchemaWithLayout(this.#schema, { ...this.#layout, elements })
+	}
+
+	/** The schema of one field by slash path, or null — see `schemaAt`. */
+	fieldSchema(path) {
+		return schemaAt(this.#schema, path)
+	}
+
+	/** A field's display label: its layout element's label, then title, then the path itself. */
+	fieldLabel(path) {
+		const el = this.#layout?.elements?.find((e) => e.scope === `#/${path}`)
+		return el?.label || (el?.title ?? path)
+	}
+}

package/dist/lib/state/FormLookups.svelte.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Fields whose options come from elsewhere — a URL, an async hook, or a filtered source — and
+ * the fields they depend on.
+ *
+ * A form with no lookups has no manager at all, and every question here answers safely.
+ */
+export class FormLookups {
+    /**
+     * @param {import('./FormValues.svelte.js').FormValues} values
+     * @param {Object<string, import('../lookup.svelte.js').LookupConfig>} lookups
+     */
+    constructor(values: import("./FormValues.svelte.js").FormValues, lookups?: {
+        [x: string]: import("../lookup.svelte.js").LookupConfig;
+    });
+    get manager(): Object | null;
+    /** Replace the lookups. Always builds a manager, even for none — as `setLookups` always has. */
+    configure(lookups: any): void;
+    /** A field's options, loading, error, fields and disabled — or null when it has no lookup. */
+    state(path: any): {
+        options: any;
+        loading: any;
+        error: any;
+        fields: any;
+        disabled: any;
+    } | null;
+    /** Disabled because a field it depends on is not set yet. */
+    isDisabled(path: any): any;
+    has(path: any): any;
+    refresh(path: any): Promise<void>;
+    initialize(): Promise<void>;
+    /**
+     * A field changed: clear the (top-level) values of lookups that depend on it — their options
+     * are about to change under them — then re-fetch those lookups.
+     */
+    fieldChanged(path: any): void;
+    /** Fold a field's lookup state into an element's props (mutates them). */
+    applyTo(path: any, props: any): void;
+    #private;
+}

package/dist/lib/state/FormLookups.svelte.js

@@ -0,0 +1,93 @@
+import { createLookupManager } from '../lookup.svelte.js'
+
+/**
+ * Fields whose options come from elsewhere — a URL, an async hook, or a filtered source — and
+ * the fields they depend on.
+ *
+ * A form with no lookups has no manager at all, and every question here answers safely.
+ */
+export class FormLookups {
+	#values
+	/** @type {ReturnType<typeof createLookupManager> | null} */
+	#manager = $state(null)
+
+	/**
+	 * @param {import('./FormValues.svelte.js').FormValues} values
+	 * @param {Object<string, import('../lookup.svelte.js').LookupConfig>} lookups
+	 */
+	constructor(values, lookups = {}) {
+		this.#values = values
+		if (Object.keys(lookups).length > 0) this.#manager = createLookupManager(lookups)
+	}
+
+	get manager() {
+		return this.#manager
+	}
+
+	/** Replace the lookups. Always builds a manager, even for none — as `setLookups` always has. */
+	configure(lookups) {
+		this.#manager = createLookupManager(lookups)
+	}
+
+	/** @param {string} path */
+	#lookup(path) {
+		return this.#manager?.getLookup(path)
+	}
+
+	/** A field's options, loading, error, fields and disabled — or null when it has no lookup. */
+	state(path) {
+		const lookup = this.#lookup(path)
+		if (!lookup) return null
+		const { options, loading, error, fields, disabled } = lookup
+		return { options, loading, error, fields, disabled }
+	}
+
+	/** Disabled because a field it depends on is not set yet. */
+	isDisabled(path) {
+		return this.#lookup(path)?.disabled ?? false
+	}
+
+	has(path) {
+		return this.#manager?.hasLookup(path) ?? false
+	}
+
+	async refresh(path) {
+		await this.#lookup(path)?.fetch(this.#values.data)
+	}
+
+	async initialize() {
+		await this.#manager?.initialize(this.#values.data)
+	}
+
+	/**
+	 * A field changed: clear the (top-level) values of lookups that depend on it — their options
+	 * are about to change under them — then re-fetch those lookups.
+	 */
+	fieldChanged(path) {
+		if (!this.#manager) return
+		for (const [depPath, lookup] of this.#manager.lookups) {
+			if (lookup.dependsOn.includes(path) && !depPath.includes('/')) this.#values.set(depPath, null)
+		}
+		this.#manager.handleFieldChange(path, this.#values.data)
+	}
+
+	/** Fold a field's lookup state into an element's props (mutates them). */
+	applyTo(path, props) {
+		const state = this.state(path)
+		if (!state) return
+		applyOptions(state, props)
+		applyAvailability(state, props)
+	}
+}
+
+/** Options and loading. */
+function applyOptions(state, props) {
+	if (state.options?.length > 0) props.options = state.options
+	if (state.loading) props.loading = true
+}
+
+/** Disabled, and the option field mapping unless the element sets its own. */
+function applyAvailability(state, props) {
+	if (state.disabled) props.disabled = true
+	if (state.fields && !props.fields) props.fields = state.fields
+}

package/dist/lib/state/FormSteps.svelte.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Every scoped field path in a list of layout elements, nested groups included.
+ * @param {Object[] | undefined} elements
+ * @returns {string[]}
+ */
+export function stepPaths(elements: Object[] | undefined): string[];
+/**
+ * A multi-step (wizard) form: a layout whose top-level elements are `{ type: 'step' }`. Only the
+ * active step's elements render. A flat layout has no steps, and all of it is active.
+ *
+ * Moving forward is `advance()` here; VALIDATING before moving is the form's job, which is why
+ * `FormBuilder.next()` checks the step and then calls this.
+ */
+export class FormSteps {
+    /** @param {import('./FormDefinition.svelte.js').FormDefinition} definition */
+    constructor(definition: import("./FormDefinition.svelte.js").FormDefinition);
+    get isMultiStep(): any;
+    get total(): any;
+    get current(): number;
+    canAdvance: boolean;
+    /** The step element at an index, or null when there is none. */
+    step(index: any): any;
+    /** The layout elements that render now: the active step's, or all of a flat layout's. */
+    get activeElements(): any;
+    /** Every step's elements, flattened — the whole form, for validating all of it at once. */
+    get allStepElements(): any;
+    advance(): boolean;
+    back(): boolean;
+    /** Return to a step already visited. Forward is only reachable through `next()`. */
+    goTo(index: any): void;
+    #private;
+}

package/dist/lib/state/FormSteps.svelte.js

@@ -0,0 +1,80 @@
+/**
+ * Every scoped field path in a list of layout elements, nested groups included.
+ * @param {Object[] | undefined} elements
+ * @returns {string[]}
+ */
+export function stepPaths(elements) {
+	const paths = []
+	for (const el of elements ?? []) {
+		if (el.scope) paths.push(el.scope.replace(/^#\//, ''))
+		if (el.elements) paths.push(...stepPaths(el.elements))
+	}
+	return paths
+}
+
+/**
+ * A multi-step (wizard) form: a layout whose top-level elements are `{ type: 'step' }`. Only the
+ * active step's elements render. A flat layout has no steps, and all of it is active.
+ *
+ * Moving forward is `advance()` here; VALIDATING before moving is the form's job, which is why
+ * `FormBuilder.next()` checks the step and then calls this.
+ */
+export class FormSteps {
+	#definition
+	#current = $state(0)
+
+	/** @param {import('./FormDefinition.svelte.js').FormDefinition} definition */
+	constructor(definition) {
+		this.#definition = definition
+	}
+
+	get #elements() {
+		return this.#definition.layout?.elements ?? []
+	}
+
+	get isMultiStep() {
+		return this.#elements.some((el) => el.type === 'step')
+	}
+	get total() {
+		return this.#elements.filter((el) => el.type === 'step').length
+	}
+	get current() {
+		return this.#current
+	}
+	canAdvance = $derived(this.#current < this.total - 1)
+
+	/** The step element at an index, or null when there is none. */
+	step(index) {
+		const el = this.#elements[index]
+		return el?.type === 'step' ? el : null
+	}
+
+	/** The layout elements that render now: the active step's, or all of a flat layout's. */
+	get activeElements() {
+		if (!this.isMultiStep) return this.#elements
+		return this.#elements[this.#current]?.elements ?? []
+	}
+
+	/** Every step's elements, flattened — the whole form, for validating all of it at once. */
+	get allStepElements() {
+		return this.#elements.filter((el) => el.type === 'step').flatMap((step) => step.elements ?? [])
+	}
+
+	advance() {
+		if (this.#current >= this.total - 1) return false
+		this.#current++
+		return true
+	}
+
+	back() {
+		if (this.#current === 0) return false
+		this.#current--
+		return true
+	}
+
+	/** Return to a step already visited. Forward is only reachable through `next()`. */
+	goTo(index) {
+		if (index >= this.#current) throw new Error('Cannot navigate forward to an unvisited step')
+		this.#current = index
+	}
+}