Make TOC sections expandable and collapsible by keyboard (#1582)

* Consistent focus ring (first pass) (#1549)

* wip

* Style focus state in header nav

* update focus ring style on all focussable elements

* simplify

* fix links in mobile sidebar overlay

* put focus rings around a few more focusable elements

* polish

* update comment

* review

* better align focus ring on collapsible admonitions

* comment and simplify sphinx-togglebutton focus ring

* make css override more explicit

* Fix SD link-card focus ring and on homepage, bring links inside card

* Update docs/index.md

---------

Co-authored-by: Daniel McCloy <[email protected]>

* Resolve current sidebar link notch and focus ring (#1561)

* Fix sidebar current notch

* focus-ring-radius

* missed a spot 0.125rem

* keep focus ring on top

* Restyle Sphinx Design tabs (#1555)

* restyle sphinx design tabs

* increase panel border radius

* increase line height, zero padding-y

* use shadow variable

* Update src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss

* Update src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss

* Fix tabbed panel colors (#1567)

* aria attributes do not update if user uses mouse instead of keyboard

* details/summary, no checkbox

* clean up

* details["open"]

* make it work for nav level 0

* pull link outside of details tag

* make it work with show nav level 0

* make level 0 heading clickable

* comments

* restore .current notches to toc parents

* fix tests

* clean up

* more comments

* make toggle icon bigger at level 0

* comments

* clarify comment

* remove list-captions class from in-page toc styles

* Update tests/test_build.py

* Update src/pydata_sphinx_theme/toctree.py

Co-authored-by: Tania Allard <[email protected]>

* update test for verbose HTML boolean attribute

* more HTML boolean attribute notation updates

* Update comment about link vs non-link HTML structure

---------

Co-authored-by: Daniel McCloy <[email protected]>
Co-authored-by: Tania Allard <[email protected]>

Author: 3 people

src/pydata_sphinx_theme/assets/styles/components/_navbar-links.scss

@@ -26,30 +26,4 @@
       @include link-style-text;
     }
   }
-
-  /**
-   * Togglable expand/collapse
-   * This is only applicable to the primary sidebar which has these checkboxes
-   */
-  .toctree-checkbox {
-    position: absolute;
-    display: none;
-  }
-
-  .toctree-checkbox {
-    ~ ul {
-      display: none;
-    }
-    ~ label .fa-chevron-down {
-      transform: rotate(0deg);
-    }
-  }
-  .toctree-checkbox:checked {
-    ~ ul {
-      display: block;
-    }
-    ~ label .fa-chevron-down {
-      transform: rotate(180deg);
-    }
-  }
 }

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

@@ -6,8 +6,7 @@ nav.page-toc {
   margin-bottom: 1rem;
 }
 
-.bd-toc .nav,
-.list-caption {
+.bd-toc .nav {
   .nav {
     display: none;
 

src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss

@@ -3,6 +3,7 @@
  * e.g., between-pages navigation.
  */
 
+$sidebar-padding-right: 1rem;
 .bd-sidebar-primary {
   display: flex;
   flex-direction: column;
@@ -13,7 +14,7 @@
   @include make-col(3);
 
   // Borders padding and whitespace
-  padding: 2rem 1rem 1rem 1rem;
+  padding: 2rem $sidebar-padding-right 1rem 1rem;
   border-right: 1px solid var(--pst-color-border);
   background-color: var(--pst-color-background);
   overflow-y: auto;
@@ -140,61 +141,107 @@
   .list-caption {
     list-style: none;
     padding-left: 0px;
-  }
-  li {
-    position: relative;
-    // If it has children, add a bit more padding to wrap the content to avoid
-    // overlapping with the <label>
-    &.has-children {
-      > .reference {
-        padding-right: 30px;
+
+    // Level 0 TOC heading is put inside the <summary> tag
+    // so let the <summary> tag take up more space
+    li.toctree-l0.has-children {
+      > details {
+        > summary {
+          position: relative;
+          height: auto;
+          width: auto;
+          display: flex;
+          justify-content: space-between;
+          align-items: baseline;
+
+          .toctree-toggle {
+            // Prevent toggle icon from getting squished by summary being a
+            // flexbox
+            flex: 0 0 auto;
+
+            // Make the level 0 chevron icon slightly bigger than descendant
+            // levels
+            .fa-chevron-down {
+              font-size: 1rem;
+            }
+          }
+        }
       }
     }
   }
-  // Navigation item chevrons
-  label.toctree-toggle {
-    position: absolute;
-    top: 0;
-    right: 0;
-    height: 30px;
-    width: 30px;
-
-    cursor: pointer;
+  li.has-children {
+    $toctree-toggle-width: 30px;
 
-    display: flex;
-    justify-content: center;
-    align-items: center;
+    position: relative;
 
-    &:hover {
-      background: var(--pst-color-surface);
+    > .reference,
+    .caption {
+      margin-right: calc(
+        $toctree-toggle-width + $focus-ring-width
+      ); // keep clear of the toggle icon
+      padding-top: 0.25rem; // align caption text with toggle chevron
     }
 
-    i {
-      display: inline-block;
-      font-size: 0.75rem;
-      text-align: center;
-      &:hover {
-        color: var(--pst-color-primary);
+    > details {
+      > summary {
+        // Remove browser default toggle icon
+        list-style: none;
+        &::-webkit-details-marker {
+          display: none;
+        }
+
+        // The summary element is natively focusable, but delegate the focus state to the toggle icon
+        &:focus-visible {
+          outline: none;
+
+          > .toctree-toggle {
+            outline: $focus-ring-outline;
+            outline-offset: -$focus-ring-width; // Prevent right side of focus ring from disappearing underneath the sidebar's right edge
+          }
+        }
+
+        // Container for expand/collapse chevron icon
+        .toctree-toggle {
+          cursor: pointer;
+
+          // Position it so that it's aligned with the top right corner of the
+          // last positioned element, in this case the li.has-children
+          position: absolute;
+          top: 0;
+          right: 0;
+
+          // Give it dimensions
+          width: $toctree-toggle-width;
+          height: $toctree-toggle-width; // make it square
+
+          // Vertically and horizontally center the icon within the container
+          display: inline-flex;
+          justify-content: center;
+          align-items: center;
+
+          .fa-chevron-down {
+            font-size: 0.75rem;
+          }
+        }
+      }
+
+      // The section is open/expanded, rotate the toggle icon (chevron) so it
+      // points up instead of down
+      &[open] {
+        > summary {
+          .fa-chevron-down {
+            transform: rotate(180deg);
+          }
+        }
       }
-    }
-  }
-  .label-parts {
-    width: 100%;
-    height: 100%;
-    &:hover {
-      background: none;
-    }
-    i {
-      width: 30px;
-      position: absolute;
-      top: 0.3em; // aligning chevron with text
-      right: 0em; // aligning chevron to the right
     }
   }
 }
 
 /* Between-page links and captions */
 nav.bd-links {
+  margin-right: -$sidebar-padding-right; // align toctree toggle chevrons with right edge of sidebar and allow text to flow closer to the right edge
+
   @include media-breakpoint-up($breakpoint-sidebar-primary) {
     display: block;
   }
@@ -213,6 +260,7 @@ nav.bd-links {
     padding: 0.25rem 0.65rem;
     @include link-sidebar;
     box-shadow: none;
+    margin-right: $focus-ring-width; // prevent the right side focus ring from disappearing under the sidebar right edge
 
     &.reference.external {
       &:after {
@@ -224,11 +272,9 @@ nav.bd-links {
     }
   }
 
-  .current {
-    > a {
-      @include link-sidebar-current;
-      background-color: transparent;
-    }
+  .current > a {
+    @include link-sidebar-current;
+    background-color: transparent;
   }
 
   // Title

src/pydata_sphinx_theme/toctree.py

@@ -339,10 +339,8 @@ def generate_toctree_html(
 
             # Open the sidebar navigation to the proper depth
             for ii in range(int(show_nav_level)):
-                for checkbox in soup.select(
-                    f"li.toctree-l{ii} > input.toctree-checkbox"
-                ):
-                    checkbox.attrs["checked"] = None
+                for details in soup.select(f"li.toctree-l{ii} > details"):
+                    details["open"] = "open"
 
         return soup
 
@@ -422,8 +420,6 @@ def add_collapse_checkboxes(soup: BeautifulSoup) -> None:
     """Add checkboxes to collapse children in a toctree."""
     # based on https://github.com/pradyunsg/furo
 
-    toctree_checkbox_count = 0
-
     for element in soup.find_all("li", recursive=True):
         # We check all "li" elements, to add a "current-page" to the correct li.
         classes = element.get("class", [])
@@ -432,7 +428,7 @@ def add_collapse_checkboxes(soup: BeautifulSoup) -> None:
         if "current" in classes:
             parentli = element.find_parent("li", class_="toctree-l0")
             if parentli:
-                parentli.select("p.caption ~ input")[0].attrs["checked"] = ""
+                parentli.find("details")["open"] = None
 
         # Nothing more to do, unless this has "children"
         if not element.find("ul"):
@@ -441,40 +437,86 @@ def add_collapse_checkboxes(soup: BeautifulSoup) -> None:
         # Add a class to indicate that this has children.
         element["class"] = [*classes, "has-children"]
 
-        # We're gonna add a checkbox.
-        toctree_checkbox_count += 1
-        checkbox_name = f"toctree-checkbox-{toctree_checkbox_count}"
-
-        # Add the "label" for the checkbox which will get filled.
         if soup.new_tag is None:
             continue
 
-        label = soup.new_tag(
-            "label", attrs={"for": checkbox_name, "class": "toctree-toggle"}
-        )
-        label.append(soup.new_tag("i", attrs={"class": "fa-solid fa-chevron-down"}))
-        if "toctree-l0" in classes:
-            # making label cover the whole caption text with css
-            label["class"] = "label-parts"
-        element.insert(1, label)
-
-        # Add the checkbox that's used to store expanded/collapsed state.
-        checkbox = soup.new_tag(
-            "input",
+        # For table of contents nodes that have subtrees, we modify the HTML so
+        # that the subtree can be expanded or collapsed in the browser.
+        #
+        # The HTML markup tree at the parent node starts with this structure:
+        #
+        # - li.has-children
+        #   - a.reference or p.caption
+        #   - ul
+        #
+        # Note the first child of li.has-children is p.caption only if this node
+        # is a section heading. (This only happens when show_nav_level is set to
+        # 0.)
+        #
+        # Now we modify the tree structure in one of two ways.
+        #
+        # (1) If the node holds a section heading, the HTML tree will be
+        # modified like so:
+        #
+        # - li.has-children
+        #   - details
+        #     - summary
+        #       - p.caption
+        #       - .toctree-toggle
+        #     - ul
+        #
+        # (2) Otherwise, if the node holds a link to a page in the docs:
+        #
+        # - li.has-children
+        #   - a.reference
+        #   - details
+        #     - summary
+        #       - .toctree-toggle
+        #   - ul
+        #
+        # Why the difference? In the first case, the TOC section heading is not
+        # a link, but in the second case it is. So in the first case it makes
+        # sense to put the (non-link) text inside the summary tag so that the
+        # user can click either the text or the .toctree-toggle chevron icon to
+        # expand/collapse the TOC subtree. But in the second case, putting the
+        # link in the summary tag would make it unclear whether clicking on the
+        # link should expand the subtree or take you to the link.
+
+        # Create <details> and put the entire subtree into it
+        details = soup.new_tag("details")
+        details.extend(element.contents)
+        element.append(details)
+
+        # Hoist the link to the top if there is one
+        toc_link = element.select_one("details > a.reference")
+        if toc_link:
+            element.insert(0, toc_link)
+
+        # Create <summary> with chevron icon
+        summary = soup.new_tag("summary")
+        span = soup.new_tag(
+            "span",
             attrs={
-                "type": "checkbox",
-                "class": ["toctree-checkbox"],
-                "id": checkbox_name,
-                "name": checkbox_name,
+                "class": "toctree-toggle",
+                "role": "presentation",  # This element and the chevron it contains are purely decorative; the actual expand/collapse functionality is delegated to the <summary> tag
             },
         )
+        span.append(soup.new_tag("i", attrs={"class": "fa-solid fa-chevron-down"}))
+        summary.append(span)
 
-        # if this has a "current" class, be expanded by default
-        # (by checking the checkbox)
-        if "current" in classes:
-            checkbox.attrs["checked"] = ""
+        # Prepend section heading (if there is one) to <summary>
+        collapsible_section_heading = element.select_one("details > p.caption")
+        if collapsible_section_heading:
+            # Put heading inside summary so that the heading text (and chevron) are both clickable
+            summary.insert(0, collapsible_section_heading)
+
+        # Prepend <summary> to <details>
+        details.insert(0, summary)
 
-        element.insert(1, checkbox)
+        # If this TOC node has a "current" class, be expanded by default
+        # (by opening the details/summary disclosure widget)
+        if "current" in classes:
+            details["open"] = "open"
 
 
 def get_nonroot_toctree(