[docs site] Update TOC to scroll with page content

[emma-boardman]

ℹ️ Pausing this work as their is another effort to update the documentation soon. Outstanding tasks documented below.

WHY are these changes introduced?

Fixes #147

WHAT is this pull request doing?

Updates the TOC component to:

• scroll independently of the page
• scroll below-the-fold links into view when the associated heading is visible on the page

Other approaches considered

1. Hide the TOC when there is not sufficient vertical space

Rationale: we already hide the TOC below 1400px

Conclusion: The TOC height varies between pages. Hiding the TOC when there is not sufficient vertical space causes inconsistent UX between pages.

2. Break the TOC content into individual child pages

Rationale: if content is so long it requires a TOC, that is too much content.

Conclusion: Due to the different structure of pages across the top-level sections, breaking all TOC content into child pages requires additional review of the IA, and a number of changes to the site components and structure (removing descriptons; curating order of sub-pages; handling subnav; handling index pages). This time investment was deemed excessive at present, given the TOC only overflows on a handful of pages. The usage of a TOC to break content into more manageable chunks is also consistent with shopify.dev IA.

Video tophat 📹 🎩

Screen.Recording.2024-10-02.at.15.36.19.mov

How to 🎩

1. Checkout branch
2. Run pnpm turbo run dev --filter=polaris.shopify.com
3. On a page with vertical TOC overflow (Content > ActionableLanguage):
   - scroll the TOC to select links below the fold
   - scroll the TOC to show links below the fold, without a selection
   - scroll the page to a heading associated with a link below the fold

🖥 Local development instructions
🗒 General tophatting guidelines
📄 Changelog guidelines

🎩 checklist

• Tested a snapshot
• Tested on mobile
• Tested on multiple browsers (Chrome MacOS; Safari MacOS; Firefox MacOS)
• Tested for accessibility
• Updated the component's README.md with documentation changes
• Tophatted documentation changes in the style guide

---

❗ Outstanding

The work remaining for this particular PR is to fix the bug shown below - when a cursor enters the TOC, no selection is made, and the cursor leaves the TOC, the page shifts.
Suspected cause: window scroll event listener is triggering when the pointer is within the TOC.

Screen.Recording.2024-10-02.at.15.09.59.mov

---

[emma-boardman]

tracking keyboard+pointer events inside the TOC to prevent the scrollLinkIntoView running when the TOC is being scrolled independent to the Page.

Instead, if the TOC is scrolled without a selection being made, the TOC scroll will be restored to the currentHeading position on mouseout.

without mouse/focus tracking:

Screen.Recording.2024-10-02.at.15.02.27.mov

with:

Screen.Recording.2024-10-02.at.15.09.59.mov

note: after leaving the TOC container without making a selection, the page scrolls to the new mouse position. This feels a little janky. However, tracking the previous scroll location could add a lot of overhead. Is this situation worth solving for, or is TOC scroll followed by selection a more common use-case?