[web] Bound mobile navigation

Merged
AS
4mo ago
+385-51

Summary

  • replace the in-flow small-screen navigation links with the existing accessible ModalDialog top sheet
  • bound and scroll the navigation independently so opening it never lengthens or displaces the page
  • close on destination selection, Close, Escape, outside interaction, and crossing the desktop breakpoint
  • preserve focus trapping/restoration and focus the first navigation destination on open
  • add focused unit, Storybook, and Cypress coverage plus a shared jsdom matchMedia stub

Root cause

The small-screen links were rendered inside the header's normal document flow. Expanding the menu therefore inserted every destination above the page content, turning the header and route content into one long mixed page.

Mobile parity

The native app already uses five fixed bottom tabs and has no expandable navigation equivalent, so no native mobile behavior changes are needed.

Validation

  • pnpm exec vitest run --project unit packages/web --reporter=dot — 166 files, 1,204 tests passed
  • pnpm exec vitest run --project unit --project mobile --reporter=dot — 942 files passed, 2 skipped; 14,597 tests passed, 21 skipped
  • pnpm --dir packages/web typecheck
  • pnpm --dir packages/server typecheck
  • pnpm tsc --noEmit
  • pnpm lint — passed with an isolated current-worktree ClickHouse service
  • Storybook runtime audit at 390 px, 768 px, and 1,024 px — bounded sheet, unchanged content position, focus/Escape restoration, and desktop breakpoint close verified

Local Cypress execution was attempted twice through the unchanged pnpm e2e:web:up workflow, but Docker infrastructure prevented the test environment from starting:

  1. The first build completed, then Docker failed creating issue-2188-e2e_default: all predefined address pools have been fully subnetted.
  2. After scoped cleanup freed an address pool, the exact retry failed in Dockerfile line 88's pnpm install --force --frozen-lockfile. The first fatal line was [ERR_PNPM_BROKEN_METADATA_JSON] The operation was aborted due to timeout after prolonged npm registry metadata requests.

The unchanged CI E2E job is therefore required as the authoritative Cypress validation before merge.

Fixes #2188

Summary by Sourcery

Bound the small-screen web navigation inside an accessible modal sheet so opening the menu no longer displaces page content and closes appropriately across viewports.

New Features:

  • Introduce a modal-based mobile navigation sheet with a titled header, explicit close action, and independent scroll area.
  • Add a Storybook scenario that presents the AppHeader with the mobile navigation menu opened by default.

Bug Fixes:

  • Ensure mobile navigation closes on destination selection, Close button, Escape key, outside interaction, and when crossing to the desktop breakpoint.
  • Preserve and restore keyboard focus correctly when opening and closing the mobile navigation sheet, with focus trapped inside while open.

Enhancements:

  • Refine mobile navigation link styling for clearer, full-width tappable targets.
  • Wire the AppHeader to respond to a desktop breakpoint media query to keep mobile and desktop navigation states in sync.
  • Mock window.matchMedia in web tests to support viewport-dependent behavior.

Documentation:

  • Add a TDD plan document describing the bounded mobile navigation change, its behavior, scope, and test strategy.

Tests:

  • Extend AppHeader unit tests to cover modal semantics, focus management, dismissal paths, and breakpoint-driven closing for mobile navigation.
  • Expand Cypress navigation E2E coverage to verify bounded mobile navigation behavior and that page content is not displaced when the menu opens.

Summary by cubic

Bound the small-screen navigation in a scroll-bounded top-sheet ModalDialog so it no longer pushes page content. It focuses the first link, traps/restores focus with preventScroll, and closes on selection, Escape, outside pointer, and when switching to desktop; fixes #2188.

  • Bug Fixes
    • Replaced in-flow mobile links with a top-sheet ModalDialog that has independent scroll, prevents scroll jumps on focus, full-width tappable links, and an explicit Close.
    • Auto-close at the lg breakpoint via matchMedia, then focus the first desktop link; desktop sidebar unchanged.
    • Standardized outside-pointer dismissal in ModalDialog to be opt-in via pointer events; mobile navigation opts in.
    • Added focused unit tests (including preventScroll and outside-pointer cases), a Storybook “MobileNavigationOpen” story, a Cypress spec asserting stable scrollY and unchanged main position, and a shared jsdom matchMedia stub; added a short TDD plan doc.