@mini_7/material-react-table-mcp 4.0.0

package/data/guides/data-columns.md

@@ -0,0 +1,292 @@
+## Data (Accessor) Columns Guide
+
+Data columns are used to display data and are the default columns that are created when you create a column with an `accessorKey` or `accessorFn`.
+
+The table can perform processing on the data of a data column, such as sorting, filtering, grouping, etc.
+
+The other type of column that you can make is a display column, which you can learn more about in the [next section](/docs/guides/display-columns).
+
+### Accessors (Connect a column to data)
+
+Each column definition must have at least an `accessorKey` (or a combination of an `id` and `accessorFn`) and a `header` property. The `accessorKey`/`accessorFn` property is the key that will be used to join the data from the `data` keys. The `header` property is used to display the column header, but is also used in other places in the table.
+
+> Note: Do NOT have your accessors resolve JSX or markup. That's what custom [`Cell`](#custom-cell-render) renders are for. Accessors should only return primitive data so that the table can sort, filter, search, and group properly.
+
+#### Method 1 - Using an accessorKey (Recommended)
+
+The simplest and most common way to define a column is to use the `accessorKey` column option. The `accessorKey` column option is the key that will be used to join the data from the `data` keys.
+
+The `accessorKey` must match one of the keys in your data, or else no data will show up in the column. The `accessorKey` also supports dot notation, so you can access nested data.
+
+By default, the `accessorKey` will double as the `id` for the column, but if you need the id of the column to be different than the accessorKey, you can use the `id` property in addition.
+
+```tsx
+const columns = useMemo<MRT_ColumnDef<Customer>[]>( //TS helps with the autocomplete while writing columns
+  () => [
+    {
+      accessorKey: 'username', //normal recommended usage of an accessorKey
+      header: 'Username',
+    },
+    {
+      accessorKey: 'name.firstName', //example of dot notation used to access nested data
+      header: 'First Name',
+    },
+    {
+      accessorKey: 'name.lastName', //example of dot notation used to access nested data
+      header: 'Last Name',
+    },
+    {
+      accessorKey: 'customerAge',
+      id: 'age' //id overridden, usually not necessary to do this, but can be helpful
+      header: 'Age',
+    },
+  ],
+  [],
+);
+```
+
+#### Method 2 - Using an accessorFn and id
+
+You can alternatively use the `accessorFn` column option. Here are at least three ways you can use it.
+
+In each case, the `id` property is now required since there is no `accessorKey` for MRT to derive it from.
+
+```tsx
+const columns = useMemo<MRT_ColumnDef<Customer>[]>(
+  () => [
+    {
+      //simple accessorFn that works the same way as an `accessorKey`
+      accessorFn: (row) => row.username,
+      id: 'username',
+      header: 'Username',
+    },
+    {
+      //accessorFn function that combines multiple data together
+      accessorFn: (row) => `${row.firstName} ${row.lastName}`,
+      id: 'name',
+      header: 'Name',
+    },
+    {
+      //accessorFn used to access nested data, though you could just use dot notation in an accessorKey
+      accessorFn: (row) => row.personalInfo.age,
+      id: 'age',
+      header: 'Age',
+    },
+  ],
+  [],
+);
+```
+
+#### Method 3 - Using createMRTColumnHelper
+
+> New in V3 (After many requests)
+
+Alternatively you can use the `createMRTColumnHelper` utility function to define your columns definitions in a slightly more type-safe way. Instantiate a `columnHelper` by passing in your `TData` type as a generic argument. Then the first argument of the `columnHelper.accessor()` method can be either an `accessorKey` or an `accessorFn`. Then you can specify the rest of the column options as the second argument.
+
+```tsx
+const columnHelper = createMRTColumnHelper<Customer>(); //TS now knows the shape of your data
+
+const columns = [
+  //accessorKey as first argument, rest of column options as second argument
+  columnHelper.accessor('name', {
+    //TS should provide autocomplete for valid accessorKeys
+    header: 'Last Name',
+  }),
+  //accessorFn as first argument, rest of column options as second argument
+  columnHelper.accessor((row) => Number(row.age), {
+    //TS should provide autocomplete for valid properties on your data
+    header: 'Age',
+    id: 'age', //id is required when using accessorFn
+  }),
+];
+```
+
+### Custom Header Render
+
+If you want to pass in custom JSX to render the header, you can pass in a `Header` option in addition to the `header` string property.
+
+> The `header` (lowercase) property is still required and still must only be a string because it is used within multiple components in the table and has string manipulation methods performed on it.
+
+```tsx
+const columns = useMemo(
+  () => [
+    {
+      accessorKey: 'name',
+      header: 'Name',
+      Header: ({ column }) => (
+        <i style={{ color: 'red' }}>{column.columnDef.header}</i> //re-use the header we already defined
+      ), //arrow function
+    },
+    {
+      accessorKey: 'age',
+      header: 'Age',
+      Header: <i style={{ color: 'red' }}>Age</i>, //plain jsx with no function
+    },
+  ],
+  [],
+);
+```
+
+### Custom Cell Render
+
+Similarly, the data cells in a column can have a custom JSX render with the `Cell` option. This is one of the most common features used in MRT.
+
+Using the `Cell` column option should be the only way that you use to render custom JSX in table cells. Do not put JSX in an accessorFn, or else the table will not be able to sort, filter, search, or group properly.
+
+```tsx
+const columns = useMemo(
+  () => [
+    {
+      accessorFn: (row) => `${row.firstName} ${row.lastName}`,
+      header: 'Name',
+      //Add a link in a cell render
+      Cell: ({ renderedCellValue, row }) => (
+        <Link to={`/profile/${row.original.username}`}>
+          {renderedCellValue}
+        </Link>
+      ),
+    },
+    {
+      accessorKey: 'salary',
+      header: 'Salary',
+      //Format a number in a cell render
+      Cell: ({ cell }) => (
+        <span>${cell.getValue<number>().toLocaleString()}</span>
+      ),
+    },
+    {
+      accessorKey: 'profileImage',
+      header: 'Profile Image',
+      //Render images in a cell render
+      Cell: ({ cell }) => <img src={cell.getValue<string>()} />,
+    },
+  ],
+  [],
+);
+```
+
+### Custom Footer Render
+
+If you want to pass in custom JSX to render the footer, you can pass in a `Footer` option. If no custom markup is needed, you can just use the `footer` string property.
+
+The footer cells can be a good place to put totals or other summary information.
+
+```tsx
+const columns = useMemo(
+  () => [
+    {
+      accessorKey: 'name',
+      header: 'Name',
+      footer: 'Name', //simple string header
+    },
+    {
+      accessorKey: 'age',
+      header: 'Age',
+      //Custom footer markup for a aggregation calculation
+      Footer: () => (
+        <Stack>
+          Max Age:
+          <Box color="warning.main">{Math.round(maxAge)}</Box>
+        </Stack>
+      ),
+    },
+  ],
+  [],
+);
+```
+
+> See the [Customize Components Guide](/docs/guides/customize-components) for more ways to style and customize header and cell components.
+
+### Set Column Widths
+
+This topic is covered in detail in the [Column Size Guide](/docs/guides/column-size), but here is a brief overview.
+
+Setting a CSS (sx or style) width prop in the `muiTableHeadCellProps`, `muiTableBodyCellProps`, etc. might not work well, and is redundant. MRT/TanStack Table has an official way to set column widths with the `size`, `minSize`, `maxSize`, and `grow` column options.
+
+```tsx
+const columns = [
+  {
+    accessorKey: 'id',
+    header: 'ID',
+    size: 50, //small column
+    grow: false, //don't allow this column to grow (if layoutMode is grid)
+  },
+  {
+    accessorKey: 'username',
+    header: 'Username',
+    minSize: 100, //min size enforced during resizing
+    maxSize: 200, //max size enforced during resizing
+    size: 180, //medium column
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    size: 300, //large column
+  },
+];
+```
+
+There is a lot of different behaviors for column widths depending on what other features are enabled or how they are configured. See the [Column Size Guide](/docs/guides/column-size) for more details on the `layoutMode`s, and how and why they are enabled and how they affect column widths.
+
+### Set Column Alignment
+
+By default, all columns are left-aligned. You can change the alignment of a column by setting the `align` option to either `"center"`, `"right"`, or `"justify"` in the `muiTableHeadCellProps` and `muiTableBodyCellProps` props/column options.
+
+```tsx
+const columns = [
+  {
+    accessorKey: 'id',
+    header: 'ID',
+    //right align the header, body, and footer cells each individually
+    muiTableHeadCellProps: {
+      align: 'right',
+    },
+    muiTableBodyCellProps: {
+      align: 'right',
+    },
+    muiTableFooterCellProps: {
+      align: 'right',
+    },
+  },
+  {
+    accessorKey: 'username',
+    header: 'Username',
+    //center align the header, body, and footer cells each individually
+    muiTableHeadCellProps: {
+      align: 'center',
+    },
+    muiTableBodyCellProps: {
+      align: 'center',
+    },
+    muiTableFooterCellProps: {
+      align: 'center',
+    },
+  },
+];
+```
+
+> Live example: `column-alignment` (call get_mrt_example with that id).
+
+### Enable or Disable Features Per Column
+
+In the same way that you can pass props to the main `<MaterialReactTable />` component to enable or disable features, you can also specify options on the column definitions to enable or disable features on a per-column basis.
+
+```tsx
+const columns = useMemo(
+  () => [
+    {
+      accessorKey: 'salary',
+      header: 'Salary',
+      enableClickToCopy: true, //enable click to copy on this column
+    },
+    {
+      accessorKey: 'profileImage',
+      header: 'Profile Image',
+      enableSorting: false, //disable sorting on this column
+    },
+  ],
+  [],
+);
+```
+
+> See all the column options you can use in the [Column Options API Reference](/docs/api/column-options).

package/data/guides/density-toggle.md

@@ -0,0 +1,46 @@
+## Density Toggle Feature Guide
+
+Material React Table includes a density toggle button in the top toolbar by default that lets you toggle between three different density levels. This is a great feature to include to help with accessibility for different user preferences, but it can also easily be disabled if desired.
+
+### Relevant Table Options
+
+Relevant table options (get_mrt_api has full details):
+
+- `enableDensityToggle` - type `boolean` - default `true`
+- `onDensityChange` - type `OnChangeFn<MRT_DensityState>`
+
+### Relevant State
+
+Relevant state options (get_mrt_api has full details):
+
+- `density` - type `'comfortable' | 'compact' | 'spacious'` - default `'comfortable'`
+
+### Default Density
+
+By default, Material React Table will render with a medium `comfortable` density.
+
+A density toggle is shown by default to let a user change the density to cycle through `spacious`, `comfortable`, and `compact` densities.
+
+> When a `compact` density is set, whitespace is set to `nowrap` by default to keep the rows as short in height as possible. This can be overridden in the `muiTableBodyCellProps` styles or sx prop.
+
+#### Change Default Density
+
+If you want to change the default density, you can set it in either the `initialState` table option or the `state` table option.
+
+```tsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  initialState: { density: 'compact' },
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+### Disable or Hide the Density Toggle
+
+You can change the default density and disable the density toggle itself if you want.
+
+In this example, the density toggle is disabled and a `compact` density is set by default in the `initialState` table option.
+
+> Live example: `disable-density-toggle` (call get_mrt_example with that id).

package/data/guides/detail-panel.md

@@ -0,0 +1,195 @@
+## Detail Panel Feature Guide
+
+Material React Table has multiple kinds of expanding features. This guide will show you how to use the detail panel feature to expand a single row to show more information for that row.
+
+If you are looking for how to expand multiple rows from a tree data structure, see the [Expanding Sub-Rows](/docs/guides/expanding-sub-rows) guide.
+
+### Relevant Table Options
+
+Relevant table options (get_mrt_api has full details):
+
+- `displayColumnDefOptions` - type `{ [key: string]: MRT_DisplayColumnDef<TData> }` - Customize and override the column definition options for the built-in display columns. (Select, Expand, Row Actions, etc.)
+- `enableExpandAll` - type `boolean` - default `true`
+- `muiDetailPanelProps` - type `TableCellProps | ({ row, table }) => TableCellProps`
+- `muiExpandAllButtonProps` - type `IconButtonProps | ({ table }) => IconButtonProps`
+- `muiExpandButtonProps` - type `IconButtonProps | ({ row, table }) => IconButtonProps`
+- `positionExpandColumn` - type `'first' | 'last'` - default `'first'`
+- `renderDetailPanel` - type `({ row, table }) => ReactNode`
+
+### Relevant State
+
+Relevant state options (get_mrt_api has full details):
+
+- `expanded` - type `Record<string, boolean> | boolean` - default `{}`
+
+### Render Detail Panel
+
+To add a detail panel to a row, all you need to do is add a `renderDetailPanel` table option.
+
+The recommended way to access the row data for the detail panel is to pull from the `original` object on a row. This gives you the original data for the row, not transformed or filtered by TanStack Table.
+
+> Using `row.getValue('columnId')` will not work for data that does not have its own column. Using `row.original.columnId` is recommended for detail panels since the data in the detail panel usually does not have its own column.
+
+### Disable Expand All Button
+
+If you don't want to show the expand all button, you can set the `enableExpandAll` table option to `false`.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  enableExpandAll: false,
+});
+```
+
+### Enable Detail Panel Conditionally Per Row
+
+If the return value of your `renderDetailPanel` function returns `null` or a falsy value for a row, the expand button will be disabled for that row.
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  renderDetailPanel: ({ row }) =>
+    row.original.someCondition ? <DetailPanelContent /> : null,
+});
+```
+
+One thing to note about the implementation of conditional detail panels is that additional `<tr>` elements will still be created for all rows, even if they do not have detail panel content. It is implemented this way in order to avoid bugs with row virtualization, or striped row CSS.
+
+### Only Allow One Detail Panel Open At A Time
+
+If you want to only allow one detail panel to be open at a time, all you have to do is add your own `onClick` logic to the `muiExpandButtonProps` table option.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  renderDetailPanel: ({ row }) => <DetailPanelContent />,
+  muiExpandButtonProps: ({ row, table }) => ({
+    onClick: () => table.setExpanded({ [row.id]: !row.getIsExpanded() }), //set only this row to be expanded
+  }),
+});
+```
+
+### Rotate Expand Icon
+
+If you don't like the default rotation styles for the expand icons, you can pass in custom CSS to the `muiExpandButtonProps` and `muiExpandAllButtonProps` table options.
+
+### Replace Expand Icon
+
+You can easily use a custom expand icon either by following the [Custom Icons Guide](/docs/guides/custom-icons) or by passing in custom `children` to the `muiExpandButtonProps` and `muiExpandAllButtonProps` table options.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  // icons, //or manage icons globally
+  muiExpandButtonProps: ({ row }) => ({
+    children: row.getIsExpanded() ? <MinusIcon /> : <AddIcon />,
+  }),
+});
+```
+
+### Customize or Style Detail Panel
+
+You can use the `muiDetailPanelProps` table option to pass in custom props to the detail panel. These props are passed to the `<td>` element that contains the detail panel content.
+
+If you need to customize the `<tr>` element containing the detail panel cell, you can just use the `muiTableBodyRowProps` table option that you use for customizing all rows. There is a `isDetailPanel` parameter that is available to you to target only detail panel rows.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  muiDetailPanelProps: ({ row }) => ({
+    sx: {
+      //...
+    },
+  }),
+  muiTableBodyRowProps: ({ isDetailPanel, row }) => ({
+    sx: {
+      // isDetailPanel ? ... : ...
+    },
+  }),
+});
+```
+
+> Live example: `enable-detail-panel-conditionally` (call get_mrt_example with that id).
+
+### Expand Detail Panel By Default
+
+If you want some or all rows to be expanded by default, you can specify that in the `initialState.expanded` table option. Pass `true` to expand all rows, or specify which rowIds should be expanded.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  initialState: {
+    expanded: true,
+    // or expand specific rows by default
+    // expanded: {
+    //   1: true,
+    //   2: true,
+    // },
+  },
+});
+```
+
+### Position Expand Column Last
+
+If you want to position the expand column last, you can set the `positionExpandColumn` table option to `'last'`.
+
+Alternatively though, you could use the [Column Pinning Feature](/docs/guides/column-pinning) to pin the expand column to the right side of the table.
+
+> Live example: `alternate-detail-panel` (call get_mrt_example with that id).
+
+### Detail Panel With Charts
+
+The detail panel can be used to show a variety of content. Here's an example of a detail panel rendering charts with the [MUI X Charts](https://mui.com/x/react-charts/getting-started/) library.
+
+> Live example: `chart-detail-panel` (call get_mrt_example with that id).
+
+### Detail Panels with Virtualization
+
+> New in v2.6.0
+
+If you are using row virtualization, detail panels will now work more properly as of version 2.6.0. However, there are some caveats to be aware of. In order for row virtualization to work well, many of the animation/transitions have been disabled. This means that the detail panel will not animate open and closed. It will simply appear and disappear.
+
+You also may need to specify some more accurate row height estimations for the row virtualizer in order to achieve the best scrollbar behavior. See the [Row Virtualization Guide](/docs/guides/row-virtualization) for the full details on this topic, but here's an example of how you might do that.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  enableRowVirtualization: true,
+  renderDetailPanel: ({ row }) => <DetailPanelContent />,
+  rowVirtualizerOptions: ({ table }) => {
+    const { density, expanded } = table.getState();
+    return {
+      //adjust to your needs
+      estimateSize: (index) =>
+        index % 2 === 1 //even rows are normal rows, odd rows are detail panels
+          ? //Estimate open detail panels as 80px tall, closed detail panels as 0px tall
+            expanded === true
+            ? 80
+            : 0
+          : //estimate normal row heights
+            density === 'compact'
+            ? 37
+            : density === 'comfortable'
+              ? 58
+              : 73,
+    };
+  },
+});
+```
+
+> Live example: `enable-detail-panel-virtualized` (call get_mrt_example with that id).
+
+### Lazy Detail Panels
+
+Fetching the additional data for the detail panels only after the user clicks to expand the row can be a good way to improve performance, and it is pretty easy to implement. It's even easier if you are using React Query.
+
+> Live example: `lazy-detail-panel` (call get_mrt_example with that id).
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-detail-panel-examples-)**

package/data/guides/display-columns.md

@@ -0,0 +1,135 @@
+## Display (Built-in) Columns Guide
+
+Display columns are used to display non-data elements in a table. They only require an `id` and `header` in the column definition. They do not need an `accessorKey` or `accessorFn`, as they are not meant to connect to your data at all.
+
+Display columns do not have any processing features, such as sorting, filtering, grouping, etc. enabled on them by default.
+
+### Relevant Table Options
+
+Relevant table options (get_mrt_api has full details):
+
+- `defaultDisplayColumn` - type `Partial<MRT_DisplayColumnDef<TData>>` - Default column options to use for all display column defs supplied to the table. This is useful for providing default cell/header/footer renderers, or turning on or off certain features for all display columns.
+- `displayColumnDefOptions` - type `{ [key: string]: MRT_DisplayColumnDef<TData> }` - Customize and override the column definition options for the built-in display columns. (Select, Expand, Row Actions, etc.)
+
+### Built-in MRT Display Columns
+
+Material React Table has a few built-in display columns that are created automatically when certain features are enabled.
+
+- `mrt-row-pin` - created when `enableRowPinning` table option is `true` with certain `rowPinningDisplayMode` values
+- `mrt-row-drag` - created when `enableRowDragging` or `enableRowOrdering` table option are `true`
+- `mrt-row-actions` - created when `enableRowActions` (or sometimes when `enableEditing`) props are `true`
+- `mrt-row-expand` - created when `enableExpanding`, `enableGrouping`, or `renderDetailPanel` props are `true`
+- `mrt-row-select` - created when `enableRowSelection` table option is `true`
+- `mrt-row-numbers` - created when `enableRowNumbers` table option is `true`
+- `mrt-row-spacer` - created when `layoutMode` is `"grid-no-grow"` (column resizing)
+
+Display columns are, for the most part, the same as a data column, except they do not have an accessor to access data. When a display column is created internally by Material React Table, the following options are all set to false by default:
+
+```tsx
+const defaultDisplayColumnDefOptions = {
+  columnDefType: 'display',
+  enableClickToCopy: false,
+  enableColumnActions: false,
+  enableColumnDragging: false,
+  enableColumnFilter: false,
+  enableColumnOrdering: false,
+  enableEditing: false,
+  enableGlobalFilter: false,
+  enableGrouping: false,
+  enableHiding: false,
+  enableResizing: false,
+  enableSorting: false,
+} as Partial<MRT_ColumnDef>;
+```
+
+All of these values are able to be overridden if needed, and you'll learn about that in the next section down below.
+
+### Customize Built-in MRT Display Columns
+
+It is possible to change and override the default behavior of built-in display columns. Whether you want to change the default column width, add some styles, or enable some features, such as column actions or column drag and drop, you can do it with the `displayColumnDefOptions` table option.
+
+#### Default Display Column Table Option
+
+First of all, if you want to enable or disable some feature for all display columns, you can just use the `defaultDisplayColumn` table option. This will apply to all display columns, including any custom display columns you create.
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  defaultDisplayColumn: {
+    enableColumnOrdering: true,
+    enableColumnResizing: true,
+    minSize: 100,
+  },
+});
+```
+
+#### Display Column Definition Options Table Option
+
+Let's say you need to adjust the width of the Actions column to be wide enough to fit all of your action buttons. You could do that as follows:
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  displayColumnDefOptions: { 'mrt-row-actions': { size: 300 } }, //change width of actions column to 300px
+  enableRowActions: true,
+  renderRowActions: ({ row }) => (
+    <Box>
+      <Button>Action 1</Button>
+      <Button>Action 2</Button>
+      <Button>Action 3</Button>
+    </Box>
+  ),
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+Or maybe you want to enable a feature that is off by default for display columns, such as column ordering or pinning.
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  displayColumnDefOptions: {
+    'mrt-row-numbers': {
+      enableOrdering: true,
+      enablePinning: true,
+      enableColumnActions: true,
+      size: 40,
+      grow: true, //new in v2.8
+    },
+  },
+  enableRowNumbers: true,
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+Here is a full example and demo for customizing display columns.
+
+> Live example: `customize-display-columns` (call get_mrt_example with that id).
+
+### Create your own Display Columns
+
+You do not have to use the built in Row Actions feature. You can just create your own display columns instead. It is as easy as creating a normal column, only specifying the `columnDefType` as `display`.
+
+```jsx
+const columns = [
+  {
+    id: 'sendEmail',
+    header: 'Send Email',
+    columnDefType: 'display', //turns off data column features like sorting, filtering, etc.
+    enableColumnOrdering: true, //but you can turn back any of those features on if you want like this
+    Cell: ({ row }) => (
+      <Button onClick={() => sendEmail(row.original.userId)}>Send Email</Button>
+    ),
+  },
+  {
+    id: 'name',
+    header: 'Name',
+    accessorKey: 'name',
+  },
+];
+```