[ENH] Implement new scrollspy (#2119)

This PR implements a new scrollspy mechanism to highlight entries in the
secondary sidebar TOC; fixes #1965, and builds on top of #2107.

## Approach

Every link in the secondary sidebar TOC is a reference to a section in
the main article. This PR works by adding an `IntersectionObserver` that
observes the _heading_ at the top of every one of these sections. As the
user scrolls down, the `IntersectionObserver` triggers a callback when
new section headings come into view; an object containing the visibility
of the various sections is kept up to date by these events. The first
visible heading is the one that needs to have its respective TOC entry
highlighted.

## Other Notes

- Unrelated, but I kept getting errors coming from a place in
`setupAnnouncementBanner` where a `const` was being assigned to. I fixed
this just to make it stop complaining. If you'd rather have this in a
separate PR, I'm happy to do so.
- The `IntersectionObserver` is set to observe element crossings with
the viewport, but because there's a sticky menu bar at the top of the
page I added a `rootMargin` to pad down the top edge so that element
crossings happen below that menu bar. Testing by hand this seems to work
pretty well.
- I also tested clicking on entries in the TOC, and as long as you click
something high enough up on the page (not close to the bottom), the
correct element gets highlighted as expected. Of course, if you have a
bunch of sections right at the bottom, the one you click on won't be
highlighted:


```
     -------------
     | Section A |
     |           |
   --|-----------|---
   ⁞ |           |  ⁞
   ⁞ |           |  ⁞
   ⁞ |           |  ⁞
   ⁞ | Section B |  ⁞  <-- Viewport is still considered to be focused on Section A,
   ⁞ | Section C |  ⁞      which extends all the way to the start of Section B
   ⁞ | end       |  ⁞
   ------------------
```

---------

Co-authored-by: gabalafou <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

@@ -95,34 +95,6 @@ function addModeListener() {
   });
 }
 
-/*******************************************************************************
- * TOC interactivity
- */
-
-/**
- * TOC sidebar - add "active" class to parent list
- *
- * Bootstrap's scrollspy adds the active class to the <a> link,
- * but for the automatic collapsing we need this on the parent list item.
- *
- * The event is triggered on "window" (and not the nav item as documented),
- * see https://github.com/twbs/bootstrap/issues/20086
- */
-function addTOCInteractivity() {
-  window.addEventListener("activate.bs.scrollspy", function () {
-    const navLinks = document.querySelectorAll(".bd-toc-nav a");
-
-    navLinks.forEach((navLink) => {
-      navLink.parentElement.classList.remove("active");
-    });
-
-    const activeNavLinks = document.querySelectorAll(".bd-toc-nav a.active");
-    activeNavLinks.forEach((navLink) => {
-      navLink.parentElement.classList.add("active");
-    });
-  });
-}
-
 /*******************************************************************************
  * Scroll
  */
@@ -1012,6 +984,160 @@ async function fetchRevealBannersTogether() {
   }, 320);
 }
 
+/**
+ * Add the machinery needed to highlight elements in the TOC when scrolling.
+ *
+ */
+function setupArticleTocSyncing() {
+  // Right sidebar table of contents container
+  const pageToc = document.querySelector("#pst-page-toc-nav");
+
+  // Not all pages have or include a table of contents. (For example, in the PST
+  // docs, at the time of this writing: /user_guide/index.html.)
+  if (!pageToc) {
+    return;
+  }
+
+  // The table of contents is a list of .toc-entry items each of which contains
+  // a link and possibly a nested list representing one level deeper in the
+  // table of contents.
+  const tocEntries = Array.from(pageToc.querySelectorAll(".toc-entry"));
+  const tocLinks = Array.from(pageToc.querySelectorAll("a"));
+
+  // If there are no links in the TOC, there's no syncing to be done.
+  // (Currently, the template does not render the TOC container if there are no
+  // TOC links, so this condition should never evaluate to true if the TOC
+  // container is found on the page, but should the template change in the
+  // future, this check will prevent a runtime error.)
+  if (tocLinks.length === 0) {
+    return;
+  }
+
+  // When the website visitor clicks a link in the TOC, we want that link to be
+  // highlighted/activated, NOT whichever TOC link the intersection observer
+  // callback would otherwise highlight, so we turn off the observer and turn it
+  // back on later.
+  let disableObserver = false;
+  pageToc.addEventListener("click", (event) => {
+    disableObserver = true;
+    const clickedTocLink = tocLinks.find((el) => el.contains(event.target));
+    activate(clickedTocLink);
+    setTimeout(() => {
+      // Give the page ample time to finish scrolling, then re-enable the
+      // intersection observer.
+      disableObserver = false;
+    }, 1000);
+  });
+
+  /**
+   * Activate an element and its chain of ancestor TOC entries; deactivate
+   * everything else in the TOC. Together with the theme CSS, this unfolds
+   * the TOC out to the given entry and highlights that entry.
+   *
+   * @param {HTMLElement} tocLink The TOC entry to be highlighted
+   */
+  function activate(tocLink) {
+    tocLinks.forEach((el) => {
+      if (el === tocLink) {
+        el.classList.add("active");
+        el.setAttribute("aria-current", "true");
+      } else {
+        el.classList.remove("active");
+        el.removeAttribute("aria-current");
+      }
+    });
+    tocEntries.forEach((el) => {
+      if (el.contains(tocLink)) {
+        el.classList.add("active");
+      } else {
+        el.classList.remove("active");
+      }
+    });
+  }
+
+  /**
+   * Get the heading in the article associated with the link in the table of contents
+   *
+   * @param {HTMLElement} tocLink TOC DOM element to use to grab an article heading
+   *
+   * @returns The article heading that the TOC element links to
+   */
+  function getHeading(tocLink) {
+    const href = tocLink.getAttribute("href");
+    if (!href.startsWith("#")) {
+      return;
+    }
+    const id = href.substring(1);
+    // There are cases where href="#" (for example, the first one at /examples/kitchen-sink/structure.html)
+    if (!id) {
+      return;
+    }
+    // Use getElementById() because querySelector() requires escaping the id string
+    const target = document.getElementById(id);
+    // Often the target is a section but we want to track section's heading
+    const heading = target.querySelector(":is(h1,h2,h3,h4,h5,h6)");
+    // Fallback to the target if there is no heading (for example, links on the
+    // PST docs page /examples/kitchen-sink/api.html target <dt> elements)
+    return heading || target;
+  }
+
+  // Map heading elements to their associated TOC links
+  const headingsToTocLinks = new Map();
+  tocLinks.forEach((tocLink) => {
+    const heading = getHeading(tocLink);
+    if (heading) {
+      headingsToTocLinks.set(heading, tocLink);
+    }
+  });
+
+  let observer;
+
+  function connectIntersectionObserver() {
+    if (observer) {
+      observer.disconnect();
+    }
+
+    const header = document.querySelector("#pst-header");
+    const headerHeight = header.getBoundingClientRect().height;
+
+    // Intersection observer options
+    const options = {
+      root: null,
+      rootMargin: `-${headerHeight}px 0px -70% 0px`, // Use -70% for the bottom margin so that intersection events happen in only the top third of the viewport
+      threshold: 0, // Trigger as soon as the heading goes into (or out of) the top 30% of the viewport
+    };
+
+    /**
+     *
+     * @param {IntersectionObserverEntry[]} entries Objects containing threshold-crossing
+     * event information
+     *
+     */
+    function callback(entries) {
+      if (disableObserver) {
+        return;
+      }
+      const entry = entries.filter((entry) => entry.isIntersecting).pop();
+      if (!entry) {
+        return;
+      }
+      const heading = entry.target;
+      const tocLink = headingsToTocLinks.get(heading);
+      activate(tocLink);
+    }
+
+    observer = new IntersectionObserver(callback, options);
+    headingsToTocLinks.keys().forEach((heading) => {
+      observer.observe(heading);
+    });
+  }
+
+  // If the user resizes the window, the header height may change and the
+  // intersection observer's root margin will need to be recalculated
+  window.addEventListener("resize", debounce(connectIntersectionObserver, 300));
+  connectIntersectionObserver();
+}
+
 /*******************************************************************************
  * Set up expand/collapse button for primary sidebar
  */
@@ -1145,10 +1271,10 @@ documentReady(fetchRevealBannersTogether);
 
 documentReady(addModeListener);
 documentReady(scrollToActive);
-documentReady(addTOCInteractivity);
 documentReady(setupSearchButtons);
 documentReady(setupSearchAsYouType);
 documentReady(setupMobileSidebarKeyboardHandlers);
+documentReady(setupArticleTocSyncing);
 documentReady(() => {
   try {
     setupCollapseSidebarButton();

src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss

@@ -40,7 +40,8 @@ nav.page-toc {
 
     @include link-sidebar;
 
-    &.active {
+    &.active,
+    &[aria-current="true"] {
       @include link-sidebar-current;
 
       background-color: transparent;

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/page-toc.html

@@ -7,7 +7,7 @@
     class="page-toc tocsection onthispage">
     <i class="fa-solid fa-list"></i> {{ _('On this page') }}
   </div>
-  <nav class="bd-toc-nav page-toc" aria-labelledby="{{ page_navigation_heading_id }}">
+  <nav id="pst-page-toc-nav" class="page-toc" aria-labelledby="{{ page_navigation_heading_id }}">
     {{ page_toc }}
   </nav>
 {%- endif %}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

@@ -48,15 +48,14 @@
   {% endif %}
 {%- endblock extrahead %}
 {% block body_tag %}
-  {# set up with scrollspy to update the toc as we scroll #}
-  {# ref: https://getbootstrap.com/docs/4.0/components/scrollspy/ #}
-  <body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="{{ default_mode }}">
+  <body data-default-mode="{{ default_mode }}">
+{%- endblock %}
 
+{% block header %}
   {# A button hidden by default to help assistive devices quickly jump to main content #}
   {# ref: https://www.youtube.com/watch?v=VUR0I5mqq7I #}
   <div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">{{ _("Skip to main content") }}</a></div>
-
-{%- endblock %}
+{% endblock %}
 
 {%- block content %}
   {# A tiny helper pixel to detect if we've scrolled #}
@@ -78,7 +77,7 @@
   {% include "sections/announcement.html" %}
 
   {% block docs_navbar %}
-    <header class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
+    <header id="pst-header" class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
       {%- include "sections/header.html" %}
     </header>
   {% endblock docs_navbar %}
@@ -148,7 +147,6 @@
   </footer>
 {%- endblock footer %}
 {# Silence the sidebars and relbars since we define our own #}
-{% block header %}{% endblock %}
 {% block relbar1 %}{% endblock %}
 {% block relbar2 %}{% endblock %}
 {% block sidebarsourcelink %}{% endblock %}