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

material-react-table-narender 1.0.0

Files changed (1769) hide show

package/apps/material-react-table-docs/pages/docs/guides/expanding-sub-rows.mdx ADDED Viewed

@@ -0,0 +1,217 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
+import EnableExample from '../../../examples/enable-expanding-tree';
+import ExpandedExample from '../../../examples/expanding-tree-expanded';
+import ExpandedRootExample from '../../../examples/expanding-tree-root-expanded';
+import ExpandingParsedTreeExample from '../../../examples/expanding-tree-flat-parse';
+import LazySubRowsExample from '../../../examples/lazy-sub-rows';
+<Head>
+  <title>
+    {'Expanding Sub-Rows/Tree Data Guide - Material React Table V3 Docs'}
+  </title>
+  <meta
+    name="description"
+    content="How to add expanding sub-rows or tree data features in Material React Table"
+  />
+</Head>
+## Expanding Sub-Rows (Tree Data) Feature Guide
+Material React Table has support for expanding sub-rows or tree data. This feature is useful for displaying hierarchical data. The sub-rows can be expanded and collapsed by clicking on the expand/collapse icon.
+> NOTE: This feature is for expanding rows of the same data type. If you want to add expansion of more data for the same row, check out the [Detail Panel Feature Guide](/docs/guides/detail-panel).
+### Relevant Table Options
+<TableOptionsTable
+  onlyOptions={
+    new Set([
+      'autoResetExpanded',
+      'data',
+      'enableExpandAll',
+      'enableExpanding',
+      'expandRowsFn',
+      'filterFromLeafRows',
+      'getExpandedRowModel',
+      'getIsRowExpanded',
+      'getRowCanExpand',
+      'getRowId',
+      'getSubRows',
+      'groupedColumnMode',
+      'manualExpanding',
+      'maxLeafRowFilterDepth',
+      'muiExpandAllButtonProps',
+      'muiExpandButtonProps',
+      'onExpandedChange',
+      'paginateExpandedRows',
+      'positionExpandColumn',
+    ])
+}
+/>
+### Relevant State Options
+<StateOptionsTable onlyOptions={new Set(['expanded'])} />
+### Enable Expanding Sub-Rows
+To enable expanding sub-rows, you must first set the `enableExpanding` table option to `true`.
+However, your data must also be formatted in a way to allow for expanding rows that are in some way related to each other. By default, Material React Table will look for a special `subRows` property on each row of your data and treat any array of rows that it finds as the sub-rows for that row. You can customize or override this behavior by passing a custom `getSubRows` table option.
+```jsx
+const data = [
+  {
+    id: 1,
+    name: 'John Doe',
+    subRows: [
+      {
+        id: 2,
+        name: 'Jane Doe',
+      },
+      //more sub rows...
+    ],
+  },
+  //more rows...
+];
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableExpanding: true,
+  getSubRows: (originalRow) => originalRow.subRows, //default, can customize
+});
+return <MaterialReactTable table={table} />;
+```
+### Expand All Rows Button
+By default, Material React Table will show the expand all button in the expand column header. You can disable this by setting the `enableExpandAll` table option to `false`.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableExpanding: true,
+  enableExpandAll: false, //hide expand all button in header
+});
+```
+<EnableExample />
+### Generate Sub Rows with getSubRows
+If your data is not yet in a tree structure, but the data has relationships that can be parsed into a tree, you can use the `getSubRows` table option to let TanStack Table find the sub rows for each row.
+There are a couple key things you have to do to make this work:
+1. Only pass in root (top level) rows in your data prop.
+2. Set the `getSubRows` table option to a function that scans all the rest of your data and returns the sub rows for a given row.
+This can sometimes be useful in combination with [lazy loading sub rows](#lazy-load-sub-rows).
+> NOTE: Be conscious of the performance implications of the `getSubRows` function. It will be called for every row in your table, so it should be performant.
+<ExpandingParsedTreeExample />
+### Expanded Rows Pagination Behavior
+By default, Material React Table will treat expanded sub-rows the same as any other row when it comes to pagination. This means that some expanded rows may be on the next page. You can change this behavior by setting the `paginateExpandedRows` table option to `false`.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableExpanding: true,
+  paginateExpandedRows: false, //expanded rows will be on the same page as their parent row
+});
+```
+### Expanded Leaf Row Filtering Behavior
+If you are using the [filtering features](/docs/guides/column-filtering) alongside sub-row features, then there are a few behaviors and customizations you should be aware of.
+#### Filter From Leaf Rows
+By default, filtering is done from parent rows down (so if a parent row is filtered out, all of its children will be filtered out as well). Setting the `filterFromLeafRows` table option to `true` will cause filtering to be done from leaf rows up (which means parent rows will be kept so long as one of their child, or grand-child, etc. rows pass the filtering).
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableExpanding: true,
+  filterFromLeafRows: true, //search for child rows and preserve parent rows
+});
+```
+#### Max Leaf Row Filter Depth
+By default, filtering is done for all rows (max depth of 100), no matter if they are root level parent rows or the child leaf rows of a parent row. Setting the `maxLeafRowFilterDepth` table option to `0` will cause filtering to only be applied to the root level parent rows, with all sub-rows remaining unfiltered. Similarly, setting this option to 1 will cause filtering to only be applied to child leaf rows 1 level deep, and so on.
+This is useful for situations where you want a row's entire child hierarchy to be visible, regardless of the applied filter.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableExpanding: true,
+  maxLeafRowFilterDepth: 0, //When filtering root rows, keep all child rows of the passing parent rows
+});
+```
+### Expand All Rows By Default
+You can manage the initial state of the expanded rows with the `expanded` state option in either the `initialState` or `state` props.
+For example, you may want all rows to be expanded by default. To do this, you can simply set the `expanded` state option to `true`.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableExpanding: true,
+  initialState: { expanded: true }, //all rows expanded by default
+});
+```
+<ExpandedExample />
+### Expand Root Rows Only By Default
+Here is a slightly more complex initial expanded state example where all the root rows are expanded by default, but none of the sub rows themselves are expanded by default. We just need to find all of the root row ids and set their key in the `expanded` `initialState` option to `true`.
+<ExpandedRootExample />
+### Customize Expand Column
+You can customize the expand column by using the `displayColumnDefOptions` table option.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableGrouping: true,
+  displayColumnDefOptions: {
+    'mrt-row-expand': {
+      enableResizing: true, //allow resizing
+      size: 120, //make the expand column wider
+    },
+  },
+});
+```
+### Lazy Load Sub Rows
+If you have a ton of nested data that you want to display, but you don't want to fetch it all up front, you can set up Material React Table to only fetch the sub-rows data when the user expands the row.
+There are quite a few ways in which you could implement fetching sub-rows lazily. This example is just one way to do it.
+The main concept to understand from this example is that you can manage the `expanded` state option in your own scope, and fetch the data for your table based on that state.
+How your data is structured from the server is up to you. It is usually easiest to have the server do the hard work and return the data in a nested tree structure, but you can also return the data in a flat structure and use the `getSubRows` table option to parse the data into a tree structure.
+<LazySubRowsExample />

package/apps/material-react-table-docs/pages/docs/guides/full-screen-toggle.mdx ADDED Viewed

@@ -0,0 +1,77 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
+<Head>
+  <title>{'Full Screen Toggle Guide - Material React Table V3 Docs'}</title>
+  <meta
+    name="description"
+    content="How to use, customize, or disable the full screen toggle button feature of Material React Table"
+  />
+</Head>
+## Full Screen Toggle Feature Guide
+### Relevant Table Options
+<TableOptionsTable
+  onlyOptions={
+    new Set([
+      'enableFullScreenToggle',
+      'onIsFullScreenChange',
+      'muiTablePaperProps',
+    ])
+  }
+/>
+### Relevant State
+<StateOptionsTable onlyOptions={new Set(['isFullScreen'])} />
+### Disable Full Screen Toggle
+The full screen toggle button is enabled by default. You can hide it by setting the `enableFullScreenToggle` table option to `false`.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableFullScreenToggle: false,
+});
+return <MaterialReactTable table={table} />;
+```
+### Change Z-Index of Full Screen Table
+Under the hood in Material React Table V3, when the table is full screen, these `styles` are applied to the root mui paper component:
+```jsx
+{
+  bottom: 0,
+  height: '100vh',
+  left: 0,
+  margin: 0,
+  maxHeight: '100vh',
+  maxWidth: '100vw',
+  padding: 0,
+  position: 'fixed',
+  right: 0,
+  top: 0,
+  width: '100vw',
+  zIndex: 999,
+}
+```
+If you need to change the `zIndex` of the full screen table, you can do so by passing in a `muiTablePaperProps` table option with a `style` object that has a `zIndex` property.
+```jsx
+muiTablePaperProps: ({ table }) => ({
+  //not sx
+  style: {
+    zIndex: table.getState().isFullScreen ? 1000 : undefined,
+  },
+});
+```
+> Note: The `sx` table option will not work here because the `style` table option was used internally instead of the `sx` table option for higher specificity.

package/apps/material-react-table-docs/pages/docs/guides/global-filtering.mdx ADDED Viewed

@@ -0,0 +1,256 @@
+import Head from 'next/head';
+import Box from '@mui/material/Box';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import ColumnOptionsTable from '../../../components/prop-tables/ColumnOptionsTable';
+import StateOptionsTable from '../../../components/prop-tables/StateOptionsTable';
+import CustomizeComponentExample from '../../../examples/customize-global-filter-component';
+import RemoteExample from '../../../examples/remote';
+<Head>
+  <title>
+    {'Global Filtering/Search Guide - Material React Table V3 Docs'}
+  </title>
+  <meta
+    name="description"
+    content="How to use, customize, or disable the global filter and search features in Material React Table"
+  />
+</Head>
+## Global Filtering (Search) Feature Guide
+Material React Table has a powerful built-in global filtering (search) feature that uses a fuzzy matching algorithm and ranks/sorts the results based on how closely rows match the search query. In this guide, we'll cover how to use, customize, or disable the global filter and search features to fit your needs.
+### Relevant Table Options
+<TableOptionsTable
+  onlyOptions={
+    new Set([
+      'enableGlobalFilter',
+      'enableGlobalFilterModes',
+      'enableGlobalFilterRankedResults',
+      'enableFilterMatchHighlighting',
+      'getColumnCanGlobalFilter',
+      'globalFilterFn',
+      'globalFilterModeOptions',
+      'manualFiltering',
+      'muiSearchTextFieldProps',
+      'onGlobalFilterChange',
+      'onGlobalFilterFnChange',
+      'onShowGlobalFilterChange',
+      'positionGlobalFilter',
+      'renderGlobalFilterModeMenuItems',
+    ])
+  }
+/>
+### Relevant Column Options
+<ColumnOptionsTable
+  onlyOptions={new Set(['enableGlobalFilter', 'enableFilterMatchHighlighting'])}
+/>
+### Relevant State Options
+<StateOptionsTable
+  onlyOptions={new Set(['globalFilter', 'globalFilterFn', 'showGlobalFilter'])}
+/>
+### Disable Global Filtering
+You can either disable the global filter feature entirely or disable it for specific columns.
+#### Disable Global Filtering per Column
+If you simply want to not include a column as one of the columns that the global filter scans through during filtering, you can set the `enableGlobalFilter` option to `false` for that column.
+```tsx
+const columns = [
+  {
+    accessorKey: 'id',
+    header: 'Id',
+    enableGlobalFilter: false, // do not scan this column during global filtering
+  },
+  {
+    accessorKey: 'name',
+    header: 'Name',
+  },
+];
+```
+#### Disable Global Filter Feature
+You can disable the global filtering feature and hide the search icon by setting the `enableGlobalFilter` table option to `false`.
+```tsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableGlobalFilter: false, //disable search feature
+});
+return <MaterialReactTable table={table} />;
+```
+### Client-Side Global Filtering
+Client-side filtering (and global filtering) is enabled by default. This means that the search box will scan through all columns and try to find matches for the search term.
+#### Global Filter Function
+You can use any of the built-in `filterFns` or any of the custom filter functions that you have defined in the `filterFns` prop, just like you would with the column filters.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  globalFilterFn: 'contains', //turn off fuzzy matching and use simple contains filter function
+});
+```
+Or a custom filter function:
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  filterFns: {
+    myCustomFilterFn: (row, id, filterValue) =>
+      row.getValue(id).startsWith(filterValue),
+  },
+  globalFilterFn: 'myCustomFilterFn', //set the global filter function to myCustomFilterFn
+});
+```
+The default global filter function is set to `fuzzy`, which is a filtering algorithm based on the popular `match-sorter` [library from Kent C. Dodds](https://www.npmjs.com/package/match-sorter), though you can change the global filter function by setting the `globalFilterFn` table option.
+#### Ranked Results
+If you keep the default `fuzzy` filterFn option as the global filter function, you get an extra ranked results feature enabled by default. This means that when a user searches with the search box, the results will be sorted by the closest match first instead of the order the data was defined in.
+The ranked results feature will disable itself automatically if a sort direction is applied to a column, if any sub-rows are expanded, or if any of the `manual` props are set to `true`.
+If you do not want ranked results to be enabled at all, but you still want fuzzy matching, you can set the `enableGlobalFilterRankedResults` table option to `false`.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableGlobalFilterRankedResults: false, //preserve the order of the data when fuzzy match searching
+});
+```
+#### Global Filter Modes
+Similar to the column filter modes, you can enable the user to be able to choose between multiple different filter modes for the global filter with the `enableGlobalFilterModes` table option. You can then customize which filter modes are available in the drop-down by setting the `globalFilterModeOptions` table option or by rendering your own custom menu items with the `renderGlobalFilterModeMenuItems` table option.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableGlobalFilterModes: true, //enable the user to choose between multiple search filter modes
+  globalFilterModeOptions: ['fuzzy', 'startsWith'], //only allow the user to choose between fuzzy and startsWith filter modes
+});
+```
+#### Show Search Field by Default
+Additionally, if you want to show the search text box by default and not hide it behind the search icon, you can set the `showGlobalFilter` state to `true` in the `initialState`.
+### Manual Server-Side Global Filtering
+A very common use case when you have a lot of data is to filter the data on the server, instead of client-side. In this case, you will want to set the `manualFiltering` table option to `true` and manage the `globalFilter` state yourself like in the example below (can work in conjunction with [manual column filtering](https://www.material-react-table.com/docs/guides/column-filtering#manual-server-side-column-filtering)).
+```tsx
+// You can manage and have control over the columnFilters state yourself
+const [globalFilter, setGlobalFilter] = useState('');
+const [data, setData] = useState([]); //data will get updated after re-fetching
+useEffect(() => {
+  const fetchData = async () => {
+    // send api requests when columnFilters state changes
+    const filteredData = await fetch();
+    setData([...filteredData]);
+  };
+}, [globalFilter]);
+const table = useMaterialReactTable({
+  columns,
+  data, // this will already be filtered on the server
+  manualFiltering: true, //turn off client-side filtering
+  onGlobalFilterChange: setGlobalFilter, //hoist internal global state to your state
+  state: { globalFilter }, //pass in your own managed globalFilter state
+});
+return <MaterialReactTable table={table} />;
+```
+> Specifying `manualFiltering` turns off all client-side filtering and assumes that the `data` you pass to `<MaterialReactTable />` is already filtered.
+Here is the full Remote Data example showing off server-side **filtering**, pagination, and sorting.
+<RemoteExample />
+### Customize Global Filter Position
+You can customize the position of the global filter (search box) in the top toolbar by setting the `positionGlobalFilter` table option to `left` or `right`. It is shown on the right by default.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  positionGlobalFilter: 'left', //show the global filter on the left side of the top toolbar
+  initialState: {
+    showGlobalFilter: true, //show the global filter by default
+  },
+});
+```
+### Customize the Search Text Field
+You can customize the search text field by passing in props to the `muiSearchTextFieldProps` table option. This is useful if you want to customize the placeholder text, add styles, or any other text field props.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  muiSearchTextFieldProps: {
+    placeholder: 'Search all users',
+    sx: { minWidth: '300px' },
+    variant: 'outlined',
+  },
+});
+return <MaterialReactTable table={table} />;
+```
+<CustomizeComponentExample />
+### Filter Match Highlighting
+Filter match highlighting is a new featured enabled by default that will highlight text in the table body cells that matches the current search query with a shade of the <Box component="span" color="warning.main">`theme.palette.warning.main`</Box> color.
+If you are using a custom `Cell` render override for a column, you will need to use the `renderedCellValue` table option instead of `cell.getValue()` to preserve the filter match highlighting.
+```jsx
+const columns = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    Cell: ({ renderedCellValue }) => <span>{renderedCellValue}</span>, // use renderedCellValue instead of cell.getValue()
+  },
+];
+```
+#### Disable Filter Match Highlighting
+Filter match highlighting can be disabled by setting the `enableFilterMatchHighlighting` table option to `false`.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  enableFilterMatchHighlighting: false, //disable filter match highlighting
+});
+```
+View Extra Storybook **[Examples](https://www.material-react-table.dev/?path=/story/features-search-examples)**

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

@@ -0,0 +1,18 @@
+import Head from 'next/head';
+import TableOfContentsList from '../../../components/navigation/TableOfContentsList';
+import { routes } from '../../../components/navigation/routes';
+<Head>
+  <title>Guides - Material React Table V3 Docs</title>
+  <meta
+    name="description"
+    content="Material React Table Guides and Tutorials"
+  />
+</Head>
+## Guides
+<TableOfContentsList
+  items={routes.find((item) => item.href === '/docs/guides').items}
+  variant="heading"
+/>

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

@@ -0,0 +1,65 @@
+import Head from 'next/head';
+import TableOptionsTable from '../../../components/prop-tables/TableOptionsTable';
+import LocaleExamples from '../../../example-groups/LocaleExamples';
+<Head>
+  <title>{'Localization/i18n Guide - Material React Table V3 Docs'}</title>
+  <meta
+    name="description"
+    content="How to customize localization and translations (i18n) in Material React Table"
+  />
+</Head>
+## Localization (i18n) Guide
+Material React Table has full support for localization (i18n). Some locales are included by default, but if your language is not yet supported, you can still easily add your own custom translations to the `localization` table option.
+### Relevant Table Options
+<TableOptionsTable onlyOptions={new Set(['localization'])} />
+### Built-in Locales
+The following locales are included and can be imported from `'material-react-table/locales/'`:
+`ar`, `az`, `bg`, `cs`, `da`, `de`, `el`, `en`, `es`, `et`, `fa`, `fi`, `fr`, `he`, `hr`, `hu`, `hy`, `id`, `it`, `ja`, `ko`, `nl`, `no`, `np`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sk`, `sr-Cyrl-RS`, `sr-Latn-RS`, `sv`, `tr`, `uk`, `vi`, `zh-Hans`, `zh-Hant`
+> If your language is not yet supported, please consider making a PR to add it to the library! See [here on GitHub](https://github.com/KevinVandy/material-react-table/tree/v3/packages/material-react-table/src/locales).
+#### Built-in Locale Examples
+Scroll and find your language below to see an example of how to use it.
+<LocaleExamples />
+> Note: In some frameworks like Remix, you may need to use a full import path like <br /> `import { MRT_Localization_ES } from 'material-react-table/locales/es/index.js';` or <br /> `import { MRT_Localization_ES } from 'material-react-table/locales/es/index.esm.js';` <br />
+> to properly import the locale.
+### Custom Non-Built-In Translations
+If you want to use a language that is not included in the library, you can still easily add your own custom translations to the `localization` table option.
+```jsx
+const table = useMaterialReactTable({
+  columns,
+  data,
+  localization: {
+    actions: 'Ações',
+    and: 'e',
+    cancel: 'Cancelar',
+    changeFilterMode: 'Alterar o modo de filtro',
+    changeSearchMode: 'Alterar o modo de pesquisa',
+    clearFilter: 'Limpar filtros',
+    clearSearch: 'Limpar pesquisa',
+    clearSort: 'Limpar classificações',
+    clickToCopy: 'Clique para copiar',
+    // ... and many more - see link below for full list of translation keys
+  },
+});
+return <MaterialReactTable table={table} />;
+```
+For a full list of all available translation keys, see [here](https://github.com/KevinVandy/material-react-table/blob/v3/packages/material-react-table/src/locales/en.ts)
+If you end up fully translating MRT into another language that is not yet supported, please consider making a PR to add it to the library so that everyone can use it!