El Desafío de Estado en los Formularios Multipaso

Los formularios multipaso, conocidos frecuentemente como wizards o steppers, dividen formularios complejos en partes manejables. En lugar de abrumar a los usuarios con docenas de campos en una sola página, los wizards los guían a través de una secuencia de pasos enfocados. Cada paso recopila información relacionada, la valida y solo entonces permite avanzar al siguiente paso.

Construir un wizard presenta desafíos interesantes de gestión de estado. El wizard necesita registrar en qué paso se encuentra el usuario, almacenar todos los datos recopilados entre pasos, validar cada paso antes de permitir el avance, recordar qué pasos han sido visitados o completados, y coordinar todo esto entre múltiples componentes.

El contexto es la solución natural. El contenedor del wizard provee un contexto al que todos los componentes de paso pueden acceder. Los pasos pueden leer los datos compartidos del formulario, actualizar su porción de ellos y disparar la navegación. El contexto maneja la validación, registra el progreso y gestiona el estado general del wizard.

En este artículo, construirás un sistema de wizard flexible que podrás reutilizar en tus aplicaciones. Implementarás navegación por pasos con compuertas de validación, seguimiento del progreso con indicadores visuales, y una API limpia que hace que crear nuevos wizards sea sencillo.

Diseñando el Wizard

Antes de implementar, pensemos qué necesita hacer un wizard y cómo debería funcionar su API.

Requisitos Básicos

Un wizard práctico debe manejar estas preocupaciones:

Preocupación	Descripción
Definición de Paso	Cada paso necesita un identificador, etiqueta y validación opcional
Almacenamiento de Datos	Los datos del formulario persisten a través de todos los pasos
Navegación	Avanzar, retroceder o saltar a pasos específicos
Validación	Validar el paso actual antes de permitir el avance
Seguimiento de Progreso	Registrar los pasos visitados y completados
Visualización de Errores	Mostrar errores de validación con claridad

Objetivos de Diseño de la API

La API del wizard debe ser intuitiva para los desarrolladores que construyen formularios:

<!-- Desired usage pattern -->
<Wizard {steps} initialData={data} onComplete={handleSubmit}>
	{#if wizard.currentStep.id === 'personal'}
		<PersonalInfoStep />
	{:else if wizard.currentStep.id === 'address'}
		<AddressStep />
	{:else if wizard.currentStep.id === 'payment'}
		<PaymentStep />
	{/if}
</Wizard>

Cada componente de paso accede al contexto del wizard para leer y actualizar datos:

<!-- Inside a step component -->
<script>
	const wizard = getWizardContext()
</script>

<input value={wizard.data.email} oninput={(e) => wizard.setField('email', e.target.value)} />

Esta separación mantiene los componentes de paso enfocados en sus campos específicos mientras el wizard maneja la orquestación.

Definiciones de Tipos

Comienza con tipos exhaustivos que documenten las capacidades del wizard:

// src/lib/wizard/types.ts

/**
 * Defines a single step in the wizard.
 */
export interface WizardStep {
	/** Unique identifier for this step */
	id: string

	/** Display label shown in progress indicator */
	label: string

	/** Optional description shown below the label */
	description?: string

	/**
	 * Validation function for this step.
	 * Receives all wizard data and returns validation result.
	 */
	validate?: (data: Record<string, unknown>) => ValidationResult

	/** Whether this step can be skipped */
	optional?: boolean
}

/**
 * Result of validating a step.
 */
export interface ValidationResult {
	/** Whether validation passed */
	valid: boolean

	/** Map of field names to error messages */
	errors: Record<string, string>
}

/**
 * The public API of the wizard context.
 */
export interface WizardContext<T extends Record<string, unknown> = Record<string, unknown>> {
	// Current state
	readonly data: T
	readonly currentStepIndex: number
	readonly currentStep: WizardStep
	readonly steps: readonly WizardStep[]
	readonly errors: Record<string, string>

	// Validation state
	readonly isValid: boolean
	readonly isSubmitting: boolean

	// Navigation state
	readonly canGoBack: boolean
	readonly canGoForward: boolean
	readonly isFirstStep: boolean
	readonly isLastStep: boolean

	// Progress
	readonly progress: number
	readonly visitedSteps: ReadonlySet<number>
	readonly completedSteps: ReadonlySet<number>

	// Data operations
	setField<K extends keyof T>(key: K, value: T[K]): void
	setFields(fields: Partial<T>): void

	// Navigation operations
	nextStep(): boolean
	prevStep(): void
	goToStep(index: number): boolean

	// Validation operations
	validate(): ValidationResult
	setError(field: string, message: string): void
	clearError(field: string): void
	clearAllErrors(): void

	// Wizard operations
	reset(): void
	submit(): Promise<void>
}

/**
 * Configuration for creating a wizard.
 */
export interface WizardOptions<T extends Record<string, unknown>> {
	/** Step definitions */
	steps: WizardStep[]

	/** Initial form data */
	initialData: T

	/** Called when wizard completes successfully */
	onComplete?: (data: T) => void | Promise<void>

	/** Allow jumping to unvisited steps */
	allowSkipAhead?: boolean
}

Entendiendo el Tipo Genérico

El wizard utiliza un tipo genérico T para los datos del formulario. Esto permite que TypeScript sepa exactamente qué campos existen:

interface CheckoutData {
	email: string
	name: string
	address: string
	cardNumber: string
}

// TypeScript knows wizard.data has these exact fields
const wizard = getWizardContext<CheckoutData>()
wizard.setField('email', 'user@example.com') // ✅ Valid
wizard.setField('phone', '555-1234') // ❌ Error: 'phone' not in CheckoutData

Implementando el Contexto del Wizard

El contexto del wizard gestiona todo el estado y provee la API para los componentes de paso:

// src/lib/wizard/wizard-context.svelte.ts

import { setContext, getContext, hasContext } from 'svelte'
import type { WizardStep, WizardContext, WizardOptions, ValidationResult } from './types'

/**
 * Symbol key for the wizard context.
 */
const WIZARD_KEY = Symbol('wizard')

/**
 * Creates and provides the wizard context.
 * Call this in your Wizard component.
 */
export function createWizardContext<T extends Record<string, unknown>>(
	options: WizardOptions<T>
): WizardContext<T> {
	const { steps, initialData, onComplete, allowSkipAhead = false } = options

	// Validate that we have at least one step
	if (steps.length === 0) {
		throw new Error('Wizard must have at least one step')
	}

	// ─────────────────────────────────────────────────────────────
	// Core State
	// ─────────────────────────────────────────────────────────────

	// Form data accumulated across all steps
	let data = $state<T>({ ...initialData })

	// Current position in the wizard
	let currentStepIndex = $state(0)

	// Validation errors for the current step
	let errors = $state<Record<string, string>>({})

	// Track which steps have been visited
	let visitedSteps = $state(new Set<number>([0]))

	// Track which steps have been completed (passed validation)
	let completedSteps = $state(new Set<number>())

	// Submission state
	let isSubmitting = $state(false)

	// ─────────────────────────────────────────────────────────────
	// Derived State
	// ─────────────────────────────────────────────────────────────

	// Current step definition
	let currentStep = $derived(steps[currentStepIndex])

	// Position checks
	let isFirstStep = $derived(currentStepIndex === 0)
	let isLastStep = $derived(currentStepIndex === steps.length - 1)

	// Navigation availability
	let canGoBack = $derived(currentStepIndex > 0)

	let canGoForward = $derived.by(() => {
		// Can't go forward from last step
		if (isLastStep) return false

		// If skipping is allowed, always can go forward
		if (allowSkipAhead) return true

		// Otherwise, current step must be completed
		return completedSteps.has(currentStepIndex)
	})

	// Progress percentage (0-100)
	let progress = $derived(Math.round(((currentStepIndex + 1) / steps.length) * 100))

	// Whether current step has no errors
	let isValid = $derived(Object.keys(errors).length === 0)

	// ─────────────────────────────────────────────────────────────
	// Validation
	// ─────────────────────────────────────────────────────────────

	/**
	 * Runs validation for the current step.
	 */
	function runValidation(): ValidationResult {
		const validator = currentStep.validate

		// No validator means step is always valid
		if (!validator) {
			return { valid: true, errors: {} }
		}

		return validator(data as Record<string, unknown>)
	}

	// ─────────────────────────────────────────────────────────────
	// Context Object
	// ─────────────────────────────────────────────────────────────

	const context: WizardContext<T> = {
		// Reactive getters
		get data() {
			return data
		},
		get currentStepIndex() {
			return currentStepIndex
		},
		get currentStep() {
			return currentStep
		},
		get steps() {
			return steps
		},
		get errors() {
			return errors
		},
		get isValid() {
			return isValid
		},
		get isSubmitting() {
			return isSubmitting
		},
		get canGoBack() {
			return canGoBack
		},
		get canGoForward() {
			return canGoForward
		},
		get isFirstStep() {
			return isFirstStep
		},
		get isLastStep() {
			return isLastStep
		},
		get progress() {
			return progress
		},
		get visitedSteps() {
			return visitedSteps
		},
		get completedSteps() {
			return completedSteps
		},

		/**
		 * Updates a single field in the form data.
		 * Automatically clears any error for that field.
		 */
		setField(key, value) {
			data[key] = value

			// Clear error when field is edited
			const fieldKey = key as string
			if (errors[fieldKey]) {
				delete errors[fieldKey]
			}
		},

		/**
		 * Updates multiple fields at once.
		 */
		setFields(fields) {
			Object.assign(data, fields)

			// Clear errors for all changed fields
			for (const key of Object.keys(fields)) {
				if (errors[key]) {
					delete errors[key]
				}
			}
		},

		/**
		 * Validates the current step and updates errors.
		 */
		validate(): ValidationResult {
			const result = runValidation()
			errors = result.errors
			return result
		},

		/**
		 * Attempts to move to the next step.
		 * Validates current step first. Returns false if validation fails.
		 * On the last step, triggers onComplete callback.
		 */
		nextStep(): boolean {
			// Run validation
			const validation = this.validate()

			if (!validation.valid) {
				return false
			}

			// Mark current step as completed
			completedSteps.add(currentStepIndex)

			// If this is the last step, we're done
			if (isLastStep) {
				this.submit()
				return true
			}

			// Move to next step
			currentStepIndex++
			visitedSteps.add(currentStepIndex)

			// Clear errors for the new step
			errors = {}

			return true
		},

		/**
		 * Moves to the previous step.
		 * No validation required to go back.
		 */
		prevStep() {
			if (!canGoBack) return

			currentStepIndex--
			errors = {}
		},

		/**
		 * Jumps to a specific step by index.
		 * Going backward is always allowed.
		 * Going forward requires completed intermediate steps (unless allowSkipAhead).
		 */
		goToStep(index: number): boolean {
			// Validate index bounds
			if (index < 0 || index >= steps.length) {
				return false
			}

			// Same step - no action needed
			if (index === currentStepIndex) {
				return true
			}

			// Going backward is always allowed
			if (index < currentStepIndex) {
				currentStepIndex = index
				errors = {}
				return true
			}

			// Going forward - check permissions
			if (!allowSkipAhead) {
				// Must have completed all steps up to the target
				for (let i = currentStepIndex; i < index; i++) {
					if (!completedSteps.has(i)) {
						return false
					}
				}
			}

			// Jump to the step
			currentStepIndex = index
			visitedSteps.add(index)
			errors = {}

			return true
		},

		/**
		 * Sets a validation error for a specific field.
		 */
		setError(field: string, message: string) {
			errors[field] = message
		},

		/**
		 * Clears the error for a specific field.
		 */
		clearError(field: string) {
			delete errors[field]
		},

		/**
		 * Clears all validation errors.
		 */
		clearAllErrors() {
			errors = {}
		},

		/**
		 * Resets the wizard to its initial state.
		 */
		reset() {
			data = { ...initialData }
			currentStepIndex = 0
			errors = {}
			visitedSteps = new Set([0])
			completedSteps = new Set()
			isSubmitting = false
		},

		/**
		 * Submits the wizard (called when completing the last step).
		 */
		async submit(): Promise<void> {
			if (!onComplete) return

			isSubmitting = true

			try {
				await onComplete(data)
			} finally {
				isSubmitting = false
			}
		}
	}

	return setContext(WIZARD_KEY, context)
}

/**
 * Retrieves the wizard context.
 * Must be called from a component inside a Wizard.
 */
export function getWizardContext<T extends Record<string, unknown>>(): WizardContext<T> {
	if (!hasContext(WIZARD_KEY)) {
		throw new Error('Wizard context not found. ' + 'Ensure this component is inside a Wizard.')
	}
	return getContext(WIZARD_KEY)
}

/**
 * Checks if wizard context is available.
 */
export function hasWizardContext(): boolean {
	return hasContext(WIZARD_KEY)
}

Entendiendo la Lógica de Navegación

La navegación del wizard tiene restricciones intencionales:

Ir Hacia Atrás: Siempre permitido. Los usuarios nunca deben sentirse atrapados. Retroceder preserva todos los datos ingresados.

Ir Hacia Adelante: Requiere que el paso actual pase la validación. Esto evita que los usuarios omitan información requerida.

Saltar a Pasos: Por defecto, solo puedes saltar a pasos que hayas visitado o completado. La opción allowSkipAhead relaja esto para wizards donde el orden de los pasos no importa.

Limpiar Errores: Cuando un usuario edita un campo, su error se limpia inmediatamente. Esto proporciona retroalimentación instantánea de que el sistema reconoció su corrección.

Construyendo los Componentes del Wizard

Ahora construyamos los componentes de UI que crean la experiencia del wizard.

El Contenedor del Wizard

El envoltorio principal que provee el contexto y renderiza la estructura del wizard:

<!-- src/lib/wizard/Wizard.svelte -->
<script lang="ts" generics="T extends Record<string, unknown>">
	import { createWizardContext } from './wizard-context.svelte'
	import type { WizardStep } from './types'
	import type { Snippet } from 'svelte'

	interface Props {
		/** Step definitions */
		steps: WizardStep[]

		/** Initial form data */
		initialData: T

		/** Called when wizard completes */
		onComplete?: (data: T) => void | Promise<void>

		/** Allow jumping ahead to unvisited steps */
		allowSkipAhead?: boolean

		/** Child content (step components) */
		children: Snippet
	}

	let { steps, initialData, onComplete, allowSkipAhead = false, children }: Props = $props()

	// Create the wizard context
	const wizard = createWizardContext({
		steps,
		initialData,
		onComplete,
		allowSkipAhead
	})
</script>

<div class="wizard">
	<!-- Progress Bar -->
	<div
		class="wizard-progress"
		role="progressbar"
		aria-valuenow={wizard.progress}
		aria-valuemin="0"
		aria-valuemax="100"
	>
		<div class="progress-fill" style="width: {wizard.progress}%"></div>
	</div>

	<!-- Step Indicators -->
	<nav class="wizard-steps" aria-label="Form progress">
		<ol class="step-list">
			{#each wizard.steps as step, index}
				{@const isActive = index === wizard.currentStepIndex}
				{@const isCompleted = wizard.completedSteps.has(index)}
				{@const isVisited = wizard.visitedSteps.has(index)}
				{@const isClickable = isVisited || allowSkipAhead}

				<li class="step-item">
					<button
						type="button"
						class="step-button"
						class:active={isActive}
						class:completed={isCompleted}
						class:visited={isVisited}
						disabled={!isClickable}
						onclick={() => wizard.goToStep(index)}
						aria-current={isActive ? 'step' : undefined}
					>
						<span class="step-indicator">
							{#if isCompleted}
								<svg
									viewBox="0 0 24 24"
									fill="none"
									stroke="currentColor"
									stroke-width="3"
									aria-hidden="true"
								>
									<polyline points="20 6 9 17 4 12" />
								</svg>
							{:else}
								{index + 1}
							{/if}
						</span>
						<span class="step-label">{step.label}</span>
					</button>

					{#if index < wizard.steps.length - 1}
						<div class="step-connector" class:completed={isCompleted}></div>
					{/if}
				</li>
			{/each}
		</ol>
	</nav>

	<!-- Current Step Content -->
	<div class="wizard-content">
		<header class="step-header">
			<h2>{wizard.currentStep.label}</h2>
			{#if wizard.currentStep.description}
				<p>{wizard.currentStep.description}</p>
			{/if}
		</header>

		<div class="step-body">
			{@render children()}
		</div>
	</div>

	<!-- Navigation Buttons -->
	<footer class="wizard-footer">
		<button
			type="button"
			class="btn btn-secondary"
			onclick={() => wizard.prevStep()}
			disabled={wizard.isFirstStep || wizard.isSubmitting}
		>
			Back
		</button>

		<button
			type="button"
			class="btn btn-primary"
			onclick={() => wizard.nextStep()}
			disabled={wizard.isSubmitting}
		>
			{#if wizard.isSubmitting}
				<span class="spinner"></span>
				Processing...
			{:else if wizard.isLastStep}
				Complete
			{:else}
				Continue
			{/if}
		</button>
	</footer>
</div>

<style>
	.wizard {
		max-width: 600px;
		margin: 0 auto;
	}

	/* Progress Bar */
	.wizard-progress {
		height: 4px;
		background-color: var(--color-border, #e2e8f0);
		border-radius: 2px;
		overflow: hidden;
		margin-bottom: 2rem;
	}

	.progress-fill {
		height: 100%;
		background-color: var(--color-primary, #3b82f6);
		transition: width 0.3s ease;
	}

	/* Step Indicators */
	.wizard-steps {
		margin-bottom: 2rem;
	}

	.step-list {
		display: flex;
		justify-content: center;
		align-items: flex-start;
		list-style: none;
		padding: 0;
		margin: 0;
	}

	.step-item {
		display: flex;
		align-items: center;
	}

	.step-button {
		display: flex;
		flex-direction: column;
		align-items: center;
		gap: 0.5rem;
		padding: 0.5rem;
		border: none;
		background: transparent;
		cursor: pointer;
		transition: opacity 0.2s;
	}

	.step-button:disabled {
		cursor: not-allowed;
		opacity: 0.5;
	}

	.step-button:not(:disabled):hover .step-indicator {
		transform: scale(1.1);
	}

	.step-indicator {
		display: flex;
		align-items: center;
		justify-content: center;
		width: 40px;
		height: 40px;
		border-radius: 50%;
		background-color: var(--color-surface, #f1f5f9);
		color: var(--color-foreground-muted, #64748b);
		font-weight: 600;
		font-size: 0.875rem;
		transition: all 0.2s;
	}

	.step-button.active .step-indicator {
		background-color: var(--color-primary, #3b82f6);
		color: white;
	}

	.step-button.completed .step-indicator {
		background-color: var(--color-success, #16a34a);
		color: white;
	}

	.step-indicator svg {
		width: 20px;
		height: 20px;
	}

	.step-label {
		font-size: 0.75rem;
		font-weight: 500;
		color: var(--color-foreground-muted, #64748b);
		white-space: nowrap;
	}

	.step-button.active .step-label {
		color: var(--color-foreground, #1e293b);
	}

	.step-connector {
		width: 40px;
		height: 2px;
		background-color: var(--color-border, #e2e8f0);
		margin: 0 0.5rem;
		margin-bottom: 1.5rem;
		transition: background-color 0.2s;
	}

	.step-connector.completed {
		background-color: var(--color-success, #16a34a);
	}

	/* Content Area */
	.wizard-content {
		background-color: var(--color-surface, #f8fafc);
		border-radius: 12px;
		padding: 2rem;
		margin-bottom: 1.5rem;
	}

	.step-header {
		margin-bottom: 1.5rem;
		text-align: center;
	}

	.step-header h2 {
		margin: 0 0 0.5rem;
		font-size: 1.25rem;
		font-weight: 600;
	}

	.step-header p {
		margin: 0;
		color: var(--color-foreground-muted, #64748b);
		font-size: 0.9375rem;
	}

	.step-body {
		/* Step content styles are handled by step components */
	}

	/* Footer Navigation */
	.wizard-footer {
		display: flex;
		justify-content: space-between;
		gap: 1rem;
	}

	.btn {
		padding: 0.75rem 1.5rem;
		font-size: 0.9375rem;
		font-weight: 500;
		border-radius: 8px;
		cursor: pointer;
		display: inline-flex;
		align-items: center;
		justify-content: center;
		gap: 0.5rem;
		transition: all 0.2s;
	}

	.btn:disabled {
		opacity: 0.6;
		cursor: not-allowed;
	}

	.btn-primary {
		background-color: var(--color-primary, #3b82f6);
		color: white;
		border: none;
	}

	.btn-primary:hover:not(:disabled) {
		background-color: var(--color-primary-hover, #2563eb);
	}

	.btn-secondary {
		background-color: transparent;
		color: var(--color-foreground, #1e293b);
		border: 1px solid var(--color-border, #e2e8f0);
	}

	.btn-secondary:hover:not(:disabled) {
		background-color: var(--color-surface, #f1f5f9);
	}

	.spinner {
		width: 16px;
		height: 16px;
		border: 2px solid rgba(255, 255, 255, 0.3);
		border-top-color: white;
		border-radius: 50%;
		animation: spin 0.8s linear infinite;
	}

	@keyframes spin {
		to {
			transform: rotate(360deg);
		}
	}

	/* Responsive adjustments */
	@media (max-width: 480px) {
		.step-label {
			display: none;
		}

		.step-connector {
			margin-bottom: 0;
		}
	}
</style>

Componente de Campo de Formulario

Un envoltorio de campo reutilizable que muestra etiquetas y errores:

<!-- src/lib/wizard/WizardField.svelte -->
<script lang="ts">
	import { getWizardContext } from './wizard-context.svelte'
	import type { Snippet } from 'svelte'

	interface Props {
		/** Field name (must match a key in wizard data) */
		name: string

		/** Display label */
		label: string

		/** Whether field is required */
		required?: boolean

		/** Help text shown below the input */
		hint?: string

		/** Child content (the input element) */
		children: Snippet
	}

	let { name, label, required = false, hint, children }: Props = $props()

	const wizard = getWizardContext()

	// Check if this field has an error
	let error = $derived(wizard.errors[name])
	let hasError = $derived(!!error)

	// Generate IDs for accessibility
	let inputId = $derived(`wizard-field-${name}`)
	let errorId = $derived(`wizard-error-${name}`)
	let hintId = $derived(`wizard-hint-${name}`)
</script>

<div class="wizard-field" class:has-error={hasError}>
	<label for={inputId} class="field-label">
		{label}
		{#if required}
			<span class="required-mark" aria-hidden="true">*</span>
		{/if}
	</label>

	<div class="field-input">
		{@render children()}
	</div>

	{#if hint && !hasError}
		<p id={hintId} class="field-hint">{hint}</p>
	{/if}

	{#if hasError}
		<p id={errorId} class="field-error" role="alert">{error}</p>
	{/if}
</div>

<style>
	.wizard-field {
		margin-bottom: 1.25rem;
	}

	.field-label {
		display: block;
		margin-bottom: 0.5rem;
		font-size: 0.875rem;
		font-weight: 500;
		color: var(--color-foreground, #1e293b);
	}

	.required-mark {
		color: var(--color-error, #dc2626);
		margin-left: 0.25rem;
	}

	.field-input {
		/* Inputs should fill the container */
	}

	.field-input :global(input),
	.field-input :global(select),
	.field-input :global(textarea) {
		width: 100%;
		padding: 0.75rem 1rem;
		font-size: 0.9375rem;
		border: 1px solid var(--color-border, #e2e8f0);
		border-radius: 8px;
		background-color: white;
		transition:
			border-color 0.2s,
			box-shadow 0.2s;
	}

	.field-input :global(input:focus),
	.field-input :global(select:focus),
	.field-input :global(textarea:focus) {
		outline: none;
		border-color: var(--color-primary, #3b82f6);
		box-shadow: 0 0 0 3px var(--color-primary-ring, rgba(59, 130, 246, 0.2));
	}

	.has-error .field-input :global(input),
	.has-error .field-input :global(select),
	.has-error .field-input :global(textarea) {
		border-color: var(--color-error, #dc2626);
	}

	.has-error .field-input :global(input:focus),
	.has-error .field-input :global(select:focus),
	.has-error .field-input :global(textarea:focus) {
		box-shadow: 0 0 0 3px var(--color-error-ring, rgba(220, 38, 38, 0.2));
	}

	.field-hint {
		margin: 0.5rem 0 0;
		font-size: 0.8125rem;
		color: var(--color-foreground-muted, #64748b);
	}

	.field-error {
		margin: 0.5rem 0 0;
		font-size: 0.8125rem;
		color: var(--color-error, #dc2626);
	}
</style>

Construyendo un Ejemplo Completo

Unamos todo con un ejemplo de wizard de pago (checkout).

Definiendo Pasos y Validación

Primero, define la estructura de datos del formulario y las configuraciones de los pasos:

// src/routes/checkout/wizard-config.ts

import type { WizardStep } from '$lib/wizard/types'

/**
 * Shape of the checkout form data.
 */
export interface CheckoutData {
	// Personal info
	email: string
	firstName: string
	lastName: string
	phone: string

	// Shipping address
	address: string
	city: string
	state: string
	zipCode: string
	country: string

	// Payment
	cardName: string
	cardNumber: string
	expiry: string
	cvv: string

	// Preferences
	saveInfo: boolean
	newsletter: boolean
}

/**
 * Initial empty state for the form.
 */
export const initialData: CheckoutData = {
	email: '',
	firstName: '',
	lastName: '',
	phone: '',
	address: '',
	city: '',
	state: '',
	zipCode: '',
	country: 'US',
	cardName: '',
	cardNumber: '',
	expiry: '',
	cvv: '',
	saveInfo: false,
	newsletter: false
}

/**
 * Email validation regex.
 */
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

/**
 * Step definitions with validation.
 */
export const steps: WizardStep[] = [
	{
		id: 'personal',
		label: 'Personal Info',
		description: 'Tell us about yourself',
		validate: (data) => {
			const errors: Record<string, string> = {}

			if (!data.email) {
				errors.email = 'Email is required'
			} else if (!emailRegex.test(data.email as string)) {
				errors.email = 'Please enter a valid email'
			}

			if (!data.firstName) {
				errors.firstName = 'First name is required'
			}

			if (!data.lastName) {
				errors.lastName = 'Last name is required'
			}

			return {
				valid: Object.keys(errors).length === 0,
				errors
			}
		}
	},
	{
		id: 'shipping',
		label: 'Shipping',
		description: 'Where should we send your order?',
		validate: (data) => {
			const errors: Record<string, string> = {}

			if (!data.address) {
				errors.address = 'Address is required'
			}

			if (!data.city) {
				errors.city = 'City is required'
			}

			if (!data.state) {
				errors.state = 'State is required'
			}

			if (!data.zipCode) {
				errors.zipCode = 'ZIP code is required'
			} else if (!/^\d{5}(-\d{4})?$/.test(data.zipCode as string)) {
				errors.zipCode = 'Please enter a valid ZIP code'
			}

			return {
				valid: Object.keys(errors).length === 0,
				errors
			}
		}
	},
	{
		id: 'payment',
		label: 'Payment',
		description: 'Enter your payment details',
		validate: (data) => {
			const errors: Record<string, string> = {}

			if (!data.cardName) {
				errors.cardName = 'Name on card is required'
			}

			if (!data.cardNumber) {
				errors.cardNumber = 'Card number is required'
			} else {
				// Basic card number validation (remove spaces)
				const cardNum = (data.cardNumber as string).replace(/\s/g, '')
				if (!/^\d{13,19}$/.test(cardNum)) {
					errors.cardNumber = 'Please enter a valid card number'
				}
			}

			if (!data.expiry) {
				errors.expiry = 'Expiry date is required'
			} else if (!/^(0[1-9]|1[0-2])\/\d{2}$/.test(data.expiry as string)) {
				errors.expiry = 'Use MM/YY format'
			}

			if (!data.cvv) {
				errors.cvv = 'CVV is required'
			} else if (!/^\d{3,4}$/.test(data.cvv as string)) {
				errors.cvv = 'CVV must be 3-4 digits'
			}

			return {
				valid: Object.keys(errors).length === 0,
				errors
			}
		}
	},
	{
		id: 'review',
		label: 'Review',
		description: 'Confirm your order details'
		// No validation - just review
	}
]

Componentes de Paso

Crea componentes individuales para cada paso:

<!-- src/routes/checkout/PersonalInfoStep.svelte -->
<script lang="ts">
	import { getWizardContext } from '$lib/wizard/wizard-context.svelte'
	import WizardField from '$lib/wizard/WizardField.svelte'
	import type { CheckoutData } from './wizard-config'

	const wizard = getWizardContext<CheckoutData>()
</script>

<div class="step-form">
	<WizardField name="email" label="Email Address" required>
		<input
			type="email"
			id="wizard-field-email"
			value={wizard.data.email}
			oninput={(e) => wizard.setField('email', e.currentTarget.value)}
			placeholder="you@example.com"
			autocomplete="email"
		/>
	</WizardField>

	<div class="field-row">
		<WizardField name="firstName" label="First Name" required>
			<input
				type="text"
				id="wizard-field-firstName"
				value={wizard.data.firstName}
				oninput={(e) => wizard.setField('firstName', e.currentTarget.value)}
				autocomplete="given-name"
			/>
		</WizardField>

		<WizardField name="lastName" label="Last Name" required>
			<input
				type="text"
				id="wizard-field-lastName"
				value={wizard.data.lastName}
				oninput={(e) => wizard.setField('lastName', e.currentTarget.value)}
				autocomplete="family-name"
			/>
		</WizardField>
	</div>

	<WizardField name="phone" label="Phone Number" hint="Optional - for delivery updates">
		<input
			type="tel"
			id="wizard-field-phone"
			value={wizard.data.phone}
			oninput={(e) => wizard.setField('phone', e.currentTarget.value)}
			placeholder="(555) 123-4567"
			autocomplete="tel"
		/>
	</WizardField>
</div>

<style>
	.step-form {
		display: flex;
		flex-direction: column;
	}

	.field-row {
		display: grid;
		grid-template-columns: 1fr 1fr;
		gap: 1rem;
	}

	@media (max-width: 480px) {
		.field-row {
			grid-template-columns: 1fr;
		}
	}
</style>

<!-- src/routes/checkout/ShippingStep.svelte -->
<script lang="ts">
	import { getWizardContext } from '$lib/wizard/wizard-context.svelte'
	import WizardField from '$lib/wizard/WizardField.svelte'
	import type { CheckoutData } from './wizard-config'

	const wizard = getWizardContext<CheckoutData>()

	const states = [
		{ value: '', label: 'Select state' },
		{ value: 'CA', label: 'California' },
		{ value: 'NY', label: 'New York' },
		{ value: 'TX', label: 'Texas' }
		// ... more states
	]
</script>

<div class="step-form">
	<WizardField name="address" label="Street Address" required>
		<input
			type="text"
			id="wizard-field-address"
			value={wizard.data.address}
			oninput={(e) => wizard.setField('address', e.currentTarget.value)}
			placeholder="123 Main St"
			autocomplete="street-address"
		/>
	</WizardField>

	<div class="field-row">
		<WizardField name="city" label="City" required>
			<input
				type="text"
				id="wizard-field-city"
				value={wizard.data.city}
				oninput={(e) => wizard.setField('city', e.currentTarget.value)}
				autocomplete="address-level2"
			/>
		</WizardField>

		<WizardField name="state" label="State" required>
			<select
				id="wizard-field-state"
				value={wizard.data.state}
				onchange={(e) => wizard.setField('state', e.currentTarget.value)}
				autocomplete="address-level1"
			>
				{#each states as state}
					<option value={state.value}>{state.label}</option>
				{/each}
			</select>
		</WizardField>
	</div>

	<div class="field-row">
		<WizardField name="zipCode" label="ZIP Code" required>
			<input
				type="text"
				id="wizard-field-zipCode"
				value={wizard.data.zipCode}
				oninput={(e) => wizard.setField('zipCode', e.currentTarget.value)}
				placeholder="12345"
				autocomplete="postal-code"
			/>
		</WizardField>

		<WizardField name="country" label="Country">
			<select
				id="wizard-field-country"
				value={wizard.data.country}
				onchange={(e) => wizard.setField('country', e.currentTarget.value)}
				autocomplete="country"
			>
				<option value="US">United States</option>
				<option value="CA">Canada</option>
			</select>
		</WizardField>
	</div>
</div>

<style>
	.step-form {
		display: flex;
		flex-direction: column;
	}

	.field-row {
		display: grid;
		grid-template-columns: 1fr 1fr;
		gap: 1rem;
	}

	@media (max-width: 480px) {
		.field-row {
			grid-template-columns: 1fr;
		}
	}
</style>

<!-- src/routes/checkout/ReviewStep.svelte -->
<script lang="ts">
	import { getWizardContext } from '$lib/wizard/wizard-context.svelte'
	import type { CheckoutData } from './wizard-config'

	const wizard = getWizardContext<CheckoutData>()

	// Mask card number for display
	let maskedCard = $derived(
		wizard.data.cardNumber ? '•••• •••• •••• ' + wizard.data.cardNumber.slice(-4) : ''
	)
</script>

<div class="review-step">
	<section class="review-section">
		<header class="section-header">
			<h3>Personal Information</h3>
			<button type="button" class="edit-btn" onclick={() => wizard.goToStep(0)}> Edit </button>
		</header>
		<dl class="review-list">
			<div>
				<dt>Name</dt>
				<dd>{wizard.data.firstName} {wizard.data.lastName}</dd>
			</div>
			<div>
				<dt>Email</dt>
				<dd>{wizard.data.email}</dd>
			</div>
			{#if wizard.data.phone}
				<div>
					<dt>Phone</dt>
					<dd>{wizard.data.phone}</dd>
				</div>
			{/if}
		</dl>
	</section>

	<section class="review-section">
		<header class="section-header">
			<h3>Shipping Address</h3>
			<button type="button" class="edit-btn" onclick={() => wizard.goToStep(1)}> Edit </button>
		</header>
		<address class="shipping-address">
			{wizard.data.address}<br />
			{wizard.data.city}, {wizard.data.state}
			{wizard.data.zipCode}<br />
			{wizard.data.country === 'US' ? 'United States' : 'Canada'}
		</address>
	</section>

	<section class="review-section">
		<header class="section-header">
			<h3>Payment Method</h3>
			<button type="button" class="edit-btn" onclick={() => wizard.goToStep(2)}> Edit </button>
		</header>
		<dl class="review-list">
			<div>
				<dt>Card</dt>
				<dd>{maskedCard}</dd>
			</div>
			<div>
				<dt>Name on Card</dt>
				<dd>{wizard.data.cardName}</dd>
			</div>
		</dl>
	</section>

	<div class="preferences">
		<label class="checkbox-label">
			<input
				type="checkbox"
				checked={wizard.data.saveInfo}
				onchange={(e) => wizard.setField('saveInfo', e.currentTarget.checked)}
			/>
			<span>Save my information for faster checkout next time</span>
		</label>

		<label class="checkbox-label">
			<input
				type="checkbox"
				checked={wizard.data.newsletter}
				onchange={(e) => wizard.setField('newsletter', e.currentTarget.checked)}
			/>
			<span>Subscribe to our newsletter for updates and offers</span>
		</label>
	</div>
</div>

<style>
	.review-step {
		display: flex;
		flex-direction: column;
		gap: 1.5rem;
	}

	.review-section {
		padding: 1rem;
		background: white;
		border-radius: 8px;
		border: 1px solid var(--color-border, #e2e8f0);
	}

	.section-header {
		display: flex;
		justify-content: space-between;
		align-items: center;
		margin-bottom: 0.75rem;
	}

	.section-header h3 {
		margin: 0;
		font-size: 0.9375rem;
		font-weight: 600;
	}

	.edit-btn {
		padding: 0.25rem 0.75rem;
		font-size: 0.8125rem;
		color: var(--color-primary, #3b82f6);
		background: transparent;
		border: 1px solid var(--color-primary, #3b82f6);
		border-radius: 4px;
		cursor: pointer;
		transition: all 0.2s;
	}

	.edit-btn:hover {
		background: var(--color-primary, #3b82f6);
		color: white;
	}

	.review-list {
		margin: 0;
		display: flex;
		flex-direction: column;
		gap: 0.5rem;
	}

	.review-list > div {
		display: flex;
		gap: 1rem;
	}

	.review-list dt {
		width: 100px;
		color: var(--color-foreground-muted, #64748b);
		font-size: 0.875rem;
	}

	.review-list dd {
		margin: 0;
		font-size: 0.875rem;
	}

	.shipping-address {
		font-style: normal;
		font-size: 0.875rem;
		line-height: 1.6;
	}

	.preferences {
		display: flex;
		flex-direction: column;
		gap: 0.75rem;
		padding-top: 0.5rem;
	}

	.checkbox-label {
		display: flex;
		align-items: flex-start;
		gap: 0.625rem;
		font-size: 0.875rem;
		cursor: pointer;
	}

	.checkbox-label input {
		margin-top: 0.125rem;
	}
</style>

La Página de Checkout

Finalmente, ensambla todo en la página:

<!-- src/routes/checkout/+page.svelte -->
<script lang="ts">
	import { goto } from '$app/navigation'
	import Wizard from '$lib/wizard/Wizard.svelte'
	import { getWizardContext } from '$lib/wizard/wizard-context.svelte'
	import { steps, initialData, type CheckoutData } from './wizard-config'

	import PersonalInfoStep from './PersonalInfoStep.svelte'
	import ShippingStep from './ShippingStep.svelte'
	import PaymentStep from './PaymentStep.svelte'
	import ReviewStep from './ReviewStep.svelte'

	/**
	 * Handles form submission when wizard completes.
	 */
	async function handleComplete(data: CheckoutData) {
		// Submit order to your backend
		const response = await fetch('/api/orders', {
			method: 'POST',
			headers: { 'Content-Type': 'application/json' },
			body: JSON.stringify(data)
		})

		if (!response.ok) {
			throw new Error('Failed to create order')
		}

		const order = await response.json()

		// Redirect to confirmation page
		goto(`/orders/${order.id}/confirmation`)
	}
</script>

<svelte:head>
	<title>Checkout | YourStore</title>
</svelte:head>

<main class="checkout-page">
	<h1>Checkout</h1>

	<Wizard {steps} {initialData} onComplete={handleComplete}>
		{#snippet children()}
			{@const wizard = getWizardContext<CheckoutData>()}

			{#if wizard.currentStep.id === 'personal'}
				<PersonalInfoStep />
			{:else if wizard.currentStep.id === 'shipping'}
				<ShippingStep />
			{:else if wizard.currentStep.id === 'payment'}
				<PaymentStep />
			{:else if wizard.currentStep.id === 'review'}
				<ReviewStep />
			{/if}
		{/snippet}
	</Wizard>
</main>

<style>
	.checkout-page {
		max-width: 700px;
		margin: 0 auto;
		padding: 2rem;
	}

	h1 {
		text-align: center;
		margin-bottom: 2rem;
		font-size: 1.75rem;
	}
</style>

Conclusión

El asistente de formulario multipaso demuestra el contexto en su máxima expresión de orquestación. Un wizard no es simplemente un formulario dividido en partes—es un sistema coordinado donde múltiples componentes comparten estado, las compuertas de validación controlan el avance y el seguimiento del progreso informa tanto la navegación como la interfaz de usuario. El contexto provee la memoria compartida que hace posible esta coordinación sin necesidad de pasar datos a través de jerarquías de componentes.

El tipado genérico merece atención. Al parametrizar el contexto del wizard con <T extends Record<string, unknown>>, TypeScript sabe exactamente qué campos existen en los datos de tu formulario. Cuando llamas a wizard.setField('email', value), TypeScript verifica que email existe en tu tipo de datos. Cuando accedes a wizard.data.cardNumber, TypeScript sabe que es un string. Esta seguridad en tiempo de compilación detecta categorías enteras de errores que de otro modo aparecerían en tiempo de ejecución.

Lo que hace reutilizable a este wizard es la separación entre orquestación y contenido. El componente Wizard maneja la navegación, las compuertas de validación, el seguimiento del progreso y el envío—preocupaciones que son las mismas para todo wizard. Los componentes de paso manejan únicamente sus campos específicos, leyendo y escribiendo en el contexto compartido. Para crear un nuevo wizard, defines tu tipo de datos, escribes configuraciones de pasos con validadores, creas componentes de paso que renderizan campos y los ensamblas en el contenedor Wizard. El patrón escala desde formularios simples de tres pasos hasta flujos complejos con ramificaciones y pasos condicionales.

Puntos Clave

Construir un asistente de formulario multipaso con contexto demuestra varios patrones importantes:

Gestión de Estado Centralizada: El contexto del wizard almacena todos los datos del formulario, haciéndolos accesibles a cualquier componente de paso sin prop drilling. Cada paso lee y escribe en el mismo estado compartido.

Compuertas de Validación: La función nextStep valida el paso actual antes de permitir el avance. Esto garantiza que los usuarios proporcionen la información requerida antes de continuar.

Estado de Navegación Derivado: Propiedades como canGoBack, canGoForward y progress se calculan a partir del estado actual. Los componentes no necesitan calcularlas por sí mismos.

Renderizado Flexible de Pasos: El contenedor del wizard maneja la navegación y el progreso mientras los componentes de paso se enfocan únicamente en sus campos. Esta separación facilita agregar, eliminar o reordenar pasos.

Seguimiento de Progreso: Los conjuntos visitedSteps y completedSteps habilitan una navegación inteligente. Los usuarios pueden volver a pasos completados pero no pueden saltarse pasos no visitados.

El mismo patrón funciona para cualquier flujo multipaso: secuencias de incorporación (onboarding), formularios de registro, encuestas, wizards de configuración o cualquier proceso que se beneficie de pasos discretos. Domina este patrón y manejarás recorridos de usuario complejos con facilidad.

¿Qué Sigue?

Escala hacia la complejidad empresarial en SaaS Multi-Tenant con Contexto, construyendo una aplicación en producción con inquilinos basados en subdominios, temas por capas y feature flags.

Ver También

Recursos de formularios

SvelteKit Form Actions — Manejo de formularios del lado del servidor
Progressive Enhancement — Formularios que funcionan sin JS