diff --git a/docs/6.x/docs/guides/migration.md b/docs/6.x/docs/guides/migration.md index 30cbc45a6a..a7e750b626 100644 --- a/docs/6.x/docs/guides/migration.md +++ b/docs/6.x/docs/guides/migration.md @@ -309,7 +309,7 @@ As with `roundness`, Paper ignores these keys, and TypeScript only reports them Components now use React Native's `aria-*` props and `role` instead of the `accessibility*` props. `accessibilityLabel` is now `aria-label`, the `accessibilityRole` of `Button` is now `role`, and the `accessibilityState` of `FAB` and `Menu.Item` is now `aria-checked` and `aria-selected`. -`Checkbox.Item`, `RadioButton.Item`, `FAB`, `Menu.Item`, `List.Accordion` and `Switch` no longer accept `accessibilityLabel`, so TypeScript reports an error. Components whose props extend React Native's view props, such as `Button`, `Chip` and `DataTable.Pagination`, still compile with the old props, but pass them to their outer container instead of the element they used to label. +`Checkbox.Item`, `RadioButton.Item`, `FAB`, `Menu.Item`, `List.Accordion` and `Switch` no longer accept `accessibilityLabel`, so TypeScript reports an error. Components whose props extend React Native's view props, such as `Chip` and `DataTable.Pagination`, still compile with the old props, but pass them to their outer container instead of the element they used to label. Props that label a part of a component keep their names, e.g. `closeIconAccessibilityLabel` on `Chip` and `dismissAccessibilityLabel` on `Modal`. diff --git a/src/components/Button/Button.tsx b/src/components/Button/Button.tsx index 93f5a59e59..6de64ccf5f 100644 --- a/src/components/Button/Button.tsx +++ b/src/components/Button/Button.tsx @@ -260,8 +260,14 @@ const Button = ({ children, 'aria-label': ariaLabel, 'aria-expanded': ariaExpanded, + 'aria-busy': ariaBusy, + 'aria-checked': ariaChecked, + 'aria-selected': ariaSelected, + accessibilityLabel, + accessibilityState, + accessibilityRole, accessibilityHint, - role = 'button', + role, hitSlop, onPress, onPressIn, @@ -316,11 +322,43 @@ const Button = ({ // toggle colors, no shape flip, and no toggle state. Every other use of // the toggle state goes through this value. const toggleSelected = isMode('text') ? undefined : selected; - // React Native's types have no `aria-pressed`. + + // As on React Native itself, an `aria-*` prop wins over the same + // `accessibilityState` field. Both are passed on as `aria-*` props, since + // react-native-web does not support `accessibilityState`. + const busy = loading || (ariaBusy ?? accessibilityState?.busy); + const checked = ariaChecked ?? accessibilityState?.checked; + + // Android only: React Native puts a busy view's state into its content + // description ("Save draft, busy"), and TalkBack reads that instead of the + // text inside the button. Without a label, the description would be just + // "busy", so the button's text becomes its label. When the content is not + // only text (strings and numbers, e.g. `Uploading {count} files`), it + // cannot be read here: the busy state is left out instead, so TalkBack + // still reads the content. + const needsAndroidBusyLabel = + Platform.OS === 'android' && + busy === true && + ariaLabel === undefined && + accessibilityLabel === undefined; + const childrenParts = React.Children.toArray(children); + const childrenText = + childrenParts.length > 0 && + childrenParts.every( + (part) => typeof part === 'string' || typeof part === 'number' + ) + ? childrenParts.join('') + : undefined; + const pressableLabel = needsAndroidBusyLabel ? childrenText : ariaLabel; + const pressableBusy = + needsAndroidBusyLabel && childrenText === undefined ? undefined : busy; + + // React Native's types have no `aria-pressed`. A given `checked` state + // still applies where the toggle state is not exposed as checked. const toggleStateProps = Platform.OS === 'web' - ? { 'aria-pressed': toggleSelected } - : { 'aria-checked': toggleSelected }; + ? { 'aria-pressed': toggleSelected, 'aria-checked': checked } + : { 'aria-checked': toggleSelected ?? checked }; // When the button is `selected`, flip the requested shape so the // unselected/selected pair contrasts visually (round ↔ square). @@ -528,10 +566,19 @@ const Button = ({ onPressIn={hasPassedTouchHandler ? handlePressIn : undefined} onPressOut={hasPassedTouchHandler ? handlePressOut : undefined} delayLongPress={delayLongPress} - aria-label={ariaLabel} - aria-expanded={ariaExpanded} + accessibilityLabel={accessibilityLabel} + accessibilityRole={accessibilityRole} + aria-label={pressableLabel} + aria-expanded={ariaExpanded ?? accessibilityState?.expanded} + aria-busy={pressableBusy} + aria-selected={ariaSelected ?? accessibilityState?.selected} accessibilityHint={accessibilityHint} - role={role} + // `role` wins over `accessibilityRole`, so the default role steps + // aside for a given `accessibilityRole`. The two use different + // names (`header` / `heading`), so one is never passed as the other. + role={ + role ?? (accessibilityRole === undefined ? 'button' : undefined) + } aria-disabled={disabled} {...toggleStateProps} accessible={accessible} @@ -556,7 +603,13 @@ const Button = ({ ) : null} {loading ? ( - + // The button itself is busy (`aria-busy`), so the indicator is + // not a separate progress element for assistive technology. + ) : null} { expect(screen.getByRole('button')).toHaveProp('accessibilityHint', 'hint'); }); +describe('accessibility props', () => { + it('exposes accessibilityLabel, accessibilityState and loading on the button only', async () => { + await render( + + ); + + expect( + screen.getByRole('button', { + name: 'Save draft', + expanded: false, + busy: true, + }) + ).toBeOnTheScreen(); + expect(screen.root).not.toHaveProp('accessibilityLabel'); + expect(screen.root).not.toHaveProp('accessibilityState'); + // The button itself is busy, so the indicator is hidden. + expect(screen.queryByRole('progressbar')).not.toBeOnTheScreen(); + expect( + screen.getByRole('progressbar', { includeHiddenElements: true }) + ).toBeOnTheScreen(); + }); + + it('exposes aria-* states on the button, ahead of accessibilityState', async () => { + await render( + + ); + + const button = screen.getByRole('button', { + name: 'Save', + expanded: true, + busy: false, + selected: true, + }); + // `getByRole` filters `checked` for checkable roles only. + expect(button).toHaveProp( + 'accessibilityState', + expect.objectContaining({ checked: 'mixed' }) + ); + expect(screen.root).not.toHaveProp('accessibilityState'); + }); + + // On Android, React Native puts "busy" into the content description, which + // TalkBack reads instead of the button's text, so a loading button without + // a label is labelled by its text there. + it('labels a loading button by its text on Android', async () => { + jest.replaceProperty(Platform, 'OS', 'android'); + + await render( + + ); + + expect(screen.getByRole('button', { busy: true })).toHaveProp( + 'accessibilityLabel', + 'Uploading 3 files' + ); + }); + + it('leaves the name of a loading button to content that is not only text on Android', async () => { + jest.replaceProperty(Platform, 'OS', 'android'); + + await render( + + ); + + // The busy state is left out, so TalkBack reads the content. + expect(screen.getByRole('button', { busy: false })).not.toHaveProp( + 'accessibilityLabel' + ); + }); + + it('uses a given accessibilityRole instead of the default button role', async () => { + await render( + + ); + + expect(screen.getByRole('link', { name: 'Docs' })).toBeOnTheScreen(); + expect(screen.queryByRole('button')).not.toBeOnTheScreen(); + }); +}); + it('should execute onPressIn', async () => { const onPressInMock = jest.fn(); const onPress = jest.fn(); diff --git a/src/components/__tests__/__snapshots__/Button.test.tsx.snap b/src/components/__tests__/__snapshots__/Button.test.tsx.snap index e7695e1022..af79fa9430 100644 --- a/src/components/__tests__/__snapshots__/Button.test.tsx.snap +++ b/src/components/__tests__/__snapshots__/Button.test.tsx.snap @@ -785,6 +785,7 @@ exports[`renders loading button 1`] = ` >