Collapsible sidebar (#2159)

Fixes #1072.

Screenshot showing vertical and horizontal alignment guidelines:

<img width="1280" alt="image"
src="https://github.com/user-attachments/assets/8d5194a8-33ce-4aa1-a419-1b85fc5b7353"
/>

---------

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

Author: 4 people

docs/user_guide/layout.rst

@@ -354,15 +354,15 @@ By default, it has the following configuration:
 .. code-block:: python
 
     html_sidebars = {
-        "**": ["sidebar-nav-bs", "sidebar-ethical-ads"]
+        "**": ["sidebar-collapse", "sidebar-nav-bs"]
     }
 
+- ``sidebar-collapse.html`` - a button that allows users to expand and collapse the sidebar.
+
 - ``sidebar-nav-bs.html`` - a bootstrap-friendly navigation section.
 
   When there are no pages to show, it will disappear and potentially add extra space for your page's content.
 
-- ``sidebar-ethical-ads.html`` - a placement for ReadTheDocs's Ethical Ads (will only show up on ReadTheDocs).
-
 Primary sidebar end sections
 ----------------------------
 
@@ -382,6 +382,8 @@ By default, it has the following templates:
       # ...
     }
 
+``sidebar-ethical-ads.html`` is a placement for ReadTheDocs's Ethical Ads (will only show up on ReadTheDocs).
+
 Remove the primary sidebar from pages
 -------------------------------------
 

src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js

@@ -1012,6 +1012,129 @@ async function fetchRevealBannersTogether() {
   }, 320);
 }
 
+/*******************************************************************************
+ * Set up expand/collapse button for primary sidebar
+ */
+function setupCollapseSidebarButton() {
+  const button = document.getElementById("pst-collapse-sidebar-button");
+  const sidebar = document.getElementById("pst-primary-sidebar");
+
+  // If this page rendered without the button or sidebar, then there's nothing to do.
+  if (!button || !sidebar) {
+    return;
+  }
+
+  const sidebarSections = Array.from(sidebar.children);
+
+  const expandTooltip = new bootstrap.Tooltip(button, {
+    title: button.querySelector(".pst-expand-sidebar-label").textContent,
+
+    // In manual testing, relying on Bootstrap to handle "hover" and "focus" was buggy.
+    trigger: "manual",
+
+    placement: "left",
+    fallbackPlacements: ["right"],
+
+    // Offsetting the tooltip a bit more than the default [0, 0] solves an issue
+    // where the appearance of the tooltip triggers a mouseleave event which in
+    // turn triggers the call to hide the tooltip. So in certain areas around
+    // the button, it would appear to the user that tooltip flashes in and then
+    // back out.
+    offset: [0, 12],
+  });
+
+  const showTooltip = () => {
+    // Only show the "expand sidebar" tooltip when the sidebar is not expanded
+    if (button.getAttribute("aria-expanded") === "false") {
+      expandTooltip.show();
+    }
+  };
+  const hideTooltip = () => {
+    expandTooltip.hide();
+  };
+
+  function squeezeSidebar(prefersReducedMotion, done) {
+    // Before squeezing the sidebar, freeze the widths of its subsections.
+    // Otherwise, the subsections will also narrow and cause the text in the
+    // sidebar to reflow and wrap, which we don't want. This is necessary
+    // because we do not remove the sidebar contents from the layout (with
+    // `display: none`). Rather, we hide the contents from both sighted users
+    // and screen readers (with `visibility: hidden`). This provides better
+    // stability to the overall layout.
+    sidebarSections.forEach(
+      (el) => (el.style.width = el.getBoundingClientRect().width + "px"),
+    );
+
+    const afterSqueeze = () => {
+      // After squeezing the sidebar, set aria-expanded to false
+      button.setAttribute("aria-expanded", "false"); // "false" is in quotes because HTML attributes are strings
+
+      button.dataset.busy = false;
+    };
+
+    if (prefersReducedMotion) {
+      sidebar.classList.add("pst-squeeze");
+      afterSqueeze();
+    } else {
+      sidebar.addEventListener("transitionend", function onTransitionEnd() {
+        afterSqueeze();
+        sidebar.removeEventListener("transitionend", onTransitionEnd);
+      });
+      sidebar.classList.add("pst-squeeze");
+    }
+  }
+
+  function expandSidebar(prefersReducedMotion, done) {
+    hideTooltip();
+
+    const afterExpand = () => {
+      // After expanding the sidebar (which may be delayed by a CSS transition),
+      // unfreeze the widths of the subsections that were frozen when the sidebar
+      // was squeezed.
+      sidebarSections.forEach((el) => (el.style.width = null));
+
+      // After expanding the sidebar, set aria-expanded to "true" - in quotes
+      // because HTML attributes are strings.
+      button.setAttribute("aria-expanded", "true");
+
+      button.dataset.busy = false;
+    };
+
+    if (prefersReducedMotion) {
+      sidebar.classList.remove("pst-squeeze");
+      afterExpand();
+    } else {
+      sidebar.addEventListener("transitionend", function onTransitionEnd() {
+        afterExpand();
+        sidebar.removeEventListener("transitionend", onTransitionEnd);
+      });
+      sidebar.classList.remove("pst-squeeze");
+    }
+  }
+
+  button.addEventListener("click", () => {
+    if (button.dataset.busy === "true") {
+      return;
+    }
+    button.dataset.busy = "true";
+
+    const prefersReducedMotion = window.matchMedia(
+      "(prefers-reduced-motion)", // must be in parentheses
+    ).matches;
+
+    if (button.getAttribute("aria-expanded") === "true") {
+      squeezeSidebar(prefersReducedMotion);
+    } else {
+      expandSidebar(prefersReducedMotion);
+    }
+  });
+
+  button.addEventListener("focus", showTooltip);
+  button.addEventListener("mouseenter", showTooltip);
+  button.addEventListener("mouseleave", hideTooltip);
+  button.addEventListener("blur", hideTooltip);
+}
+
 /*******************************************************************************
  * Call functions after document loading.
  */
@@ -1026,6 +1149,15 @@ documentReady(addTOCInteractivity);
 documentReady(setupSearchButtons);
 documentReady(setupSearchAsYouType);
 documentReady(setupMobileSidebarKeyboardHandlers);
+documentReady(() => {
+  try {
+    setupCollapseSidebarButton();
+  } catch (err) {
+    // This exact error message is used in pytest tests
+    console.log("[PST] Error setting up collapse sidebar button");
+    console.error(err);
+  }
+});
 
 // Determining whether an element has scrollable content depends on stylesheets,
 // so we're checking for the "load" event rather than "DOMContentLoaded"

src/pydata_sphinx_theme/assets/styles/components/_sidebar-collapse.scss

@@ -0,0 +1,178 @@
+/**
+ * The collapse/expand primary sidebar button
+ */
+
+.bd-sidebar-primary {
+  .sidebar-primary-item.pst-sidebar-collapse {
+    padding-top: 0;
+  }
+
+  #pst-collapse-sidebar-button {
+    // Only show this button when there's enough width for both sidebar and main
+    // content. Do not show the button in the mobile menu where it would not
+    // make any sense.
+    @include media-breakpoint-down($breakpoint-sidebar-primary) {
+      display: none;
+    }
+
+    border: 0; // reset
+    padding: 0; // reset
+    text-align: start; // reset;
+    background-color: transparent;
+    outline-offset: $focus-ring-offset;
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 0.25rem;
+
+    // min width and height of the button must be 24px to meet WCAG Success Criterion 2.5.8
+    min-width: 24px;
+    min-height: 24px;
+    position: relative;
+    bottom: 0.2em;
+
+    .pst-icon {
+      color: var(--pst-color-link);
+
+      // The padding value was chosen by trial and error. For reference, the
+      // svg-inline--fa class normally applies a -.125em adjustment but this
+      // adjustment doesn't work when the icon is within a flex box. Important:
+      // the padding top value must match the padding bottom value because the
+      // icon undergoes a 180deg rotation when the sidebar is collapsed.
+      padding: 0.4em 0;
+
+      // This value was also chosen by trial and error until it looked good.
+      height: 1.3em;
+    }
+
+    .pst-collapse-sidebar-label {
+      // // inline-flex so we can set dimensions (width, height)
+      // display: inline-flex;
+      width: 100%;
+      height: 100%;
+
+      @include link-style-default;
+    }
+
+    .pst-expand-sidebar-label {
+      // inline-flex so we can set dimensions (width, height)
+      // display: inline-flex;
+
+      // When the sidebar is squeezed, there is no space to show the "expand
+      // sidebar" label. However, the label text is copied to a Bootstrap
+      // tooltip. It's also exposed to screen readers with this
+      // `visually-hidden` mixin from Bootstrap.
+      @include visually-hidden;
+
+      // Turn off for screen readers initially because the sidebar starts off in the expanded state.
+      // When the
+      visibility: hidden;
+    }
+
+    &:hover {
+      .pst-icon {
+        color: var(--pst-color-link-hover);
+      }
+
+      .pst-collapse-sidebar-label {
+        @include link-style-hover;
+      }
+    }
+  }
+
+  // Define transitions (if the environment permits animation)
+  @media (prefers-reduced-motion: no-preference) {
+    $duration: 400ms;
+
+    transition: width $duration ease;
+
+    #pst-collapse-sidebar-button {
+      .pst-icon {
+        transition:
+          transform $duration ease,
+          padding $duration ease;
+      }
+    }
+
+    @each $selector,
+      $delay
+        in (
+          // When the sidebar is collapsing, we need to delay the transition of
+          // properties that make the elements invisible so the user can see the
+          // opacity transition from 1 to 0 first.
+          ".pst-squeeze": $duration,
+          // When the sidebar is expanding, it's the opposite: we need to transition
+          // the properties that make the elements visible immediately so the user
+          // can watch the opacity transition from 0 to 1.
+          ":not(.pst-squeeze)": "0s"
+        )
+    {
+      &#{$selector} {
+        .pst-collapse-sidebar-label {
+          transition:
+            opacity $duration linear,
+            visibility 0s linear $delay,
+            width 0s linear $delay,
+            height 0s linear $delay;
+        }
+
+        .sidebar-primary-item:not(.pst-sidebar-collapse) {
+          transition:
+            opacity $duration linear,
+            visibility 0s linear $delay;
+        }
+
+        // There is no need to transition any other properties on the expand
+        // label (width, height, opacity) because it is always visually hidden
+        // (i.e., width 0, height 0, etc), but toggles its availability to
+        // screen readers as the sidebar collapses or expands via the
+        // `visibility` property.
+        .pst-expand-sidebar-label {
+          transition: visibility 0s linear $delay;
+        }
+      }
+    }
+  }
+
+  // Why "squeeze" and not "collapse"? Bootstrap uses the class name `collapse`
+  // so it seemed best to avoid possible confusion. (Later the class name was
+  // prefixed with `pst-`.)
+  &.pst-squeeze {
+    width: 4rem;
+    overflow: hidden;
+
+    #pst-collapse-sidebar-button {
+      .pst-icon {
+        transform: translateX(0.25em) rotate(180deg);
+      }
+
+      .pst-collapse-sidebar-label {
+        opacity: 0;
+        visibility: hidden;
+        width: 0;
+        height: 0;
+      }
+
+      .pst-expand-sidebar-label {
+        visibility: visible;
+      }
+    }
+
+    .sidebar-primary-item:not(.pst-sidebar-collapse) {
+      opacity: 0;
+      visibility: hidden;
+    }
+  }
+
+  &:not(.pst-squeeze) {
+    // When the sidebar is expanded, hide the "Expand Sidebar" label.
+    .pst-expand-sidebar-label {
+      visibility: hidden;
+    }
+
+    // This block is shorter than its counterpart above because there's no need,
+    // for example, to explicitly set `visibility: visible` or `opacity: 1` on
+    // the collapse label and sidebar subsections because those are the default
+    // values.
+  }
+}

src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss

@@ -49,6 +49,7 @@
 @import "./components/prev-next";
 @import "./components/search";
 @import "./components/searchbox";
+@import "./components/sidebar-collapse";
 @import "./components/switcher-theme";
 @import "./components/switcher-version";
 @import "./components/toc-inpage";

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

@@ -16,10 +16,10 @@ $sidebar-padding-right: 1rem;
   @include make-col(3);
 
   // Borders padding and whitespace
-  padding: 2rem $sidebar-padding-right 1rem 1rem;
+  padding: $sidebar-padding-right;
   border-right: 1px solid var(--pst-color-border);
   background-color: var(--pst-color-background);
-  overflow-y: auto;
+  overflow: hidden auto;
   font-size: var(--pst-sidebar-font-size-mobile);
 
   @include media-breakpoint-up($breakpoint-sidebar-primary) {