@mini_7/material-react-table-mcp 4.0.0

package/data/skills/getting-started/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: getting-started
+description: >
+  Build a Material React Table V4 with useMaterialReactTable and the MaterialReactTable table prop: install @mini_7/material-react-table with Material UI V9 peers, define stable data and MRT_ColumnDef columns, toggle features with enable* options, and read the instance. Load for a first MRT table, a Material UI data grid on TanStack Table V9, or when a TanStack useTable or upstream material-react-table example is producing the wrong setup.
+metadata:
+  type: framework
+  library: '@mini_7/material-react-table'
+  library_version: '4.0.0'
+  framework: react
+requires:
+  - '@tanstack/table-core#core'
+sources:
+  - 'gyminii/material-react-table:apps/material-react-table-docs/pages/docs/getting-started/install.mdx'
+  - 'gyminii/material-react-table:apps/material-react-table-docs/pages/docs/getting-started/usage.mdx'
+  - 'gyminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/best-practices.mdx'
+  - 'gyminii/material-react-table:packages/material-react-table/src/hooks/useMaterialReactTable.ts'
+  - 'gyminii/material-react-table:packages/material-react-table/src/types.ts'
+---
+
+This skill builds on `@tanstack/table-core#core` for the headless model and stable inputs. Material React Table (MRT) owns the TanStack Table instance, feature registration, and all Material UI rendering. Application code never calls `useTable` or `tableFeatures`; it configures MRT options and renders MRT components.
+
+## Setup
+
+```bash
+npm install @mini_7/material-react-table @mui/material@^9 @mui/icons-material@^9 @mui/x-date-pickers@^9 @emotion/react @emotion/styled
+```
+
+Do not install `@tanstack/react-table`; MRT pins its own exact version. Node 22.12 or newer is required for the CommonJS build because TanStack Table V9 is ESM-only.
+
+```tsx
+import { useMemo } from 'react'
+import {
+  MaterialReactTable,
+  useMaterialReactTable,
+  type MRT_ColumnDef,
+} from '@mini_7/material-react-table'
+
+type Person = { name: string; age: number }
+
+const data: Person[] = [
+  { name: 'Ada', age: 36 },
+  { name: 'Grace', age: 45 },
+]
+
+export function PeopleTable() {
+  const columns = useMemo<MRT_ColumnDef<Person>[]>(
+    () => [
+      { accessorKey: 'name', header: 'Name' },
+      { accessorKey: 'age', header: 'Age' },
+    ],
+    [],
+  )
+
+  const table = useMaterialReactTable({
+    columns,
+    data,
+    enableRowSelection: true,
+  })
+
+  return <MaterialReactTable table={table} />
+}
+```
+
+`useMaterialReactTable(options)` returns an `MRT_TableInstance<TData>`. Every MRT component takes that instance through a `table` prop; nothing is passed through React context.
+
+## Core Patterns
+
+### Accessors return primitives, renders return markup
+
+```tsx
+const columns: MRT_ColumnDef<Person>[] = [
+  {
+    accessorFn: (row) => `${row.firstName} ${row.lastName}`,
+    id: 'fullName',
+    header: 'Name',
+    Cell: ({ cell, row }) => (
+      <a href={row.original.profileUrl}>{cell.getValue<string>()}</a>
+    ),
+  },
+]
+```
+
+`accessorKey` or `accessorFn` feeds sorting, filtering, grouping, and search, so it must return a string, number, boolean, or Date. `Cell`, `Header`, `Footer`, `Edit`, `Filter`, `AggregatedCell`, and `GroupedCell` are the render slots. An `accessorFn` column needs an explicit `id`.
+
+### Infer column types with createMRTColumnHelper
+
+```tsx
+import { createMRTColumnHelper } from '@mini_7/material-react-table'
+
+const helper = createMRTColumnHelper<Person>()
+const columns = [
+  helper.accessor('name', { header: 'Name' }),
+  helper.accessor((row) => row.age, {
+    id: 'age',
+    header: 'Age',
+    Cell: ({ cell }) => cell.getValue().toLocaleString(), // typed number
+  }),
+  helper.display({ id: 'actions', header: 'Actions' }),
+]
+```
+
+### Toggle features with enable* options
+
+Table-level `enable*` options switch a feature on for every column; the same option on a column definition overrides it for that column. `enableColumnFilters`, `enableSorting`, `enablePagination`, `enableGlobalFilter`, `enableColumnActions`, `enableDensityToggle`, `enableFullScreenToggle`, `enableHiding`, and `enableTopToolbar` are on by default. Row selection, editing, grouping, pinning, ordering, expanding, virtualization, and row actions are off until enabled.
+
+```tsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableColumnOrdering: true,
+  enableColumnPinning: true,
+  enableGrouping: true,
+  enablePagination: false,
+  renderDetailPanel: ({ row }) => <pre>{JSON.stringify(row.original)}</pre>,
+})
+```
+
+### Read the instance where you need it
+
+```tsx
+const selectedRows = table.getSelectedRowModel().rows
+const { pagination, sorting } = table.getState()
+table.resetRowSelection()
+```
+
+`table.getState()` returns the full MRT state, including MRT-only slices such as `density`, `isFullScreen`, and `showColumnFilters`. Inside render code `table.state` is the reactive equivalent.
+
+## Common Mistakes
+
+### HIGH Building the table with TanStack hooks
+
+Wrong:
+
+```tsx
+const table = useTable({ features, columns, data })
+return <MaterialReactTable table={table} />
+```
+
+Correct:
+
+```tsx
+const table = useMaterialReactTable({ columns, data })
+return <MaterialReactTable table={table} />
+```
+
+`MaterialReactTable` needs the MRT instance, which registers MRT's features, display columns, localization, icons, and Material UI props. A bare TanStack instance lacks all of them.
+
+Source: `packages/material-react-table/src/hooks/useMaterialReactTable.ts`
+
+### HIGH Unstable data or columns
+
+Wrong:
+
+```tsx
+const table = useMaterialReactTable({
+  columns: [{ accessorKey: 'name', header: 'Name' }],
+  data: response.data ?? [],
+})
+```
+
+Correct:
+
+```tsx
+const columns = useMemo<MRT_ColumnDef<Person>[]>(() => [...], [])
+const EMPTY: Person[] = []
+const table = useMaterialReactTable({ columns, data: response.data ?? EMPTY })
+```
+
+A new array each render invalidates every row model and can loop forever. Keep `columns` and `data` in `useMemo`, `useState`, module scope, or a query cache.
+
+Source: `docs/getting-started/usage.mdx`
+
+### MEDIUM Mixing the upstream and fork package names
+
+Wrong:
+
+```tsx
+import { MaterialReactTable } from 'material-react-table'
+import { MRT_Localization_DE } from '@mini_7/material-react-table/locales/de'
+```
+
+Correct:
+
+```tsx
+import { MaterialReactTable } from '@mini_7/material-react-table'
+import { MRT_Localization_DE } from '@mini_7/material-react-table/locales/de'
+```
+
+Two copies of MRT produce two `MRT_TableInstance` types and duplicate Emotion styles. Pick the fork everywhere, or alias `material-react-table` to it in `package.json`.
+
+Source: `MIGRATION.md`
+
+### MEDIUM Returning JSX from an accessor
+
+Wrong:
+
+```tsx
+{ accessorFn: (row) => <b>{row.name}</b>, id: 'name', header: 'Name' }
+```
+
+Correct:
+
+```tsx
+{ accessorKey: 'name', header: 'Name', Cell: ({ cell }) => <b>{cell.getValue<string>()}</b> }
+```
+
+Sorting, filtering, and global search compare accessor values, so JSX breaks all three.
+
+Source: `docs/getting-started/usage.mdx`
+
+## API Discovery
+
+Read `node_modules/@mini_7/material-react-table/dist/index.d.ts` for `MRT_TableOptions`, `MRT_ColumnDef`, `MRT_TableInstance`, and `MRT_TableState`; the `mui*Props`, `render*`, `enable*`, and `on*Change` option families are all declared there with JSDoc. The docs prop tables at `/docs/api/table-options`, `/docs/api/column-options`, and `/docs/api/state-options` list every option with its default and source library.

package/data/skills/localization/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: localization
+description: >
+  Translate Material React Table V4 with the localization option: import a built-in locale from @mini_7/material-react-table/locales/<code>, override individual MRT_Localization strings, write a full custom locale with the language BCP 47 tag, keep {column} placeholders, and pair it with Material UI theme locales and the date pickers adapterLocale. Load for i18n, translating toolbar and menu text, number formatting in pagination, or a locale import that fails to resolve.
+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/localization.mdx'
+  - 'gyminii/material-react-table:apps/material-react-table-docs/examples/localization-i18n-de/sandbox/src/TS.tsx'
+  - 'gyminii/material-react-table:packages/material-react-table/src/locales/en.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`. Every user-facing string MRT renders comes from one `MRT_Localization` object. The `localization` option takes a partial object that is merged over the English defaults, so a locale file or a handful of overrides both work.
+
+## Setup
+
+```tsx
+import { MRT_Localization_DE } from '@mini_7/material-react-table/locales/de'
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  localization: MRT_Localization_DE,
+})
+```
+
+Built-in locales, imported from `@mini_7/material-react-table/locales/<code>`: `ar`, `az`, `bg`, `cs`, `da`, `de`, `el`, `en`, `es`, `et`, `fa`, `fi`, `fr`, `he`, `hr`, `hu`, `hy`, `id`, `it`, `ja`, `ko`, `mk`, `nl`, `no`, `np`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sk`, `sr-Cyrl-RS`, `sr-Latn-RS`, `sv`, `tr`, `uk`, `vi`, `zh-Hans`, `zh-Hant`. Each exports `MRT_Localization_<CODE>` with hyphens replaced by underscores, for example `MRT_Localization_PT_BR` and `MRT_Localization_ZH_HANS`. Column headers, cell content, and your own toolbar buttons are not translated by MRT; those come from your column definitions and render slots.
+
+## Core Patterns
+
+### Override a few strings
+
+```tsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  localization: {
+    ...MRT_Localization_DE,
+    noRecordsToDisplay: 'Keine Personen gefunden',
+    rowsPerPage: 'Personen pro Seite',
+  },
+})
+```
+
+Partial objects are merged over English, so an override object without a base locale still renders every other string. Keep the `localization` object stable (module scope or `useMemo`); MRT memoizes the merge on its identity.
+
+### Write a custom locale
+
+```tsx
+import { type MRT_Localization } from '@mini_7/material-react-table'
+
+export const MRT_Localization_GA: MRT_Localization = {
+  ...MRT_Localization_EN, // start from English so nothing is missing
+  language: 'ga', // BCP 47 tag used for number formatting
+  actions: 'Gníomhartha',
+  filterByColumn: 'Scag de réir {column}',
+  sortByColumnAsc: 'Sórtáil de réir {column} in ord ardaitheach',
+  noRecordsToDisplay: 'Níl aon taifid le taispeáint',
+}
+```
+
+`MRT_Localization` has around 90 keys; `language` is required on the type and feeds `toLocaleString` for the row counts in pagination and the selection banner. Strings such as `filterByColumn`, `sortByColumnAsc`, `dropToGroupBy`, and `filteringByColumn` contain `{column}` placeholders that MRT replaces with the column header, so keep the token verbatim. Fully translated locales are welcome as pull requests to `packages/material-react-table/src/locales`.
+
+### Pair with Material UI and the date pickers
+
+```tsx
+import { createTheme, ThemeProvider, useTheme } from '@mui/material'
+import { deDE } from '@mui/material/locale'
+import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider'
+import { AdapterDayjs } from '@mui/x-date-pickers/AdapterDayjs'
+import { deDE as pickersDeDE } from '@mui/x-date-pickers/locales'
+import 'dayjs/locale/de'
+
+const theme = useTheme()
+
+<ThemeProvider theme={createTheme(theme, deDE, pickersDeDE)}>
+  <LocalizationProvider dateAdapter={AdapterDayjs} adapterLocale="de">
+    <MaterialReactTable table={table} />
+  </LocalizationProvider>
+</ThemeProvider>
+```
+
+MRT's `localization` covers MRT strings only. Material UI's own component text (pagination select labels, accessibility labels) comes from the theme locale, and the date and time filter pickers take their month names and formats from the pickers locale and `adapterLocale`.
+
+### Switch locales at runtime
+
+```tsx
+const locales = { en: MRT_Localization_EN, de: MRT_Localization_DE, ja: MRT_Localization_JA }
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  localization: locales[currentLanguage],
+})
+```
+
+The table re-renders with the new strings; no state is reset.
+
+## Common Mistakes
+
+### HIGH Importing a locale from the upstream package name
+
+Wrong:
+
+```tsx
+import { MRT_Localization_ES } from 'material-react-table/locales/es'
+```
+
+Correct:
+
+```tsx
+import { MRT_Localization_ES } from '@mini_7/material-react-table/locales/es'
+```
+
+The fork publishes locales under its own `exports` map. The upstream path resolves only if the upstream package is also installed, which produces two copies of MRT.
+
+Source: `MIGRATION.md`
+
+### MEDIUM Custom locale without the language tag
+
+Wrong:
+
+```tsx
+localization: { actions: 'Ações', cancel: 'Cancelar', rowsPerPage: 'Linhas por página' }
+```
+
+Correct:
+
+```tsx
+localization: { language: 'pt', actions: 'Ações', cancel: 'Cancelar', rowsPerPage: 'Linhas por página' }
+```
+
+Without `language`, the English `en` tag from the merged defaults formats row counts, so `1.234` renders as `1,234`.
+
+Source: `packages/material-react-table/src/locales/en.ts`
+
+### MEDIUM Dropping the {column} placeholder
+
+Wrong:
+
+```tsx
+localization: { filterByColumn: 'Filtrer' }
+```
+
+Correct:
+
+```tsx
+localization: { filterByColumn: 'Filtrer par {column}' }
+```
+
+MRT substitutes the header into `{column}`; without it the tooltip and placeholder no longer say which column they apply to.
+
+Source: `packages/material-react-table/src/locales/en.ts`
+
+### LOW Passing an unstable localization object
+
+Wrong:
+
+```tsx
+localization: { ...MRT_Localization_FR, noRecordsToDisplay: t('empty') }, // new object each render
+```
+
+Correct:
+
+```tsx
+const localization = useMemo(() => ({ ...MRT_Localization_FR, noRecordsToDisplay: t('empty') }), [t])
+```
+
+A fresh object every render re-runs the merge and invalidates the memoized table options.
+
+Source: `packages/material-react-table/src/hooks/useMRT_TableOptions.ts`
+
+## API Discovery
+
+`MRT_Localization` in `node_modules/@mini_7/material-react-table/dist/index.d.ts` lists every key; `en.ts` in `packages/material-react-table/src/locales` is the reference translation. `ls node_modules/@mini_7/material-react-table/locales` shows the shipped locale folders. The Localization guide at `/docs/guides/localization` renders an example per locale.

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 @mini_7/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: '@mini_7/material-react-table'
+  library_version: '4.0.0'
+  framework: react
+requires:
+  - getting-started
+sources:
+  - 'gyminii/material-react-table:MIGRATION.md'
+  - 'gyminii/material-react-table:apps/material-react-table-docs/pages/docs/getting-started/migrating-to-v4.mdx'
+  - 'gyminii/material-react-table:packages/material-react-table/src/types.ts'
+  - 'gyminii/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 @mini_7/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 '@mini_7/material-react-table';
++import { MRT_Localization_DE } from '@mini_7/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 `@mini_7/material-react-table`, `@mini_7/material-react-table/locales/<code>`, and `@mini_7/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 '@mini_7/material-react-table/dist/locales/fr'
+```
+
+Correct:
+
+```tsx
+import { MRT_Localization_FR } from '@mini_7/material-react-table/locales/fr'
+```
+
+Source: `packages/material-react-table/package.json` exports map
+
+## API Discovery
+
+Compare `node_modules/@mini_7/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`.