[ENH] Implement new scrollspy

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 %}