material-react-table 3.0.0-beta.1 → 3.0.0-beta.2

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.2",
   "license": "MIT",
   "name": "material-react-table",
   "description": "A fully featured Material UI V6 implementation of TanStack React Table V8, written from the ground up in TypeScript.",

package/src/components/body/MRT_TableBodyCell.tsx

@@ -18,7 +18,7 @@ import {
 } from '../../types';
 import {
   isCellEditable,
-  cellNavigation,
+  cellKeyboardShortcuts,
   openEditingCell,
 } from '../../utils/cell.utils';
 import { getCommonMRTCellStyles } from '../../utils/style.utils';
@@ -58,7 +58,7 @@ export const MRT_TableBodyCell = <TData extends MRT_RowData>({
       enableColumnOrdering,
       enableColumnPinning,
       enableGrouping,
-      enableCellNavigation,
+      enableKeyboardShortcuts,
       layoutMode,
       mrtTheme: { draggingBorderColor },
       muiSkeletonProps,
@@ -233,14 +233,12 @@ export const MRT_TableBodyCell = <TData extends MRT_RowData>({
   };
 
   const handleKeyDown = (event: React.KeyboardEvent<HTMLTableCellElement>) => {
-    if (enableCellNavigation) {
-      cellNavigation({
-        cell,
-        cellValue: cell.getValue<string>(),
-        event,
-        table,
-      });
-    }
+    cellKeyboardShortcuts({
+      cell,
+      cellValue: cell.getValue<string>(),
+      event,
+      table,
+    });
     tableCellProps?.onKeyDown?.(event);
   };
 
@@ -249,7 +247,7 @@ export const MRT_TableBodyCell = <TData extends MRT_RowData>({
       align={theme.direction === 'rtl' ? 'right' : 'left'}
       data-index={staticColumnIndex}
       data-pinned={!!isColumnPinned || undefined}
-      tabIndex={enableCellNavigation ? 0 : undefined}
+      tabIndex={enableKeyboardShortcuts ? 0 : undefined}
       {...tableCellProps}
       onKeyDown={handleKeyDown}
       onContextMenu={handleContextMenu}

package/src/components/footer/MRT_TableFooterCell.tsx

@@ -7,7 +7,7 @@ import {
 } from '../../types';
 import { getCommonMRTCellStyles } from '../../utils/style.utils';
 import { parseFromValuesOrFunc } from '../../utils/utils';
-import { cellNavigation } from '../../utils/cell.utils';
+import { cellKeyboardShortcuts } from '../../utils/cell.utils';
 
 export interface MRT_TableFooterCellProps<TData extends MRT_RowData>
   extends TableCellProps {
@@ -28,7 +28,7 @@ export const MRT_TableFooterCell = <TData extends MRT_RowData>({
     options: {
       enableColumnPinning,
       muiTableFooterCellProps,
-      enableCellNavigation,
+      enableKeyboardShortcuts,
     },
   } = table;
   const { density } = getState();
@@ -49,13 +49,11 @@ export const MRT_TableFooterCell = <TData extends MRT_RowData>({
   };
 
   const handleKeyDown = (event: React.KeyboardEvent<HTMLTableCellElement>) => {
-    if (enableCellNavigation) {
-      cellNavigation({
-        event,
-        cellValue: footer.column.columnDef.footer,
-        table,
-      });
-    }
+    cellKeyboardShortcuts({
+      event,
+      cellValue: footer.column.columnDef.footer,
+      table,
+    });
     tableCellProps?.onKeyDown?.(event);
   };
 
@@ -71,6 +69,7 @@ export const MRT_TableFooterCell = <TData extends MRT_RowData>({
       colSpan={footer.colSpan}
       data-index={staticColumnIndex}
       data-pinned={!!isColumnPinned || undefined}
+      tabIndex={enableKeyboardShortcuts ? 0 : undefined}
       variant="footer"
       {...tableCellProps}
       onKeyDown={handleKeyDown}

package/src/components/head/MRT_TableHeadCell.tsx

@@ -17,7 +17,7 @@ import {
 } from '../../types';
 import { getCommonMRTCellStyles } from '../../utils/style.utils';
 import { parseFromValuesOrFunc } from '../../utils/utils';
-import { cellNavigation } from '../../utils/cell.utils';
+import { cellKeyboardShortcuts } from '../../utils/cell.utils';
 
 export interface MRT_TableHeadCellProps<TData extends MRT_RowData>
   extends TableCellProps {
@@ -41,12 +41,12 @@ export const MRT_TableHeadCell = <TData extends MRT_RowData>({
       columnFilterDisplayMode,
       columnResizeDirection,
       columnResizeMode,
+      enableKeyboardShortcuts,
       enableColumnActions,
       enableColumnDragging,
       enableColumnOrdering,
       enableColumnPinning,
       enableGrouping,
-      enableCellNavigation,
       enableMultiSort,
       layoutMode,
       mrtTheme: { draggingBorderColor },
@@ -150,14 +150,13 @@ export const MRT_TableHeadCell = <TData extends MRT_RowData>({
   };
 
   const handleKeyDown = (event: React.KeyboardEvent<HTMLTableCellElement>) => {
-    if (enableCellNavigation) {
-      cellNavigation({
-        event,
-        cellValue: header.column.columnDef.header,
-        table,
-        header,
-      });
-    }
+    cellKeyboardShortcuts({
+      event,
+      cellValue: header.column.columnDef.header,
+      table,
+      header,
+    });
+
     tableCellProps?.onKeyDown?.(event);
   };
 
@@ -199,7 +198,7 @@ export const MRT_TableHeadCell = <TData extends MRT_RowData>({
           }
         }
       }}
-      tabIndex={enableCellNavigation ? 0 : undefined}
+      tabIndex={enableKeyboardShortcuts ? 0 : undefined}
       {...tableCellProps}
       onKeyDown={handleKeyDown}
       sx={(theme: Theme) => ({

package/src/hooks/useMRT_TableOptions.ts

@@ -76,7 +76,7 @@ export const useMRT_TableOptions: <TData extends MRT_RowData>(
   enableGlobalFilterRankedResults = true,
   enableGrouping = false,
   enableHiding = true,
-  enableCellNavigation = true,
+  enableKeyboardShortcuts = true,
   enableMultiRowSelection = true,
   enableMultiSort = true,
   enablePagination = true,
@@ -204,7 +204,7 @@ export const useMRT_TableOptions: <TData extends MRT_RowData>(
     enableGlobalFilterRankedResults,
     enableGrouping,
     enableHiding,
-    enableCellNavigation,
+    enableKeyboardShortcuts,
     enableMultiRowSelection,
     enableMultiSort,
     enablePagination,

package/src/types.ts

@@ -184,9 +184,10 @@ export interface MRT_Localization {
   filterFuzzy: string;
   filterGreaterThan: string;
   filterGreaterThanOrEqualTo: string;
-  filterInNumberRange: string;
   filterIncludesString: string;
   filterIncludesStringSensitive: string;
+  filteringByColumn: string;
+  filterInNumberRange: string;
   filterLessThan: string;
   filterLessThanOrEqualTo: string;
   filterMode: string;
@@ -194,7 +195,6 @@ export interface MRT_Localization {
   filterNotEquals: string;
   filterStartsWith: string;
   filterWeakEquals: string;
-  filteringByColumn: string;
   goToFirstPage: string;
   goToLastPage: string;
   goToNextPage: string;
@@ -412,6 +412,22 @@ export interface MRT_ColumnDef<TData extends MRT_RowData, TValue = unknown>
     | 'id'
     | 'sortingFn'
   > {
+  /**
+   * Either an `accessorKey` or a combination of an `accessorFn` and `id` are required for a data column definition.
+   * Specify a function here to point to the correct property in the data object.
+   *
+   * @example accessorFn: (row) => row.username
+   */
+  accessorFn?: (originalRow: TData) => TValue;
+  /**
+   * Either an `accessorKey` or a combination of an `accessorFn` and `id` are required for a data column definition.
+   * Specify which key in the row this column should use to access the correct data.
+   * Also supports Deep Key Dot Notation.
+   *
+   * @example accessorKey: 'username' //simple
+   * @example accessorKey: 'name.firstName' //deep key dot notation
+   */
+  accessorKey?: DeepKeys<TData> | (string & {});
   AggregatedCell?: (props: {
     cell: MRT_Cell<TData, TValue>;
     column: MRT_Column<TData, TValue>;
@@ -420,6 +436,7 @@ export interface MRT_ColumnDef<TData extends MRT_RowData, TValue = unknown>
     staticColumnIndex?: number;
     staticRowIndex?: number;
   }) => ReactNode;
+  aggregationFn?: Array<MRT_AggregationFn<TData>> | MRT_AggregationFn<TData>;
   Cell?: (props: {
     cell: MRT_Cell<TData, TValue>;
     column: MRT_Column<TData, TValue>;
@@ -430,63 +447,6 @@ export interface MRT_ColumnDef<TData extends MRT_RowData, TValue = unknown>
     staticRowIndex?: number;
     table: MRT_TableInstance<TData>;
   }) => ReactNode;
-  Edit?: (props: {
-    cell: MRT_Cell<TData, TValue>;
-    column: MRT_Column<TData, TValue>;
-    row: MRT_Row<TData>;
-    table: MRT_TableInstance<TData>;
-  }) => ReactNode;
-  Filter?: (props: {
-    column: MRT_Column<TData, TValue>;
-    header: MRT_Header<TData>;
-    rangeFilterIndex?: number;
-    table: MRT_TableInstance<TData>;
-  }) => ReactNode;
-  Footer?:
-    | ((props: {
-        column: MRT_Column<TData, TValue>;
-        footer: MRT_Header<TData>;
-        table: MRT_TableInstance<TData>;
-      }) => ReactNode)
-    | ReactNode;
-  GroupedCell?: (props: {
-    cell: MRT_Cell<TData, TValue>;
-    column: MRT_Column<TData, TValue>;
-    row: MRT_Row<TData>;
-    table: MRT_TableInstance<TData>;
-    staticColumnIndex?: number;
-    staticRowIndex?: number;
-  }) => ReactNode;
-  Header?:
-    | ((props: {
-        column: MRT_Column<TData, TValue>;
-        header: MRT_Header<TData>;
-        table: MRT_TableInstance<TData>;
-      }) => ReactNode)
-    | ReactNode;
-  PlaceholderCell?: (props: {
-    cell: MRT_Cell<TData, TValue>;
-    column: MRT_Column<TData, TValue>;
-    row: MRT_Row<TData>;
-    table: MRT_TableInstance<TData>;
-  }) => ReactNode;
-  /**
-   * Either an `accessorKey` or a combination of an `accessorFn` and `id` are required for a data column definition.
-   * Specify a function here to point to the correct property in the data object.
-   *
-   * @example accessorFn: (row) => row.username
-   */
-  accessorFn?: (originalRow: TData) => TValue;
-  /**
-   * Either an `accessorKey` or a combination of an `accessorFn` and `id` are required for a data column definition.
-   * Specify which key in the row this column should use to access the correct data.
-   * Also supports Deep Key Dot Notation.
-   *
-   * @example accessorKey: 'username' //simple
-   * @example accessorKey: 'name.firstName' //deep key dot notation
-   */
-  accessorKey?: DeepKeys<TData> | (string & {});
-  aggregationFn?: Array<MRT_AggregationFn<TData>> | MRT_AggregationFn<TData>;
   /**
    * Specify what type of column this is. Either `data`, `display`, or `group`. Defaults to `data`.
    * Leave this blank if you are just creating a normal data column.
@@ -500,6 +460,12 @@ export interface MRT_ColumnDef<TData extends MRT_RowData, TValue = unknown>
     LiteralUnion<string & MRT_FilterOption>
   > | null;
   columns?: MRT_ColumnDef<TData, TValue>[];
+  Edit?: (props: {
+    cell: MRT_Cell<TData, TValue>;
+    column: MRT_Column<TData, TValue>;
+    row: MRT_Row<TData>;
+    table: MRT_TableInstance<TData>;
+  }) => ReactNode;
   editSelectOptions?:
     | ((props: {
         cell: MRT_Cell<TData, TValue>;
@@ -519,6 +485,12 @@ export interface MRT_ColumnDef<TData extends MRT_RowData, TValue = unknown>
   enableColumnOrdering?: boolean;
   enableEditing?: ((row: MRT_Row<TData>) => boolean) | boolean;
   enableFilterMatchHighlighting?: boolean;
+  Filter?: (props: {
+    column: MRT_Column<TData, TValue>;
+    header: MRT_Header<TData>;
+    rangeFilterIndex?: number;
+    table: MRT_TableInstance<TData>;
+  }) => ReactNode;
   filterFn?: MRT_FilterFn<TData>;
   filterSelectOptions?: DropdownOption[];
   filterVariant?:
@@ -539,6 +511,21 @@ export interface MRT_ColumnDef<TData extends MRT_RowData, TValue = unknown>
    * footer must be a string. If you want custom JSX to render the footer, you can also specify a `Footer` option. (Capital F)
    */
   footer?: string;
+  Footer?:
+    | ((props: {
+        column: MRT_Column<TData, TValue>;
+        footer: MRT_Header<TData>;
+        table: MRT_TableInstance<TData>;
+      }) => ReactNode)
+    | ReactNode;
+  GroupedCell?: (props: {
+    cell: MRT_Cell<TData, TValue>;
+    column: MRT_Column<TData, TValue>;
+    row: MRT_Row<TData>;
+    table: MRT_TableInstance<TData>;
+    staticColumnIndex?: number;
+    staticRowIndex?: number;
+  }) => ReactNode;
   /**
    * If `layoutMode` is `'grid'` or `'grid-no-grow'`, you can specify the flex grow value for individual columns to still grow and take up remaining space, or set to `false`/0 to not grow.
    */
@@ -547,6 +534,13 @@ export interface MRT_ColumnDef<TData extends MRT_RowData, TValue = unknown>
    * header must be a string. If you want custom JSX to render the header, you can also specify a `Header` option. (Capital H)
    */
   header: string;
+  Header?:
+    | ((props: {
+        column: MRT_Column<TData, TValue>;
+        header: MRT_Header<TData>;
+        table: MRT_TableInstance<TData>;
+      }) => ReactNode)
+    | ReactNode;
   /**
    * Either an `accessorKey` or a combination of an `accessorFn` and `id` are required for a data column definition.
    *
@@ -651,6 +645,12 @@ export interface MRT_ColumnDef<TData extends MRT_RowData, TValue = unknown>
         table: MRT_TableInstance<TData>;
       }) => TableCellProps)
     | TableCellProps;
+  PlaceholderCell?: (props: {
+    cell: MRT_Cell<TData, TValue>;
+    column: MRT_Column<TData, TValue>;
+    row: MRT_Row<TData>;
+    table: MRT_TableInstance<TData>;
+  }) => ReactNode;
   renderCellActionMenuItems?: (props: {
     cell: MRT_Cell<TData>;
     closeMenu: () => void;
@@ -813,12 +813,6 @@ export interface MRT_TableOptions<TData extends MRT_RowData>
   columnFilterModeOptions?: Array<
     LiteralUnion<string & MRT_FilterOption>
   > | null;
-  columnVirtualizerInstanceRef?: MutableRefObject<MRT_ColumnVirtualizer | null>;
-  columnVirtualizerOptions?:
-    | ((props: {
-        table: MRT_TableInstance<TData>;
-      }) => Partial<VirtualizerOptions<HTMLDivElement, HTMLTableCellElement>>)
-    | Partial<VirtualizerOptions<HTMLDivElement, HTMLTableCellElement>>;
   /**
    * The columns to display in the table. `accessorKey`s or `accessorFn`s must match keys in the `data` table option.
    *
@@ -830,6 +824,12 @@ export interface MRT_TableOptions<TData extends MRT_RowData>
    * @link https://www.material-react-table.com/docs/api/column-options
    */
   columns: MRT_ColumnDef<TData, any>[];
+  columnVirtualizerInstanceRef?: MutableRefObject<MRT_ColumnVirtualizer | null>;
+  columnVirtualizerOptions?:
+    | ((props: {
+        table: MRT_TableInstance<TData>;
+      }) => Partial<VirtualizerOptions<HTMLDivElement, HTMLTableCellElement>>)
+    | Partial<VirtualizerOptions<HTMLDivElement, HTMLTableCellElement>>;
   createDisplayMode?: 'custom' | 'modal' | 'row';
   /**
    * Pass your data as an array of objects. Objects can theoretically be any shape, but it's best to keep them consistent.
@@ -870,7 +870,7 @@ export interface MRT_TableOptions<TData extends MRT_RowData>
   enableFullScreenToggle?: boolean;
   enableGlobalFilterModes?: boolean;
   enableGlobalFilterRankedResults?: boolean;
-  enableCellNavigation?: boolean;
+  enableKeyboardShortcuts?: boolean;
   enablePagination?: boolean;
   enableRowActions?: boolean;
   enableRowDragging?: boolean;

package/src/utils/cell.utils.ts

@@ -10,6 +10,13 @@ import {
 } from './row.utils';
 import { parseFromValuesOrFunc } from './utils';
 
+const isWinCtrlMacMeta = (event: React.KeyboardEvent<HTMLTableCellElement>) => {
+  return (
+    (event.ctrlKey && navigator.platform.toLowerCase().includes('win')) ||
+    (event.metaKey && navigator.platform.toLowerCase().includes('mac'))
+  );
+};
+
 export const isCellEditable = <TData extends MRT_RowData>({
   cell,
   table,
@@ -54,7 +61,7 @@ export const openEditingCell = <TData extends MRT_RowData>({
   }
 };
 
-export const cellNavigation = <TData extends MRT_RowData = MRT_RowData>({
+export const cellKeyboardShortcuts = <TData extends MRT_RowData = MRT_RowData>({
   cell,
   cellElements,
   cellValue,
@@ -73,10 +80,14 @@ export const cellNavigation = <TData extends MRT_RowData = MRT_RowData>({
   parentElement?: HTMLTableRowElement;
   table: MRT_TableInstance<TData>;
 }) => {
-  if (cellValue && (event.ctrlKey || event.metaKey) && event.key === 'c') {
+  if (!table.options.enableKeyboardShortcuts) return;
+  const currentCell = event.currentTarget;
+
+  if (cellValue && isWinCtrlMacMeta(event) && event.key === 'c') {
     navigator.clipboard.writeText(cellValue);
   } else if (['Enter', ' '].includes(event.key)) {
     if (cell?.column?.id === 'mrt-row-select') {
+      event.preventDefault();
       getMRT_RowSelectionHandler({
         row: cell.row,
         table,
@@ -87,6 +98,7 @@ export const cellNavigation = <TData extends MRT_RowData = MRT_RowData>({
       header?.column?.id === 'mrt-row-select' &&
       table.options.enableSelectAll
     ) {
+      event.preventDefault();
       getMRT_SelectAllHandler({
         table,
       })(event as any);
@@ -95,15 +107,16 @@ export const cellNavigation = <TData extends MRT_RowData = MRT_RowData>({
       (cell.row.getCanExpand() ||
         table.options.renderDetailPanel?.({ row: cell.row, table }))
     ) {
+      event.preventDefault();
       cell.row.toggleExpanded();
     } else if (
       header?.column?.id === 'mrt-row-expand' &&
       table.options.enableExpandAll
     ) {
+      event.preventDefault();
       table.toggleAllRowsExpanded();
-    } else if (header?.column?.getCanSort()) {
-      header.column.toggleSorting();
     } else if (cell?.column.id === 'mrt-row-pin') {
+      event.preventDefault();
       cell.row.getIsPinned()
         ? cell.row.pin(false)
         : cell.row.pin(
@@ -111,16 +124,32 @@ export const cellNavigation = <TData extends MRT_RowData = MRT_RowData>({
               ? 'bottom'
               : 'top',
           );
+    } else if (header && isWinCtrlMacMeta(event)) {
+      const actionsButton = currentCell.querySelector(
+        `button[aria-label="${table.options.localization.columnActions}"]`,
+      );
+      if (actionsButton) {
+        (actionsButton as HTMLButtonElement).click();
+      }
+    } else if (header?.column?.getCanSort()) {
+      event.preventDefault();
+      header.column.toggleSorting();
     }
   } else if (
-    ['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown', 'Home', 'End'].includes(
-      event.key,
-    )
+    [
+      'ArrowRight',
+      'ArrowLeft',
+      'ArrowUp',
+      'ArrowDown',
+      'Home',
+      'End',
+      'PageUp',
+      'PageDown',
+    ].includes(event.key)
   ) {
     event.preventDefault();
-    const currentCell = event.currentTarget;
-    const currentRow = parentElement || currentCell.closest('tr');
 
+    const currentRow = parentElement || currentCell.closest('tr');
     const tableElement = containerElement || currentCell.closest('table');
     const allCells =
       cellElements ||
@@ -146,6 +175,17 @@ export const cellNavigation = <TData extends MRT_RowData = MRT_RowData>({
       return targetCell as HTMLElement;
     };
 
+    //page up/down first or last cell in column
+    const findBottomTopCell = (columnIndex: number, edge: 'b' | 't') => {
+      const row =
+        edge === 't'
+          ? tableElement?.querySelector('tr')
+          : tableElement?.lastElementChild?.lastElementChild;
+      const rowCells = Array.from(row?.children || []);
+      const targetCell = rowCells[columnIndex];
+      return targetCell as HTMLElement;
+    };
+
     const findAdjacentCell = (
       columnIndex: number,
       searchDirection: 'f' | 'b',
@@ -173,10 +213,16 @@ export const cellNavigation = <TData extends MRT_RowData = MRT_RowData>({
         nextCell = findAdjacentCell(currentIndex, 'f');
         break;
       case 'Home':
-        nextCell = findEdgeCell(event.ctrlKey ? 'f' : 'c', 'f');
+        nextCell = findEdgeCell(isWinCtrlMacMeta(event) ? 'f' : 'c', 'f');
         break;
       case 'End':
-        nextCell = findEdgeCell(event.ctrlKey ? 'l' : 'c', 'l');
+        nextCell = findEdgeCell(isWinCtrlMacMeta(event) ? 'l' : 'c', 'l');
+        break;
+      case 'PageUp':
+        nextCell = findBottomTopCell(currentIndex, 't');
+        break;
+      case 'PageDown':
+        nextCell = findBottomTopCell(currentIndex, 'b');
         break;
     }