BREAKING: useTable renamed to useTableFeatures

change/@fluentui-react-components-751955cf-f7fb-477a-9ea1-537da4c2754b.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "BREAKING: `useTable` renamed to `useTableFeatures`",
+  "packageName": "@fluentui/react-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-table-d05cfee5-5a24-46f8-99a4-05010ebfdc30.json

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

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

@@ -262,7 +262,6 @@ import { useSelect_unstable } from '@fluentui/react-select';
 import { useSelection } from '@fluentui/react-table';
 import { useSelectStyles_unstable } from '@fluentui/react-select';
 import { useSort } from '@fluentui/react-table';
-import { useTable } from '@fluentui/react-table';
 import { useTable_unstable } from '@fluentui/react-table';
 import { useTableBody_unstable } from '@fluentui/react-table';
 import { useTableBodyStyles_unstable } from '@fluentui/react-table';
@@ -273,6 +272,7 @@ import { useTableCellLayout_unstable } from '@fluentui/react-table';
 import { useTableCellLayoutStyles_unstable } from '@fluentui/react-table';
 import { useTableCellStyles_unstable } from '@fluentui/react-table';
 import { useTableContext } from '@fluentui/react-table';
+import { useTableFeatures } from '@fluentui/react-table';
 import { useTableHeader_unstable } from '@fluentui/react-table';
 import { useTableHeaderCell_unstable } from '@fluentui/react-table';
 import { useTableHeaderCellStyles_unstable } from '@fluentui/react-table';
@@ -804,8 +804,6 @@ export { useSelectStyles_unstable }
 
 export { useSort }
 
-export { useTable }
-
 export { useTable_unstable }
 
 export { useTableBody_unstable }
@@ -826,6 +824,8 @@ export { useTableCellStyles_unstable }
 
 export { useTableContext }
 
+export { useTableFeatures }
+
 export { useTableHeader_unstable }
 
 export { useTableHeaderCell_unstable }

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

@@ -208,7 +208,7 @@ export {
   useTableCellLayoutStyles_unstable,
   renderTableCellLayout_unstable,
   tableCellLayoutClassNames,
-  useTable,
+  useTableFeatures,
   useSelection,
   useSort,
   createColumn,

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

@@ -539,9 +539,6 @@ export function useSelection<TItem>(options: UseSelectionOptions): (tableState:
 // @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;
 
@@ -572,6 +569,9 @@ export const useTableCellStyles_unstable: (state: TableCellState) => TableCellSt
 // @public (undocumented)
 export const useTableContext: () => TableContextValue;
 
+// @public (undocumented)
+export function useTableFeatures<TItem>(options: UseTableOptions<TItem>, plugins?: TableStatePlugin[]): HeadlessTableState<TItem>;
+
 // @public
 export const useTableHeader_unstable: (props: TableHeaderProps, ref: React_2.Ref<HTMLElement>) => TableHeaderState;
 

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

@@ -2,7 +2,7 @@ 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, useSort, useSelection } from '../../hooks';
+import { useTableFeatures, useSort, useSelection } from '../../hooks';
 
 /**
  * Create the state required to render DataGrid.
@@ -32,7 +32,7 @@ export const useDataGrid_unstable = (props: DataGridProps, ref: React.Ref<HTMLEl
   const navigable = focusMode !== 'none';
   const keyboardNavAttr = useArrowNavigationGroup({ axis: 'grid' });
 
-  const tableState = useTable({ items, columns }, [
+  const tableState = useTableFeatures({ items, columns }, [
     useSort({
       defaultSortState,
       sortState,

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

@@ -1,5 +1,5 @@
 export * from './types';
-export * from './useTable';
+export * from './useTableFeatures';
 export * from './useSort';
 export * from './useSelection';
 export * from './createColumn';

packages/react-components/react-table/src/hooks/useTable.test.ts → packages/react-components/react-table/src/hooks/useTableFeatures.test.ts

@@ -2,12 +2,12 @@ import { renderHook } from '@testing-library/react-hooks';
 import { createColumn } from './createColumn';
 import { defaultTableSelectionState, useSelection } from './useSelection';
 import { defaultTableSortState, useSort } from './useSort';
-import { useTable } from './useTable';
+import { useTableFeatures } from './useTableFeatures';
 
-describe('useTable', () => {
+describe('useTableFeatures', () => {
   it('should return sort state', () => {
     const { result } = renderHook(() =>
-      useTable(
+      useTableFeatures(
         {
           columns: [createColumn({ columnId: 1 })],
           items: [{}, {}, {}],
@@ -31,7 +31,7 @@ describe('useTable', () => {
 
   it('should return selection state', () => {
     const { result } = renderHook(() =>
-      useTable(
+      useTableFeatures(
         {
           columns: [createColumn({ columnId: 1 })],
           items: [{}, {}, {}],
@@ -56,7 +56,7 @@ describe('useTable', () => {
   describe('getRows', () => {
     it('should enahnce rows', () => {
       const { result } = renderHook(() =>
-        useTable({
+        useTableFeatures({
           columns: [createColumn({ columnId: 1 })],
           items: [{}, {}, {}],
         }),
@@ -90,7 +90,7 @@ describe('useTable', () => {
 
     it('should use custom rowId', () => {
       const { result } = renderHook(() =>
-        useTable({
+        useTableFeatures({
           columns: [createColumn({ columnId: 1 })],
           items: [{ value: 'a' }, { value: 'b' }, { value: 'c' }],
           getRowId: item => item.value,
@@ -103,7 +103,7 @@ describe('useTable', () => {
 
     it('should return original items', () => {
       const { result } = renderHook(() =>
-        useTable({
+        useTableFeatures({
           columns: [createColumn({ columnId: 1 })],
           items: [{ value: 1 }, { value: 2 }, { value: 3 }],
         }),

packages/react-components/react-table/src/hooks/useTable.ts → packages/react-components/react-table/src/hooks/useTableFeatures.ts

@@ -13,7 +13,10 @@ export const defaultTableState: TableState<unknown> = {
   columns: [],
 };
 
-export function useTable<TItem>(options: UseTableOptions<TItem>, plugins: TableStatePlugin[] = []): TableState<TItem> {
+export function useTableFeatures<TItem>(
+  options: UseTableOptions<TItem>,
+  plugins: TableStatePlugin[] = [],
+): TableState<TItem> {
   const { items, getRowId, columns } = options;
 
   const getRows = <TRowState extends RowState<TItem>>(

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

@@ -1,4 +1,4 @@
-export { useTable, useSelection, useSort, createColumn } from './hooks';
+export { useTableFeatures, useSelection, useSort, createColumn } from './hooks';
 export type {
   UseTableOptions,
   TableState as HeadlessTableState,

packages/react-components/react-table/stories/Table/DataGrid.stories.tsx

@@ -18,7 +18,7 @@ import {
   TableHeaderCell,
   TableSelectionCell,
   TableCellLayout,
-  useTable,
+  useTableFeatures,
   ColumnDefinition,
   useSelection,
   useSort,
@@ -127,7 +127,7 @@ export const DataGrid = () => {
     getRows,
     selection: { allRowsSelected, someRowsSelected, toggleAllRows, toggleRow, isRowSelected },
     sort: { getSortDirection, toggleColumnSort, sort },
-  } = useTable(
+  } = useTableFeatures(
     {
       columns,
       items,
@@ -217,7 +217,7 @@ DataGrid.parameters = {
   docs: {
     description: {
       story: [
-        'The `DataGrid` component is simply a composition of hook and primitive `Table` components',
+        'The `DataGrid` component is a composition of the `useTableFeatures` hook and primitive `Table` components',
         'along with some convenience features such as accessible markup and event handlers.',
         'Any feature of the `DataGrid` is achievable with the primitive components and hook',
       ].join('\n'),

packages/react-components/react-table/stories/Table/MultipleSelect.stories.tsx

@@ -18,7 +18,7 @@ import {
   TableHeaderCell,
   TableSelectionCell,
   TableCellLayout,
-  useTable,
+  useTableFeatures,
   ColumnDefinition,
   useSelection,
   createColumn,
@@ -112,7 +112,7 @@ export const MultipleSelect = () => {
   const {
     getRows,
     selection: { allRowsSelected, someRowsSelected, toggleAllRows, toggleRow, isRowSelected },
-  } = useTable(
+  } = useTableFeatures(
     {
       columns,
       items,
@@ -193,7 +193,8 @@ MultipleSelect.parameters = {
     description: {
       story: [
         'Selection can be achieved easily by combining the `TableSelectionCell` component along with',
-        'other primitive components. The hook can handle state management for selection, although its use is not',
+        'other primitive components. `useTableFeatures` can handle state management for selection,',
+        'although its use is not',
         'necessary if users already have their own state management.',
       ].join('\n'),
     },

packages/react-components/react-table/stories/Table/MultipleSelectControlled.stories.tsx

@@ -18,7 +18,7 @@ import {
   TableHeaderCell,
   TableSelectionCell,
   TableCellLayout,
-  useTable,
+  useTableFeatures,
   ColumnDefinition,
   RowId,
   useSelection,
@@ -117,7 +117,7 @@ export const MultipleSelectControlled = () => {
   const {
     getRows,
     selection: { allRowsSelected, someRowsSelected, toggleAllRows, toggleRow, isRowSelected },
-  } = useTable(
+  } = useTableFeatures(
     {
       columns,
       items,

packages/react-components/react-table/stories/Table/SingleSelect.stories.tsx

@@ -17,7 +17,7 @@ import {
   TableHeader,
   TableHeaderCell,
   TableSelectionCell,
-  useTable,
+  useTableFeatures,
   ColumnDefinition,
   useSelection,
   TableCellLayout,
@@ -112,7 +112,7 @@ export const SingleSelect = () => {
   const {
     getRows,
     selection: { toggleRow, isRowSelected },
-  } = useTable(
+  } = useTableFeatures(
     {
       columns,
       items,

packages/react-components/react-table/stories/Table/SingleSelectControlled.stories.tsx

@@ -17,7 +17,7 @@ import {
   TableHeader,
   TableHeaderCell,
   TableSelectionCell,
-  useTable,
+  useTableFeatures,
   ColumnDefinition,
   RowId,
   useSelection,
@@ -116,7 +116,7 @@ export const SingleSelectControlled = () => {
   const {
     getRows,
     selection: { toggleRow, isRowSelected },
-  } = useTable(
+  } = useTableFeatures(
     {
       columns,
       items,
@@ -192,7 +192,8 @@ SingleSelectControlled.parameters = {
   docs: {
     description: {
       story: [
-        'By default our hook is uncontrolled. However, it is possible to control selection features with external',
+        'By default the `useTableFeatures` hook is uncontrolled. ',
+        'However, it is possible to control selection features with external',
         'user state.',
       ].join('\n'),
     },

packages/react-components/react-table/stories/Table/Sort.stories.tsx

@@ -16,7 +16,7 @@ import {
   Table,
   TableHeader,
   TableHeaderCell,
-  useTable,
+  useTableFeatures,
   ColumnDefinition,
   ColumnId,
   useSort,
@@ -124,7 +124,7 @@ export const Sort = () => {
   const {
     getRows,
     sort: { getSortDirection, toggleColumnSort, sort },
-  } = useTable(
+  } = useTableFeatures(
     {
       columns,
       items,
@@ -185,7 +185,7 @@ Sort.parameters = {
       story: [
         'Using the `sortable` prop will configure all header cells to be buttons and add extra styles.',
         'The `TableHeaderCell` component accepts a `sortDirection` prop that will indicate whether the',
-        'header is sorted. Handling the sort of data and column state is handled by our hook.',
+        'header is sorted. Handling the sort of data and column state is handled by `useTableFeatures`.',
       ].join('\n'),
     },
   },

packages/react-components/react-table/stories/Table/SortControlled.stories.tsx

@@ -16,7 +16,7 @@ import {
   Table,
   TableHeader,
   TableHeaderCell,
-  useTable,
+  useTableFeatures,
   ColumnDefinition,
   ColumnId,
   useSort,
@@ -132,7 +132,7 @@ export const SortControlled = () => {
   const {
     getRows,
     sort: { getSortDirection, toggleColumnSort, sort },
-  } = useTable(
+  } = useTableFeatures(
     {
       columns,
       items,

packages/react-components/react-table/stories/Table/SubtleSelection.stories.tsx

@@ -18,7 +18,7 @@ import {
   TableHeaderCell,
   TableSelectionCell,
   TableCellLayout,
-  useTable,
+  useTableFeatures,
   ColumnDefinition,
   useSelection,
   createColumn,
@@ -112,7 +112,7 @@ export const SubtleSelection = () => {
   const {
     getRows,
     selection: { allRowsSelected, someRowsSelected, toggleAllRows, toggleRow, isRowSelected },
-  } = useTable(
+  } = useTableFeatures(
     {
       columns,
       items,

packages/react-components/react-table/stories/Table/TableDescription.md

@@ -17,5 +17,10 @@
 > from first class Microsoft design and accessibility support.
 
 A Table displays sets of two-dimensional data. The primitive components can be fully customized to support different
-feature sets. The library provides a default hook that handles the business logic and state management of common
+feature sets. The library provides a default `useTableFeatures` hook that handles the business logic and state management of common
 features. There is no obligation to use our hook with these components, we've created it for convenience.
+
+The `useTableFeatures` hook was designed with feature composition in mind. This means that are composed using
+plugins hooks such as `useSort` and `useSelection` as a part of `useTableFeatures`. This means
+that as the feature set expands, users will not need to pay the bundle size price for features that they do not intend
+to use. Please consult the usage examples below for more details.