Files
kandev/docs/plans/walkthrough-navigation-layout/plan.md
T
2026-08-24 11:09:03 +00:00

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.