79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
---
|
|
spec: docs/specs/ui/requirements/walkthrough-navigation-layout.md
|
|
created: 2026-07-28
|
|
status: done
|
|
---
|
|
|
|
# Fix Plan: Stable Walkthrough Navigation
|
|
|
|
## Root cause
|
|
|
|
`WalkthroughStepInner` only constrains its maximum height. Its explanation,
|
|
navigation, and comment form therefore size the card together; the body's
|
|
`flex-1` has no definite height to fill. A longer or shorter step consequently
|
|
moves the navigation row.
|
|
|
|
## Overview
|
|
|
|
Give the walkthrough surface a viewport-bounded, definite height and make the
|
|
step explanation its single internal scroll owner. Render the navigation as the
|
|
final fixed card footer so **Next** has a stable location while the current
|
|
step changes. Prove the geometry in existing desktop and mobile walkthrough
|
|
Playwright coverage.
|
|
|
|
## Frontend
|
|
|
|
### Walkthrough card composition
|
|
|
|
- `apps/web/components/diff/walkthrough-step-card.tsx` — make the shared inner
|
|
card a definite-height flex column; preserve a scrollable step body and move
|
|
the navigation row into the fixed footer after the feedback form.
|
|
- `apps/web/components/diff/walkthrough-floating-window.tsx` — give the
|
|
desktop floating card and phone bottom sheet the available bounded height,
|
|
while retaining the desktop drag position, mobile bottom alignment, and
|
|
app-status-bar clearance.
|
|
|
|
### Mobile design contract
|
|
|
|
- **Outcome / entry point:** advance an open walkthrough from its existing
|
|
bottom-sheet launcher.
|
|
- **Exemplar:** the existing `WalkthroughFloatingWindow` bottom-sheet
|
|
presentation supplies the surface and dismissal behavior; this change keeps
|
|
its primary action visible rather than introducing a new phone pattern.
|
|
- **Hierarchy / primary action:** explanation scrolls above; **Next** remains
|
|
the final, visible primary action.
|
|
- **Surface / rationale:** a bottom sheet remains appropriate because the
|
|
walkthrough is a temporary companion to the open code editor, not a primary
|
|
route. One bounded sheet and its interior own the vertical scroll.
|
|
- **Geometry:** use dynamic viewport sizing, preserve safe-area/status-bar
|
|
clearance, keep controls at least their existing touch target size, and keep
|
|
document horizontal overflow at zero.
|
|
|
|
## Tests
|
|
|
|
- No new non-trivial pure helper is introduced; the regression is rendered
|
|
geometry and is covered at the browser level.
|
|
|
|
## E2E Tests
|
|
|
|
- **Scenario:** desktop steps with different content lengths. **File:**
|
|
`apps/web/e2e/tests/review/walkthrough.spec.ts`. **Proof:** compare the
|
|
navigation-footer bounding box before and after advancing, then assert the
|
|
next step renders.
|
|
- **Scenario:** mobile bottom-sheet walkthrough. **File:**
|
|
`apps/web/e2e/tests/review/mobile-walkthrough.spec.ts`. **Proof:** advance
|
|
through steps and assert the navigation footer remains visible, contained by
|
|
the viewport, and in the same card position.
|
|
|
|
## Implementation Wave
|
|
|
|
1. [Stable navigation footer](task-01-stable-navigation-footer.md) — done, sequential.
|
|
|
|
## Risks
|
|
|
|
- A fixed height can hide long text if the body is not the sole scroll owner.
|
|
- Phone viewport and app-status-bar offsets can put a bottom action behind
|
|
browser chrome if dynamic height and existing bottom clearance are not kept.
|
|
- Hiding an occluded anchor must not also hide the editor range indicator;
|
|
preserve the range while clearing only the connector anchor.
|