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

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

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

File layout

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

2.8 KiB Raw Blame History