From 340acbde76bbad3d7925f3c374cb9f23a8d7f924 Mon Sep 17 00:00:00 2001 From: Olivier Tassinari Date: Wed, 20 Nov 2024 01:55:57 +0100 Subject: [PATCH] [docs][data grid] Polish Server-side data section (#15330) --- docs/data/data-grid/list-view/list-view.md | 10 +++--- .../data-grid/row-spanning/row-spanning.md | 6 +++- .../server-side-data/ServerSideDataGrid.js | 4 +-- .../server-side-data/ServerSideDataGrid.tsx | 4 +-- .../ServerSideDataGrid.tsx.preview | 7 ++++ .../server-side-data/ServerSideDataGridTTL.js | 4 +-- .../ServerSideDataGridTTL.tsx | 4 +-- .../ServerSideDataGridTTL.tsx.preview | 8 +++++ docs/data/data-grid/server-side-data/index.md | 32 +++++++++---------- .../server-side-data/row-grouping.md | 12 +++---- .../data-grid/server-side-data/tree-data.md | 14 ++++---- docs/data/pages.ts | 17 +++++++--- .../server-side-data/aggregation.js | 2 +- .../react-data-grid/server-side-data/index.js | 2 +- .../server-side-data/infinite-loading.js | 2 +- .../server-side-data/lazy-loading.js | 2 +- .../server-side-data/row-grouping.js | 2 +- .../server-side-data/tree-data.js | 2 +- .../x-data-grid/src/models/gridDataSource.ts | 24 +++++++------- 19 files changed, 88 insertions(+), 70 deletions(-) create mode 100644 docs/data/data-grid/server-side-data/ServerSideDataGrid.tsx.preview create mode 100644 docs/data/data-grid/server-side-data/ServerSideDataGridTTL.tsx.preview diff --git a/docs/data/data-grid/list-view/list-view.md b/docs/data/data-grid/list-view/list-view.md index 11f4b7ca3e88..362b056fa059 100644 --- a/docs/data/data-grid/list-view/list-view.md +++ b/docs/data/data-grid/list-view/list-view.md @@ -2,20 +2,20 @@ title: Data Grid - List view --- -# Data Grid - List view [](/x/introduction/licensing/#pro-plan 'Pro plan') +# Data Grid - List view [](/x/introduction/licensing/#pro-plan 'Pro plan')🧪

Display data in a single-column list view. Can be used to present a more compact grid on smaller screens and mobile devices.

+:::warning +This feature is marked as **unstable**. While you can use this feature in production, the API could change in the future. +::: + List view can be enabled by providing the `unstable_listView` prop. Unlike the default grid view, the list view makes no assumptions on how data is presented to end users. In order to display data in a list view, a `unstable_listColumn` prop must be provided with a `renderCell` function. -:::warning -This feature is under development and is marked as **unstable**. While you can use the list view feature in production, the API could change in the future. -::: - {{"demo": "ListView.js", "bg": "inline"}} ## Advanced usage diff --git a/docs/data/data-grid/row-spanning/row-spanning.md b/docs/data/data-grid/row-spanning/row-spanning.md index bc8d37752e05..8e3dcdc1febe 100644 --- a/docs/data/data-grid/row-spanning/row-spanning.md +++ b/docs/data/data-grid/row-spanning/row-spanning.md @@ -1,7 +1,11 @@ -# Data Grid - Row spanning +# Data Grid - Row spanning 🧪

Span cells across several rows.

+:::warning +This feature is marked as **unstable**. While you can use this feature in production, the API could change in the future. +::: + By default, each cell in a Data Grid takes up the height of one row. The row spanning feature makes it possible for a cell to fill multiple rows in a single column. diff --git a/docs/data/data-grid/server-side-data/ServerSideDataGrid.js b/docs/data/data-grid/server-side-data/ServerSideDataGrid.js index 31bfbc5b61b7..8095791c05b4 100644 --- a/docs/data/data-grid/server-side-data/ServerSideDataGrid.js +++ b/docs/data/data-grid/server-side-data/ServerSideDataGrid.js @@ -2,7 +2,7 @@ import * as React from 'react'; import { DataGridPro } from '@mui/x-data-grid-pro'; import { useMockServer } from '@mui/x-data-grid-generator'; -function ServerSideDataGrid() { +export default function ServerSideDataGrid() { const { columns, initialState, fetchRows } = useMockServer( {}, { useCursorPagination: false }, @@ -51,5 +51,3 @@ function ServerSideDataGrid() { ); } - -export default ServerSideDataGrid; diff --git a/docs/data/data-grid/server-side-data/ServerSideDataGrid.tsx b/docs/data/data-grid/server-side-data/ServerSideDataGrid.tsx index 498c1e067429..019b75d76752 100644 --- a/docs/data/data-grid/server-side-data/ServerSideDataGrid.tsx +++ b/docs/data/data-grid/server-side-data/ServerSideDataGrid.tsx @@ -2,7 +2,7 @@ import * as React from 'react'; import { DataGridPro, GridDataSource } from '@mui/x-data-grid-pro'; import { useMockServer } from '@mui/x-data-grid-generator'; -function ServerSideDataGrid() { +export default function ServerSideDataGrid() { const { columns, initialState, fetchRows } = useMockServer( {}, { useCursorPagination: false }, @@ -51,5 +51,3 @@ function ServerSideDataGrid() { ); } - -export default ServerSideDataGrid; diff --git a/docs/data/data-grid/server-side-data/ServerSideDataGrid.tsx.preview b/docs/data/data-grid/server-side-data/ServerSideDataGrid.tsx.preview new file mode 100644 index 000000000000..85adc7fdbcfd --- /dev/null +++ b/docs/data/data-grid/server-side-data/ServerSideDataGrid.tsx.preview @@ -0,0 +1,7 @@ + \ No newline at end of file diff --git a/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.js b/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.js index 33d5403393f8..71b71560b605 100644 --- a/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.js +++ b/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.js @@ -4,7 +4,7 @@ import { useMockServer } from '@mui/x-data-grid-generator'; const lowTTLCache = new GridDataSourceCacheDefault({ ttl: 1000 * 10 }); // 10 seconds -function ServerSideDataGridTTL() { +export default function ServerSideDataGridTTL() { const { columns, initialState, fetchRows } = useMockServer( {}, { useCursorPagination: false }, @@ -54,5 +54,3 @@ function ServerSideDataGridTTL() { ); } - -export default ServerSideDataGridTTL; diff --git a/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.tsx b/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.tsx index f33906bf70b6..ccf7346b9809 100644 --- a/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.tsx +++ b/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.tsx @@ -8,7 +8,7 @@ import { useMockServer } from '@mui/x-data-grid-generator'; const lowTTLCache = new GridDataSourceCacheDefault({ ttl: 1000 * 10 }); // 10 seconds -function ServerSideDataGridTTL() { +export default function ServerSideDataGridTTL() { const { columns, initialState, fetchRows } = useMockServer( {}, { useCursorPagination: false }, @@ -58,5 +58,3 @@ function ServerSideDataGridTTL() { ); } - -export default ServerSideDataGridTTL; diff --git a/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.tsx.preview b/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.tsx.preview new file mode 100644 index 000000000000..dfa35d39ae48 --- /dev/null +++ b/docs/data/data-grid/server-side-data/ServerSideDataGridTTL.tsx.preview @@ -0,0 +1,8 @@ + \ No newline at end of file diff --git a/docs/data/data-grid/server-side-data/index.md b/docs/data/data-grid/server-side-data/index.md index 3b89ae28e5b2..035be2e8fdf6 100644 --- a/docs/data/data-grid/server-side-data/index.md +++ b/docs/data/data-grid/server-side-data/index.md @@ -2,10 +2,16 @@ title: React Data Grid - Server-side data --- -# Data Grid - Server-side data [](/x/introduction/licensing/#pro-plan 'Pro plan') +# Data Grid - Server-side data [](/x/introduction/licensing/#pro-plan 'Pro plan')🧪

The Data Grid server-side data.

+:::warning +This feature is under development and is marked as **unstable**. +While you can use this feature in production, the API could change in the future. +Feel free to subscribe or comment on the official GitHub [umbrella issue](https://github.com/mui/mui-x/issues/8179). +::: + ## Introduction Server-side data management in React can become complex with growing datasets. @@ -72,14 +78,6 @@ The idea for a centralized data source is to simplify server-side data fetching. It's an abstraction layer between the Data Grid and the server, providing a simple interface for interacting with the server. Think of it like an intermediary handling the communication between the Data Grid (client) and the actual data source (server). -:::warning - -This feature is under development and is marked as **unstable**. -The information shared on this page could change in the future. -Feel free to subscribe or comment on the official GitHub [umbrella issue](https://github.com/mui/mui-x/issues/8179). - -::: - It has an initial set of required methods that you need to implement. The Data Grid will use these methods internally to fetch a subset of data when needed. Let's take a look at the minimal `GridDataSource` interface configuration. @@ -88,8 +86,9 @@ Let's take a look at the minimal `GridDataSource` interface configuration. interface GridDataSource { /** * This method will be called when the grid needs to fetch some rows. - * @param {GridGetRowsParams} params The parameters required to fetch the rows - * @returns {Promise} A promise that resolves to the data of type [GridGetRowsResponse] + * @param {GridGetRowsParams} params The parameters required to fetch the rows. + * @returns {Promise} A promise that resolves to the data of + * type [GridGetRowsResponse]. */ getRows(params: GridGetRowsParams): Promise; } @@ -133,7 +132,7 @@ The code has been significantly reduced, the need for managing the controlled st The data source changes how the existing server-side features like `filtering`, `sorting`, and `pagination` work. -**Without data source** +### Without data source When there's no data source, the features `filtering`, `sorting`, `pagination` work on `client` by default. In order for them to work with server-side data, you need to set them to `server` explicitly and provide the [`onFilterModelChange`](/x/react-data-grid/filtering/server-side/), [`onSortModelChange`](/x/react-data-grid/sorting/#server-side-sorting), [`onPaginationModelChange`](/x/react-data-grid/pagination/#server-side-pagination) event handlers to fetch the data from the server based on the updated variables. @@ -158,7 +157,7 @@ In order for them to work with server-side data, you need to set them to `server /> ``` -**With data source** +### With data source With the data source, the features `filtering`, `sorting`, `pagination` are automatically set to `server`. @@ -167,7 +166,8 @@ When the corresponding models update, the Data Grid calls the `getRows` method w ```tsx ``` @@ -187,9 +187,7 @@ Open info section of the browser console to see the requests being made and the The data source caches fetched data by default. This means that if the user navigates to a page or expands a node that has already been fetched, the grid will not call the `getRows` function again to avoid unnecessary calls to the server. -The `GridDataSourceCacheDefault` is used by default which is a simple in-memory cache that stores the data in a plain object. It can be seen in action in the demo below. - -{{"demo": "ServerSideDataGrid.js", "bg": "inline"}} +The `GridDataSourceCacheDefault` is used by default which is a simple in-memory cache that stores the data in a plain object. It can be seen in action in the [demo above](#with-data-source). ### Customize the cache lifetime diff --git a/docs/data/data-grid/server-side-data/row-grouping.md b/docs/data/data-grid/server-side-data/row-grouping.md index 25b6044f3f43..f7fd48290f8d 100644 --- a/docs/data/data-grid/server-side-data/row-grouping.md +++ b/docs/data/data-grid/server-side-data/row-grouping.md @@ -2,7 +2,7 @@ title: React Server-side row grouping --- -# Data Grid - Server-side row grouping [](/x/introduction/licensing/#pro-plan 'Pro plan') +# Data Grid - Server-side row grouping [](/x/introduction/licensing/#premium-plan 'Premium plan')🧪

Lazy-loaded row grouping with server-side data source.

@@ -20,14 +20,14 @@ Similar to the [tree data](/x/react-data-grid/server-side-data/tree-data/), you ```tsx const customDataSource: GridDataSource = { getRows: async (params) => { - // Fetch the data from the server + // Fetch the data from the server. }, getGroupKey: (row) => { - // Return the group key for the row, e.g. `name` + // Return the group key for the row, e.g. `name`. return row.name; }, getChildrenCount: (row) => { - // Return the number of children for the row + // Return the number of children for the row. return row.childrenCount; }, }; @@ -45,7 +45,7 @@ const getRows: async (params) => { }); const getRowsResponse = await fetchRows( // Server should group the data based on `groupFields` and - // extract the rows for the nested level based on `groupKeys` + // extract the rows for the nested level based on `groupKeys`. `https://mui.com/x/api/data-grid?${urlParams.toString()}`, ); return { @@ -74,7 +74,7 @@ This example shows error handling with toast notifications and default error mes ## Group expansion The group expansion works similar to the [data source tree data](/x/react-data-grid/server-side-data/tree-data/#group-expansion). -The following demo uses `defaultGroupingExpansionDepth='-1'` to expand all the groups. +The following demo uses `defaultGroupingExpansionDepth={-1}` to expand all the groups. {{"demo": "ServerSideRowGroupingGroupExpansion.js", "bg": "inline"}} diff --git a/docs/data/data-grid/server-side-data/tree-data.md b/docs/data/data-grid/server-side-data/tree-data.md index d5c725ac456e..b93f559d5b07 100644 --- a/docs/data/data-grid/server-side-data/tree-data.md +++ b/docs/data/data-grid/server-side-data/tree-data.md @@ -2,7 +2,7 @@ title: React Server-side tree data --- -# Data Grid - Server-side tree data [](/x/introduction/licensing/#pro-plan 'Pro plan') +# Data Grid - Server-side tree data [](/x/introduction/licensing/#pro-plan 'Pro plan')🧪

Tree data lazy-loading with server-side data source.

@@ -20,14 +20,14 @@ The data source also requires some additional props to handle tree data: ```tsx const customDataSource: GridDataSource = { getRows: async (params) => { - // Fetch the data from the server + // Fetch the data from the server. }, getGroupKey: (row) => { - // Return the group key for the row, e.g. `name` + // Return the group key for the row, e.g. `name`. return row.name; }, getChildrenCount: (row) => { - // Return the number of children for the row + // Return the number of children for the row. return row.childrenCount; }, }; @@ -39,11 +39,11 @@ Use `groupKeys` on the server to extract the rows for a given nested level. ```tsx const getRows: async (params) => { const urlParams = new URLSearchParams({ - // Example: JSON.stringify(['Billy Houston', 'Lora Dean']) + // Example: JSON.stringify(['Billy Houston', 'Lora Dean']). groupKeys: JSON.stringify(params.groupKeys), }); const getRowsResponse = await fetchRows( - // Server should extract the rows for the nested level based on `groupKeys` + // Server should extract the rows for the nested level based on `groupKeys`. `https://mui.com/x/api/data-grid?${urlParams.toString()}`, ); return { @@ -78,7 +78,7 @@ The demo below shows a toast apart from the default error message in the groupin The idea behind the group expansion is the same as explained in the [Row grouping](/x/react-data-grid/row-grouping/#group-expansion) section. The difference is that the data is not initially available and is fetched automatically after the Data Grid is mounted based on the props `defaultGroupingExpansionDepth` and `isGroupExpandedByDefault` in a waterfall manner. -The following demo uses `defaultGroupingExpansionDepth='-1'` to expand all levels of the tree by default. +The following demo uses `defaultGroupingExpansionDepth={-1}` to expand all levels of the tree by default. {{"demo": "ServerSideTreeDataGroupExpansion.js", "bg": "inline"}} diff --git a/docs/data/pages.ts b/docs/data/pages.ts index c89a8c552c6c..e3810ebd7004 100644 --- a/docs/data/pages.ts +++ b/docs/data/pages.ts @@ -62,7 +62,7 @@ const pages: MuiPage[] = [ { pathname: '/x/react-data-grid/row-definition' }, { pathname: '/x/react-data-grid/row-updates' }, { pathname: '/x/react-data-grid/row-height' }, - { pathname: '/x/react-data-grid/row-spanning', newFeature: true }, + { pathname: '/x/react-data-grid/row-spanning', unstable: true }, { pathname: '/x/react-data-grid/master-detail', plan: 'pro' }, { pathname: '/x/react-data-grid/row-ordering', plan: 'pro' }, { pathname: '/x/react-data-grid/row-pinning', plan: 'pro' }, @@ -142,8 +142,17 @@ const pages: MuiPage[] = [ title: 'Server-side data', plan: 'pro', children: [ - { pathname: '/x/react-data-grid/server-side-data', title: 'Overview' }, - { pathname: '/x/react-data-grid/server-side-data/tree-data', plan: 'pro' }, + { + pathname: '/x/react-data-grid/server-side-data', + title: 'Overview', + plan: 'pro', + unstable: true, + }, + { + pathname: '/x/react-data-grid/server-side-data/tree-data', + plan: 'pro', + unstable: true, + }, { pathname: '/x/react-data-grid/server-side-data/lazy-loading', plan: 'pro', @@ -157,7 +166,7 @@ const pages: MuiPage[] = [ { pathname: '/x/react-data-grid/server-side-data/row-grouping', plan: 'premium', - planned: true, + unstable: true, }, { pathname: '/x/react-data-grid/server-side-data/aggregation', diff --git a/docs/pages/x/react-data-grid/server-side-data/aggregation.js b/docs/pages/x/react-data-grid/server-side-data/aggregation.js index bfcbd582f587..3ac36d099e2b 100644 --- a/docs/pages/x/react-data-grid/server-side-data/aggregation.js +++ b/docs/pages/x/react-data-grid/server-side-data/aggregation.js @@ -3,5 +3,5 @@ import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; import * as pageProps from 'docsx/data/data-grid/server-side-data/aggregation.md?muiMarkdown'; export default function Page() { - return ; + return ; } diff --git a/docs/pages/x/react-data-grid/server-side-data/index.js b/docs/pages/x/react-data-grid/server-side-data/index.js index d9df4aa83ae5..df29698d72ab 100644 --- a/docs/pages/x/react-data-grid/server-side-data/index.js +++ b/docs/pages/x/react-data-grid/server-side-data/index.js @@ -3,5 +3,5 @@ import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; import * as pageProps from 'docsx/data/data-grid/server-side-data/index.md?muiMarkdown'; export default function Page() { - return ; + return ; } diff --git a/docs/pages/x/react-data-grid/server-side-data/infinite-loading.js b/docs/pages/x/react-data-grid/server-side-data/infinite-loading.js index 17c80ea529aa..8392e3a0416f 100644 --- a/docs/pages/x/react-data-grid/server-side-data/infinite-loading.js +++ b/docs/pages/x/react-data-grid/server-side-data/infinite-loading.js @@ -3,5 +3,5 @@ import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; import * as pageProps from 'docsx/data/data-grid/server-side-data/infinite-loading.md?muiMarkdown'; export default function Page() { - return ; + return ; } diff --git a/docs/pages/x/react-data-grid/server-side-data/lazy-loading.js b/docs/pages/x/react-data-grid/server-side-data/lazy-loading.js index a5a2bfb0671a..500157f7352e 100644 --- a/docs/pages/x/react-data-grid/server-side-data/lazy-loading.js +++ b/docs/pages/x/react-data-grid/server-side-data/lazy-loading.js @@ -3,5 +3,5 @@ import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; import * as pageProps from 'docsx/data/data-grid/server-side-data/lazy-loading.md?muiMarkdown'; export default function Page() { - return ; + return ; } diff --git a/docs/pages/x/react-data-grid/server-side-data/row-grouping.js b/docs/pages/x/react-data-grid/server-side-data/row-grouping.js index 0ca6eb198e2f..843d4e65ab4d 100644 --- a/docs/pages/x/react-data-grid/server-side-data/row-grouping.js +++ b/docs/pages/x/react-data-grid/server-side-data/row-grouping.js @@ -3,5 +3,5 @@ import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; import * as pageProps from 'docsx/data/data-grid/server-side-data/row-grouping.md?muiMarkdown'; export default function Page() { - return ; + return ; } diff --git a/docs/pages/x/react-data-grid/server-side-data/tree-data.js b/docs/pages/x/react-data-grid/server-side-data/tree-data.js index 0f161a986cc3..545a750f5537 100644 --- a/docs/pages/x/react-data-grid/server-side-data/tree-data.js +++ b/docs/pages/x/react-data-grid/server-side-data/tree-data.js @@ -3,5 +3,5 @@ import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; import * as pageProps from 'docsx/data/data-grid/server-side-data/tree-data.md?muiMarkdown'; export default function Page() { - return ; + return ; } diff --git a/packages/x-data-grid/src/models/gridDataSource.ts b/packages/x-data-grid/src/models/gridDataSource.ts index 44bd45159349..2df17b84cf2d 100644 --- a/packages/x-data-grid/src/models/gridDataSource.ts +++ b/packages/x-data-grid/src/models/gridDataSource.ts @@ -42,7 +42,7 @@ export interface GridGetRowsResponse { rowCount?: number; /** * Additional `pageInfo` for advanced use-cases. - * `hasNextPage`: When row count is unknown/estimated, `hasNextPage` will be used to check if more records are available on server + * `hasNextPage`: When row count is unknown/estimated, `hasNextPage` will be used to check if more records are available on server. */ pageInfo?: { hasNextPage?: boolean; @@ -53,25 +53,25 @@ export interface GridGetRowsResponse { export interface GridDataSource { /** * This method will be called when the grid needs to fetch some rows. - * @param {GridGetRowsParams} params The parameters required to fetch the rows - * @returns {Promise} A promise that resolves to the data of type [GridGetRowsResponse] + * @param {GridGetRowsParams} params The parameters required to fetch the rows. + * @returns {Promise} A promise that resolves to the data of type [GridGetRowsResponse]. */ getRows(params: GridGetRowsParams): Promise; /** * This method will be called when the user updates a row [Not yet implemented]. - * @param {GridRowModel} updatedRow The updated row - * @returns {Promise} If resolved (synced on the backend), the grid will update the row and mutate the cache + * @param {GridRowModel} updatedRow The updated row. + * @returns {Promise} If resolved (synced on the backend), the grid will update the row and mutate the cache. */ updateRow?(updatedRow: GridRowModel): Promise; /** * Used to group rows by their parent group. Replaces `getTreeDataPath` used in client side tree-data. - * @param {GridRowModel} row The row to get the group key of - * @returns {string} The group key for the row + * @param {GridRowModel} row The row to get the group key of. + * @returns {string} The group key for the row. */ getGroupKey?: (row: GridRowModel) => string; /** * Used to determine the number of children a row has on server. - * @param {GridRowModel} row The row to check the number of children + * @param {GridRowModel} row The row to check the number of children. * @returns {number} The number of children the row has. * If the children count is not available for some reason, but there are some children, `getChildrenCount` should return `-1`. */ @@ -81,14 +81,14 @@ export interface GridDataSource { export interface GridDataSourceCache { /** * Set the cache entry for the given key. - * @param {GridGetRowsParams} key The key of type `GridGetRowsParams` - * @param {GridGetRowsResponse} value The value to be stored in the cache + * @param {GridGetRowsParams} key The key of type `GridGetRowsParams`. + * @param {GridGetRowsResponse} value The value to be stored in the cache. */ set: (key: GridGetRowsParams, value: GridGetRowsResponse) => void; /** * Get the cache entry for the given key. - * @param {GridGetRowsParams} key The key of type `GridGetRowsParams` - * @returns {GridGetRowsResponse} The value stored in the cache + * @param {GridGetRowsParams} key The key of type `GridGetRowsParams`. + * @returns {GridGetRowsResponse} The value stored in the cache. */ get: (key: GridGetRowsParams) => GridGetRowsResponse | undefined; /**