From ca6e64d45180f0c7c6d77fd8f5e97941ba78ef95 Mon Sep 17 00:00:00 2001
From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com>
Date: Sun, 30 Nov 2025 13:11:20 -0300
Subject: [PATCH] docs: Fix bug on table of contents (#43840)

We were previously always highlighting the last header in the table of
contents as active even if you were at the top of the page. This is now
fixed, where upon loading the page, no header is highlighted, and as you
scroll, we highlight the top-most heading one by one.

Release Notes:

- N/A
---
 docs/theme/page-toc.js | 60 +++++++++++++++++++++++++-----------------
 1 file changed, 36 insertions(+), 24 deletions(-)

diff --git a/docs/theme/page-toc.js b/docs/theme/page-toc.js
index 1ca6f621de..627416fddf 100644
--- a/docs/theme/page-toc.js
+++ b/docs/theme/page-toc.js
@@ -3,21 +3,18 @@ let scrollTimeout;
 const listenActive = () => {
   const elems = document.querySelector(".pagetoc").children;
   [...elems].forEach((el) => {
-    el.addEventListener("click", (event) => {
+    el.addEventListener("click", (_) => {
       clearTimeout(scrollTimeout);
       [...elems].forEach((el) => el.classList.remove("active"));
       el.classList.add("active");
-      // Prevent scroll updates for a short period
+
       scrollTimeout = setTimeout(() => {
         scrollTimeout = null;
-      }, 100); // Adjust timing as needed
+      }, 100);
     });
   });
 };
 
-const getPagetoc = () =>
-  document.querySelector(".pagetoc") || autoCreatePagetoc();
-
 const autoCreatePagetoc = () => {
   const main = document.querySelector("#content > main");
   const content = Object.assign(document.createElement("div"), {
@@ -27,30 +24,41 @@ const autoCreatePagetoc = () => {
   main.prepend(content);
   main.insertAdjacentHTML(
     "afterbegin",
-    '<div class="sidetoc"><nav class="pagetoc"></nav></div>',
+    '<div class="toc-container"><nav class="pagetoc"></nav></div>',
   );
   return document.querySelector(".pagetoc");
 };
-const updateFunction = () => {
-  if (scrollTimeout) return; // Skip updates if within the cooldown period from a click
-  const headers = [...document.getElementsByClassName("header")];
-  const scrolledY = window.scrollY;
-  let lastHeader = null;
 
-  // Find the last header that is above the current scroll position
-  for (let i = headers.length - 1; i >= 0; i--) {
-    if (scrolledY >= headers[i].offsetTop) {
-      lastHeader = headers[i];
-      break;
+const getPagetoc = () =>
+  document.querySelector(".pagetoc") || autoCreatePagetoc();
+
+const updateFunction = () => {
+  if (scrollTimeout) return;
+
+  const headers = [...document.getElementsByClassName("header")];
+  if (headers.length === 0) return;
+
+  const threshold = 100;
+  let activeHeader = null;
+
+  for (const header of headers) {
+    const rect = header.getBoundingClientRect();
+
+    if (rect.top <= threshold) {
+      activeHeader = header;
     }
   }
 
+  if (!activeHeader && headers.length > 0) {
+    activeHeader = headers[0];
+  }
+
   const pagetocLinks = [...document.querySelector(".pagetoc").children];
   pagetocLinks.forEach((link) => link.classList.remove("active"));
 
-  if (lastHeader) {
+  if (activeHeader) {
     const activeLink = pagetocLinks.find(
-      (link) => lastHeader.href === link.href,
+      (link) => activeHeader.href === link.href,
     );
     if (activeLink) activeLink.classList.add("active");
   }
@@ -63,13 +71,9 @@ document.addEventListener("DOMContentLoaded", () => {
   const nonH1Headers = headers.filter(
     (header) => !header.parentElement.tagName.toLowerCase().startsWith("h1"),
   );
-  const sidetoc = document.querySelector(".sidetoc");
   const tocContainer = document.querySelector(".toc-container");
 
   if (nonH1Headers.length === 0) {
-    if (sidetoc) {
-      sidetoc.style.display = "none";
-    }
     if (tocContainer) {
       tocContainer.classList.add("no-toc");
     }
@@ -84,6 +88,7 @@ document.addEventListener("DOMContentLoaded", () => {
     className: "toc-title",
     textContent: "On This Page",
   });
+
   pagetoc.appendChild(tocTitle);
 
   headers.forEach((header) => {
@@ -94,7 +99,14 @@ document.addEventListener("DOMContentLoaded", () => {
     });
     pagetoc.appendChild(link);
   });
+
   updateFunction();
   listenActive();
-  window.addEventListener("scroll", updateFunction);
+
+  const pageElement = document.querySelector(".page");
+  if (pageElement) {
+    pageElement.addEventListener("scroll", updateFunction);
+  } else {
+    window.addEventListener("scroll", updateFunction);
+  }
 });