@lminii/material-react-table 4.0.0

package/skills/virtualization/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: virtualization
+description: >
+  Render thousands of rows or hundreds of columns in Material React Table V4 with enableRowVirtualization and enableColumnVirtualization, tune rowVirtualizerOptions and columnVirtualizerOptions (overscan, estimateSize), reach the TanStack Virtual instance through rowVirtualizerInstanceRef for scrollToIndex, and understand the automatic layoutMode grid and sticky header. Load for large unpaginated tables, infinite scroll, scroll-to-row, jumpy scrolling, or headless virtualization with useMRT_RowVirtualizer.
+metadata:
+  type: framework
+  library: '@lminii/material-react-table'
+  library_version: '4.0.0'
+  framework: react
+requires:
+  - getting-started
+sources:
+  - 'lminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/virtualization.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/examples/enable-row-virtualization/sandbox/src/TS.tsx'
+  - 'lminii/material-react-table:packages/material-react-table/src/hooks/useMRT_RowVirtualizer.ts'
+  - 'lminii/material-react-table:packages/material-react-table/src/hooks/useMRT_TableOptions.ts'
+  - 'lminii/material-react-table:packages/material-react-table/src/types.ts'
+---
+
+This skill builds on `getting-started`. MRT wraps `@tanstack/react-virtual` so only the rows and columns inside the scroll container render. Enable it when a table shows more than about 50 rows without pagination or more than about a dozen columns; below that it adds overhead without benefit.
+
+## Setup
+
+```tsx
+const table = useMaterialReactTable({
+  columns,
+  data, // 10,000 rows
+  enablePagination: false,
+  enableRowVirtualization: true,
+  enableColumnVirtualization: true, // only with many columns
+  muiTableContainerProps: { sx: { maxHeight: '600px' } },
+  rowVirtualizerOptions: { overscan: 5 },
+  columnVirtualizerOptions: { overscan: 2 },
+})
+```
+
+Row virtualization sets `enableStickyHeader` to true and, unless `layoutMode` was given, switches `layoutMode` to `'grid'`, so the table renders with CSS grid and flexbox instead of semantic table layout. The container needs a bounded height for scrolling; the sticky header default caps it at 100vh, and `muiTableContainerProps.sx.maxHeight` sets a tighter one.
+
+## Core Patterns
+
+### Tune the virtualizer
+
+```tsx
+rowVirtualizerOptions: ({ table }) => ({
+  overscan: 10,
+  estimateSize: () => (table.getState().density === 'compact' ? 37 : 73),
+}),
+columnVirtualizerOptions: { overscan: 3, estimateSize: () => 200 },
+```
+
+Both options accept an object or a callback receiving `table`, and both are `Partial<VirtualizerOptions>` from TanStack Virtual. MRT already estimates row height from the density (37, 58, or 73 px) and measures rendered rows, sets `overscan: 4`, and keeps a dragging row mounted; anything you pass merges over those defaults. Raise `overscan` if fast scrolling shows blank rows, and set `estimateSize` when rows or columns are far from the defaults so the scrollbar length is accurate.
+
+### Reach the virtualizer instance
+
+```tsx
+const rowVirtualizerInstanceRef = useRef<MRT_RowVirtualizer>(null)
+const [sorting, setSorting] = useState<MRT_SortingState>([])
+
+useEffect(() => {
+  rowVirtualizerInstanceRef.current?.scrollToIndex?.(0) // back to top when sorting changes
+}, [sorting])
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enablePagination: false,
+  enableRowVirtualization: true,
+  rowVirtualizerInstanceRef,
+  state: { sorting },
+  onSortingChange: setSorting,
+})
+```
+
+`MRT_RowVirtualizer` and `MRT_ColumnVirtualizer` are the TanStack `Virtualizer` plus `virtualRows` or `virtualColumns`, so `scrollToIndex`, `scrollToOffset`, `measure`, and `getVirtualItems` are available. `columnVirtualizerInstanceRef` is the column counterpart.
+
+### Infinite scroll on the container
+
+```tsx
+const tableContainerRef = useRef<HTMLDivElement>(null)
+
+const table = useMaterialReactTable({
+  columns,
+  data: flatRows,
+  enablePagination: false,
+  enableRowVirtualization: true,
+  manualFiltering: true,
+  manualSorting: true,
+  muiTableContainerProps: {
+    ref: tableContainerRef,
+    sx: { maxHeight: '600px' },
+    onScroll: (event) => {
+      const { scrollHeight, scrollTop, clientHeight } = event.currentTarget
+      if (scrollHeight - scrollTop - clientHeight < 400 && !isFetching && hasNextPage) fetchNextPage()
+    },
+  },
+  renderBottomToolbarCustomActions: () => <Typography>Fetched {flatRows.length} of {totalRowCount} rows</Typography>,
+  state: { isLoading, showProgressBars: isFetching },
+})
+```
+
+Virtualization keeps the DOM small while the fetched array grows. Server-side sorting and filtering options are covered in `state-and-server-data`.
+
+### Headless virtualization
+
+```tsx
+import { useMRT_Rows, useMRT_RowVirtualizer, useMRT_ColumnVirtualizer } from '@lminii/material-react-table'
+
+const rows = useMRT_Rows(table)
+const rowVirtualizer = useMRT_RowVirtualizer(table)
+const columnVirtualizer = useMRT_ColumnVirtualizer(table)
+
+rowVirtualizer?.virtualRows.map((virtualRow) => {
+  const row = rows[virtualRow.index]
+  return <MyRow key={row.id} row={row} style={{ transform: `translateY(${virtualRow.start}px)` }} />
+})
+```
+
+The hooks return `undefined` when the matching `enable*Virtualization` option is off. They read the scroll element from `table.refs.tableContainerRef`, so a custom layout must attach that ref to its scroll container.
+
+## Common Mistakes
+
+### HIGH Enabling virtualization conditionally
+
+Wrong:
+
+```tsx
+enableRowVirtualization: data.length > 100,
+```
+
+Correct:
+
+```tsx
+enableRowVirtualization: true, // decide once per table, not per render
+```
+
+The virtualizer hooks run only when enabled, so toggling the option at runtime changes the hook order and breaks React's rules of hooks; it also flips `layoutMode`, which re-lays out every cell.
+
+Source: `docs/guides/virtualization.mdx`
+
+### HIGH Leaving pagination on
+
+Wrong:
+
+```tsx
+enableRowVirtualization: true,
+```
+
+Correct:
+
+```tsx
+enableRowVirtualization: true,
+enablePagination: false,
+```
+
+With pagination on, only one page of rows exists to virtualize, so the table still renders 10 rows and the user pages through 10,000.
+
+Source: `docs/guides/virtualization.mdx`
+
+### MEDIUM Expecting semantic table CSS to keep working
+
+Wrong:
+
+```tsx
+enableRowVirtualization: true,
+muiTableBodyCellProps: { sx: { width: '20%' } }, // percentage widths ignored in grid layout
+```
+
+Correct:
+
+```tsx
+enableRowVirtualization: true,
+columns: [{ accessorKey: 'email', header: 'Email', size: 300, grow: false }],
+```
+
+Virtualization forces `layoutMode: 'grid'`, where column widths come from `size`, `minSize`, `maxSize`, and `grow`, not from table-layout CSS.
+
+Source: `packages/material-react-table/src/hooks/useMRT_TableOptions.ts`
+
+### MEDIUM Detail panels with a fixed row estimate
+
+Wrong:
+
+```tsx
+enableRowVirtualization: true,
+renderDetailPanel: ({ row }) => <Details row={row} />,
+rowVirtualizerOptions: { estimateSize: () => 50 },
+```
+
+Correct:
+
+```tsx
+enableRowVirtualization: true,
+renderDetailPanel: ({ row }) => <Details row={row} />,
+// keep MRT's estimate: it counts two virtual items per row and sizes the panel item from the expanded state
+```
+
+With a detail panel MRT virtualizes two items per row (row and panel) and estimates the panel at 0 or 100 px depending on expansion. A flat `estimateSize` breaks the scrollbar and item positions.
+
+Source: `packages/material-react-table/src/hooks/useMRT_RowVirtualizer.ts`
+
+## API Discovery
+
+Search `node_modules/@lminii/material-react-table/dist/index.d.ts` for `Virtualizer` to find `MRT_RowVirtualizer`, `MRT_ColumnVirtualizer`, `MRT_VirtualizerOptions`, and `MRT_VirtualItem`. The TanStack Virtual docs at `https://tanstack.com/virtual/v3/docs/api/virtualizer` list every option and instance method. The Virtualization guide at `/docs/guides/virtualization` and the examples `/docs/examples/virtualized`, `enable-row-virtualization`, `enable-column-virtualization`, `enable-detail-panel-virtualized`, and `infinite-scrolling` show the patterns above.

package/src/components/MaterialReactTable.tsx

@@ -0,0 +1,36 @@
+import { MRT_TablePaper } from './table/MRT_TablePaper';
+import { useMaterialReactTable } from '../hooks/useMaterialReactTable';
+import {
+  type MRT_RowData,
+  type MRT_TableInstance,
+  type MRT_TableOptions,
+  type Xor,
+} from '../types';
+
+export type MaterialReactTableProps<TData extends MRT_RowData> = Xor<
+  TableInstanceProp<TData>,
+  MRT_TableOptions<TData>
+>;
+
+type TableInstanceProp<TData extends MRT_RowData> = {
+  table: MRT_TableInstance<TData>;
+};
+
+const isTableInstanceProp = <TData extends MRT_RowData>(
+  props: MaterialReactTableProps<TData>,
+): props is TableInstanceProp<TData> =>
+  (props as TableInstanceProp<TData>).table !== undefined;
+
+export const MaterialReactTable = <TData extends MRT_RowData>(
+  props: MaterialReactTableProps<TData>,
+) => {
+  let table: MRT_TableInstance<TData>;
+
+  if (isTableInstanceProp(props)) {
+    table = props.table;
+  } else {
+    table = useMaterialReactTable(props);
+  }
+
+  return <MRT_TablePaper table={table} />;
+};

package/src/components/body/MRT_TableBody.tsx

@@ -0,0 +1,221 @@
+import { memo, useMemo } from 'react';
+import { type VirtualItem } from '@tanstack/react-virtual';
+import TableBody, { type TableBodyProps } from '@mui/material/TableBody';
+import Typography from '@mui/material/Typography';
+import { useMRT_Rows } from '../../hooks/useMRT_Rows';
+import { useMRT_RowVirtualizer } from '../../hooks/useMRT_RowVirtualizer';
+import { Memo_MRT_TableBodyRow, MRT_TableBodyRow } from './MRT_TableBodyRow';
+import {
+  type MRT_ColumnVirtualizer,
+  type MRT_Row,
+  type MRT_RowData,
+  type MRT_TableInstance,
+} from '../../types';
+import { parseFromValuesOrFunc } from '../../utils/utils';
+
+export interface MRT_TableBodyProps<TData extends MRT_RowData>
+  extends TableBodyProps {
+  columnVirtualizer?: MRT_ColumnVirtualizer;
+  table: MRT_TableInstance<TData>;
+}
+
+export const MRT_TableBody = <TData extends MRT_RowData>({
+  columnVirtualizer,
+  table,
+  ...rest
+}: MRT_TableBodyProps<TData>) => {
+  const {
+    getBottomRows,
+    getIsSomeRowsPinned,
+    getRowModel,
+    getTopRows,
+    options: {
+      enableStickyFooter,
+      enableStickyHeader,
+      layoutMode,
+      localization,
+      memoMode,
+      muiTableBodyProps,
+      renderDetailPanel,
+      renderEmptyRowsFallback,
+      rowPinningDisplayMode,
+    },
+    refs: { tableFooterRef, tableHeadRef, tablePaperRef },
+    state,
+  } = table;
+  const { columnFilters, globalFilter, isFullScreen, rowPinning } = state;
+
+  const tableBodyProps = {
+    ...parseFromValuesOrFunc(muiTableBodyProps, { table }),
+    ...rest,
+  };
+
+  const tableHeadHeight =
+    ((enableStickyHeader || isFullScreen) &&
+      tableHeadRef.current?.clientHeight) ||
+    0;
+  const tableFooterHeight =
+    (enableStickyFooter && tableFooterRef.current?.clientHeight) || 0;
+
+  const pinnedRowIds = useMemo(() => {
+    if (!rowPinning.bottom?.length && !rowPinning.top?.length) return [];
+    return getRowModel()
+      .rows.filter((row) => row.getIsPinned())
+      .map((r) => r.id);
+  }, [rowPinning, getRowModel().rows]);
+
+  const rows = useMRT_Rows(table);
+
+  const rowVirtualizer = useMRT_RowVirtualizer(table, rows);
+
+  const { virtualRows } = rowVirtualizer ?? {};
+
+  const commonRowProps = {
+    columnVirtualizer,
+    numRows: rows.length,
+    table,
+  };
+
+  return (
+    <>
+      {!rowPinningDisplayMode?.includes('sticky') &&
+        getIsSomeRowsPinned('top') && (
+          <TableBody
+            {...tableBodyProps}
+            sx={(theme) => ({
+              display: layoutMode?.startsWith('grid') ? 'grid' : undefined,
+              position: 'sticky',
+              top: tableHeadHeight - 1,
+              zIndex: 1,
+              ...(parseFromValuesOrFunc(tableBodyProps?.sx, theme) as any),
+            })}
+          >
+            {getTopRows().map((row, staticRowIndex) => {
+              const props = {
+                ...commonRowProps,
+                row,
+                staticRowIndex,
+              };
+              return memoMode === 'rows' ? (
+                <Memo_MRT_TableBodyRow key={row.id} {...props} />
+              ) : (
+                <MRT_TableBodyRow key={row.id} {...props} />
+              );
+            })}
+          </TableBody>
+        )}
+      <TableBody
+        {...tableBodyProps}
+        sx={(theme) => ({
+          display: layoutMode?.startsWith('grid') ? 'grid' : undefined,
+          height: rowVirtualizer
+            ? `${rowVirtualizer.getTotalSize()}px`
+            : undefined,
+          minHeight: !rows.length ? '100px' : undefined,
+          position: 'relative',
+          ...(parseFromValuesOrFunc(tableBodyProps?.sx, theme) as any),
+        })}
+      >
+        {tableBodyProps?.children ??
+          (!rows.length ? (
+            <tr
+              style={{
+                display: layoutMode?.startsWith('grid') ? 'grid' : undefined,
+              }}
+            >
+              <td
+                colSpan={table.getVisibleLeafColumns().length}
+                style={{
+                  display: layoutMode?.startsWith('grid') ? 'grid' : undefined,
+                }}
+              >
+                {renderEmptyRowsFallback?.({ table }) ?? (
+                  <Typography
+                    sx={{
+                      color: 'text.secondary',
+                      fontStyle: 'italic',
+                      maxWidth: `min(100vw, ${
+                        tablePaperRef.current?.clientWidth ? tablePaperRef.current?.clientWidth + "px" : "100%"
+                      })`,
+                      py: '2rem',
+                      textAlign: 'center',
+                      width: '100%',
+                    }}
+                  >
+                    {globalFilter || columnFilters.length
+                      ? localization.noResultsFound
+                      : localization.noRecordsToDisplay}
+                  </Typography>
+                )}
+              </td>
+            </tr>
+          ) : (
+            <>
+              {(virtualRows ?? rows).map((rowOrVirtualRow, staticRowIndex) => {
+                let row = rowOrVirtualRow as MRT_Row<TData>;
+                if (rowVirtualizer) {
+                  if (renderDetailPanel) {
+                    if (rowOrVirtualRow.index % 2 === 1) {
+                      return null;
+                    } else {
+                      staticRowIndex = rowOrVirtualRow.index / 2;
+                    }
+                  } else {
+                    staticRowIndex = rowOrVirtualRow.index;
+                  }
+                  row = rows[staticRowIndex];
+                }
+                const props = {
+                  ...commonRowProps,
+                  pinnedRowIds,
+                  row,
+                  rowVirtualizer,
+                  staticRowIndex,
+                  virtualRow: rowVirtualizer
+                    ? (rowOrVirtualRow as VirtualItem)
+                    : undefined,
+                };
+                const key = `${row.id}-${row.index}`;
+                return memoMode === 'rows' ? (
+                  <Memo_MRT_TableBodyRow key={key} {...props} />
+                ) : (
+                  <MRT_TableBodyRow key={key} {...props} />
+                );
+              })}
+            </>
+          ))}
+      </TableBody>
+      {!rowPinningDisplayMode?.includes('sticky') &&
+        getIsSomeRowsPinned('bottom') && (
+          <TableBody
+            {...tableBodyProps}
+            sx={(theme) => ({
+              bottom: tableFooterHeight - 1,
+              display: layoutMode?.startsWith('grid') ? 'grid' : undefined,
+              position: 'sticky',
+              zIndex: 1,
+              ...(parseFromValuesOrFunc(tableBodyProps?.sx, theme) as any),
+            })}
+          >
+            {getBottomRows().map((row, staticRowIndex) => {
+              const props = {
+                ...commonRowProps,
+                row,
+                staticRowIndex,
+              };
+              return memoMode === 'rows' ? (
+                <Memo_MRT_TableBodyRow key={row.id} {...props} />
+              ) : (
+                <MRT_TableBodyRow key={row.id} {...props} />
+              );
+            })}
+          </TableBody>
+        )}
+    </>
+  );
+};
+
+export const Memo_MRT_TableBody = memo(
+  MRT_TableBody,
+  (prev, next) => prev.table.options.data === next.table.options.data,
+) as typeof MRT_TableBody;