From 58d96cbb48aff1eed44416617f59547f08239c92 Mon Sep 17 00:00:00 2001 From: Kawa Date: Wed, 1 Apr 2026 12:56:45 +0200 Subject: [PATCH] docs(10-03): complete credential-field help text plan - Add 10-03-SUMMARY.md with full deviation documentation - Update STATE.md: progress 97%, decisions, session - Update ROADMAP.md: phase 10 plan progress (2/3 summaries) - Mark UX-04 requirement complete in REQUIREMENTS.md --- .planning/REQUIREMENTS.md | 4 +- .planning/STATE.md | 5 +- .../10-content-clarity/10-03-SUMMARY.md | 98 +++++++++++++++++++ 3 files changed, 104 insertions(+), 3 deletions(-) create mode 100644 .planning/phases/10-content-clarity/10-03-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index c1ea6e7..e4e7dab 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -22,7 +22,7 @@ - [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-03**: Each wizard step has a 1-2 sentence description below the heading explaining what the user is doing and why -- [ ] **UX-04**: All backend credential fields have contextual help text explaining what to enter and where to find it +- [x] **UX-04**: All backend credential fields have contextual help text explaining what to enter and where to find it ### Polish @@ -66,7 +66,7 @@ | UX-01 | Phase 10 | Complete | | UX-02 | Phase 10 | Pending | | UX-03 | Phase 10 | Complete | -| UX-04 | Phase 10 | Pending | +| UX-04 | Phase 10 | Complete | | POLISH-01 | Phase 11 | Pending | | POLISH-02 | Phase 11 | Pending | | POLISH-03 | Phase 11 | Pending | diff --git a/.planning/STATE.md b/.planning/STATE.md index 502a3d8..1a4c78a 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -4,7 +4,7 @@ milestone: v1.2 milestone_name: UI Polish & Clarity status: completed stopped_at: Completed 10-03-PLAN.md -last_updated: "2026-04-01T10:56:11.800Z" +last_updated: "2026-04-01T10:56:24.154Z" last_activity: 2026-04-01 — Phase 9 complete (COMP-01, COMP-02, COMP-03, COMP-04, DEBT-01 satisfied) progress: total_phases: 4 @@ -60,6 +60,9 @@ Recent decisions affecting current work: - [Phase 10-content-clarity]: showIntro is local useState in WizardShell — not persisted, resets on page reload by design - [Phase 10-content-clarity]: IntroSection declared as a local component in App.tsx — appropriate for small co-located UI - [Phase 10-content-clarity]: ReviewStep lacked h2 heading — added 'Step 4: Review & Download' before description paragraph +- [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) ### Pending Todos diff --git a/.planning/phases/10-content-clarity/10-03-SUMMARY.md b/.planning/phases/10-content-clarity/10-03-SUMMARY.md new file mode 100644 index 0000000..3289282 --- /dev/null +++ b/.planning/phases/10-content-clarity/10-03-SUMMARY.md @@ -0,0 +1,98 @@ +--- +phase: 10-content-clarity +plan: "03" +subsystem: schemas +tags: [tooltips, help-text, ux, registry, credential-fields] +dependency_graph: + requires: [] + provides: [UX-04] + affects: [src/components/ui/FieldRenderer.tsx, src/components/ui/PasswordField.tsx] +tech_stack: + added: [] + patterns: [FieldDef enrichment, tooltipText/helpText data layer] +key_files: + created: [] + modified: + - src/schemas/registry.ts + - src/components/wizard/RemoteConfigStep.test.tsx +decisions: + - "S3 region gets tooltipText only (no helpText needed — placeholder is already descriptive)" + - "S3-compatible and S3 access key fields get both helpText and tooltipText" + - "GCS service_account_credentials tooltipText includes official doc link for key creation" + - "SFTP host and user intentionally get no tooltipText (self-explanatory, per user decision)" + - "B2 and GCS already had helpText — added tooltipText only, no rewrites" + - "OneDrive drive_id gets tooltipText alongside existing helpText" + - "Selector ambiguity fix ({ selector: 'input' }) applied to all getByLabelText calls now that tooltip buttons render aria-label attributes matching field labels" +metrics: + duration_minutes: 7 + completed_date: "2026-04-01" + tasks_completed: 2 + files_modified: 2 +requirements_satisfied: [UX-04] +--- + +# Phase 10 Plan 03: Credential Field Help Text and Tooltips Summary + +**One-liner:** Enriched BACKEND_REGISTRY with actionable tooltipText and helpText for all S3, S3-compatible, GCS, B2, and OneDrive drive_id credential fields, directing users to the exact console location to find each value. + +## What Was Built + +Registry.ts now contains contextual help for 11 credential fields across 5 backend types. Each tooltip tells users WHERE to find the value (not just what it is), with doc links for GCS service account JSON creation. + +### Fields enriched + +| Backend | Field | tooltipText | helpText | +|---|---|---|---| +| s3 | access_key_id | Yes (IAM console path) | Yes | +| s3 | secret_access_key | Yes (shown-once warning) | Yes | +| s3 | region | Yes (S3 console bucket list) | No | +| s3-compatible | access_key_id | Yes (Wasabi/R2/MinIO paths) | Yes | +| s3-compatible | secret_access_key | Yes (shown-once warning) | Yes | +| s3-compatible | endpoint | Yes (provider examples) | No (pre-existing) | +| gcs | project_number | Yes (Cloud Console path, numeric vs text ID) | No (pre-existing) | +| gcs | service_account_credentials | Yes (IAM steps + doc link) | No (pre-existing) | +| b2 | account | Yes (App Keys page, key ID vs account ID) | No (pre-existing) | +| b2 | key | Yes (shown-once warning) | No (pre-existing) | +| onedrive | drive_id | Yes (rclone authorize output, b! prefix) | No (pre-existing) | + +### Fields intentionally unchanged +- azureblob key, sas_url — pre-existing tooltipText preserved +- onedrive token — pre-existing tooltipText preserved +- sftp host, user — no tooltip (self-explanatory per user decision) +- sftp pass, key_pem — pre-existing helpText preserved + +## Tests + +37 tests pass. Added 4 new UX-01 tests verifying tooltip info buttons render for: +- S3 `access_key_id` +- S3-compatible `endpoint` +- GCS `service_account_credentials` +- B2 `account` (Application Key ID) + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Fixed getByLabelText selector ambiguity across test suite** +- **Found during:** Task 1 (immediately after first test run) +- **Issue:** Adding tooltipText to fields causes tooltip buttons to render with `aria-label="More info about {Field Label}"`. This made `getByLabelText(/field name/i)` match both the input element AND the tooltip button, triggering "Found multiple elements" errors in 13 tests. +- **Fix:** Added `{ selector: 'input' }` to all affected `getByLabelText` calls in BACK-02, BACK-03, BACK-01 (drive_id), BACK-03 GCS, BACK-04 B2, and VALID-01 blocks. This is the same DEBT-01 pattern resolved in Phase 09-03. +- **Files modified:** `src/components/wizard/RemoteConfigStep.test.tsx` +- **Commit:** 489dfab + +## Commits + +| Hash | Message | +|---|---| +| 356d557 | feat(10-03): enrich registry.ts with tooltipText and helpText for credential fields | +| 489dfab | feat(10-03): add tooltip tests for enriched fields; fix selector ambiguity | + +## Self-Check + +Files exist: +- src/schemas/registry.ts — verified (tooltipText count: 15 = 1 interface + 14 fields) +- src/components/wizard/RemoteConfigStep.test.tsx — verified (37 tests pass) + +Commits exist: +- 356d557 — verified +- 489dfab — verified