@mini_7/material-react-table-mcp 4.0.0

package/data/guides/toolbar-customization.md

@@ -0,0 +1,251 @@
+## Toolbar Customization Guide
+
+This guide shows you how to [hide](#hide-or-disable-toolbars), [customize](#customize-toolbar-buttons), or [override](#override-with-custom-toolbar-components) the top and bottom toolbars in Material React Table.
+
+> Note: This guide has become much more simple since the introduction of the `useMaterialReactTable` hook in v2. <br />
+> No more `tableInstanceRef` or `useReducer` rerender hacks required!
+
+### Relevant Table Options
+
+Relevant table options (get_mrt_api has full details):
+
+- `enableBottomToolbar` - type `boolean` - default `true`
+- `enableToolbarInternalActions` - type `boolean` - default `true`
+- `enableTopToolbar` - type `boolean` - default `true`
+- `muiBottomToolbarProps` - type `BoxProps | ({ table }) => BoxProps`
+- `muiLinearProgressProps` - type `LinearProgressProps | ({ isTopToolbar, table }) => LinearProgressProps`
+- `muiToolbarAlertBannerChipProps` - type `ChipProps| ({ table }} => ChipProps`
+- `muiToolbarAlertBannerProps` - type `AlertProps | ({ table }) => AlertProps`
+- `muiTopToolbarProps` - type `BoxProps | ({ table }) => BoxProps`
+- `positionGlobalFilter` - type `'left' | 'right'` - default `'right'`
+- `positionPagination` - type `'bottom' | 'top' | 'both'` - default `'bottom'`
+- `positionToolbarAlertBanner` - type `'bottom' | 'top' | 'none'` - default `'top'`
+- `positionToolbarDropZone` - type `'bottom' | 'top' | 'both' | 'none'` - default `'top'`
+- `renderBottomToolbar` - type `ReactNode | ({ table }) => ReactNode`
+- `renderBottomToolbarCustomActions` - type `({ table }) => ReactNode`
+- `renderToolbarAlertBannerContent` - type `({ table, groupedAlert, selectedAlert }) => ReactNode`
+- `renderToolbarInternalActions` - type `({ table}) => ReactNode`
+- `renderTopToolbar` - type `ReactNode | ({ table }) => ReactNode`
+- `renderTopToolbarCustomActions` - type `({ table }) => ReactNode`
+
+### Relevant State
+
+Relevant state options (get_mrt_api has full details):
+
+- `showAlertBanner` - type `boolean` - default `false`
+- `showProgressBars` - type `boolean` - default `false`
+
+### Hide or Disable Toolbars
+
+There are `enableTopToolbar` and `enableBottomToolbar` table options that you can use to show or hide the toolbars.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  enableTopToolbar: false,
+  enableBottomToolbar: false,
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+Alternatively, you could just use a different MRT component that does not have the toolbars built-in. For example, use the `<MRT_TableContainer />` or `<MRT_Table />` components instead of the `<MaterialReactTable />` component.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+});
+
+//This MRT sub-component does not contain the code for the toolbars. MRT_TablePaper and MaterialReactTable do.
+return <MRT_TableContainer table={table} />;
+```
+
+#### No Toolbars Example
+
+> Live example: `minimal` (call get_mrt_example with that id).
+
+### Customize Toolbar buttons
+
+Everything in the toolbars are customizable. You can add your own buttons or change the order of the built-in buttons.
+
+#### Customize Built-In Internal Toolbar Button Area
+
+The `renderToolbarInternalActions` table option allows you to redefine the built-in buttons that usually reside in the top right of the top toolbar. You can reorder the icon buttons or even insert your own custom buttons. All of the built-in buttons are available to be imported from 'material-react-table'.
+
+```jsx
+import {
+  MaterialReactTable,
+  MRT_ShowHideColumnsButton,
+  MRT_ToggleFullScreenButton,
+} from 'material-react-table';
+
+const table = useMaterialReactTable({
+  data,
+  columns,
+  renderToolbarInternalActions: ({ table }) => (
+    <>
+      {/* add your own custom print button or something */}
+      <IconButton onClick={() => showPrintPreview(true)}>
+        <PrintIcon />
+      </IconButton>
+      {/* built-in buttons (must pass in table prop for them to work!) */}
+      <MRT_ShowHideColumnsButton table={table} />
+      <MRT_ToggleFullScreenButton table={table} />
+    </>
+  ),
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+#### Add Custom Toolbar Buttons/Components
+
+The `renderTopToolbarCustomActions` and `renderBottomToolbarCustomActions` table options allow you to add your own custom buttons or components to the top and bottom toolbar areas. These props are functions that return a ReactNode. You can add your own buttons or whatever components you want.
+
+In all of these `render...` table options, you get access to the `table` instance that you can use to perform actions or extract data from the table.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  enableRowSelection: true,
+  //Simply adding a table title to the top-left of the top toolbar
+  renderTopToolbarCustomActions: () => (
+    <Typography variant="h3">Customer's Table</Typography>
+  ),
+  //Adding a custom button to the bottom toolbar
+  renderBottomToolbarCustomActions: ({ table }) => (
+    <Button
+      variant="contained"
+      color="lightblue"
+      //extract all selected rows from the table instance and do something with them
+      onClick={() => handleDownloadRows(table.getSelectedRowModel().rows)}
+    >
+      Download Selected Rows
+    </Button>
+  ),
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+#### Custom Toolbar Actions Example
+
+> Live example: `custom-top-toolbar` (call get_mrt_example with that id).
+
+### Position Toolbar Areas
+
+The `positionToolbarAlertBanner`, `positionGlobalFilter`, `positionPagination`, and `positionToolbarDropZone` table options allow you to swap the default position of certain areas of the toolbars. Experiment moving them around until you find a layout that works for you.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns
+  //if rendering top toolbar buttons, sometimes you want alerts to be at the bottom
+  positionToolbarAlertBanner: 'bottom',
+  positionGlobalFilter: 'left', //move the search box to the left of the top toolbar
+  positionPagination: 'top',
+  renderTopToolbarCustomActions: () => <Box>...</Box>,
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+### Customize Toolbar Props and Styles
+
+The `muiTopToolbarProps`, `muiBottomToolbarProps`, `muiToolbarAlertBannerProps`, and `muiToolbarAlertBannerChipProps` table options allow you to customize the props and styles of the underlying Material components that make up the toolbar components. Remember that you can pass CSS overrides to their `sx` or `style` props. Some have found this useful for forcing `position: absolute` on alerts, etc.
+
+### Customize Linear Progress Bars
+
+The progress bars that display in both the top and bottom toolbars become visible when either the `isLoading` or `showProgressBars` state options are set to `true`. You can customize the progress bars by passing in props to the `muiLinearProgressProps` table option. By default, the progress bars have a full animated progress bar, but you can set the `value` table option to a number between 0 and 100 to show real progress values if your table is doing some complicated long running tasks that you want to show progress for. Visit the [Material UI Progress docs](https://mui.com/material-ui/react-progress/) to learn more.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  muiLinearProgressProps: ({ isTopToolbar }) => ({
+    color: 'warning',
+    sx: { display: isTopToolbar ? 'block' : 'none' }, //only show top toolbar progress bar
+    value: fetchProgress, //show precise real progress value if you so desire
+  }),
+  state: {
+    isLoading,
+    showProgressBars,
+  },
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+### Customize Toolbar Alert Banner
+
+The toolbar alert banner is an internal component used to display alerts to the user. By default, it will automatically show messages around the number of selected rows or grouping state.
+
+However, you can repurpose this alert banner to show your own custom messages too. You can force the alert banner to show by setting the `showAlertBanner` state option to `true`. You can then customize the messages and other stylings using the `muiToolbarAlertBannerProps` to create your custom message. You probably saw this in the [Remote Data](/docs/examples/remote) or [React Query](/docs/examples/react-query) examples.
+
+```jsx
+const table = useMaterialReactTable({
+  data,
+  columns,
+  //show a custom error message if there was an error fetching data in the top toolbar
+  muiToolbarAlertBannerProps: isError
+    ? {
+        color: 'error',
+        children: 'Network Error. Could not fetch data.',
+      }
+    : undefined,
+  state: {
+    showAlertBanner: isError,
+    showProgressBars: isFetching,
+  },
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+### Override with Custom Toolbar Components
+
+If you want to completely override the default toolbar components, you can do so by passing in your own custom components to the `renderTopToolbar` and `renderBottomToolbar` props.
+
+The drawback to this approach is that you will not get all the automatic features of the default toolbar components, such as the automatic alert banner, progress bars, etc. You will have to implement all of that yourself if you still want those features. Though you can also just import those MRT components and use them in your custom toolbar.
+
+```jsx
+import {
+  MRT_GlobalFilterTextInput, //import MRT sub components!
+  MRT_TablePagination,
+  MaterialReactTable,
+  useMaterialReactTable,
+} from 'material-react-table';
+
+const table = useMaterialReactTable({
+  data,
+  columns,
+  renderTopToolbar: ({ table }) => (
+    <Box
+      sx={{
+        display: 'flex',
+        justifyContent: 'space-between',
+        alignItems: 'center',
+      }}
+    >
+      <MRT_GlobalFilterTextInput table={table} />
+      <MRT_TablePagination table={table} />
+    </Box>
+  ),
+  renderBottomToolbar: ({ table }) => (
+    <Box>
+      <Button>Download</Button>
+    </Box>
+  ),
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+### Build Your Own Toolbar
+
+Instead of overriding the toolbar components up above, you may want 100% control over the layout and styling of your table controls and where they are on the page. You can do this by just using a MRT sub component such as `<MRT_TableContainer />` for the table component, which does not have the internal toolbar components built-in. Optionally, build your own custom toolbar components using the other MRT sub components.
+
+> Live example: `external-toolbar` (call get_mrt_example with that id).

package/data/guides/virtualization.md

@@ -0,0 +1,183 @@
+## Virtualization Feature Guide
+
+> MRT v1.4 and v1.5 have major virtualization upgrades after switching to `@tanstack/react-virtual` v3.0!
+
+Virtualization is useful when you have a lot of data you want to display client-side all at once without having to use pagination. Material React Table makes this as simple as possible, thanks to [`@tanstack/react-virtual`](https://tanstack.com/virtual/v3) with both [row virtualization](#enable-row-virtualization) and [column virtualization](#enable-column-virtualization) support.
+
+> NOTE: You should only enable row virtualization if you have a large number of rows. Depending on the size of the table, if you are rendering less than a couple dozen rows at a time, you will actually just be adding extra overhead to the table renders. Virtualization only becomes necessary when you have more than 50 rows or so at the same time with no pagination.
+
+### Relevant Table Options
+
+Relevant table options (get_mrt_api has full details):
+
+- `columnVirtualizerInstanceRef` - type `MutableRefObject<Virtualizer | null>`
+- `columnVirtualizerOptions` - type `Partial<VirtualizerOptions<HTMLDivElement, HTMLTableCellElement>>`
+- `enableColumnVirtualization` - type `boolean` - Enables column virtualization and creates an MRT_ColumnVirtualizer instance internally. This option CANNOT be enabled conditionally. Other side effects include layoutMode will be set either to "grid" or "grid-no-grow"
+- `enableRowVirtualization` - type `boolean` - Enables row virtualization and creates an MRT_RowVirtualizer instance internally. This option CANNOT be enabled conditionally. Other side effects include layoutMode will be set either to "grid" or "grid-no-grow"
+- `rowVirtualizerInstanceRef` - type `MutableRefObject<Virtualizer | null>`
+- `rowVirtualizerOptions` - type `Partial<VirtualizerOptions<HTMLDivElement, HTMLTableRowElement>>`
+
+### What is Virtualization?
+
+Virtualization, or virtual scrolling, works by only rendering the rows or columns that are visible on the screen. This is useful for performance and user experience, as we can make it appear that there are hundreds, thousands, or even tens of thousands of rows in the table all at once, but in reality, the table will only render the couple dozen rows that are visible on the screen, or the handful of columns that are visible on the screen.
+
+For more reading on the concept of virtualization, we recommend this [blog post](https://blog.logrocket.com/virtual-scrolling-core-principles-and-basic-implementation-in-react/) by LogRocket.
+
+### Does Your Table Even Need Virtualization?
+
+If your table is paginated or you are not going to render more than 50 rows at once, you probably do not need row virtualization.
+
+If your table does not have more than 12 columns, you probably do not need column virtualization.
+
+There is a slight amount of extra overhead that gets added to your table's rendering when virtualization is enabled, so do not just enable it for every table. That being said, if your table does have well more than 100 rows that it is trying to render all at once without pagination, performance should improve significantly once it has been enabled.
+
+### Enable Row Virtualization
+
+Enabling row virtualization is as simple as setting the `enableRowVirtualization` table option to `true`. However, you will probably also want to turn off pagination, which you can do by setting `enablePagination` to `false`.
+
+```tsx
+<MaterialReactTable
+  columns={columns}
+  data={data}
+  enablePagination={false}
+  enableRowVirtualization
+/>
+```
+
+Take a look at the example below with 10,000 rows!
+
+> Live example: `enable-row-virtualization` (call get_mrt_example with that id).
+
+### Enable Column Virtualization
+
+Enabling column virtualization is also as simple as setting the `enableColumnVirtualization` table option to `true`.
+
+```tsx
+<MaterialReactTable columns={columns} data={data} enableColumnVirtualization />
+```
+
+Take a look at the example below with 500 columns!
+
+> Live example: `enable-column-virtualization` (call get_mrt_example with that id).
+
+> WARNING: Do not enable row or column virtualization conditionally. This could break React's Rule of Hooks and/or cause other UI jumpiness.
+
+### Virtualization Side Effects
+
+When either row or column virtualization is enabled, a few other props automatically get set internally.
+
+#### `layoutMode` Prop
+
+In MRT Versions 1.3 and earlier, a CSS `table-layout: fixed` style was automatically added to the `<table>` element to prevent columns from wiggling back and forth during scrolling due to body cells having varying widths.
+
+But now in MRT Versions 1.4 and later, the `layoutMode` table option is automatically set to the `'grid'` value when either row or column virtualization is enabled, which means that all of the table markup will use CSS Grid and Flexbox instead of the traditional semantic styles that usually come with table tags. This is necessary to make the virtualization work properly with decent performance.
+
+#### `enableStickyHeader` Prop
+
+The `enableStickyHeader` table option is automatically set to `true` when row virtualization is enabled. This keeps the table header sticky and visible while scrolling and adds a default max-height of 100vh to the table container.
+
+### Customize Virtualizer Props
+
+You can adjust some of the virtualizer props that are used internally with the `rowVirtualizerOptions` and `columnVirtualizerOptions` props. The most useful virtualizer props are the `overscan` and `estimateSize` options. You may want to adjust these values if you have unusual row heights or column widths that are causing the default scrolling to behave strangely.
+
+```jsx
+<MaterialReactTable
+  columns={columns}
+  data={data}
+  enableColumnVirtualization
+  enablePagination={false}
+  enableRowVirtualization
+  columnVirtualizerOptions={{
+    overscan: 5, //adjust the number of columns that are rendered to the left and right of the visible area of the table
+    estimateSize: () => 400, //if your columns are wider or , try tweaking this value to make scrollbar size more accurate
+  }}
+  rowVirtualizerOptions={{
+    overscan: 10, //adjust the number or rows that are rendered above and below the visible area of the table
+    estimateSize: () => 100, //if your rows are taller than normal, try tweaking this value to make scrollbar size more accurate
+  }}
+/>
+```
+
+See the official TanStack [Virtualizer Options API Docs](https://tanstack.com/virtual/v3/docs/api/virtualizer#optional-options) for more information.
+
+> MRT v1.4 upgraded from `react-virtual` v2 to `@tanstack/react-virtual` v3.0, which has some breaking changes and virtualizer option name changes. TypeScript hints should help you with any prop name changes, but you can also view the official [TanStack Virtual Docs](https://tanstack.com/virtual/v3/docs/api/virtualizer#optional-options) for guidance.
+
+### Access Underlying Virtualizer Instances
+
+In a similar way that you can [access the underlying table instance](/docs/guides/table-state-management#access-the-underlying-table-instance-reference), you can also access the underlying virtualizer instances. This can be useful for accessing methods like the `scrollToIndex` method, which can be used to programmatically scroll to a specific row or column.
+
+```tsx
+const columnVirtualizerInstanceRef = useRef<MRT_ColumnVirtualizer>(null);
+const rowVirtualizerInstanceRef = useRef<MRT_RowVirtualizer>(null);
+
+useEffect(() => {
+  if (rowVirtualizerInstanceRef.current) {
+    //scroll to the top of the table when sorting changes
+    rowVirtualizerInstanceRef.current.scrollToIndex(0);
+  }
+}, [sorting]);
+
+return (
+  <MaterialReactTable
+    columns={columns}
+    data={data}
+    enableColumnVirtualization
+    enableRowVirtualization
+    rowVirtualizerInstanceRef={rowVirtualizerInstanceRef}
+    columnVirtualizerInstanceRef={columnVirtualizerInstanceRef}
+  />
+);
+```
+
+See the official TanStack [Virtualizer Instance API Docs](https://tanstack.com/virtual/v3/docs/api/virtualizer#virtualizer-instance) for more information.
+
+### Full Row and Column Virtualization Example
+
+Try out the performance of the [fully virtualized example](/docs/examples/virtualized) with **10,000 rows** and over a dozen columns! Filtering, search, and sorting also maintain usable performance.
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-virtualization)**
+
+### Headless Virtualization with MRT Hooks
+
+If you are building a custom table in headless mode, you can still take advantage of some of the built-in virtualization functionality via the `useMRT_ColumnVirtualizer` and `useMRT_RowVirtualizer` hooks, which are wrappers for the TanStack Virtual `useVirtualizer` hook.
+
+If you go this route, you will need to consult the [TanStack Virtual Docs](https://tanstack.com/virtual/v3) for more information on the exact styles and markup needed for the virtualization to work properly.
+
+Here is the basics of how to use the MRT virtualization hooks:
+
+```tsx
+import {
+  useMaterialReactTable,
+  useMRT_Rows,
+  useMRT_RowVirtualizer,
+  useMRT_ColumnVirtualizer,
+} from 'material-react-table';
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableColumnVirtualization: true,
+  enableRowVirtualization: true,
+  columnVirtualizerOptions: {
+    //...virtualizer options
+  },
+  rowVirtualizerOptions: {
+    //...virtualizer options
+  },
+});
+
+const rows = useMRT_Rows(table); //alternative to table.getRowModel()
+
+const columnVirtualizer = useMRT_ColumnVirtualizer(table);
+const rowVirtualizer = useMRT_RowVirtualizer(table);
+
+//down in your row render
+const virtualRows = rowVirtualizer.getVirtualItems();
+
+virtualRows.map((virtualRow) => {
+  const row = rows[virtualRow.index];
+  return <Row key={row.id} />;
+});
+```
+
+Alternatively, just use the `useVirtualizer` hook directly from `@tanstack/react-virtual` if you want to build your own virtualization logic from scratch. The MRT hooks are provided as opinionated wrappers for your potential convenience.