@careharmony/mantine-react-table-ng 0.0.0-stage → 4.0.0-beta.0

package/src/hooks/useMRT_TableOptions.ts

@@ -0,0 +1,300 @@
+'use no memo';
+
+import { useMemo } from 'react';
+
+import {
+  type Column,
+  getCoreRowModel,
+  getExpandedRowModel,
+  getFacetedMinMaxValues,
+  getFacetedRowModel,
+  getFacetedUniqueValues,
+  getFilteredRowModel,
+  getGroupedRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+} from '@tanstack/react-table';
+
+import { useDirection } from '@mantine/core';
+
+import { MRT_AggregationFns } from '../fns/aggregationFns';
+import { MRT_FilterFns } from '../fns/filterFns';
+import { MRT_SortingFns } from '../fns/sortingFns';
+import { MRT_Default_Icons } from '../icons';
+import { MRT_Localization_EN } from '../locales/en';
+import {
+  type MRT_DefinedTableOptions,
+  type MRT_RowData,
+  type MRT_TableOptions,
+} from '../types';
+
+export const MRT_DefaultColumn = {
+  filterVariant: 'text',
+  maxSize: 1000,
+  minSize: 40,
+  size: 180,
+} as const;
+
+export const MRT_DefaultDisplayColumn = {
+  columnDefType: 'display',
+  enableClickToCopy: false,
+  enableColumnActions: false,
+  enableColumnDragging: false,
+  enableColumnFilter: false,
+  enableColumnOrdering: false,
+  enableEditing: false,
+  enableGlobalFilter: false,
+  enableGrouping: false,
+  enableHiding: false,
+  enableResizing: false,
+  enableSorting: false,
+} as const;
+
+const globalFilterValueCache = new WeakMap<object, Map<string, boolean>>();
+
+/**
+ * Finds the first row with a value in the column and checks that the value is
+ * a string or a number. The result is cached for each data array.
+ */
+const getColumnHasGlobalFilterValue = <TData extends MRT_RowData>(
+  data: TData[] | undefined,
+  column: Column<TData, unknown>,
+): boolean => {
+  if (!data?.length || !column.accessorFn) return false;
+  let cache = globalFilterValueCache.get(data);
+  if (!cache) {
+    cache = new Map();
+    globalFilterValueCache.set(data, cache);
+  }
+  let hasValue = cache.get(column.id);
+  if (hasValue === undefined) {
+    hasValue = false;
+    for (let index = 0; index < data.length; index++) {
+      const value = column.accessorFn(data[index], index);
+      if (value !== null && value !== undefined) {
+        hasValue = typeof value === 'string' || typeof value === 'number';
+        break;
+      }
+    }
+    cache.set(column.id, hasValue);
+  }
+  return hasValue;
+};
+
+export const useMRT_TableOptions: <TData extends MRT_RowData>(
+  tableOptions: MRT_TableOptions<TData>,
+) => MRT_DefinedTableOptions<TData> = <TData extends MRT_RowData>({
+  aggregationFns,
+  autoResetExpanded = false,
+  columnFilterDisplayMode = 'subheader',
+  columnResizeDirection,
+  columnResizeMode = 'onChange',
+  createDisplayMode = 'modal',
+  defaultColumn,
+  defaultDisplayColumn,
+  editDisplayMode = 'modal',
+  enableBatchRowSelection = true,
+  enableBottomToolbar = true,
+  enableColumnActions = true,
+  enableColumnFilters = true,
+  enableColumnOrdering = false,
+  enableColumnPinning = false,
+  enableColumnResizing = false,
+  enableColumnVirtualization,
+  enableDensityToggle = true,
+  enableExpandAll = true,
+  enableExpanding,
+  enableFacetedValues = false,
+  enableFilterMatchHighlighting = true,
+  enableFilters = true,
+  enableFullScreenToggle = true,
+  enableGlobalFilter = true,
+  enableGlobalFilterRankedResults = true,
+  enableGrouping = false,
+  enableHeaderActionsHoverReveal = false,
+  enableHiding = true,
+  enableMultiRowSelection = true,
+  enableMultiSort = true,
+  enablePagination = true,
+  enableRowPinning = false,
+  enableRowSelection = false,
+  enableRowVirtualization,
+  enableSelectAll = true,
+  enableSorting = true,
+  enableStickyHeader = false,
+  enableTableFooter = true,
+  enableTableHead = true,
+  enableToolbarInternalActions = true,
+  enableTopToolbar = true,
+  filterFns,
+  icons,
+  layoutMode,
+  localization,
+  manualFiltering,
+  manualGrouping,
+  manualPagination,
+  manualSorting,
+  paginationDisplayMode = 'default',
+  positionActionsColumn = 'first',
+  positionCreatingRow = 'top',
+  positionExpandColumn = 'first',
+  positionGlobalFilter = 'right',
+  positionPagination = 'bottom',
+  positionToolbarAlertBanner = 'top',
+  positionToolbarDropZone = 'top',
+  rowNumberDisplayMode = 'static',
+  rowPinningDisplayMode = 'sticky',
+  selectAllMode = 'page',
+  sortingFns,
+  ...rest
+}: MRT_TableOptions<TData>) => {
+  const direction = useDirection();
+
+  icons = useMemo(() => ({ ...MRT_Default_Icons, ...icons }), [icons]);
+  localization = useMemo(
+    () => ({
+      ...MRT_Localization_EN,
+      ...localization,
+    }),
+    [localization],
+  );
+  aggregationFns = useMemo(
+    () => ({ ...MRT_AggregationFns, ...aggregationFns }),
+    [],
+  );
+  filterFns = useMemo(() => ({ ...MRT_FilterFns, ...filterFns }), []);
+  sortingFns = useMemo(() => ({ ...MRT_SortingFns, ...sortingFns }), []);
+  defaultColumn = useMemo(
+    () => ({ ...MRT_DefaultColumn, ...defaultColumn }),
+    [defaultColumn],
+  );
+  defaultDisplayColumn = useMemo(
+    () => ({
+      ...MRT_DefaultDisplayColumn,
+      ...defaultDisplayColumn,
+    }),
+    [defaultDisplayColumn],
+  );
+  //cannot be changed after initialization
+  [enableColumnVirtualization, enableRowVirtualization] = useMemo(
+    () => [enableColumnVirtualization, enableRowVirtualization],
+    [],
+  );
+
+  if (!columnResizeDirection) {
+    columnResizeDirection = direction.dir || 'ltr';
+  }
+
+  layoutMode =
+    layoutMode || (enableColumnResizing ? 'grid-no-grow' : 'semantic');
+  if (
+    layoutMode === 'semantic' &&
+    (enableRowVirtualization || enableColumnVirtualization)
+  ) {
+    layoutMode = 'grid';
+  }
+
+  if (enableRowVirtualization) {
+    enableStickyHeader = true;
+  }
+
+  if (enablePagination === false && manualPagination === undefined) {
+    manualPagination = true;
+  }
+
+  if (!rest.data?.length) {
+    manualFiltering = true;
+    manualGrouping = true;
+    manualPagination = true;
+    manualSorting = true;
+  }
+
+  return {
+    aggregationFns,
+    autoResetExpanded,
+    columnFilterDisplayMode,
+    columnResizeDirection,
+    columnResizeMode,
+    createDisplayMode,
+    defaultColumn,
+    defaultDisplayColumn,
+    editDisplayMode,
+    enableBatchRowSelection,
+    enableBottomToolbar,
+    enableColumnActions,
+    enableColumnFilters,
+    enableColumnOrdering,
+    enableColumnPinning,
+    enableColumnResizing,
+    enableColumnVirtualization,
+    enableDensityToggle,
+    enableExpandAll,
+    enableExpanding,
+    enableFacetedValues,
+    enableFilterMatchHighlighting,
+    enableFilters,
+    enableFullScreenToggle,
+    enableGlobalFilter,
+    enableGlobalFilterRankedResults,
+    enableGrouping,
+    enableHeaderActionsHoverReveal,
+    enableHiding,
+    enableMultiRowSelection,
+    enableMultiSort,
+    enablePagination,
+    enableRowPinning,
+    enableRowSelection,
+    enableRowVirtualization,
+    enableSelectAll,
+    enableSorting,
+    enableStickyHeader,
+    enableTableFooter,
+    enableTableHead,
+    enableToolbarInternalActions,
+    enableTopToolbar,
+    filterFns,
+    //TanStack only checks the value in the first row, so a null there removes the column from the global filter
+    getColumnCanGlobalFilter: (column) =>
+      getColumnHasGlobalFilterValue(rest.data, column),
+    getCoreRowModel: getCoreRowModel(),
+    getExpandedRowModel:
+      enableExpanding || enableGrouping ? getExpandedRowModel() : undefined,
+    getFacetedMinMaxValues: enableFacetedValues
+      ? getFacetedMinMaxValues()
+      : undefined,
+    getFacetedRowModel: enableFacetedValues ? getFacetedRowModel() : undefined,
+    getFacetedUniqueValues: enableFacetedValues
+      ? getFacetedUniqueValues()
+      : undefined,
+    getFilteredRowModel:
+      enableColumnFilters || enableGlobalFilter || enableFilters
+        ? getFilteredRowModel()
+        : undefined,
+    getGroupedRowModel: enableGrouping ? getGroupedRowModel() : undefined,
+    getPaginationRowModel: enablePagination
+      ? getPaginationRowModel()
+      : undefined,
+    getSortedRowModel: enableSorting ? getSortedRowModel() : undefined,
+    getSubRows: (row) => row?.subRows,
+    icons,
+    layoutMode,
+    localization,
+    manualFiltering,
+    manualGrouping,
+    manualPagination,
+    manualSorting,
+    paginationDisplayMode,
+    positionActionsColumn,
+    positionCreatingRow,
+    positionExpandColumn,
+    positionGlobalFilter,
+    positionPagination,
+    positionToolbarAlertBanner,
+    positionToolbarDropZone,
+    rowNumberDisplayMode,
+    rowPinningDisplayMode,
+    selectAllMode,
+    sortingFns,
+    ...rest,
+  } as MRT_DefinedTableOptions<TData>;
+};

package/src/hooks/useMRT_TableSnapshot.ts

@@ -0,0 +1,134 @@
+'use no memo';
+
+import { useRef } from 'react';
+
+import {
+  type MRT_RowData,
+  type MRT_TableInstance,
+  type MRT_TableOptions,
+} from '../types';
+import { createMRT_View } from '../utils/snapshot.utils';
+
+type Snapshot<TData extends MRT_RowData> = {
+  options: Record<string, unknown>;
+  state: Record<string, unknown>;
+  stateVersion: number;
+  table: MRT_TableInstance<TData>;
+  version: number;
+};
+
+//`state` and `initialState` are compared through `table.getState()` instead
+const ignoredOptionKeys = new Set(['initialState', 'state']);
+
+const isPlain = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return (
+    prototype === Object.prototype || prototype === null || Array.isArray(value)
+  );
+};
+
+/**
+ * Compares plain objects and arrays by content, `depth` levels deep, and
+ * everything else by identity. `table.setSorting([{ desc: false, id: 'name' }])`
+ * with the sorting that is already set makes a new array with the same content,
+ * and that must not count as a change.
+ */
+const isEqual = (a: unknown, b: unknown, depth: number): boolean => {
+  if (Object.is(a, b)) return true;
+  if (
+    !depth ||
+    !isPlain(a) ||
+    !isPlain(b) ||
+    Array.isArray(a) !== Array.isArray(b)
+  ) {
+    return false;
+  }
+  const keys = Object.keys(a);
+  return (
+    keys.length === Object.keys(b).length &&
+    keys.every((key) => key in b && isEqual(a[key], b[key], depth - 1))
+  );
+};
+
+/**
+ * Option objects such as `mantineTableProps={{ striped: true }}` compare by
+ * content. Arrays (`data`, `columns`) and functions compare by identity,
+ * because TanStack rebuilds rows and columns when their identity changes.
+ */
+const optionsEqual = (
+  a: Record<string, unknown>,
+  b: Record<string, unknown>,
+) => {
+  if (a === b) return true;
+  const keys = Object.keys(a);
+  return (
+    keys.length === Object.keys(b).length &&
+    keys.every(
+      (key) =>
+        key in b &&
+        (ignoredOptionKeys.has(key) ||
+          isEqual(a[key], b[key], Array.isArray(a[key]) ? 0 : 1)),
+    )
+  );
+};
+
+const stateVersions = new WeakMap<object, number>();
+
+/**
+ * A number that changes when table state changes, and not when only table
+ * options change. `memoMode: 'rows'` compares it, so a consumer that passes
+ * inline options still gets memoized rows.
+ */
+export const getMRT_TableStateVersion = (table: object) =>
+  stateVersions.get(table);
+
+/**
+ * TanStack Table mutates one table instance for the lifetime of the hook. The
+ * React Compiler memoizes on reference identity, so compiled consumer code
+ * (`<MantineReactTable table={table} />`, `table.getState()` and so on) never
+ * sees a change on that instance.
+ *
+ * This hook returns a new reference whenever table state, table options or the
+ * internal render version change, and the same reference otherwise. State and
+ * option objects are compared by content, so a setter called with the current
+ * value keeps the reference. A function option is compared by identity: pass a
+ * stable function (`useCallback` or the React Compiler) to keep the reference
+ * across renders of the component that calls the hook. Each
+ * reference is a view (see `snapshot.utils.ts`) of the one underlying instance,
+ * so every reference reads current data and an old reference is never stale.
+ */
+export const useMRT_TableSnapshot = <TData extends MRT_RowData>(
+  table: MRT_TableInstance<TData>,
+  tableOptions: MRT_TableOptions<TData>,
+  version: number,
+): MRT_TableInstance<TData> => {
+  const snapshotRef = useRef<null | Snapshot<TData>>(null);
+
+  const options = tableOptions as unknown as Record<string, unknown>;
+  const state = table.getState() as unknown as Record<string, unknown>;
+  const previous = snapshotRef.current;
+
+  const stateChanged =
+    !previous ||
+    previous.version !== version ||
+    !isEqual(previous.state, state, 3);
+
+  if (stateChanged || !optionsEqual(previous.options, options)) {
+    const snapshot = createMRT_View(table, {
+      //a new function identity keeps `const { getState } = table` reactive too
+      getState: () => table.getState(),
+    } as Partial<MRT_TableInstance<TData>>);
+    const stateVersion = (previous?.stateVersion ?? 0) + (stateChanged ? 1 : 0);
+    stateVersions.set(snapshot, stateVersion);
+    snapshotRef.current = {
+      options,
+      state,
+      stateVersion,
+      table: snapshot,
+      version,
+    };
+  }
+
+  return snapshotRef.current!.table;
+};

package/src/hooks/useMRT_VirtualizerScrollElement.ts

@@ -0,0 +1,31 @@
+'use no memo';
+
+import { useEffect, useReducer } from 'react';
+
+/**
+ * TanStack Virtual reads its scroll element in a layout effect. Child layout
+ * effects run before the table container attaches its ref, so the first read
+ * returns null and no rows or columns are rendered.
+ *
+ * Passive effects run after every ref is attached. This hook re-renders the
+ * owner once when the virtualizer still holds a different scroll element, so
+ * the next layout effect picks up the mounted container. The virtualizer no
+ * longer depends on an unrelated parent re-render, which compiled consumer
+ * code does not produce.
+ */
+export const useMRT_VirtualizerScrollElement = (virtualizer: {
+  options: { enabled?: boolean; getScrollElement: () => unknown };
+  scrollElement: unknown;
+}) => {
+  const rerender = useReducer((version: number) => version + 1, 0)[1];
+
+  useEffect(() => {
+    //the virtualizer's own options decide the element, so a consumer's
+    //`getScrollElement` or `enabled: false` never leaves a permanent mismatch
+    const { enabled, getScrollElement } = virtualizer.options;
+    const scrollElement = enabled === false ? null : getScrollElement();
+    if (scrollElement && virtualizer.scrollElement !== scrollElement) {
+      rerender();
+    }
+  });
+};

package/src/hooks/useMantineReactTable.ts

@@ -0,0 +1,23 @@
+'use no memo';
+
+import { useReducer } from 'react';
+
+import {
+  type MRT_RowData,
+  type MRT_TableInstance,
+  type MRT_TableOptions,
+} from '../types';
+import { useMRT_TableInstance } from './useMRT_TableInstance';
+import { useMRT_TableOptions } from './useMRT_TableOptions';
+import { useMRT_TableSnapshot } from './useMRT_TableSnapshot';
+
+export const useMantineReactTable = <TData extends MRT_RowData>(
+  tableOptions: MRT_TableOptions<TData>,
+): MRT_TableInstance<TData> => {
+  const [version, rerender] = useReducer((v: number) => v + 1, 0);
+  const table = useMRT_TableInstance(
+    useMRT_TableOptions(tableOptions),
+    rerender,
+  );
+  return useMRT_TableSnapshot(table, tableOptions, version);
+};

package/src/icons.ts

@@ -0,0 +1,108 @@
+import {
+  IconArrowAutofitContent,
+  IconArrowsSort,
+  IconBaselineDensityLarge,
+  IconBaselineDensityMedium,
+  IconBaselineDensitySmall,
+  IconBoxMultiple,
+  IconChevronDown,
+  IconChevronLeft,
+  IconChevronLeftPipe,
+  IconChevronRight,
+  IconChevronRightPipe,
+  IconChevronsDown,
+  IconCircleX,
+  IconClearAll,
+  IconColumns,
+  IconDeviceFloppy,
+  IconDots,
+  IconDotsVertical,
+  IconEdit,
+  IconEyeOff,
+  IconFilter,
+  IconFilterCog,
+  IconFilterOff,
+  IconGripHorizontal,
+  IconMaximize,
+  IconMinimize,
+  IconPinned,
+  IconPinnedOff,
+  IconSearch,
+  IconSearchOff,
+  IconSortAscending,
+  IconSortDescending,
+  IconX,
+} from '@tabler/icons-react';
+
+export type MRT_IconKeys =
+  | 'IconArrowAutofitContent'
+  | 'IconArrowsSort'
+  | 'IconBaselineDensityLarge'
+  | 'IconBaselineDensityMedium'
+  | 'IconBaselineDensitySmall'
+  | 'IconBoxMultiple'
+  | 'IconChevronDown'
+  | 'IconChevronLeft'
+  | 'IconChevronLeftPipe'
+  | 'IconChevronRight'
+  | 'IconChevronRightPipe'
+  | 'IconChevronsDown'
+  | 'IconCircleX'
+  | 'IconClearAll'
+  | 'IconColumns'
+  | 'IconDeviceFloppy'
+  | 'IconDots'
+  | 'IconDotsVertical'
+  | 'IconEdit'
+  | 'IconEyeOff'
+  | 'IconFilter'
+  | 'IconFilterCog'
+  | 'IconFilterOff'
+  | 'IconGripHorizontal'
+  | 'IconMaximize'
+  | 'IconMinimize'
+  | 'IconPinned'
+  | 'IconPinnedOff'
+  | 'IconSearch'
+  | 'IconSearchOff'
+  | 'IconSortAscending'
+  | 'IconSortDescending'
+  | 'IconX';
+
+export type MRT_Icons = Record<MRT_IconKeys, any>;
+
+export const MRT_Default_Icons: MRT_Icons = {
+  IconArrowAutofitContent,
+  IconArrowsSort,
+  IconBaselineDensityLarge,
+  IconBaselineDensityMedium,
+  IconBaselineDensitySmall,
+  IconBoxMultiple,
+  IconChevronDown,
+  IconChevronLeft,
+  IconChevronLeftPipe,
+  IconChevronRight,
+  IconChevronRightPipe,
+  IconChevronsDown,
+  IconCircleX,
+  IconClearAll,
+  IconColumns,
+  IconDeviceFloppy,
+  IconDots,
+  IconDotsVertical,
+  IconEdit,
+  IconEyeOff,
+  IconFilter,
+  IconFilterCog,
+  IconFilterOff,
+  IconGripHorizontal,
+  IconMaximize,
+  IconMinimize,
+  IconPinned,
+  IconPinnedOff,
+  IconSearch,
+  IconSearchOff,
+  IconSortAscending,
+  IconSortDescending,
+  IconX,
+};

package/src/index.ts

@@ -0,0 +1,91 @@
+//body components
+export * from './components/body/MRT_TableBody';
+
+export * from './components/body/MRT_TableBodyCell';
+export * from './components/body/MRT_TableBodyCellValue';
+export * from './components/body/MRT_TableBodyEmptyRow';
+export * from './components/body/MRT_TableBodyRow';
+export * from './components/body/MRT_TableBodyRowGrabHandle';
+
+export * from './components/body/MRT_TableBodyRowPinButton';
+export * from './components/body/MRT_TableDetailPanel';
+//button components
+export * from './components/buttons/MRT_ColumnPinningButtons';
+
+export * from './components/buttons/MRT_CopyButton';
+export * from './components/buttons/MRT_EditActionButtons';
+export * from './components/buttons/MRT_ExpandAllButton';
+export * from './components/buttons/MRT_ExpandButton';
+export * from './components/buttons/MRT_GrabHandleButton';
+export * from './components/buttons/MRT_RowPinButton';
+export * from './components/buttons/MRT_ShowHideColumnsButton';
+
+export * from './components/buttons/MRT_ToggleDensePaddingButton';
+export * from './components/buttons/MRT_ToggleFiltersButton';
+export * from './components/buttons/MRT_ToggleFullScreenButton';
+export * from './components/buttons/MRT_ToggleGlobalFilterButton';
+export * from './components/buttons/MRT_ToggleRowActionMenuButton';
+//footer components
+export * from './components/footer/MRT_TableFooter';
+export * from './components/footer/MRT_TableFooterCell';
+export * from './components/footer/MRT_TableFooterRow';
+//head components
+export * from './components/head/MRT_TableHead';
+export * from './components/head/MRT_TableHeadCell';
+export * from './components/head/MRT_TableHeadCellFilterContainer';
+export * from './components/head/MRT_TableHeadCellFilterLabel';
+export * from './components/head/MRT_TableHeadCellGrabHandle';
+export * from './components/head/MRT_TableHeadCellResizeHandle';
+export * from './components/head/MRT_TableHeadCellSortLabel';
+export * from './components/head/MRT_TableHeadRow';
+//input components
+export * from './components/inputs/MRT_EditCellTextInput';
+export * from './components/inputs/MRT_FilterCheckbox';
+export * from './components/inputs/MRT_FilterRangeFields';
+export * from './components/inputs/MRT_FilterRangeSlider';
+export * from './components/inputs/MRT_FilterTextInput';
+export * from './components/inputs/MRT_GlobalFilterTextInput';
+export * from './components/inputs/MRT_SelectCheckbox';
+//components
+export * from './components/MantineReactTable';
+//menu components
+export * from './components/menus/MRT_ColumnActionMenu';
+export * from './components/menus/MRT_FilterOptionMenu';
+export * from './components/menus/MRT_RowActionMenu';
+export * from './components/menus/MRT_ShowHideColumnsMenu';
+export * from './components/menus/MRT_ShowHideColumnsMenuItems';
+//modal components
+export * from './components/modals/MRT_EditRowModal';
+//table components
+export * from './components/table/MRT_Table';
+export * from './components/table/MRT_TableContainer';
+export * from './components/table/MRT_TablePaper';
+//toolbar components
+export * from './components/toolbar/MRT_BottomToolbar';
+export * from './components/toolbar/MRT_ProgressBar';
+export * from './components/toolbar/MRT_TablePagination';
+export * from './components/toolbar/MRT_ToolbarAlertBanner';
+export * from './components/toolbar/MRT_ToolbarDropZone';
+export * from './components/toolbar/MRT_ToolbarInternalButtons';
+export * from './components/toolbar/MRT_TopToolbar';
+//fns
+export * from './fns/aggregationFns';
+export * from './fns/filterFns';
+export * from './fns/sortingFns';
+//hooks
+export * from './hooks/useMantineReactTable';
+export * from './hooks/useMRT_ColumnVirtualizer';
+export * from './hooks/useMRT_Effects';
+export * from './hooks/useMRT_Rows';
+export * from './hooks/useMRT_RowVirtualizer';
+export * from './hooks/useMRT_TableInstance';
+export * from './hooks/useMRT_TableOptions';
+export * from './types';
+export * from './utils/column.utils';
+export * from './utils/displayColumn.utils';
+export * from './utils/row.utils';
+export * from './utils/snapshot.utils';
+export * from './utils/style.utils';
+//helpers
+export * from './utils/tanstack.helpers';
+export * from './utils/utils';