@lminii/material-react-table 4.0.0

package/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 @lminii/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: '@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/localization.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/examples/localization-i18n-de/sandbox/src/TS.tsx'
+  - 'lminii/material-react-table:packages/material-react-table/src/locales/en.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`. 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 '@lminii/material-react-table/locales/de'
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  localization: MRT_Localization_DE,
+})
+```
+
+Built-in locales, imported from `@lminii/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 '@lminii/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 '@lminii/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/@lminii/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/@lminii/material-react-table/locales` shows the shipped locale folders. The Localization guide at `/docs/guides/localization` renders an example per locale.

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