@rokkit/forms 1.0.0-next.151 → 1.0.0-next.153

package/dist/src/index.d.ts

@@ -6,6 +6,7 @@ export { default as Input } from "./Input.svelte";
 export { default as InputField } from "./InputField.svelte";
 export { default as InfoField } from "./InfoField.svelte";
 export { default as StatusList } from "./StatusList.svelte";
+export { default as StepIndicator } from "./StepIndicator.svelte";
 export * from "./display";
 export * from "./input";
 export { createLookup, createLookupManager, clearLookupCache } from "./lib/lookup.svelte.js";

package/dist/src/lib/builder.svelte.d.ts

@@ -14,6 +14,8 @@ export class FormBuilder {
     });
     /** @type {FormElement[]} */
     elements: FormElement[];
+    /** True when currentStep can advance to the next step */
+    canAdvance: boolean;
     /** Combined schema+layout (scoped elements only) */
     get combined(): any;
     /**
@@ -194,6 +196,39 @@ export class FormBuilder {
      * Reset form data to initial snapshot and clear validation
      */
     reset(): void;
+    /** True when the layout contains step elements */
+    get isMultiStep(): any;
+    /** Number of step elements in the layout */
+    get totalSteps(): any;
+    /** Zero-based index of the active step */
+    get currentStep(): number;
+    /**
+     * Validate the current step and advance if valid.
+     * @returns {boolean} true if advanced, false if validation failed
+     */
+    next(): boolean;
+    /**
+     * Move to the previous step without validation.
+     * @returns {boolean} true if moved, false if already on first step
+     */
+    prev(): boolean;
+    /**
+     * Navigate to a previously visited step (index < currentStep).
+     * @param {number} index - Target step index
+     */
+    goToStep(index: number): void;
+    /**
+     * Validate all fields in a given step. Defaults to currentStep.
+     * @param {number} [index] - Step index (defaults to currentStep)
+     * @returns {boolean} true if no errors
+     */
+    isStepValid(index?: number): boolean;
+    /**
+     * Validate all fields belonging to a step by index.
+     * @param {number} index - Step index
+     * @returns {boolean} true if no errors
+     */
+    validateStep(index: number): boolean;
     #private;
 }
 export type FormElement = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/forms",
-  "version": "1.0.0-next.151",
+  "version": "1.0.0-next.153",
   "description": "Form building components for Rokkit applications",
   "repository": {
     "type": "git",

package/src/FormRenderer.svelte

@@ -65,11 +65,10 @@
 		}
 	})
 
-	// Sync prop changes to builder
+	// Sync external data prop changes to builder (effect only tracks `data`, not formBuilder.data,
+	// to avoid a proxy-vs-raw-value comparison loop)
 	$effect(() => {
-		if (formBuilder.data !== data) {
-			formBuilder.data = data
-		}
+		formBuilder.data = data
 	})
 
 	$effect(() => {
@@ -158,13 +157,22 @@
 		bind:this={formRoot}
 		data-form-root
 		data-form-submitting={submitting || undefined}
+		data-form-step={formBuilder.isMultiStep ? formBuilder.currentStep : undefined}
 		class={className}
 		onsubmit={handleSubmit}
 		{...props}
 	>
-		{#each formBuilder.elements as element, index (index)}
-			{@render renderElement(element)}
-		{/each}
+		{#if formBuilder.isMultiStep}
+			<div data-form-step-content>
+				{#each formBuilder.elements as element, index (index)}
+					{@render renderElement(element)}
+				{/each}
+			</div>
+		{:else}
+			{#each formBuilder.elements as element, index (index)}
+				{@render renderElement(element)}
+			{/each}
+		{/if}
 		{#if actions}
 			{@render actions({
 				submitting,
@@ -173,6 +181,17 @@
 				submit: handleSubmit,
 				reset: handleReset
 			})}
+		{:else if formBuilder.isMultiStep}
+			<div data-form-actions>
+				{#if formBuilder.currentStep > 0}
+					<button type="button" data-form-prev onclick={() => formBuilder.prev()}>Previous</button>
+				{/if}
+				{#if formBuilder.canAdvance}
+					<button type="button" data-form-next onclick={() => formBuilder.next()}>Next</button>
+				{:else}
+					<button type="submit" data-form-submit disabled={submitting}>Submit</button>
+				{/if}
+			</div>
 		{:else}
 			<div data-form-actions>
 				<button
@@ -188,10 +207,24 @@
 		{/if}
 	</form>
 {:else}
-	<div bind:this={formRoot} data-form-root class={className} {...props}>
-		{#each formBuilder.elements as element, index (index)}
-			{@render renderElement(element)}
-		{/each}
+	<div
+		bind:this={formRoot}
+		data-form-root
+		data-form-step={formBuilder.isMultiStep ? formBuilder.currentStep : undefined}
+		class={className}
+		{...props}
+	>
+		{#if formBuilder.isMultiStep}
+			<div data-form-step-content>
+				{#each formBuilder.elements as element, index (index)}
+					{@render renderElement(element)}
+				{/each}
+			</div>
+		{:else}
+			{#each formBuilder.elements as element, index (index)}
+				{@render renderElement(element)}
+			{/each}
+		{/if}
 	</div>
 {/if}
 

package/src/StepIndicator.svelte

@@ -0,0 +1,41 @@
+<script>
+	/**
+	 * StepIndicator — standalone presentational component showing multi-step form progress.
+	 * Place anywhere on the page; wire to FormBuilder.currentStep and FormBuilder.goToStep.
+	 */
+
+	let {
+		steps = [],
+		current = 0,
+		onclick = undefined
+	} = $props()
+
+	function stepState(index) {
+		if (index < current) return 'complete'
+		if (index === current) return 'current'
+		return 'upcoming'
+	}
+
+	function handleClick(index) {
+		if (index < current) onclick?.(index)
+	}
+</script>
+
+<ol data-step-indicator>
+	{#each steps as label, index (index)}
+		{@const state = stepState(index)}
+		<li data-step-item data-step-state={state}>
+			{#if state === 'complete'}
+				<button
+					type="button"
+					data-step-number
+					onclick={() => handleClick(index)}
+					onkeydown={(e) => e.key === 'Enter' && handleClick(index)}
+				>{index + 1}</button>
+			{:else}
+				<span data-step-number>{index + 1}</span>
+			{/if}
+			<span data-step-label>{label}</span>
+		</li>
+	{/each}
+</ol>

package/src/index.js

@@ -14,6 +14,7 @@ export { default as Input } from './Input.svelte'
 export { default as InputField } from './InputField.svelte'
 export { default as InfoField } from './InfoField.svelte'
 export { default as StatusList } from './StatusList.svelte'
+export { default as StepIndicator } from './StepIndicator.svelte'
 
 // Display Components
 export * from './display'

package/src/lib/builder.svelte.js

@@ -127,9 +127,15 @@ export class FormBuilder {
 	/** @type {ReturnType<typeof createLookupManager>|null} */
 	#lookupManager = $state(null)
 
+	/** @type {number} */
+	#currentStep = $state(0)
+
 	/** @type {FormElement[]} */
 	elements = $derived(this.#buildElements())
 
+	/** True when currentStep can advance to the next step */
+	canAdvance = $derived(this.#currentStep < this.totalSteps - 1)
+
 	/** Combined schema+layout (scoped elements only) */
 	get combined() {
 		const scopedElements = (this.#layout?.elements ?? []).filter((el) => el.scope)
@@ -459,7 +465,7 @@ export class FormBuilder {
 	 */
 	#buildElements() {
 		try {
-			const layoutElements = this.#layout?.elements ?? []
+			const layoutElements = this.#getActiveElements()
 			const combinedMap = this.#buildCombinedMap(layoutElements)
 			return this.#collectElements(layoutElements, combinedMap)
 		} catch (error) {
@@ -708,6 +714,17 @@ export class FormBuilder {
 	 * @returns {Object} Validation results keyed by field path
 	 */
 	validate() {
+		if (this.isMultiStep) {
+			// Flatten all step elements into a synthetic layout for full validation
+			const allElements = []
+			for (const step of this.#layout?.elements ?? []) {
+				if (step.type === 'step') allElements.push(...(step.elements ?? []))
+			}
+			const flatLayout = { ...this.#layout, elements: allElements }
+			const results = validateAllFields(this.#data, this.#schema, flatLayout)
+			this.#validation = results
+			return results
+		}
 		const results = validateAllFields(this.#data, this.#schema, this.#layout)
 		const visiblePaths = new SvelteSet(
 			this.elements.filter((el) => el.scope).map((el) => el.scope.replace(/^#\//, ''))
@@ -777,8 +794,7 @@ export class FormBuilder {
 	 * @returns {Set<string>}
 	 */
 	get dirtyFields() {
-		// eslint-disable-next-line svelte/prefer-svelte-reactivity
-		const dirty = new Set()
+		const dirty = new SvelteSet()
 		this.#collectDirtyFields(this.#data, this.#initialData, '', dirty)
 		return dirty
 	}
@@ -884,10 +900,144 @@ export class FormBuilder {
 		this.#data = deepClone(this.#initialData)
 		this.#validation = {}
 	}
+
+	// ── Multi-Step ────────────────────────────────────────────
+
+	/** True when the layout contains step elements */
+	get isMultiStep() {
+		return (this.#layout?.elements ?? []).some((el) => el.type === 'step')
+	}
+
+	/** Number of step elements in the layout */
+	get totalSteps() {
+		return (this.#layout?.elements ?? []).filter((el) => el.type === 'step').length
+	}
+
+	/** Zero-based index of the active step */
+	get currentStep() {
+		return this.#currentStep
+	}
+
+	/**
+	 * Validate the current step and advance if valid.
+	 * @returns {boolean} true if advanced, false if validation failed
+	 */
+	next() {
+		if (!this.validateStep(this.#currentStep)) return false
+		if (this.#currentStep < this.totalSteps - 1) {
+			this.#currentStep++
+			return true
+		}
+		return false
+	}
+
+	/**
+	 * Move to the previous step without validation.
+	 * @returns {boolean} true if moved, false if already on first step
+	 */
+	prev() {
+		if (this.#currentStep > 0) {
+			this.#currentStep--
+			return true
+		}
+		return false
+	}
+
+	/**
+	 * Navigate to a previously visited step (index < currentStep).
+	 * @param {number} index - Target step index
+	 */
+	goToStep(index) {
+		if (index >= this.#currentStep) throw new Error('Cannot navigate forward to an unvisited step')
+		this.#currentStep = index
+	}
+
+	/**
+	 * Validate all fields in a given step. Defaults to currentStep.
+	 * @param {number} [index] - Step index (defaults to currentStep)
+	 * @returns {boolean} true if no errors
+	 */
+	isStepValid(index = this.#currentStep) {
+		return this.validateStep(index)
+	}
+
+	/**
+	 * Validate all fields belonging to a step by index.
+	 * @param {number} index - Step index
+	 * @returns {boolean} true if no errors
+	 */
+	validateStep(index) {
+		const stepEl = (this.#layout?.elements ?? [])[index]
+		if (!stepEl || stepEl.type !== 'step') return true
+		const stepLayout = { ...this.#layout, elements: stepEl.elements ?? [] }
+		const results = validateAllFields(this.#data, this.#schema, stepLayout)
+		this.#applyStepValidation(results, stepEl.elements)
+		return isAllValid(results)
+	}
+
+	/**
+	 * Apply validation results for a step's fields into the validation state.
+	 * @private
+	 */
+	#applyStepValidation(results, elements) {
+		const paths = new SvelteSet(this.#collectStepPaths(elements))
+		for (const path of paths) {
+			this.setFieldValidation(path, results[path] ?? null)
+		}
+	}
+
+	/**
+	 * Collect all scoped field paths from a step's elements recursively.
+	 * @private
+	 * @param {Object[]} elements - Step element array
+	 * @returns {string[]}
+	 */
+	#collectStepPaths(elements) {
+		const paths = []
+		for (const el of elements ?? []) {
+			if (el.scope) paths.push(el.scope.replace(/^#\//, ''))
+			if (el.elements) paths.push(...this.#collectStepPaths(el.elements))
+		}
+		return paths
+	}
+
+	/**
+	 * Collect all field paths across all steps.
+	 * @private
+	 * @returns {Set<string>}
+	 */
+	#getAllStepPaths() {
+		const paths = new SvelteSet()
+		for (const step of this.#layout?.elements ?? []) {
+			if (step.type === 'step') {
+				for (const path of this.#collectStepPaths(step.elements)) paths.add(path)
+			}
+		}
+		return paths
+	}
+
+	/**
+	 * Return the layout elements for the active step (or all elements for flat layouts).
+	 * @private
+	 * @returns {Object[]}
+	 */
+	#getActiveElements() {
+		const elements = this.#layout?.elements ?? []
+		if (!elements.some((el) => el.type === 'step')) return elements
+		return elements[this.#currentStep]?.elements ?? []
+	}
 }
 
 // ── Module-level helpers (no `this`) ──────────────────────────────────────────
 
+/**
+ * Returns true when no result in the map has state === 'error'
+ * @private
+ */
+function isAllValid(results) {
+	return Object.values(results).every((msg) => msg?.state !== 'error')
+}
+
 /**
  * Return the display label for a layout element, falling back to fieldPath
  * @private