Use ListView item's description text as aria-describedby (#3121)

* Use item description text as aria-describedby

* lint

* move description addition to hook

* add descriptionProps

* fix missing row aria-describedby

* use aria-labelledby if description is present

* add aria-labelledby check to test

* update long text story with better textValue

* fixing double announcement for cases with textValue and description

* fix test

Co-authored-by: Daniel Lu <[email protected]>
Co-authored-by: Robert Snow <[email protected]>

Author: 3 people

packages/@react-aria/list/src/useListItem.ts

@@ -15,7 +15,7 @@ import {getRowId, listMap} from './utils';
 import {HTMLAttributes, KeyboardEvent as ReactKeyboardEvent, RefObject} from 'react';
 import {isFocusVisible} from '@react-aria/interactions';
 import type {ListState} from '@react-stately/list';
-import {mergeProps} from '@react-aria/utils';
+import {mergeProps, useSlotId} from '@react-aria/utils';
 import {Node as RSNode} from '@react-types/shared';
 import {SelectableItemStates, useSelectableItem} from '@react-aria/selection';
 import {useLocale} from '@react-aria/i18n';
@@ -33,7 +33,9 @@ export interface ListItemAria extends SelectableItemStates {
   /** Props for the list row element. */
   rowProps: HTMLAttributes<HTMLElement>,
   /** Props for the grid cell element within the list row. */
-  gridCellProps: HTMLAttributes<HTMLElement>
+  gridCellProps: HTMLAttributes<HTMLElement>,
+  /** Props for the list item description element, if any. */
+  descriptionProps: HTMLAttributes<HTMLElement>
 }
 
 /**
@@ -52,6 +54,7 @@ export function useListItem<T>(props: AriaListItemOptions, state: ListState<T>,
 
   let {direction} = useLocale();
   let {onAction} = listMap.get(state);
+  let descriptionId = useSlotId();
   let focus = () => {
     // Don't shift focus to the row if the active element is a element within the row already
     // (e.g. clicking on a row button)
@@ -164,9 +167,10 @@ export function useListItem<T>(props: AriaListItemOptions, state: ListState<T>,
     role: 'row',
     onKeyDownCapture: onKeyDown,
     onFocus,
-    'aria-label': node.textValue,
+    'aria-label': node.textValue || undefined,
     'aria-selected': state.selectionManager.canSelectItem(node.key) ? state.selectionManager.isSelected(node.key) : undefined,
     'aria-disabled': state.selectionManager.isDisabled(node.key) || undefined,
+    'aria-labelledby': descriptionId && node.textValue ? `${getRowId(state, node.key)} ${descriptionId}` : undefined,
     id: getRowId(state, node.key)
   });
 
@@ -182,6 +186,9 @@ export function useListItem<T>(props: AriaListItemOptions, state: ListState<T>,
   return {
     rowProps,
     gridCellProps,
+    descriptionProps: {
+      id: descriptionId
+    },
     ...itemStates
   };
 }

packages/@react-spectrum/list/src/ListViewItem.tsx

@@ -50,11 +50,11 @@ export function ListViewItem<T>(props: ListViewItemProps<T>) {
     focusProps: focusWithinProps
   } = useFocusRing({within: true});
   let {isFocusVisible, focusProps} = useFocusRing();
-
   let {
     rowProps,
     gridCellProps,
     isPressed,
+    descriptionProps,
     isSelected,
     isDisabled,
     allowsSelection,
@@ -242,7 +242,7 @@ export function ListViewItem<T>(props: ListViewItemProps<T>) {
           <SlotProvider
             slots={{
               text: {UNSAFE_className: listStyles['react-spectrum-ListViewItem-content']},
-              description: {UNSAFE_className: listStyles['react-spectrum-ListViewItem-description']},
+              description: {UNSAFE_className: listStyles['react-spectrum-ListViewItem-description'], ...descriptionProps},
               icon: {UNSAFE_className: listStyles['react-spectrum-ListViewItem-icon'], size: 'M'},
               image: {UNSAFE_className: listStyles['react-spectrum-ListViewItem-image']},
               actionButton: {UNSAFE_className: listStyles['react-spectrum-ListViewItem-actions'], isQuiet: true},

packages/@react-spectrum/list/stories/ListView.stories.tsx

@@ -224,11 +224,11 @@ storiesOf('ListView', module)
     </ListView>
   ))
   .add('long text', args => (
-    <ListView width="250px" aria-label="long text ListView" {...args}>
-      <Item textValue="row 1">row 1 with a very very very very very long title</Item>
-      <Item textValue="row 2">
-        <Text>Text slot with a really really really long name</Text>
-        <Text slot="description">Description slot with a really really long name</Text>
+    <ListView width="250px" {...args}>
+      <Item textValue="Homeward Bound: The Incredible Journey">Homeward Bound: The Incredible Journey</Item>
+      <Item textValue="Monsters University">
+        <Text>Monsters University</Text>
+        <Text slot="description">As a first grader, Mike Wazowski begins to dream of becoming a Scarer</Text>
       </Item>
     </ListView>
   ));

packages/@react-spectrum/list/test/ListView.test.js

@@ -22,6 +22,7 @@ import {installPointerEvent, triggerPress} from '@react-spectrum/test-utils';
 import {Item, ListView} from '../src';
 import {Provider} from '@react-spectrum/provider';
 import React from 'react';
+import {Text} from '@react-spectrum/text';
 import {theme} from '@react-spectrum/theme-default';
 import userEvent from '@testing-library/user-event';
 
@@ -592,6 +593,21 @@ describe('ListView', function () {
     expect(grid).toHaveAttribute('data-testid', 'test');
   });
 
+  it('should use item description text as aria-describedby', function () {
+    let {getAllByRole} = render(
+      <ListView aria-label="List">
+        <Item textValue="Label">
+          <Text>Label</Text>
+          <Text slot="description">Description</Text>
+        </Item>
+      </ListView>
+    );
+
+    let rows = getAllByRole('row');
+    let description = within(rows[0]).getByText('Description');
+    expect(rows[0]).toHaveAttribute('aria-labelledby', `${rows[0].id} ${description.id}`);
+  });
+
   describe('selection', function () {
     let items = [
       {key: 'foo', label: 'Foo'},