@lminii/material-react-table-mcp 4.0.1

package/data/skills/migrate-v3-to-v4/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: migrate-v3-to-v4
+description: >
+  Migrate an application from material-react-table V3 to @lminii/material-react-table V4: switch the package and imports, upgrade Material UI and X Date Pickers to V9, move text field props to slotProps, and apply every TanStack Table V9 rename and behaviour change (column pinning start/end, columnResizing, sortFn, getPaginatedRowModel, rowSelection true values, removed getCoreRowModel options and onStateChange). Load for migration plans, implementation, or audits of a V3 codebase.
+metadata:
+  type: lifecycle
+  library: '@lminii/material-react-table'
+  library_version: '4.0.0'
+  framework: react
+requires:
+  - getting-started
+sources:
+  - 'lminii/material-react-table:MIGRATION.md'
+  - 'lminii/material-react-table:apps/material-react-table-docs/pages/docs/getting-started/migrating-to-v4.mdx'
+  - 'lminii/material-react-table:packages/material-react-table/src/types.ts'
+  - 'lminii/material-react-table:packages/material-react-table/src/hooks/useMRT_TableOptions.ts'
+---
+
+This skill builds on `getting-started`. V4 keeps the V3 API: `useMaterialReactTable`, the `table` prop, every `mui*Props`, `render*`, and `enable*` option. Breaking changes come from three sources only: the package rename, Material UI V9, and TanStack Table V9. Do them in that order.
+
+## Setup
+
+```bash
+npx @mui/codemod@latest v9.0.0/system-props src
+npx @mui/codemod@latest deprecations/all src
+npm uninstall material-react-table
+npm install @lminii/material-react-table @mui/material@^9 @mui/icons-material@^9 @mui/x-date-pickers@^9
+```
+
+Then rewrite imports:
+
+```diff
+-import { MaterialReactTable } from 'material-react-table';
+-import { MRT_Localization_DE } from 'material-react-table/locales/de';
++import { MaterialReactTable } from '@lminii/material-react-table';
++import { MRT_Localization_DE } from '@lminii/material-react-table/locales/de';
+```
+
+Peer floors are `@mui/material`, `@mui/icons-material`, and `@mui/x-date-pickers` at 9.0 or newer; React 18 and Emotion 11.13 are unchanged. Node 22.12 or newer is required for the CommonJS build.
+
+## Core Patterns
+
+### Renames from TanStack Table V9
+
+Each of these is a find and replace across the codebase:
+
+| V3 | V4 |
+| --- | --- |
+| `columnPinning: { left, right }` | `columnPinning: { start, end }` |
+| `column.pin('left')`, `getIsPinned() === 'left'` | `column.pin('start')`, `getIsPinned() === 'start'` |
+| `table.getLeftLeafColumns()`, `getRight*`, `row.getLeftVisibleCells()` | `getStartLeafColumns()`, `getEnd*`, `row.getStartVisibleCells()` |
+| `columnSizingInfo`, `onColumnSizingInfoChange`, `setColumnSizingInfo` | `columnResizing`, `onColumnResizingChange`, `setColumnResizing` |
+| `sortingFn`, `sortingFns`, `column.getSortingFn()` | `sortFn`, `sortFns`, `column.getSortFn()` |
+| `table.getPrePaginationRowModel()`, `getPaginationRowModel()` | `getPrePaginatedRowModel()`, `getPaginatedRowModel()` |
+| `column.getAggregationFn()` | `column.getAggregationFns()` |
+| `MRT_SortingFn`, `MRT_ColumnSizingInfoState` | `MRT_SortFn`, `MRT_ColumnResizingState` (old names remain as deprecated aliases) |
+
+### Behaviour changes to audit
+
+- `rowSelection` values are `true`, never `false`. Deselect by deleting the key.
+- `rowPinning` needs both `top` and `bottom`; `columnPinning` needs both `start` and `end` when passed through `initialState` or `state`.
+- `table.getIsSomeRowsSelected()` is `true` when all rows are selected. Indeterminate is `getIsSomeRowsSelected() && !getIsAllRowsSelected()`.
+- A custom `aggregationFn` is `{ aggregate: (context) => value }`, not a callable. Built-in names still work.
+- `getCoreRowModel`, `getFilteredRowModel`, `getSortedRowModel`, `getPaginationRowModel`, `getExpandedRowModel`, `getGroupedRowModel`, and `getFaceted*` options are gone; the models are always registered. Use `manual*` to take over a stage.
+- Rows with `renderDetailPanel` report `row.getCanExpand()` as `true`. Pass `getRowCanExpand` to restrict it.
+- `onStateChange` and `table.setState()` are gone. Control slices individually.
+- `table.getState()` still returns the full state; `table.state` is reactive in render code.
+- Pinned cells use `insetInlineStart` and `insetInlineEnd`, so RTL pins to the logical start and end.
+
+### Material UI V9 changes inside MRT options
+
+```diff
+ muiFilterTextFieldProps: {
+-  InputProps: { sx: { minWidth: 120 } },
++  slotProps: { input: { sx: { minWidth: 120 } } },
+ },
+-const pickerProps: DatePickerProps<Dayjs> = { ... };
++const pickerProps: DatePickerProps = { ... };
+```
+
+`muiFilterDatePickerProps`, `muiFilterDateTimePickerProps`, and `muiFilterTimePickerProps` are no longer generic, and the filter pickers render `PickersTextField`, so a custom `slots.textField` must accept `PickersTextFieldProps`. Everything else in `mui*Props` passes straight to Material UI, so Material UI's own V7 and V9 notes apply.
+
+### Package entry points
+
+The package ships an `exports` map with `.mjs` and `.js` builds. Only `@lminii/material-react-table`, `@lminii/material-react-table/locales/<code>`, and `@lminii/material-react-table/package.json` resolve; deep imports into `dist/` or `src/` fail at build time and must be replaced with root exports.
+
+## Common Mistakes
+
+### HIGH Keeping v8 pinning literals
+
+Wrong:
+
+```tsx
+initialState: { columnPinning: { left: ['mrt-row-select'], right: ['mrt-row-actions'] } }
+```
+
+Correct:
+
+```tsx
+initialState: { columnPinning: { start: ['mrt-row-select'], end: ['mrt-row-actions'] } }
+```
+
+`left` and `right` are no longer valid keys, so the pinning state is silently empty.
+
+Source: `MIGRATION.md`
+
+### HIGH Passing row model factories
+
+Wrong:
+
+```tsx
+useMaterialReactTable({ columns, data, getSortedRowModel: getSortedRowModel() })
+```
+
+Correct:
+
+```tsx
+useMaterialReactTable({ columns, data })
+```
+
+The options no longer exist in `MRT_TableOptions`; MRT registers every row model itself.
+
+Source: `packages/material-react-table/src/features/mrtFeatures.ts`
+
+### MEDIUM Treating the migration as a TanStack useTable rewrite
+
+Wrong:
+
+```tsx
+const table = useTable({ features: tableFeatures({ rowSortingFeature }), columns, data })
+```
+
+Correct:
+
+```tsx
+const table = useMaterialReactTable({ columns, data })
+```
+
+The `@tanstack/react-table#migrate-v8-to-v9` skill describes migrating a headless table. MRT applications stay on `useMaterialReactTable`; only the renamed instance methods and state shapes from that skill apply.
+
+Source: `MIGRATION.md`
+
+### LOW Deep-importing a locale file
+
+Wrong:
+
+```tsx
+import { MRT_Localization_FR } from '@lminii/material-react-table/dist/locales/fr'
+```
+
+Correct:
+
+```tsx
+import { MRT_Localization_FR } from '@lminii/material-react-table/locales/fr'
+```
+
+Source: `packages/material-react-table/package.json` exports map
+
+## API Discovery
+
+Compare `node_modules/@lminii/material-react-table/dist/index.d.ts` against the V3 declarations for renamed members; the deprecated `MRT_SortingFn` and `MRT_ColumnSizingInfoState` aliases carry JSDoc pointing to the new names. The full guide with tables is at `/docs/getting-started/migrating-to-v4`.

package/data/skills/state-and-server-data/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: state-and-server-data
+description: >
+  Control Material React Table V4 state with initialState, the state option plus on*Change callbacks, MRT_Updater handlers, table.getState and table.state, and move filtering, sorting, pagination, grouping, or expanding to the server with manual* options and rowCount. Load for controlled tables, persisted state, side effects on state change, TanStack Query integration, or infinite scrolling.
+metadata:
+  type: framework
+  library: '@lminii/material-react-table'
+  library_version: '4.0.0'
+  framework: react
+requires:
+  - getting-started
+  - '@tanstack/table-core#client-vs-server'
+sources:
+  - 'lminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/state-management.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/pagination.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/async-loading.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/examples/react-query/sandbox/src/TS.tsx'
+  - 'lminii/material-react-table:packages/material-react-table/src/types.ts'
+---
+
+This skill builds on `getting-started` and `@tanstack/table-core#client-vs-server`. MRT manages every state slice internally by default. Take over only the slices you need to read or persist, and only through the `state` option paired with the matching `on*Change` callback.
+
+## Setup
+
+```tsx
+const [pagination, setPagination] = useState<MRT_PaginationState>({ pageIndex: 0, pageSize: 25 })
+const [sorting, setSorting] = useState<MRT_SortingState>([])
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  initialState: { density: 'compact', showColumnFilters: true },
+  state: { pagination, sorting },
+  onPaginationChange: setPagination,
+  onSortingChange: setSorting,
+})
+```
+
+`initialState` seeds slices MRT keeps managing. `state` hands a slice over to you; from then on MRT calls `on<Slice>Change` and reads only what you pass back. Do not put the same slice in both.
+
+## Core Patterns
+
+### Handle updaters like React setState
+
+```tsx
+import { type MRT_Updater, type MRT_RowSelectionState } from '@lminii/material-react-table'
+
+const handleRowSelectionChange = (updater: MRT_Updater<MRT_RowSelectionState>) => {
+  setRowSelection((previous) => {
+    const next = updater instanceof Function ? updater(previous) : updater
+    onSelectionChanged(Object.keys(next)) // side effect runs once, even in Strict Mode
+    return next
+  })
+}
+```
+
+Callbacks receive either a value or an updater function, exactly like `useState`. Use `getRowId` so selection keys are stable ids instead of row indexes.
+
+### Server-side data with manual* options
+
+```tsx
+const { data: page, isLoading, isError, isRefetching } = useQuery({
+  queryKey: ['people', pagination, sorting, columnFilters, globalFilter],
+  queryFn: () => fetchPeople({ pagination, sorting, columnFilters, globalFilter }),
+  placeholderData: keepPreviousData,
+})
+
+const table = useMaterialReactTable({
+  columns,
+  data: page?.rows ?? EMPTY,
+  rowCount: page?.total ?? 0,
+  manualFiltering: true,
+  manualPagination: true,
+  manualSorting: true,
+  state: { pagination, sorting, columnFilters, globalFilter, isLoading, showAlertBanner: isError, showProgressBars: isRefetching },
+  onPaginationChange: setPagination,
+  onSortingChange: setSorting,
+  onColumnFiltersChange: setColumnFilters,
+  onGlobalFilterChange: setGlobalFilter,
+  muiToolbarAlertBannerProps: isError ? { color: 'error', children: 'Error loading data' } : undefined,
+})
+```
+
+Each `manual*` option tells MRT that stage already happened on the server, so the client row model passes rows through. `rowCount` (or `pageCount`) drives the pagination controls. `isLoading`, `showProgressBars`, `showSkeletons`, and `showLoadingOverlay` are MRT state slices meant to be set from fetch status.
+
+### Read state without controlling it
+
+```tsx
+const table = useMaterialReactTable({ columns, data })
+
+<Button onClick={() => save(table.getState().columnVisibility)}>Save layout</Button>
+```
+
+`table.getState()` returns the complete state, including MRT-only slices such as `density`, `isFullScreen`, `showColumnFilters`, `editingRow`, and `creatingRow`. In render code `table.state` is reactive. Setters such as `table.setPagination`, `table.resetSorting`, `table.setShowColumnFilters`, and `table.setDensity` exist for every slice.
+
+### Persist state
+
+```tsx
+const [columnVisibility, setColumnVisibility] = useState<MRT_VisibilityState>(
+  () => JSON.parse(localStorage.getItem('people-columns') ?? '{}'),
+)
+useEffect(() => {
+  localStorage.setItem('people-columns', JSON.stringify(columnVisibility))
+}, [columnVisibility])
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  state: { columnVisibility },
+  onColumnVisibilityChange: setColumnVisibility,
+})
+```
+
+## Common Mistakes
+
+### HIGH Passing on*Change without state
+
+Wrong:
+
+```tsx
+const table = useMaterialReactTable({ columns, data, onSortingChange: setSorting })
+```
+
+Correct:
+
+```tsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  state: { sorting },
+  onSortingChange: setSorting,
+})
+```
+
+Once a callback is supplied, MRT stops updating that slice itself. Without `state`, the table never sorts.
+
+Source: `docs/guides/state-management.mdx`
+
+### HIGH Toggling row selection with false
+
+Wrong:
+
+```tsx
+setRowSelection((old) => ({ ...old, [id]: false }))
+```
+
+Correct:
+
+```tsx
+setRowSelection(({ [id]: _removed, ...rest }) => rest)
+```
+
+TanStack Table V9 types `rowSelection` as `Record<string, true>`, so a `false` entry is a type error; absence of the key is the only deselected state.
+
+Source: `MIGRATION.md`
+
+### MEDIUM Using onStateChange or table.setState
+
+Wrong:
+
+```tsx
+onStateChange: (updater) => setTableState(updater)
+```
+
+Correct:
+
+```tsx
+state: { pagination, sorting },
+onPaginationChange: setPagination,
+onSortingChange: setSorting,
+```
+
+`onStateChange` and `table.setState` were removed with TanStack Table V9. Control slices individually.
+
+Source: `MIGRATION.md`
+
+### MEDIUM Forgetting rowCount with manualPagination
+
+Wrong:
+
+```tsx
+manualPagination: true,
+data: page.rows,
+```
+
+Correct:
+
+```tsx
+manualPagination: true,
+data: page.rows,
+rowCount: page.total,
+```
+
+Without a total, MRT assumes the current page is all the data and disables the next page button.
+
+Source: `docs/guides/pagination.mdx`
+
+## API Discovery
+
+`MRT_TableState` in `node_modules/@lminii/material-react-table/dist/index.d.ts` lists every slice; each has an `on<Slice>Change` option and `table.set<Slice>` method. The State Options table at `/docs/api/state-options` shows defaults, and the `manual*` and `rowCount` options are in `/docs/api/table-options`.

package/data/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.