Associate library-generated description, hint and validationMessage nodes with aria-describedby (#1324)

Author: mxmason

src/form-field/__tests__/FormField.test.js

@@ -0,0 +1,47 @@
+import React from 'react'
+import { render } from '@testing-library/react'
+import FormField from '../src/FormField'
+
+const TEST_ID = 'foo'
+
+const makeFormFieldFixture = (props = {}) => (
+  <FormField label="hi" labelFor={TEST_ID} data-testid={TEST_ID} {...props} />
+)
+
+describe('<FormField />', () => {
+  it('Should render without crashing', () => {
+    expect(() => render(makeFormFieldFixture())).not.toThrow()
+  })
+
+  it('renders a label associated with its provided ID', async () => {
+    const { container } = render(makeFormFieldFixture())
+
+    const label = container.querySelector('label')
+    expect(label).toHaveAttribute('for', 'foo')
+    expect(label.textContent).toBe('hi')
+  })
+
+  it('renders a description with correct ID', async () => {
+    const { container } = render(makeFormFieldFixture({ description: 'some content' }))
+
+    const description = container.querySelector(`#${TEST_ID}__description`)
+    expect(description).toBeDefined()
+    expect(description.textContent).toBe('some content')
+  })
+
+  it('renders a hint with correct ID', async () => {
+    const { container } = render(makeFormFieldFixture({ hint: 'some content' }))
+
+    const hint = container.querySelector(`#${TEST_ID}__hint`)
+    expect(hint).toBeDefined()
+    expect(hint.textContent).toBe('some content')
+  })
+
+  it('renders a validation message with correct ID', async () => {
+    const { container } = render(makeFormFieldFixture({ validationMessage: 'some content' }))
+
+    const validationMessage = container.querySelector(`#${TEST_ID}__validation-message`)
+    expect(validationMessage).toBeDefined()
+    expect(validationMessage.textContent).toBe('some content')
+  })
+})

src/form-field/src/FormField.js

@@ -26,15 +26,27 @@ const FormField = memo(
           <FormFieldLabel htmlFor={labelFor} isAstrixShown={isRequired} {...labelProps}>
             {label}
           </FormFieldLabel>
-          {typeof description === 'string' ? <FormFieldDescription>{description}</FormFieldDescription> : description}
+          {typeof description === 'string' ? (
+            <FormFieldDescription id={labelFor + '__description'}>{description}</FormFieldDescription>
+          ) : (
+            description
+          )}
         </Box>
         {children}
         {typeof validationMessage === 'string' ? (
-          <FormFieldValidationMessage marginTop={8}>{validationMessage}</FormFieldValidationMessage>
+          <FormFieldValidationMessage marginTop={8} id={labelFor + '__validation-message'}>
+            {validationMessage}
+          </FormFieldValidationMessage>
         ) : (
           validationMessage
         )}
-        {typeof hint === 'string' ? <FormFieldHint marginTop={6}>{hint}</FormFieldHint> : hint}
+        {typeof hint === 'string' ? (
+          <FormFieldHint marginTop={6} id={labelFor + '__hint'}>
+            {hint}
+          </FormFieldHint>
+        ) : (
+          hint
+        )}
       </Box>
     )
   })

src/form-field/src/FormFieldLabel.js

@@ -7,7 +7,13 @@ const FormFieldLabel = memo(
     const { children, isAstrixShown, ...rest } = props
     return (
       <Label display="block" marginBottom={0} {...rest} ref={ref}>
-        {children} {isAstrixShown && <span title="This field is required.">*</span>}
+        {children}
+        {isAstrixShown && (
+          <>
+            {' '}
+            <span title="This field is required.">*</span>
+          </>
+        )}
       </Label>
     )
   })

src/lib/generate-aria-describedby.js

@@ -0,0 +1,36 @@
+/**
+ * Generates a token value for `aria-describedby` when the author provides `description`, `hint`, or `validationMessage` strings.
+ * @param {String} id
+ * @param {Object} helperTextCandidates
+ * @param {String | React.ReactNode} [helperTextCandidates.description]
+ * @param {String | React.ReactNode} [helperTextCandidates.hint]
+ * @param {String | React.ReactNode} [helperTextCandidates.validationMessage]
+ * @returns {String | null}
+ */
+export function generateAriaDescribedBy(id, { description, hint, validationMessage }) {
+  let tokens = ''
+
+  // Only add each of the following to aria-describedby if
+  // it was provided as a string. When the author provides
+  // a React element, we assume they want to manage aria-describedby themselves.
+
+  // NB: Token order matches the order that these hint texts appear in the DOM.
+  // If the order of the hint texts changes, this should also change.
+
+  if (typeof description === 'string') {
+    tokens += ' ' + id + '__description'
+  }
+
+  if (typeof validationMessage === 'string') {
+    tokens += ' ' + id + '__validation-message'
+  }
+
+  if (typeof hint === 'string') {
+    tokens += ' ' + id + '__hint'
+  }
+
+  if (tokens.length) {
+    return tokens.trim()
+  }
+  return null
+}

src/select/__tests__/SelectField.test.js

@@ -1,16 +1,88 @@
 import React from 'react'
 import { render } from '@testing-library/react'
-import { SelectField } from '../'
+import userEvent from '@testing-library/user-event'
+import { Select, SelectField } from '../'
 import { mockRef } from '../../test/utils'
 
-const makeSelectFieldFixture = (props = {}) => <SelectField data-testid="select-field" label="SelectField" {...props} />
+function makeSelectFixture(props = {}) {
+  return (
+    <Select data-testid="select" defaultValue="foo" name="select" {...props}>
+      <option value="foo">Foo</option>
+      <option value="bar">Bar</option>
+    </Select>
+  )
+}
+
+function makeSelectFieldFixture(props = {}) {
+  return (
+    <SelectField data-testid="select" defaultValue="foo" label="Select" {...props}>
+      <option value="foo">Foo</option>
+      <option value="bar">Bar</option>
+    </SelectField>
+  )
+}
+
+describe('Select', () => {
+  it('Should render without crashing', () => {
+    expect(() => render(makeSelectFixture())).not.toThrow()
+  })
+
+  it('Should set an invalid state if `isInvalid` is `true`', () => {
+    const { container } = render(makeSelectFixture({ isInvalid: true }))
+    const input = container.querySelector('select')
+    expect(input).toHaveAttribute('aria-invalid', 'true')
+  })
+
+  it('Should not be interactive if `disabled` is passed in', () => {
+    const { container } = render(makeSelectFixture({ disabled: true }))
+    const select = container.querySelector('select')
+
+    expect(document.body).toHaveFocus()
+    userEvent.tab()
+    expect(select).not.toHaveFocus()
+  })
+})
 
 describe('SelectField', () => {
+  it('Should render without crashing', () => {
+    expect(() => render(makeSelectFieldFixture())).not.toThrow()
+  })
+
   it('should forward ref to underlying <select />', () => {
     const ref = mockRef()
 
     render(makeSelectFieldFixture({ ref }))
 
     expect(ref.current).toBeInstanceOf(HTMLSelectElement)
   })
+
+  it('Should have expected accessible name when `label` prop passed in', () => {
+    const { container, getByLabelText } = render(makeSelectFieldFixture())
+    const select = container.querySelector('select')
+    expect(getByLabelText('Select')).toBeInTheDocument()
+    expect(select).toHaveAccessibleName('Select')
+  })
+
+  it('Should add hint text to accessible description when `hint` prop provided', () => {
+    const { container, getByText } = render(makeSelectFieldFixture({ hint: 'Some description.' }))
+    expect(getByText('Some description.')).toBeInTheDocument()
+    expect(container.querySelector('select')).toHaveAccessibleDescription('Some description.')
+  })
+
+  it('Should render an astrix when `required` is passed in', () => {
+    const { getByTitle } = render(makeSelectFieldFixture({ required: true }))
+    expect(getByTitle('This field is required.')).toBeInTheDocument()
+  })
+
+  it('Should render a `validationMessage` when passed in', () => {
+    const { container, getByText } = render(makeSelectFieldFixture({ validationMessage: 'Please choose a value.' }))
+    expect(getByText('Please choose a value.')).toBeInTheDocument()
+    expect(container.querySelector('select')).toHaveAccessibleDescription('Please choose a value.')
+  })
+
+  it('Should correctly compose an accessible description from multiple hints', () => {
+    const { container } = render(makeSelectFieldFixture({ hint: 'Am hint.', validationMessage: 'Try again.' }))
+
+    expect(container.querySelector('select')).toHaveAccessibleDescription('Try again. Am hint.')
+  })
 })

src/select/src/Select.js

@@ -43,6 +43,7 @@ const Select = memo(
   forwardRef(function Select(props, ref) {
     const {
       appearance = 'default',
+      'aria-describedby': ariaDescribedby,
       autoFocus,
       children,
       defaultValue,
@@ -98,6 +99,7 @@ const Select = memo(
           paddingRight={iconMargin * 2 + iconSize}
           {...boxProps}
           height="100%"
+          aria-describedby={ariaDescribedby}
         >
           {children}
         </Box>

src/select/src/SelectField.js

@@ -3,6 +3,7 @@ import PropTypes from 'prop-types'
 import { splitBoxProps } from 'ui-box'
 import { FormField } from '../../form-field'
 import { useId } from '../../hooks'
+import { generateAriaDescribedBy } from '../../lib/generate-aria-describedby'
 import Select from './Select'
 
 const SelectField = memo(
@@ -57,6 +58,7 @@ const SelectField = memo(
           isInvalid={isInvalid}
           appearance={appearance}
           ref={ref}
+          aria-describedby={generateAriaDescribedBy(id, { description, hint, validationMessage })}
           {...remainingProps}
         />
       </FormField>

src/text-input/__tests__/TextInput.test.js

@@ -1,13 +1,17 @@
 import React, { useState } from 'react'
 import { render } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
-import { TextInput } from '../'
+import { TextInput, TextInputField } from '../'
 import { mockRef } from '../../test/utils'
 
 function makeTextInputFixture(props = {}) {
   return <TextInput data-testid="input" {...props} />
 }
 
+function makeTextInputFieldFixture(props = {}) {
+  return <TextInputField data-testid="input" label="Name" {...props} />
+}
+
 describe('TextInput', () => {
   it('should forward ref to underlying <input />', () => {
     const ref = mockRef()
@@ -65,3 +69,42 @@ describe('TextInput', () => {
     expect(getByDisplayValue('')).toEqual(input)
   })
 })
+
+describe('TextInputField', () => {
+  it('Should render without crashing', () => {
+    expect(() => render(makeTextInputFieldFixture())).not.toThrow()
+  })
+
+  it('Should have expected accessible name when `label` prop', () => {
+    const { getByLabelText, getByTestId } = render(makeTextInputFieldFixture())
+    expect(getByLabelText('Name')).toBeInTheDocument()
+    expect(getByTestId('input')).toHaveAccessibleName('Name')
+  })
+
+  it('Should add hint text to accessible description when `hint` prop provided', () => {
+    const { getByTestId, getByText } = render(makeTextInputFieldFixture({ hint: 'Enter a value in the input' }))
+    expect(getByText('Enter a value in the input')).toBeInTheDocument()
+    expect(getByTestId('input')).toHaveAccessibleDescription('Enter a value in the input')
+  })
+
+  it('Should render an astrix when `required` is passed in', () => {
+    const { getByTitle } = render(makeTextInputFieldFixture({ required: true }))
+    expect(getByTitle('This field is required.')).toBeInTheDocument()
+  })
+
+  it('Should render a `validationMessage` when passed in', () => {
+    const { getByTestId, getByText } = render(makeTextInputFieldFixture({ validationMessage: 'Please enter a value.' }))
+    expect(getByText('Please enter a value.')).toBeInTheDocument()
+    expect(getByTestId('input')).toHaveAccessibleDescription('Please enter a value.')
+  })
+
+  it('Should correctly compose an accessible description from multiple hints', () => {
+    const { getByTestId, getByText } = render(
+      makeTextInputFieldFixture({ description: 'A description.', hint: 'Am hint.', validationMessage: 'Try again.' })
+    )
+    expect(getByText('A description.')).toBeInTheDocument()
+    expect(getByText('Am hint.')).toBeInTheDocument()
+    expect(getByText('Try again.')).toBeInTheDocument()
+    expect(getByTestId('input')).toHaveAccessibleDescription('A description. Try again. Am hint.')
+  })
+})

src/text-input/src/TextInputField.js

@@ -3,6 +3,7 @@ import PropTypes from 'prop-types'
 import { splitBoxProps } from 'ui-box'
 import { FormField } from '../../form-field'
 import { useId } from '../../hooks'
+import { generateAriaDescribedBy } from '../../lib/generate-aria-describedby'
 import { majorScale } from '../../scales'
 import TextInput from './TextInput'
 
@@ -61,6 +62,7 @@ const TextInputField = memo(
           placeholder={placeholder}
           spellCheck={spellCheck}
           ref={ref}
+          aria-describedby={generateAriaDescribedBy(id, { description, hint, validationMessage })}
           {...remainingProps}
         />
       </FormField>

src/textarea/__tests__/TextareaField.test.js

@@ -144,4 +144,14 @@ describe('TextareaField', () => {
       expect(onChange).toHaveBeenCalled()
     })
   })
+
+  it('Should correctly compose an accessible description from multiple hints', () => {
+    const { getByTestId, getByText } = render(
+      makeTextareaFieldFixture({ description: 'A description.', hint: 'Am hint.', validationMessage: 'Try again.' })
+    )
+    expect(getByText('A description.')).toBeInTheDocument()
+    expect(getByText('Am hint.')).toBeInTheDocument()
+    expect(getByText('Try again.')).toBeInTheDocument()
+    expect(getByTestId('TextareaField')).toHaveAccessibleDescription('A description. Try again. Am hint.')
+  })
 })