feat: Implement focusMode prop for DataGrid, apply role="grid" correctly

change/@fluentui-react-table-7398941b-ae22-4a18-878d-1ac8e853c6ee.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat: Implement `focusMode` prop for DataGrid, apply role=\"grid\" correctly",
+  "packageName": "@fluentui/react-table",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-table/etc/react-table.api.md

@@ -90,7 +90,9 @@ export type DataGridCellState = TableCellState;
 export const dataGridClassNames: SlotClassNames<DataGridSlots>;
 
 // @public (undocumented)
-export type DataGridContextValue = HeadlessTableState<any>;
+export type DataGridContextValue = HeadlessTableState<any> & {
+    focusMode: FocusMode;
+};
 
 // @public (undocumented)
 export type DataGridContextValues = TableContextValues & {
@@ -128,7 +130,7 @@ export type DataGridHeaderSlots = TableHeaderSlots;
 export type DataGridHeaderState = TableHeaderState;
 
 // @public
-export type DataGridProps = TableProps & Pick<DataGridContextValue, 'items' | 'columns'>;
+export type DataGridProps = TableProps & Pick<DataGridContextValue, 'items' | 'columns'> & Pick<Partial<DataGridContextValue>, 'focusMode'>;
 
 // @public
 export const DataGridRow: ForwardRefComponent<DataGridRowProps>;
@@ -168,7 +170,10 @@ export type DataGridSlots = TableSlots;
 // @public
 export type DataGridState = TableState & {
     tableState: HeadlessTableState<unknown>;
-};
+} & Pick<DataGridContextValue, 'focusMode'>;
+
+// @public (undocumented)
+export type FocusMode = 'none' | 'cell';
 
 // @public (undocumented)
 export interface HeadlessTableState<TItem> extends Pick<UseTableOptions<TItem>, 'items' | 'getRowId'> {

packages/react-components/react-table/src/components/DataGrid/DataGrid.test.tsx

@@ -51,4 +51,69 @@ describe('DataGrid', () => {
     );
     expect(result.container).toMatchSnapshot();
   });
+
+  it('should render tabster attributes when `focusMode` has value `cell`', () => {
+    const result = render(
+      <DataGrid items={testItems} columns={testColumns} focusMode="cell">
+        <DataGridHeader>
+          <DataGridRow>
+            {({ renderHeaderCell, columnId }) => <DataGridCell key={columnId}>{renderHeaderCell()}</DataGridCell>}
+          </DataGridRow>
+        </DataGridHeader>
+        <DataGridBody>
+          {({ item, rowId }: RowState<Item>) => (
+            <DataGridRow key={rowId}>
+              {({ renderCell, columnId }) => <DataGridCell key={columnId}>{renderCell(item)}</DataGridCell>}
+            </DataGridRow>
+          )}
+        </DataGridBody>
+      </DataGrid>,
+    );
+
+    expect(result.getByRole('grid').getAttribute('data-tabster')).toMatchInlineSnapshot(
+      `"{\\"mover\\":{\\"cyclic\\":false,\\"direction\\":3}}"`,
+    );
+  });
+
+  it('should not render tabster attributes when `focusMode` has value `none`', () => {
+    const result = render(
+      <DataGrid items={testItems} columns={testColumns} focusMode="none">
+        <DataGridHeader>
+          <DataGridRow>
+            {({ renderHeaderCell, columnId }) => <DataGridCell key={columnId}>{renderHeaderCell()}</DataGridCell>}
+          </DataGridRow>
+        </DataGridHeader>
+        <DataGridBody>
+          {({ item, rowId }: RowState<Item>) => (
+            <DataGridRow key={rowId}>
+              {({ renderCell, columnId }) => <DataGridCell key={columnId}>{renderCell(item)}</DataGridCell>}
+            </DataGridRow>
+          )}
+        </DataGridBody>
+      </DataGrid>,
+    );
+
+    expect(result.getByRole('grid').hasAttribute('data-tabster')).toBe(false);
+  });
+
+  it('should not render tabster attributes when `focusMode` prop is not set', () => {
+    const result = render(
+      <DataGrid items={testItems} columns={testColumns}>
+        <DataGridHeader>
+          <DataGridRow>
+            {({ renderHeaderCell, columnId }) => <DataGridCell key={columnId}>{renderHeaderCell()}</DataGridCell>}
+          </DataGridRow>
+        </DataGridHeader>
+        <DataGridBody>
+          {({ item, rowId }: RowState<Item>) => (
+            <DataGridRow key={rowId}>
+              {({ renderCell, columnId }) => <DataGridCell key={columnId}>{renderCell(item)}</DataGridCell>}
+            </DataGridRow>
+          )}
+        </DataGridBody>
+      </DataGrid>,
+    );
+
+    expect(result.getByRole('grid').hasAttribute('data-tabster')).toBe(false);
+  });
 });

packages/react-components/react-table/src/components/DataGrid/DataGrid.types.ts

@@ -3,21 +3,34 @@ import { TableState as HeadlessTableState } from '../../hooks';
 
 export type DataGridSlots = TableSlots;
 
+export type FocusMode = 'none' | 'cell';
+
 export type DataGridContextValues = TableContextValues & {
   dataGrid: DataGridContextValue;
 };
 
 // Use any here since we can't know the user types
 // The user is responsible for narrowing the type downstream
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type DataGridContextValue = HeadlessTableState<any>;
+export type DataGridContextValue = HeadlessTableState<any> & {
+  /**
+   * How focus navigation will work in the datagrid
+   * @default none
+   */
+  focusMode: FocusMode;
+};
 
 /**
  * DataGrid Props
  */
-export type DataGridProps = TableProps & Pick<DataGridContextValue, 'items' | 'columns'>;
+export type DataGridProps = TableProps &
+  Pick<DataGridContextValue, 'items' | 'columns'> &
+  Pick<Partial<DataGridContextValue>, 'focusMode'>;
 
 /**
  * State used in rendering DataGrid
  */
-export type DataGridState = TableState & { tableState: HeadlessTableState<unknown> };
+export type DataGridState = TableState & { tableState: HeadlessTableState<unknown> } & Pick<
+    DataGridContextValue,
+    'focusMode'
+  >;

packages/react-components/react-table/src/components/DataGrid/__snapshots__/DataGrid.test.tsx.snap

@@ -4,7 +4,7 @@ exports[`DataGrid renders a default state 1`] = `
 <div>
   <div
     class="fui-DataGrid fui-Table"
-    role="table"
+    role="grid"
   >
     <div
       class="fui-DataGridHeader fui-TableHeader"
@@ -16,19 +16,19 @@ exports[`DataGrid renders a default state 1`] = `
       >
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           first
         </div>
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           second
         </div>
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           third
         </div>
@@ -44,19 +44,19 @@ exports[`DataGrid renders a default state 1`] = `
       >
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           first
         </div>
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           second
         </div>
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           third
         </div>
@@ -67,19 +67,19 @@ exports[`DataGrid renders a default state 1`] = `
       >
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           first
         </div>
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           second
         </div>
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           third
         </div>
@@ -90,19 +90,19 @@ exports[`DataGrid renders a default state 1`] = `
       >
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           first
         </div>
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           second
         </div>
         <div
           class="fui-DataGridCell fui-TableCell"
-          role="cell"
+          role="gridcell"
         >
           third
         </div>

packages/react-components/react-table/src/components/DataGrid/useDataGrid.ts

@@ -1,4 +1,5 @@
 import * as React from 'react';
+import { useArrowNavigationGroup } from '@fluentui/react-tabster';
 import type { DataGridProps, DataGridState } from './DataGrid.types';
 import { useTable_unstable } from '../Table/useTable';
 import { useTable } from '../../hooks/useTable';
@@ -13,12 +14,18 @@ import { useTable } from '../../hooks/useTable';
  * @param ref - reference to root HTMLElement of DataGrid
  */
 export const useDataGrid_unstable = (props: DataGridProps, ref: React.Ref<HTMLElement>): DataGridState => {
-  const { items, columns } = props;
+  const { items, columns, focusMode = 'none' } = props;
+  const navigable = focusMode !== 'none';
+  const keyboardNavAttr = useArrowNavigationGroup({ axis: 'grid' });
   const tableState = useTable({ items, columns }, []);
-  const baseTableState = useTable_unstable({ ...props, as: 'div' }, ref);
+  const baseTableState = useTable_unstable(
+    { role: 'grid', as: 'div', ...(navigable && keyboardNavAttr), ...props },
+    ref,
+  );
 
   return {
     ...baseTableState,
+    focusMode,
     tableState,
   };
 };

packages/react-components/react-table/src/components/DataGrid/useDataGridContextValues.ts

@@ -7,6 +7,7 @@ export function useDataGridContextValues_unstable(state: DataGridState): DataGri
     ...tableContextValues,
     dataGrid: {
       ...state.tableState,
+      focusMode: state.focusMode,
     },
   };
 }

packages/react-components/react-table/src/components/DataGridCell/DataGridCell.test.tsx

@@ -3,17 +3,40 @@ import { render } from '@testing-library/react';
 import { DataGridCell } from './DataGridCell';
 import { isConformant } from '../../testing/isConformant';
 import { DataGridCellProps } from './DataGridCell.types';
+import { DataGridContextProvider } from '../../contexts/dataGridContext';
+import { mockDataGridContext } from '../../testing/mockDataGridContext';
 
 describe('DataGridCell', () => {
   isConformant<DataGridCellProps>({
     Component: DataGridCell,
     displayName: 'DataGridCell',
   });
 
-  // TODO add more tests here, and create visual regression tests in /apps/vr-tests
-
   it('renders a default state', () => {
     const result = render(<DataGridCell>Default DataGridCell</DataGridCell>);
     expect(result.container).toMatchSnapshot();
   });
+
+  it('should set tabindex="0" when focusMode is cell', () => {
+    const context = mockDataGridContext({ focusMode: 'cell' });
+    const result = render(
+      <DataGridContextProvider value={context}>
+        <DataGridCell>Default DataGridCell</DataGridCell>
+      </DataGridContextProvider>,
+    );
+
+    expect(result.getByRole('gridcell').tabIndex).toBe(0);
+  });
+
+  it('should not set tabindex when focusMode is none', () => {
+    const context = mockDataGridContext({ focusMode: 'none' });
+    const result = render(
+      <DataGridContextProvider value={context}>
+        <DataGridCell>Default DataGridCell</DataGridCell>
+      </DataGridContextProvider>,
+    );
+
+    expect(result.getByRole('gridcell').tabIndex).toBe(-1);
+    expect(result.getByRole('gridcell').hasAttribute('tabindex')).toBe(false);
+  });
 });

packages/react-components/react-table/src/components/DataGridCell/__snapshots__/DataGridCell.test.tsx.snap

@@ -4,7 +4,8 @@ exports[`DataGridCell renders a default state 1`] = `
 <div>
   <div
     class="fui-DataGridCell fui-TableCell"
-    role="cell"
+    role="gridcell"
+    tabindex="0"
   >
     Default DataGridCell
   </div>

packages/react-components/react-table/src/components/DataGridCell/useDataGridCell.ts

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import type { DataGridCellProps, DataGridCellState } from './DataGridCell.types';
 import { useTableCell_unstable } from '../TableCell/useTableCell';
+import { useDataGridContext_unstable } from '../../contexts/dataGridContext';
 
 /**
  * Create the state required to render DataGridCell.
@@ -12,5 +13,6 @@ import { useTableCell_unstable } from '../TableCell/useTableCell';
  * @param ref - reference to root HTMLElement of DataGridCell
  */
 export const useDataGridCell_unstable = (props: DataGridCellProps, ref: React.Ref<HTMLElement>): DataGridCellState => {
-  return useTableCell_unstable({ ...props, as: 'div' }, ref);
+  const tabbable = useDataGridContext_unstable(ctx => ctx.focusMode !== 'none');
+  return useTableCell_unstable({ as: 'div', role: 'gridcell', tabIndex: tabbable ? 0 : undefined, ...props }, ref);
 };

packages/react-components/react-table/src/components/DataGridSelectionCell/__snapshots__/DataGridSelectionCell.test.tsx.snap

@@ -4,7 +4,7 @@ exports[`DataGridSelectionCell renders a default state 1`] = `
 <div>
   <div
     class="fui-DataGridSelectionCell fui-TableSelectionCell"
-    role="cell"
+    role="gridcell"
   >
     <span
       class="fui-Checkbox fui-DataGridSelectionCell__checkboxIndicator fui-TableSelectionCell__checkboxIndicator"

packages/react-components/react-table/src/components/DataGridSelectionCell/useDataGridSelectionCell.ts

@@ -15,5 +15,5 @@ export const useDataGridSelectionCell_unstable = (
   props: DataGridSelectionCellProps,
   ref: React.Ref<HTMLElement>,
 ): DataGridSelectionCellState => {
-  return useTableSelectionCell_unstable({ ...props, as: 'div' }, ref);
+  return useTableSelectionCell_unstable({ as: 'div', role: 'gridcell', ...props }, ref);
 };

packages/react-components/react-table/src/contexts/dataGridContext.ts

@@ -7,6 +7,7 @@ const dataGridContext = createContext<DataGridContextValue | undefined>(undefine
 
 const dataGridContextDefaultValue: DataGridContextValue = {
   ...defaultTableState,
+  focusMode: 'none',
 };
 
 export const DataGridContextProvider = dataGridContext.Provider;

packages/react-components/react-table/src/index.ts

@@ -140,6 +140,7 @@ export type {
   DataGridState,
   DataGridContextValues,
   DataGridContextValue,
+  FocusMode,
 } from './DataGrid';
 
 export {