@lminii/material-react-table 4.0.0

package/src/hooks/useMRT_ColumnVirtualizer.ts

@@ -0,0 +1,124 @@
+import { useCallback, useMemo } from 'react';
+import { type Range, useVirtualizer } from '@tanstack/react-virtual';
+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 {
+    options: {
+      columnVirtualizerInstanceRef,
+      columnVirtualizerOptions,
+      enableColumnPinning,
+      enableColumnVirtualization,
+    },
+    refs: { tableContainerRef },
+    state,
+  } = table;
+  const { columnPinning, columnVisibility, draggingColumn } = state;
+
+  if (!enableColumnVirtualization) return undefined;
+
+  const columnVirtualizerProps = parseFromValuesOrFunc(
+    columnVirtualizerOptions,
+    {
+      table,
+    },
+  );
+
+  const visibleColumns = table.getVisibleLeafColumns();
+
+  const [leftPinnedIndexes, rightPinnedIndexes] = useMemo(
+    () =>
+      enableColumnPinning
+        ? [
+            table.getStartVisibleLeafColumns().map((c) => c.getPinnedIndex()),
+            table
+              .getEndVisibleLeafColumns()
+              .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,108 @@
+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,
+    getPrePaginatedRowModel,
+    options: { enablePagination, enableRowPinning, rowCount },
+    state,
+  } = table;
+  const {
+    columnOrder,
+    density,
+    globalFilter,
+    isFullScreen,
+    isLoading,
+    pagination,
+    showSkeletons,
+    sorting,
+  } = state;
+
+  const totalColumnCount = table.options.columns.length;
+  const totalRowCount = rowCount ?? getPrePaginatedRowModel().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, state: table.state }),
+      );
+    }
+  }, [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,88 @@
+import { useCallback, useMemo } from 'react';
+import { type Range, useVirtualizer } from '@tanstack/react-virtual';
+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,
+    options: {
+      enableRowVirtualization,
+      renderDetailPanel,
+      rowVirtualizerInstanceRef,
+      rowVirtualizerOptions,
+    },
+    refs: { tableContainerRef },
+    state,
+  } = table;
+  const { density, draggingRow, expanded } = state;
+
+  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,44 @@
+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,
+    options: { data, enableGlobalFilterRankedResults, positionCreatingRow },
+    state,
+  } = table;
+  const {
+    creatingRow,
+    expanded,
+    globalFilter,
+    pagination,
+    rowPinning,
+    sorting,
+  } = state;
+
+  const rows = useMemo(
+    () => getMRT_Rows(table),
+    [
+      creatingRow,
+      data,
+      enableGlobalFilterRankedResults,
+      expanded,
+      getRowModel().rows,
+      globalFilter,
+      pagination.pageIndex,
+      pagination.pageSize,
+      positionCreatingRow,
+      rowPinning,
+      sorting,
+    ],
+  );
+
+  return rows;
+};

package/src/hooks/useMRT_TableInstance.ts

@@ -0,0 +1,181 @@
+import { useMemo, useRef } from 'react';
+import { useTable } from '@tanstack/react-table';
+import { getMRT_RowActionsColumnDef } from './display-columns/getMRT_RowActionsColumnDef';
+import { getMRT_RowDragColumnDef } from './display-columns/getMRT_RowDragColumnDef';
+import { getMRT_RowExpandColumnDef } from './display-columns/getMRT_RowExpandColumnDef';
+import { getMRT_RowNumbersColumnDef } from './display-columns/getMRT_RowNumbersColumnDef';
+import { getMRT_RowPinningColumnDef } from './display-columns/getMRT_RowPinningColumnDef';
+import { getMRT_RowSelectColumnDef } from './display-columns/getMRT_RowSelectColumnDef';
+import { getMRT_RowSpacerColumnDef } from './display-columns/getMRT_RowSpacerColumnDef';
+import { useMRT_Effects } from './useMRT_Effects';
+import {
+  mrtFeatures,
+  mrtFeaturesWithoutFacetedValues,
+} from '../features/mrtFeatures';
+import {
+  type MRT_ColumnDef,
+  type MRT_ColumnResizingState,
+  type MRT_DefinedTableOptions,
+  type MRT_RowData,
+  type MRT_StatefulTableOptions,
+  type MRT_TableInstance,
+  type MRT_TableState,
+} from '../types';
+import {
+  getAllLeafColumnDefs,
+  getColumnId,
+  getDefaultColumnFilterFn,
+  prepareColumns,
+} from '../utils/column.utils';
+import {
+  getDefaultColumnOrderIds,
+  showRowActionsColumn,
+  showRowDragColumn,
+  showRowExpandColumn,
+  showRowNumbersColumn,
+  showRowPinningColumn,
+  showRowSelectionColumn,
+  showRowSpacerColumn,
+} from '../utils/displayColumn.utils';
+
+/**
+ * The MRT hook that wraps the TanStack useTable hook and adds additional functionality
+ * @param definedTableOptions - table options with proper defaults set
+ * @returns the MRT table instance
+ */
+export const useMRT_TableInstance = <TData extends MRT_RowData>(
+  definedTableOptions: MRT_DefinedTableOptions<TData>,
+): MRT_TableInstance<TData> => {
+  const tableRef = useRef<MRT_TableInstance<TData> | null>(null);
+
+  //transform initial state with proper column order and filter fns
+  const initialState: Partial<MRT_TableState<TData>> = useMemo(() => {
+    const initState = definedTableOptions.initialState ?? {};
+    initState.columnOrder =
+      initState.columnOrder ??
+      getDefaultColumnOrderIds({
+        ...definedTableOptions,
+        state: {
+          ...definedTableOptions.initialState,
+          ...definedTableOptions.state,
+        },
+      } as MRT_StatefulTableOptions<TData>);
+    initState.columnFilterFns = Object.assign(
+      {},
+      ...getAllLeafColumnDefs(
+        definedTableOptions.columns as MRT_ColumnDef<TData>[],
+      ).map((col) => ({
+        [getColumnId(col)]:
+          col.filterFn instanceof Function
+            ? (col.filterFn.name ?? 'custom')
+            : (col.filterFn ??
+              initState.columnFilterFns?.[getColumnId(col)] ??
+              getDefaultColumnFilterFn(col)),
+      })),
+    );
+    initState.globalFilterFn = definedTableOptions.globalFilterFn ?? 'fuzzy';
+    return initState;
+  }, []);
+
+  definedTableOptions.initialState = initialState;
+
+  //MRT-owned state lives in the table store; the previous render's state feeds
+  //the option transforms below, falling back to the initial state on first render
+  const controlledState = definedTableOptions.state;
+  definedTableOptions.state = {
+    columnResizing: {} as MRT_ColumnResizingState,
+    creatingRow: null,
+    draggingColumn: null,
+    draggingRow: null,
+    grouping: [],
+    isLoading: false,
+    pagination: { pageIndex: 0, pageSize: 10 },
+    showSkeletons: false,
+    ...initialState,
+    ...tableRef.current?.state,
+    ...controlledState,
+  };
+
+  //The table options now include all state needed to help determine column visibility and order logic
+  const statefulTableOptions =
+    definedTableOptions as MRT_StatefulTableOptions<TData>;
+
+  //don't recompute columnDefs while resizing column or dragging column/row
+  const columnDefsRef = useRef<MRT_ColumnDef<TData>[]>([]);
+  statefulTableOptions.columns =
+    statefulTableOptions.state.columnResizing.isResizingColumn ||
+    statefulTableOptions.state.draggingColumn ||
+    statefulTableOptions.state.draggingRow
+      ? columnDefsRef.current
+      : prepareColumns({
+          columnDefs: [
+            ...([
+              showRowPinningColumn(statefulTableOptions) &&
+                getMRT_RowPinningColumnDef(statefulTableOptions),
+              showRowDragColumn(statefulTableOptions) &&
+                getMRT_RowDragColumnDef(statefulTableOptions),
+              showRowActionsColumn(statefulTableOptions) &&
+                getMRT_RowActionsColumnDef(statefulTableOptions),
+              showRowExpandColumn(statefulTableOptions) &&
+                getMRT_RowExpandColumnDef(statefulTableOptions),
+              showRowSelectionColumn(statefulTableOptions) &&
+                getMRT_RowSelectColumnDef(statefulTableOptions),
+              showRowNumbersColumn(statefulTableOptions) &&
+                getMRT_RowNumbersColumnDef(statefulTableOptions),
+            ].filter(Boolean) as MRT_ColumnDef<TData>[]),
+            ...statefulTableOptions.columns,
+            ...([
+              showRowSpacerColumn(statefulTableOptions) &&
+                getMRT_RowSpacerColumnDef(statefulTableOptions),
+            ].filter(Boolean) as MRT_ColumnDef<TData>[]),
+          ],
+          tableOptions: statefulTableOptions,
+        });
+  columnDefsRef.current = statefulTableOptions.columns;
+
+  //if loading, generate blank rows to show skeleton loaders
+  statefulTableOptions.data = useMemo(
+    () =>
+      (statefulTableOptions.state.isLoading ||
+        statefulTableOptions.state.showSkeletons) &&
+      !statefulTableOptions.data.length
+        ? [
+            ...Array(
+              Math.min(statefulTableOptions.state.pagination.pageSize, 20),
+            ).fill(null),
+          ].map(() =>
+            Object.assign(
+              {},
+              ...getAllLeafColumnDefs(statefulTableOptions.columns).map(
+                (col) => ({
+                  [getColumnId(col)]: null,
+                }),
+              ),
+            ),
+          )
+        : statefulTableOptions.data,
+    [
+      statefulTableOptions.data,
+      statefulTableOptions.state.isLoading,
+      statefulTableOptions.state.showSkeletons,
+    ],
+  );
+
+  //only the user's own `state` option controls slices; the merged copy above
+  //is for the transforms and must not be passed to the table
+  const { state, ...tableOptions } = statefulTableOptions;
+  const table = useTable({
+    ...tableOptions,
+    features: tableOptions.enableFacetedValues
+      ? mrtFeatures
+      : mrtFeaturesWithoutFacetedValues,
+    globalFilterFn: state.globalFilterFn ?? 'fuzzy',
+    state: controlledState,
+  } as any) as unknown as MRT_TableInstance<TData>;
+
+  tableRef.current = table;
+
+  useMRT_Effects(table);
+
+  return table;
+};