Multi-Step Form Wizard con Validación de Esquemas Zod

Los flujos de registro empresarial, configuración de proyectos o checkouts complejos suelen dividirse en múltiples pasos para no saturar al usuario. Sin embargo, un desafío crítico es asegurar que cada paso valide sus campos de forma estricta antes de permitir avanzar, evitando estados inválidos en la base de datos.

Esta receta enseña a orquestar PxFormWizard en conjunto con Zod para una validación robusta y tipada por cada etapa del formulario.

---

Demostración Interactiva

Prueba avanzar sin completar los campos requeridos: PxFormWizard detendrá la navegación, mostrará una alerta descriptiva y focalizará el error. Al completar el último paso, se capturará el payload final.

Wizard de Registro con Validación por Paso

Nombre Completo *

Correo Corporativo *

<script setup lang="ts">
import { ref } from 'vue'
import { PxFormWizard, type WizardStep } from 'praxis-vue-ui'
import { z } from 'zod'

// 1. Definición de Esquemas Zod por Paso
const accountSchema = z.object({
  fullName: z.string().min(3, 'El nombre debe tener al menos 3 caracteres'),
  email: z.string().email('Ingresa un correo electrónico corporativo válido')
})

const companySchema = z.object({
  orgName: z.string().min(2, 'El nombre de la empresa es obligatorio'),
  role: z.string().min(1, 'Selecciona tu cargo')
})

// 2. Estado reactivo del formulario completo
const formState = ref({
  fullName: '',
  email: '',
  orgName: '',
  role: '',
  plan: 'pro'
})

// 3. Configuración de Pasos con Validación Zod
const steps: WizardStep[] = [
  {
    id: 'account',
    title: 'Información Personal',
    description: 'Credenciales de acceso',
    schema: [
      { key: 'fullName', label: 'Nombre Completo', type: 'text', required: true },
      { key: 'email', label: 'Correo Corporativo', type: 'text', required: true }
    ],
    // Validador utilizando el schema Zod
    validate: (data) => {
      const result = accountSchema.safeParse(data)
      if (!result.success) {
        return result.error.issues[0]?.message || 'Error en los datos de cuenta'
      }
      return true
    }
  },
  {
    id: 'company',
    title: 'Organización & Rol',
    description: 'Detalles del espacio de trabajo',
    schema: [
      { key: 'orgName', label: 'Organización', type: 'text', required: true },
      {
        key: 'role',
        label: 'Cargo',
        type: 'select',
        options: [
          { label: 'Engineering', value: 'eng' },
          { label: 'Product & Design', value: 'design' },
          { label: 'Management', value: 'exec' }
        ]
      }
    ],
    validate: (data) => {
      const result = companySchema.safeParse(data)
      if (!result.success) {
        return result.error.issues[0]?.message || 'Error en datos corporativos'
      }
      return true
    }
  },
  {
    id: 'plan',
    title: 'Plan & Resumen',
    description: 'Selección de suscripción',
    schema: [
      {
        key: 'plan',
        label: 'Plan',
        type: 'select',
        options: [
          { label: 'Starter', value: 'free' },
          { label: 'Pro ($29/mes)', value: 'pro' }
        ]
      }
    ]
  }
]

async function onWizardComplete(finalPayload: typeof formState.value) {
  console.log('Enviando payload al backend:', finalPayload)
  // Envío a la API: await api.post('/register', finalPayload)
}
</script>

<template>
  <PxFormWizard
    v-model="formState"
    :steps="steps"
    next-label="Continuar"
    previous-label="Atrás"
    complete-label="Finalizar Registro"
    @complete="onWizardComplete"
  />
</template>

---

Patrones y Buenas Prácticas

1. safeParse en lugar de parse

Al validar formularios reactivos, evita que Zod arroje excepciones no controladas (throw). Utiliza safeParse():

const result = accountSchema.safeParse(data)
if (!result.success) {
  // Retorna el primer mensaje de error para mostrar al usuario
  return result.error.issues[0]?.message
}
return true

2. Guardado de Progreso en localStorage

Para evitar frustraciones si el usuario recarga la página por accidente o pierde la conexión, puedes sincronizar el modelo del Wizard con useStorage de @vueuse/core:

import { useStorage } from '@vueuse/core'

const formState = useStorage('praxis_onboarding_draft', {
  fullName: '',
  email: '',
  orgName: '',
  role: '',
  plan: 'pro'
})

// Al completar con éxito, limpias el borrador:
function onWizardComplete() {
  localStorage.removeItem('praxis_onboarding_draft')
}

3. Validación Asíncrona (Unicidad de Usuario o Subdominio)

Si requieres verificar si un nombre de usuario o subdominio ya existe en el servidor antes de permitir pasar al paso 2, la función validate de cada paso puede ser asíncrona:

validate: async (data) => {
  const isAvailable = await checkOrgAvailability(data.orgName)
  if (!isAvailable) {
    return 'Este nombre de organización ya se encuentra en uso'
  }
  return true
}