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

Co-authored-by: Sebastian Silbermann <silbermann.sebastian@gmail.com>

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