support {checked: true} for checkbox / radio

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,28 @@ test('`selected` throws on unsupported roles', () => {
   )
 })
 
+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('`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,37 @@ function computeAriaSelected(element) {
   if (element.tagName === 'OPTION') {
     return element.selected
   }
+  if ('checked' in element) {
+    return element.checked
+  }
+
+  // explicit value
+  const attributeValue =
+    element.getAttribute('aria-selected') ||
+    element.getAttribute('aria-checked')
+  if (attributeValue === 'true') {
+    return true
+  }
+  if (attributeValue === 'false') {
+    return false
+  }
+  return undefined
+}
+
+/**
+ * @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 ('checked' in element) {
+    return element.checked
+  }
+
   // explicit value
-  const attributeValue = element.getAttribute('aria-selected')
+  const attributeValue = element.getAttribute('aria-checked')
   if (attributeValue === 'true') {
     return true
   }
@@ -204,4 +233,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">`.