@cutting/material-react-table 4.0.0

package/src/hooks/display-columns/getMRT_RowActionsColumnDef.tsx

@@ -0,0 +1,28 @@
+import { MRT_ToggleRowActionMenuButton } from '../../components/buttons/MRT_ToggleRowActionMenuButton';
+import {
+  type MRT_ColumnDef,
+  type MRT_RowData,
+  type MRT_StatefulTableOptions,
+} from '../../types';
+import { defaultDisplayColumnProps } from '../../utils/displayColumn.utils';
+
+export const getMRT_RowActionsColumnDef = <TData extends MRT_RowData>(
+  tableOptions: MRT_StatefulTableOptions<TData>,
+): MRT_ColumnDef<TData> => {
+  return {
+    Cell: ({ cell, row, staticRowIndex, table }) => (
+      <MRT_ToggleRowActionMenuButton
+        cell={cell}
+        row={row}
+        staticRowIndex={staticRowIndex}
+        table={table}
+      />
+    ),
+    ...defaultDisplayColumnProps({
+      header: 'actions',
+      id: 'mrt-row-actions',
+      size: 70,
+      tableOptions,
+    }),
+  };
+};

package/src/hooks/display-columns/getMRT_RowDragColumnDef.tsx

@@ -0,0 +1,30 @@
+import { type RefObject } from 'react';
+
+import { MRT_TableBodyRowGrabHandle } from '../../components/body/MRT_TableBodyRowGrabHandle';
+import {
+  type MRT_ColumnDef,
+  type MRT_RowData,
+  type MRT_StatefulTableOptions,
+} from '../../types';
+import { defaultDisplayColumnProps } from '../../utils/displayColumn.utils';
+
+export const getMRT_RowDragColumnDef = <TData extends MRT_RowData>(
+  tableOptions: MRT_StatefulTableOptions<TData>,
+): MRT_ColumnDef<TData> => {
+  return {
+    Cell: ({ row, rowRef, table }) => (
+      <MRT_TableBodyRowGrabHandle
+        row={row}
+        rowRef={rowRef as RefObject<HTMLTableRowElement | null>}
+        table={table}
+      />
+    ),
+    grow: false,
+    ...defaultDisplayColumnProps({
+      header: 'move',
+      id: 'mrt-row-drag',
+      size: 60,
+      tableOptions,
+    }),
+  };
+};

package/src/hooks/display-columns/getMRT_RowExpandColumnDef.tsx

@@ -0,0 +1,97 @@
+import Stack from '@mui/material/Stack';
+import Tooltip from '@mui/material/Tooltip';
+import { type ReactNode } from 'react';
+
+import { MRT_ExpandAllButton } from '../../components/buttons/MRT_ExpandAllButton';
+import { MRT_ExpandButton } from '../../components/buttons/MRT_ExpandButton';
+import {
+  type MRT_ColumnDef,
+  type MRT_RowData,
+  type MRT_StatefulTableOptions,
+} from '../../types';
+import { defaultDisplayColumnProps } from '../../utils/displayColumn.utils';
+import { getCommonTooltipProps } from '../../utils/style.utils';
+
+export const getMRT_RowExpandColumnDef = <TData extends MRT_RowData>(
+  tableOptions: MRT_StatefulTableOptions<TData>,
+): MRT_ColumnDef<TData> => {
+  const {
+    defaultColumn,
+    enableExpandAll,
+    groupedColumnMode,
+    positionExpandColumn,
+    renderDetailPanel,
+    state: { grouping },
+  } = tableOptions;
+
+  const alignProps =
+    positionExpandColumn === 'last'
+      ? ({
+          align: 'right',
+        } as const)
+      : undefined;
+
+  return {
+    Cell: ({ cell, column, row, staticRowIndex, table }) => {
+      const expandButtonProps = { row, staticRowIndex, table };
+      const subRowsLength = row.subRows?.length;
+      if (groupedColumnMode === 'remove' && row.groupingColumnId) {
+        return (
+          <Stack
+            sx={{
+              alignItems: "center",
+              flexDirection: "row",
+              gap: "0.25rem"
+            }}>
+            <MRT_ExpandButton {...expandButtonProps} />
+            <Tooltip
+              {...getCommonTooltipProps('right')}
+              title={table.getColumn(row.groupingColumnId).columnDef.header}
+            >
+              <span>{row.groupingValue as ReactNode}</span>
+            </Tooltip>
+            {!!subRowsLength && <span>({subRowsLength})</span>}
+          </Stack>
+        );
+      } else {
+        return (
+          <>
+            <MRT_ExpandButton {...expandButtonProps} />
+            {column.columnDef.GroupedCell?.({ cell, column, row, table })}
+          </>
+        );
+      }
+    },
+    Header: enableExpandAll
+      ? ({ table }) => {
+          return (
+            <>
+              <MRT_ExpandAllButton table={table} />
+              {groupedColumnMode === 'remove' &&
+                grouping
+                  ?.map(
+                    (groupedColumnId) =>
+                      table.getColumn(groupedColumnId).columnDef.header,
+                  )
+                  ?.join(', ')}
+            </>
+          );
+        }
+      : undefined,
+    muiTableBodyCellProps: alignProps,
+    muiTableHeadCellProps: alignProps,
+    ...defaultDisplayColumnProps({
+      header: 'expand',
+      id: 'mrt-row-expand',
+      size:
+        groupedColumnMode === 'remove'
+          ? (defaultColumn?.size ?? 180)
+          : renderDetailPanel
+            ? enableExpandAll
+              ? 60
+              : 70
+            : 100,
+      tableOptions,
+    }),
+  };
+};

package/src/hooks/display-columns/getMRT_RowNumbersColumnDef.tsx

@@ -0,0 +1,30 @@
+import {
+  type MRT_ColumnDef,
+  type MRT_RowData,
+  type MRT_StatefulTableOptions,
+} from '../../types';
+import { defaultDisplayColumnProps } from '../../utils/displayColumn.utils';
+
+export const getMRT_RowNumbersColumnDef = <TData extends MRT_RowData>(
+  tableOptions: MRT_StatefulTableOptions<TData>,
+): MRT_ColumnDef<TData> => {
+  const { localization, rowNumberDisplayMode } = tableOptions;
+  const {
+    pagination: { pageIndex, pageSize },
+  } = tableOptions.state;
+
+  return {
+    Cell: ({ row, staticRowIndex }) =>
+      ((rowNumberDisplayMode === 'static'
+        ? (staticRowIndex || 0) + (pageSize || 0) * (pageIndex || 0)
+        : row.index) ?? 0) + 1,
+    grow: false,
+    Header: () => localization.rowNumber,
+    ...defaultDisplayColumnProps({
+      header: 'rowNumbers',
+      id: 'mrt-row-numbers',
+      size: 50,
+      tableOptions,
+    }),
+  };
+};

package/src/hooks/display-columns/getMRT_RowPinningColumnDef.tsx

@@ -0,0 +1,24 @@
+import { MRT_TableBodyRowPinButton } from '../../components/body/MRT_TableBodyRowPinButton';
+import {
+  type MRT_ColumnDef,
+  type MRT_RowData,
+  type MRT_StatefulTableOptions,
+} from '../../types';
+import { defaultDisplayColumnProps } from '../../utils/displayColumn.utils';
+
+export const getMRT_RowPinningColumnDef = <TData extends MRT_RowData>(
+  tableOptions: MRT_StatefulTableOptions<TData>,
+): MRT_ColumnDef<TData> => {
+  return {
+    Cell: ({ row, table }) => (
+      <MRT_TableBodyRowPinButton row={row} table={table} />
+    ),
+    grow: false,
+    ...defaultDisplayColumnProps({
+      header: 'pin',
+      id: 'mrt-row-pin',
+      size: 60,
+      tableOptions,
+    }),
+  };
+};

package/src/hooks/display-columns/getMRT_RowSelectColumnDef.tsx

@@ -0,0 +1,34 @@
+import { MRT_SelectCheckbox } from '../../components/inputs/MRT_SelectCheckbox';
+import {
+  type MRT_ColumnDef,
+  type MRT_RowData,
+  type MRT_StatefulTableOptions,
+} from '../../types';
+import { defaultDisplayColumnProps } from '../../utils/displayColumn.utils';
+
+export const getMRT_RowSelectColumnDef = <TData extends MRT_RowData>(
+  tableOptions: MRT_StatefulTableOptions<TData>,
+): MRT_ColumnDef<TData> => {
+  const { enableMultiRowSelection, enableSelectAll } = tableOptions;
+
+  return {
+    Cell: ({ row, staticRowIndex, table }) => (
+      <MRT_SelectCheckbox
+        row={row}
+        staticRowIndex={staticRowIndex}
+        table={table}
+      />
+    ),
+    grow: false,
+    Header:
+      enableSelectAll && enableMultiRowSelection
+        ? ({ table }) => <MRT_SelectCheckbox table={table} />
+        : undefined,
+    ...defaultDisplayColumnProps({
+      header: 'select',
+      id: 'mrt-row-select',
+      size: enableSelectAll ? 60 : 70,
+      tableOptions,
+    }),
+  };
+};

package/src/hooks/display-columns/getMRT_RowSpacerColumnDef.tsx

@@ -0,0 +1,33 @@
+import {
+  type MRT_ColumnDef,
+  type MRT_RowData,
+  type MRT_StatefulTableOptions,
+} from '../../types';
+import { defaultDisplayColumnProps } from '../../utils/displayColumn.utils';
+import { MRT_DefaultDisplayColumn } from '../useMRT_TableOptions';
+
+const blankColProps = {
+  children: null,
+  sx: {
+    minWidth: 0,
+    p: 0,
+    width: 0,
+  },
+};
+
+export const getMRT_RowSpacerColumnDef = <TData extends MRT_RowData>(
+  tableOptions: MRT_StatefulTableOptions<TData>,
+): MRT_ColumnDef<TData> => {
+  return {
+    ...defaultDisplayColumnProps({
+      id: 'mrt-row-spacer',
+      size: 0,
+      tableOptions,
+    }),
+    grow: true,
+    ...MRT_DefaultDisplayColumn,
+    muiTableBodyCellProps: blankColProps,
+    muiTableFooterCellProps: blankColProps,
+    muiTableHeadCellProps: blankColProps,
+  };
+};

package/src/hooks/useMRT_ColumnVirtualizer.ts

@@ -0,0 +1,125 @@
+import { type Range, useVirtualizer } from '@tanstack/react-virtual';
+import { useCallback, useMemo } from 'react';
+
+import {
+  type MRT_ColumnVirtualizer,
+  type MRT_RowData,
+  type MRT_TableInstance,
+} from '../types';
+import { parseFromValuesOrFunc } from '../utils/utils';
+import { extraIndexRangeExtractor } from '../utils/virtualization.utils';
+
+export const useMRT_ColumnVirtualizer = <
+  TData extends MRT_RowData,
+  TScrollElement extends Element | Window = HTMLDivElement,
+  TItemElement extends Element = HTMLTableCellElement,
+>(
+  table: MRT_TableInstance<TData>,
+): MRT_ColumnVirtualizer | undefined => {
+  const {
+    getState,
+    options: {
+      columnVirtualizerInstanceRef,
+      columnVirtualizerOptions,
+      enableColumnPinning,
+      enableColumnVirtualization,
+    },
+    refs: { tableContainerRef },
+  } = table;
+  const { columnPinning, columnVisibility, draggingColumn } = getState();
+
+  if (!enableColumnVirtualization) return undefined;
+
+  const columnVirtualizerProps = parseFromValuesOrFunc(
+    columnVirtualizerOptions,
+    {
+      table,
+    },
+  );
+
+  const visibleColumns = table.getVisibleLeafColumns();
+
+  const [leftPinnedIndexes, rightPinnedIndexes] = useMemo(
+    () =>
+      enableColumnPinning
+        ? [
+            table.getLeftVisibleLeafColumns().map((c) => c.getPinnedIndex()),
+            table
+              .getRightVisibleLeafColumns()
+              .map(
+                (column) => visibleColumns.length - column.getPinnedIndex() - 1,
+              )
+              .sort((a, b) => a - b),
+          ]
+        : [[], []],
+    [columnPinning, columnVisibility, enableColumnPinning],
+  );
+
+  const numPinnedLeft = leftPinnedIndexes.length;
+  const numPinnedRight = rightPinnedIndexes.length;
+
+  const draggingColumnIndex = useMemo(
+    () =>
+      draggingColumn?.id
+        ? visibleColumns.findIndex((c) => c.id === draggingColumn?.id)
+        : undefined,
+    [draggingColumn?.id],
+  );
+
+  const columnVirtualizer = useVirtualizer({
+    count: visibleColumns.length,
+    estimateSize: (index) => visibleColumns[index].getSize(),
+    getScrollElement: () => tableContainerRef.current,
+    horizontal: true,
+    overscan: 3,
+    rangeExtractor: useCallback(
+      (range: Range) => {
+        const newIndexes = extraIndexRangeExtractor(range, draggingColumnIndex);
+        if (!numPinnedLeft && !numPinnedRight) {
+          return newIndexes;
+        }
+        return [
+          ...new Set([
+            ...leftPinnedIndexes,
+            ...newIndexes,
+            ...rightPinnedIndexes,
+          ]),
+        ];
+      },
+      [leftPinnedIndexes, rightPinnedIndexes, draggingColumnIndex],
+    ),
+    ...columnVirtualizerProps,
+  }) as unknown as MRT_ColumnVirtualizer<TScrollElement, TItemElement>;
+
+  const virtualColumns = columnVirtualizer.getVirtualItems();
+  columnVirtualizer.virtualColumns = virtualColumns as any;
+  const numColumns = virtualColumns.length;
+
+  if (numColumns) {
+    const totalSize = columnVirtualizer.getTotalSize();
+
+    const leftNonPinnedStart = virtualColumns[numPinnedLeft]?.start || 0;
+    const leftNonPinnedEnd =
+      virtualColumns[leftPinnedIndexes.length - 1]?.end || 0;
+
+    const rightNonPinnedStart =
+      virtualColumns[numColumns - numPinnedRight]?.start || 0;
+    const rightNonPinnedEnd =
+      virtualColumns[numColumns - numPinnedRight - 1]?.end || 0;
+
+    columnVirtualizer.virtualPaddingLeft =
+      leftNonPinnedStart - leftNonPinnedEnd;
+
+    columnVirtualizer.virtualPaddingRight =
+      totalSize -
+      rightNonPinnedEnd -
+      (numPinnedRight ? totalSize - rightNonPinnedStart : 0);
+  }
+
+  if (columnVirtualizerInstanceRef) {
+    //@ts-expect-error
+    columnVirtualizerInstanceRef.current = columnVirtualizer;
+  }
+
+  return columnVirtualizer as any;
+};

package/src/hooks/useMRT_Effects.ts

@@ -0,0 +1,107 @@
+import { useEffect, useReducer, useRef } from 'react';
+
+import {
+  type MRT_RowData,
+  type MRT_SortingState,
+  type MRT_TableInstance,
+} from '../types';
+import { getDefaultColumnOrderIds } from '../utils/displayColumn.utils';
+import { getCanRankRows } from '../utils/row.utils';
+
+export const useMRT_Effects = <TData extends MRT_RowData>(
+  table: MRT_TableInstance<TData>,
+) => {
+  const {
+    getIsSomeRowsPinned,
+    getPrePaginationRowModel,
+    getState,
+    options: { enablePagination, enableRowPinning, rowCount },
+  } = table;
+  const {
+    columnOrder,
+    density,
+    globalFilter,
+    isFullScreen,
+    isLoading,
+    pagination,
+    showSkeletons,
+    sorting,
+  } = getState();
+
+  const totalColumnCount = table.options.columns.length;
+  const totalRowCount = rowCount ?? getPrePaginationRowModel().rows.length;
+
+  const rerender = useReducer(() => ({}), {})[1];
+  const initialBodyHeight = useRef<string>(null);
+  const previousTop = useRef<number>(null);
+
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      initialBodyHeight.current = document.body.style.height;
+    }
+  }, []);
+
+  //hide scrollbars when table is in full screen mode, preserve body scroll position after full screen exit
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      if (isFullScreen) {
+        previousTop.current = document.body.getBoundingClientRect().top; //save scroll position
+        document.body.style.height = '100dvh'; //hide page scrollbars when table is in full screen mode
+      } else {
+        document.body.style.height = initialBodyHeight.current as string;
+        if (!previousTop.current) return;
+        //restore scroll position
+        window.scrollTo({
+          behavior: 'instant',
+          top: -1 * (previousTop.current as number),
+        });
+      }
+    }
+  }, [isFullScreen]);
+
+  //recalculate column order when columns change or features are toggled on/off
+  useEffect(() => {
+    if (totalColumnCount !== columnOrder.length) {
+      table.setColumnOrder(getDefaultColumnOrderIds(table.options));
+    }
+  }, [totalColumnCount]);
+
+  //if page index is out of bounds, set it to the last page
+  useEffect(() => {
+    if (!enablePagination || isLoading || showSkeletons) return;
+    const { pageIndex, pageSize } = pagination;
+    const totalPages: number =
+      totalRowCount > 0 ? Math.ceil(totalRowCount / pageSize) : 1;
+    const isOutOfBounds: boolean = pageIndex < 0 || pageIndex >= totalPages;
+
+    if (isOutOfBounds) {
+      table.setPageIndex(totalPages - 1);
+    }
+  }, [totalRowCount, enablePagination, isLoading, showSkeletons]);
+
+  //turn off sort when global filter is looking for ranked results
+  const appliedSort = useRef<MRT_SortingState>(sorting);
+  useEffect(() => {
+    if (sorting.length) {
+      appliedSort.current = sorting;
+    }
+  }, [sorting]);
+
+  useEffect(() => {
+    if (!getCanRankRows(table)) return;
+    if (globalFilter) {
+      table.setSorting([]);
+    } else {
+      table.setSorting(() => appliedSort.current || []);
+    }
+  }, [globalFilter]);
+
+  //fix pinned row top style when density changes
+  useEffect(() => {
+    if (enableRowPinning && getIsSomeRowsPinned()) {
+      setTimeout(() => {
+        rerender();
+      }, 150);
+    }
+  }, [density]);
+};

package/src/hooks/useMRT_RowVirtualizer.ts

@@ -0,0 +1,89 @@
+import { type Range, useVirtualizer } from '@tanstack/react-virtual';
+import { useCallback, useMemo } from 'react';
+
+import {
+  type MRT_Row,
+  type MRT_RowData,
+  type MRT_RowVirtualizer,
+  type MRT_TableInstance,
+} from '../types';
+import { parseFromValuesOrFunc } from '../utils/utils';
+import { extraIndexRangeExtractor } from '../utils/virtualization.utils';
+
+export const useMRT_RowVirtualizer = <
+  TData extends MRT_RowData,
+  TScrollElement extends Element | Window = HTMLDivElement,
+  TItemElement extends Element = HTMLTableRowElement,
+>(
+  table: MRT_TableInstance<TData>,
+  rows?: MRT_Row<TData>[],
+): MRT_RowVirtualizer<TScrollElement, TItemElement> | undefined => {
+  const {
+    getRowModel,
+    getState,
+    options: {
+      enableRowVirtualization,
+      renderDetailPanel,
+      rowVirtualizerInstanceRef,
+      rowVirtualizerOptions,
+    },
+    refs: { tableContainerRef },
+  } = table;
+  const { density, draggingRow, expanded } = getState();
+
+  if (!enableRowVirtualization) return undefined;
+
+  const rowVirtualizerProps = parseFromValuesOrFunc(rowVirtualizerOptions, {
+    table,
+  });
+
+  const realRows = rows ?? getRowModel().rows;
+  /**
+   * when filtering, should find the correct index in filtered rows
+   */
+  const draggingRowIndex = useMemo(
+    () =>
+      draggingRow?.id
+        ? realRows.findIndex((r) => r.id === draggingRow?.id)
+        : undefined,
+    [realRows, draggingRow?.id],
+  );
+
+  const rowCount = realRows.length;
+
+  const normalRowHeight =
+    density === 'compact' ? 37 : density === 'comfortable' ? 58 : 73;
+
+  const rowVirtualizer = useVirtualizer({
+    count: renderDetailPanel ? rowCount * 2 : rowCount,
+    estimateSize: (index) =>
+      renderDetailPanel && index % 2 === 1
+        ? expanded === true
+          ? 100
+          : 0
+        : normalRowHeight,
+    getScrollElement: () => tableContainerRef.current,
+    measureElement:
+      typeof window !== 'undefined' &&
+      navigator.userAgent.indexOf('Firefox') === -1
+        ? (element) => element?.getBoundingClientRect().height
+        : undefined,
+    overscan: 4,
+    rangeExtractor: useCallback(
+      (range: Range) => {
+        return extraIndexRangeExtractor(range, draggingRowIndex);
+      },
+      [draggingRowIndex],
+    ),
+    ...rowVirtualizerProps,
+  }) as unknown as MRT_RowVirtualizer<TScrollElement, TItemElement>;
+
+  rowVirtualizer.virtualRows = rowVirtualizer.getVirtualItems() as any;
+
+  if (rowVirtualizerInstanceRef) {
+    //@ts-expect-error
+    rowVirtualizerInstanceRef.current = rowVirtualizer;
+  }
+
+  return rowVirtualizer;
+};

package/src/hooks/useMRT_Rows.ts

@@ -0,0 +1,45 @@
+import { useMemo } from 'react';
+
+import {
+  type MRT_Row,
+  type MRT_RowData,
+  type MRT_TableInstance,
+} from '../types';
+import { getMRT_Rows } from '../utils/row.utils';
+
+export const useMRT_Rows = <TData extends MRT_RowData>(
+  table: MRT_TableInstance<TData>,
+): MRT_Row<TData>[] => {
+  const {
+    getRowModel,
+    getState,
+    options: { data, enableGlobalFilterRankedResults, positionCreatingRow },
+  } = table;
+  const {
+    creatingRow,
+    expanded,
+    globalFilter,
+    pagination,
+    rowPinning,
+    sorting,
+  } = getState();
+
+  const rows = useMemo(
+    () => getMRT_Rows(table),
+    [
+      creatingRow,
+      data,
+      enableGlobalFilterRankedResults,
+      expanded,
+      getRowModel().rows,
+      globalFilter,
+      pagination.pageIndex,
+      pagination.pageSize,
+      positionCreatingRow,
+      rowPinning,
+      sorting,
+    ],
+  );
+
+  return rows;
+};