@mini_7/material-react-table-mcp 4.0.0

package/data/guides/sorting.md

@@ -0,0 +1,190 @@
+## Sorting Feature Guide
+
+Material React Table supports almost any sorting scenario you may have. Client-side sorting is enabled by default, but you can opt to implement your own server-side sorting logic or even replace the default client-side sorting with your own implementation.
+
+### Relevant Table Options
+
+Relevant table options (get_mrt_api has full details):
+
+- `enableGlobalFilterRankedResults` - type `boolean` - default `true`
+- `enableMultiSort` - type `boolean`
+- `enableSorting` - type `boolean` - default `true`
+- `enableSortingRemoval` - type `boolean` - default `true`
+- `isMultiSortEvent` - type `(e: unknown) => boolean` - Pass a custom function that will be used to determine if a multi-sort event should be triggered. It is passed the event from the sort toggle handler and should return true if the event should trigger a multi-sort.
+- `manualSorting` - type `boolean` - Enables manual sorting for the table. If this is true, you will be expected to sort your data before it is passed to the table. This is useful if you are doing server-side sorting.
+- `maxMultiSortColCount` - type `number` - Set a maximum number of columns that can be multi-sorted.
+- `onSortingChange` - type `OnChangeFn<SortingState>` - If provided, this function will be called with an updaterFn when state.sorting changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table.
+- `sortDescFirst` - type `boolean` - Set to true for sorting toggles on this column to start in the descending direction.
+- `sortFns` - type `Record<string, SortFn>` - This option allows you to define custom sorting functions that can be referenced in a column's sortFn option by their key. Example:
+
+### Relevant Column Options
+
+Relevant column options (get_mrt_api has full details):
+
+- `enableMultiSort` - type `boolean` - default `true`
+- `enableSorting` - type `boolean`
+- `invertSorting` - type `boolean` - default `false`
+- `sortDescFirst` - type `boolean`
+- `sortFn` - type `SortingFnOption`
+- `sortUndefined` - type `'first' | 'last' | false | 1 | -1`
+
+### Relevant State Options
+
+Relevant state options (get_mrt_api has full details):
+
+- `sorting` - type `Array<{ id: string, desc: boolean }>` - default `[]`
+
+### Disable Sorting
+
+Sorting can be disabled globally by setting the `enableSorting` table option to `false`. This will disable sorting for all columns. You can also disable sorting for individual columns by setting the `enableSorting` column option to `false`.
+
+```tsx
+const columns = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    enableSorting: false, // disable sorting for this column
+  },
+];
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableSorting: false, //disable sorting for all columns
+});
+```
+
+### Initial/Default Sorting
+
+You can sort by a column or multiple columns by default by setting the `sorting` state option in either the `initialState` or `state` props.
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  initialState: {
+    sorting: [
+      {
+        id: 'age', //sort by age by default on page load
+        desc: true,
+      },
+      {
+        id: 'lastName', //then sort by lastName if age is the same
+        desc: true,
+      },
+    ],
+  },
+});
+```
+
+### Default Sorting Features
+
+Client-side sorting is enabled by default. When sorting is toggled on for a column, the table will be sorted by the [`basic` sorting algorithm](https://tanstack.com/table/v9/docs/framework/react/guide/sorting) by default.
+
+#### Multi-Sorting
+
+Multi-sorting is also enabled by default, which means you can sort by multiple columns at once. You can do this by clicking on a column header while holding down the `shift` key. The table will then be sorted by the previously sorted column, followed by the newly clicked column. Alternatively, if you want multi-sorting to be the default click behavior without the need to hold `shift`, you can set the `isMultiSortEvent` table option to `() => true`.
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  isMultiSortEvent: () => true, //multi-sorting will be the default click behavior without the need to hold shift
+});
+```
+
+You can limit the number of columns that can be sorted at once by setting the `maxMultiSortColCount` prop, or you can disable multi-sorting entirely by setting the `enableMultiSort` table option to `false`.
+
+#### Sorting Removal
+
+By default, users can remove a sort on a column by clicking through the sort direction options or selecting "Clear Sort" from the column actions menu. You can disable this feature by setting the `enableSortingRemoval` table option to `false`.
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableSortingRemoval: false, //users will not be able to remove a sort on a column
+});
+```
+
+#### Sort Direction
+
+By default, columns with `string` datatypes will sort alphabetically in ascending order, but columns with `number` datatypes will sort numerically in descending order. You can change the default sort direction per column by specifying the `sortDescFirst` column option to either `true` or `false`. You can also change the default sort direction globally by setting the `sortDescFirst` table option to either `true` or `false`.
+
+> Live example: `multi-sorting` (call get_mrt_example with that id).
+
+### Sorting Functions
+
+By default, Material React Table will use the `basic` sorting function for all columns.
+
+There are six built-in sorting functions you can choose from: ` alphanumeric`, `alphanumericCaseSensitive`, `text`, `textCaseSensitive`, `datetime`, and `basic`. You can learn more about these built-in sorting functions in the [TanStack Table Sorting API docs](https://tanstack.com/table/v9/docs/framework/react/guide/sorting).
+
+#### Add Custom Sorting Functions
+
+If none of these sorting functions meet your needs, you can add your own custom sorting functions by specifying more sorting functions in the `sortFns` table option.
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  sortFns: {
+    //will add a new sorting function to the list of other sorting functions already available
+    myCustomSortingFn: (rowA, rowB, columnId) => // your custom sorting logic
+  },
+})
+```
+
+#### Change Sorting Function Per Column
+
+You can now choose a sorting function for each column by either passing a string value of the built-in sorting function names to the `sortFn` column option or by passing a custom sorting function to the `sortFn` column option.
+
+```tsx
+const columns = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    sortFn: 'textCaseSensitive', //use the built-in textCaseSensitive sorting function instead of the default basic sorting function
+  },
+  {
+    accessorKey: 'age',
+    header: 'Age',
+    //use your own custom sorting function instead of any of the built-in sorting functions
+    sortFn: (rowA, rowB, columnId) => // your custom sorting logic
+  },
+];
+```
+
+### Manual Server-Side Sorting
+
+If you are working with large data sets, you may want to let your back-end APIs handle all of the sorting and pagination processing instead of doing it client-side. You can do this by setting the `manualSorting` table option to `true`. This will disable the default client-side sorting and pagination features and will let you implement your own sorting and pagination logic.
+
+> When `manualSorting` is set to `true`, Material React Table assumes that your `data` is already sorted by the time you are passing it to the table.
+
+If you need to sort your data in a back-end API, then you will also probably need access to the internal `sorting` state from the table. You can do this by managing the `sorting` state yourself and then passing it to the table via the `state` table option. You can also pass a callback function to the `onSortingChange` prop, which will be called whenever the `sorting` state changes internally in the table
+
+```jsx
+const [sorting, setSorting] = useState([]);
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  manualSorting: true,
+  state: { sorting },
+  onSortingChange: setSorting,
+});
+
+useEffect(() => {
+  //do something with the sorting state when it changes
+  //or use table.getState().sorting
+}, [sorting]);
+
+return <MaterialReactTable table={table} />;
+```
+
+#### Remote Sorting Example
+
+Here is the full Remote Data example showing how to implement server-side sorting, filtering, and pagination with Material React Table.
+
+> Live example: `remote` (call get_mrt_example with that id).
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-sorting-examples)**

package/data/guides/state-management.md

@@ -0,0 +1,165 @@
+## State Management Guide
+
+> Note: `tableInstanceRef` has been removed in MRT v2 since the `useMaterialReactTable` hook now returns the table instance directly. See the [Migration Guide](/migrating-to-v2) for more information.
+
+Material React Table does not try to hide any of its internal state from you. You can initialize state with custom initial values, manage individual states yourself as you discover the need to have access to them, or read any of the state from the table instance itself.
+
+This is all optional, of course. If you do not need access to any of the internal state, you do not need to do anything and it will just automatically be managed internally.
+
+See the [State Options API Docs](/docs/api/state-options) for more information on which states are available for you to manage.
+
+### Relevant Table Options
+
+Relevant table options (get_mrt_api has full details):
+
+- `initialState` - type `Partial<MRT_TableState<TData>>` - Use this option to optionally pass initial state to the table. This state will be used when resetting various table states either automatically by the table (eg. options.autoResetPagination) or via functions like table.resetRowSelection(). Most reset function allow you optionally pass a flag to reset to a blank/default state instead of the initial state. Table state will not be reset when this object changes, which also means that the initial state object does not need to be stable.
+- `state` - type `Partial<MRT_TableState<TData>>`
+
+### Populate Initial State
+
+If all you care about is setting parts of the initial or default state when the table mounts, then you may be able to specify that state in the `initialState` table option and not have to worry about managing the state yourself.
+
+For example, let's say you do not need access to the `showColumnFilters` state, but you want to set the default value to `true` when the table mounts. You can do that with the `initialState` table option:
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  initialState: {
+    density: 'xs', //set default density to compact
+    expanded: true, //expand all rows by default
+    pagination: { pageIndex: 0, pageSize: 15 }, //set different default page size
+    showColumnFilters: true, //show filters by default
+    sorting: [{ id: 'name', desc: false }], //sort by name ascending by default
+  },
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+> Note: If you use both `initialState` and `state`, the state initializer in `state` table option will take precedence and overwrite the same state values in `initialState`. So just use either `initialState` or `state`, not both for the same states.
+
+### Manage Individual States as Needed
+
+It is pretty common to need to manage certain state yourself, so that you can react to changes in that state, or have easy access to it when sending it to an API.
+
+You can pass in any state that you are managing yourself to the `state` table option, and it will be used instead of the internal state. Each state property option also has a corresponding `on[StateName]Change` callback that you can use set/update your managed state as it changes internally in the table.
+
+For example, let's say you need to store the pagination, sorting, and row selection states in a place where you can easily access it in order to use it in parameters for an API call.
+
+```jsx
+const [pagination, setPagination] = useState({
+  pageIndex: 0,
+  pageSize: 15, //set different default page size by initializing the state here
+});
+const [rowSelection, setRowSelection] = useState({});
+const [sorting, setSorting] = useState([{ id: 'name', desc: false }]);
+
+//see example at bottom of page for alternatives to useEffect here
+useEffect(() => {
+  //do something when the pagination state changes
+}, [pagination]);
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  getRowId: (originalRow) => row.username,
+  onPaginationChange: setPagination,
+  onRowSelectionChange: setRowSelection,
+  onSortingChange: setSorting,
+  state: { pagination, rowSelection, sorting }, //must pass states back down if using their on[StateName]Change callbacks
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+### Add Side Effects in Set State Callbacks
+
+In React 18 and beyond, it is becoming more discouraged to use `useEffect` to react to state changes, because in React Strict Mode (and maybe future versions of React), the useEffect hook may run twice per render. Instead, more event driven functions are recommended to be used. Here is an example for how that looks here. The callback signature for the `on[StateName]Change` works just like a React setState callback from the `useState` hook. This means that you have to check if the updater is a function or not, and then call the setState function with the updater callback if it is a function.
+
+```tsx
+const [pagination, setPagination] = useState({
+  pageIndex: 0,
+  pageSize: 15,
+});
+
+const handlePaginationChange = (updater: MRT_Updater<PaginationState>) => {
+  //call the setState as normal, but need to check if using an updater callback with a previous state
+  setPagination((prevPagination) =>
+    //if updater is a function, call it with the previous state, otherwise just use the updater value
+    updater instanceof Function ? updater(prevPagination) : updater,
+  );
+  //put more code for your side effects here, guaranteed to only run once, even in React Strict Mode
+};
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  onPaginationChange: handlePaginationChange,
+  state: { pagination },
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+### Read From the Table Instance
+
+> Note: Previously, in early MRT v1, you could use the `tableInstanceRef` table option to get access to the table instance. This is no longer necessary as the `useMaterialReactTable` hook now just returns the table instance directly.
+
+The `useMaterialReactTable` hook returns the table instance. The `<MaterialReactTable />` needs the table instance for all of its internal logic, but you can also use it for your own purposes.
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  //...
+});
+
+const someEventHandler = (event) => {
+  console.info(table.getRowModel().rows); //example - get access to all page rows in the table
+  console.info(table.getSelectedRowModel()); //example - get access to all selected rows in the table
+  console.info(table.getState().sorting); //example - get access to the current sorting state without having to manage it yourself
+};
+
+return (
+  <div>
+    <ExternalButton onClick={someEventHandler}>
+      Export or Something
+    </ExternalButton>
+    <MaterialReactTable table={table} />
+  </div>
+);
+```
+
+The table instance is the same object that you will also see as a provided parameter in many of the other callback functions throughout Material React Table, such as all the `render...` props or the `Cell` or `Header` render overrides in the column definition options.
+
+```jsx
+const columns = useMemo(
+  () => [
+    {
+      Header: 'Name',
+      accessor: 'name',
+      Cell: ({ cell, table }) => <span>{cell.getValue()}</span>,
+      //The `table` parameter from the Cell option params and the `table` are the same object
+    },
+  ],
+  [],
+);
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  renderTopToolbarCustomActions: ({ table }) => {
+    //The `table` parameter here and the table returned from the hook are the same object
+    return <Button>Button</Button>;
+  },
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+### Persistent State
+
+Persistent state is not a built-in feature of Material React Table, but it is an easy feature to implement yourself using the above patterns with the `state` table option and the `on[StateName]Change` callbacks. Here is an example of how you might implement persistent state using `sessionStorage`:
+
+> Live example: `persistent-state` (call get_mrt_example with that id).

package/data/guides/sticky-header.md

@@ -0,0 +1,41 @@
+## Sticky Header and Footer Feature Guide
+
+The sticky header and footer feature allows you to keep the header and footer of the table visible while scrolling through the table. This is useful when you have a large table and want to keep the header and footer visible at all times.
+
+### Relevant Table Options
+
+Relevant table options (get_mrt_api has full details):
+
+- `enableStickyFooter` - type `boolean`
+- `enableStickyHeader` - type `boolean`
+
+### Enable Sticky Header
+
+Enabling the sticky header is as simple as setting the `enableStickyHeader` table option to `true`. This will make the header of the table stick to the top and remain visible while scrolling through the table.
+
+When the sticky header is enabled, you will probably also want to give the table a maxHeight so that the table can scroll vertically and keep the header visible. You can do this by styling the table container with the `muiTableContainerProps` table option.
+
+> If no maxHeight is specified, the table container will default to a `100vh` maxHeight when `enableStickyHeader` is enabled.
+
+```tsx
+<MaterialReactTable
+  columns={columns}
+  data={data}
+  enableStickyHeader
+  muiTableContainerProps={{ sx: { maxHeight: '500px' } }}
+/>
+```
+
+### Enable Sticky Footer
+
+Similarly, enabling the sticky footer is as simple as setting the `enableStickyFooter` table option to `true`. This will make the footer of the table stick to the bottom of the table and always be visible, even before the table is scrolled to the bottom.
+
+```tsx
+<MaterialReactTable columns={columns} data={data} enableStickyFooter />
+```
+
+### Enable Sticky Header and Footer Demo
+
+> Live example: `enable-sticky-header` (call get_mrt_example with that id).
+
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/styling-sticky-header-examples)**

package/data/guides/table-event-listeners.md

@@ -0,0 +1,103 @@
+## Table Event Listeners Guide
+
+You can pretty much add ANY event listener to ANY component in Material React Table.
+
+You can do this by passing props to any of the `mui...Props` props. This guide gives a few examples of the most common use cases, but there are limitless possibilities.
+
+### Add Event Listeners to any of the Material UI Components
+
+In the [customize components docs](/docs/guides/customize-components#material-ui-prop-types), we explained how to pass any prop you need to pass to any exposed Material UI component that is in the table. The list of props that you can pass to Material UI components includes any event listener.
+
+Here are a few common examples of some useful event listeners you might want to add to the table, although the possibilities are countless.
+
+#### Add an onClick to a Table Row
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiTableBodyRowProps: ({ row }) => ({
+    onClick: (event) => {
+      console.info(event, row.id);
+    },
+    sx: {
+      cursor: 'pointer', //you might want to change the cursor too when adding an onClick
+    },
+  }),
+});
+```
+
+#### Add an onDoubleClick to a Table Cell
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiTableBodyCellProps: ({ cell }) => ({
+    onDoubleClick: (event) => {
+      console.info(event, cell.id);
+    },
+  }),
+});
+```
+
+#### Add an onBlur to an Edit TextField
+
+```jsx
+//add to every edit text field
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiEditTextFieldProps: ({ cell }) => ({
+    onBlur: (event) => {
+      console.info(event, cell.id);
+    },
+  }),
+});
+```
+
+```jsx
+//or add to just edit text fields in a specific column
+const columns = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    muiEditTextFieldProps: ({ cell }) => ({
+      onBlur: (event) => {
+        console.info(event);
+      },
+    }),
+  },
+];
+```
+
+#### Add an onChange to an Edit TextField
+
+> Warning: Be careful when using onChange, as it can trigger re-renders with every keystroke, which can lead to performance issues
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiEditTextFieldProps: ({ cell }) => ({
+    onChange: (event) => {
+      console.info(event, cell.id);
+    },
+  }),
+});
+```
+
+```jsx
+//or add to just edit text fields in a specific column
+const columns = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    muiEditTextFieldProps: ({ cell }) => ({
+      onChange: (event) => {
+        console.info(event);
+      },
+    }),
+  },
+];
+```