From ea76990bb6014ce9bb72ee2d7364987ad7272b06 Mon Sep 17 00:00:00 2001
From: Jeffrey Phillips Freeman <the@jeffreyfreeman.me>
Date: Mon, 16 Feb 2026 19:26:49 -0500
Subject: [PATCH] Docs: Fixed some bugs int he ToC's javascript

---
 docs/javascripts/toc-collapse.js | 22 +++++++-----
 docs/stylesheets/extra.css       | 59 ++++++++++++++++++++++++++++----
 2 files changed, 66 insertions(+), 15 deletions(-)

diff --git a/docs/javascripts/toc-collapse.js b/docs/javascripts/toc-collapse.js
index e04bf49a5..20d3f6a5c 100644
--- a/docs/javascripts/toc-collapse.js
+++ b/docs/javascripts/toc-collapse.js
@@ -74,15 +74,19 @@
     userPinned.clear();
     autoExpanded.clear();
 
-    // Mark all nav roots so CSS can scope styles
-    sidebar.querySelectorAll("nav.md-nav").forEach(function (nav) {
-      nav.classList.add("md-nav--integrated");
-    });
-
-    // Find every <li> inside the actual TOC (md-nav--secondary) that has
-    // nested children.  We scope to the secondary nav to avoid touching the
-    // page-level nav item that wraps the TOC — that item contains a <label>
-    // for the mobile TOC toggle and would show up as a bogus duplicate entry.
+    // Find the actual TOC (md-nav--secondary).  We scope to the secondary
+    // nav to avoid touching the page-level nav items that wrap sections —
+    // those use Material's native checkbox-based toggle and should not be
+    // overridden.
+    //
+    // NOTE: The primary nav already has .md-nav--integrated added by
+    // mkdocs-material when the toc.integrate feature is enabled.  We do
+    // NOT re-add that class or extend it to descendant navs — doing so
+    // causes the CSS rule ".md-nav--integrated .md-nav__item--nested >
+    // .md-nav { display: block }" to override Material's native
+    // checkbox-based collapse on primary nav sections (Reference,
+    // Development, Architecture Decisions, etc.), creating whitespace
+    // below collapsed section headings.
     var tocNav = sidebar.querySelector("nav.md-nav--secondary");
     if (!tocNav) return;
 
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index 83fb9d0b9..0cb84594e 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -98,10 +98,57 @@
   min-width: 0;
 }
 
+/* --- Primary nav section collapse fix -----------------------------------------
+ *
+ * Material's native checkbox-based toggle for nav sections (Reference,
+ * Development, Architecture Decisions, etc.) must fully hide children
+ * when unchecked.  Without this, the <nav> container retains residual
+ * height from padding/grid-rows even when the checkbox is unchecked,
+ * causing visible whitespace below collapsed section headings.
+ * ----------------------------------------------------------------------- */
+
+/* Fully hide children of unchecked primary nav sections */
+.md-sidebar--primary .md-nav__item--nested > .md-nav__toggle:not(:checked) ~ .md-nav {
+  display: none;
+}
+
+/* --- Active page TOC collapsibility -------------------------------------------
+ *
+ * With toc.integrate, Material shows the page's TOC in the left sidebar
+ * but hides the toggle <label> on desktop (>= 76.25em), making the TOC
+ * always visible with no way to collapse it.  These rules show the toggle
+ * label (with its chevron icon) at all screen sizes, hide the duplicate
+ * <a> link, and respect the __toc checkbox for collapse/expand.
+ * ----------------------------------------------------------------------- */
+
+/* Show the TOC toggle label on desktop so users can collapse the TOC */
+.md-nav--integrated > .md-nav__list > .md-nav__item--active > label.md-nav__link[for="__toc"] {
+  display: flex !important;
+}
+
+/* Activate the chevron icon inside the label */
+.md-nav--integrated > .md-nav__list > .md-nav__item--active > label.md-nav__link[for="__toc"] .md-icon::after {
+  content: "";
+}
+
+/* Hide the duplicate <a> navigation link (user is already on this page) */
+.md-nav--integrated > .md-nav__list > .md-nav__item--active > label.md-nav__link[for="__toc"] + .md-nav__link {
+  display: none;
+}
+
+/* When the TOC checkbox is unchecked, hide the TOC.
+ * This overrides Material's "display: block" rule that forces the TOC
+ * visible for the active page. */
+.md-nav--integrated > .md-nav__list > .md-nav__item--active > #__toc:not(:checked) ~ .md-nav--secondary {
+  display: none !important;
+}
+
 /* --- Collapsible TOC in integrated sidebar --- */
 
-/* Container for the link row: link text + toggle chevron side by side */
-.md-nav--integrated .md-nav__item--nested > .md-nav__link {
+/* Container for the link row: link text + toggle chevron side by side.
+ * Scoped to .md-nav--secondary (the TOC) so it does not affect primary
+ * nav section headings which use Material's native <label> + checkbox. */
+.md-nav--secondary .md-nav__item--nested > .md-nav__link {
   display: flex;
   align-items: center;
 }
@@ -144,13 +191,13 @@
   transform: rotate(-90deg);
 }
 
-/* Hide nested nav list when collapsed */
-.md-nav--integrated .md-nav__item--nested.toc-collapsed > .md-nav {
+/* Hide nested nav list when collapsed (TOC items only) */
+.md-nav--secondary .md-nav__item--nested.toc-collapsed > .md-nav {
   display: none;
 }
 
-/* Show nested nav when expanded */
-.md-nav--integrated .md-nav__item--nested > .md-nav {
+/* Show nested nav when expanded (TOC items only) */
+.md-nav--secondary .md-nav__item--nested > .md-nav {
   display: block;
 }