fix(accessibility): Field announce error message for focused field #8329

majornista · 2025-05-30T21:05:27Z

Closes #8328

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue #8328.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

Open the Spectrum 2 Preview > Form > Example storybook example.
With a screen reader running, like VoiceOver on macOS or NVDA on Windows, navigate to move focus to the Email field, which is the third field in the form.
Enter an invalid email value, like "admin", and press Enter to trigger validation by submitting the form.
The screen reader should announce the error message that renders politely.
Type some more to modify the value to another invalid value like, "admin@", then Tab or Shift+Tab to blur the input, which again trigger validation.
After the screen reader announces the input that receives keyboard focus, it should announce "Please review Email field: Please enter a part following '@'. 'admin@' is incomplete," with the name and error message for the Email field that was blurred.

🧢 Your Project:

Accessibility/SUSI/Adobe

Copilot

Pull Request Overview

This PR fixes the error message announcement behavior for focused fields by updating the logic in the Field component to announce errors via the live announcer. Key changes include:

Adding a useEffect in Field.tsx to announce error messages when the field is focused.
Renaming the help text flag to hasErrorMessage for clarity.
Adding the @react-aria/live-announcer dependency in package.json.
Extending InlineAlert stories with a new DynamicWithAriaLivePolite variant.

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
packages/@react-spectrum/label/src/Field.tsx	Updates error message announcement logic and variable naming
packages/@react-spectrum/label/package.json	Adds dependency for live announcer
packages/@react-spectrum/inlinealert/stories/InlineAlert.stories.tsx	Adds a new story variant showcasing aria-live behavior

packages/@react-spectrum/label/src/Field.tsx

rspbot · 2025-05-30T22:12:58Z

Build successful! 🎉

Copilot

Pull Request Overview

This PR improves accessibility by ensuring that error messages are announced when the associated field is focused.

Introduces an effect in Field.tsx to announce error messages when the field is active.
Adds a dependency on @react-aria/live-announcer in package.json.
Updates stories and tests to better handle error message rendering.

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

File	Description
packages/@react-spectrum/label/src/Field.tsx	Implements useEffect to announce error messages for focused fields.
packages/@react-spectrum/label/package.json	Adds the live announcer dependency to support new accessibility logic.
packages/@react-spectrum/inlinealert/stories/InlineAlert.stories.tsx	Introduces a new story variant with aria-live explicitly set.
packages/@react-spectrum/datepicker/test/DateField.test.js	Modifies test to access the first instance of the error message element.

Comments suppressed due to low confidence (2)

packages/@react-spectrum/datepicker/test/DateField.test.js:239

Verify that multiple occurrences of the 'Date unavailable.' text are expected. If only one error message should appear, consider updating this to use a more specific selector to avoid masking potential duplication issues.

expect(tree.getAllByText('Date unavailable.')[0]).toBeInTheDocument();

packages/@react-spectrum/label/src/Field.tsx:71

Ensure that the ref passed to Field is always a RefObject. The current cast to RefObject assumes a stable object ref; if callback refs are used, this might lead to unexpected behavior when announcing error messages.

React.useEffect(() => {

rspbot · 2025-06-03T00:17:15Z

Build successful! 🎉

rspbot · 2025-06-03T15:19:18Z

Build successful! 🎉

rspbot · 2025-06-03T15:23:20Z

Build successful! 🎉

rspbot · 2025-06-04T13:55:31Z

Build successful! 🎉

rspbot · 2025-06-04T19:12:28Z

Build successful! 🎉

rspbot · 2025-06-04T20:32:39Z

Build successful! 🎉

rspbot · 2025-06-06T18:23:05Z

Build successful! 🎉

Co-authored-by: Copilot <[email protected]>

…red field

…blurred field 1. Improves announcement of validation error for just blurred field, by including accessible name in announcement for context. 2. Forgo announcement when the field receiving focus already has a validation error. It can be too much information. 3. Add alt text, "(valid)," to validationIcon, and include it in the `aria-describedby` for input for TextFieldBase. 4. fix tests after adding alt text to validationIcon

rspbot · 2025-06-10T16:00:38Z

Build successful! 🎉

…e fields when validationState is 'valid'

rspbot · 2025-06-10T22:53:28Z

Build successful! 🎉

rspbot · 2025-06-11T14:04:36Z

Build successful! 🎉

rspbot · 2025-06-11T14:34:08Z

Build successful! 🎉

rspbot · 2025-06-11T16:07:57Z

Build successful! 🎉

…on before validation message announcement

rspbot · 2025-06-11T19:20:14Z

Build successful! 🎉

Copilot

Pull Request Overview

This pull request enhances accessibility by ensuring error messages for focused fields are appropriately announced and by refining ID and aria-describedby attributes across form components.

Introduces a valid state localized string and updates intl files.
Adjusts IDs and aria attributes for Input, DateField, DatePicker, DateRangePicker, ComboBox, and Autocomplete to improve accessibility announcements.
Enhances form validation logic with a timeout mechanism to announce error messages upon blur.

Reviewed Changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/@react-spectrum/textfield/intl/en-US.json	Adds new locale string for valid state.
packages/@react-spectrum/label/src/Field.tsx	Removes an unnecessary blank line.
packages/@react-spectrum/label/package.json	Updates dependency versions and adds live announcer.
packages/@react-spectrum/inlinealert/stories/InlineAlert.stories.tsx	Adds a new story with aria-live="polite".
packages/@react-spectrum/datepicker/test/DateField.test.js	Adjusts test selector for improved reliability.
packages/@react-spectrum/datepicker/src/TimeField.tsx	Adds ID and aria-describedby for valid icon accessibility.
packages/@react-spectrum/datepicker/src/Input.tsx	Updates ID propagation and valid icon logic.
packages/@react-spectrum/datepicker/src/DateRangePicker.tsx	Introduces useId for the input and assigns IDs conditionally on validation state.
packages/@react-spectrum/datepicker/src/DatePickerSegment.tsx	Enhances merging of aria-describedby props.
packages/@react-spectrum/datepicker/src/DatePickerField.tsx	Propagates the valid icon ID to segments for accessibility.
packages/@react-spectrum/datepicker/src/DatePicker.tsx	Incorporates useId for improved ID management.
packages/@react-spectrum/datepicker/src/DateField.tsx	Integrates improved ID handling and aria-describedby for a valid field.
packages/@react-spectrum/datepicker/intl/en-US.json	Adds new valid state locale string entry.
packages/@react-spectrum/combobox/src/MobileComboBox.tsx	Adds valid icon ID for improved validation accessibility.
packages/@react-spectrum/combobox/intl/en-US.json	Updates locale strings to include a valid state.
packages/@react-spectrum/autocomplete/src/MobileSearchAutocomplete.tsx	Adds valid icon ID and updates aria-labelledby join logic for accessibility.
packages/@react-spectrum/autocomplete/intl/en-US.json	Updates locale strings to include a valid state.
packages/@react-aria/form/src/useFormValidation.ts	Enhances error message announcement logic with a delay on blur.
packages/@react-aria/form/package.json	Updates dependencies and adds dom-accessibility-api.
packages/@react-aria/form/intl/en-US.json	Introduces new locale strings for invalid value and review field prompts.

packages/@react-spectrum/datepicker/src/DateRangePicker.tsx

rspbot · 2025-06-12T17:57:17Z

Build successful! 🎉

rspbot · 2025-06-16T20:56:44Z

Build successful! 🎉

LFDanLu

Verified the before and after behavior and confirmed that we are getting proper announcement when blurring from an errored field or if attempting to submit and invalid value. Will need to poke around/think some more on the change in useFormValidation though

LFDanLu · 2025-06-23T23:16:50Z

packages/@react-spectrum/autocomplete/src/MobileSearchAutocomplete.tsx

@@ -262,7 +263,8 @@ const SearchAutocompleteButton = React.forwardRef(function SearchAutocompleteBut
      props['aria-labelledby'],
      props['aria-label'] && !props['aria-labelledby'] ? props.id : null,
      valueId,
-      validationState === 'invalid' ? invalidId : null
+      validationState === 'invalid' ? invalidId : null,
+      validationState === 'valid' ? validId : null


oh huh, I probably should've done this in #8435 instead

I think it's a simpler approach for including the validation state in the labelling of the popup button used for the combobox on mobile, and it's the same for both invalid and valid states.

I'll go ahead and update my PR to do that instead, thanks! Will hopefully make the conflicts easier to resolve for this PR and/or we can defer to your PR instead

LFDanLu · 2025-06-23T23:33:18Z

packages/@react-spectrum/datepicker/src/DatePickerField.tsx

  return (
    <span {...fieldProps} data-testid={props['data-testid']} className={classNames(datepickerStyles, 'react-spectrum-Datepicker-segments', inputClassName)} ref={ref}>
      {state.segments.map((segment, i) =>
        (<DatePickerSegment
+          aria-describedby={i === 0 ? validIconId : undefined}


perhaps doesn't have to be done in this PR, but I wonder if we could instead modify useDateSegment to handle this for us automatically since it already tries to only apply aria-describedby to the first segment. If would need to accept user provided aria attributes as well as the ones from useDateField but would allow this logic to be non-RSP specific

See comment below: #8329 (comment)

LFDanLu · 2025-06-23T23:34:01Z

packages/@react-spectrum/datepicker/src/DatePickerSegment.tsx

+  if (ariaDescribedByProp) {
+    // Merge aria-describedby from segmentProps and otherProps
+    segmentProps['aria-describedby'] = segmentProps['aria-describedby'] ? `${segmentProps['aria-describedby']} ${ariaDescribedByProp}` : ariaDescribedByProp;
+  }


as mentioned previously, might be good to handle this in the hooks to make it non-RSP specific, but definitely can be followup

See comment below: #8329 (comment)

LFDanLu · 2025-06-23T23:37:48Z

packages/@react-spectrum/datepicker/src/Input.tsx

 import {mergeProps, mergeRefs, useEvent, useLayoutEffect, useResizeObserver} from '@react-aria/utils';
 import React, {ReactElement, useCallback, useRef} from 'react';
 import textfieldStyles from '@adobe/spectrum-css-temp/components/textfield/vars.css';
 import {useFocusRing} from '@react-aria/focus';
+import {useLocalizedStringFormatter} from '@react-aria/i18n';
+
+export const VALID_ICON_POSTFIX = '-valid-icon';


bit unfortunate that this needs to be imported in several places, but fine for now IMO. It would be nice if the hooks or something could handle this automatically for us, maybe via generating the label for us and applying it on a hidden span or something

The valid icon is an React-Spectrum thing and, in the case of the DatePicker and DateRangePicker, is contained within the Input that wraps the DateFields, which contain the segments. I wrestled with the best way to handle this without altering APIs.

fair enough, will have to update this for S2 as well I'd imagine then but fine for now

LFDanLu · 2025-06-24T00:00:36Z

packages/@react-aria/form/src/useFormValidation.ts

+    if (
+      (!input || !input.validationMessage) ||
+      (relatedTarget && isValidatableElement(relatedTarget) && (relatedTarget as ValidatableElement).validationMessage)
+    ) {
+      // If the input has no validation message,
+      // or the relatedTarget has a validation message, don't announce the error message.
+      // This prevents announcing the error message when the user is navigating
+      // between inputs that may already have an error message.
+      return;
+    }


just to make sure I'm understanding the expected behavior here:
the polite error message will announce if you navigate to a field that isn't in an error state from one that was invalid but NOT if you are going between multiple invalid fields since we prefer the user to fix the error on the field they just landed on?

You are understanding correctly, when the field receiving focus and the invalid field being blurred both announce it becomes pretty confusing.

…imilar support for MobileCombobox (#8435) * preventing talkback from focusing valid icon and adding to mobile combobox * update string, match some logic from #8329

majornista requested review from devongovett, reidbarber and Copilot May 30, 2025 21:05

majornista added enhancement New feature or request accessibility labels May 30, 2025

majornista force-pushed the Issue-8328-field-error-announcement branch from db1dec4 to 71e40dc Compare May 30, 2025 21:05

Copilot AI reviewed May 30, 2025

View reviewed changes

packages/@react-spectrum/label/src/Field.tsx Outdated Show resolved Hide resolved

majornista force-pushed the Issue-8328-field-error-announcement branch from 71e40dc to 3484b2f Compare May 30, 2025 21:20

majornista changed the title ~~fix(#8328): Field announce error message for focused field~~ fix(accessibility): Field announce error message for focused field May 30, 2025

majornista force-pushed the Issue-8328-field-error-announcement branch 3 times, most recently from fee6570 to af43a05 Compare May 30, 2025 22:04

majornista requested a review from Copilot May 30, 2025 22:18

Copilot AI reviewed May 30, 2025

View reviewed changes

majornista requested a review from Copilot June 3, 2025 15:08

This comment was marked as outdated.

Sign in to view

majornista force-pushed the Issue-8328-field-error-announcement branch from fd00b91 to fbd7356 Compare June 3, 2025 15:09

majornista requested a review from Copilot June 4, 2025 13:45

This comment was marked as outdated.

Sign in to view

majornista force-pushed the Issue-8328-field-error-announcement branch from 3573692 to bd37367 Compare June 4, 2025 13:45

majornista force-pushed the Issue-8328-field-error-announcement branch from f862c17 to 72b183c Compare June 4, 2025 20:23

majornista requested a review from Copilot June 4, 2025 20:23

This comment was marked as outdated.

Sign in to view

Michael Jordan and others added 5 commits June 10, 2025 15:51

fix(accessibility): Field announce error message for focused field

3289789

fix(accessibility): refactor announcement into useFormValidation

bf1384c

Update packages/@react-aria/form/src/useFormValidation.ts

66a35b9

Co-authored-by: Copilot <[email protected]>

fix(accessibility): add announcement of error message for a just blur…

9462223

…red field

majornista force-pushed the Issue-8328-field-error-announcement branch from 2fb28d7 to 4acca66 Compare June 10, 2025 15:51

Michael Jordan added 2 commits June 10, 2025 18:39

fix(accessibility): add aria-describedby to first segment in Date/Tim…

a235045

…e fields when validationState is 'valid'

Merge branch 'main' into Issue-8328-field-error-announcement

c0ac217

Merge branch 'main' into Issue-8328-field-error-announcement

28d3b68

fix(accessibility): fix code review suggestions from Copilot

310b60a

Merge branch 'main' into Issue-8328-field-error-announcement

c777f1f

fix(accessibility): useFormValidation: slightly longer timeout durati…

0bffa04

…on before validation message announcement

majornista requested a review from Copilot June 12, 2025 17:46

Merge branch 'main' into Issue-8328-field-error-announcement

3d5029b

Copilot AI reviewed Jun 12, 2025

View reviewed changes

packages/@react-spectrum/datepicker/src/DateRangePicker.tsx Show resolved Hide resolved

Merge branch 'main' into Issue-8328-field-error-announcement

5fd6bb8

majornista requested review from LFDanLu and dannify June 23, 2025 22:18

LFDanLu reviewed Jun 24, 2025

View reviewed changes

LFDanLu added a commit that referenced this pull request Jun 24, 2025

update string, match some logic from #8329

3233f58

fix(accessibility): Field announce error message for focused field #8329

Are you sure you want to change the base?

fix(accessibility): Field announce error message for focused field #8329

Conversation

majornista commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

rspbot commented May 30, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

rspbot commented Jun 3, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

rspbot commented Jun 3, 2025

Uh oh!

rspbot commented Jun 3, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

rspbot commented Jun 4, 2025

Uh oh!

rspbot commented Jun 4, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

rspbot commented Jun 4, 2025

Uh oh!

rspbot commented Jun 6, 2025

Uh oh!

rspbot commented Jun 10, 2025

Uh oh!

rspbot commented Jun 10, 2025

Uh oh!

rspbot commented Jun 11, 2025

Uh oh!

rspbot commented Jun 11, 2025

Uh oh!

rspbot commented Jun 11, 2025

Uh oh!

rspbot commented Jun 11, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

rspbot commented Jun 12, 2025

Uh oh!

rspbot commented Jun 16, 2025

Uh oh!

LFDanLu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

majornista Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LFDanLu Jun 23, 2025 • edited by majornista Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

majornista commented May 30, 2025 •

edited

Loading

majornista Jun 24, 2025 •

edited

Loading

LFDanLu Jun 23, 2025 •

edited by majornista

Loading