BREAKING: refactor useTable to be composable

change/@fluentui-react-table-ccf8542c-a19a-4fa9-a941-4b5fa851901f.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "BREAKING: refactor `useTable` to be composable",
+  "packageName": "@fluentui/react-table",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

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

@@ -27,6 +27,14 @@ export interface ColumnDefinition<TItem> {
 // @public (undocumented)
 export type ColumnId = string | number;
 
+// @public (undocumented)
+export interface HeadlessTableState<TItem> extends Pick<UseTableOptions<TItem>, 'items' | 'getRowId'> {
+    columns: ColumnDefinition<TItem>[];
+    getRows: <TRowState extends RowState<TItem> = RowState<TItem>>(rowEnhancer?: RowEnhancer<TItem, TRowState>) => TRowState[];
+    selection: TableSelectionState;
+    sort: TableSortState<TItem>;
+}
+
 // @public
 export const renderTable_unstable: (state: TableState, contextValues: TableContextValues) => JSX.Element;
 
@@ -270,7 +278,7 @@ export interface TableSelectionState {
     clearRows: () => void;
     deselectRow: (rowId: RowId) => void;
     isRowSelected: (rowId: RowId) => boolean;
-    selectedRows: RowId[];
+    selectedRows: Set<RowId>;
     selectRow: (rowId: RowId) => void;
     someRowsSelected: boolean;
     toggleAllRows: () => void;
@@ -283,9 +291,10 @@ export type TableSlots = {
 };
 
 // @public (undocumented)
-export interface TableSortState {
+export interface TableSortState<TItem> {
     getSortDirection: (columnId: ColumnId) => SortDirection | undefined;
     setColumnSort: (columnId: ColumnId, sortDirection: SortDirection) => void;
+    sort: (rows: RowState<TItem>[]) => RowState<TItem>[];
     sortColumn: ColumnId | undefined;
     sortDirection: SortDirection;
     toggleColumnSort: (columnId: ColumnId) => void;
@@ -295,7 +304,16 @@ export interface TableSortState {
 export type TableState = ComponentState<TableSlots> & Pick<Required<TableProps>, 'size' | 'noNativeElements'> & TableContextValue;
 
 // @public (undocumented)
-export function useTable<TItem, TRowState extends RowState<TItem> = RowState<TItem>>(options: UseTableOptions<TItem, TRowState>): TableState_2<TItem, TRowState>;
+export type TableStatePlugin = <TItem>(tableState: HeadlessTableState<TItem>) => HeadlessTableState<TItem>;
+
+// @public (undocumented)
+export function useSelection<TItem>(options: UseSelectionOptions): (tableState: HeadlessTableState<TItem>) => HeadlessTableState<TItem>;
+
+// @public (undocumented)
+export function useSort<TItem>(options: UseSortOptions): (tableState: HeadlessTableState<TItem>) => HeadlessTableState<TItem>;
+
+// @public (undocumented)
+export function useTable<TItem>(options: UseTableOptions<TItem>, plugins?: TableStatePlugin[]): HeadlessTableState<TItem>;
 
 // @public
 export const useTable_unstable: (props: TableProps, ref: React_2.Ref<HTMLElement>) => TableState;
@@ -340,23 +358,13 @@ export const useTableHeaderCellStyles_unstable: (state: TableHeaderCellState) =>
 export const useTableHeaderStyles_unstable: (state: TableHeaderState) => TableHeaderState;
 
 // @public (undocumented)
-export interface UseTableOptions<TItem, TRowState extends RowState<TItem> = RowState<TItem>> {
+export interface UseTableOptions<TItem> {
     // (undocumented)
     columns: ColumnDefinition<TItem>[];
-    defaultSelectedRows?: Set<RowId>;
-    defaultSortState?: SortState;
     // (undocumented)
     getRowId?: (item: TItem) => RowId;
     // (undocumented)
     items: TItem[];
-    onSelectionChange?: OnSelectionChangeCallback;
-    onSortChange?: OnSortChangeCallback;
-    // (undocumented)
-    rowEnhancer?: RowEnhancer<TItem, TRowState>;
-    selectedRows?: Set<RowId>;
-    // (undocumented)
-    selectionMode?: SelectionMode_2;
-    sortState?: SortState;
 }
 
 // @public

packages/react-components/react-table/src/common/mockTableState.ts

@@ -0,0 +1,15 @@
+import type { TableState, TableSortState } from '../hooks';
+import { defaultTableSelectionState, defaultTableSortState } from '../hooks';
+
+export const mockTableState = <TItem = unknown>(options: Partial<TableState<TItem>> = {}) => {
+  const mockState: TableState<TItem> = {
+    columns: [],
+    getRows: () => [],
+    items: [],
+    selection: defaultTableSelectionState,
+    sort: defaultTableSortState as TableSortState<TItem>,
+    ...options,
+  };
+
+  return mockState;
+};

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

@@ -1,2 +1,4 @@
 export * from './types';
 export * from './useTable';
+export * from './useSort';
+export * from './useSelection';

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

@@ -2,10 +2,7 @@ import { SortDirection } from '../components/Table/Table.types';
 
 export type RowId = string | number;
 export type ColumnId = string | number;
-export type GetRowIdInternal<TItem> = (rowId: TItem, index: number) => RowId;
 export type SelectionMode = 'single' | 'multiselect';
-export type OnSelectionChangeCallback = (selectedItems: Set<RowId>) => void;
-export type OnSortChangeCallback = (state: { sortColumn: ColumnId | undefined; sortDirection: SortDirection }) => void;
 
 export interface SortState {
   sortColumn: ColumnId | undefined;
@@ -19,66 +16,9 @@ export interface ColumnDefinition<TItem> {
 
 export type RowEnhancer<TItem, TRowState extends RowState<TItem> = RowState<TItem>> = (
   row: RowState<TItem>,
-  state: { selection: TableSelectionState; sort: TableSortState },
 ) => TRowState;
 
-export interface TableSortStateInternal<TItem> {
-  sortDirection: SortDirection;
-  sortColumn: ColumnId | undefined;
-  setColumnSort: (columnId: ColumnId, sortDirection: SortDirection) => void;
-  toggleColumnSort: (columnId: ColumnId) => void;
-  getSortDirection: (columnId: ColumnId) => SortDirection | undefined;
-  /**
-   * Returns a sorted **shallow** copy of original items
-   */
-  sort: (items: TItem[]) => TItem[];
-}
-
-export interface UseTableOptions<TItem, TRowState extends RowState<TItem> = RowState<TItem>> {
-  columns: ColumnDefinition<TItem>[];
-  items: TItem[];
-  selectionMode?: SelectionMode;
-  /**
-   * Used in uncontrolled mode to set initial selected rows on mount
-   */
-  defaultSelectedRows?: Set<RowId>;
-  /**
-   * Used to control row selection
-   */
-  selectedRows?: Set<RowId>;
-  /**
-   * Called when selection changes
-   */
-  onSelectionChange?: OnSelectionChangeCallback;
-  /**
-   * Used to control sorting
-   */
-  sortState?: SortState;
-  /**
-   * Used in uncontrolled mode to set initial sort column and direction on mount
-   */
-  defaultSortState?: SortState;
-  /**
-   * Called when sort changes
-   */
-  onSortChange?: OnSortChangeCallback;
-  getRowId?: (item: TItem) => RowId;
-  rowEnhancer?: RowEnhancer<TItem, TRowState>;
-}
-
-export interface TableSelectionStateInternal {
-  clearRows: () => void;
-  deselectRow: (rowId: RowId) => void;
-  selectRow: (rowId: RowId) => void;
-  toggleAllRows: () => void;
-  toggleRow: (rowId: RowId) => void;
-  isRowSelected: (rowId: RowId) => boolean;
-  selectedRows: Set<RowId>;
-  allRowsSelected: boolean;
-  someRowsSelected: boolean;
-}
-
-export interface TableSortState {
+export interface TableSortState<TItem> {
   /**
    * Current sort direction
    */
@@ -100,6 +40,11 @@ export interface TableSortState {
    * returns undefined if the column is not sorted
    */
   getSortDirection: (columnId: ColumnId) => SortDirection | undefined;
+
+  /**
+   * Sorts rows and returns a **shallow** copy of original items
+   */
+  sort: (rows: RowState<TItem>[]) => RowState<TItem>[];
 }
 
 export interface TableSelectionState {
@@ -126,7 +71,7 @@ export interface TableSelectionState {
   /**
    * Collection of row ids corresponding to selected rows
    */
-  selectedRows: RowId[];
+  selectedRows: Set<RowId>;
   /**
    * Whether all rows are selected
    */
@@ -153,17 +98,66 @@ export interface RowState<TItem> {
   rowId: RowId;
 }
 
-export interface TableState<TItem, TRowState extends RowState<TItem> = RowState<TItem>> {
+export interface TableState<TItem> extends Pick<UseTableOptions<TItem>, 'items' | 'getRowId'> {
   /**
    * The row data for rendering
+   * @param rowEnhancer - Enhances the row with extra user data
    */
-  rows: TRowState[];
+  getRows: <TRowState extends RowState<TItem> = RowState<TItem>>(
+    rowEnhancer?: RowEnhancer<TItem, TRowState>,
+  ) => TRowState[];
   /**
    * State and actions to manage row selection
    */
   selection: TableSelectionState;
   /**
    * State and actions to manage row sorting
    */
-  sort: TableSortState;
+  sort: TableSortState<TItem>;
+  /**
+   * Table columns
+   */
+  columns: ColumnDefinition<TItem>[];
+}
+
+export interface UseSortOptions {
+  /**
+   * Used to control sorting
+   */
+  sortState?: SortState;
+  /**
+   * Used in uncontrolled mode to set initial sort column and direction on mount
+   */
+  defaultSortState?: SortState;
+  /**
+   * Called when sort changes
+   */
+  onSortChange?: (state: SortState) => void;
 }
+
+export interface UseSelectionOptions {
+  /**
+   * Can be multi or single select
+   */
+  selectionMode: SelectionMode;
+  /**
+   * Used in uncontrolled mode to set initial selected rows on mount
+   */
+  defaultSelectedItems?: Set<RowId>;
+  /**
+   * Used to control row selection
+   */
+  selectedItems?: Set<RowId>;
+  /**
+   * Called when selection changes
+   */
+  onSelectionChange?: (selectedItems: Set<RowId>) => void;
+}
+
+export interface UseTableOptions<TItem> {
+  columns: ColumnDefinition<TItem>[];
+  items: TItem[];
+  getRowId?: (item: TItem) => RowId;
+}
+
+export type TableStatePlugin = <TItem>(tableState: TableState<TItem>) => TableState<TItem>;