@lminii/material-react-table 4.0.0

package/skills/composable-components/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: composable-components
+description: >
+  Compose a custom Material React Table V4 layout from exported MRT_* components that all take the same table prop: MRT_TablePaper, MRT_TableContainer, MRT_Table, MRT_TopToolbar, MRT_TablePagination, MRT_GlobalFilterTextField, MRT_ToolbarInternalButtons, MRT_ShowHideColumnsButton, and MRT_TableBodyCellValue for fully custom markup. Load for tables inside cards or dialogs, toolbars placed outside the table, split layouts, or headless rendering with MRT state.
+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/api/mrt-components.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/examples/custom-headless/sandbox/src/TS.tsx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/examples/custom-top-toolbar/sandbox/src/TS.tsx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/examples/external-toolbar/sandbox/src/TS.tsx'
+  - 'lminii/material-react-table:packages/material-react-table/src/index.ts'
+---
+
+This skill builds on `getting-started`. `MaterialReactTable` is a thin composition of exported sub-components. Because every sub-component takes the same `table` instance as a prop, you can render any subset of them anywhere in your tree while MRT keeps managing state.
+
+## Setup
+
+```tsx
+import {
+  MRT_GlobalFilterTextField,
+  MRT_TableContainer,
+  MRT_TablePagination,
+  MRT_ToggleFiltersButton,
+  useMaterialReactTable,
+} from '@lminii/material-react-table'
+
+const table = useMaterialReactTable({ columns, data, enableBottomToolbar: false })
+
+return (
+  <Card>
+    <CardHeader
+      title="People"
+      action={
+        <Stack direction="row" gap={1}>
+          <MRT_GlobalFilterTextField table={table} />
+          <MRT_ToggleFiltersButton table={table} />
+        </Stack>
+      }
+    />
+    <MRT_TableContainer table={table} />
+    <CardActions sx={{ justifyContent: 'flex-end' }}>
+      <MRT_TablePagination table={table} />
+    </CardActions>
+  </Card>
+)
+```
+
+`MRT_TableContainer` renders the scroll container, the table, the loading overlay, the edit row modal, and the cell action menu. Turn off the built-in toolbars with `enableTopToolbar` and `enableBottomToolbar` when you place their pieces elsewhere.
+
+## Core Patterns
+
+### Layers of the default component
+
+```text
+MRT_TablePaper
+  MRT_TopToolbar
+    MRT_GlobalFilterTextField, MRT_ToolbarInternalButtons, MRT_ToolbarAlertBanner, MRT_TablePagination
+  MRT_TableContainer
+    MRT_Table
+      MRT_TableHead > MRT_TableHeadRow > MRT_TableHeadCell
+      MRT_TableBody > MRT_TableBodyRow > MRT_TableBodyCell, MRT_TableDetailPanel
+      MRT_TableFooter > MRT_TableFooterRow > MRT_TableFooterCell
+  MRT_BottomToolbar
+```
+
+Start from the layer just above what you need to change. Replacing `MRT_TopToolbar` with your own component is the most common cut; replacing `MRT_TableBodyRow` is rarely worth it because `muiTableBodyRowProps` covers styling and events.
+
+### Toolbar buttons are individual exports
+
+```tsx
+import {
+  MRT_ShowHideColumnsButton,
+  MRT_ToggleDensePaddingButton,
+  MRT_ToggleFullScreenButton,
+} from '@lminii/material-react-table'
+
+<MRT_ShowHideColumnsButton table={table} />
+<MRT_ToggleDensePaddingButton table={table} />
+<MRT_ToggleFullScreenButton table={table} />
+```
+
+Each button reads and writes MRT state on the shared instance, so it works from any position in the tree.
+
+### Fully custom markup with MRT_TableBodyCellValue
+
+```tsx
+import { MRT_TableBodyCellValue, flexRender } from '@lminii/material-react-table'
+
+<Table>
+  <TableHead>
+    {table.getHeaderGroups().map((group) => (
+      <TableRow key={group.id}>
+        {group.headers.map((header) => (
+          <TableCell key={header.id}>
+            {header.isPlaceholder ? null : flexRender(header.column.columnDef.Header ?? header.column.columnDef.header, header.getContext())}
+          </TableCell>
+        ))}
+      </TableRow>
+    ))}
+  </TableHead>
+  <TableBody>
+    {table.getRowModel().rows.map((row, staticRowIndex) => (
+      <TableRow key={row.id} selected={row.getIsSelected()}>
+        {row.getVisibleCells().map((cell) => (
+          <TableCell key={cell.id}>
+            <MRT_TableBodyCellValue cell={cell} table={table} staticRowIndex={staticRowIndex} />
+          </TableCell>
+        ))}
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+`MRT_TableBodyCellValue` applies the column's `Cell`, `AggregatedCell`, `GroupedCell`, filter match highlighting, and click to copy, so custom markup keeps MRT cell behaviour. `table.getRowModel()` is the final model after filtering, sorting, grouping, expanding, and pagination.
+
+### Row virtualization in custom layouts
+
+Render `MRT_TableContainer` rather than `MRT_Table` when `enableRowVirtualization` or `enableColumnVirtualization` is on. The container owns the scroll element the virtualizers measure.
+
+## Common Mistakes
+
+### HIGH Rendering MRT components without the table prop
+
+Wrong:
+
+```tsx
+<MRT_TablePagination />
+```
+
+Correct:
+
+```tsx
+<MRT_TablePagination table={table} />
+```
+
+MRT does not use React context. Every component requires the instance explicitly.
+
+Source: `packages/material-react-table/src/components/toolbar/MRT_TablePagination.tsx`
+
+### MEDIUM Duplicating the toolbar
+
+Wrong:
+
+```tsx
+const table = useMaterialReactTable({ columns, data })
+<MRT_GlobalFilterTextField table={table} />
+<MaterialReactTable table={table} />
+```
+
+Correct:
+
+```tsx
+const table = useMaterialReactTable({ columns, data, enableTopToolbar: false })
+<MRT_GlobalFilterTextField table={table} />
+<MaterialReactTable table={table} />
+```
+
+The default top toolbar already contains the search field, so two inputs fight over `globalFilter`.
+
+Source: `docs/api/mrt-components.mdx`
+
+### MEDIUM Using a v8 header render
+
+Wrong:
+
+```tsx
+flexRender(header.column.columnDef.header, header.getContext())
+```
+
+Correct:
+
+```tsx
+flexRender(header.column.columnDef.Header ?? header.column.columnDef.header, header.getContext())
+```
+
+MRT columns carry both `header` (string) and `Header` (custom render). Falling back to the string alone drops custom header markup.
+
+Source: `apps/material-react-table-docs/examples/custom-headless/sandbox/src/TS.tsx`
+
+## API Discovery
+
+`node_modules/@lminii/material-react-table/dist/index.d.ts` exports every `MRT_*` component with its props interface; all of them include `table: MRT_TableInstance<TData>`. The component tree with links to source is at `/docs/api/mrt-components`.

package/skills/customization/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: customization
+description: >
+  Style and extend Material React Table V4 through mui*Props objects and callbacks, the sx prop, Material UI V9 slotProps on text fields, render* slots for toolbars, row actions, detail panels and empty states, displayColumnDefOptions, icons, and localization. Load for theming, conditional row or cell styling, custom toolbar buttons, or replacing built-in display columns.
+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/customize-components.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/display-columns.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/toolbar-customization.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/row-actions.mdx'
+  - 'lminii/material-react-table:MIGRATION.md'
+---
+
+This skill builds on `getting-started`. MRT renders Material UI components and forwards props to each of them through a matching `mui<Component>Props` option, so customization means passing Material UI props, not overriding MRT internals.
+
+## Setup
+
+```tsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiTablePaperProps: { elevation: 0, sx: { borderRadius: 0 } },
+  muiTableBodyRowProps: ({ row }) => ({
+    sx: { backgroundColor: row.getIsSelected() ? 'action.selected' : undefined },
+  }),
+  muiTableBodyCellProps: ({ column }) => ({
+    align: column.id === 'amount' ? 'right' : 'left',
+  }),
+})
+```
+
+Every `mui*Props` option accepts a static object or a callback. The callback receives `table` plus whatever is in scope for that component: `row`, `cell`, `column`, `staticRowIndex`, `isDetailPanel`, and similar. Static objects are cheaper; use a callback only when the props depend on data.
+
+## Core Patterns
+
+### Text field options use Material UI V9 slotProps
+
+```tsx
+muiSearchTextFieldProps: {
+  placeholder: 'Search people',
+  slotProps: {
+    input: { startAdornment: <SearchIcon /> },
+    htmlInput: { 'aria-label': 'Search people' },
+    inputLabel: { shrink: true },
+  },
+},
+```
+
+`muiEditTextFieldProps`, `muiFilterTextFieldProps`, and `muiSearchTextFieldProps` take `slotProps.input`, `slotProps.htmlInput`, `slotProps.select`, and `slotProps.inputLabel`. MRT merges the object form of each slot after its own defaults and composes `sx`. The function form `(ownerState) => props` is ignored.
+
+### Column-level props override table-level props
+
+```tsx
+const columns: MRT_ColumnDef<Person>[] = [
+  {
+    accessorKey: 'salary',
+    header: 'Salary',
+    muiTableHeadCellProps: { align: 'right' },
+    muiTableBodyCellProps: { align: 'right' },
+    Cell: ({ cell }) => cell.getValue<number>().toLocaleString('en-US', { style: 'currency', currency: 'USD' }),
+  },
+]
+```
+
+`muiTableHeadCellProps`, `muiTableBodyCellProps`, `muiTableFooterCellProps`, `muiFilter*Props`, `muiEditTextFieldProps`, `muiCopyButtonProps`, and `muiColumnActionsButtonProps` exist on both the table options and the column definition. The column value wins.
+
+### render* slots add UI without replacing MRT components
+
+```tsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableRowActions: true,
+  positionActionsColumn: 'last',
+  renderRowActionMenuItems: ({ row, closeMenu }) => [
+    <MenuItem key="edit" onClick={() => { edit(row.original); closeMenu() }}>Edit</MenuItem>,
+  ],
+  renderTopToolbarCustomActions: ({ table }) => (
+    <Button onClick={() => exportRows(table.getPrePaginatedRowModel().rows)}>Export</Button>
+  ),
+  renderDetailPanel: ({ row }) => <Address address={row.original.address} />,
+  renderEmptyRowsFallback: () => <Typography>No people match these filters</Typography>,
+})
+```
+
+`renderTopToolbar` and `renderBottomToolbar` replace the whole toolbar; `renderTopToolbarCustomActions`, `renderBottomToolbarCustomActions`, and `renderToolbarInternalActions` add to it. `renderRowActions` renders inline buttons; `renderRowActionMenuItems` fills the kebab menu. `renderDetailPanel` also makes every row expandable.
+
+### Adjust built-in display columns
+
+```tsx
+displayColumnDefOptions: {
+  'mrt-row-actions': { header: '', size: 80, muiTableHeadCellProps: { align: 'center' } },
+  'mrt-row-select': { enableColumnActions: false },
+  'mrt-row-expand': { size: 40 },
+},
+```
+
+Display column ids are `mrt-row-actions`, `mrt-row-drag`, `mrt-row-expand`, `mrt-row-numbers`, `mrt-row-pin`, `mrt-row-select`, and `mrt-row-spacer`. They exist only when the matching feature is enabled.
+
+### Icons and localization
+
+```tsx
+import { MRT_Localization_DE } from '@lminii/material-react-table/locales/de'
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  localization: MRT_Localization_DE,
+  icons: { SearchIcon: (props) => <TravelExploreIcon {...props} /> },
+})
+```
+
+`icons` accepts a partial `MRT_Icons` map; `localization` accepts a partial `MRT_Localization`, so overriding a few strings is fine.
+
+## Common Mistakes
+
+### HIGH Passing removed Material UI text field props
+
+Wrong:
+
+```tsx
+muiSearchTextFieldProps: {
+  InputProps: { startAdornment: <SearchIcon /> },
+  inputProps: { 'aria-label': 'Search' },
+}
+```
+
+Correct:
+
+```tsx
+muiSearchTextFieldProps: {
+  slotProps: {
+    input: { startAdornment: <SearchIcon /> },
+    htmlInput: { 'aria-label': 'Search' },
+  },
+}
+```
+
+Material UI V9 removed `InputProps`, `inputProps`, `SelectProps`, `InputLabelProps`, and `FormHelperTextProps` from `TextField`, so the old keys are type errors and are never applied.
+
+Source: `MIGRATION.md`
+
+### MEDIUM Styling with a class selector instead of the sx prop
+
+Wrong:
+
+```tsx
+muiTableBodyCellProps: { className: 'my-cell' }
+// plus a global .my-cell rule fighting Material UI specificity
+```
+
+Correct:
+
+```tsx
+muiTableBodyCellProps: {
+  sx: (theme) => ({ borderRight: `1px solid ${theme.palette.divider}` }),
+}
+```
+
+`sx` receives the Material UI theme and wins the specificity contest with Emotion styles that MRT already applies.
+
+Source: `docs/guides/customize-components.mdx`
+
+### MEDIUM Replacing the toolbar when only a button was needed
+
+Wrong:
+
+```tsx
+renderTopToolbar: ({ table }) => <Button onClick={add}>Add</Button>
+```
+
+Correct:
+
+```tsx
+renderTopToolbarCustomActions: ({ table }) => <Button onClick={add}>Add</Button>
+```
+
+`renderTopToolbar` removes the search box, filter toggle, density and full screen buttons, and the alert banner. The `*CustomActions` slot keeps them.
+
+Source: `docs/guides/toolbar-customization.mdx`
+
+## API Discovery
+
+Search `node_modules/@lminii/material-react-table/dist/index.d.ts` for `mui` to see every prop option and its callback arguments, and for `render` to see every render slot. The Customize Components guide at `/docs/guides/customize-components` lists the options per component, and `/docs/api/column-options` marks which options also exist on columns.

package/skills/drag-and-drop-ordering/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: drag-and-drop-ordering
+description: >
+  Reorder columns and rows by drag and drop in Material React Table V4: enableColumnOrdering with the columnOrder state and mrt-row-* display column ids, enableRowOrdering with muiRowDragHandleProps onDragEnd reading draggingRow and hoveredRow, enableRowDragging for dropping rows onto other tables or UI, enableColumnDragging for column drags without reordering, and the draggingColumn, hoveredColumn, draggingRow, hoveredRow state. Load for user-arranged columns, sortable lists, moving rows between tables, or a drop that never fires.
+metadata:
+  type: framework
+  library: '@lminii/material-react-table'
+  library_version: '4.0.0'
+  framework: react
+requires:
+  - getting-started
+  - state-and-server-data
+  - '@tanstack/table-core#column-ordering'
+sources:
+  - 'lminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/column-ordering-dnd.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/pages/docs/guides/row-ordering-dnd.mdx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/examples/enable-row-ordering/sandbox/src/TS.tsx'
+  - 'lminii/material-react-table:apps/material-react-table-docs/examples/enable-row-dragging/sandbox/src/TS.tsx'
+  - 'lminii/material-react-table:packages/material-react-table/src/components/body/MRT_TableBodyRowGrabHandle.tsx'
+  - 'lminii/material-react-table:packages/material-react-table/src/utils/column.utils.ts'
+---
+
+This skill builds on `getting-started`, `state-and-server-data`, and `@tanstack/table-core#column-ordering`. MRT uses native HTML drag events with a grab handle button. Column ordering is fully built in; row ordering exposes the drag state and leaves the reorder of `data` to you.
+
+## Setup
+
+```tsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableColumnOrdering: true, // drag handles in every header
+  enableRowOrdering: true, // adds the mrt-row-drag display column
+  enableSorting: false, // manual order and sorting fight each other
+  muiRowDragHandleProps: ({ table }) => ({
+    onDragEnd: () => {
+      const { draggingRow, hoveredRow } = table.getState()
+      if (draggingRow && hoveredRow) {
+        setData((old) => {
+          const next = [...old]
+          next.splice(hoveredRow.index!, 0, next.splice(draggingRow.index, 1)[0])
+          return next
+        })
+      }
+    },
+  }),
+})
+```
+
+Column-level `enableColumnOrdering: false` removes the handle from one column. `hoveredRow` and `hoveredColumn` are typed as partial objects because a drop target may be a placeholder; read `index` or `id` and guard for undefined.
+
+## Core Patterns
+
+### Set or persist the column order
+
+```tsx
+const [columnOrder, setColumnOrder] = useState<MRT_ColumnOrderState>([
+  'mrt-row-select',
+  'name',
+  'email',
+  'mrt-row-actions',
+])
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableRowSelection: true,
+  enableRowActions: true,
+  enableColumnOrdering: true,
+  state: { columnOrder },
+  onColumnOrderChange: setColumnOrder,
+})
+```
+
+`columnOrder` is an array of column ids (`accessorKey` or `id`). Include the display column ids you enable (`mrt-row-select`, `mrt-row-actions`, `mrt-row-expand`, `mrt-row-numbers`, `mrt-row-drag`, `mrt-row-pin`) at the position you want; missing ones are appended at the start or end. If the array length does not match the column count MRT regenerates it, so `initialState.columnOrder` is enough when you only need a default. A dropped column is also pinned to the target column's pin position.
+
+### Move rows between tables
+
+```tsx
+const [draggingRow, setDraggingRow] = useState<MRT_Row<Person> | null>(null)
+const [hoveredTable, setHoveredTable] = useState<string | null>(null)
+
+const common = {
+  columns,
+  enableRowDragging: true, // handle only; no in-table reorder
+  onDraggingRowChange: setDraggingRow,
+  state: { draggingRow },
+}
+
+const table1 = useMaterialReactTable({
+  ...common,
+  data: data1,
+  getRowId: (row) => `t1-${row.id}`,
+  muiRowDragHandleProps: {
+    onDragEnd: () => {
+      if (hoveredTable === 'table-2' && draggingRow) {
+        setData2((rows) => [...rows, draggingRow.original])
+        setData1((rows) => rows.filter((r) => r !== draggingRow.original))
+      }
+      setHoveredTable(null)
+    },
+  },
+  muiTablePaperProps: {
+    onDragEnter: () => setHoveredTable('table-1'),
+    sx: { outline: hoveredTable === 'table-1' ? '2px dashed' : undefined },
+  },
+})
+```
+
+`enableRowDragging` shows the handle and maintains `draggingRow` without the in-table hover targets that `enableRowOrdering` adds. Any element can be a drop target through its own `onDragEnter`. Share `draggingRow` across tables by controlling it. Use `enableColumnDragging` the same way for columns that should be draggable onto external targets, for example a group-by drop zone.
+
+### Style the drag interaction
+
+```tsx
+muiRowDragHandleProps: ({ row }) => ({
+  'aria-label': `Move ${row.original.name}`,
+  sx: { cursor: 'grab' },
+}),
+muiTableBodyRowProps: ({ row, table }) => ({
+  sx: {
+    opacity: table.getState().draggingRow?.id === row.id ? 0.5 : 1,
+    outline: table.getState().hoveredRow?.id === row.id ? '2px dashed' : undefined,
+  },
+}),
+```
+
+`muiRowDragHandleProps` takes `IconButtonProps`; your `onDragStart` and `onDragEnd` run before MRT sets or clears `draggingRow`. `muiColumnDragHandleProps` is the column counterpart, and `hoveredColumn` / `draggingColumn` drive header styling. Replace the handle icon through `icons.DragHandleIcon`.
+
+### Combine with virtualization
+
+```tsx
+enableRowOrdering: true,
+enableRowVirtualization: true,
+enablePagination: false,
+```
+
+The row virtualizer keeps the dragging row mounted while it is scrolled out of view, so drops still resolve. Keep `autoResetPageIndex: false` when paginated so a drop does not jump back to page one.
+
+## Common Mistakes
+
+### HIGH Reordering with the wrong row index
+
+Wrong:
+
+```tsx
+onDragEnd: () => {
+  const { draggingRow, hoveredRow } = table.getState()
+  data.splice(hoveredRow.index, 0, data.splice(draggingRow.index, 1)[0])
+  setData(data) // same array reference, no re-render
+},
+```
+
+Correct:
+
+```tsx
+onDragEnd: () => {
+  const { draggingRow, hoveredRow } = table.getState()
+  if (!draggingRow || hoveredRow?.index === undefined) return
+  setData((old) => {
+    const next = [...old]
+    next.splice(hoveredRow.index!, 0, next.splice(draggingRow.index, 1)[0])
+    return next
+  })
+},
+```
+
+`row.index` is the index in the original `data` array, so it is only meaningful when no client-side sort or filter is applied; and a mutated array with the same reference does not trigger a render.
+
+Source: `docs/examples/enable-row-ordering`
+
+### HIGH Expecting a drop callback
+
+Wrong:
+
+```tsx
+onHoveredRowChange: (row) => moveRow(row), // fires on every hover, not on drop
+```
+
+Correct:
+
+```tsx
+muiRowDragHandleProps: { onDragEnd: () => moveRow(table.getState().hoveredRow) },
+```
+
+There is no `onRowDrop`; the drop point is the handle's `onDragEnd`, after which MRT clears `draggingRow` and `hoveredRow`.
+
+Source: `packages/material-react-table/src/components/body/MRT_TableBodyRowGrabHandle.tsx`
+
+### MEDIUM Leaving sorting on with row ordering
+
+Wrong:
+
+```tsx
+enableRowOrdering: true,
+```
+
+Correct:
+
+```tsx
+enableRowOrdering: true,
+enableSorting: false,
+```
+
+A sorted view re-sorts after every drop, so the user's arrangement disappears and `row.index` no longer maps to the visible position.
+
+Source: `docs/guides/row-ordering-dnd.mdx`
+
+### MEDIUM Column order array that ignores display columns
+
+Wrong:
+
+```tsx
+initialState: { columnOrder: ['name', 'email'] }, // with enableRowSelection: true
+```
+
+Correct:
+
+```tsx
+initialState: { columnOrder: ['mrt-row-select', 'name', 'email'] },
+```
+
+The length mismatch makes MRT regenerate the order from the column definitions, discarding the custom arrangement.
+
+Source: `docs/guides/column-ordering-dnd.mdx`
+
+## API Discovery
+
+Search `node_modules/@lminii/material-react-table/dist/index.d.ts` for `enableRowOrdering`, `enableRowDragging`, `muiRowDragHandleProps`, `muiColumnDragHandleProps`, `draggingRow`, and `hoveredColumn`. The Column Ordering and Row Ordering guides at `/docs/guides/column-ordering-dnd` and `/docs/guides/row-ordering-dnd` list the related options, and `/docs/examples/enable-column-ordering`, `enable-row-ordering`, and `enable-row-dragging` are runnable examples.