feat(navigation): add accessible responsive menu to the header

[ekwe7]

closes #71

Add Accessible Responsive Navigation Menu to Header

Summary

This PR introduces a responsive, accessible navigation menu to the application header. On smaller viewports, the existing horizontal navigation is replaced with a collapsible disclosure menu controlled by a dedicated toggle button. On larger screens, the current inline navigation layout remains unchanged.

The implementation prioritizes accessibility, keyboard navigation, focus management, and responsive behavior while preserving existing navigation semantics and styling.

Problem

The current Header component renders all navigation links in a single horizontal row without responsive behavior. On narrow screens:

• Navigation links wrap or overflow the header
• No mobile-friendly navigation pattern is available
• Users lack a clear menu affordance
• Keyboard and accessibility expectations for responsive navigation are not met

Solution

Implemented a responsive disclosure-style navigation menu that:

• Displays a hamburger/menu toggle on smaller viewports
• Maintains the existing inline navigation on larger screens
• Uses semantic HTML and ARIA attributes
• Supports keyboard-only interaction
• Automatically closes during route navigation

Changes

Header Component

Updated src/components/Header.tsx to:

• Add a responsive navigation toggle button
• Use a semantic <button> element for menu control
• Implement aria-expanded and aria-controls
• Convert the component to a client component where required
• Preserve the existing logo link
• Preserve the existing Main navigation aria-label
• Preserve focus-visible ring behavior

Accessibility Improvements

Implemented:

• Keyboard-operable menu interactions
• Proper Tab navigation through menu items
• Escape key support to close the menu
• Focus restoration to the toggle button after closing
• Accessible disclosure state announcements through ARIA attributes

Route Change Handling

Added automatic menu closure when navigation occurs to prevent stale open states after route transitions.

Testing

Extended:

src/components/__tests__/Header.test.tsx

Added coverage for:

• Menu opens and closes correctly
• aria-expanded state updates appropriately
• Escape key closes the menu
• Focus returns to the toggle after close
• Navigation links remain reachable via keyboard
• Menu closes after route changes
• Desktop navigation layout remains unaffected

Documentation

Updated README.md with:

• Responsive navigation behavior
• Accessibility considerations
• Breakpoint selection rationale
• Keyboard interaction support

Testing Performed

Executed:

npm run lint
npm run typecheck
npm test
npm run build

Covered Edge Cases

• Opening menu and navigating to a new route
• Closing via Escape key
• Keyboard-only interaction flows
• Focus restoration behavior
• Desktop layout unaffected by responsive menu implementation

Accessibility Checklist

• Uses semantic button element
• Includes aria-expanded
• Includes aria-controls
• Supports keyboard navigation
• Supports Escape to close
• Restores focus appropriately
• Preserves existing navigation semantics
• Maintains focus-visible styling

Acceptance Criteria

• Responsive menu toggle added below breakpoint
• Accessible disclosure behavior implemented
• Menu closes on route changes
• Existing Header tests preserved and extended
• Navigation links remain keyboard accessible
• README updated with responsive navigation details
• Header component maintains high test coverage
• Wide-screen navigation behavior remains unchanged

[mikewheeleer]

well done — thanks for picking it up 🙌