doc: improve accessibility of expandable lists

aduh95 · marco-ippolito · commit dc9244c9dd1a · 2025-03-06T13:08:45.000+01:00
PR-URL: #56749 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com> Reviewed-By: Claudio Wunder <cwunder@gnome.org>
diff --git a/doc/api_assets/api.js b/doc/api_assets/api.js
@@ -41,6 +41,7 @@
     function closeAllPickers() {
       for (const picker of pickers) {
         picker.parentNode.classList.remove('expanded');
+        picker.ariaExpanded = false;
       }
 
       window.removeEventListener('click', closeAllPickers);
@@ -58,14 +59,15 @@
     for (const picker of pickers) {
       const parentNode = picker.parentNode;
 
+      picker.ariaExpanded = parentNode.classList.contains('expanded');
       picker.addEventListener('click', function(e) {
         e.preventDefault();
 
         /*
           closeAllPickers as window event trigger already closed all the pickers,
           if it already closed there is nothing else to do here
         */
-        if (parentNode.classList.contains('expanded')) {
+        if (picker.ariaExpanded === 'true') {
           return;
         }
 
@@ -75,9 +77,11 @@
         */
 
         requestAnimationFrame(function() {
+          picker.ariaExpanded = true;
           parentNode.classList.add('expanded');
           window.addEventListener('click', closeAllPickers);
           window.addEventListener('keydown', onKeyDown);
+          parentNode.querySelector('.picker a').focus();
         });
       });
     }
diff --git a/doc/api_assets/style.css b/doc/api_assets/style.css
@@ -182,34 +182,29 @@ li.picker-header .picker-arrow {
   height: .6rem;
   border-top: .3rem solid transparent;
   border-bottom: .3rem solid transparent;
-  border-left: .6rem solid var(--color-links);
+  border-left: .6rem solid currentColor;
   border-right: none;
   margin: 0 .2rem .05rem 0;
 }
 
-li.picker-header a:focus .picker-arrow,
-li.picker-header a:active .picker-arrow,
-li.picker-header a:hover .picker-arrow {
-  border-left: .6rem solid var(--white);
-}
-
-li.picker-header.expanded a:focus .picker-arrow,
-li.picker-header.expanded a:active .picker-arrow,
-li.picker-header.expanded a:hover .picker-arrow,
+li.picker-header.expanded .picker-arrow,
+:root:not(.has-js) li.picker-header:focus-within .picker-arrow,
 :root:not(.has-js) li.picker-header:hover .picker-arrow  {
-  border-top: .6rem solid var(--white);
+  border-top: .6rem solid currentColor;
   border-bottom: none;
   border-left: .35rem solid transparent;
   border-right: .35rem solid transparent;
   margin-bottom: 0;
 }
 
 li.picker-header.expanded > a,
+:root:not(.has-js) li.picker-header:focus-within > a,
 :root:not(.has-js) li.picker-header:hover > a {
   border-radius: 2px 2px 0 0;
 }
 
 li.picker-header.expanded > .picker, 
+:root:not(.has-js) li.picker-header:focus-within > .picker,
 :root:not(.has-js) li.picker-header:hover > .picker {
   display: block;
   z-index: 1;
diff --git a/doc/template.html b/doc/template.html
@@ -59,13 +59,13 @@ <h1>Node.js __VERSION__ documentation</h1>
             __GTOC_PICKER__
             __ALTDOCS__
             <li class="picker-header">
-              <a href="#">
+              <a href="#options-picker" aria-controls="options-picker">
                 <span class="picker-arrow"></span>
                 Options
               </a>
         
-              <div class="picker">
-                <ul>
+              <div class="picker" tabindex="-1">
+                <ul id="options-picker">
                   <li>
                     <a href="all.html">View on single page</a>
                   </li>
diff --git a/tools/doc/html.mjs b/tools/doc/html.mjs
@@ -527,11 +527,11 @@ function altDocs(filename, docCreated, versions) {
 
   return list ? `
     <li class="picker-header">
-      <a href="#">
+      <a href="#alt-docs" aria-controls="alt-docs">
         <span class="picker-arrow"></span>
         Other versions
       </a>
-      <div class="picker"><ol id="alt-docs">${list}</ol></div>
+      <div class="picker" tabindex="-1"><ol id="alt-docs">${list}</ol></div>
     </li>
   ` : '';
 }
@@ -557,12 +557,12 @@ function gtocPicker(id) {
 
   return `
     <li class="picker-header">
-      <a href="#">
+      <a href="#gtoc-picker" aria-controls="gtoc-picker">
         <span class="picker-arrow"></span>
         Index
       </a>
 
-      <div class="picker">${gtoc}</div>
+      <div class="picker" tabindex="-1" id="gtoc-picker">${gtoc}</div>
     </li>
   `;
 }
@@ -574,12 +574,12 @@ function tocPicker(id, content) {
 
   return `
     <li class="picker-header">
-      <a href="#">
+      <a href="#toc-picker" aria-controls="toc-picker">
         <span class="picker-arrow"></span>
         Table of contents
       </a>
 
-      <div class="picker">${content.tocPicker}</div>
+      <div class="picker" tabindex="-1">${content.tocPicker.replace('<ul', '<ul id="toc-picker"')}</div>
     </li>
   `;
 }
