@databiosphere/findable-ui 18.0.0 → 20.0.0

package/src/components/Table/common/utils.ts

@@ -1,16 +1,12 @@
-import SouthRoundedIcon from "@mui/icons-material/SouthRounded";
-import { TableSortLabelProps } from "@mui/material";
 import {
   Cell,
   Column,
   ColumnFiltersState,
-  ColumnSort,
   InitialTableState,
   memo,
   PaginationState,
   Row,
   RowData,
-  SortDirection,
   sortingFns,
   Table,
   VisibilityState,
@@ -24,6 +20,7 @@ import {
 import { EXPLORE_MODE, ExploreMode } from "../../../hooks/useExploreMode";
 import { ACCESSOR_KEYS } from "../../TableCreator/common/constants";
 import { CheckboxMenuListItem } from "../components/CheckboxMenu/checkboxMenu";
+import { handleToggleVisibility } from "../components/TableFeatures/ColumnVisibility/utils";
 
 /**
  * Internal model of a category term count keyed by category term.
@@ -122,20 +119,6 @@ function formatDataToTSV(data: TableData[][]): string {
     .join("\n");
 }
 
-/**
- * Returns the column sort direction.
- * @param sortDirection - Column sort direction.
- * @returns the coumn sort direction.
- */
-export function getColumnSortDirection(
-  sortDirection: false | SortDirection
-): SortDirection | undefined {
-  if (!sortDirection) {
-    return;
-  }
-  return sortDirection;
-}
-
 /**
  * Returns filtered entity results as a blob.
  * @param rows - Table rows.
@@ -164,31 +147,27 @@ export function getEditColumnOptions<T extends RowData>(
   const { getAllColumns, initialState } = table;
   const { columnVisibility: initialVisibilityState } = initialState;
   const allColumns = getAllColumns();
-  return allColumns.reduce(
-    (
-      acc,
-      {
-        columnDef: { header },
-        getCanHide,
-        getIsVisible,
-        getToggleVisibilityHandler,
-        id,
-      }
-    ) => {
-      if (getCanHide()) {
-        const option: CheckboxMenuListItem = {
-          checked: getIsVisible(),
-          disabled: initialVisibilityState[id],
-          label: header as string, // TODO revisit type assertion here
-          onChange: getToggleVisibilityHandler(),
-          value: id,
-        };
-        acc.push(option);
-      }
-      return acc;
-    },
-    [] as CheckboxMenuListItem[]
-  );
+  return allColumns.reduce((acc, column) => {
+    const {
+      columnDef: { header },
+      getCanHide,
+      getIsVisible,
+      id,
+    } = column;
+    if (getCanHide()) {
+      const option: CheckboxMenuListItem = {
+        checked: getIsVisible(),
+        disabled: initialVisibilityState[id], // TODO(cc) column visibility toggle should be disabled when table enableGrouping is false, and column is grouped.
+        label: header as string, // TODO revisit type assertion here
+        onChange: () => {
+          handleToggleVisibility(table, column);
+        },
+        value: id,
+      };
+      acc.push(option);
+    }
+    return acc;
+  }, [] as CheckboxMenuListItem[]);
 }
 
 /**
@@ -243,6 +222,7 @@ export function getGridTemplateColumns<T extends RowData>(
   columns: Column<T>[]
 ): string {
   return columns
+    .filter(filterGroupedColumn)
     .map(({ columnDef: { meta } }) => {
       const width = meta?.width;
       if (isGridTrackMinMax(width)) {
@@ -256,35 +236,17 @@ export function getGridTemplateColumns<T extends RowData>(
 /**
  * Returns initial table state.
  * @param columns - Column configuration.
- * @param defaultSort - Column sort configuration.
  * @returns initial table state.
  */
-export function getInitialState(
-  columns: ColumnConfig[],
-  defaultSort: ColumnSort | undefined
+export function getInitialState<T extends RowData>(
+  columns: ColumnConfig<T>[]
 ): InitialTableState {
   const columnVisibility = getInitialTableColumnVisibility(columns);
-  const sorting = getInitialTableStateSorting(defaultSort);
   return {
     columnVisibility,
-    sorting,
   };
 }
 
-/**
- * Returns the initial table sorting state for the specified column sort configuration.
- * @param defaultSort - Column sort configuration.
- * @returns initial table sorting state.
- */
-export function getInitialTableStateSorting(
-  defaultSort: ColumnSort | undefined
-): ColumnSort[] {
-  if (!defaultSort) {
-    return [];
-  }
-  return [defaultSort];
-}
-
 /**
  * Returns the pinned cell and its index tuple.
  * @param row - Row.
@@ -296,7 +258,12 @@ export function getPinnedCellIndex<T extends RowData>(
   const visibleCells = row.getVisibleCells();
   let pinnedIndex = 0;
   for (let i = 0; i < visibleCells.length; i++) {
-    if (visibleCells[i].column.columnDef.meta?.columnPinned) {
+    const cell = visibleCells[i];
+    if (cell.getIsGrouped()) {
+      pinnedIndex = i;
+      break;
+    }
+    if (cell.column.columnDef.meta?.columnPinned) {
       pinnedIndex = i;
       break;
     }
@@ -304,24 +271,6 @@ export function getPinnedCellIndex<T extends RowData>(
   return [visibleCells[pinnedIndex], pinnedIndex];
 }
 
-/**
- * Returns table sort label props.
- * @param column - Table column.
- * @returns table sort label props.
- */
-export function getTableSortLabelProps<T extends RowData>(
-  column: Column<T>
-): TableSortLabelProps {
-  const { getCanSort, getIsSorted, getToggleSortingHandler } = column;
-  return {
-    IconComponent: SouthRoundedIcon,
-    active: isColumnSortActive(getIsSorted()),
-    direction: getColumnSortDirection(getIsSorted()),
-    disabled: !getCanSort(),
-    onClick: getToggleSortingHandler(),
-  };
-}
-
 /**
  * Returns table state pagination.
  * @param pageIndex - Explore state page index.
@@ -364,21 +313,23 @@ function getRowsTableData<T extends RowData>(rows: Row<T>[]): TableData[][] {
   );
 }
 
+/**
+ * Returns true if the column is not grouped (filters out grouped columns).
+ * @param column - Table column.
+ * @returns true if the column is not grouped.
+ */
+function filterGroupedColumn<T extends RowData>(column: Column<T>): boolean {
+  return !column.getIsGrouped();
+}
+
 /**
  * Returns true if any or all table rows are selected.
  * @param table - Table.
  * @returns true if a row is selected.
  */
 export function isAnyRowSelected<T extends RowData>(table: Table<T>): boolean {
-  const {
-    getIsAllPageRowsSelected,
-    getIsSomePageRowsSelected,
-    options: { enableRowSelection },
-  } = table;
-  return Boolean(
-    enableRowSelection &&
-      (getIsSomePageRowsSelected() || getIsAllPageRowsSelected())
-  );
+  const { getIsAllPageRowsSelected, getIsSomePageRowsSelected } = table;
+  return getIsSomePageRowsSelected() || getIsAllPageRowsSelected();
 }
 
 /**
@@ -404,20 +355,6 @@ export function isCollapsableRowDisabled<T extends RowData>(
   return tableInstance.getVisibleLeafColumns().length === 1;
 }
 
-/**
- * Returns true if column has a sort direction.
- * @param sortDirection - Column sort direction.
- * @returns true when column has a sort direction.
- */
-export function isColumnSortActive(
-  sortDirection: false | SortDirection
-): boolean {
-  if (!sortDirection) {
-    return sortDirection;
-  }
-  return true;
-}
-
 /**
  * Returns sort return value from the compare function. The compare function is dependent on the row value type:
  * - row values of type "array" use a compare function based off React Table "basic" compare function,
@@ -465,8 +402,8 @@ function basicSort<TValue>(val0: TValue, val1: TValue): number {
  * @param columns - Column configuration.
  * @returns initial table visibility state.
  */
-export function getInitialTableColumnVisibility(
-  columns: ColumnConfig[]
+export function getInitialTableColumnVisibility<T extends RowData>(
+  columns: ColumnConfig<T>[]
 ): VisibilityState {
   return columns.reduce((acc, { columnVisible = true, id }) => {
     Object.assign(acc, { [id]: columnVisible });

package/src/components/Table/components/TableBody/hooks/virtualizer/constants.ts

@@ -0,0 +1,3 @@
+export const VIRTUALIZER_OPTIONS = {
+  overscan: 20,
+};

package/src/components/Table/components/TableBody/hooks/virtualizer/hook.ts

@@ -0,0 +1,23 @@
+import { Row, RowData } from "@tanstack/react-table";
+import { useWindowVirtualizer } from "@tanstack/react-virtual";
+import { useCallback } from "react";
+import { VIRTUALIZER_OPTIONS } from "./constants";
+import { UseVirtualizer } from "./types";
+
+/**
+ * A hook to create and manage TanStack window virtualizer for table rows.
+ * @param rows - Rows.
+ * @returns An object containing the virtualizer instance, which manages the visible rows.
+ */
+export function useVirtualizer<T extends RowData>(
+  rows: Row<T>[]
+): UseVirtualizer {
+  const estimateSize = useCallback(() => 100, []);
+  const count = rows.length;
+  const virtualizer = useWindowVirtualizer({
+    ...VIRTUALIZER_OPTIONS,
+    count,
+    estimateSize,
+  });
+  return { virtualizer };
+}

package/src/components/Table/components/TableBody/hooks/virtualizer/types.ts

@@ -0,0 +1,5 @@
+import { Virtualizer } from "@tanstack/react-virtual";
+
+export interface UseVirtualizer {
+  virtualizer: Virtualizer<Window, Element>;
+}

package/src/components/Table/components/TableBody/tableBody.tsx

@@ -1,40 +1,38 @@
 import { TableBody as MTableBody } from "@mui/material";
-import { RowData, Table } from "@tanstack/react-table";
-import { useWindowVirtualizer } from "@tanstack/react-virtual";
-import React, { useCallback } from "react";
+import { Row, RowData, Table } from "@tanstack/react-table";
+import React from "react";
 import { ROW_DIRECTION } from "../../common/entities";
 import { CollapsableRows } from "../TableRows/components/CollapsableRows/collapsableRows";
 import { VirtualizedRow } from "../TableRows/components/VirtualizedRow/virtualizedRow";
 import { TableRows } from "../TableRows/tableRows";
-
-const OVERSCAN = 20;
+import { useVirtualizer } from "./hooks/virtualizer/hook";
+import { getAllVirtualizedRows } from "./utils";
 
 export interface TableBodyProps<T extends RowData> {
   rowDirection: ROW_DIRECTION;
+  rows: Row<T>[];
   tableInstance: Table<T>;
 }
 
 export const TableBody = <T extends RowData>({
   rowDirection,
+  rows,
   tableInstance,
 }: TableBodyProps<T>): JSX.Element => {
-  const { getRowModel } = tableInstance;
-  const { rows } = getRowModel();
-  const estimateSize = useCallback(() => 100, []);
-  const count = rows.length;
-  const virtualizer = useWindowVirtualizer({
-    count,
-    estimateSize,
-    measureElement,
-    overscan: OVERSCAN,
-  });
+  const virtualizedRows = getAllVirtualizedRows(
+    tableInstance,
+    rows,
+    rowDirection
+  );
+  const { virtualizer } = useVirtualizer(virtualizedRows);
   return (
     <MTableBody>
       <VirtualizedRow isUpperRow={true} virtualizer={virtualizer} />
       {rowDirection === ROW_DIRECTION.DEFAULT ? (
-        <TableRows tableInstance={tableInstance} virtualizer={virtualizer} />
+        <TableRows rows={virtualizedRows} virtualizer={virtualizer} />
       ) : (
         <CollapsableRows
+          rows={virtualizedRows}
           tableInstance={tableInstance}
           virtualizer={virtualizer}
         />
@@ -43,17 +41,3 @@ export const TableBody = <T extends RowData>({
     </MTableBody>
   );
 };
-
-/**
- * Measures the height of the element.
- * @param element - Element to measure.
- * @returns height of the element.
- */
-function measureElement(element: Element): number {
-  // We select the first child element because the row is not a box element due to the "display: contents" style attribute.
-  const box = element.children[0];
-  if (!box) {
-    return 0;
-  }
-  return box.getBoundingClientRect().height;
-}

package/src/components/Table/components/TableBody/utils.ts

@@ -0,0 +1,21 @@
+import { Row, RowData, Table } from "@tanstack/react-table";
+import { ROW_DIRECTION } from "../../common/entities";
+
+/**
+ * Filters and returns the appropriate rows for a virtualized table based on row direction
+ * and grouping state.
+ * Rows are filtered if `ROW_DIRECTION` is `VERTICAL` and the table is grouped.
+ * @param table - Table.
+ * @param rows - Rows.
+ * @param rowDirection - Row direction.
+ * @returns Rows based on the provided row direction and table grouping state.
+ */
+export function getAllVirtualizedRows<T extends RowData>(
+  table: Table<T>,
+  rows: Row<T>[],
+  rowDirection: ROW_DIRECTION
+): Row<T>[] {
+  if (rowDirection === ROW_DIRECTION.DEFAULT) return rows;
+  if (table.getState().grouping.length === 0) return rows;
+  return rows.filter(({ getIsGrouped }) => getIsGrouped());
+}

package/src/components/Table/components/TableCell/components/CollapsableCell/collapsableCell.tsx

@@ -1,6 +1,7 @@
 import { Collapse, IconButton, Typography } from "@mui/material";
 import { Cell, flexRender, Row, RowData } from "@tanstack/react-table";
-import React, { useState } from "react";
+import { Virtualizer } from "@tanstack/react-virtual";
+import React from "react";
 import { TEXT_BODY_400_2_LINES } from "../../../../../../theme/common/typography";
 import { UnfoldMoreIcon } from "../../../../../common/CustomIcon/components/UnfoldMoreIcon/unfoldMoreIcon";
 import { getPinnedCellIndex } from "../../../../common/utils";
@@ -14,35 +15,36 @@ import {
 export interface CollapsableCellProps<T extends RowData> {
   isDisabled?: boolean;
   row: Row<T>;
+  virtualizer?: Virtualizer<Window, Element>;
 }
 
 export const CollapsableCell = <T extends RowData>({
   isDisabled = false,
   row,
+  virtualizer,
 }: CollapsableCellProps<T>): JSX.Element => {
-  const [isExpanded, setIsExpanded] = useState<boolean>(false);
   const [pinnedCell, pinnedIndex] = getPinnedCellIndex(row);
-
-  // Toggles open/close table cell.
-  const onToggleExpanded = (): void => {
-    setIsExpanded((expanded) => !expanded);
-  };
-
   return (
-    <TableCell isExpanded={isExpanded}>
+    <TableCell isExpanded={row.getIsExpanded()}>
       <PinnedCell>
         {flexRender(pinnedCell.column.columnDef.cell, pinnedCell.getContext())}
         <IconButton
           color="ink"
           disabled={isDisabled}
           edge="end"
-          onClick={onToggleExpanded}
+          onClick={() => row.toggleExpanded()}
           size="large"
         >
           <UnfoldMoreIcon fontSize="small" />
         </IconButton>
       </PinnedCell>
-      <Collapse in={isExpanded}>
+      <Collapse
+        in={row.getIsExpanded()}
+        mountOnEnter
+        onEntered={() => virtualizer?.measure()} // Measure when cell is opened.
+        onExited={() => virtualizer?.measure()} // Measure when cell is closed.
+        unmountOnExit
+      >
         <CollapsedContents>
           {getRowVisibleCells(row).map((cell, i) => {
             if (cell.getIsAggregated()) return null; // Display of aggregated cells is currently not supported.
@@ -80,10 +82,7 @@ function getRowVisibleCells<T extends RowData>(
   row: Row<T>
 ): Cell<T, unknown>[] {
   if (row.getIsGrouped()) {
-    return row
-      .getLeafRows()
-      .map((leafRow) => leafRow.getVisibleCells())
-      .flat();
+    return row.subRows.map(({ getVisibleCells }) => getVisibleCells()).flat();
   }
   return row.getVisibleCells();
 }

package/src/components/Table/components/TableFeatures/ColumnGrouping/utils.ts

@@ -0,0 +1,70 @@
+import { Column, RowData, Table } from "@tanstack/react-table";
+import { buildColumnSort } from "../RowSorting/utils";
+
+/**
+ * Clears the grouping state of the table and optionally resets the sorting state.
+ * ### Grouping State:
+ * - Grouping state is reset to `[]`.
+ * ### Sorting State:
+ * - Sorting state is reset to initial state (if sorting is enabled).
+ * @param table - Table.
+ */
+export function handleClearGroupingState<T extends RowData>(
+  table: Table<T>
+): void {
+  const {
+    options: { enableSorting },
+    resetGrouping,
+    resetSorting,
+  } = table;
+  resetGrouping(true); // Clears grouping state to `[]`.
+  if (enableSorting) resetSorting(); // Resets sorting state to initial state.
+}
+
+/**
+ * Toggles the grouping state for the given column.
+ * ### Grouping State
+ * - **Column grouping is not enabled**:
+ *   - No grouping action (exit).
+ * - **Column grouping is enabled**:
+ *   - Toggles the grouping state of the specified column.
+ * ### Sorting State
+ * - **Table sorting is not enabled**:
+ *   - No sorting action (exit).
+ * - **Column sorting is not enabled**:
+ *   - Resets sorting state to initial state.
+ * - **Column sorting is enabled**:
+ *   - Sets new sorting state with the grouped column as the first sort key.
+ * @param table - Table.
+ * @param column - Column.
+ */
+export function handleToggleGrouping<T extends RowData>(
+  table: Table<T>,
+  column: Column<T>
+): void {
+  const {
+    options: { enableSorting },
+    resetSorting,
+    setSorting,
+  } = table;
+  const { getCanGroup, getCanSort } = column;
+
+  // Column cannot be grouped.
+  if (!getCanGroup()) return;
+
+  // Toggle column grouping.
+  column.toggleGrouping(); // Grouping state currently only supports single-column grouping.
+
+  // Table sorting is not enabled.
+  if (!enableSorting) return;
+
+  // Column sorting is enabled.
+  if (getCanSort()) {
+    // Set new sorting state; grouped column is first sort.
+    setSorting([buildColumnSort(column)]);
+    return;
+  }
+
+  // Column sorting is not enabled; reset sorting state to initial state.
+  resetSorting();
+}

package/src/components/Table/components/TableFeatures/ColumnVisibility/utils.ts

@@ -0,0 +1,52 @@
+import { Column, RowData, Table } from "@tanstack/react-table";
+
+/**
+ * Toggles the visibility state for the given column.
+ * ### Column Visibility State
+ * - **Column visibility is not enabled**:
+ *   - No column visibility action (exit).
+ * - **Column visibility is enabled**:
+ *   - Toggles the visibility state of the specified column.
+ * ### Grouping and Sorting State
+ * - **Column is not visible**:
+ *   - No grouping or sorting action (exit).
+ * - **Column is visible**:
+ *   - **Column is grouped**:
+ *     - Resets grouping state to `[]`.
+ *     - Clears column from sorting state.
+ *   - **Column is not grouped**:
+ *     - No grouping or sorting action.
+ * @param table - Table.
+ * @param column - Column.
+ */
+export function handleToggleVisibility<T extends RowData>(
+  table: Table<T>,
+  column: Column<T>
+): void {
+  const {
+    options: { enableGrouping },
+    resetGrouping,
+  } = table;
+  const {
+    clearSorting,
+    getCanHide,
+    getIsGrouped,
+    getIsVisible,
+    toggleVisibility,
+  } = column;
+  if (!getCanHide()) return;
+
+  // Toggle column visibility.
+  toggleVisibility();
+
+  // Column is not visible i.e. requesting column visibility and therefore no further action is needed.
+  if (!getIsVisible()) return;
+
+  // Column is visible.
+  // Table grouping is enabled, and column is grouped.
+  if (enableGrouping && getIsGrouped()) {
+    resetGrouping(true); // Clears grouping state to `[]`.
+    // Currently, only a grouped column's sorting state is cleared.
+    clearSorting(); // Clears column sorting.
+  }
+}

package/src/components/Table/components/TableFeatures/RowSorting/utils.ts

@@ -0,0 +1,87 @@
+import { Column, ColumnSort, RowData, Table } from "@tanstack/react-table";
+import { MouseEvent } from "react";
+
+/**
+ * Constructs a `ColumnSort` object from a column.
+ * @param column - Column.
+ * @returns `ColumnSort` object with sorting direction and column ID.
+ */
+export function buildColumnSort<T extends RowData>(
+  column: Column<T>
+): ColumnSort {
+  return { desc: column.getFirstSortDir() === "desc", id: column.id };
+}
+
+/**
+ * Toggles the sorting state for the specified column.
+ * The sorting state of a table is modified based on user interaction, table grouping state, and
+ * its sorting configuration (single-sort or multi-sort modes).
+ * ### Sorting State:
+ * - **Ungrouped Table**:
+ *  - Sorting is toggled normally, respecting single-sort or multi-sort modes.
+ * - **Grouped Table**:
+ *   - **Multi-Sort Request**:
+ *     - Sorting is toggled normally.
+ *   - **Single-Sort Request**:
+ *     - **Multi-Sort Mode**:
+ *       - Grouped column is preserved as the first sort key, and the requested column is sorted as the second sort key.
+ *     - **Single-Sort Mode**:
+ *       - If the grouped column is already sorted, no action taken (the grouped column remains the primary sort key).
+ *       - Otherwise, sorting is toggled normally.
+ * @param mouseEvent - Mouse event.
+ * @param table - Table.
+ * @param column - Column.
+ */
+export function handleToggleSorting<T extends RowData>(
+  mouseEvent: MouseEvent,
+  table: Table<T>,
+  column: Column<T>
+): void {
+  const {
+    getColumn,
+    getState,
+    options: { enableMultiSort, isMultiSortEvent },
+    setSorting,
+  } = table;
+  const { getCanSort, getSortIndex, toggleSorting } = column;
+  const { grouping, sorting } = getState();
+
+  // Table and column sorting is not enabled.
+  if (!getCanSort()) return;
+
+  // Sorting is enabled.
+  // Table is not grouped; toggle sorting as usual.
+  if (grouping.length === 0) {
+    toggleSorting(undefined, isMultiSortEvent?.(mouseEvent));
+    return;
+  }
+
+  // Table is grouped.
+  // Multi-sort mode and multi-sort requested; toggle sorting as usual.
+  if (enableMultiSort && isMultiSortEvent?.(mouseEvent)) {
+    toggleSorting(undefined, true);
+    return;
+  }
+
+  // Retrieve the grouped column.
+  const groupedColumn = getColumn(grouping[0]); // Grouping state currently only supports single-column grouping.
+
+  // Single-sort requested (either single-sort or multi-sort mode).
+  // Grouped column is sorted.
+  if (groupedColumn?.getIsSorted()) {
+    if (enableMultiSort) {
+      // Multi-sort mode.
+      // Column to be sorted is not the last most recent sorted column.
+      if (getSortIndex() !== sorting.length - 1) {
+        // Reset sorting state, preserving grouped column as the first sort, and requested column to be sorted as the second sort.
+        setSorting([buildColumnSort(groupedColumn), buildColumnSort(column)]);
+        return;
+      }
+    } else {
+      // Special case; in single-sort mode we do not override a grouped sort.
+      return;
+    }
+  }
+
+  toggleSorting();
+}