@databiosphere/findable-ui 17.0.0 → 19.0.0

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();
+}

package/src/components/Table/components/TableHead/tableHead.tsx

@@ -1,22 +1,20 @@
+import SouthRoundedIcon from "@mui/icons-material/SouthRounded";
 import {
   TableHead as MTableHead,
   TableRow as MTableRow,
   TableCell,
   TableSortLabel,
 } from "@mui/material";
-import { flexRender, RowData, Table } from "@tanstack/react-table";
+import { flexRender, RowData } from "@tanstack/react-table";
 import React, { Fragment } from "react";
 import { ROW_DIRECTION } from "../../common/entities";
-import { getTableSortLabelProps } from "../../common/utils";
 import {
   getTableCellAlign,
   getTableCellPadding,
 } from "../TableCell/common/utils";
-
-export interface TableHeadProps<T extends RowData> {
-  rowDirection: ROW_DIRECTION;
-  tableInstance: Table<T>;
-}
+import { handleToggleSorting } from "../TableFeatures/RowSorting/utils";
+import { TableHeadProps } from "./types";
+import { isSortDisabled, shouldSortColumn } from "./utils";
 
 export const TableHead = <T extends RowData>({
   rowDirection,
@@ -28,34 +26,28 @@ export const TableHead = <T extends RowData>({
         tableInstance.getHeaderGroups().map((headerGroup) => (
           <MTableHead key={headerGroup.id}>
             <MTableRow>
-              {headerGroup.headers.map((header) => {
-                const {
-                  column: {
-                    columnDef: {
-                      meta: { enableSortingInteraction = true } = {},
-                    },
-                  },
-                } = header;
-                return header.column.getIsGrouped() ? null : (
+              {headerGroup.headers.map(({ column, getContext, id }) => {
+                const { columnDef, getIsGrouped, getIsSorted } = column;
+                return getIsGrouped() ? null : (
                   <TableCell
-                    key={header.id}
-                    align={getTableCellAlign(header.column)}
-                    padding={getTableCellPadding(header.id)}
+                    key={id}
+                    align={getTableCellAlign(column)}
+                    padding={getTableCellPadding(id)}
                   >
-                    {header.column.getCanSort() && enableSortingInteraction ? (
+                    {shouldSortColumn(tableInstance, column) ? (
                       <TableSortLabel
-                        {...getTableSortLabelProps(header.column)}
+                        IconComponent={SouthRoundedIcon}
+                        active={Boolean(getIsSorted())}
+                        direction={getIsSorted() || undefined}
+                        disabled={isSortDisabled(tableInstance)}
+                        onClick={(mouseEvent) =>
+                          handleToggleSorting(mouseEvent, tableInstance, column)
+                        }
                       >
-                        {flexRender(
-                          header.column.columnDef.header,
-                          header.getContext()
-                        )}
+                        {flexRender(columnDef.header, getContext())}
                       </TableSortLabel>
                     ) : (
-                      flexRender(
-                        header.column.columnDef.header,
-                        header.getContext()
-                      )
+                      flexRender(columnDef.header, getContext())
                     )}
                   </TableCell>
                 );

package/src/components/Table/components/TableHead/types.ts

@@ -0,0 +1,7 @@
+import { RowData, Table } from "@tanstack/react-table";
+import { ROW_DIRECTION } from "../../common/entities";
+
+export interface TableHeadProps<T extends RowData> {
+  rowDirection: ROW_DIRECTION;
+  tableInstance: Table<T>;
+}

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

@@ -0,0 +1,42 @@
+import { Column, RowData, Table } from "@tanstack/react-table";
+
+/**
+ * Determines if the column sorting interaction should be disabled.
+ * The sort label is disabled under the following conditions:
+ * - The table is in single-sort mode, and is grouped, and the grouped column is already sorted.
+ * When multi-sort mode is enabled or the table is not grouped, the sort label remains enabled.
+ * @param table - Table.
+ * @returns `true` if the sort label should be disabled; otherwise, `false`.
+ */
+export function isSortDisabled<T extends RowData>(table: Table<T>): boolean {
+  const {
+    getColumn,
+    getState,
+    options: { enableMultiSort },
+  } = table;
+  const { grouping } = getState();
+  // Multi-sort is enabled - sorting is always enabled.
+  if (enableMultiSort) return false;
+  // Table is not grouped - sorting is always enabled.
+  if (grouping.length === 0) return false;
+  // In single-sort mode, check if the grouped column is already sorted.
+  const groupedColumn = getColumn(grouping[0]); // Grouping state currently only supports single-column grouping.
+  return Boolean(groupedColumn?.getIsSorted());
+}
+
+/**
+ * Checks whether a column in a table can be sorted.
+ * A column is sortable if both table sorting interactions are enabled
+ * and the column itself is marked as sortable.
+ * @param table - Table.
+ * @param column - Column.
+ * @returns {boolean} `true` if the column can be sorted; otherwise, `false`.
+ */
+export function shouldSortColumn<T extends RowData>(
+  table: Table<T>,
+  column: Column<T>
+): boolean {
+  const { enableSortingInteraction } = table.options;
+  const canSort = column.getCanSort();
+  return Boolean(enableSortingInteraction && canSort);
+}

package/src/components/Table/components/TableRow/tableRow.styles.ts

@@ -1,18 +1,35 @@
 import { css } from "@emotion/react";
 import styled from "@emotion/styled";
 import { TableRow as MTableRow } from "@mui/material";
-import { primaryLightest } from "../../../../styles/common/mixins/colors";
+import {
+  primaryLightest,
+  smokeLightest,
+} from "../../../../styles/common/mixins/colors";
+import { textBodySmall500 } from "../../../../styles/common/mixins/fonts";
 
 interface Props {
+  isGrouped?: boolean;
   isPreview?: boolean;
 }
 
 export const TableRow = styled(MTableRow, {
-  shouldForwardProp: (prop) => prop !== "isPreview",
+  shouldForwardProp: (prop) => prop !== "isPreview" && prop !== "isGrouped",
 })<Props>`
   && {
     transition: background-color 300ms ease-in;
 
+    ${(props) =>
+      props.isGrouped &&
+      css`
+        background-color: ${smokeLightest(props)};
+
+        td {
+          ${textBodySmall500(props)};
+          background-color: inherit;
+          grid-column: 1 / -1;
+        }
+      `}
+
     ${(props) =>
       props.isPreview &&
       css`

package/src/components/Table/components/TableRows/components/CollapsableRows/collapsableRows.tsx

@@ -4,24 +4,29 @@ import React, { Fragment } from "react";
 import { isCollapsableRowDisabled } from "../../../../common/utils";
 import { CollapsableCell } from "../../../TableCell/components/CollapsableCell/collapsableCell";
 import { TableRow } from "../../../TableRow/tableRow.styles";
+import { useCollapsableRows } from "./hook";
 
 export interface CollapsableRowsProps<T extends RowData> {
+  rows: Row<T>[];
   tableInstance: Table<T>;
   virtualizer: Virtualizer<Window, Element>;
 }
 
 export const CollapsableRows = <T extends RowData>({
+  rows,
   tableInstance,
   virtualizer,
 }: CollapsableRowsProps<T>): JSX.Element => {
-  const { getRowModel } = tableInstance;
-  const { rows } = getRowModel();
+  const { getState } = tableInstance;
+  const { grouping } = getState();
   const virtualItems = virtualizer.getVirtualItems();
+  useCollapsableRows(tableInstance);
   return (
     <Fragment>
       {virtualItems.map((virtualRow) => {
         const row = rows[virtualRow.index] as Row<T>;
         const { getIsPreview } = row;
+        if (grouping.length > 0 && row.depth > 0) return null; // TODO(cc) hide sub rows -- sub-rows are within collapsed content -- UI TBD.
         return (
           <TableRow
             key={row.id}
@@ -32,6 +37,7 @@ export const CollapsableRows = <T extends RowData>({
             <CollapsableCell
               isDisabled={isCollapsableRowDisabled(tableInstance)}
               row={row}
+              virtualizer={virtualizer}
             />
           </TableRow>
         );

package/src/components/Table/components/TableRows/components/CollapsableRows/hook.ts

@@ -0,0 +1,20 @@
+import { RowData, Table } from "@tanstack/react-table";
+import { useEffect } from "react";
+
+/**
+ * Hook to manage the expanded row state during viewport transitions (e.g., desktop to mobile and vice versa).
+ * Designed for use with the `CollapsableRows` component, where row expansion is a work in progress for desktop viewports.
+ * This hook ensures that all rows are collapsed when transitioning from desktop to mobile (when `CollapsableRows` component is mounted).
+ * It also resets the expanded row state when transitioning back to desktop (when the `CollapsableRows` component is unmounted).
+ * @param table - Table.
+ */
+export function useCollapsableRows<T extends RowData>(table: Table<T>): void {
+  const { resetExpanded, toggleAllRowsExpanded } = table;
+
+  useEffect(() => {
+    toggleAllRowsExpanded(false);
+    return (): void => {
+      resetExpanded();
+    };
+  }, [resetExpanded, toggleAllRowsExpanded]);
+}