docs(03-03): complete BackendSelectionStep plan

- SUMMARY.md: BackendSelectionStep TDD execution, WIZD-01 + WIZD-04 - STATE.md: progress updated to 85% (11/13), decisions added - ROADMAP.md: phase 3 plan progress updated (3/5 summaries)
2026-03-27 09:34:53 +01:00
parent b47f607224
commit 97651b5d59
3 changed files with 104 additions and 6 deletions
@@ -0,0 +1,94 @@
+---
+phase: 03-wizard-ui
+plan: "03"
+subsystem: wizard-step
+tags: [react, forms, react-hook-form, zod, tdd, validation]
+dependency_graph:
+  requires:
+    - "03-01: test infrastructure and RED baseline"
+    - "03-02: BackendCard UI atom"
+    - "src/store/context.tsx: WizardProvider, useWizard"
+    - "src/store/types.ts: WizardAction, BackendType"
+  provides:
+    - "src/components/wizard/BackendSelectionStep.tsx"
+  affects:
+    - "03-05: App step routing (renders BackendSelectionStep at step 0)"
+tech_stack:
+  added: []
+  patterns:
+    - "react-hook-form handleSubmit triggered by card click via pendingBackend ref"
+    - "mode: onSubmit + reValidateMode: onChange — no errors on fill, live errors after first failed submit"
+    - "SET_REMOTE_PARAMS({}) on backend selection — clears stale params without wiping deployment"
+key_files:
+  created:
+    - "src/components/wizard/BackendSelectionStep.tsx"
+  modified:
+    - "src/components/wizard/BackendSelectionStep.test.tsx"
+decisions:
+  - "[03-03] waitFor used in async validation tests — handleSubmit is async, React state updates need await"
+  - "[03-03] pendingBackend useRef stores clicked backend type before handleSubmit fires — avoids closure staleness"
+  - "[03-03] Dispatch order: SET_REMOTE_NAME -> SET_BACKEND_TYPE -> SET_REMOTE_PARAMS({}) -> SET_STEP(1)"
+metrics:
+  duration: "2 min"
+  completed: "2026-03-27"
+  tasks_completed: 1
+  files_created: 1
+  files_modified: 1
+---
+
+# Phase 03 Plan 03: BackendSelectionStep Summary
+
+BackendSelectionStep implemented with TDD: remote name zod validation (onSubmit mode) and popularity-sorted backend card grid that validates name before dispatching three store actions on card click.
+
+## Tasks Completed
+
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| RED | Add failing tests for BackendSelectionStep | cf06d72 | src/components/wizard/BackendSelectionStep.test.tsx |
+| GREEN | Implement BackendSelectionStep | b47f607 | src/components/wizard/BackendSelectionStep.tsx, BackendSelectionStep.test.tsx |
+
+## What Was Built
+
+**BackendSelectionStep** — Step 0 of the wizard. Renders a remote name text field (top) with zod-powered react-hook-form validation, followed by three backend selection cards in popularity order (Azure Blob Storage, Amazon S3, S3-Compatible).
+
+Clicking a card triggers `handleSubmit` internally — the form validates the remote name before dispatching actions. If the name is invalid, an inline error appears and navigation does not proceed. On valid submit, the component dispatches:
+1. `SET_REMOTE_NAME` — stores the validated name
+2. `SET_BACKEND_TYPE` — stores the selected backend
+3. `SET_REMOTE_PARAMS({})` — clears any stale backend-specific params
+4. `SET_STEP(1)` — advances to step 1
+
+The component never dispatches `RESET` — deployment options (includeInstall, configPath, scriptTargets) are preserved across back-navigation.
+
+## TDD Execution
+
+- **RED commit:** `cf06d72` — 10 test stubs replaced with real assertions, failing because component did not exist
+- **GREEN commit:** `b47f607` — Component implemented, all 10 tests pass
+
+## Verification
+
+```
+Test Files  1 passed (1)
+Tests      10 passed (10)
+```
+
+All WIZD-01 and WIZD-04 cases GREEN. Full suite: 71 passing, 16 RED (expected `expect.fail` stubs from Plans 03-04 and 03-05).
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Added waitFor to async validation tests**
+- **Found during:** GREEN phase test run
+- **Issue:** `handleSubmit` is async — React state updates from zod validation don't flush synchronously. Tests using `fireEvent.click` without `waitFor` found no alert in DOM.
+- **Fix:** Imported `waitFor` from `@testing-library/react`; wrapped post-click assertions in `await waitFor(...)` for the three tests that assert on validation error presence/absence.
+- **Files modified:** src/components/wizard/BackendSelectionStep.test.tsx
+- **Commit:** b47f607
+
+## Self-Check
+
+- [x] `src/components/wizard/BackendSelectionStep.tsx` exists
+- [x] `src/components/wizard/BackendSelectionStep.test.tsx` updated with real tests
+- [x] Commit `cf06d72` exists (RED tests)
+- [x] Commit `b47f607` exists (GREEN implementation)
+- [x] All 10 BackendSelectionStep tests GREEN
+- [x] No regressions in previously passing tests (71 passing)