Fix: Accessibility roles and aria labels (#2304)

* Fix “main” role * Fix primary navigation role and aria label * Fix secondary navigation aria label * Fix progress bar role and aria labels * Fix cover page role and aria label * Fix search role * Fix search results aria labels * Add search results status element * Update snapshots with new roles and aria labels
docsifyjs · Nov 29, 2023 · da43bd7 · da43bd7 · vercel · Nov 29, 2023
1 parent dac8e59
commit da43bd7
Show file tree

Hide file tree

Showing 5 changed files with 31 additions and 12 deletions.
diff --git a/src/core/render/index.js b/src/core/render/index.js
@@ -416,6 +416,8 @@ export function Render(Base) {
       let navAppendToTarget = dom.body;
 
       if (el) {
+        navEl.setAttribute('aria-label', 'secondary');
+
         if (config.repo) {
           html += tpl.corner(config.repo, config.cornerExternalLinkTarget);
         }

diff --git a/src/core/render/progressbar.js b/src/core/render/progressbar.js
@@ -10,6 +10,10 @@ function init() {
   const div = dom.create('div');
 
   div.classList.add('progress');
+  div.setAttribute('role', 'progressbar');
+  div.setAttribute('aria-valuemin', '0');
+  div.setAttribute('aria-valuemax', '100');
+  div.setAttribute('aria-label', 'Loading...');
   dom.appendTo(dom.body, div);
   barEl = div;
 }
@@ -33,13 +37,15 @@ export default function (info) {
 
   barEl.style.opacity = 1;
   barEl.style.width = num >= 95 ? '100%' : num + '%';
+  barEl.setAttribute('aria-valuenow', num >= 95 ? 100 : num);
 
   if (num >= 95) {
     clearTimeout(timeId);
     // eslint-disable-next-line no-unused-vars
     timeId = setTimeout(_ => {
       barEl.style.opacity = 0;
       barEl.style.width = '0%';
+      barEl.removeAttribute('aria-valuenow');
     }, 200);
   }
 }
diff --git a/src/core/render/tpl.js b/src/core/render/tpl.js
@@ -42,7 +42,7 @@ export function main(config) {
         <span></span><span></span><span></span>
       </div>
     </button>
-    <aside class="sidebar">
+    <aside class="sidebar" role="none">
       ${
         config.name
           ? /* html */ `
@@ -52,14 +52,14 @@ export function main(config) {
           `
           : ''
       }
-      <div class="sidebar-nav"><!--sidebar--></div>
+      <div class="sidebar-nav" role="navigation" aria-label="primary"><!--sidebar--></div>
     </aside>
   `;
 
   return /* html */ `
-    <main>${aside}
+    <main role="presentation">${aside}
       <section class="content">
-        <article class="markdown-section" id="main"><!--main--></article>
+        <article class="markdown-section" id="main" role="main"><!--main--></article>
       </section>
     </main>
   `;
@@ -80,7 +80,7 @@ export function cover() {
   `;
 
   return /* html */ `
-    <section class="cover show" style="background: ${bgc}">
+    <section class="cover show" role="complementary" aria-label="cover" style="background: ${bgc}">
       <div class="mask"></div>
       <div class="cover-main"><!--cover--></div>
     </section>

diff --git a/src/plugins/search/component.js b/src/plugins/search/component.js
@@ -21,6 +21,11 @@ function style() {
   align-items: center;
 }
 
+.search .results-status:not(:empty) {
+  margin-top: 10px;
+  font-size: smaller;
+}
+
 .search .results-panel {
   display: none;
 }
@@ -122,12 +127,14 @@ function tpl(defaultValue = '') {
         </svg>
       </div>
     </div>
+    <div class="results-status" aria-live="polite"></div>
     <div class="results-panel"></div>
   `;
   const el = Docsify.dom.create('div', html);
   const aside = Docsify.dom.find('aside');
 
   Docsify.dom.toggleClass(el, 'search');
+  el.setAttribute('role', 'search');
   Docsify.dom.before(aside, el);
 }
 
@@ -136,12 +143,14 @@ function doSearch(value) {
   const $panel = Docsify.dom.find($search, '.results-panel');
   const $clearBtn = Docsify.dom.find($search, '.clear-button');
   const $sidebarNav = Docsify.dom.find('.sidebar-nav');
+  const $status = Docsify.dom.find('div.search .results-status');
   const $appName = Docsify.dom.find('.app-name');
 
   if (!value) {
     $panel.classList.remove('show');
     $clearBtn.classList.remove('show');
     $panel.innerHTML = '';
+    $status.textContent = '';
 
     if (options.hideOtherSidebarContent) {
       $sidebarNav && $sidebarNav.classList.remove('hide');
@@ -151,12 +160,12 @@ function doSearch(value) {
     return;
   }
 
-  const matchs = search(value);
+  const matches = search(value);
 
   let html = '';
-  matchs.forEach(post => {
+  matches.forEach((post, i) => {
     html += /* html */ `
-      <div class="matching-post">
+      <div class="matching-post" aria-label="search result ${i + 1}">
         <a href="${post.url}">
           <h2>${post.title}</h2>
           <p>${post.content}</p>
@@ -168,6 +177,8 @@ function doSearch(value) {
   $panel.classList.add('show');
   $clearBtn.classList.add('show');
   $panel.innerHTML = html || /* html */ `<p class="empty">${NO_DATA_TEXT}</p>`;
+  $status.textContent = `Found ${matches.length} results`;
+
   if (options.hideOtherSidebarContent) {
     $sidebarNav && $sidebarNav.classList.add('hide');
     $appName && $appName.classList.add('hide');

diff --git a/test/integration/__snapshots__/docs.test.js.snap b/test/integration/__snapshots__/docs.test.js.snap
@@ -1,7 +1,7 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Docs Site coverpage renders and is unchanged 1`] = `
-"<section class=\\"cover show\\" style=\\"background: 
+"<section class=\\"cover show\\" role=\\"complementary\\" aria-label=\\"cover\\" style=\\"background: 
     linear-gradient(
       to left bottom,
       hsl(127, 100%, 85%) 0%,
@@ -16,11 +16,11 @@ exports[`Docs Site coverpage renders and is unchanged 1`] = `
     </section>"
 `;
 
-exports[`Docs Site navbar renders and is unchanged 1`] = `"<nav class=\\"app-nav no-badge\\"><ul><li>Translations<ul><li><a href=\\"#/\\" title=\\"undefined\\" class=\\"active\\"><img src=\\"https://github.githubassets.com/images/icons/emoji/unicode/1f1ec-1f1e7.png?v8.png\\" alt=\\"uk\\" class=\\"emoji\\" loading=\\"lazy\\"> English</a></li><li><a href=\\"#/zh-cn/\\" title=\\"undefined\\"><img src=\\"https://github.githubassets.com/images/icons/emoji/unicode/1f1e8-1f1f3.png?v8.png\\" alt=\\"cn\\" class=\\"emoji\\" loading=\\"lazy\\"> 简体中文</a></li><li><a href=\\"#/de-de/\\" title=\\"undefined\\"><img src=\\"https://github.githubassets.com/images/icons/emoji/unicode/1f1e9-1f1ea.png?v8.png\\" alt=\\"de\\" class=\\"emoji\\" loading=\\"lazy\\"> Deutsch</a></li><li><a href=\\"#/es/\\" title=\\"undefined\\"><img src=\\"https://github.githubassets.com/images/icons/emoji/unicode/1f1ea-1f1f8.png?v8.png\\" alt=\\"es\\" class=\\"emoji\\" loading=\\"lazy\\"> Español</a></li><li><a href=\\"#/ru-ru/\\" title=\\"undefined\\"><img src=\\"https://github.githubassets.com/images/icons/emoji/unicode/1f1f7-1f1fa.png?v8.png\\" alt=\\"ru\\" class=\\"emoji\\" loading=\\"lazy\\"> Русский</a></li></ul></li></ul></nav>"`;
+exports[`Docs Site navbar renders and is unchanged 1`] = `"<nav aria-label=\\"secondary\\" class=\\"app-nav no-badge\\"><ul><li>Translations<ul><li><a href=\\"#/\\" title=\\"undefined\\" class=\\"active\\"><img src=\\"https://github.githubassets.com/images/icons/emoji/unicode/1f1ec-1f1e7.png?v8.png\\" alt=\\"uk\\" class=\\"emoji\\" loading=\\"lazy\\"> English</a></li><li><a href=\\"#/zh-cn/\\" title=\\"undefined\\"><img src=\\"https://github.githubassets.com/images/icons/emoji/unicode/1f1e8-1f1f3.png?v8.png\\" alt=\\"cn\\" class=\\"emoji\\" loading=\\"lazy\\"> 简体中文</a></li><li><a href=\\"#/de-de/\\" title=\\"undefined\\"><img src=\\"https://github.githubassets.com/images/icons/emoji/unicode/1f1e9-1f1ea.png?v8.png\\" alt=\\"de\\" class=\\"emoji\\" loading=\\"lazy\\"> Deutsch</a></li><li><a href=\\"#/es/\\" title=\\"undefined\\"><img src=\\"https://github.githubassets.com/images/icons/emoji/unicode/1f1ea-1f1f8.png?v8.png\\" alt=\\"es\\" class=\\"emoji\\" loading=\\"lazy\\"> Español</a></li><li><a href=\\"#/ru-ru/\\" title=\\"undefined\\"><img src=\\"https://github.githubassets.com/images/icons/emoji/unicode/1f1f7-1f1fa.png?v8.png\\" alt=\\"ru\\" class=\\"emoji\\" loading=\\"lazy\\"> Русский</a></li></ul></li></ul></nav>"`;
 
 exports[`Docs Site sidebar renders and is unchanged 1`] = `
-"<aside class=\\"sidebar\\">
+"<aside class=\\"sidebar\\" role=\\"none\\">
       
-      <div class=\\"sidebar-nav\\"><ul><li><p>Getting started</p><ul><li><a href=\\"#/quickstart\\" title=\\"undefined\\">Quick start</a></li><li><a href=\\"#/more-pages\\" title=\\"undefined\\">Writing more pages</a></li><li><a href=\\"#/custom-navbar\\" title=\\"undefined\\">Custom navbar</a></li><li><a href=\\"#/cover\\" title=\\"undefined\\">Cover page</a></li></ul></li><li><p>Customization</p><ul><li><a href=\\"#/configuration\\" title=\\"undefined\\">Configuration</a></li><li><a href=\\"#/themes\\" title=\\"undefined\\">Themes</a></li><li><a href=\\"#/plugins\\" title=\\"undefined\\">List of Plugins</a></li><li><a href=\\"#/write-a-plugin\\" title=\\"undefined\\">Write a Plugin</a></li><li><a href=\\"#/markdown\\" title=\\"undefined\\">Markdown configuration</a></li><li><a href=\\"#/language-highlight\\" title=\\"undefined\\">Language highlighting</a></li><li><a href=\\"#/emoji\\" title=\\"undefined\\">Emoji</a></li></ul></li><li><p>Guide</p><ul><li><a href=\\"#/deploy\\" title=\\"undefined\\">Deploy</a></li><li><a href=\\"#/helpers\\" title=\\"undefined\\">Helpers</a></li><li><a href=\\"#/vue\\" title=\\"undefined\\">Vue compatibility</a></li><li><a href=\\"#/cdn\\" title=\\"undefined\\">CDN</a></li><li><a href=\\"#/pwa\\" title=\\"undefined\\">Offline Mode (PWA)</a></li><li><a href=\\"#/embed-files\\" title=\\"undefined\\">Embed Files</a></li></ul></li><li><p><a href=\\"#/awesome\\" title=\\"undefined\\">Awesome docsify</a></p></li><li><p><a href=\\"#/changelog\\" title=\\"undefined\\">Changelog</a></p></li></ul></div>
+      <div class=\\"sidebar-nav\\" role=\\"navigation\\" aria-label=\\"primary\\"><ul><li><p>Getting started</p><ul><li><a href=\\"#/quickstart\\" title=\\"undefined\\">Quick start</a></li><li><a href=\\"#/more-pages\\" title=\\"undefined\\">Writing more pages</a></li><li><a href=\\"#/custom-navbar\\" title=\\"undefined\\">Custom navbar</a></li><li><a href=\\"#/cover\\" title=\\"undefined\\">Cover page</a></li></ul></li><li><p>Customization</p><ul><li><a href=\\"#/configuration\\" title=\\"undefined\\">Configuration</a></li><li><a href=\\"#/themes\\" title=\\"undefined\\">Themes</a></li><li><a href=\\"#/plugins\\" title=\\"undefined\\">List of Plugins</a></li><li><a href=\\"#/write-a-plugin\\" title=\\"undefined\\">Write a Plugin</a></li><li><a href=\\"#/markdown\\" title=\\"undefined\\">Markdown configuration</a></li><li><a href=\\"#/language-highlight\\" title=\\"undefined\\">Language highlighting</a></li><li><a href=\\"#/emoji\\" title=\\"undefined\\">Emoji</a></li></ul></li><li><p>Guide</p><ul><li><a href=\\"#/deploy\\" title=\\"undefined\\">Deploy</a></li><li><a href=\\"#/helpers\\" title=\\"undefined\\">Helpers</a></li><li><a href=\\"#/vue\\" title=\\"undefined\\">Vue compatibility</a></li><li><a href=\\"#/cdn\\" title=\\"undefined\\">CDN</a></li><li><a href=\\"#/pwa\\" title=\\"undefined\\">Offline Mode (PWA)</a></li><li><a href=\\"#/embed-files\\" title=\\"undefined\\">Embed Files</a></li></ul></li><li><p><a href=\\"#/awesome\\" title=\\"undefined\\">Awesome docsify</a></p></li><li><p><a href=\\"#/changelog\\" title=\\"undefined\\">Changelog</a></p></li></ul></div>
     </aside>"
 `;