npm - material-react-table-narender - Versions diffs - 1.0.0 - Mend

material-react-table-narender 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1769) hide show

package/apps/material-react-table-docs/pages/docs/guides/data-columns.mdx ADDED Viewed

@@ -0,0 +1,303 @@
+import Head from 'next/head';
+import AlignmentExample from '../../../examples/column-alignment';
+<Head>
+  <title>{'Data (Accessor) Columns - Material React Table V3 Docs'}</title>
+  <meta
+    name="description"
+    content="How to create data columns in Material React Table and use accessKeys and accessorFns the right way"
+  />
+</Head>
+## 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',
+    },
+  },
+];
+```
+<AlignmentExample />
+### 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/apps/material-react-table-docs/pages/docs/guides/density-toggle.mdx ADDED Viewed

@@ -0,0 +1,56 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
+import DisableExample from '../../../examples/disable-density-toggle';
+<Head>
+  <title>{'Density Toggle Guide - Material React Table V3 Docs'}</title>
+  <meta
+    name="description"
+    content="How to use, customize, or disable the density toggle button feature of Material React Table"
+  />
+</Head>
+## 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
+<TableOptionsTable
+  onlyOptions={new Set(['enableDensityToggle', 'onDensityChange'])}
+/>
+### Relevant State
+<StateOptionsTable onlyOptions={new Set(['density'])} />
+### 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.
+<DisableExample />

package/apps/material-react-table-docs/pages/docs/guides/detail-panel.mdx ADDED Viewed

@@ -0,0 +1,214 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
+import AlternateExample from '../../../examples/alternate-detail-panel';
+import ChartDetailPanelExample from '../../../examples/chart-detail-panel';
+import ExampleVirtualized from '../../../examples/enable-detail-panel-virtualized';
+import ExampleConditional from '../../../examples/enable-detail-panel-conditionally';
+import LazyDetailPanelExample from '../../../examples/lazy-detail-panel';
+<Head>
+  <title>{'Detail Panel Expanding Guide - Material React Table V3 Docs'}</title>
+  <meta
+    name="description"
+    content="How to add expanding detail panels to each row in Material React Table"
+  />
+</Head>
+## 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
+<TableOptionsTable
+  onlyOptions={
+    new Set([
+      'displayColumnDefOptions',
+      'enableExpandAll',
+      'muiDetailPanelProps',
+      'muiExpandAllButtonProps',
+      'muiExpandButtonProps',
+      'positionExpandColumn',
+      'renderDetailPanel',
+    ])
+  }
+/>
+### Relevant State
+<StateOptionsTable onlyOptions={new Set(['expanded'])} />
+### 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 ? ... : ...
+    },
+  }),
+});
+```
+<ExampleConditional />
+### 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.
+<AlternateExample />
+### 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.
+<ChartDetailPanelExample />
+### 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,
+    };
+  },
+});
+```
+<ExampleVirtualized />
+### 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.
+<LazyDetailPanelExample />
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-detail-panel-examples-)**