Make annotations more accessible (#41163)

components/lib/toggle-annotations.ts

@@ -21,6 +21,22 @@ export default function toggleAnnotation() {
   const annotationButtons = Array.from(document.querySelectorAll('div.BtnGroup button'))
   if (!annotationButtons.length) return
 
+  if (!document.getElementById('tooltip-inline')) {
+    const theSpan = document.createElement('span')
+    theSpan.id = 'tooltip-inline'
+    theSpan.classList.add('visually-hidden')
+    theSpan.innerText = 'Render annotations inline with the code sample.'
+    document.body.appendChild(theSpan)
+  }
+
+  if (!document.getElementById('tooltip-beside')) {
+    const theSpan = document.createElement('span')
+    theSpan.id = 'tooltip-beside'
+    theSpan.classList.add('visually-hidden')
+    theSpan.innerText = 'Render annotations beside the code sample.'
+    document.body.appendChild(theSpan)
+  }
+
   const cookie = validateMode(Cookies.get('annotate-mode')) // will default to beside
   displayAnnotationMode(annotationButtons, cookie)
 
@@ -46,9 +62,13 @@ function setActive(annotationButtons: Array<Element>, targetMode?: string) {
   targetMode = validateMode(targetMode)
   annotationButtons.forEach((el) => {
     if (el.getAttribute('value') === targetMode) {
-      el.ariaSelected = 'true'
+      el.ariaCurrent = 'true'
+      el.classList.add('selected')
       activeElements.push(el)
-    } else el.removeAttribute('aria-selected')
+    } else {
+      el.removeAttribute('aria-current')
+      el.classList.remove('selected')
+    }
   })
 
   if (!activeElements.length)

src/content-render/unified/annotate.js

@@ -134,8 +134,8 @@ function getSubnav() {
       name: 'annotate-display',
       value: 'beside',
       type: 'button',
-      ariaLabel: 'Display annotations beside the code sample',
+      className: 'BtnGroup-item btn btn-sm',
-      className: 'BtnGroup-item btn btn-sm tooltipped tooltipped-nw',
+      ariaDescribedBy: 'tooltip-beside',
     },
     ['Beside'],
   )
@@ -145,8 +145,8 @@ function getSubnav() {
       name: 'annotate-display',
       value: 'inline',
       type: 'button',
-      ariaLabel: 'Display annotations inline as comments of the code sample',
+      className: 'BtnGroup-item btn btn-sm',
-      className: 'BtnGroup-item btn btn-sm tooltipped tooltipped-nw',
+      ariaDescribedBy: 'tooltip-inline',
     },
     ['Inline'],
   )

tests/rendering/__snapshots__/annotate.js.snap

@@ -1,7 +1,7 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`annotate renders annotations 1`] = `
-"<div class="annotate beside"><div class="annotate-header"><header class="d-flex flex-items-center flex-justify-between p-2 text-small rounded-top-1 border-top border-left border-right"><span class="flex-1">YAML</span><div class="BtnGroup"><button name="annotate-display" value="beside" type="button" aria-label="Display annotations beside the code sample" class="BtnGroup-item btn btn-sm tooltipped tooltipped-nw">Beside</button><button name="annotate-display" value="inline" type="button" aria-label="Display annotations inline as comments of the code sample" class="BtnGroup-item btn btn-sm tooltipped tooltipped-nw">Inline</button></div><button class="js-btn-copy btn btn-sm tooltipped tooltipped-nw" aria-label="Copy code to clipboard" data-clipboard="1746955726"><svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-copy" aria-hidden="true"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button><pre hidden data-clipboard="1746955726"># The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
+"<div class="annotate beside"><div class="annotate-header"><header class="d-flex flex-items-center flex-justify-between p-2 text-small rounded-top-1 border-top border-left border-right"><span class="flex-1">YAML</span><div class="BtnGroup"><button name="annotate-display" value="beside" type="button" class="BtnGroup-item btn btn-sm" aria-describedby="tooltip-beside">Beside</button><button name="annotate-display" value="inline" type="button" class="BtnGroup-item btn btn-sm" aria-describedby="tooltip-inline">Inline</button></div><button class="js-btn-copy btn btn-sm tooltipped tooltipped-nw" aria-label="Copy code to clipboard" data-clipboard="1746955726"><svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-copy" aria-hidden="true"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"></path><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"></path></svg></button><pre hidden data-clipboard="1746955726"># The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
 name: Post welcome comment
 
 # Add the \`pull_request\` event, so that the workflow runs automatically