feat: Adds support for table data grouping (2nd attempt, see: #126)

This reverts commit 86ce17a.

Author: pan-kot

package-lock.json

@@ -42,10 +42,14 @@
     "LICENSE",
     "NOTICE"
   ],
+  "dependencies": {
+    "@cloudscape-design/component-toolkit": "^1.0.0-beta"
+  },
   "peerDependencies": {
     "react": ">=16.8.0"
   },
   "devDependencies": {
+    "@cloudscape-design/build-tools": "github:cloudscape-design/build-tools#main",
     "@testing-library/react": "^11.2.7",
     "@types/react": "^16.14.21",
     "@types/react-dom": "^16.9.14",
@@ -73,6 +77,9 @@
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": [
       "eslint --fix"
+    ],
+    "package-lock.json": [
+      "prepare-package-lock"
     ]
   },
   "overrides": {

package.json

@@ -3,7 +3,7 @@
 import * as React from 'react';
 import { render as testRender } from '@testing-library/react';
 import { UseCollectionResult, CollectionRef } from '../index.js';
-import { getTrackableValue } from '../operations/trackby-utils.js';
+import { getTrackableValue } from '@cloudscape-design/component-toolkit/internal';
 
 export type Item = { id: string; date?: Date };
 

src/__tests__/stubs.tsx

@@ -4,28 +4,45 @@
 import React from 'react';
 import { useCollection, UseCollectionOptions, UseCollectionResult } from '..';
 import { render } from '@testing-library/react';
-import { getTrackableValue } from '../operations/trackby-utils.js';
+import { getTrackableValue } from '@cloudscape-design/component-toolkit/internal';
+import { Item } from './stubs';
 
 export function renderUseCollection<T>(allItems: readonly T[], options: UseCollectionOptions<T>) {
-  const result: {
-    collection: UseCollectionResult<T>;
+  const current: {
+    result: UseCollectionResult<T>;
     rerender: (allItems: readonly T[], options: UseCollectionOptions<T>) => void;
     // Derived props for simpler assertions
     visibleItems: T[];
   } = {} as any;
 
   const onResult = (collection: UseCollectionResult<T>) => {
-    result.collection = collection;
-    result.visibleItems = getVisibleItems(collection);
+    current.result = collection;
+    current.visibleItems = getVisibleItems(collection);
   };
   const { rerender } = render(<App allItems={allItems} options={options} onResult={onResult} />);
 
-  result.rerender = (allItems: readonly T[], options: UseCollectionOptions<T>) =>
+  current.rerender = (allItems: readonly T[], options: UseCollectionOptions<T>) =>
     rerender(<App allItems={allItems} options={options} onResult={onResult} />);
 
-  return result;
+  return current;
 }
 
+// Generates random items tree to be used for property-based tests.
+export const generateRandomNestedItems = ({ totalItems }: { totalItems: number }) => {
+  const items: Item[] = [];
+  let nextIndex = 0;
+  let level = 1;
+  while (nextIndex < totalItems - 1) {
+    for (; nextIndex < totalItems && nextIndex < nextIndex + Math.floor(Math.random() * 5); nextIndex++) {
+      const levelParents = items.filter(i => i.id.split('.').length === level - 1);
+      const parent = levelParents[Math.floor(Math.random() * levelParents.length)];
+      items.push({ id: !parent ? `${nextIndex}` : `${parent.id}.${nextIndex}` });
+    }
+    level = Math.random() > 0.5 ? level + 1 : level;
+  }
+  return items;
+};
+
 function App<T>({
   allItems,
   options,

src/__tests__/use-collection-expadable-rows.test.tsx

@@ -26,6 +26,15 @@ export interface SelectionChangeDetail<T> {
   selectedItems: ReadonlyArray<T>;
 }
 
+export interface GroupSelectionState<T> {
+  inverted: boolean;
+  toggledItems: readonly T[];
+}
+
+export interface GroupSelectionChangeDetail<T> {
+  groupSelection: GroupSelectionState<T>;
+}
+
 export type TrackBy<T> = string | ((item: T) => string);
 
 export interface UseCollectionOptions<T> {
@@ -57,15 +66,23 @@ export interface ExpandableRowsProps<ItemType> {
   getId(item: ItemType): string;
   getParentId(item: ItemType): null | string;
   defaultExpandedItems?: ReadonlyArray<ItemType>;
+  // When set, only leaf nodes (those with no children) are reflected in the counters,
+  // and selection is replaced by group selection.
+  dataGrouping?: DataGroupingProps;
 }
 
+// There is no configuration for data grouping yet, but it might come in future releases.
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface DataGroupingProps {}
+
 export interface CollectionState<T> {
   filteringText: string;
   propertyFilteringQuery: PropertyFilterQuery;
   currentPageIndex: number;
   sortingState?: SortingState<T>;
   selectedItems: ReadonlyArray<T>;
   expandedItems: ReadonlyArray<T>;
+  groupSelection: GroupSelectionState<T>;
 }
 
 export interface CollectionActions<T> {
@@ -75,6 +92,7 @@ export interface CollectionActions<T> {
   setSelectedItems(selectedItems: ReadonlyArray<T>): void;
   setPropertyFiltering(query: PropertyFilterQuery): void;
   setExpandedItems(items: ReadonlyArray<T>): void;
+  setGroupSelection(state: GroupSelectionState<T>): void;
 }
 
 interface UseCollectionResultBase<T> {
@@ -86,17 +104,29 @@ interface UseCollectionResultBase<T> {
     onSortingChange?(event: CustomEventLike<SortingState<T>>): void;
     sortingColumn?: SortingColumn<T>;
     sortingDescending?: boolean;
+    // When expandableRows.dataGrouping={}, the selected items are derived from the expandableRows.groupSelection,
+    // and include all effectively selected leaf nodes.
     selectedItems?: ReadonlyArray<T>;
     onSelectionChange?(event: CustomEventLike<SelectionChangeDetail<T>>): void;
     expandableRows?: {
       getItemChildren: (item: T) => T[];
       isItemExpandable: (item: T) => boolean;
       expandedItems: ReadonlyArray<T>;
       onExpandableItemToggle(event: CustomEventLike<{ item: T; expanded: boolean }>): void;
+      // The groupSelection property is only added in case selection is configured, and expandableRows.dataGrouping={}.
+      groupSelection?: GroupSelectionState<T>;
+      onGroupSelectionChange(event: CustomEventLike<GroupSelectionChangeDetail<T>>): void;
+      // The counts reflect the number of nested selectable/selected nodes (deeply), including the given one.
+      // When expandableRows.dataGrouping={}, only leaf nodes are considered. They return 1 when called on leaf nodes.
+      getItemsCount?: (item: T) => number;
+      getSelectedItemsCount?: (item: T) => number;
     };
     trackBy?: string | ((item: T) => string);
     ref: React.RefObject<CollectionRef>;
+    // The counts reflect the number of selectable/selected nodes (deeply).
+    // When expandableRows.dataGrouping={}, only leaf nodes are considered.
     totalItemsCount: number;
+    totalSelectedItemsCount: number;
     firstIndex: number;
   };
   filterProps: {

src/__tests__/utils.tsx

@@ -6,50 +6,71 @@ import { createPropertyFilterPredicate } from './property-filter.js';
 import { createComparator } from './sort.js';
 import { createPageProps } from './pagination.js';
 import { composeFilters } from './compose-filters.js';
-import { getTrackableValue } from './trackby-utils.js';
+import { getTrackableValue, SelectionTree } from '@cloudscape-design/component-toolkit/internal';
 import { computeFlatItems, computeTreeItems } from './items-tree.js';
 
 export function processItems<T>(
   allItems: ReadonlyArray<T>,
-  { filteringText, sortingState, currentPageIndex, propertyFilteringQuery }: Partial<CollectionState<T>>,
-  { filtering, sorting, pagination, propertyFiltering, expandableRows }: UseCollectionOptions<T>
+  state: Partial<CollectionState<T>>,
+  { filtering, sorting, pagination, propertyFiltering, expandableRows, selection }: UseCollectionOptions<T>
 ): {
   items: readonly T[];
   allPageItems: readonly T[];
   pagesCount: number | undefined;
   actualPageIndex: number | undefined;
+  totalItemsCount: number;
   filteredItemsCount: number | undefined;
+  selectedItems: undefined | T[];
+  getItemsCount?: (item: T) => number;
+  getSelectedItemsCount?: (item: T) => number;
   getChildren: (item: T) => T[];
 } {
   const filterPredicate = composeFilters(
-    createPropertyFilterPredicate(propertyFiltering, propertyFilteringQuery),
-    createFilterPredicate(filtering, filteringText)
+    createPropertyFilterPredicate(propertyFiltering, state.propertyFilteringQuery),
+    createFilterPredicate(filtering, state.filteringText)
   );
-  const sortingComparator = createComparator(sorting, sortingState);
-  const { items, size, getChildren } = expandableRows
+  const sortingComparator = createComparator(sorting, state.sortingState);
+  const { items, totalItemsCount, getChildren, getItemsCount } = expandableRows
     ? computeTreeItems(allItems, expandableRows, filterPredicate, sortingComparator)
     : computeFlatItems(allItems, filterPredicate, sortingComparator);
+  const filteredItemsCount = filterPredicate ? totalItemsCount : undefined;
 
-  const filteredItemsCount = filterPredicate ? size : undefined;
+  let getSelectedItemsCount: undefined | ((item: T) => number) = undefined;
+  let selectedItems: undefined | T[] = undefined;
+  if (selection && expandableRows?.dataGrouping && state.groupSelection) {
+    const trackBy = selection?.trackBy ?? expandableRows?.getId;
+    const selectionTreeProps = { getChildren: getChildren, trackBy };
+    const selectionTree = new SelectionTree(items, selectionTreeProps, state.groupSelection);
+    getSelectedItemsCount = selectionTree.getSelectedItemsCount;
+    selectedItems = selectionTree.getSelectedItems();
+  }
 
-  const pageProps = createPageProps(pagination, currentPageIndex, items);
+  const pageProps = createPageProps(pagination, state.currentPageIndex, items);
   if (pageProps) {
     return {
       items: items.slice((pageProps.pageIndex - 1) * pageProps.pageSize, pageProps.pageIndex * pageProps.pageSize),
       allPageItems: items,
+      totalItemsCount,
       filteredItemsCount,
       pagesCount: pageProps?.pagesCount,
       actualPageIndex: pageProps?.pageIndex,
+      selectedItems,
+      getItemsCount,
+      getSelectedItemsCount,
       getChildren,
     };
   }
 
   return {
     items: items,
     allPageItems: items,
+    totalItemsCount,
     filteredItemsCount,
     pagesCount: undefined,
     actualPageIndex: undefined,
+    selectedItems,
+    getItemsCount,
+    getSelectedItemsCount,
     getChildren,
   };
 }

src/interfaces.ts

@@ -1,9 +1,12 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import { DataGroupingProps } from '../interfaces';
+
 interface TreeProps<T> {
   getId(item: T): string;
   getParentId(item: T): null | string;
+  dataGrouping?: DataGroupingProps;
 }
 
 export function computeFlatItems<T>(
@@ -17,7 +20,7 @@ export function computeFlatItems<T>(
   if (sortingComparator) {
     items = items.slice().sort(sortingComparator);
   }
-  return { items, size: items.length, getChildren: () => [] };
+  return { items, totalItemsCount: items.length, getChildren: () => [], getItemsCount: undefined };
 }
 
 export function computeTreeItems<T>(
@@ -27,8 +30,9 @@ export function computeTreeItems<T>(
   sortingComparator: null | ((a: T, b: T) => number)
 ) {
   const idToChildren = new Map<string, T[]>();
+  const idToCount = new Map<string, number>();
   let items: T[] = [];
-  let size = allItems.length;
+  let totalItemsCount = 0;
 
   for (const item of allItems) {
     const parentId = treeProps.getParentId(item);
@@ -47,13 +51,10 @@ export function computeTreeItems<T>(
     const filterNode = (item: T): boolean => {
       const children = getChildren(item);
       const filteredChildren = children.filter(filterNode);
-      size -= children.length - filteredChildren.length;
       setChildren(item, filteredChildren);
       return filterPredicate(item) || filteredChildren.length > 0;
     };
-    const prevLength = items.length;
     items = items.filter(filterNode);
-    size -= prevLength - items.length;
   }
 
   if (sortingComparator) {
@@ -66,5 +67,19 @@ export function computeTreeItems<T>(
     sortLevel(items);
   }
 
-  return { items, size, getChildren };
+  function computeGroupCounts(item: T) {
+    const children = getChildren(item);
+    let itemCount = children.length === 0 ? 1 : 0;
+    for (const child of children) {
+      itemCount += computeGroupCounts(child);
+    }
+    idToCount.set(treeProps.getId(item), itemCount);
+    return itemCount;
+  }
+  for (const item of items) {
+    totalItemsCount += treeProps.dataGrouping ? computeGroupCounts(item) : 1;
+  }
+  const getItemsCount = treeProps.dataGrouping ? (item: T) => idToCount.get(treeProps.getId(item)) ?? 0 : undefined;
+
+  return { items, totalItemsCount, getChildren, getItemsCount };
 }

src/operations/index.ts

@@ -8,6 +8,7 @@
 declare global {
   const process: { env: { NODE_ENV?: string } };
   const console: { warn: (...args: Array<any>) => void };
+  type AbortSignal = any; // Used in the component-toolkit dependency
 }
 
 // dummy export to make typescript treat this file as ES module