Phase 7: Validation & UX Polish - Context

Gathered: 2026-03-31 Status: Ready for planning

## Phase Boundary

Add format validation to specific credential fields (inline error on bad format) and clickable contextual tooltips to sensitive or confusing fields in RemoteConfigStep. Does not add new backends or change existing required/optional field logic.

## Implementation Decisions

Validation scope

Azure account name (account field, azureblob): 3–24 lowercase alphanumeric characters — validate with regex
S3 region (region field, s3): valid AWS region format (lowercase letters, digits, hyphens, e.g. us-east-1) — validate with regex
GCS project number (project_number field, gcs): digits only — validate with regex
S3-compatible endpoint: non-empty only (existing required behavior) — no URL format validation
S3-compatible region: skip — optional field, no universal format rule across providers
No other backends/fields need format validation beyond what already exists

Validation rule location

Add a validate?: { regex: RegExp; message: string } property to FieldDef in src/schemas/registry.ts
buildZodSchema() in src/schemas/index.ts reads field.validate and adds .regex(...) to the Zod string — keeps the registry as single source of truth
Registry entries for the 3 validated fields get their validate rule inline

Tooltip trigger

ⓘ icon (info icon) placed next to the field label — click/tap toggles explanation
Inline reveal: explanation expands directly below the field input, pushing content down
Toggle state is local to the field component (no global state needed)
Tooltip stays visible until ⓘ is clicked again (not dismissed on blur)

Add a new optional tooltipText?: string field to the FieldDef interface
helpText remains unchanged (brief hint, always visible below the field)
tooltipText is the longer plain-language explanation shown on ⓘ click — only fields that need a tooltip get this field populated
FieldRenderer and PasswordField render the ⓘ icon + inline expand when tooltipText is present

Fields that get tooltips

Per roadmap requirements (VALID-01 / UX-01 success criteria):

azureblob sas_url: explain SAS URL vs access key — a SAS URL bundles endpoint + time-limited token, scoped to containers; access key is the full account credential
azureblob key (access key): explain it's the full storage account key — different from SAS, full access
sftp auth method (password vs key): explain the difference between password auth and key-based auth — SftpAuthToggle UI needs an ⓘ on the tab labels or above the toggle
onedrive token: explain what the JSON token is and how to obtain it via rclone authorize "onedrive"

Claude's Discretion

Exact Tailwind styling of the ⓘ icon and inline tooltip panel
Whether SftpAuthToggle gets its ⓘ on the tab label or as a standalone line above the tabs
ⓘ icon source (Heroicons, inline SVG, or text character)
Exact wording of tooltip content (stay close to existing helpText tone)

<code_context>

Existing Code Insights

Reusable Assets

FieldDef interface (src/schemas/registry.ts): add validate?: { regex: RegExp; message: string } and tooltipText?: string — minimal interface extension
buildZodSchema() (src/schemas/index.ts): reads field.required to pick .min(1) — extend to also read field.validate?.regex and chain .regex(regex, message)
FieldRenderer (src/components/ui/FieldRenderer.tsx): already renders helpText and error — add ⓘ icon + conditional inline tooltip panel alongside label
PasswordField (src/components/ui/PasswordField.tsx): password fields also need the ⓘ icon treatment for sas_url, key, onedrive token
SftpAuthToggle (src/components/wizard/SftpAuthToggle.tsx): manages pass/key_pem tab — needs an ⓘ for the auth method concept (tab-level, not field-level)

Established Patterns

Error display: errors shown only after first submit, then live (mode: 'onSubmit', reValidateMode: 'onChange' already set in RemoteConfigStep — no change needed)
helpText rendered as <p className="text-xs text-gray-500"> below field — tooltip panel should use a similar small-text style, perhaps a different color (e.g., blue-tinted)
CSS-hidden toggle pattern used in AzureAuthToggle/SftpAuthToggle — can use same div.hidden/div.block for tooltip visibility

Integration Points

src/schemas/registry.ts: FieldDef interface + registry entries for azureblob.account, s3.region, gcs.project_number (add validate), and sas_url/key/sftp-auth/onedrive-token (add tooltipText)
src/schemas/index.ts: buildZodSchema() — read field.validate and apply regex
src/components/ui/FieldRenderer.tsx: add ⓘ icon + inline tooltip to text and select renderers
src/components/ui/PasswordField.tsx: add ⓘ icon + inline tooltip to password renderer
src/components/wizard/SftpAuthToggle.tsx: add ⓘ near the auth method tabs

</code_context>

## Specific Ideas

Tooltip expand is local React state (useState per field) — no external state or store involvement
The ⓘ icon appears inline with the label text: Storage Account Name ⓘ — clicking ⓘ expands an explanation block below the input
Validation regex for Azure account: /^[a-z0-9]{3,24}$/
Validation regex for S3 region: /^[a-z][a-z0-9-]+[a-z0-9]$/ (AWS region format)
Validation regex for GCS project number: /^\d+$/

## Deferred Ideas

None — discussion stayed within phase scope.

Phase: 07-validation-ux-polish Context gathered: 2026-03-31

5.7 KiB Raw Blame History Unescape Escape