BUG: fix highlighting of current version in switcher menu (#1357)

* cherry-pick changes from 1305

Co-authored-by: Julianus Pfeuffer <[email protected]>

* update switcher IDs and fix broken tests

* fix another one

* fix rebase snafu

* JS fixes

* update highlighting test for new color theme

* more rebase cruft

* fix ARIA roles

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

* fix tests

* Update src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/version-switcher.html

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

* Update tests/test_build/navbar_switcher.html

---------

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

Author: 3 people

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

@@ -357,6 +357,7 @@ if (versionSwitcherBtns.length) {
     const anchor = document.createElement("a");
     anchor.setAttribute("class", "list-group-item list-group-item-action py-1");
     anchor.setAttribute("href", `${entry.url}${currentFilePath}`);
+    anchor.setAttribute("role", "option");
     const span = document.createElement("span");
     span.textContent = `${entry.name}`;
     anchor.appendChild(span);
@@ -368,10 +369,11 @@ if (versionSwitcherBtns.length) {
     // this version, rather than using sphinx's {{ version }} variable.
     // also highlight the dropdown entry for the currently-viewed
     // version's entry
-    if (entry.version == DOCUMENTATION_OPTIONS.version_switcher_version_match) {
+    if (entry.version == DOCUMENTATION_OPTIONS.theme_switcher_version_match) {
       anchor.classList.add("active");
       versionSwitcherBtns.forEach((btn) => {
-        btn.innerText = btn.dataset["activeVersionName"] = entry.name;
+        btn.innerText = entry.name;
+        btn.dataset["activeVersionName"] = entry.name;
         btn.dataset["activeVersion"] = entry.version;
       });
     }

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/version-switcher.html

@@ -3,11 +3,11 @@
 <script>
 document.write(`
   <div class="version-switcher__container dropdown">
-    <button type="button" class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle" data-bs-toggle="dropdown">
+    <button id="versionswitcherbutton" type="button" role="button" class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle" data-bs-toggle="dropdown" aria-haspopup="listbox" aria-controls="versionswitcherlist" aria-label="Version switcher list">
       {{ theme_switcher.get('version_match') }}  <!-- this text may get changed later by javascript -->
       <span class="caret"></span>
     </button>
-    <div class="version-switcher__menu dropdown-menu list-group-flush py-0">
+    <div id="versionswitcherlist" class="version-switcher__menu dropdown-menu list-group-flush py-0" role="listbox" aria-labelledby="versionswitcherbutton">
     <!-- dropdown will be populated by javascript on page load -->
     </div>
   </div>

tests/test_a11y.py

@@ -12,7 +12,7 @@
 
 # Using importorskip to ensure these tests are only loaded if Playwright is installed.
 playwright = pytest.importorskip("playwright")
-from playwright.sync_api import Page  # noqa: E402
+from playwright.sync_api import Page, expect  # noqa: E402
 
 # Important note: automated accessibility scans can only find a fraction of
 # potential accessibility issues.
@@ -112,3 +112,19 @@ def test_axe_core_kitchen_sink(
 
     # Expect Axe-core to have found 0 accessibility violations
     assert len(results["violations"]) == 0, pretty_axe_results(results, selector)
+
+
+def test_version_switcher_highlighting(page: Page, url_base: str) -> None:
+    """This isn't an a11y test, but needs a served site for Javascript to inject the version menu."""
+    page.goto(url=url_base)
+    # no need to include_hidden here ↓↓↓, we just need to get the active version name
+    button = page.get_by_role("button").filter(has_text="dev")
+    active_version_name = button.get_attribute("data-active-version-name")
+    # here we do include_hidden, so sidebar & topbar menus should each have a matching entry:
+    entries = page.get_by_role("option", include_hidden=True).filter(
+        has_text=active_version_name
+    )
+    assert entries.count() == 2
+    # make sure they're highlighted
+    for entry in entries.all():
+        expect(entry).to_have_css("color", "rgb(10, 125, 145)")

tests/test_build.py

@@ -648,12 +648,14 @@ def test_show_nav_level(sphinx_build_factory) -> None:
         assert "checked" in checkbox.attrs
 
 
+# the switcher files tested in test_version_switcher_error_states, not all of them exist
 switcher_files = ["switcher.json", "http://a.b/switcher.json", "missing_url.json"]
-"the switcher files tested in test_version_switcher, not all of them exist"
 
 
 @pytest.mark.parametrize("url", switcher_files)
-def test_version_switcher(sphinx_build_factory, file_regression, url) -> None:
+def test_version_switcher_error_states(
+    sphinx_build_factory, file_regression, url
+) -> None:
     """Regression test the version switcher dropdown HTML.
 
     Note that a lot of the switcher HTML gets populated by JavaScript,
@@ -878,7 +880,7 @@ def test_translations(sphinx_build_factory) -> None:
     assert "Créé en utilisant" in str(footer)
     assert "Construit avec le" in str(footer)
 
-    footer_article = index.select(".prev-next-footer")[0]
+    footer_article = index.select(".prev-next-area")[0]
     assert "précédent" in str(footer_article)
     assert "page suivante" in str(footer_article)
 

tests/test_build/navbar_switcher.html

@@ -1,11 +1,11 @@
 <script>
  document.write(`
   <div class="version-switcher__container dropdown">
-    <button type="button" class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle" data-bs-toggle="dropdown">
+    <button id="versionswitcherbutton" type="button" role="button" class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle" data-bs-toggle="dropdown" aria-haspopup="listbox" aria-controls="versionswitcherlist" aria-label="Version switcher list">
       0.7.1  <!-- this text may get changed later by javascript -->
       <span class="caret"></span>
     </button>
-    <div class="version-switcher__menu dropdown-menu list-group-flush py-0">
+    <div id="versionswitcherlist" class="version-switcher__menu dropdown-menu list-group-flush py-0" role="listbox" aria-labelledby="versionswitcherbutton">
     <!-- dropdown will be populated by javascript on page load -->
     </div>
   </div>