Keyboard handlers to open and close mobile sidebars (#1585)

gabalafou · drammock · 12rambau · web-flow · commit 97f939b671aa · 2024-01-23T13:47:29.000-06:00
* 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 <dan@mccloy.info> * 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) * update feature focus (#1569) * docs: add instructions for custom SVG icons (#1490) * docs: add instructions for custom SVG icons * docs: minor tweaks in SVG icon instructions * docs: some more tweaks to SVG icon instructions * Update docs/user_guide/header-links.rst Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * Change literalinclude to code-block in header links * Update docs/user_guide/header-links.rst Co-authored-by: Daniel McCloy <dan@mccloy.info> * Update docs/user_guide/header-links.rst * Update docs/user_guide/header-links.rst * Update docs/user_guide/header-links.rst * Update docs/user_guide/header-links.rst * Update docs/user_guide/header-links.rst --------- Co-authored-by: tgresavage <thomas.gresavage.ext@afresearchlab.com> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> * fix: make table background transparent (#1546) * fix: make table background transparent * fix: make table background transparent * fix: add color-theme option to html tag (#1536) * Silence warnings (#1542) * avoid webpack warning during asset compile * avoid frozen modules warning during import * try to make jupyterlite quieter * add config option to silence warnings * fix tests * add docs * hide conditional warning logic in utils * bump: 0.14.2 → 0.14.3 * chore: back to dev * docs: add the list of component using a directive (#1476) * fix: create the component list automatically * fix: read the first comment as documentation * docs: add disclaimer on .html suffix * docs: document every component with a simple one liner * fix: use regex to identify comments * update component branch (#15) * Change default logo alt text (#1472) * Default logo alt text only if no extra text * change default logo * use docstitle as default logo alt text * update docs to reflect change * Apply suggestions from code review Co-authored-by: Daniel McCloy <dan@mccloy.info> * use string formatting operator * Update docs/user_guide/branding.rst * docs fixes * Update docs/user_guide/branding.rst * add test * Update pyproject.toml * revert to original --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * chore(i18n) catalan (#1488) i18n: Translate sphinx.po in ca 100% translated source file: 'sphinx.po' on 'ca'. Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> * Build(deps): Bump postcss and css-loader (#1494) Bumps [postcss](https://github.com/postcss/postcss) to 8.4.31 and updates ancestor dependency [css-loader](https://github.com/webpack-contrib/css-loader). These dependencies need to be updated together. Updates `postcss` from 8.4.21 to 8.4.31 - [Release notes](https://github.com/postcss/postcss/releases) - [Changelog](https://github.com/postcss/postcss/blob/main/CHANGELOG.md) - [Commits](postcss/postcss@8.4.21...8.4.31) Updates `css-loader` from 3.6.0 to 6.8.1 - [Release notes](https://github.com/webpack-contrib/css-loader/releases) - [Changelog](https://github.com/webpack-contrib/css-loader/blob/master/CHANGELOG.md) - [Commits](webpack-contrib/css-loader@v3.6.0...v6.8.1) --- updated-dependencies: - dependency-name: postcss dependency-type: indirect - dependency-name: css-loader dependency-type: direct:development ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Revert "Build(deps): Bump postcss and css-loader" (#1509) Revert "Build(deps): Bump postcss and css-loader (#1494)" This reverts commit 185a37a. * Update pst docs buttons (#1502) * call them button-links * copy edit * docs: link back to GitHub from PyPI metadata (#1504) This will add a "Source" link in the PyPI page. * navigation_with_keys = False (#1503) * navigation_with_keys = False * None -> False * Apply suggestions from code review --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * fix: convert "stable" to actual version number (#1512) * convert "stable" to actual version number * fix tests re: navigation_with_keys * try bumping autoapi * refactor: use nbsphinx as the default execution lib (#1482) * refactor: use nbsphinx as the default execution lib * add nbstripout to the pre-commits' * add pandoc to the readthedocs deps * refactor: clean the notebook * move the example to the correct folder * fix: solve link issue * install pandoc in the test environment * fix: display of large table in executed cells * avoid Userwarnings from matplotlib * hide the matplotlib wrning management cell * Update readthedocs.yml * build: use pandoc_binary to install pandoc * docs: add reference to pandoc in the setup * update docs * remove pypandoc_binary * Update pyproject.toml Co-authored-by: gabalafou <gabriel@fouasnon.com> * ci: use back setup-pandoc * Trigger CI build --------- Co-authored-by: Gabriel Fouasnon <gabriel@fouasnon.com> * BUG - Clear alt_text in conf.py (#1471) * comment out alt_text in conf.py * set alt_text to empty string * remove alt_text from conf.py * fix: use 12rambau fork until it's merged with nikeee repo (#1517) * deps: drop support for Sphinx 5 (#1516) * remove ref to myst-nb * update minimal supported version of sphinx * Fix: (webpack.config.js) css-loader API change (#1508) * Fix: (webpack.config.js) css-loader API change The build was broken in <https://github.com/pydata/pydata-sphinx-theme/commit/185a37aa36820f77bffa4c87a772092e9e7cc380>/<https://github.com/pydata/pydata-sphinx-theme/pull/1494>. This change fixes the build, and it seems to be in accordance with the current API as described at <https://github.com/webpack-contrib/css-loader/blob/c6f36cf91ac61743a70e81cfb077faa0f8730ebe/README.md#boolean>. Closes <#1507>. * dedup * restore version bump --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * Fix duplicate HTML IDs (#1425) * Fix duplicate HTML IDs * fix tests * Do not animate the version admonitions colors. (#1424) Otherwise a delay has to be added to the accessibility color contrast checks, to wait for the colors to fully transition. * BUG - Remove redundant ARIA in breadcrumb navigation (#1426) * style(i18n): French Typo fixed (#1430) * Add the ability to add a center section to the footer (#1432) * Add a center section for the footer * Add docs for footer_center * Add a test site for the center footer * test it in our own docs * remove new test site * add footer test --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * Build(deps): Bump actions/checkout from 3 to 4 (#1433) Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](actions/checkout@v3...v4) --- updated-dependencies: - dependency-name: actions/checkout dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Add dropdown_text argument to generate_header_nav_html (#1423) * Add dropdown_text argument to generate_header_nav_html * Add a test, fix typo in theme.conf and remove header_dropdown_text from docs/conf.py * fixed? --------- Co-authored-by: Daniel McCloy <dan@mccloy.info> * fix: rollback ref and Id changes (#1438) * bump: version 0.13.3 → 0.14.0 (#1440) * bump version * update version switcher * back to dev * fix: change the z-index of the dropdown (#1442) In order to be on top of the primary sidebar on small screens. * fix: set the same background for dark/light (#1443) * fix: set the same background for dark/light et the same background color for all state of the search field. It is currently only applied when hovered * fix: wrong css selector * Update src/pydata_sphinx_theme/assets/styles/components/_search.scss * Update src/pydata_sphinx_theme/assets/styles/components/_search.scss * Fix duplicate HTML IDs * fix tests * unique_html_id * backwards-compat generate_header_nav_html * feedback review * update fixture * ughhhh...caching * code cleanup * fix test snapshot * put comment inside def --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> * chore: build the devcontainer automatically in codespace (#1483) * chore: build the devcontainer automaticallyin codespace * refactor: lint * add pandoc to the environment * Fix font color in search input box (#1524) * Fix color * Use --pst-color-text-base * docs: add DecentralChain (#1528) Co-authored-by: jourlez <josuecr.288@gmail.com> * Updates for file src/pydata_sphinx_theme/locale/en/LC_MESSAGES/sphinx.po in ru [Manual Sync] (#1527) i18n: Translate sphinx.po in ru [Manual Sync] 96% of minimum 20% translated source file: 'sphinx.po' on 'ru'. Sync of partially translated files: untranslated content is included with an empty translation or source language content depending on file format Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> * ignore transient errors in windows build CI (#1520) * use warning list * clean up notebook * refactor to pass on all platforms? * simplify * fix logic * iterate backwards * fix plaform detection? also don't log unnecessarily�[H * ignore empty string warnings * remove notebook metawarning * Revert "remove notebook metawarning" This reverts commit 42f4672. * try again * debug the mysterious empty warning * escape color codes * import * triage by intermittency, not by platform; better var names * simplify * fix list.remove * undo what I broke * Update tests/utils/check_warnings.py * refactor: remove extention on component set-up (#1529) * use event.key for search shortcut (#1525) * use event.key for search shortcut * suggestions from review * caps lock --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: gabalafou <gabriel@fouasnon.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ned Batchelder <ned@nedbatchelder.com> Co-authored-by: Adam Porter <adam@alphapapa.net> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Harutaka Kawamura <hkawamura0130@gmail.com> Co-authored-by: jourlez <josuecr.288@gmail.com> * fix: use a directive instead of raw html * fix: make links externals * fix: set reference in paragraphs * fix: missing parameter * fix: use the stem for the component name * refactor: remove never used variables * standardize component descriptions --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: gabalafou <gabriel@fouasnon.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ned Batchelder <ned@nedbatchelder.com> Co-authored-by: Adam Porter <adam@alphapapa.net> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Harutaka Kawamura <hkawamura0130@gmail.com> Co-authored-by: jourlez <josuecr.288@gmail.com> * fix: primer link in docs (#1556) * docs: add data-content (#1559) Reproduce the change made in Sphinx 7 sphinx-doc/sphinx@8e730ae#diff-a5066e933cbf65adc46e0d1ab9a0b44e0a53ca64cc95dca7e6aa902aed6bd468R105 * Obviate background-from-color-variable (#1558) * Obviate background-from-color-variable * backwards compatibility --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: gresavage <tomgresavage@gmail.com> Co-authored-by: tgresavage <thomas.gresavage.ext@afresearchlab.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: gabalafou <gabriel@fouasnon.com> Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ned Batchelder <ned@nedbatchelder.com> Co-authored-by: Adam Porter <adam@alphapapa.net> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Harutaka Kawamura <hkawamura0130@gmail.com> Co-authored-by: jourlez <josuecr.288@gmail.com> Co-authored-by: Chris Holdgraf <choldgraf@berkeley.edu> * Keyboard handlers to open and close mobile sidebars * Update src/pydata_sphinx_theme/__init__.py --------- Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: Daniel McCloy <dan@mccloy.info> Co-authored-by: Rambaud Pierrick <12rambau@users.noreply.github.com> Co-authored-by: gresavage <tomgresavage@gmail.com> Co-authored-by: tgresavage <thomas.gresavage.ext@afresearchlab.com> Co-authored-by: transifex-integration[bot] <43880903+transifex-integration[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ned Batchelder <ned@nedbatchelder.com> Co-authored-by: Adam Porter <adam@alphapapa.net> Co-authored-by: Denis Bitouzé <dbitouze@wanadoo.fr> Co-authored-by: Stuart Mumford <stuart@cadair.com> Co-authored-by: Alenka Frim <AlenkaF@users.noreply.github.com> Co-authored-by: Harutaka Kawamura <hkawamura0130@gmail.com> Co-authored-by: jourlez <josuecr.288@gmail.com> Co-authored-by: Chris Holdgraf <choldgraf@berkeley.edu>
diff --git a/src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js b/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);
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_header.scss b/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 {
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-toggle.scss b/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;
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html b/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>
diff --git a/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/header.html b/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 %}
