Initial Commit

openspec/changes/enterprise-react-wizard/proposal.md

@@ -0,0 +1,85 @@
+# 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
+```