Build a Multi-Step Form Wizard with Validation

// src/forms/onboarding-schema.ts
import { z } from 'zod';

// Each step has its own Zod schema
export const companyInfoSchema = z.object({
  companyName: z.string().min(2, 'Company name is required').max(100),
  industry: z.enum(['saas', 'ecommerce', 'fintech', 'healthcare', 'education', 'other']),
  companySize: z.enum(['1-10', '11-50', '51-200', '201-1000', '1000+']),
  website: z.string().url('Enter a valid URL').optional().or(z.literal('')),
  country: z.string().min(2, 'Select a country'),
});

export const billingSchema = z.object({
  plan: z.enum(['starter', 'pro', 'enterprise']),
  billingCycle: z.enum(['monthly', 'annual']),
  paymentMethod: z.enum(['card', 'invoice']),
  // Conditional: only if paymentMethod === 'card'
  cardholderName: z.string().optional(),
  taxId: z.string().optional(),
});

export const teamSchema = z.object({
  teamName: z.string().min(1, 'Team name required').max(50),
  inviteEmails: z.array(z.string().email()).max(20).default([]),
  defaultRole: z.enum(['admin', 'editor', 'viewer']).default('editor'),
});

export const integrationsSchema = z.object({
  selectedIntegrations: z.array(z.enum([
    'slack', 'github', 'jira', 'notion', 'linear', 'google-drive', 'none',
  ])).min(1, 'Select at least one option'),
  // Conditional fields based on selections
  slackWorkspace: z.string().optional(),
  githubOrg: z.string().optional(),
});

export const preferencesSchema = z.object({
  timezone: z.string(),
  dateFormat: z.enum(['MM/DD/YYYY', 'DD/MM/YYYY', 'YYYY-MM-DD']).default('YYYY-MM-DD'),
  weekStart: z.enum(['monday', 'sunday']).default('monday'),
  emailNotifications: z.boolean().default(true),
  productUpdates: z.boolean().default(false),
});

// Combined schema for the complete form
export const onboardingSchema = z.object({
  companyInfo: companyInfoSchema,
  billing: billingSchema,
  team: teamSchema,
  integrations: integrationsSchema,
  preferences: preferencesSchema,
});

export type OnboardingData = z.infer<typeof onboardingSchema>;

// Step definitions with metadata
export const steps = [
  { id: 'company', title: 'Company Info', schema: companyInfoSchema, key: 'companyInfo' as const },
  { id: 'billing', title: 'Billing', schema: billingSchema, key: 'billing' as const },
  { id: 'team', title: 'Your Team', schema: teamSchema, key: 'team' as const },
  { id: 'integrations', title: 'Integrations', schema: integrationsSchema, key: 'integrations' as const },
  { id: 'preferences', title: 'Preferences', schema: preferencesSchema, key: 'preferences' as const },
] as const;

// src/forms/use-wizard-form.ts
import { useState, useEffect, useCallback } from 'react';
import { z } from 'zod';

interface WizardStep<T extends z.ZodTypeAny> {
  id: string;
  title: string;
  schema: T;
  key: string;
}

export function useWizardForm<T extends Record<string, any>>(
  steps: readonly WizardStep<any>[],
  options: {
    storageKey: string;
    onComplete: (data: T) => Promise<void>;
    onStepChange?: (step: number, data: Partial<T>) => void;
  }
) {
  const [currentStep, setCurrentStep] = useState(0);
  const [formData, setFormData] = useState<Partial<T>>({});
  const [errors, setErrors] = useState<Record<string, string[]>>({});
  const [isSubmitting, setIsSubmitting] = useState(false);

  // Restore progress from localStorage
  useEffect(() => {
    const saved = localStorage.getItem(options.storageKey);
    if (saved) {
      try {
        const { step, data } = JSON.parse(saved);
        setCurrentStep(step);
        setFormData(data);
      } catch {}
    }
  }, []);

  // Save progress on every change
  const saveProgress = useCallback((step: number, data: Partial<T>) => {
    localStorage.setItem(options.storageKey, JSON.stringify({ step, data }));
  }, []);

  const validateStep = useCallback((stepIndex: number, data: any): boolean => {
    const step = steps[stepIndex];
    const result = step.schema.safeParse(data);
    if (!result.success) {
      const fieldErrors: Record<string, string[]> = {};
      for (const issue of result.error.issues) {
        const path = issue.path.join('.');
        fieldErrors[path] = fieldErrors[path] ?? [];
        fieldErrors[path].push(issue.message);
      }
      setErrors(fieldErrors);
      return false;
    }
    setErrors({});
    return true;
  }, [steps]);

  const nextStep = useCallback((stepData: any) => {
    if (!validateStep(currentStep, stepData)) return false;

    const step = steps[currentStep];
    const newData = { ...formData, [step.key]: stepData };
    setFormData(newData);

    if (currentStep < steps.length - 1) {
      const next = currentStep + 1;
      setCurrentStep(next);
      saveProgress(next, newData);
      options.onStepChange?.(next, newData);
    }
    return true;
  }, [currentStep, formData, steps]);

  const prevStep = useCallback(() => {
    if (currentStep > 0) {
      setCurrentStep(currentStep - 1);
      setErrors({});
    }
  }, [currentStep]);

  const submit = useCallback(async (lastStepData: any) => {
    if (!validateStep(currentStep, lastStepData)) return;

    const step = steps[currentStep];
    const completeData = { ...formData, [step.key]: lastStepData } as T;

    setIsSubmitting(true);
    try {
      await options.onComplete(completeData);
      localStorage.removeItem(options.storageKey);
    } finally {
      setIsSubmitting(false);
    }
  }, [currentStep, formData]);

  return {
    currentStep,
    totalSteps: steps.length,
    stepConfig: steps[currentStep],
    formData,
    errors,
    isSubmitting,
    isFirstStep: currentStep === 0,
    isLastStep: currentStep === steps.length - 1,
    progress: ((currentStep + 1) / steps.length) * 100,
    nextStep,
    prevStep,
    submit,
    goToStep: (step: number) => { if (step <= currentStep) setCurrentStep(step); },
  };
}

// src/forms/analytics.ts
export function trackFormAnalytics(
  formId: string,
  event: 'step_viewed' | 'step_completed' | 'step_error' | 'form_completed' | 'form_abandoned',
  data: {
    step: number;
    stepName: string;
    timeOnStepMs?: number;
    errors?: string[];
    totalTimeMs?: number;
  }
): void {
  // Send to analytics service
  fetch('/api/analytics/form-events', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      formId,
      event,
      ...data,
      timestamp: new Date().toISOString(),
    }),
    keepalive: true, // ensure delivery on page close
  }).catch(() => {});
}

// Dashboard query: funnel analysis per step
// SELECT step_name, COUNT(DISTINCT session_id) as started,
//        COUNT(DISTINCT session_id) FILTER (WHERE event = 'step_completed') as completed
// FROM form_events WHERE form_id = 'onboarding'
// GROUP BY step_name ORDER BY step;