fix(#3726): highlight last TOC heading when scrolled to bottom

[twjeffery]

Summary

• Fixes the sticky TOC highlighting the wrong section for short sections near the bottom of the page (e.g. "Get started" on the workspace page)
• Adds a bottom-of-page check in handleScroll: when window.innerHeight + window.scrollY >= document.body.scrollHeight - 10, the last visible heading is set as active instead of relying on the 120px threshold

Screen.Recording.2026-03-31.at.3.07.21.PM.mov

Closes #3726

Test plan

• Navigate to a docs page with a short final section (e.g. workspace example page)
• Scroll to the very bottom of the page — the last TOC item should be highlighted
• Click the last TOC item — it should become active
• Scroll back up — TOC highlighting should still work normally for all other sections

https://claude.ai/code/session_01Rcc9hcmnjnE8vdXhiz7VMM

[Spark450]

I think it is certainly working better but it looks like the selection "bounces" a bit then settles.
https://jam.dev/c/08f2e673-e30e-4d7d-a609-a1a81e62637a

[twjeffery]

I think it is certainly working better but it looks like the selection "bounces" a bit then settles. jam.dev/c/08f2e673-e30e-4d7d-a609-a1a81e62637a

I think that's expected for what it's fixing and doing. This is a fix to make it change (override what's set from the scroll position) to the last item if scroll is at the bottom. It's kind of like, it follows the heading based on the scroll position, and then if the scroll is at the bottom, then set it to bottom as active.

[chrisolsen]

If you are scrolling to the bottom, is there any reason you can't just set the last of the headings as the current, rather than this logic + calculations? Is there ever a time that the last heading isn't visible when you scroll to the bottom of the screen?

const atBottom = window.innerHeight + window.scrollY >= document.body.scrollHeight - 10;
if (atBottom) {
	const lastHeading = headings[headings.length - 1];
    const lastVisibleId = lastHeading.getAttribute("id");
    setActiveId(lastVisibleId);
    return;
}

[twjeffery]

Good point. The reason we need to filter is that headings here is all the matching headings in the DOM, not just the active tab. On component pages we have 4 tabs (Properties, Examples, Usage, Accessibility) and the headings from all of them are in the DOM at once. If we just grabbed the last one we'd always end up on a heading from the Accessibility tab no matter which tab the user is on.

You're right that we were doing more work than we needed to though. I refactored it to filter visible headings once at the top and both branches reuse that. It should be simpler now.

[Spark450]

If this approach is valid I think the behaviour is acceptable.

[chrisolsen]

🎉 This PR is included in version 2.0.0-dev.6 🎉

The release is available on:

• npm package (@dev dist-tag)
• GitHub release

Your semantic-release bot 📦🚀