feat(react-table): Add toggleSomeRows selection state

change/@fluentui-react-table-6b2871b9-31bb-401e-b4f6-f3b674177622.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add toggleSomeRows selection state to enable partial row selection",
+  "packageName": "@fluentui/react-table",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@fluentui-react-utilities-116979d5-e6dc-45ef-a1e4-85977256df11.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add toggleSomeItems utility",
+  "packageName": "@fluentui/react-utilities",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

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

@@ -550,6 +550,7 @@ export interface TableSelectionState {
     someRowsSelected: boolean;
     toggleAllRows: (e: React_2.SyntheticEvent) => void;
     toggleRow: (e: React_2.SyntheticEvent, rowId: TableRowId) => void;
+    toggleSomeRows: (e: React_2.SyntheticEvent, rowIds: Set<TableRowId>) => void;
 }
 
 // @public (undocumented)

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

@@ -76,6 +76,10 @@ export interface TableSelectionState {
    * Toggle selection of all rows
    */
   toggleAllRows: (e: React.SyntheticEvent) => void;
+  /**
+   * Toggle selection of some rows
+   */
+  toggleSomeRows: (e: React.SyntheticEvent, rowIds: Set<TableRowId>) => void;
   /**
    * Toggle selection of single row
    */

packages/react-components/react-table/library/src/hooks/useTableSelection.test.ts

@@ -80,6 +80,45 @@ describe('useTableSelectionState', () => {
         expect(onSelectionChange).toHaveBeenNthCalledWith(2, mockSyntheticEvent(), { selectedItems: new Set() });
       });
     });
+
+    describe('toggleSomeRows', () => {
+      const someRows = new Set([0, 2, 4]);
+
+      it('should select some rows', () => {
+        const onSelectionChange = jest.fn();
+        const { result } = renderHook(() =>
+            useTableSelectionState(mockTableState({ items }), { selectionMode: 'multiselect', onSelectionChange }),
+        );
+
+        act(() => {
+          result.current.selection.toggleSomeRows(mockSyntheticEvent(), someRows);
+        });
+        expect(result.current.selection.selectedRows.size).toBe(Array.from(someRows).length);
+        expect(Array.from(result.current.selection.selectedRows)).toEqual(Array.from(someRows));
+        expect(onSelectionChange).toHaveBeenCalledTimes(1);
+        expect(onSelectionChange).toHaveBeenCalledWith(mockSyntheticEvent(), { selectedItems: someRows });
+      });
+
+      it('should deselect some rows', () => {
+        const onSelectionChange = jest.fn();
+        const { result } = renderHook(() =>
+            useTableSelectionState(mockTableState({ items }), { selectionMode: 'multiselect', onSelectionChange }),
+        );
+
+        act(() => {
+          result.current.selection.toggleSomeRows(mockSyntheticEvent(), someRows);
+        });
+
+        act(() => {
+          result.current.selection.toggleSomeRows(mockSyntheticEvent(), someRows);
+        });
+
+        expect(result.current.selection.selectedRows.size).toBe(0);
+        expect(onSelectionChange).toHaveBeenCalledTimes(2);
+        expect(onSelectionChange).toHaveBeenNthCalledWith(2, mockSyntheticEvent(), { selectedItems: new Set() });
+      });
+    });
+
     describe('clearRows', () => {
       it('should clear selection', () => {
         const onSelectionChange = jest.fn();

packages/react-components/react-table/library/src/hooks/useTableSelection.ts

@@ -15,6 +15,7 @@ export const defaultTableSelectionState: TableSelectionState = {
   selectedRows: new Set(),
   someRowsSelected: false,
   toggleAllRows: noop,
+  toggleSomeRows: noop,
   toggleRow: noop,
   selectionMode: 'multiselect',
 };
@@ -100,6 +101,13 @@ export function useTableSelectionState<TItem>(
     );
   });
 
+  const toggleSomeRows: TableSelectionState['toggleSomeRows'] = useEventCallback((e, rowIds: Set<TableRowId>) => {
+    selectionMethods.toggleSomeItems(
+      e,
+      Array.from(rowIds).map((rowId, i) => Number(rowId) ?? i),
+    );
+  });
+
   const toggleRow: TableSelectionState['toggleRow'] = useEventCallback((e, rowId: TableRowId) =>
     selectionMethods.toggleItem(e, rowId),
   );
@@ -125,6 +133,7 @@ export function useTableSelectionState<TItem>(
       selectedRows: selected,
       toggleRow,
       toggleAllRows,
+      toggleSomeRows,
       clearRows,
       deselectRow,
       selectRow,

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

@@ -260,6 +260,8 @@ export interface SelectionMethods {
     toggleAllItems(event: React_2.SyntheticEvent, itemIds: SelectionItemId[]): void;
     // (undocumented)
     toggleItem(event: React_2.SyntheticEvent, id: SelectionItemId): void;
+    // (undocumented)
+    toggleSomeItems(event: React_2.SyntheticEvent, itemIds: SelectionItemId[]): void;
 }
 
 // @public (undocumented)

packages/react-components/react-utilities/src/selection/types.ts

@@ -9,6 +9,7 @@ export interface SelectionMethods {
   clearItems(event: React.SyntheticEvent): void;
   isSelected(id: SelectionItemId): boolean;
   toggleAllItems(event: React.SyntheticEvent, itemIds: SelectionItemId[]): void;
+  toggleSomeItems(event: React.SyntheticEvent, itemIds: SelectionItemId[]): void;
 }
 
 export type SelectionItemId = string | number;

packages/react-components/react-utilities/src/selection/useSelection.ts

@@ -34,6 +34,11 @@ function useSingleSelection(params: Omit<SelectionHookParams, 'selectionMode'>)
         throw new Error('[react-utilities]: `toggleAllItems` should not be used in single selection mode');
       }
     },
+    toggleSomeItems: () => {
+      if (process.env.NODE_ENV !== 'production') {
+        throw new Error('[react-utilities]: `toggleSomeItems` should not be used in single selection mode');
+      }
+    },
     toggleItem: (event, itemId) => changeSelection(event, new Set([itemId])),
     clearItems: event => changeSelection(event, new Set()),
     isSelected: itemId => selected.has(itemId) ?? false,
@@ -77,6 +82,16 @@ function useMultipleSelection(params: Omit<SelectionHookParams, 'selectionMode'>
       }
       changeSelection(event, nextSelectedItems);
     },
+    toggleSomeItems: (event, itemIds) => {
+      const allItemsSelected = itemIds.every(itemId => selected.has(itemId));
+      const nextSelectedItems = new Set(selected);
+      if (allItemsSelected) {
+        itemIds.forEach(itemId => nextSelectedItems.delete(itemId));
+      } else {
+        itemIds.forEach(itemId => nextSelectedItems.add(itemId));
+      }
+      changeSelection(event, nextSelectedItems);
+    }
   };
   return [selected, methods] as const;
 }