@mini_7/material-react-table-mcp 4.0.0

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: '@mini_7/material-react-table'
+  library_version: '4.0.0'
+  framework: react
+requires:
+  - getting-started
+  - '@tanstack/table-core#client-vs-server'
+sources:
+  - 'gyminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/state-management.mdx'
+  - 'gyminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/pagination.mdx'
+  - 'gyminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/async-loading.mdx'
+  - 'gyminii/material-react-table:apps/material-react-table-docs/examples/react-query/sandbox/src/TS.tsx'
+  - 'gyminii/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 '@mini_7/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/@mini_7/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: '@mini_7/material-react-table'
+  library_version: '4.0.0'
+  framework: react
+requires:
+  - getting-started
+sources:
+  - 'gyminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/virtualization.mdx'
+  - 'gyminii/material-react-table:apps/material-react-table-docs/examples/enable-row-virtualization/sandbox/src/TS.tsx'
+  - 'gyminii/material-react-table:packages/material-react-table/src/hooks/useMRT_RowVirtualizer.ts'
+  - 'gyminii/material-react-table:packages/material-react-table/src/hooks/useMRT_TableOptions.ts'
+  - 'gyminii/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 '@mini_7/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/@mini_7/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/dist/data.js

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const CATEGORIES = [
+    'tableOptions',
+    'columnOptions',
+    'stateOptions',
+    'tableInstanceAPIs',
+    'columnInstanceAPIs',
+    'rowInstanceAPIs',
+    'cellInstanceAPIs',
+];
+const dataDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'data');
+export const loadApi = () => JSON.parse(readFileSync(join(dataDir, 'api.json'), 'utf8'));
+export const loadDocsIndex = () => JSON.parse(readFileSync(join(dataDir, 'index.json'), 'utf8'));
+export const loadMigrationGuide = () => readFileSync(join(dataDir, 'MIGRATION.md'), 'utf8');
+export const listSkills = () => readdirSync(join(dataDir, 'skills'), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+export const loadSkill = (name) => {
+    if (!listSkills().includes(name))
+        return undefined;
+    return readFileSync(join(dataDir, 'skills', name, 'SKILL.md'), 'utf8');
+};
+const safeName = /^[a-z0-9-]+$/;
+export const loadGuide = (name) => {
+    const file = join(dataDir, 'guides', `${name}.md`);
+    if (!safeName.test(name) || !existsSync(file))
+        return undefined;
+    return readFileSync(file, 'utf8');
+};
+export const loadReference = (name) => {
+    const file = join(dataDir, 'reference', `${name}.md`);
+    if (!safeName.test(name) || !existsSync(file))
+        return undefined;
+    return readFileSync(file, 'utf8');
+};
+export const loadExample = (id) => {
+    const file = join(dataDir, 'examples', `${id}.tsx`);
+    if (!safeName.test(id) || !existsSync(file))
+        return undefined;
+    return readFileSync(file, 'utf8');
+};
+const tokenize = (query) => query.toLowerCase().split(/\s+/).filter(Boolean);
+/** Ranks name matches above description matches; exact and prefix matches first. */
+export const searchApi = (api, query, categories = CATEGORIES, limit = 20) => {
+    const terms = tokenize(query);
+    if (terms.length === 0)
+        return [];
+    const hits = [];
+    for (const category of categories) {
+        for (const entry of api.categories[category]) {
+            const name = entry.name.toLowerCase();
+            const description = entry.description.toLowerCase();
+            let score = 0;
+            for (const term of terms) {
+                if (name === term)
+                    score += 100;
+                else if (name.startsWith(term))
+                    score += 60;
+                else if (name.includes(term))
+                    score += 40;
+                else if (description.includes(term))
+                    score += 10;
+                else {
+                    score = 0;
+                    break;
+                }
+            }
+            if (score > 0)
+                hits.push({ ...entry, category, score });
+        }
+    }
+    return hits
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+        .slice(0, limit);
+};
+/** Every term must match the name, title, headings, or description of a document. */
+export const searchDocs = (index, query, limit = 20, kinds = ['guide', 'reference', 'skill', 'example']) => {
+    const terms = tokenize(query);
+    if (terms.length === 0)
+        return [];
+    const docs = [];
+    const pushDoc = (kind, entry) => docs.push({
+        kind,
+        name: entry.name,
+        summary: entry.description || entry.title,
+        text: [entry.title, ...entry.headings, entry.description]
+            .join(' ')
+            .toLowerCase(),
+    });
+    index.guides.forEach((entry) => pushDoc('guide', entry));
+    index.reference.forEach((entry) => pushDoc('reference', entry));
+    index.skills.forEach((entry) => pushDoc('skill', entry));
+    index.examples.forEach((entry) => docs.push({
+        kind: 'example',
+        name: entry.id,
+        summary: entry.guides.length
+            ? `used in guides: ${entry.guides.join(', ')}`
+            : entry.pages.length
+                ? `shown on example pages: ${entry.pages.join(', ')}`
+                : 'standalone example',
+        text: [...entry.guides, ...entry.pages].join(' ').toLowerCase(),
+    }));
+    const hits = [];
+    for (const doc of docs) {
+        if (!kinds.includes(doc.kind))
+            continue;
+        const name = doc.name.toLowerCase();
+        let score = 0;
+        for (const term of terms) {
+            if (name === term)
+                score += 100;
+            else if (name.split('-').includes(term))
+                score += 60;
+            else if (name.includes(term))
+                score += 40;
+            else if (doc.text.includes(term))
+                score += 10;
+            else {
+                score = 0;
+                break;
+            }
+        }
+        if (score > 0)
+            hits.push({
+                kind: doc.kind,
+                name: doc.name,
+                summary: doc.summary,
+                score,
+            });
+    }
+    return hits
+        .sort((a, b) => b.score - a.score || a.name.localeCompare(b.name))
+        .slice(0, limit);
+};