# OpenSpec Change: enterprise-react-wizard

- **Change ID**: enterprise-react-wizard
- **Package**: `@suaveplan/react-wizard`
- **Category**: react
- **Target path**: `react/forms/react-wizard`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-wizard.md`

---

## Summary

Deliver `@suaveplan/react-wizard` on genesis from scratch at enterprise quality. Multi-step form wizard primitives: `Wizard`, `WizardStep`, `WizardBranch`, `WizardProgress` components, `WizardProvider`/`WizardDataProvider` contexts, `useWizard`/`useWizardData` hooks, async step guards (`runGuard`, `combineGuards`). Genesis adds Storybook stories for all components and hooks, Playwright E2E for a complete multi-step flow, `@suaveplan/error`-backed errors, and OTel span events.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `WizardError` |
| `@suaveplan/react-translate` (`workspace:^`) | i18n |
| `zod` (`catalog:forms`) | Step data schemas |
| `@opentelemetry/api` (`catalog:observability`) | `wizard.step_complete` span |

External: `tslib catalog:build`. React 18 peer.

---

## Preserved public API surface

```ts
Wizard, WizardStep, WizardBranch, WizardProgress
WizardProvider, WizardContext, WizardDataProvider, WizardDataContext
useWizard, useWizardData
runGuard, combineGuards

// Types
WizardProps, WizardStepProps, WizardBranchProps, WizardProgressProps,
WizardContextValue, WizardDataContextValue, StepGuard, StepValidator,
StepValidation, StepStatus, ProgressVariant
```

---

## New additions for genesis

1. **`WizardError`** — codes: `WIZARD_CONTEXT_MISSING`, `WIZARD_GUARD_FAILED`, `WIZARD_STEP_NOT_FOUND`.
2. **OTel `wizard.step_complete` span** — attributes: `wizard.step_index`, `wizard.total_steps`.
3. **Stories** — `Wizard` (linear 3-step), `WizardBranch` (conditional path), `WizardProgress` (all variants), `useWizard` playground, `useWizardData` playground.
4. **Playwright E2E** — 3-step wizard: fill step 1, click Next, fill step 2, click Back, re-fill, complete step 3.

---

## File layout

```text
react/forms/react-wizard/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    wizard/ (tsx + types + md + test + stories + index)
    wizard-context/ (tsx + types + md + test + index)
    wizard-step/ (tsx + types + md + test + stories + index)
    branching/ (tsx + types + md + test + stories + index)
    progress/ (tsx + types + md + test + stories + index)
    hooks/
      use-wizard/ (ts + types + md + test + stories + index)
      use-wizard-data/ (ts + types + md + test + stories + index)
    data/ (wizard-data-context + useWizardData)
    guards/ (step-guard.ts + md + test + index)
    types/
  e2e/
    wizard.spec.ts
```