feat: #10121 Implemented the Table Column Header Focus

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

@@ -615,6 +615,13 @@ export interface TableProps
    * the Table.
    */
   dragAndDropHooks?: DragAndDropHooks;
+  /**
+   * Whether the first row or the first column header should be focused when the user tabs into the
+   * table.
+   *
+   * @default 'row'
+   */
+  initialFocus?: 'row' | 'columnheader';
 }
 
 /**

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

@@ -988,6 +988,59 @@ export const OnLoadMoreTableStory: StoryObj<typeof OnLoadMoreTable> = {
   }
 };
 
+const InitialFocusExample = (args: {
+  initialFocus?: 'row' | 'columnheader';
+  selectionMode?: 'none' | 'single' | 'multiple';
+}) => (
+  <div style={{display: 'flex', flexDirection: 'column', gap: 8}}>
+    <Table aria-label="Files" {...args}>
+      <TableHeader>
+        <Column isRowHeader allowsSorting>
+          Name
+        </Column>
+        <Column allowsSorting>Type</Column>
+        <Column allowsSorting>Date Modified</Column>
+      </TableHeader>
+      <TableBody>
+        <Row id="1">
+          <Cell>Games</Cell>
+          <Cell>File folder</Cell>
+          <Cell>6/7/2020</Cell>
+        </Row>
+        <Row id="2">
+          <Cell>Program Files</Cell>
+          <Cell>File folder</Cell>
+          <Cell>4/7/2021</Cell>
+        </Row>
+        <Row id="3">
+          <Cell>bootmgr</Cell>
+          <Cell>System file</Cell>
+          <Cell>11/20/2010</Cell>
+        </Row>
+      </TableBody>
+    </Table>
+  </div>
+);
+
+export const InitialFocusExampleStory: StoryObj<typeof InitialFocusExample> = {
+  render: InitialFocusExample,
+  name: 'initialFocus="columnheader"',
+  args: {
+    initialFocus: 'columnheader',
+    selectionMode: 'multiple'
+  },
+  argTypes: {
+    initialFocus: {
+      control: 'radio',
+      options: ['row', 'columnheader']
+    },
+    selectionMode: {
+      control: 'radio',
+      options: ['none', 'single', 'multiple']
+    }
+  }
+};
+
 export const VirtualizedTable: TableStory = () => {
   let items: {id: number; foo: string; bar: string; baz: string}[] = [];
   for (let i = 0; i < 1000; i++) {

packages/react-aria-components/test/Table.test.js

@@ -861,6 +861,65 @@ describe('Table', () => {
     expect(column).toHaveClass('focus');
   });
 
+  it('should focus the first column header when tabbing in with initialFocus="columnheader"', async () => {
+    let {getAllByRole} = renderTable({tableProps: {initialFocus: 'columnheader'}});
+
+    await user.tab();
+    expect(document.activeElement).toBe(getAllByRole('columnheader')[0]);
+  });
+
+  it('should move focus from a focused column header to the first row cell with ArrowDown when initialFocus="columnheader"', async () => {
+    let {getAllByRole} = renderTable({tableProps: {initialFocus: 'columnheader'}});
+
+    await user.tab();
+    let columnHeader = getAllByRole('columnheader')[0];
+    expect(document.activeElement).toBe(columnHeader);
+
+    await user.keyboard('{ArrowDown}');
+
+    let cell = getAllByRole('rowheader')[0];
+    expect(document.activeElement).toBe(cell);
+  });
+
+  it('should still focus the first cell in a row with Home when initialFocus="columnheader"', async () => {
+    let {getAllByRole} = renderTable({tableProps: {initialFocus: 'columnheader'}});
+
+    await user.tab();
+    let columnHeader = getAllByRole('columnheader')[0];
+
+    expect(document.activeElement).toBe(columnHeader);
+
+    await user.keyboard('{ArrowDown}');
+
+    let cell1 = getAllByRole('rowheader')[0];
+    expect(document.activeElement).toBe(cell1);
+
+    await user.keyboard('{ArrowRight}');
+
+    let cell2 = getAllByRole('gridcell')[0];
+    expect(document.activeElement).toBe(cell2);
+
+    await user.keyboard('{Home}');
+
+    expect(document.activeElement).toBe(cell1);
+  });
+
+  it('should focus the selected row rather than the first column header when tabbing in with initialFocus="columnheader" if a row is already selected', async () => {
+    let {getAllByRole} = renderTable({
+      tableProps: {
+        initialFocus: 'columnheader',
+        selectionMode: 'single',
+        defaultSelectedKeys: ['1']
+      }
+    });
+
+    let selectedRow = getAllByRole('row')[1];
+    expect(selectedRow).toHaveAttribute('aria-selected', 'true');
+
+    await user.tab();
+    expect(document.activeElement).toBe(selectedRow);
+  });
+
   it('should support press state', async () => {
     let {getAllByRole} = renderTable({
       tableProps: {selectionMode: 'multiple'},

packages/react-aria/src/dnd/DropTargetKeyboardNavigation.ts

@@ -24,6 +24,25 @@ export function navigate(
   }
 }
 
+export function getFirstItemKey(
+  keyboardDelegate: KeyboardDelegate,
+  collection: Collection<Node<unknown>>
+): Key | null {
+  let key = keyboardDelegate.getFirstKey?.() ?? null;
+  let item = key != null ? collection.getItem(key) : null;
+  if (item && item.type !== 'item') {
+    // If the delegate returns a non-item (e.g. column header), return the first item in the collection.
+    // This ensures DnD always starts at rows.
+    for (let node of collection) {
+      if (node.type === 'item') {
+        return node.key;
+      }
+    }
+    return null;
+  }
+  return key;
+}
+
 function nextDropTarget(
   keyboardDelegate: KeyboardDelegate,
   collection: Collection<Node<unknown>>,
@@ -38,7 +57,7 @@ function nextDropTarget(
   }
 
   if (target.type === 'root') {
-    let nextKey = keyboardDelegate.getFirstKey?.() ?? null;
+    let nextKey = getFirstItemKey(keyboardDelegate, collection);
     if (nextKey != null) {
       return {
         type: 'item',

packages/react-aria/src/dnd/useDroppableCollection.ts

@@ -35,9 +35,9 @@ import {
 } from '@react-types/shared';
 import * as DragManager from './DragManager';
 import {DroppableCollectionState} from 'react-stately/useDroppableCollectionState';
+import {getFirstItemKey, navigate} from './DropTargetKeyboardNavigation';
 import {HTMLAttributes, useCallback, useEffect, useRef} from 'react';
 import {mergeProps} from '../utils/mergeProps';
-import {navigate} from './DropTargetKeyboardNavigation';
 import {setInteractionModality} from '../interactions/useFocusVisible';
 import {useAutoScroll} from './useAutoScroll';
 import {useDrop} from './useDrop';
@@ -665,7 +665,7 @@ export function useDroppableCollection(
                 target = nextValidTarget(null, types, drag.allowedDropOperations, getNextTarget);
               } else {
                 // If on the root, go to the item a page below the top. Otherwise a page below the current item.
-                let targetKey = keyboardDelegate.getFirstKey?.();
+                let targetKey = getFirstItemKey(keyboardDelegate, localState.state.collection);
                 if (target.type === 'item') {
                   targetKey = target.key;
                 }
@@ -737,15 +737,15 @@ export function useDroppableCollection(
               target = nextValidTarget(null, types, drag.allowedDropOperations, getPreviousTarget);
             } else if (target.type === 'item') {
               // If at the top already, switch to the root. Otherwise navigate a page up.
-              if (target.key === keyboardDelegate.getFirstKey?.()) {
+              if (target.key === getFirstItemKey(keyboardDelegate, localState.state.collection)) {
                 target = {
                   type: 'root'
                 };
               } else {
                 let nextKey: Key | null | undefined = keyboardDelegate.getKeyPageAbove(target.key);
                 let dropPosition = target.dropPosition;
                 if (nextKey == null) {
-                  nextKey = keyboardDelegate.getFirstKey?.();
+                  nextKey = getFirstItemKey(keyboardDelegate, localState.state.collection);
                   dropPosition = 'before';
                 }
 

packages/react-aria/src/table/TableKeyboardDelegate.ts

@@ -11,15 +11,46 @@
  */
 
 import {getChildNodes, getFirstItem} from 'react-stately/private/collections/getChildNodes';
-import {GridKeyboardDelegate} from '../grid/GridKeyboardDelegate';
+import {GridKeyboardDelegate, GridKeyboardDelegateOptions} from '../grid/GridKeyboardDelegate';
 import {ITableCollection} from 'react-stately/private/table/TableCollection';
 import {Key, Node} from '@react-types/shared';
 
+export interface TableKeyboardDelegateOptions<T> extends GridKeyboardDelegateOptions<
+  ITableCollection<T>
+> {
+  /**
+   * Whether the first row or the first column header should be focused when the user tabs into the
+   * table.
+   *
+   * @default 'row'
+   */
+  initialFocus?: 'row' | 'columnheader';
+}
+
 export class TableKeyboardDelegate<T> extends GridKeyboardDelegate<T, ITableCollection<T>> {
+  private initialFocus: 'row' | 'columnheader';
+
+  constructor(options: TableKeyboardDelegateOptions<T>) {
+    super(options);
+    this.initialFocus = options.initialFocus ?? 'row';
+  }
+
   protected isCell(node: Node<T>): boolean {
     return node.type === 'cell' || node.type === 'rowheader' || node.type === 'column';
   }
 
+  getFirstKey(fromKey?: Key, global?: boolean): Key | null {
+    if (fromKey == null && this.initialFocus === 'columnheader') {
+      let firstColumn = this.collection.columns.find(
+        column => !column.props?.isDragButtonCell && !column.props?.isSelectionCell
+      );
+      if (firstColumn) {
+        return firstColumn.key;
+      }
+    }
+    return super.getFirstKey(fromKey, global);
+  }
+
   getKeyBelow(key: Key, options?: {includeDisabled?: boolean}): Key | null {
     let startItem = this.collection.getItem(key);
     if (!startItem) {
@@ -34,7 +65,7 @@ export class TableKeyboardDelegate<T> extends GridKeyboardDelegate<T, ITableColl
         return child.key;
       }
 
-      let firstKey = this.getFirstKey();
+      let firstKey = super.getFirstKey();
       if (firstKey == null) {
         return null;
       }

packages/react-aria/src/table/useTable.ts

@@ -36,6 +36,13 @@ export interface AriaTableProps extends GridProps {
   layoutDelegate?: LayoutDelegate;
   /** @deprecated - Use layoutDelegate instead. */
   layout?: DeprecatedLayout;
+  /**
+   * Whether the first row or the first column header should be focused when the user tabs into the
+   * table.
+   *
+   * @default 'row'
+   */
+  initialFocus?: 'row' | 'columnheader';
 }
 
 interface DeprecatedLayout {
@@ -66,7 +73,7 @@ export function useTable<T>(
   state: TableState<T> | TreeGridState<T>,
   ref: RefObject<HTMLElement | null>
 ): GridAria {
-  let {keyboardDelegate, isVirtualized, layoutDelegate, layout} = props;
+  let {keyboardDelegate, isVirtualized, layoutDelegate, layout, initialFocus} = props;
 
   // By default, a KeyboardDelegate is provided which uses the DOM to query layout information (e.g. for page up/page down).
   // When virtualized, the layout object will be passed in as a prop and override this.
@@ -84,7 +91,8 @@ export function useTable<T>(
         direction,
         collator,
         layoutDelegate,
-        layout
+        layout,
+        initialFocus
       }),
     [
       keyboardDelegate,
@@ -95,7 +103,8 @@ export function useTable<T>(
       direction,
       collator,
       layoutDelegate,
-      layout
+      layout,
+      initialFocus
     ]
   );
   let id = useId(props.id);