docs(phase-07): complete phase execution — VALID-01 and UX-01 verified

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.planning/STATE.md

@@ -4,7 +4,7 @@ milestone: v1.1
 milestone_name: Backlog & Tech Debt
 status: planning
 stopped_at: Completed 07-validation-ux-polish 07-02-PLAN.md
-last_updated: "2026-03-31T11:48:24.342Z"
+last_updated: "2026-03-31T11:53:18.993Z"
 last_activity: 2026-03-27 — v1.1 roadmap created, 11 requirements mapped across 3 phases
 progress:
   total_phases: 3

.planning/phases/07-validation-ux-polish/07-VERIFICATION.md

@@ -0,0 +1,159 @@
+---
+phase: 07-validation-ux-polish
+verified: 2026-03-31T13:55:00Z
+status: human_needed
+score: 12/12 must-haves verified
+re_verification: false
+human_verification:
+  - test: "Inline validation error on Azure account name field"
+    expected: "Typing 'ABC' then clicking Next shows 'Must be 3–24 lowercase alphanumeric characters' below the field before advancing"
+    why_human: "Visual rendering and wizard step-gate behavior cannot be confirmed by test assertions alone"
+  - test: "Inline validation error on S3 region field"
+    expected: "Typing 'us east 1' then clicking Next shows 'Must be a valid AWS region format (e.g. us-east-1)' inline"
+    why_human: "Visual placement and UX clarity require a human eye"
+  - test: "Inline validation error on GCS project_number field"
+    expected: "Typing 'abc' then clicking Next shows 'Must contain digits only' inline"
+    why_human: "Visual placement and UX clarity require a human eye"
+  - test: "Tooltip toggle on SAS URL field"
+    expected: "Clicking ⓘ next to 'SAS URL' label reveals an explanation panel; clicking again hides it"
+    why_human: "The human-verify checkpoint in Plan 07-02 was approved (commit 7548c7b) — but that approval is documented in a commit message, not independently verifiable by automated means. A fresh human confirmation closes the loop."
+  - test: "Tooltip toggle on Access Key field"
+    expected: "Clicking ⓘ next to 'Access Key' label reveals the unrestricted-access warning panel; clicking again hides it"
+    why_human: "Same as above — visual confirm of content and toggle"
+  - test: "Tooltip toggle on SFTP authentication method"
+    expected: "Clicking ⓘ above the Password/Private Key tabs reveals the auth-method explanation; clicking again hides it"
+    why_human: "Section-level tooltip — visual placement relative to segmented control needs human confirm"
+  - test: "Tooltip toggle on OneDrive token field"
+    expected: "Clicking ⓘ next to 'OAuth Token (JSON)' label reveals the rclone-authorize JSON token explanation; clicking again hides it"
+    why_human: "Visual confirm of content and toggle"
+---
+
+# Phase 7: Validation and UX Polish Verification Report
+
+**Phase Goal:** Add inline field format validation and contextual tooltip help to reduce config errors and support-ticket load.
+**Verified:** 2026-03-31T13:55:00Z
+**Status:** human_needed
+**Re-verification:** No — initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| #  | Truth | Status | Evidence |
+|----|-------|--------|----------|
+| 1  | VALID-01 failing tests exist for Azure account name regex rejection and acceptance | VERIFIED | `describe('VALID-01 — format validation')` block in RemoteConfigStep.test.tsx, lines 233–337; 3 Azure tests present |
+| 2  | VALID-01 failing tests exist for S3 region regex rejection and acceptance | VERIFIED | S3 region tests at lines 282–309 in test file |
+| 3  | VALID-01 failing tests exist for GCS project_number regex rejection and acceptance | VERIFIED | GCS tests at lines 312–336 in test file |
+| 4  | UX-01 failing tests exist for ⓘ button presence and tooltip toggle behavior | VERIFIED | `describe('UX-01 — contextual tooltips')` block at lines 339–401; 5 tests present |
+| 5  | User entering 'MyStorage' in Azure account name sees an inline error before advancing | VERIFIED | `validate: { regex: /^[a-z0-9]{3,24}$/, message: 'Must be 3–24 lowercase alphanumeric characters...' }` in registry.ts line 33; `buildZodSchema()` chains `.regex()` in index.ts line 18; test passes |
+| 6  | User entering 'us east 1' in S3 region field sees an inline error | VERIFIED | `validate: { regex: /^[a-z][a-z0-9-]+[a-z0-9]$/, message: 'Must be a valid AWS region format...' }` in registry.ts line 87; test passes |
+| 7  | User entering 'abc' in GCS project_number field sees an inline error | VERIFIED | `validate: { regex: /^\d+$/, message: 'Must contain digits only' }` in registry.ts line 183; test passes |
+| 8  | Valid values produce no format error | VERIFIED | Acceptance tests at lines 266, 295, 325 all pass (159/159 full suite) |
+| 9  | Empty required fields show 'required' error, not the regex error | VERIFIED | `buildZodSchema()` applies `min(1)` before `regex()` for required fields; order guaranteed by let-schema pattern |
+| 10 | User can click ⓘ next to SAS URL / Access Key and read an explanation | VERIFIED | `tooltipText` populated in registry.ts lines 44, 53; AzureAuthToggle reads from BACKEND_REGISTRY and passes to PasswordField (lines 19–20); PasswordField renders ⓘ button + toggle panel |
+| 11 | User can click ⓘ on SFTP authentication method section | VERIFIED | SftpAuthToggle.tsx has `showAuthTip` state, ⓘ button with `aria-label="More info about authentication methods"`, conditional explanation panel |
+| 12 | User can click ⓘ next to OneDrive token label | VERIFIED | `tooltipText` populated in registry.ts line 147; FieldRenderer passes `tooltipText={field.tooltipText}` to PasswordField for password-type fields |
+
+**Score:** 12/12 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `src/components/wizard/RemoteConfigStep.test.tsx` | Failing test stubs for VALID-01 and UX-01 | VERIFIED | `describe('VALID-01...')` and `describe('UX-01...')` blocks present; 12 tests added (7 VALID-01 + 5 UX-01); all 33 RemoteConfigStep tests pass |
+| `src/schemas/registry.ts` | FieldDef with `validate?` and `tooltipText?`; 3 entries with validate rules; tooltipText for sas_url, key, token | VERIFIED | Both optional properties on FieldDef (lines 17–18); validate rules on azureblob.account, s3.region, gcs.project_number; tooltipText on azureblob.sas_url, azureblob.key, onedrive.token |
+| `src/schemas/index.ts` | `buildZodSchema()` chains `.regex()` when `field.validate` is present | VERIFIED | `if (field.validate)` block at lines 17–19 chains `(schema as z.ZodString).regex(...)` |
+| `src/components/ui/FieldRenderer.tsx` | ⓘ button + tooltip panel for text/select; passes `tooltipText` to PasswordField | VERIFIED | `useState(false)` for `showTooltip`; ⓘ button in both text (line 90) and select (line 48) branches; `tooltipText={field.tooltipText}` passed to PasswordField (line 35) |
+| `src/components/ui/PasswordField.tsx` | `tooltipText` prop + `showTooltip` state + ⓘ button + conditional panel | VERIFIED | `tooltipText?: string` in interface (line 11); `showTooltip` state (line 16); ⓘ button (line 23); conditional panel (line 34) |
+| `src/components/wizard/AzureAuthToggle.tsx` | Reads `tooltipText` from BACKEND_REGISTRY, passes to PasswordField | VERIFIED | `sasUrlTooltip` and `keyTooltip` lookups via `BACKEND_REGISTRY.azureblob.fields.find(...)` (lines 19–20); both passed as `tooltipText` prop to PasswordField |
+| `src/components/wizard/SftpAuthToggle.tsx` | `showAuthTip` state + ⓘ button above segmented control | VERIFIED | `showAuthTip` state (line 17); ⓘ button with `aria-label="More info about authentication methods"` (line 27); conditional explanation panel (line 33) |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `BACKEND_REGISTRY azureblob.account.validate` | `buildZodSchema('azureblob')` | `field.validate` conditional + `(schema as z.ZodString).regex()` | WIRED | index.ts lines 17–19; regex applied and test confirms error message surfaces |
+| `BACKEND_REGISTRY s3.region.validate` | `buildZodSchema('s3')` | same pattern | WIRED | registry.ts line 87; test passing |
+| `BACKEND_REGISTRY gcs.project_number.validate` | `buildZodSchema('gcs')` | same pattern | WIRED | registry.ts line 183; test passing |
+| `BACKEND_REGISTRY azureblob.sas_url.tooltipText` | `AzureAuthToggle → PasswordField tooltipText prop` | `BACKEND_REGISTRY.azureblob.fields.find(f => f.key === 'sas_url')?.tooltipText` | WIRED | AzureAuthToggle.tsx line 19; `tooltipText={sasUrlTooltip}` at line 61 |
+| `BACKEND_REGISTRY onedrive.token.tooltipText` | `FieldRenderer ⓘ button rendered` | `field.tooltipText` present → `tooltipText` passed to PasswordField | WIRED | FieldRenderer.tsx line 35; test `renders ⓘ button on OneDrive token field` passes |
+| `SftpAuthToggle showAuthTip state` | inline explanation panel | `useState` + `{showAuthTip && <p>...}` | WIRED | SftpAuthToggle.tsx line 33; test `renders ⓘ button on SFTP auth method section` passes |
+
+### Requirements Coverage
+
+| Requirement | Source Plans | Description | Status | Evidence |
+|-------------|-------------|-------------|--------|----------|
+| VALID-01 | 07-00, 07-01 | User sees inline validation error on format violations (Azure account, S3 region, GCS project_number) | SATISFIED | validate rules in registry.ts; buildZodSchema chains .regex(); 7 VALID-01 tests pass; TypeScript compiles clean |
+| UX-01 | 07-00, 07-02 | User can view contextual tooltip on sensitive/complex fields (SAS token, access key, SFTP auth method, OneDrive token) | SATISFIED | tooltipText in registry; ⓘ buttons in PasswordField/FieldRenderer/SftpAuthToggle; AzureAuthToggle wired; 5 UX-01 tests pass |
+
+No orphaned requirements — REQUIREMENTS.md maps only VALID-01 and UX-01 to Phase 7, both claimed by plans and verified.
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| `src/components/ui/FieldRenderer.tsx` | 94–98 | Text-branch ⓘ button uses `<span className="sr-only">` for accessible name instead of `aria-label` on the button element directly — unlike the select branch (line 52) which uses `aria-label` | Info | Tests still pass because `sr-only` span content is used by testing-library as the button's accessible name. However the two branches are inconsistent: select uses `aria-label`, text uses `sr-only` span. Not a functional defect but a maintainability inconsistency. |
+
+No blockers, no stubs, no TODO/FIXME/placeholder comments found in modified files.
+
+### Human Verification Required
+
+All automated checks pass (159/159 tests, 0 TypeScript errors). The items below require a human to confirm real-browser behavior, because the human-verify checkpoint documented in Plan 07-02 (commit 7548c7b) was the original approval — this verification independently requests a fresh confirmation.
+
+#### 1. Inline Validation — Azure Account Name
+
+**Test:** Open wizard, select Azure Blob Storage. Type `ABC` into Storage Account Name, click Next.
+**Expected:** An inline error reading "Must be 3–24 lowercase alphanumeric characters (no hyphens or uppercase)" appears below the field. The wizard does not advance.
+**Why human:** Visual placement of error, step-gate behavior.
+
+#### 2. Inline Validation — S3 Region
+
+**Test:** Select Amazon S3. Type `us east 1` into Region, click Next.
+**Expected:** Inline error reading "Must be a valid AWS region format (e.g. us-east-1)" appears. Wizard does not advance.
+**Why human:** Visual placement of error, step-gate behavior.
+
+#### 3. Inline Validation — GCS Project Number
+
+**Test:** Select Google Cloud Storage. Type `abc` into Project Number, click Next.
+**Expected:** Inline error "Must contain digits only" appears. Wizard does not advance.
+**Why human:** Visual placement of error, step-gate behavior.
+
+#### 4. Tooltip Toggle — SAS URL
+
+**Test:** Select Azure Blob Storage. Click the ⓘ button next to "SAS URL".
+**Expected:** An explanation panel appears below the SAS URL field containing text about Shared Access Signatures. Click ⓘ again — panel disappears.
+**Why human:** Visual appearance, tooltip content readability, toggle feel.
+
+#### 5. Tooltip Toggle — Access Key
+
+**Test:** In Azure Blob Storage, switch to the "Access Key" tab. Click ⓘ next to "Access Key".
+**Expected:** Panel appears with unrestricted-access warning. Click ⓘ again — panel hides.
+**Why human:** Visual confirm; the ⓘ button is CSS-hidden until the Access Key tab is active.
+
+#### 6. Tooltip Toggle — SFTP Authentication Method
+
+**Test:** Select SFTP. Confirm ⓘ appears above the Password/Private Key tab row (labeled "Authentication Method ⓘ"). Click it.
+**Expected:** Explanation panel appears describing password vs key-based auth. Click again — panel hides.
+**Why human:** Section-level tooltip placement relative to segmented control.
+
+#### 7. Tooltip Toggle — OneDrive Token
+
+**Test:** Select OneDrive. Click ⓘ next to "OAuth Token (JSON)".
+**Expected:** Panel appears explaining `rclone authorize "onedrive"` and pasting the JSON blob. Click ⓘ again — panel hides.
+**Why human:** Content accuracy and readability of the rclone-specific guidance.
+
+### Gaps Summary
+
+No gaps found. All automated evidence confirms the phase goal was achieved:
+
+- VALID-01: Three backend-specific regex validators wired end-to-end from `BACKEND_REGISTRY` through `buildZodSchema()` to the wizard form; inline error messages match the specified copy; all 7 validation tests pass.
+- UX-01: Four tooltip surfaces implemented (SAS URL, Access Key, SFTP auth method, OneDrive token); ⓘ button + toggle panel present in FieldRenderer, PasswordField, AzureAuthToggle, and SftpAuthToggle; all 5 tooltip tests pass.
+- Full suite: 159 tests, 0 failures, 0 TypeScript errors.
+- All 6 commits documented in summaries confirmed in git history.
+
+The only outstanding item is fresh human confirmation that the UI behaves correctly in a running browser. The original human-verify checkpoint (Plan 07-02 Task 3) was approved, so this is a confirmation step rather than a discovery step.
+
+---
+
+_Verified: 2026-03-31T13:55:00Z_
+_Verifier: Claude (gsd-verifier)_