From 21267cc68d1c23b29a32719d246c93952a36aacd Mon Sep 17 00:00:00 2001
From: Brian Munkholm <brian.munkholm@crate.io>
Date: Mon, 8 Dec 2025 15:10:26 +0100
Subject: [PATCH 1/3] TOC expand-collapse icons

Added icons for collapsable/expandable TOC sections.
minor

minor
---
 docs/conf.py                                  |   3 +
 src/crate/theme/rtd/crate/sidebar.html        |   4 +
 .../rtd/crate/static/css/crateio-rtd.css      |  69 ++++++++++-
 src/crate/theme/rtd/crate/static/js/index.js  |   1 +
 .../theme/rtd/crate/static/js/toc-toggle.js   | 108 ++++++++++++++++++
 src/crate/theme/rtd/crate/theme.conf          |   4 +
 6 files changed, 188 insertions(+), 1 deletion(-)
 create mode 100644 src/crate/theme/rtd/crate/static/js/toc-toggle.js

diff --git a/docs/conf.py b/docs/conf.py
index f835f8e08..19da2681e 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,5 +1,8 @@
 from crate.theme.rtd.conf.theme import *
 
+# Note: TOC toggle icons are enabled by default in the theme.
+# To disable: html_theme_options["toc_toggle_icons"] = "false"
+
 # Mimic some bits of the RTD context being propagated to its Sphinx builder.
 # https://github.com/readthedocs/readthedocs.org/blob/main/readthedocs/doc_builder/backends/sphinx.py
 html_context.update({
diff --git a/src/crate/theme/rtd/crate/sidebar.html b/src/crate/theme/rtd/crate/sidebar.html
index ebe24fe3a..2537458fb 100644
--- a/src/crate/theme/rtd/crate/sidebar.html
+++ b/src/crate/theme/rtd/crate/sidebar.html
@@ -1,4 +1,8 @@
+{% if theme_toc_toggle_icons == 'true' %}
+<div role="complementary" class="bs-docs-sidebar hidden-print toc-toggle-icons-enabled">
+{% else %}
 <div role="complementary" class="bs-docs-sidebar hidden-print">
+{% endif %}
   {% if project == 'SQL 99' %}
   <div class="search-link">
     {% if pagename == "search" %}
diff --git a/src/crate/theme/rtd/crate/static/css/crateio-rtd.css b/src/crate/theme/rtd/crate/static/css/crateio-rtd.css
index 61132d732..4562012d0 100644
--- a/src/crate/theme/rtd/crate/static/css/crateio-rtd.css
+++ b/src/crate/theme/rtd/crate/static/css/crateio-rtd.css
@@ -104,7 +104,7 @@ div.hero.danger {
 }
 
 .bs-docs-sidenav > li {
-  display: none;
+  display: block;
 }
 
 /** MENUE **/
@@ -203,3 +203,70 @@ a code {
 div.topic {
   border: 0;
 }
+
+/* ========================================================================== */
+/* TOC Toggle Icons for Navigation                                           */
+/* ========================================================================== */
+/* Enable by adding class "toc-toggle-icons-enabled" to sidebar container    */
+/* Configuration: Set html_theme_options['toc_toggle_icons'] = True          */
+/* ========================================================================== */
+
+/* Add expand/collapse icon to items that have children */
+/* Modern browsers: Use :has() selector */
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li:has(> ul) > a::after,
+/* Fallback: Use .has-children class added by JavaScript */
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li.has-children > a::after {
+  content: "";
+  display: inline-block;
+  width: 16px;
+  height: 16px;
+  margin-left: auto;
+  padding-left: 8px;
+  background-color: var(--color-sidebar-left-link);
+  mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M15.707 12l-5.647-5.646a.5.5 0 01.708-.708l6 6a.5.5 0 010 .708l-6 6a.5.5 0 01-.708-.708L15.707 12z"/></svg>');
+  mask-size: contain;
+  mask-repeat: no-repeat;
+  mask-position: center;
+  transform: rotate(0deg);
+  /* transition: transform 0.3s ease-in-out, opacity 0.2s ease; */
+  /* Animation disabled - pages reload on navigation, causing animation to play on every page load */
+  opacity: 0.6;
+  flex-shrink: 0;
+}
+
+/* Rotate icon when parent is expanded (current/active or manually expanded) */
+/* Modern browsers: Use :has() selector */
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li.expanded:has(> ul) > a::after,
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li.has-children.expanded > a::after {
+  transform: rotate(90deg);
+}
+
+/* Hover effect on icon */
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li:has(> ul) > a:hover::after,
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li.has-children > a:hover::after {
+  opacity: 1;
+}
+
+/* Make link a flex container to position icon at the right */
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li:has(> ul) > a,
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li.has-children > a {
+  display: flex;
+  align-items: center;
+}
+
+/* Make cursor indicate clickable area for items with children */
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li:has(> ul) > a,
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li.has-children > a {
+  cursor: pointer;
+}
+
+/* JavaScript-driven expand/collapse behavior */
+/* Hide all children by default when JS is enabled */
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li.has-children > ul {
+  display: none !important;
+}
+
+/* Show children when parent is marked as expanded */
+.toc-toggle-icons-enabled .bs-docs-sidenav .toctree li.has-children.expanded > ul {
+  display: block !important;
+}
diff --git a/src/crate/theme/rtd/crate/static/js/index.js b/src/crate/theme/rtd/crate/static/js/index.js
index 27fe69abc..52ba04b2b 100644
--- a/src/crate/theme/rtd/crate/static/js/index.js
+++ b/src/crate/theme/rtd/crate/static/js/index.js
@@ -5,3 +5,4 @@ import "sticky-sidebar";
 import "./util";
 import "./crate";
 import "./custom";
+import "./toc-toggle";
diff --git a/src/crate/theme/rtd/crate/static/js/toc-toggle.js b/src/crate/theme/rtd/crate/static/js/toc-toggle.js
new file mode 100644
index 000000000..bc4c20eee
--- /dev/null
+++ b/src/crate/theme/rtd/crate/static/js/toc-toggle.js
@@ -0,0 +1,108 @@
+/**
+ * TOC Navigation Expand/Collapse Toggle
+ *
+ * This module adds interactive expand/collapse functionality to the table of
+ * contents (TOC) navigation sidebar. It allows users to click on parent items
+ * to show/hide their children.
+ *
+ * Features:
+ * - Click on items with children to toggle expand/collapse
+ * - Auto-expand current page's parent hierarchy
+ * - Add .has-children class for browsers without :has() support
+ * - ARIA attributes for accessibility
+ */
+
+/**
+ * Initialize TOC toggle behavior
+ */
+function initTocToggle() {
+  // Only initialize if the toc-toggle-icons-enabled class is present
+  const sidebar = document.querySelector('.toc-toggle-icons-enabled .bs-docs-sidenav');
+  if (!sidebar) {
+    return;
+  }
+
+  const tocItems = sidebar.querySelectorAll('.toctree li');
+
+  let itemsWithChildren = 0;
+  tocItems.forEach(item => {
+    // Check if item has direct ul children (already rendered)
+    const hasDirectChildren = item.querySelector(':scope > ul');
+
+    // Check if the link suggests this is a parent page (links to index.html or has children)
+    const link = item.querySelector(':scope > a');
+    const linkHref = link ? link.getAttribute('href') : '';
+    const linksToIndex = linkHref && (linkHref.endsWith('/index.html') || linkHref.includes('/index.html#'));
+
+    // Check if this item is alone in its parent <ul> (no siblings)
+    // Items with children are typically alone in their own <ul> block
+    const parentUl = item.parentElement;
+    const siblings = parentUl ? parentUl.querySelectorAll(':scope > li') : [];
+    const isAloneInUl = siblings.length === 1;
+
+    // Determine if item has or could have children:
+    // - Has direct children already rendered, OR
+    // - Links to index.html AND is alone in its <ul> (likely a section with children)
+    const hasChildren = hasDirectChildren || (linksToIndex && isAloneInUl);
+
+    if (!hasChildren) return;
+
+    itemsWithChildren++;
+
+    // Add .has-children class for browsers without :has() support
+    item.classList.add('has-children');
+
+    // Link was already found above, skip if not found
+    if (!link) return;
+
+    // Determine initial state
+    const isCurrentPath = item.classList.contains('current') ||
+                          item.classList.contains('active');
+
+    // Mark as expanded if in current path, otherwise collapsed
+    if (isCurrentPath) {
+      item.classList.add('expanded');
+    }
+
+    // Initialize ARIA attribute
+    link.setAttribute('aria-expanded', item.classList.contains('expanded').toString());
+
+    // Add click handler to toggle expansion (only if item has direct children to toggle)
+    if (hasDirectChildren) {
+      link.addEventListener('click', (e) => {
+        // Check if clicking on the icon area (right side)
+        const linkRect = link.getBoundingClientRect();
+        const clickX = e.clientX - linkRect.left;
+        const linkWidth = linkRect.width;
+
+        // If clicking in the last 30px (icon area), toggle instead of navigate
+        if (clickX > linkWidth - 30) {
+          e.preventDefault();
+          toggleItem(item, link);
+        }
+      });
+    }
+    // For items that link to index.html but don't have children rendered yet,
+    // clicking the icon will navigate to the page (normal link behavior)
+  });
+}
+
+/**
+ * Toggle expand/collapse state of a TOC item
+ * @param {HTMLElement} item - The list item element
+ * @param {HTMLElement} link - The anchor element
+ */
+function toggleItem(item, link) {
+  const isExpanded = item.classList.toggle('expanded');
+  // Force a reflow to ensure the browser applies the new CSS rules immediately.
+  void item.offsetHeight;
+  link.setAttribute('aria-expanded', isExpanded.toString());
+}
+
+// Run after DOM is ready
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', initTocToggle);
+} else {
+  // DOM already loaded
+  initTocToggle();
+}
diff --git a/src/crate/theme/rtd/crate/theme.conf b/src/crate/theme/rtd/crate/theme.conf
index f849a80dd..e8a6afb8c 100644
--- a/src/crate/theme/rtd/crate/theme.conf
+++ b/src/crate/theme/rtd/crate/theme.conf
@@ -52,6 +52,10 @@ tracking_hubspot_id =
 # Can be used the query string of a resource URL for HTTP cache busting
 ver =
 
+# TOC toggle icons - show expand/collapse icons in sidebar navigation
+# Values: "true" (default) or "false"
+toc_toggle_icons = true
+
 # Furo
 announcement =
 dark_css_variables =

From 5292a82bffdd8531b97a61baf3bf47de6b4af7af Mon Sep 17 00:00:00 2001
From: Brian Munkholm <brian.munkholm@crate.io>
Date: Mon, 8 Dec 2025 17:47:55 +0100
Subject: [PATCH 2/3] Remove left-over debug statements

---
 src/crate/theme/rtd/crate/static/js/toc-toggle.js | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/src/crate/theme/rtd/crate/static/js/toc-toggle.js b/src/crate/theme/rtd/crate/static/js/toc-toggle.js
index bc4c20eee..bad52f96e 100644
--- a/src/crate/theme/rtd/crate/static/js/toc-toggle.js
+++ b/src/crate/theme/rtd/crate/static/js/toc-toggle.js
@@ -24,7 +24,6 @@ function initTocToggle() {
 
   const tocItems = sidebar.querySelectorAll('.toctree li');
 
-  let itemsWithChildren = 0;
   tocItems.forEach(item => {
     // Check if item has direct ul children (already rendered)
     const hasDirectChildren = item.querySelector(':scope > ul');
@@ -44,11 +43,8 @@ function initTocToggle() {
     // - Has direct children already rendered, OR
     // - Links to index.html AND is alone in its <ul> (likely a section with children)
     const hasChildren = hasDirectChildren || (linksToIndex && isAloneInUl);
-
     if (!hasChildren) return;
 
-    itemsWithChildren++;
-
     // Add .has-children class for browsers without :has() support
     item.classList.add('has-children');
 

From 820eb570850ef17f3fa5e0de169e45fb9cca23ba Mon Sep 17 00:00:00 2001
From: Brian Munkholm <brian.munkholm@crate.io>
Date: Mon, 8 Dec 2025 18:24:46 +0100
Subject: [PATCH 3/3] fixes

---
 src/crate/theme/rtd/crate/static/css/crateio-rtd.css | 4 ++--
 src/crate/theme/rtd/crate/static/js/toc-toggle.js    | 7 +------
 2 files changed, 3 insertions(+), 8 deletions(-)

diff --git a/src/crate/theme/rtd/crate/static/css/crateio-rtd.css b/src/crate/theme/rtd/crate/static/css/crateio-rtd.css
index 4562012d0..e60a40d94 100644
--- a/src/crate/theme/rtd/crate/static/css/crateio-rtd.css
+++ b/src/crate/theme/rtd/crate/static/css/crateio-rtd.css
@@ -104,7 +104,7 @@ div.hero.danger {
 }
 
 .bs-docs-sidenav > li {
-  display: block;
+  display: none;
 }
 
 /** MENUE **/
@@ -208,7 +208,7 @@ div.topic {
 /* TOC Toggle Icons for Navigation                                           */
 /* ========================================================================== */
 /* Enable by adding class "toc-toggle-icons-enabled" to sidebar container    */
-/* Configuration: Set html_theme_options['toc_toggle_icons'] = True          */
+/* Configuration: Set html_theme_options['toc_toggle_icons'] = true          */
 /* ========================================================================== */
 
 /* Add expand/collapse icon to items that have children */
diff --git a/src/crate/theme/rtd/crate/static/js/toc-toggle.js b/src/crate/theme/rtd/crate/static/js/toc-toggle.js
index bad52f96e..088b16bb3 100644
--- a/src/crate/theme/rtd/crate/static/js/toc-toggle.js
+++ b/src/crate/theme/rtd/crate/static/js/toc-toggle.js
@@ -51,16 +51,13 @@ function initTocToggle() {
     // Link was already found above, skip if not found
     if (!link) return;
 
-    // Determine initial state
+    // Mark as expanded if in current path
     const isCurrentPath = item.classList.contains('current') ||
                           item.classList.contains('active');
-
-    // Mark as expanded if in current path, otherwise collapsed
     if (isCurrentPath) {
       item.classList.add('expanded');
     }
 
-    // Initialize ARIA attribute
     link.setAttribute('aria-expanded', item.classList.contains('expanded').toString());
 
     // Add click handler to toggle expansion (only if item has direct children to toggle)
@@ -90,8 +87,6 @@ function initTocToggle() {
  */
 function toggleItem(item, link) {
   const isExpanded = item.classList.toggle('expanded');
-  // Force a reflow to ensure the browser applies the new CSS rules immediately.
-  void item.offsetHeight;
   link.setAttribute('aria-expanded', isExpanded.toString());
 }