@mini_7/material-react-table-mcp 4.0.0

package/data/guides/aggregation.md

@@ -0,0 +1,210 @@
+## Aggregation Feature Guide
+
+Material React Table has built-in aggregation features. There are options for both automatic client-side grouping and aggregation, as well as manual server-side grouping and aggregation. This guide will walk you through the different options and how to use and customize them.
+
+> See the [Column Grouping Guide](/docs/guides/column-grouping) as a prerequisite to this guide. The Aggregation and Grouping Guide was recently split into two separate guides.
+
+### Relevant Table Options
+
+Relevant table options (get_mrt_api has full details):
+
+- `aggregationFns` - type `Record<string, AggregationFn>` - This option allows you to define custom aggregation functions that can be referenced in a column's aggregationFn option by their key
+- `enableExpandAll` - type `boolean` - default `true`
+- `enableGrouping` - type `boolean`
+- `enableStickyFooter` - type `boolean`
+- `groupedColumnMode` - type `false | 'reorder' | 'remove'` - default `reorder` - Grouping columns are automatically reordered by default to the start of the columns list. If you would rather remove them or leave them as-is, set the appropriate mode here.
+- `manualGrouping` - type `boolean` - Enables manual grouping. If this option is set to true, the table will not automatically group rows using getGroupedRowModel() and instead will expect you to manually group the rows before passing them to the table. This is useful if you are doing server-side grouping and aggregation.
+- `muiToolbarAlertBannerChipProps` - type `ChipProps| ({ table }} => ChipProps`
+- `onGroupingChange` - type `OnChangeFn<GroupingState>` - If this function is provided, it will be called when the grouping state changes and you will be expected to manage the state yourself. You can pass the managed state back to the table via the tableOptions.state.grouping option.
+- `positionToolbarAlertBanner` - type `'bottom' | 'top' | 'none'` - default `'top'`
+
+### Relevant Column Options
+
+Relevant column options (get_mrt_api has full details):
+
+- `AggregatedCell` - type `({ cell, column, row, table }) => ReactNode` - Define a custom cell render for an aggregated cell.
+- `enableGrouping` - type `boolean`
+- `Footer` - type `ReactNode | ({ column, footer, table }) => ReactNode` - Render custom markup for a column footer.
+- `GroupedCell` - type `({ cell, column, row, table }) => ReactNode` - Define a custom cell render for a grouped cell.
+- `PlaceholderCell` - type `({ cell, column, row, table }) => ReactNode` - Define a custom cell render for a placeholder cell.
+
+### Relevant State
+
+Relevant state options (get_mrt_api has full details):
+
+- `expanded` - type `Record<string, boolean> | boolean` - default `{}`
+- `grouping` - type `Array<string>` - default `[]`
+
+### Aggregation on Grouped Rows
+
+One of the cool features of Material React Table is that it can automatically aggregate the data in grouped rows. To enable this, you must specify both an `aggregationFn` and an `AggregatedCell` render option on a column definition.
+
+#### Built-in Aggregation Functions
+
+There are several built-in aggregation functions available that you can use. They are:
+
+- `count` - Finds the number of rows in a group
+- `extent` - Finds the minimum and maximum values of a group of rows
+- `max` - Finds the maximum value of a group of rows
+- `mean` - Finds the average value of a group of rows
+- `median` - Finds the median value of a group of rows
+- `min` - Finds the minimum value of a group of rows
+- `sum` - sums the values of a group of rows
+- `uniqueCount` - Finds the number of unique values of a group of rows
+- `unique` - Finds the unique values of a group of rows
+
+_All of these built-in aggregation functions are from [TanStack Table](https://tanstack.com/table/v9/docs/framework/react/guide/grouping)_
+
+```jsx
+const columns = [
+  {
+    accessorKey: 'team', //grouped by team in initial state below
+    header: 'Team',
+  },
+  {
+    accessorKey: 'player',
+    header: 'Player',
+  },
+  {
+    accessorKey: 'points',
+    header: 'Points',
+    aggregationFn: 'sum', //calc total points for each team by adding up all the points for each player on the team
+    AggregatedCell: ({ cell }) => <div>Team Score: {cell.getValue()}</div>,
+  },
+];
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableGrouping: true,
+  initialState: { grouping: ['team'], expanded: true },
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+#### Custom Aggregation Functions
+
+If none of these pre-built aggregation functions work for you, you can also pass in a custom aggregation function. The aggregation function will be passed in an array of values from the column that you are aggregating. It should return a single value that will be displayed in the aggregated cell.
+
+If you are specifying a custom aggregation function, it must implement the following type:
+
+```jsx
+export type AggregationFn<TData extends AnyData> = (
+  getLeafRows: () => Row<TData>[],
+  getChildRows: () => Row<TData>[]
+) => any
+```
+
+### Aggregation on All Rows in Footer
+
+Material React Table does not automatically aggregate all rows for you to calculate totals for the entire table. However, it is still easy enough to do this manually and add in your custom calculations into the `footer` or `Footer` of a column definition. It is recommended that you do any necessary aggregation calculations on your data in a useMemo hook before passing it to the columns footer in your columns definition.
+
+```jsx
+//calculate the total points for all players in the table in a useMemo hook
+const averageScore = useMemo(() => {
+  const totalPoints = data.reduce((acc, row) => acc + row.points, 0);
+  const totalPlayers = data.length;
+  return totalPoints / totalPlayers;
+}, [data]);
+
+const columns = useMemo(
+  () => [
+    {
+      accessorKey: 'name',
+      header: 'Name',
+    },
+    {
+      accessorKey: 'score',
+      header: 'Score',
+      Footer: () => <div>Average Score: {averageScore}</div>, //do not do calculations in render, do them in useMemo hook and pass them in here
+    },
+  ],
+  [averageScore],
+);
+```
+
+> Please remember to perform heavy aggregation calculations in a useMemo hook to avoid unnecessary re-renders!
+
+### Custom Cell Renders for Aggregation and Grouping
+
+There are a few custom cell render overrides that you should be aware of when using grouping and aggregation features.
+
+#### AggregatedCell Column Option
+
+"Aggregation Cells" are cells in an aggregated row (not a normal data row) that can display aggregates (avg, sum, etc.) of the data in a group. The cell that the table is grouped on, however, is not an Aggregate Cell, but rather a [GroupedCell](#groupedcell-column-option).
+
+You can specify the custom render for these cells with the `AggregatedCell` render option on a column definition.
+
+```jsx
+const columns = [
+  {
+    accessorKey: 'points',
+    header: 'Points',
+    aggregationFn: 'sum',
+    AggregatedCell: ({ cell }) => <div>Total Score: {cell.getValue()}</div>,
+  },
+];
+```
+
+#### GroupedCell Column Option
+
+"Grouped Cells" are cells in a grouped row (not a normal data row) that by default display the value that the rows are grouped on and the number of rows in the group. You can override the default render for these cells with the `GroupedCell` render option on a column definition.
+
+```jsx
+const columns = [
+  {
+    accessorKey: 'team',
+    header: 'Team',
+    GroupedCell: ({ cell }) => <div>Team: {cell.getValue()}</div>,
+  },
+];
+```
+
+#### PlaceholderCell Column Option
+
+"Placeholder Cells" are cells that are usually meant to be empty in grouped rows and columns. They are simply rendered with a value of `null` by default, but you can override the default render for these cells with the `PlaceholderCell` render option on a column definition.
+
+```jsx
+const columns = [
+  {
+    accessorKey: 'team',
+    header: 'Team',
+    PlaceholderCell: ({ cell, row }) => (
+      <div>{row.original.someOtherRowValue}</div>
+    ),
+  },
+];
+```
+
+### Aggregation/Grouping Example
+
+> Live example: `aggregation-and-grouping` (call get_mrt_example with that id).
+
+### Multiple Aggregations Per column
+
+You may want to calculate more than one aggregation per column. This is now easier if you are upgraded to at least v1.3.0. You can now specify an array of `aggregationFn`s, and then reference the aggregation results from an array in the `AggregatedCell` render option.
+
+```jsx
+const columns = [
+  {
+    header: 'Salary',
+    accessorKey: 'salary',
+    aggregationFn: ['count', 'mean'], //multiple aggregation functions
+    AggregatedCell: ({ cell, table }) => (
+      <div>
+        {/*get the count from the first aggregation*/}
+        <div>Count: {cell.getValue()[0]}</div>
+        {/*get the average from the second aggregation*/}
+        <div>Average Salary: {cell.getValue()[1]}</div>
+      </div>
+    ),
+  },
+];
+```
+
+> Live example: `aggregation-multi` (call get_mrt_example with that id).
+
+### Manual Grouping
+
+Manual Grouping means that the `data` that you pass to the table is already grouped and aggregated, and you do not want Material React Table to do any of the grouping or aggregation for you. This is useful if you are using a backend API to do the grouping and aggregation for you, and you just want to display the results. However, you will need to put your data in the specific format that the `expanding` features understand.

package/data/guides/async-loading.md

@@ -0,0 +1,132 @@
+## Async Loading UI Feature Guide
+
+While you are fetching your data, you may want to show some loading indicators. Material React Table has some nice loading UI features built in that look better than a simple spinner.
+
+> This guide is mostly focused on the loading UI features. Make sure to also check out the [Remote Data](/docs/examples/remote) and [React Query](/docs/examples/react-query) examples for server-side logic examples.
+
+### Relevant Table Options
+
+Relevant table options (get_mrt_api has full details):
+
+- `muiCircularProgressProps` - type `CircularProgressProps | ({ table }) => CircularProgressProps`
+- `muiLinearProgressProps` - type `LinearProgressProps | ({ isTopToolbar, table }) => LinearProgressProps`
+- `muiSkeletonProps` - type `SkeletonProps | ({ cell, column, row, table }) => SkeletonProps`
+
+### Relevant State Options
+
+Relevant state options (get_mrt_api has full details):
+
+- `isLoading` - type `boolean` - default `false`
+- `isSaving` - type `boolean` - default `false`
+- `showLoadingOverlay` - type `boolean` - default `false`
+- `showProgressBars` - type `boolean` - default `false`
+- `showSkeletons` - type `boolean` - default `false`
+
+### isLoading UI
+
+There are three different loading UI features that are built into Material React Table:
+
+1. Loading Overlay - shows spinner overlay over the table container.
+2. Cell Skeletons - show pretty and shimmering skeletons for each cell.
+3. Linear Progress Bars - shows progress bars above and/or below the table.
+
+You can use any combination of these loading UIs by managing the `showLoadingOverlay`, `showSkeletons`, and `showProgressBars` states.
+
+There are also two other loading states that are shortcuts for combining some of the above states:
+
+- `isLoading` - shows loading overlay and cell skeletons.
+- `isSaving` - shows the progress bars and adds spinners to the save buttons in editing features.
+
+Here is some of the recommended loading UI that you might use with React Query:
+
+```jsx
+const {
+  data = [],
+  isLoading: isLoadingTodos,
+  isRefetching: isRefetchingTodos,
+} = useQuery({
+  /**/
+});
+
+const { mutate, isPending: isSavingTodos } = useMutation({
+  /**/
+});
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  state: {
+    isLoading: isLoadingTodos, //cell skeletons and loading overlay
+    showProgressBars: isRefetchingTodos, //progress bars while refetching
+    isSaving: isSavingTodos, //progress bars and save button spinners
+  },
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+> Note: The Loading Overlay UI makes the table container non-interactive while it is showing. This is usually desired while no data is yet in the table. Consider avoiding using the Loading Overlay UI during "refetching" operations like filtering, sorting, or pagination.
+
+### Customize Loading UI
+
+You can customize the loading UI by passing props to the `muiSkeletonProps`, `muiLinearProgressProps`, and `muiCircularProgressProps` props.
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiSkeletonProps: {
+    animation: 'wave',
+  },
+  muiLinearProgressProps: {
+    color: 'secondary',
+  },
+  muiCircularProgressProps: {
+    color: 'secondary',
+  },
+});
+
+return <MaterialReactTable table={table} />;
+```
+
+> Live example: `loading` (call get_mrt_example with that id).
+
+#### Custom Loading Spinner component
+
+> New in v2.11.0
+
+If you need to use a custom loading spinner component other than the built-in MUI one, you can now pass in custom component in the `muiCircularProgressProps` `Component` prop.
+
+```jsx
+import { MyCustomSpinner } from './MyCustomSpinner';
+
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiCircularProgressProps: {
+    Component: <MyCustomSpinner />,
+  },
+});
+```
+
+### Only Show Progress Bars or Skeletons
+
+If you do not want both progress bars and cell skeletons to show, you can use the `showProgressBars` and `showSkeletons` states, instead.
+
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  state: {
+    showProgressBars: true, //or showSkeletons
+  },
+});
+```
+
+> Live example: `linear-progress` (call get_mrt_example with that id).
+
+### Full Loading and Server-Side Logic Example
+
+Here is a copy of the full [React Query](/docs/examples/react-query) example.
+
+> Live example: `react-query` (call get_mrt_example with that id).