feat(ByRole): Add 'level' option for *ByRole('heading') (#757)

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

Author: winterlamon

src/__tests__/ariaAttributes.js

@@ -167,3 +167,38 @@ test('`pressed: true|false` matches `pressed` elements with proper role', () =>
   expect(getByRole('button', {pressed: true})).toBeInTheDocument()
   expect(getByRole('button', {pressed: false})).toBeInTheDocument()
 })
+
+test('`level` matches elements with `heading` role', () => {
+  const {getAllByRole, queryByRole} = renderIntoDocument(
+    `<div>
+      <h1 id="heading-one">H1</h1>
+      <h2 id="first-heading-two">First H2</h2>
+      <h3 id="heading-three">H3</h3>
+      <div role="heading" aria-level="2" id="second-heading-two">Second H2</div>
+    </div>`,
+  )
+
+  expect(getAllByRole('heading', {level: 1}).map(({id}) => id)).toEqual([
+    'heading-one',
+  ])
+
+  expect(getAllByRole('heading', {level: 2}).map(({id}) => id)).toEqual([
+    'first-heading-two',
+    'second-heading-two',
+  ])
+
+  expect(getAllByRole('heading', {level: 3}).map(({id}) => id)).toEqual([
+    'heading-three',
+  ])
+
+  expect(queryByRole('heading', {level: 4})).not.toBeInTheDocument()
+})
+
+test('`level` throws on unsupported roles', () => {
+  const {getByRole} = render(`<button>Button</button>`)
+  expect(() =>
+    getByRole('button', {level: 3}),
+  ).toThrowErrorMatchingInlineSnapshot(
+    `"Role \\"button\\" cannot have \\"level\\" property."`,
+  )
+})

src/queries/role.js

@@ -4,6 +4,7 @@ import {
   computeAriaSelected,
   computeAriaChecked,
   computeAriaPressed,
+  computeHeadingLevel,
   getImplicitAriaRoles,
   prettyRoles,
   isInaccessible,
@@ -33,6 +34,7 @@ function queryAllByRole(
     selected,
     checked,
     pressed,
+    level,
   } = {},
 ) {
   checkContainerType(container)
@@ -60,6 +62,13 @@ function queryAllByRole(
     }
   }
 
+  if (level !== undefined) {
+    // guard against using `level` option with any role other than `heading`
+    if (role !== 'heading') {
+      throw new Error(`Role "${role}" cannot have "level" property.`)
+    }
+  }
+
   const subtreeIsInaccessibleCache = new WeakMap()
   function cachedIsSubtreeInaccessible(element) {
     if (!subtreeIsInaccessibleCache.has(element)) {
@@ -106,6 +115,9 @@ function queryAllByRole(
       if (pressed !== undefined) {
         return pressed === computeAriaPressed(element)
       }
+      if (level !== undefined) {
+        return level === computeHeadingLevel(element)
+      }
       // don't care if aria attributes are unspecified
       return true
     })

src/role-helpers.js

@@ -233,6 +233,30 @@ function checkBooleanAttribute(element, attribute) {
   return undefined
 }
 
+/**
+ * @param {Element} element -
+ * @returns {number | undefined} - number if implicit heading or aria-level present, otherwise undefined
+ */
+function computeHeadingLevel(element) {
+  // https://w3c.github.io/html-aam/#el-h1-h6
+  // https://w3c.github.io/html-aam/#el-h1-h6
+  const implicitHeadingLevels = {
+    H1: 1,
+    H2: 2,
+    H3: 3,
+    H4: 4,
+    H5: 5,
+    H6: 6,
+  }
+  // explicit aria-level value
+  // https://www.w3.org/TR/wai-aria-1.2/#aria-level
+  const ariaLevelAttribute =
+    element.getAttribute('aria-level') &&
+    Number(element.getAttribute('aria-level'))
+
+  return ariaLevelAttribute || implicitHeadingLevels[element.tagName]
+}
+
 export {
   getRoles,
   logRoles,
@@ -243,4 +267,5 @@ export {
   computeAriaSelected,
   computeAriaChecked,
   computeAriaPressed,
+  computeHeadingLevel,
 }

types/queries.d.ts

@@ -88,6 +88,12 @@ export interface ByRoleOptions extends MatcherOptions {
    * pressed in the accessibility tree, i.e., `aria-pressed="true"`
    */
   pressed?: boolean
+  /**
+   * Includes elements with the `"heading"` role matching the indicated level,
+   * either by the semantic HTML heading elements `<h1>-<h6>` or matching
+   * the `aria-level` attribute.
+   */
+  level?: number
   /**
    * Includes every role used in the `role` attribute
    * For example *ByRole('progressbar', {queryFallbacks: true})` will find <div role="meter progressbar">`.

types/role-helpers.d.ts

@@ -1,6 +1,9 @@
-export function logRoles(container: HTMLElement): string;
-export function getRoles(container: HTMLElement): { [index: string]: HTMLElement[] };
+export function logRoles(container: HTMLElement): string
+export function getRoles(
+  container: HTMLElement,
+): {[index: string]: HTMLElement[]}
 /**
  * https://testing-library.com/docs/dom-testing-library/api-helpers#isinaccessible
  */
-export function isInaccessible(element: Element): boolean;
+export function isInaccessible(element: Element): boolean
+export function computeHeadingLevel(element: Element): number | undefined