Keyboard handlers to open and close mobile sidebars

src/pydata_sphinx_theme/__init__.py

@@ -16,7 +16,6 @@
 
 __version__ = "0.14.5dev0"
 
-
 def update_config(app):
     """Update config with new default values and handle deprecated keys."""
     # By the time `builder-inited` happens, `app.builder.theme_options` already exists.

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

@@ -562,6 +562,89 @@ if (hasVersionsJSON && (hasSwitcherMenu || wantsWarningBanner)) {
   }
 }
 
+/*******************************************************************************
+ * Add keyboard functionality to mobile sidebars.
+ *
+ * Wire up the hamburger-style buttons using the click event which (on buttons)
+ * handles both mouse clicks and the space and enter keys.
+ */
+function setupMobileSidebarKeyboardHandlers() {
+  // These are hidden checkboxes at the top of the page whose :checked property
+  // allows the mobile sidebars to be hidden or revealed via CSS.
+  const primaryToggle = document.getElementById("pst-primary-sidebar-checkbox");
+  const secondaryToggle = document.getElementById(
+    "pst-secondary-sidebar-checkbox"
+  );
+  const primarySidebar = document.querySelector(".bd-sidebar-primary");
+  const secondarySidebar = document.querySelector(".bd-sidebar-secondary");
+
+  // Toggle buttons -
+  //
+  // These are the hamburger-style buttons in the header nav bar. When the user
+  // clicks, the button transmits the click to the hidden checkboxes used by the
+  // CSS to control whether the sidebar is open or closed.
+  const primaryClickTransmitter = document.querySelector(".primary-toggle");
+  const secondaryClickTransmitter = document.querySelector(".secondary-toggle");
+  [
+    [primaryClickTransmitter, primaryToggle, primarySidebar],
+    [secondaryClickTransmitter, secondaryToggle, secondarySidebar],
+  ].forEach(([clickTransmitter, toggle, sidebar]) => {
+    if (!clickTransmitter) {
+      return;
+    }
+    clickTransmitter.addEventListener("click", (event) => {
+      event.preventDefault();
+      event.stopPropagation();
+      toggle.checked = !toggle.checked;
+
+      // If we are opening the sidebar, move focus to the first focusable item
+      // in the sidebar
+      if (toggle.checked) {
+        // Note: this selector is not exhaustive, and we may need to update it
+        // in the future
+        const tabStop = sidebar.querySelector("a, button");
+        // use setTimeout because you cannot move focus synchronously during a
+        // click in the handler for the click event
+        setTimeout(() => tabStop.focus(), 100);
+      }
+    });
+  });
+
+  // Escape key -
+  //
+  // When sidebar is open, user should be able to press escape key to close the
+  // sidebar.
+  [
+    [primarySidebar, primaryToggle, primaryClickTransmitter],
+    [secondarySidebar, secondaryToggle, secondaryClickTransmitter],
+  ].forEach(([sidebar, toggle, transmitter]) => {
+    if (!sidebar) {
+      return;
+    }
+    sidebar.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        event.stopPropagation();
+        toggle.checked = false;
+        transmitter.focus();
+      }
+    });
+  });
+
+  // When the <label> overlay is clicked to close the sidebar, return focus to
+  // the opener button in the nav bar.
+  [
+    [primaryToggle, primaryClickTransmitter],
+    [secondaryToggle, secondaryClickTransmitter],
+  ].forEach(([toggle, transmitter]) => {
+    toggle.addEventListener("change", (event) => {
+      if (!event.currentTarget.checked) {
+        transmitter.focus();
+      }
+    });
+  });
+}
+
 /*******************************************************************************
  * Call functions after document loading.
  */
@@ -571,3 +654,4 @@ documentReady(scrollToActive);
 documentReady(addTOCInteractivity);
 documentReady(setupSearchButtons);
 documentReady(initRTDObserver);
+documentReady(setupMobileSidebarKeyboardHandlers);

src/pydata_sphinx_theme/assets/styles/sections/_header.scss

@@ -176,8 +176,8 @@
 
 // Hide the header items on mobile
 .bd-header {
-  // Toggle labels
-  label {
+  // Toggle buttons
+  button {
     &.sidebar-toggle {
       display: flex;
       cursor: pointer;
@@ -186,6 +186,8 @@
       color: var(--pst-color-muted);
       margin-bottom: 0;
       padding-bottom: 0.25rem;
+      background-color: inherit;
+      border: none;
     }
 
     &.primary-toggle {

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

@@ -28,20 +28,22 @@ label.overlay {
 
 input {
   // Show the correct overlay when its input is checked
-  &#__primary:checked + label.overlay.overlay-primary,
-  &#__secondary:checked + label.overlay.overlay-secondary {
+  &#pst-primary-sidebar-checkbox:checked + label.overlay.overlay-primary,
+  &#pst-secondary-sidebar-checkbox:checked + label.overlay.overlay-secondary {
     height: 100vh;
     width: 100vw;
   }
 
   // Primary sidebar slides in from the left
-  &#__primary:checked ~ .bd-container .bd-sidebar-primary {
+  &#pst-primary-sidebar-checkbox:checked ~ .bd-container .bd-sidebar-primary {
     visibility: visible;
     margin-left: 0;
   }
 
   // Secondary sidebar slides in from the right
-  &#__secondary:checked ~ .bd-container .bd-sidebar-secondary {
+  &#pst-secondary-sidebar-checkbox:checked
+    ~ .bd-container
+    .bd-sidebar-secondary {
     visibility: visible;
     margin-right: 0;
   }
@@ -82,11 +84,11 @@ input {
 
 // Primary sidebar hides/shows at earlier widths
 @include media-breakpoint-up($breakpoint-sidebar-primary) {
-  label.sidebar-toggle.primary-toggle {
+  .sidebar-toggle.primary-toggle {
     display: none;
   }
 
-  input#__primary {
+  input#pst-primary-sidebar-checkbox {
     &:checked + label.overlay.overlay-primary {
       height: 0;
       width: 0;

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

@@ -67,15 +67,13 @@
   {# checkbox to toggle primary sidebar #}
   <input type="checkbox"
           class="sidebar-toggle"
-          name="__primary"
-          id="__primary"/>
-  <label class="overlay overlay-primary" for="__primary"></label>
+          id="pst-primary-sidebar-checkbox"/>
+  <label class="overlay overlay-primary" for="pst-primary-sidebar-checkbox"></label>
   {# Checkboxes to toggle the secondary sidebar #}
   <input type="checkbox"
           class="sidebar-toggle"
-          name="__secondary"
-          id="__secondary"/>
-  <label class="overlay overlay-secondary" for="__secondary"></label>
+          id="pst-secondary-sidebar-checkbox"/>
+  <label class="overlay overlay-secondary" for="pst-secondary-sidebar-checkbox"></label>
   {# A search field pop-up that will only show when the search button is clicked #}
   <div class="search-button__wrapper">
     <div class="search-button__overlay"></div>

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html

@@ -1,8 +1,8 @@
 {% if theme_navbar_start or theme_navbar_center or theme_navbar_end or theme_navbar_persistent %}
 <div class="bd-header__inner bd-page-width">
-  <label class="sidebar-toggle primary-toggle" for="__primary">
+  <button class="sidebar-toggle primary-toggle" aria-label="{{ _('Site navigation') }}">
     <span class="fa-solid fa-bars"></span>
-  </label>
+  </button>
   {% set navbar_start, navbar_class, navbar_align = navbar_align_class() %}
   {% if theme_navbar_start %}
   <div class="{{ navbar_start }} navbar-header-items__start">
@@ -40,9 +40,9 @@
   {% endfor %}
 
   {% if not remove_sidebar_secondary %}
-    <label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0">
+    <button class="sidebar-toggle secondary-toggle" aria-label="{{ _('On this page') }}">
       <span class="fa-solid fa-outdent"></span>
-    </label>
+    </button>
   {% endif %}
 </div>
 {% endif %}