86 lines
2.8 KiB
Markdown
86 lines
2.8 KiB
Markdown
# 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
|
|
```
|