feat(Announce): add support for computing text equivalence

packages/react/src/live-region/Announce.features.stories.tsx

@@ -2,6 +2,7 @@ import type {StoryObj} from '@storybook/react'
 import React, {useEffect, useState} from 'react'
 import {Announce} from './Announce'
 import {VisuallyHidden} from '../VisuallyHidden'
+import RelativeTime from '../RelativeTime'
 
 export default {
   title: 'Experimental/Components/Announce/Features',
@@ -36,3 +37,11 @@ export const WithDelay = () => {
 
   return <Announce delayMs={1000}>{message}</Announce>
 }
+
+export const WithCustomElement = () => {
+  return (
+    <Announce>
+      <RelativeTime date={new Date('2020-01-01T00:00:00Z')} noTitle={true} />
+    </Announce>
+  )
+}

packages/react/src/live-region/Announce.tsx

@@ -3,6 +3,7 @@ import React, {useEffect, useRef, useState, type ElementRef} from 'react'
 import Box from '../Box'
 import {useEffectOnce} from '../internal/hooks/useEffectOnce'
 import {useEffectCallback} from '../internal/hooks/useEffectCallback'
+import {computeTextEquivalent} from './computeTextEquivalent'
 
 export type AnnounceProps = React.ComponentPropsWithoutRef<typeof Box> & {
   /**
@@ -66,7 +67,7 @@ export function Announce({
       return
     }
 
-    const textContent = getTextContent(element)
+    const textContent = computeTextEquivalent(element)
     if (textContent === previousAnnouncementText) {
       return
     }
@@ -131,13 +132,3 @@ export function Announce({
     </Box>
   )
 }
-
-function getTextContent(element: HTMLElement): string {
-  let value = ''
-  if (element.hasAttribute('aria-label')) {
-    value = element.getAttribute('aria-label')!
-  } else if (element.textContent) {
-    value = element.textContent
-  }
-  return value ? value.trim() : ''
-}

packages/react/src/live-region/__tests__/computeTextEquivalent.test.tsx

@@ -0,0 +1,155 @@
+import {computeTextEquivalent} from '../computeTextEquivalent'
+
+describe('computeTextEquivalent', () => {
+  afterEach(() => {
+    document.body.innerHTML = ''
+  })
+
+  test('Text', () => {
+    expect(computeTextEquivalent(new Text('test'))).toEqual('test')
+  })
+
+  test('HTMLElement', () => {
+    const element = document.createElement('div')
+
+    expect(computeTextEquivalent(element)).toEqual('')
+
+    element.textContent = 'test'
+    expect(computeTextEquivalent(element)).toEqual('test')
+  })
+
+  test('HTMLElement with children', () => {
+    const element = document.createElement('div')
+    element.innerHTML = `<div>test</div>`
+
+    expect(computeTextEquivalent(element)).toEqual('test')
+  })
+
+  test('HTMLElement with text and element children', () => {
+    const element = document.createElement('div')
+    element.innerHTML = `before <div>test</div> after`
+
+    expect(computeTextEquivalent(element)).toEqual('before test after')
+  })
+
+  test('HTMLElement with aria-label', () => {
+    const element = document.createElement('div')
+    element.setAttribute('aria-label', 'test')
+    expect(computeTextEquivalent(element)).toEqual('test')
+  })
+
+  test('HTMLElement with aria-labelledby', () => {
+    const label = document.createElement('div')
+    label.textContent = 'test'
+    label.id = 'label'
+
+    const element = document.createElement('div')
+    element.setAttribute('aria-labelledby', 'label')
+
+    document.body.appendChild(label)
+    document.body.appendChild(element)
+
+    expect(computeTextEquivalent(element)).toEqual('test')
+  })
+
+  test('HTMLElement with aria-labelledby but no node with id', () => {
+    const element = document.createElement('div')
+    element.setAttribute('aria-labelledby', 'label')
+
+    document.body.appendChild(element)
+
+    expect(computeTextEquivalent(element)).toEqual('')
+  })
+
+  test('HTMLElement with aria-labelledby with node that is aria-hidden="true"', () => {
+    const label = document.createElement('div')
+    label.textContent = 'test'
+    label.id = 'label'
+    label.setAttribute('aria-hidden', 'true')
+
+    const element = document.createElement('div')
+    element.setAttribute('aria-labelledby', 'label')
+
+    document.body.appendChild(label)
+    document.body.appendChild(element)
+
+    expect(computeTextEquivalent(element)).toEqual('test')
+  })
+
+  test('HTMLElement with aria-labelledby that points to multiple nodes', () => {
+    const label1 = document.createElement('div')
+    label1.textContent = 'test1'
+    label1.id = 'label1'
+
+    const label2 = document.createElement('div')
+    label2.textContent = 'test2'
+    label2.id = 'label2'
+
+    const element = document.createElement('div')
+    element.setAttribute('aria-labelledby', 'label1 label2')
+
+    document.body.appendChild(label1)
+    document.body.appendChild(label2)
+    document.body.appendChild(element)
+
+    expect(computeTextEquivalent(element)).toEqual('test1 test2')
+  })
+
+  test('HTMLElement with aria-hidden', () => {
+    const element = document.createElement('div')
+    element.setAttribute('aria-hidden', 'true')
+    element.textContent = 'test'
+    expect(computeTextEquivalent(element)).toEqual('')
+  })
+
+  test('HTMLElement with aria-hidden and allowAriaHidden', () => {
+    const element = document.createElement('div')
+    element.setAttribute('aria-hidden', 'true')
+    element.textContent = 'test'
+    expect(computeTextEquivalent(element, {allowAriaHidden: true})).toEqual('test')
+  })
+
+  test('HTMLElement with display: none', () => {
+    const element = document.createElement('div')
+    element.style.display = 'none'
+    element.textContent = 'test'
+    expect(computeTextEquivalent(element)).toEqual('')
+  })
+
+  test('HTMLElement with visibility: hidden', () => {
+    const element = document.createElement('div')
+    element.style.visibility = 'hidden'
+    element.textContent = 'test'
+    expect(computeTextEquivalent(element)).toEqual('')
+  })
+
+  test('HTMLElement with shadowRoot', () => {
+    const element = document.createElement('div')
+    const shadowRoot = element.attachShadow({mode: 'open'})
+    shadowRoot.innerHTML = 'shadow'
+    expect(computeTextEquivalent(element)).toEqual('shadow')
+  })
+
+  test('HTMLElement with shadowRoot', () => {
+    const element = document.createElement('div')
+    const shadowRoot = element.attachShadow({mode: 'open'})
+    shadowRoot.innerHTML = 'shadow'
+    expect(computeTextEquivalent(element)).toEqual('shadow')
+  })
+
+  test('HTMLElement with shadowRoot and internal id', () => {
+    const element = document.createElement('div')
+    const shadowRoot = element.attachShadow({mode: 'open'})
+
+    const label = document.createElement('div')
+    label.textContent = 'shadow test'
+    label.id = 'label'
+    shadowRoot.appendChild(label)
+
+    const childElement = document.createElement('div')
+    childElement.setAttribute('aria-labelledby', 'label')
+    shadowRoot.appendChild(childElement)
+
+    expect(computeTextEquivalent(element)).toEqual('shadow test')
+  })
+})

packages/react/src/live-region/computeTextEquivalent.ts

@@ -0,0 +1,87 @@
+type TextEquivalentOptions = {
+  allowAriaHidden: boolean
+}
+
+const defaultOptions: TextEquivalentOptions = {
+  allowAriaHidden: false,
+}
+
+/**
+ * Simplified version of the algorithm to compute the text equivalent of an
+ * element. We do not include support for getting the text equivalence for
+ * various roles
+ *
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps
+ */
+function computeTextEquivalent(
+  elementOrText: HTMLElement | Text,
+  options: TextEquivalentOptions = defaultOptions,
+  parentShadowRoot?: ShadowRoot,
+): string {
+  if (elementOrText instanceof HTMLElement && elementOrText.shadowRoot) {
+    const shadowRoot = elementOrText.shadowRoot!
+    return Array.from(elementOrText.shadowRoot.childNodes)
+      .map(node => {
+        if (node instanceof Text) {
+          return computeTextEquivalent(node, options, shadowRoot)
+        }
+
+        if (node instanceof HTMLElement) {
+          return computeTextEquivalent(node, options, shadowRoot)
+        }
+
+        return null
+      })
+      .filter(Boolean)
+      .join(' ')
+  }
+
+  if (elementOrText instanceof Text) {
+    return elementOrText.textContent?.trim() ?? ''
+  }
+
+  const style = window.getComputedStyle(elementOrText)
+  if (style.display === 'none' || style.visibility === 'hidden') {
+    return ''
+  }
+
+  if (options.allowAriaHidden === false && elementOrText.getAttribute('aria-hidden') === 'true') {
+    return ''
+  }
+
+  if (elementOrText.hasAttribute('aria-labelledby')) {
+    const idrefs = elementOrText.getAttribute('aria-labelledby')!
+    const context = parentShadowRoot ?? document
+    return idrefs
+      .split(' ')
+      .map(idref => {
+        const item = context.getElementById(idref)
+        if (item) {
+          return computeTextEquivalent(item, {allowAriaHidden: true})
+        }
+        return null
+      })
+      .filter(Boolean)
+      .join(' ')
+  }
+
+  if (elementOrText.hasAttribute('aria-label')) {
+    return elementOrText.getAttribute('aria-label')!.trim()
+  }
+
+  if (elementOrText.childNodes.length > 0) {
+    return Array.from(elementOrText.childNodes)
+      .map(node => {
+        if (node instanceof Text || node instanceof HTMLElement) {
+          return computeTextEquivalent(node, options)
+        }
+        return null
+      })
+      .filter(Boolean)
+      .join(' ')
+  }
+
+  return elementOrText.textContent?.trim() ?? ''
+}
+
+export {computeTextEquivalent}