System Design #12: Design a Multi-Step Form Wizard

type WizardState = 
  | { status: 'filling'; currentStep: string; direction: 'forward' | 'backward' }
  | { status: 'validating'; currentStep: string }
  | { status: 'submitting' }
  | { status: 'success'; result: SubmissionResult }
  | { status: 'error'; error: string; lastStep: string };

type WizardAction =
  | { type: 'NEXT' }
  | { type: 'PREVIOUS' }
  | { type: 'JUMP_TO'; step: string }
  | { type: 'VALIDATION_SUCCESS' }
  | { type: 'VALIDATION_FAILURE'; errors: Record<string, string> }
  | { type: 'SUBMIT' }
  | { type: 'SUBMIT_SUCCESS'; result: SubmissionResult }
  | { type: 'SUBMIT_FAILURE'; error: string }
  | { type: 'SAVE_DRAFT' };

// Steps aren't always linear — they form a directed graph
interface StepDefinition {
  id: string;
  title: string;
  component: React.LazyExoticComponent<any>;
  schema: z.ZodSchema;          // Validation schema for this step
  next: (data: FormData) => string | null; // Dynamic next step
  canSkip?: boolean;
  isVisible?: (data: FormData) => boolean; // Conditional visibility
}

const steps: StepDefinition[] = [
  {
    id: 'personal-info',
    title: 'Personal Info',
    component: lazy(() => import('./steps/PersonalInfo')),
    schema: personalInfoSchema,
    next: () => 'address',
  },
  {
    id: 'address',
    title: 'Address',
    component: lazy(() => import('./steps/Address')),
    schema: addressSchema,
    next: (data) => data.needsBilling ? 'billing' : 'review', // Conditional!
  },
  {
    id: 'billing',
    title: 'Billing',
    component: lazy(() => import('./steps/Billing')),
    schema: billingSchema,
    isVisible: (data) => data.needsBilling === true, // Only show if needed
    next: () => 'review',
  },
  {
    id: 'review',
    title: 'Review',
    component: lazy(() => import('./steps/Review')),
    schema: z.object({}), // No validation on review step
    next: () => null,     // Final step
  },
];

interface WizardFormState {
  // Step data — keyed by step ID
  data: Record<string, Record<string, any>>;
  
  // Meta
  currentStepId: string;
  visitedSteps: Set<string>;      // Track which steps user has been to
  completedSteps: Set<string>;    // Steps that passed validation
  errors: Record<string, Record<string, string>>; // stepId → field → error
  
  // Persistence
  draftId: string | null;         // Server-side draft ID
  lastSavedAt: string | null;
  isDirty: boolean;               // Has unsaved changes
  
  // Files (handled separately from JSON data)
  files: Record<string, File[]>; // stepId → uploaded files
}

// Persist to sessionStorage for crash recovery
function usePersistentWizard(wizardId: string) {
  const STORAGE_KEY = `wizard-${wizardId}`;
  
  const [state, dispatch] = useReducer(wizardReducer, null, () => {
    const saved = sessionStorage.getItem(STORAGE_KEY);
    return saved ? JSON.parse(saved) : createInitialState();
  });
  
  // Auto-save on every state change
  useEffect(() => {
    sessionStorage.setItem(STORAGE_KEY, JSON.stringify({
      data: state.data,
      currentStepId: state.currentStepId,
      visitedSteps: [...state.visitedSteps],
      completedSteps: [...state.completedSteps],
    }));
  }, [state]);
  
  // Clear on successful submission
  const clearDraft = () => sessionStorage.removeItem(STORAGE_KEY);
  
  return { state, dispatch, clearDraft };
}

import { z } from 'zod';

// Per-step schemas
const personalInfoSchema = z.object({
  firstName: z.string().min(1, 'Required'),
  lastName: z.string().min(1, 'Required'),
  email: z.string().email('Invalid email'),
  phone: z.string().regex(/^\+?[1-9]\d{7,14}$/, 'Invalid phone').optional(),
});

const addressSchema = z.object({
  street: z.string().min(1, 'Required'),
  city: z.string().min(1, 'Required'),
  state: z.string().min(1, 'Required'),
  zip: z.string().min(5, 'Invalid zip code'),
  country: z.string().min(1, 'Required'),
  needsBilling: z.boolean(),
});

// Cross-step validation (runs before final submission)
const fullFormSchema = z.object({
  personalInfo: personalInfoSchema,
  address: addressSchema,
  billing: billingSchema.optional(),
}).refine(
  (data) => !(data.address.needsBilling && !data.billing),
  { message: 'Billing information required', path: ['billing'] }
);

// Async validation (debounced)
async function validateEmailUnique(email: string): Promise<string | null> {
  const { exists } = await api.get(`/check-email?email=${email}`);
  return exists ? 'Email already registered' : null;
}