Add accessible name to tooltip portal element with id theme-picker-tooltip

Author: webstackdev

axe-results-incomplete.json

@@ -0,0 +1,42 @@
+[
+  {
+    "id": "aria-valid-attr-value",
+    "impact": "critical",
+    "tags": [
+      "cat.aria",
+      "wcag2a",
+      "wcag412",
+      "EN-301-549",
+      "EN-9.4.1.2",
+      "RGAAv4",
+      "RGAA-7.1.1"
+    ],
+    "description": "Ensure all ARIA attributes have valid values",
+    "help": "ARIA attributes must conform to valid values",
+    "helpUrl": "https://dequeuniversity.com/rules/axe/4.11/aria-valid-attr-value?application=playwright",
+    "nodes": [
+      {
+        "any": [],
+        "all": [
+          {
+            "id": "aria-valid-attr-value",
+            "data": {
+              "messageKey": "controlsWithinPopup",
+              "needsReview": "aria-controls=\"theme-picker-panel\""
+            },
+            "relatedNodes": [],
+            "impact": "critical",
+            "message": "Unable to determine if aria-controls referenced ID exists on the page while using aria-haspopup: aria-controls=\"theme-picker-panel\""
+          }
+        ],
+        "none": [],
+        "impact": "critical",
+        "html": "<button class=\"theme-toggle-btn the...\" type=\"button\" aria-expanded=\"false\" aria-controls=\"theme-picker-panel\" aria-label=\"toggle theme switche...\" aria-haspopup=\"true\" data-theme-toggle=\"\">",
+        "target": [
+          ".theme-toggle-btn"
+        ],
+        "failureSummary": "Fix all of the following:\n  Unable to determine if aria-controls referenced ID exists on the page while using aria-haspopup: aria-controls=\"theme-picker-panel\""
+      }
+    ]
+  }
+]

axe-results-violations.json

@@ -0,0 +1,60 @@
+[
+  {
+    "id": "aria-tooltip-name",
+    "impact": "serious",
+    "tags": [
+      "cat.aria",
+      "wcag2a",
+      "wcag412",
+      "EN-301-549",
+      "EN-9.4.1.2"
+    ],
+    "description": "Ensure every ARIA tooltip node has an accessible name",
+    "help": "ARIA tooltip nodes must have an accessible name",
+    "helpUrl": "https://dequeuniversity.com/rules/axe/4.11/aria-tooltip-name?application=playwright",
+    "nodes": [
+      {
+        "any": [
+          {
+            "id": "has-visible-text",
+            "data": null,
+            "relatedNodes": [],
+            "impact": "serious",
+            "message": "Element does not have text that is visible to screen readers"
+          },
+          {
+            "id": "aria-label",
+            "data": null,
+            "relatedNodes": [],
+            "impact": "serious",
+            "message": "aria-label attribute does not exist or is empty"
+          },
+          {
+            "id": "aria-labelledby",
+            "data": null,
+            "relatedNodes": [],
+            "impact": "serious",
+            "message": "aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty"
+          },
+          {
+            "id": "non-empty-title",
+            "data": {
+              "messageKey": "noAttr"
+            },
+            "relatedNodes": [],
+            "impact": "serious",
+            "message": "Element has no title attribute"
+          }
+        ],
+        "all": [],
+        "none": [],
+        "impact": "serious",
+        "html": "<div data-theme-tooltip-portal=\"true\" id=\"theme-picker-tooltip\" role=\"tooltip\" class=\"fixed left-0 top-0 z-(--z-theme-picker) pointer-events-none opacity-0 transition-opacity duration-150 ease-out\">",
+        "target": [
+          "#theme-picker-tooltip"
+        ],
+        "failureSummary": "Fix any of the following:\n  Element does not have text that is visible to screen readers\n  aria-label attribute does not exist or is empty\n  aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty\n  Element has no title attribute"
+      }
+    ]
+  }
+]

src/components/ThemePicker/client/__tests__/index.spec.ts

@@ -49,6 +49,8 @@ const getThemeButtons = (root: ThemePickerElement) =>
   queryElements<HTMLButtonElement>(root, '[data-theme]')
 const getThemeSelectButtons = (root: ThemePickerElement) =>
   queryElements<HTMLButtonElement>(root, '.themepicker__selectBtn')
+const getTooltipPortal = (doc: Document) =>
+  queryElement<HTMLDivElement>(doc, '[data-theme-tooltip-portal]')
 
 let container: AstroContainer
 
@@ -176,6 +178,23 @@ describe('ThemePicker Component', () => {
         expect(header.getAttribute('role')).toBe('banner')
       })
     })
+
+    it('keeps the tooltip hidden from assistive tech until a theme is focused', async () => {
+      await renderThemePickerDom(({ element, window }) => {
+        const tooltip = getTooltipPortal(window.document)
+        expect(tooltip.getAttribute('role')).toBe('tooltip')
+        expect(tooltip.getAttribute('aria-hidden')).toBe('true')
+        expect(tooltip.hasAttribute('hidden')).toBe(true)
+
+        const [firstThemeButton] = getThemeButtons(element)
+        firstThemeButton.dispatchEvent(new window.FocusEvent('focusin', { bubbles: true }))
+
+        expect(firstThemeButton.getAttribute('aria-describedby')).toBe('theme-picker-tooltip')
+        expect(tooltip.hasAttribute('hidden')).toBe(false)
+        expect(tooltip.getAttribute('aria-hidden')).toBeNull()
+        expect(tooltip.textContent?.trim().length).toBeGreaterThan(0)
+      })
+    })
   })
 
   describe('CSS Classes', () => {

src/components/ThemePicker/client/index.ts

@@ -88,6 +88,8 @@ export class ThemePickerElement extends LitElement {
 
   private readonly tooltipId = 'theme-picker-tooltip'
 
+  private readonly hiddenTooltipAttribute = 'hidden'
+
   private readonly emblaUpdateHandler = () => this.updateEmblaOverflowVisibility()
 
   // Track View Transitions
@@ -565,6 +567,8 @@ export class ThemePickerElement extends LitElement {
       portal.setAttribute('data-theme-tooltip-portal', 'true')
       portal.setAttribute('id', this.tooltipId)
       portal.setAttribute('role', 'tooltip')
+      portal.setAttribute('aria-hidden', 'true')
+      portal.setAttribute(this.hiddenTooltipAttribute, '')
       portal.className =
         'fixed left-0 top-0 z-(--z-theme-picker) pointer-events-none opacity-0 transition-opacity duration-150 ease-out'
 
@@ -616,7 +620,9 @@ export class ThemePickerElement extends LitElement {
     this.tooltipPortalContent.textContent = tooltipText
     this.tooltipActiveButton = button
 
-    // Make it accessible when visible.
+    // Expose the tooltip only while it has content and is referenced.
+    this.tooltipPortal.removeAttribute('aria-hidden')
+    this.tooltipPortal.removeAttribute(this.hiddenTooltipAttribute)
     button.setAttribute('aria-describedby', this.tooltipId)
 
     this.updateTooltipPosition()
@@ -633,6 +639,8 @@ export class ThemePickerElement extends LitElement {
     }
 
     this.tooltipActiveButton = null
+    this.tooltipPortal.setAttribute('aria-hidden', 'true')
+    this.tooltipPortal.setAttribute(this.hiddenTooltipAttribute, '')
     this.tooltipPortal.style.opacity = '0'
 
     if (this.tooltipRafId !== null && typeof cancelAnimationFrame === 'function') {