fix(docs): Table of Contents Anchor Navigation in Safari on Mobile/Small Screens

[shashankxrm]

Summary

Root Cause

• On mobile/tablet, the TableOfContents(TOC) is hidden by default and shown via a button. When a link is clicked, the TOC is still visible or transitioning, and Safari sometimes fails to process anchor navigation or scrollIntoView if the element or its parent was recently hidden or transitioned.
• The previous implementation did not close the TOC before attempting to scroll, causing Safari to ignore the scroll action.

Solution

• State Management: Added state to track whether the TOC is open on mobile/tablet.
• Close Before Scroll: When a TOC link is clicked on mobile/tablet, the TOC is closed first, and then the scroll is triggered after a short delay (using setTimeout). This ensures the scroll happens after the TOC is hidden and the DOM is stable, which is required for Safari to process the scroll correctly.
• Responsive Logic: The scroll-and-close logic only applies on screens smaller than the desktop breakpoint (xl), so desktop/large screens are unaffected.
• Accessibility: The TOC button now uses aria-expanded and aria-controls for better accessibility.
• No Regression: No functional change for desktop/large screens.

Implementation

• Updated TableOfContents.tsx:
  • Added open state and a setOpen function to control TOC visibility.
  • Passed setTocOpen down to NavLink components.
  • In NavLink, when on mobile/tablet, clicking a link closes the TOC and then scrolls to the heading after a 250ms delay.
  • Used document.querySelector with CSS.escape for robust element selection.
  • Used scrollIntoView({ behavior: 'smooth', block: 'start' }) for smooth scrolling where supported.
  • The TOC closes when clicking outside of it on mobile/tablet.

Testing

• Safari (iOS and macOS):
  • On small screens, open the TOC, click a link, and verify the page scrolls to the correct section.
  • On large screens, verify the TOC links work as before.

Screen.Recording.2025-05-20.at.17.09.28.mov

Motivation

Bugs needed to be solved.

Change Type

• 🐞 Bug fix (non-breaking fix for an issue)
• ✨ Feature (non-breaking addition)
• 🧹 Refactor (non-breaking improvements, no behavior change)
• 💥 Breaking change (fix or feature that would change existing functionality)

Checklist

• I’ve read the Contributing Guidelines
• My code matches the project’s coding style (npm run lint)
• My change introduces changes to the documentation
• I’ve updated documentation where needed
• I’ve added tests covering new behavior
• All existing and new tests pass

Related Issues

• Closes "On this page" navigation links not working on Safari browser #3