TextInputWithTokens: announce selected token values for screen readers

.changeset/three-suns-move.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': patch
+---
+
+TextInputWithTokens: announce selected token values for screen readers.

packages/react/src/TextInputWithTokens/TextInputWithTokens.test.tsx

@@ -60,6 +60,31 @@ describe('TextInputWithTokens', () => {
     expect(render(<TextInputWithTokens tokens={mockTokens} onTokenRemove={onRemoveMock} />)).toMatchSnapshot()
   })
 
+  it('announces selected token values when used as a combobox', () => {
+    const onRemoveMock = vi.fn()
+    const {getByRole} = render(
+      <LabelledTextInputWithTokens
+        role="combobox"
+        tokens={[
+          {text: 'css', id: 'css'},
+          {text: 'react', id: 'react'},
+        ]}
+        onTokenRemove={onRemoveMock}
+      />,
+    )
+
+    const combobox = getByRole('combobox', {name: 'Tokens'})
+    const describedByIds = combobox.getAttribute('aria-describedby')
+
+    expect(describedByIds).toBeTruthy()
+
+    const describedByNodes = describedByIds
+      ? describedByIds.split(' ').map(descriptionId => document.getElementById(descriptionId))
+      : []
+
+    expect(describedByNodes.some(node => node?.textContent === 'Selected: css, react')).toBe(true)
+  })
+
   it('renders with tokens using a custom token component', () => {
     const onRemoveMock = vi.fn()
     expect(

packages/react/src/TextInputWithTokens/TextInputWithTokens.tsx

@@ -5,10 +5,12 @@ import React, {useRef, useState} from 'react'
 import {isValidElementType} from 'react-is'
 import {useRefObjectAsForwardedRef} from '../hooks/useRefObjectAsForwardedRef'
 import {useFocusZone} from '../hooks/useFocusZone'
+import {useId} from '../hooks/useId'
 import Text from '../Text'
 import type {TextInputProps} from '../TextInput'
 import Token from '../Token/Token'
 import type {TokenSizeKeys} from '../Token/TokenBase'
+import VisuallyHidden from '../_VisuallyHidden'
 
 import type {TextInputSizes} from '../internal/components/TextInputWrapper'
 import TextInputWrapper from '../internal/components/TextInputWrapper'
@@ -101,11 +103,32 @@ function TextInputWithTokensInnerComponent<TokenComponentType extends AnyReactCo
   }: TextInputWithTokensProps<TokenComponentType | typeof Token>,
   forwardedRef: React.ForwardedRef<HTMLInputElement>,
 ) {
-  const {onBlur, onFocus, onKeyDown, ...inputPropsRest} = rest
+  const {onBlur, onFocus, onKeyDown, 'aria-describedby': ariaDescribedByProp, role, ...inputPropsRest} = rest
+
   const ref = useRef<HTMLInputElement>(null)
+
+  const selectedValuesDescriptionId = useId()
   useRefObjectAsForwardedRef(forwardedRef, ref)
   const [selectedTokenIndex, setSelectedTokenIndex] = useState<number | undefined>()
   const [tokensAreTruncated, setTokensAreTruncated] = useState<boolean>(Boolean(visibleTokenCount))
+  const selectedTokenTexts = tokens
+    .map(token => {
+      if ('text' in token && typeof token.text === 'string' && token.text.trim().length) {
+        return token.text
+      }
+
+      return null
+    })
+    .filter((tokenText): tokenText is string => tokenText !== null)
+  const selectedValuesDescription = selectedTokenTexts.length ? `Selected: ${selectedTokenTexts.join(', ')}` : ''
+  const shouldExposeSelectedValuesDescription = role === 'combobox' && Boolean(selectedValuesDescription)
+  const ariaDescribedBy = [
+    ariaDescribedByProp,
+    shouldExposeSelectedValuesDescription ? selectedValuesDescriptionId : undefined,
+  ]
+    .filter(Boolean)
+    .join(' ')
+
   const {containerRef} = useFocusZone(
     {
       focusOutBehavior: 'wrap',
@@ -295,8 +318,13 @@ function TextInputWithTokensInnerComponent<TokenComponentType extends AnyReactCo
             type="text"
             className={styles.UnstyledTextInput}
             aria-invalid={validationStatus === 'error' ? 'true' : 'false'}
+            role={role}
+            aria-describedby={ariaDescribedBy || undefined}
             {...inputPropsRest}
           />
+          {shouldExposeSelectedValuesDescription ? (
+            <VisuallyHidden id={selectedValuesDescriptionId}>{selectedValuesDescription}</VisuallyHidden>
+          ) : null}
         </div>
         {visibleTokens.map(({id, ...tokenRest}, i) => (
           <TokenComponent