doc: improve accessibility of expandable lists

PR-URL: nodejs/node#56749
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Claudio Wunder <cwunder@gnome.org>

Author: aduh95

src/generators/legacy-html/assets/api.js

@@ -43,6 +43,7 @@
     function closeAllPickers() {
       for (const picker of pickers) {
         picker.parentNode.classList.remove('expanded');
+        picker.ariaExpanded = false;
       }
 
       window.removeEventListener('click', closeAllPickers);
@@ -60,14 +61,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;
         }
 
@@ -77,9 +79,11 @@
         */
 
         requestAnimationFrame(function () {
+          picker.ariaExpanded = true;
           parentNode.classList.add('expanded');
           window.addEventListener('click', closeAllPickers);
           window.addEventListener('keydown', onKeyDown);
+          parentNode.querySelector('.picker a').focus();
         });
       });
     }

src/generators/legacy-html/assets/style.css

@@ -203,34 +203,29 @@ li.picker-header .picker-arrow {
   height: 0.6rem;
   border-top: 0.3rem solid transparent;
   border-bottom: 0.3rem solid transparent;
-  border-left: 0.6rem solid var(--color-links);
+  border-left: 0.6rem solid currentColor;
   border-right: none;
   margin: 0 0.2rem 0.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: 0.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: 0.6rem solid var(--white);
+  border-top: 0.6rem solid currentColor;
   border-bottom: none;
   border-left: 0.35rem solid transparent;
   border-right: 0.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;

src/generators/legacy-html/template.html

@@ -100,12 +100,12 @@ <h1>Node.js __VERSION__ documentation</h1>
               <li class="pinned-header">Node.js __VERSION__</li>
               __TOC_PICKER__ __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>

src/generators/legacy-html/utils/buildDropdowns.mjs

@@ -23,10 +23,10 @@ import {
 const buildToC = tableOfContents => {
   if (tableOfContents.length) {
     return (
-      `<li class="picker-header"><a href="#">` +
+      `<li class="picker-header"><a href="#toc-picker" aria-controls="toc-picker">` +
       `<span class="picker-arrow"></span>` +
       `Table of contents</a><div class="picker">` +
-      `<div class="toc">${tableOfContents}</div></div></li>`
+      `<div class="toc" tabindex="-1">${tableOfContents.replace('<ul', '<ul id="toc-picker"')}</div></div></li>`
     );
   }
 
@@ -42,9 +42,9 @@ const buildToC = tableOfContents => {
  * @param {string} navigationContents The stringified Navigation
  */
 const buildNavigation = navigationContents =>
-  `<li class="picker-header"><a href="#">` +
+  `<li class="picker-header"><a href="#gtoc-picker" aria-controls="gtoc-picker">` +
   `<span class="picker-arrow"></span>Index</a>` +
-  `<div class="picker"><ul><li><a href="index.html">Index</a>` +
+  `<div class="picker" tabindex="-1" id="gtoc-picker"><ul><li><a href="index.html">Index</a>` +
   `</li></ul><hr class="line" />${navigationContents}</div></li>`;
 
 /**
@@ -76,9 +76,9 @@ const buildVersions = (api, added, versions) => {
   });
 
   return (
-    `<li class="picker-header"><a href="#">` +
+    `<li class="picker-header"><a href="#alt-docs" aria-controls="alt-docs">` +
     `<span class="picker-arrow"></span>Other versions</a>` +
-    `<div class="picker"><ol id="alt-docs">${versionsAsList.join('')}</ol></div></li>`
+    `<div class="picker" tabindex="-1"><ol id="alt-docs">${versionsAsList.join('')}</ol></div></li>`
   );
 };