feat: support description text in tree items

packages/dev/s2-docs/pages/react-aria/Tree.mdx

@@ -448,15 +448,18 @@ function Example() {
 
 ## API
 
+Place a `<Text slot="description">` inside `TreeItemContent` to provide an accessible description for a row. It is associated with the row using `aria-describedby`, keeping the row's accessible name separate from its description.
+
 <Anatomy role="img" aria-label="Anatomy diagram of a Tree, consisting of multiple items. Each item in the tree contains a selection checkbox, an expand toggle button, and the name of the item." />
 
-```tsx links={{Tree: '#tree', TreeItem: '#treeitem', TreeItemContent: '#treeitemcontent', TreeSection: '#treesection', TreeHeader: '#treeheader', Button: 'Button', Checkbox: 'Checkbox', TreeLoadMoreItem: '#treeloadmoreitem', SelectionIndicator: 'selection#animated-selectionindicator'}}
+```tsx links={{Tree: '#tree', TreeItem: '#treeitem', TreeItemContent: '#treeitemcontent', TreeSection: '#treesection', TreeHeader: '#treeheader', Button: 'Button', Checkbox: 'Checkbox', TreeLoadMoreItem: '#treeloadmoreitem', Text: 'Text', SelectionIndicator: 'selection#animated-selectionindicator'}}
 <Tree>
   <TreeItem>
     <TreeItemContent>
       <Button slot="chevron" />
       <Checkbox slot="selection" /> or <SelectionIndicator />
       <Button slot="drag" />
+      <Text slot="description" />
     </TreeItemContent>
     <TreeItem>
       {/* ... */}

packages/react-aria-components/src/Tree.tsx

@@ -107,6 +107,7 @@ import React, {
 } from 'react';
 import {SelectionIndicatorContext} from './SelectionIndicator';
 import {SharedElementTransition} from './SharedElementTransition';
+import {TextContext} from './Text';
 import {TreeDropTargetDelegate} from './TreeDropTargetDelegate';
 import {TreeState, useTreeState} from 'react-stately/useTreeState';
 import {useCachedChildren} from 'react-aria/private/collections/useCachedChildren';
@@ -782,8 +783,6 @@ export const TreeItem = /*#__PURE__*/ createBranchComponent(
     let isDraggable =
       dragState && !(dragState.isDisabled || dragState.selectionManager.isDisabled(item.key));
 
-    // TODO: remove this when we support description in tree row
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     let {rowProps, gridCellProps, expandButtonProps, descriptionProps, ...states} = useTreeItem(
       {
         node: item,
@@ -1020,7 +1019,7 @@ export const TreeItem = /*#__PURE__*/ createBranchComponent(
                     }
                   }
                 ],
-                // TODO: support description in the tree row
+                [TextContext, {slots: {[DEFAULT_SLOT]: {}, description: descriptionProps}}],
                 // TODO: don't think I need to pass isExpanded to the button here since it can be sourced from the renderProps? Might be worthwhile passing it down?
                 [
                   ButtonContext,

packages/react-aria-components/stories/Tree.stories.tsx

@@ -298,6 +298,36 @@ const TreeExampleStaticNoActionsRender = <T extends any>(args: TreeProps<T>): JS
   </Tree>
 );
 
+export const WithDescriptions: TreeStory = args => (
+  <Tree {...args} aria-label="Files" className={styles.tree} selectionMode="single">
+    <TreeItem id="projects" textValue="Projects" className={styles['tree-item']}>
+      <TreeItemContent>
+        {({isExpanded}) => (
+          <>
+            <Button slot="chevron">{isExpanded ? '⏷' : '⏵'}</Button>
+            <div>
+              <Text>Projects</Text>
+              <Text slot="description" style={{display: 'block'}}>
+                Shared project files
+              </Text>
+            </div>
+          </>
+        )}
+      </TreeItemContent>
+      <TreeItem id="report" textValue="Report" className={styles['tree-item']}>
+        <TreeItemContent>
+          <div>
+            <Text>Report</Text>
+            <Text slot="description" style={{display: 'block'}}>
+              Last updated today
+            </Text>
+          </div>
+        </TreeItemContent>
+      </TreeItem>
+    </TreeItem>
+  </Tree>
+);
+
 export const TreeExampleStatic: StoryObj<typeof TreeExampleStaticRender> = {
   render: args => <TreeExampleStaticRender {...args} />,
   args: {

packages/react-aria-components/test/Tree.test.tsx

@@ -411,6 +411,90 @@ describe('Tree', () => {
     }
   });
 
+  describe('descriptions', () => {
+    function DescriptionTree({
+      showDescription = true,
+      label
+    }: {
+      showDescription?: boolean;
+      label?: string;
+    }) {
+      return (
+        <Tree aria-label="Files" selectionMode="single">
+          <TreeItem id="projects" textValue="Projects" aria-label={label}>
+            <TreeItemContent>
+              <Button slot="chevron">Expand</Button>
+              <Text>Projects</Text>
+              {showDescription && (
+                <Text slot="description" id="tree-desc">
+                  Shared files
+                </Text>
+              )}
+            </TreeItemContent>
+            <TreeItem id="report" textValue="Report">
+              <TreeItemContent>Report</TreeItemContent>
+            </TreeItem>
+          </TreeItem>
+        </Tree>
+      );
+    }
+
+    it.each([undefined, 'Team projects'])(
+      'keeps the row name separate from its description (%s)',
+      label => {
+        let {getByRole, getByText} = render(<DescriptionTree label={label} />);
+        let row = getByRole('row', {name: label || 'Projects'});
+        expect(row).toHaveAccessibleDescription('Shared files');
+        expect(row).toHaveAttribute('aria-describedby', getByText('Shared files').id);
+        expect(row).not.toHaveAttribute('aria-labelledby');
+        expect(getByRole('button')).toHaveAccessibleName(`Expand ${label || 'Projects'}`);
+      }
+    );
+
+    it('updates the description relationship when the slot is removed and added', () => {
+      let {getByRole, rerender} = render(<DescriptionTree />);
+      expect(getByRole('row')).toHaveAccessibleDescription('Shared files');
+      rerender(<DescriptionTree showDescription={false} />);
+      expect(getByRole('row')).not.toHaveAttribute('aria-describedby');
+      rerender(<DescriptionTree />);
+      expect(getByRole('row')).toHaveAccessibleDescription('Shared files');
+    });
+
+    it('preserves keyboard selection and expansion with a description', async () => {
+      let {getByRole} = render(<DescriptionTree />);
+      await user.tab();
+      let row = getByRole('row', {name: 'Projects'});
+      expect(row).toHaveFocus();
+      await user.keyboard(' ');
+      expect(row).toHaveAttribute('aria-selected', 'true');
+      await user.keyboard('{ArrowRight}{ArrowDown}');
+      expect(row).toHaveAttribute('aria-expanded', 'true');
+      expect(getByRole('row', {name: 'Report'})).toHaveFocus();
+    });
+
+    it('preserves explicit labels and additional descriptions', () => {
+      let {getByRole} = render(
+        <>
+          <span id="row-description">Read only</span>
+          <Tree aria-label="Files">
+            <TreeItem
+              id="projects"
+              textValue="Projects"
+              aria-label="Team projects"
+              aria-describedby="row-description">
+              <TreeItemContent>
+                Projects <Text slot="description">Shared files</Text>
+              </TreeItemContent>
+            </TreeItem>
+          </Tree>
+        </>
+      );
+      expect(getByRole('row', {name: 'Team projects'})).toHaveAccessibleDescription(
+        'Read only Shared files'
+      );
+    });
+  });
+
   it('should render a Tree with custom classes', () => {
     let {getByRole, getAllByRole} = render(
       <StaticTree treeProps={{className: 'test-tree'}} rowProps={{className: 'test-row'}} />

packages/react-aria/src/gridlist/useGridListItem.ts

@@ -107,7 +107,7 @@ export function useGridListItem<T>(
   let {direction} = useLocale();
   let {onAction, linkBehavior, keyboardNavigationBehavior, shouldSelectOnPressUp} =
     listMap.get(state)!;
-  let descriptionId = useSlotId();
+  let descriptionId = useSlotId([node]);
 
   // We need to track the key of the item at the time it was last focused so that we force
   // focus to go to the item when the DOM node is reused for a different item in a virtualizer.

packages/react-aria/src/tree/useTreeItem.ts

@@ -81,6 +81,14 @@ export function useTreeItem<T>(
   // TODO: should it return a state specifically for isExpanded? Or is aria attribute sufficient?
   return {
     ...gridListAria,
+    rowProps: {
+      ...gridListAria.rowProps,
+      'aria-labelledby': undefined,
+      'aria-describedby':
+        [node.props['aria-describedby'], gridListAria.descriptionProps.id]
+          .filter(Boolean)
+          .join(' ') || undefined
+    },
     expandButtonProps
   };
 }