Stepper

<!-- Horizontal stepper -->
<nav aria-label="Registration progress">
  <ol class="stepper" role="list">
    <li class="step step--completed">
      <span class="step__indicator" aria-hidden="true">
        <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor"><path d="M13.485 3.929a1 1 0 010 1.414l-6.364 6.364a1 1 0 01-1.414 0L3.05 9.05a1 1 0 111.414-1.414l2.121 2.121 5.657-5.657a1 1 0 011.414 0z"/></svg>
      </span>
      <span class="step__label">Account</span>
      <span class="sr-only">, completed</span>
    </li>
    <li class="step step--active" aria-current="step">
      <span class="step__indicator" aria-hidden="true">2</span>
      <span class="step__label">Personal Info</span>
      <span class="sr-only">, current step</span>
    </li>
    <li class="step step--upcoming">
      <span class="step__indicator" aria-hidden="true">3</span>
      <span class="step__label">Preferences</span>
      <span class="sr-only">, upcoming</span>
    </li>
    <li class="step step--upcoming">
      <span class="step__indicator" aria-hidden="true">4</span>
      <span class="step__label">Review</span>
      <span class="sr-only">, upcoming</span>
    </li>
  </ol>
</nav>

<!-- Live region for step announcements -->
<div role="status" aria-live="polite" class="sr-only" id="stepper-status">
  Step 2 of 4: Personal Info
</div>

<!-- Step content panel -->
<div class="step-content" role="region" aria-label="Personal Info">
  <form>
    <div class="form-field">
      <label for="firstName">First Name</label>
      <input type="text" id="firstName" required />
    </div>
    <div class="form-field">
      <label for="lastName">Last Name</label>
      <input type="text" id="lastName" required />
    </div>
  </form>
  <div class="step-actions">
    <button type="button" class="btn btn--secondary" onclick="goToPrevStep()">Back</button>
    <button type="button" class="btn btn--primary" onclick="goToNextStep()">Continue</button>
  </div>
</div>

<style>
.stepper {
  display: flex;
  list-style: none;
  padding: 0;
  margin: 0 0 32px;
  counter-reset: step;
}
.step {
  flex: 1;
  display: flex;
  flex-direction: column;
  align-items: center;
  position: relative;
  text-align: center;
}
.step:not(:last-child)::after {
  content: '';
  position: absolute;
  top: 16px;
  left: calc(50% + 20px);
  width: calc(100% - 40px);
  height: 2px;
  background: #d1d5db;
}
.step--completed:not(:last-child)::after {
  background: var(--color-brand, #6366f1);
}
.step__indicator {
  width: 32px;
  height: 32px;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 0.875rem;
  font-weight: 600;
  position: relative;
  z-index: 1;
  background: #f3f4f6;
  color: #6b7280;
}
.step--completed .step__indicator {
  background: var(--color-brand, #6366f1);
  color: #fff;
}
.step--active .step__indicator {
  background: var(--color-brand, #6366f1);
  color: #fff;
  box-shadow: 0 0 0 4px rgba(99, 102, 241, 0.2);
}
.step__label {
  margin-top: 8px;
  font-size: 0.875rem;
  color: #6b7280;
}
.step--active .step__label {
  color: #111827;
  font-weight: 500;
}
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  border: 0;
}
</style>

import React, { useState, useCallback } from 'react';

interface StepConfig {
  label: string;
  description?: string;
  optional?: boolean;
  icon?: React.ReactNode;
  validate?: () => boolean | Promise<boolean>;
  content: React.ReactNode;
}

interface StepperProps {
  steps: StepConfig[];
  orientation?: 'horizontal' | 'vertical';
  linear?: boolean;
  onComplete?: () => void;
  className?: string;
}

function Stepper({
  steps,
  orientation = 'horizontal',
  linear = true,
  onComplete,
  className,
}: StepperProps) {
  const [activeStep, setActiveStep] = useState(0);
  const [completedSteps, setCompletedSteps] = useState<Set<number>>(new Set());
  const [errorSteps, setErrorSteps] = useState<Set<number>>(new Set());
  const [statusMessage, setStatusMessage] = useState(`Step 1 of ${steps.length}: ${steps[0].label}`);

  const goToStep = useCallback((index: number) => {
    if (linear && index > activeStep && !completedSteps.has(activeStep)) return;
    if (index < 0 || index >= steps.length) return;
    setActiveStep(index);
    setStatusMessage(`Step ${index + 1} of ${steps.length}: ${steps[index].label}`);
  }, [linear, activeStep, completedSteps, steps]);

  const handleNext = useCallback(async () => {
    const step = steps[activeStep];
    if (step.validate) {
      const isValid = await step.validate();
      if (!isValid) {
        setErrorSteps(prev => new Set(prev).add(activeStep));
        setStatusMessage(`Error on step ${activeStep + 1}: ${step.label}. Please fix errors before continuing.`);
        return;
      }
    }
    setErrorSteps(prev => { const next = new Set(prev); next.delete(activeStep); return next; });
    setCompletedSteps(prev => new Set(prev).add(activeStep));

    if (activeStep === steps.length - 1) {
      onComplete?.();
      setStatusMessage('All steps completed.');
    } else {
      goToStep(activeStep + 1);
    }
  }, [activeStep, steps, goToStep, onComplete]);

  const handleBack = useCallback(() => {
    goToStep(activeStep - 1);
  }, [activeStep, goToStep]);

  const getStepState = (index: number) => {
    if (errorSteps.has(index)) return 'error';
    if (completedSteps.has(index)) return 'completed';
    if (index === activeStep) return 'active';
    return 'upcoming';
  };

  const isHorizontal = orientation === 'horizontal';

  return (
    <div className={className}>
      <nav aria-label="Form progress">
        <ol
          role="list"
          style={{
            display: 'flex',
            flexDirection: isHorizontal ? 'row' : 'column',
            listStyle: 'none',
            padding: 0,
            margin: '0 0 32px',
            gap: isHorizontal ? 0 : 8,
          }}
        >
          {steps.map((step, i) => {
            const state = getStepState(i);
            const isClickable = !linear || completedSteps.has(i) || i === activeStep;
            return (
              <li
                key={i}
                style={{ flex: isHorizontal ? 1 : undefined, textAlign: isHorizontal ? 'center' : 'left' }}
                aria-current={state === 'active' ? 'step' : undefined}
              >
                <button
                  type="button"
                  onClick={() => isClickable && goToStep(i)}
                  disabled={!isClickable}
                  aria-label={`Step ${i + 1}: ${step.label}, ${state}`}
                  style={{
                    display: 'flex',
                    flexDirection: isHorizontal ? 'column' : 'row',
                    alignItems: 'center',
                    gap: 8,
                    background: 'none',
                    border: 'none',
                    cursor: isClickable ? 'pointer' : 'default',
                    padding: 0,
                    width: '100%',
                    opacity: state === 'upcoming' ? 0.5 : 1,
                  }}
                >
                  <span
                    style={{
                      width: 32,
                      height: 32,
                      borderRadius: '50%',
                      display: 'flex',
                      alignItems: 'center',
                      justifyContent: 'center',
                      fontSize: '0.875rem',
                      fontWeight: 600,
                      background: state === 'active' || state === 'completed' ? '#6366f1'
                        : state === 'error' ? '#ef4444' : '#f3f4f6',
                      color: state === 'active' || state === 'completed' || state === 'error' ? '#fff' : '#6b7280',
                      flexShrink: 0,
                    }}
                  >
                    {state === 'completed' ? '✓' : state === 'error' ? '!' : i + 1}
                  </span>
                  <span style={{
                    fontSize: '0.875rem',
                    fontWeight: state === 'active' ? 500 : 400,
                    color: state === 'active' ? '#111827' : '#6b7280',
                  }}>
                    {step.label}
                    {step.optional && <span style={{ display: 'block', fontSize: '0.75rem' }}>Optional</span>}
                  </span>
                </button>
              </li>
            );
          })}
        </ol>
      </nav>

      {/* Live region for screen reader announcements */}
      <div role="status" aria-live="polite" className="sr-only">{statusMessage}</div>

      {/* Step content */}
      <div role="region" aria-label={steps[activeStep].label}>
        {steps[activeStep].content}
      </div>

      {/* Navigation */}
      <div style={{ display: 'flex', justifyContent: 'space-between', marginTop: 24 }}>
        <button onClick={handleBack} disabled={activeStep === 0} className="btn btn--secondary">
          Back
        </button>
        <button onClick={handleNext} className="btn btn--primary">
          {activeStep === steps.length - 1 ? 'Complete' : 'Continue'}
        </button>
      </div>
    </div>
  );
}

// Usage
function CheckoutFlow() {
  return (
    <Stepper
      steps={[
        {
          label: 'Cart Review',
          validate: () => true,
          content: <div>Review your items...</div>,
        },
        {
          label: 'Shipping',
          validate: () => true,
          content: <div>Enter shipping address...</div>,
        },
        {
          label: 'Payment',
          validate: () => true,
          content: <div>Enter payment details...</div>,
        },
        {
          label: 'Confirmation',
          optional: false,
          content: <div>Review and confirm your order...</div>,
        },
      ]}
      onComplete={() => console.log('Order placed!')}
    />
  );
}