# Tasks: enterprise-react-wizard

**Change ID**: enterprise-react-wizard
**Package**: `@suaveplan/react-wizard`
**Target path**: `react/forms/react-wizard`
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/react-translate`

---

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Scaffold

- [ ] Create directory tree per proposal layout.
- [ ] Write `package.json` at `0.1.0` with `"sideEffects": false`, exports map.
- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/react-translate workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`.
- [ ] Write `tsconfig.json`, `vitest.config.ts`, scripts.

---

## 2. Error codes and types

- [ ] Define `WizardError` extending `SuaveplanError`; codes: `WIZARD_CONTEXT_MISSING`, `WIZARD_GUARD_FAILED`, `WIZARD_STEP_NOT_FOUND`.
- [ ] Define all public types: `StepStatus`, `ProgressVariant`, `StepGuard`, `StepValidator`, `StepValidation`, `WizardContextValue`, `WizardDataContextValue`.

---

## 3. Guards

- [ ] Implement `runGuard(guard: StepGuard, data: unknown): Promise<StepValidation>` — calls guard, catches errors and wraps in `WizardError(WIZARD_GUARD_FAILED)`.
- [ ] Implement `combineGuards(...guards): StepGuard` — runs sequentially; first failure stops the chain.
- [ ] Write `step-guard.test.ts`: passing guard, failing guard, combined guards short-circuit. `{ timeout: 10000 }`.
- [ ] Write `step-guard.md`.

---

## 4. WizardContext + WizardProvider

- [ ] Manages `currentStep`, `totalSteps`, `stepStatuses: Record<number, StepStatus>`, `goNext()`, `goPrevious()`, `goTo(index)`, `validateCurrent()`.
- [ ] `useWizard()` throws `WizardError(WIZARD_CONTEXT_MISSING)` outside provider.
- [ ] OTel `wizard.step_complete` span emitted in `goNext()` on validation success; attributes `wizard.step_index`, `wizard.total_steps`.
- [ ] Write test + md.

---

## 5. WizardDataContext

- [ ] Manages cross-step data bag; `useWizardData()` returns `{ data, setData, mergeData, getData }`.
- [ ] Write test + stories (playground for `useWizardData`) + md.

---

## 6. Components

### Wizard

- [ ] Top-level orchestrator; collects `WizardStep` children via React traversal; renders current step.
- [ ] Write test, stories (linear-3-step, with-guard, playground), md.

### WizardStep

- [ ] Step boundary: accepts `label`, `validator?`, `guard?`; registers with `WizardContext`.
- [ ] Throws `WizardError(WIZARD_STEP_NOT_FOUND)` if used outside `Wizard`.
- [ ] Write test, stories, md.

### WizardBranch

- [ ] Conditional step rendering based on a `condition(data): boolean` prop.
- [ ] Write test, stories (conditional-path demo), md.

### WizardProgress

- [ ] Progress bar/stepper variants (`ProgressVariant`: `bar`, `dots`, `steps`).
- [ ] Uses `useTranslation` for step labels.
- [ ] Write test, stories (all-variants), md.

---

## 7. useWizard hook

- [ ] Returns `{ currentStep, totalSteps, stepStatus, goNext, goPrevious, goTo, validateCurrent, isFirstStep, isLastStep }`.
- [ ] Write test, stories (playground), md.

---

## 8. E2E

- [ ] `e2e/wizard.spec.ts` — Playwright: render 3-step wizard, fill step 1, click Next (validates), fill step 2 with invalid data (validation error shown), fix and click Next, fill step 3, complete → `onComplete` called.

---

## 9. Verify and publish

- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-wizard` — green.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-wizard` — 100%.
- [ ] `bun scripts/publish.ts --package @suaveplan/react-wizard`.
- [ ] Archive change folder.