From ad012ca1f3b84639fb081882923def33f54990a2 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Sun, 26 Jan 2025 19:31:35 +0100
Subject: [PATCH] doc: improve accessibility of expandable lists
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR-URL: https://github.com/nodejs/node/pull/56749
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ulises Gascón <ulisesgascongonzalez@gmail.com>
Reviewed-By: Claudio Wunder <cwunder@gnome.org>
---
 doc/api_assets/api.js    |  6 +++++-
 doc/api_assets/style.css | 17 ++++++-----------
 doc/template.html        |  6 +++---
 tools/doc/html.mjs       | 12 ++++++------
 4 files changed, 20 insertions(+), 21 deletions(-)

diff --git a/doc/api_assets/api.js b/doc/api_assets/api.js
index 394b5ba990946c..e86f110e0346bf 100644
--- 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,6 +59,7 @@
     for (const picker of pickers) {
       const parentNode = picker.parentNode;
 
+      picker.ariaExpanded = parentNode.classList.contains('expanded');
       picker.addEventListener('click', function(e) {
         e.preventDefault();
 
@@ -65,7 +67,7 @@
           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
index 28a284e3b975b8..a40990a39252a4 100644
--- a/doc/api_assets/style.css
+++ b/doc/api_assets/style.css
@@ -182,22 +182,15 @@ 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;
@@ -205,11 +198,13 @@ li.picker-header.expanded a:hover .picker-arrow,
 }
 
 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
index ab8be0e747f492..51e789b7e6168c 100644
--- 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
index 68762d89e048ce..d61d335c7b8957 100644
--- 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>
   `;
 }