From 74fa072e10cc0a258ee911050bab0c0e8dcf83c7 Mon Sep 17 00:00:00 2001 From: Kawa Date: Wed, 1 Apr 2026 12:58:27 +0200 Subject: [PATCH] docs(10-02): complete live remote name preview plan - Create 10-02-SUMMARY.md with task details and deviations - Update STATE.md: add decision, session info, update progress to 100% - Update ROADMAP.md: phase 10 marked complete (3/3 summaries) - Update REQUIREMENTS.md: mark UX-02 complete --- .planning/REQUIREMENTS.md | 4 +- .planning/ROADMAP.md | 6 +- .planning/STATE.md | 13 +-- .../10-content-clarity/10-02-SUMMARY.md | 90 +++++++++++++++++++ 4 files changed, 102 insertions(+), 11 deletions(-) create mode 100644 .planning/phases/10-content-clarity/10-02-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index e4e7dab..82e54b9 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -20,7 +20,7 @@ ### Content & Clarity - [x] **UX-01**: First-time visitor sees an intro section explaining what Ready2Blob does, with a clear call-to-action to start the wizard -- [ ] **UX-02**: Remote name field includes a placeholder example, help text explaining what it is, and a visual preview showing how it appears in the generated `[remote-name]` config +- [x] **UX-02**: Remote name field includes a placeholder example, help text explaining what it is, and a visual preview showing how it appears in the generated `[remote-name]` config - [x] **UX-03**: Each wizard step has a 1-2 sentence description below the heading explaining what the user is doing and why - [x] **UX-04**: All backend credential fields have contextual help text explaining what to enter and where to find it @@ -64,7 +64,7 @@ | COMP-04 | Phase 9 | Complete | | DEBT-01 | Phase 9 | Complete | | UX-01 | Phase 10 | Complete | -| UX-02 | Phase 10 | Pending | +| UX-02 | Phase 10 | Complete | | UX-03 | Phase 10 | Complete | | UX-04 | Phase 10 | Complete | | POLISH-01 | Phase 11 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 7976527..0d18fb6 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -37,7 +37,7 @@ Full phase details: [.planning/milestones/v1.1-ROADMAP.md](milestones/v1.1-ROADM - [x] **Phase 8: Theme Foundation** - MD3 color token system and dark mode infrastructure (completed 2026-04-01) - [x] **Phase 9: MD3 Components** - UI primitives and component migration to semantic tokens (completed 2026-04-01) -- [ ] **Phase 10: Content & Clarity** - Intro section, step descriptions, and contextual help +- [x] **Phase 10: Content & Clarity** - Intro section, step descriptions, and contextual help (completed 2026-04-01) - [ ] **Phase 11: Polish & Responsiveness** - Mobile layout, focus states, transitions, scroll-to-error ## Phase Details @@ -83,7 +83,7 @@ Plans: 2. Remote name field displays a placeholder example, help text, and a live preview showing how the name appears in `[remote-name]` config syntax 3. Every wizard step has a 1-2 sentence description below the heading explaining what the user is doing and why 4. All backend credential fields have contextual help text explaining what to enter and where to find the value -**Plans:** 2/3 plans executed +**Plans:** 3/3 plans complete Plans: - [ ] 10-01-PLAN.md — Intro section with CTA and step descriptions for all 4 steps - [ ] 10-02-PLAN.md — Remote name live config preview with helpText @@ -113,5 +113,5 @@ Plans: | 7. Validation & UX Polish | v1.1 | 3/3 | Complete | 2026-03-31 | | 8. Theme Foundation | v1.2 | 2/2 | Complete | 2026-04-01 | | 9. MD3 Components | v1.2 | 5/5 | Complete | 2026-04-01 | -| 10. Content & Clarity | 2/3 | In Progress| | - | +| 10. Content & Clarity | 3/3 | Complete | 2026-04-01 | - | | 11. Polish & Responsiveness | v1.2 | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 1a4c78a..5dadeae 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.2 milestone_name: UI Polish & Clarity status: completed -stopped_at: Completed 10-03-PLAN.md -last_updated: "2026-04-01T10:56:24.154Z" +stopped_at: Completed 10-02-PLAN.md +last_updated: "2026-04-01T10:58:05.053Z" last_activity: 2026-04-01 — Phase 9 complete (COMP-01, COMP-02, COMP-03, COMP-04, DEBT-01 satisfied) progress: total_phases: 4 - completed_phases: 2 + completed_phases: 3 total_plans: 10 - completed_plans: 9 + completed_plans: 10 percent: 64 --- @@ -63,6 +63,7 @@ Recent decisions affecting current work: - [Phase 10-03]: S3 region gets tooltipText only (no helpText) — placeholder is already descriptive - [Phase 10-03]: SFTP host and user intentionally omitted from tooltipText — self-explanatory per user decision - [Phase 10-03]: getByLabelText selector ambiguity fixed with { selector: 'input' } across all affected tests (same DEBT-01 pattern as Phase 09-03) +- [Phase 10-content-clarity]: RemoteNamePreview renders only div/span elements (no form controls) to preserve single-textbox selector contract in BackendSelectionStep tests ### Pending Todos @@ -74,6 +75,6 @@ None yet. ## Session Continuity -Last session: 2026-04-01T10:56:11.794Z -Stopped at: Completed 10-03-PLAN.md +Last session: 2026-04-01T10:58:05.050Z +Stopped at: Completed 10-02-PLAN.md Resume file: None diff --git a/.planning/phases/10-content-clarity/10-02-SUMMARY.md b/.planning/phases/10-content-clarity/10-02-SUMMARY.md new file mode 100644 index 0000000..2f32a05 --- /dev/null +++ b/.planning/phases/10-content-clarity/10-02-SUMMARY.md @@ -0,0 +1,90 @@ +--- +phase: 10-content-clarity +plan: "02" +subsystem: wizard-ui +tags: [live-preview, ux, form-fields, tdd] +dependency_graph: + requires: [] + provides: [RemoteNamePreview component, live config preview in BackendSelectionStep] + affects: [src/components/wizard/BackendSelectionStep.tsx] +tech_stack: + added: [] + patterns: [stateless display component, react-hook-form watch(), TDD red-green] +key_files: + created: + - src/components/ui/RemoteNamePreview.tsx + - src/components/ui/RemoteNamePreview.test.tsx + modified: + - src/components/wizard/BackendSelectionStep.tsx + - src/components/wizard/BackendSelectionStep.test.tsx + - src/components/wizard/RemoteConfigStep.test.tsx +decisions: + - "RemoteNamePreview renders only div/span — no form controls, preserving single-textbox selector contract" + - "watch('name') from useForm used for live preview — no useWatch, per plan spec" + - "helpText uses full sentence explaining rclone.conf syntax and naming constraints" +metrics: + duration_minutes: 8 + tasks_completed: 2 + files_created: 2 + files_modified: 3 + completed_date: "2026-04-01" +requirements_satisfied: [UX-02] +--- + +# Phase 10 Plan 02: Live Remote Name Preview Summary + +**One-liner:** Stateless RemoteNamePreview component with empty/value states integrated into BackendSelectionStep via watch('name') and enriched with helpText. + +## Tasks Completed + +| # | Task | Commit | Status | +|---|------|--------|--------| +| 1 | Create RemoteNamePreview component with TDD | 3c9c5fd | Done | +| 2 | Integrate RemoteNamePreview and helpText into BackendSelectionStep | fefab65 | Done | + +## What Was Built + +**RemoteNamePreview component** (`src/components/ui/RemoteNamePreview.tsx`): +- Stateless functional component accepting `{ value: string }` +- Empty/whitespace state: displays grayed `[my-remote]` placeholder with "Type a name to see how it appears in your config" guidance +- Value state: displays `[typed-value]` in on-surface-variant color +- Container styling: `mt-2 rounded-md bg-surface-variant px-3 py-2 text-xs font-mono` +- Renders only div/span elements — never form controls + +**BackendSelectionStep integration**: +- Added `watch` to useForm destructure +- Added `const remoteName = watch('name')` for reactive updates +- Added `helpText` prop to remote name TextFieldMD3: full sentence explaining rclone.conf [name] syntax +- Added `` below the TextFieldMD3 +- Note: description paragraph and RemoteNamePreview import were committed as part of Plan 10-01 linter sweep (commit 4b837b1) + +## Tests + +- `RemoteNamePreview.test.tsx`: 9 tests (empty state x3, value state x3, element type constraints x3) +- `BackendSelectionStep.test.tsx`: 2 new integration tests (empty-state placeholder, live update on type) +- Full suite: 202 tests pass + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Fixed getByText(/required/i) ambiguity in BackendSelectionStep.test.tsx** +- **Found during:** Task 2 +- **Issue:** New description paragraph ("...credentials are required in the next step") caused `getByText(/required/i)` to match two elements, breaking existing "shows inline error" test +- **Fix:** Changed to `screen.getByRole('alert').textContent.toMatch(/required/i)` for precise alert text assertion +- **Files modified:** `src/components/wizard/BackendSelectionStep.test.tsx` +- **Commit:** fefab65 + +**2. [Rule 1 - Bug] Fixed getByLabelText ambiguity in RemoteConfigStep.test.tsx** +- **Found during:** Task 2 (full suite run) +- **Issue:** Linter-added paragraphs in RemoteConfigStep, combined with partial `{ selector: 'input' }` fix from 10-03 commits, left GCS, B2, and S3-region VALID-01 tests failing with "Found multiple elements" +- **Fix:** Added `{ selector: 'input' }` to all remaining `getByLabelText` calls in BACK-03, BACK-04, and VALID-01 sections +- **Files modified:** `src/components/wizard/RemoteConfigStep.test.tsx` +- **Commit:** fefab65 (included in Task 2 commit via linter application) + +## Self-Check: PASSED + +- src/components/ui/RemoteNamePreview.tsx: FOUND +- src/components/ui/RemoteNamePreview.test.tsx: FOUND +- Commit 3c9c5fd (Task 1): FOUND +- Commit fefab65 (Task 2): FOUND