feat(role): support {checked: true} for checkbox / radio (#692)

Co-authored-by: Sebastian Silbermann <[email protected]>

Author: idanen

src/__tests__/ariaAttributes.js

@@ -1,4 +1,4 @@
-import {render} from './helpers/test-utils'
+import {render, renderIntoDocument} from './helpers/test-utils'
 
 test('`selected` throws on unsupported roles', () => {
   const {getByRole} = render(`<input aria-selected="true" type="text">`)
@@ -9,6 +9,59 @@ test('`selected` throws on unsupported roles', () => {
   )
 })
 
+test('`checked` throws on unsupported roles', () => {
+  const {getByRole} = render(`<input aria-checked="true" type="text">`)
+  expect(() =>
+    getByRole('textbox', {checked: true}),
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"\\"aria-checked\\" is not supported on role \\"textbox\\"."`,
+  )
+})
+
+test('`checked: true|false` matches `checked` checkboxes', () => {
+  const {getByRole} = renderIntoDocument(
+    `<div>
+      <input type="checkbox" checked />
+      <input type="checkbox" />
+    </div>`,
+  )
+  expect(getByRole('checkbox', {checked: true})).toBeInTheDocument()
+  expect(getByRole('checkbox', {checked: false})).toBeInTheDocument()
+})
+
+test('`checked: true|false` matches `checked` elements with proper role', () => {
+  const {getByRole} = renderIntoDocument(
+    `<div>
+      <span role="checkbox" aria-checked="true">✔</span>
+      <span role="checkbox" aria-checked="false">𝒙</span>
+    </div>`,
+  )
+  expect(getByRole('checkbox', {checked: true})).toBeInTheDocument()
+  expect(getByRole('checkbox', {checked: false})).toBeInTheDocument()
+})
+
+test('`checked: true|false` does not match element in `indeterminate` state', () => {
+  const {queryByRole, getByLabelText} = renderIntoDocument(
+    `<div>
+      <span role="checkbox" aria-checked="mixed">not so much</span>
+      <input type="checkbox" checked aria-label="indeteminate yes" />
+      <input type="checkbox" aria-label="indeteminate no" />
+    </div>`,
+  )
+  getByLabelText(/indeteminate yes/i).indeterminate = true
+  getByLabelText(/indeteminate no/i).indeterminate = true
+
+  expect(
+    queryByRole('checkbox', {checked: true, name: /indeteminate yes/i}),
+  ).toBeNull()
+  expect(
+    queryByRole('checkbox', {checked: false, name: /indeteminate no/i}),
+  ).toBeNull()
+  expect(
+    queryByRole('checkbox', {checked: true, name: /not so much/i}),
+  ).toBeNull()
+})
+
 test('`selected: true` matches `aria-selected="true"` on supported roles', () => {
   const {getAllByRole} = render(`
 <select>

src/queries/role.js

@@ -2,6 +2,7 @@ import {computeAccessibleName} from 'dom-accessibility-api'
 import {roles as allRoles} from 'aria-query'
 import {
   computeAriaSelected,
+  computeAriaChecked,
   getImplicitAriaRoles,
   prettyRoles,
   isInaccessible,
@@ -29,6 +30,7 @@ function queryAllByRole(
     normalizer,
     queryFallbacks = false,
     selected,
+    checked,
   } = {},
 ) {
   checkContainerType(container)
@@ -42,6 +44,13 @@ function queryAllByRole(
     }
   }
 
+  if (checked !== undefined) {
+    // guard against unknown roles
+    if (allRoles.get(role)?.props['aria-checked'] === undefined) {
+      throw new Error(`"aria-checked" is not supported on role "${role}".`)
+    }
+  }
+
   const subtreeIsInaccessibleCache = new WeakMap()
   function cachedIsSubtreeInaccessible(element) {
     if (!subtreeIsInaccessibleCache.has(element)) {
@@ -82,6 +91,9 @@ function queryAllByRole(
       if (selected !== undefined) {
         return selected === computeAriaSelected(element)
       }
+      if (checked !== undefined) {
+        return checked === computeAriaChecked(element)
+      }
       // don't care if aria attributes are unspecified
       return true
     })

src/role-helpers.js

@@ -185,8 +185,32 @@ function computeAriaSelected(element) {
   if (element.tagName === 'OPTION') {
     return element.selected
   }
+
   // explicit value
-  const attributeValue = element.getAttribute('aria-selected')
+  return checkBooleanAttribute(element, 'aria-selected')
+}
+
+/**
+ * @param {Element} element -
+ * @returns {boolean | undefined} - false/true if (not)checked, undefined if not checked-able
+ */
+function computeAriaChecked(element) {
+  // implicit value from html-aam mappings: https://www.w3.org/TR/html-aam-1.0/#html-attribute-state-and-property-mappings
+  // https://www.w3.org/TR/html-aam-1.0/#details-id-56
+  // https://www.w3.org/TR/html-aam-1.0/#details-id-67
+  if ('indeterminate' in element && element.indeterminate) {
+    return undefined
+  }
+  if ('checked' in element) {
+    return element.checked
+  }
+
+  // explicit value
+  return checkBooleanAttribute(element, 'aria-checked')
+}
+
+function checkBooleanAttribute(element, attribute) {
+  const attributeValue = element.getAttribute(attribute)
   if (attributeValue === 'true') {
     return true
   }
@@ -204,4 +228,5 @@ export {
   prettyRoles,
   isInaccessible,
   computeAriaSelected,
+  computeAriaChecked,
 }

types/queries.d.ts

@@ -79,6 +79,11 @@ export interface ByRoleOptions extends MatcherOptions {
    * selected in the accessibility tree, i.e., `aria-selected="true"`
    */
   selected?: boolean
+  /**
+   * If true only includes elements in the query set that are marked as
+   * checked in the accessibility tree, i.e., `aria-checked="true"`
+   */
+  checked?: boolean
   /**
    * Includes every role used in the `role` attribute
    * For example *ByRole('progressbar', {queryFallbacks: true})` will find <div role="meter progressbar">`.