[docs][data grid] Add documentation for the list view feature (#15344)

Signed-off-by: Kenan Yusuf <[email protected]> Co-authored-by: Sycamore <[email protected]> Co-authored-by: Bilal Shafi <[email protected]> Co-authored-by: Andrew Cherniavskyi <[email protected]>
mui · Nov 27, 2024 · 2e05222 · 2e05222
1 parent ea3fa72
commit 2e05222
Show file tree

Hide file tree

Showing 28 changed files with 1,006 additions and 193 deletions.
diff --git a/docs/data/data-grid/list-view/ListView.js b/docs/data/data-grid/list-view/ListView.js
@@ -1,17 +1,19 @@
 import * as React from 'react';
-import { DataGridPro } from '@mui/x-data-grid-pro';
-import Box from '@mui/material/Box';
+import { DataGridPro, GridToolbarContainer } from '@mui/x-data-grid-pro';
 import { useDemoData } from '@mui/x-data-grid-generator';
 import Stack from '@mui/material/Stack';
 import Avatar from '@mui/material/Avatar';
 import Typography from '@mui/material/Typography';
-import Checkbox from '@mui/material/Checkbox';
-import FormControlLabel from '@mui/material/FormControlLabel';
 import IconButton from '@mui/material/IconButton';
 import MessageIcon from '@mui/icons-material/Message';
+import ToggleButtonGroup from '@mui/material/ToggleButtonGroup';
+import ToggleButton from '@mui/material/ToggleButton';
+import GridIcon from '@mui/icons-material/GridOn';
+import ListIcon from '@mui/icons-material/TableRowsOutlined';
 
 function MessageAction(params) {
-  const handleMessage = () => {
+  const handleMessage = (event) => {
+    event.stopPropagation();
     console.log(`send message to ${params.row.phone}`);
   };
   return (
@@ -52,10 +54,50 @@ const listColDef = {
 
 const VISIBLE_FIELDS = ['avatar', 'name', 'position'];
 
+function Toolbar({ view, onChangeView }) {
+  return (
+    <GridToolbarContainer
+      sx={{ borderBottom: '1px solid', borderColor: 'divider', py: 1 }}
+    >
+      <ToggleButtonGroup
+        size="small"
+        sx={{ ml: 'auto' }}
+        value={view}
+        exclusive
+        onChange={(_, newView) => {
+          if (newView) {
+            onChangeView(newView);
+          }
+        }}
+      >
+        <ToggleButton
+          size="small"
+          color="primary"
+          sx={{ gap: 0.5 }}
+          value="grid"
+          selected={view === 'grid'}
+        >
+          <GridIcon fontSize="small" /> Grid
+        </ToggleButton>
+        <ToggleButton
+          size="small"
+          color="primary"
+          sx={{ gap: 0.5 }}
+          value="list"
+          selected={view === 'list'}
+        >
+          <ListIcon fontSize="small" /> List
+        </ToggleButton>
+      </ToggleButtonGroup>
+    </GridToolbarContainer>
+  );
+}
+
 export default function ListView() {
-  const [isListView, setIsListView] = React.useState(true);
+  const [view, setView] = React.useState('list');
+  const isListView = view === 'list';
 
-  const { data } = useDemoData({
+  const { data, loading } = useDemoData({
     dataSet: 'Employee',
     rowLength: 20,
     visibleFields: VISIBLE_FIELDS,
@@ -76,32 +118,25 @@ export default function ListView() {
   const rowHeight = isListView ? 64 : 52;
 
   return (
-    <Box sx={{ width: '100%' }}>
-      <FormControlLabel
-        control={
-          <Checkbox
-            checked={isListView}
-            onChange={(event) => setIsListView(event.target.checked)}
-          />
-        }
-        label="Enable list view"
-      />
-      <Box
-        sx={{
-          width: '100%',
-          maxWidth: isListView ? 360 : undefined,
-          height: 600,
-          margin: '0 auto',
+    <div style={{ maxWidth: 360, height: 600 }}>
+      <DataGridPro
+        {...data}
+        loading={loading}
+        columns={columns}
+        rowHeight={rowHeight}
+        unstable_listView={isListView}
+        unstable_listColumn={listColDef}
+        slots={{
+          toolbar: Toolbar,
         }}
-      >
-        <DataGridPro
-          {...data}
-          columns={columns}
-          rowHeight={rowHeight}
-          unstable_listView={isListView}
-          unstable_listColumn={listColDef}
-        />
-      </Box>
-    </Box>
+        slotProps={{
+          toolbar: {
+            view,
+            onChangeView: setView,
+          },
+        }}
+        sx={{ backgroundColor: 'background.paper' }}
+      />
+    </div>
   );
 }
diff --git a/docs/data/data-grid/list-view/ListView.tsx b/docs/data/data-grid/list-view/ListView.tsx
@@ -5,19 +5,29 @@ import {
   GridListColDef,
   GridColDef,
   GridRowParams,
+  GridToolbarContainer,
 } from '@mui/x-data-grid-pro';
-import Box from '@mui/material/Box';
 import { useDemoData } from '@mui/x-data-grid-generator';
 import Stack from '@mui/material/Stack';
 import Avatar from '@mui/material/Avatar';
 import Typography from '@mui/material/Typography';
-import Checkbox from '@mui/material/Checkbox';
-import FormControlLabel from '@mui/material/FormControlLabel';
 import IconButton from '@mui/material/IconButton';
 import MessageIcon from '@mui/icons-material/Message';
+import ToggleButtonGroup from '@mui/material/ToggleButtonGroup';
+import ToggleButton from '@mui/material/ToggleButton';
+import GridIcon from '@mui/icons-material/GridOn';
+import ListIcon from '@mui/icons-material/TableRowsOutlined';
+
+declare module '@mui/x-data-grid' {
+  interface ToolbarPropsOverrides {
+    view: 'grid' | 'list';
+    onChangeView: (view: 'grid' | 'list') => void;
+  }
+}
 
 function MessageAction(params: Pick<GridRowParams, 'row'>) {
-  const handleMessage = () => {
+  const handleMessage = (event: React.MouseEvent) => {
+    event.stopPropagation();
     console.log(`send message to ${params.row.phone}`);
   };
   return (
@@ -58,10 +68,55 @@ const listColDef: GridListColDef = {
 
 const VISIBLE_FIELDS = ['avatar', 'name', 'position'];
 
+type ToolbarProps = {
+  view: 'grid' | 'list';
+  onChangeView: (view: 'grid' | 'list') => void;
+};
+
+function Toolbar({ view, onChangeView }: ToolbarProps) {
+  return (
+    <GridToolbarContainer
+      sx={{ borderBottom: '1px solid', borderColor: 'divider', py: 1 }}
+    >
+      <ToggleButtonGroup
+        size="small"
+        sx={{ ml: 'auto' }}
+        value={view}
+        exclusive
+        onChange={(_, newView) => {
+          if (newView) {
+            onChangeView(newView);
+          }
+        }}
+      >
+        <ToggleButton
+          size="small"
+          color="primary"
+          sx={{ gap: 0.5 }}
+          value="grid"
+          selected={view === 'grid'}
+        >
+          <GridIcon fontSize="small" /> Grid
+        </ToggleButton>
+        <ToggleButton
+          size="small"
+          color="primary"
+          sx={{ gap: 0.5 }}
+          value="list"
+          selected={view === 'list'}
+        >
+          <ListIcon fontSize="small" /> List
+        </ToggleButton>
+      </ToggleButtonGroup>
+    </GridToolbarContainer>
+  );
+}
+
 export default function ListView() {
-  const [isListView, setIsListView] = React.useState(true);
+  const [view, setView] = React.useState<'grid' | 'list'>('list');
+  const isListView = view === 'list';
 
-  const { data } = useDemoData({
+  const { data, loading } = useDemoData({
     dataSet: 'Employee',
     rowLength: 20,
     visibleFields: VISIBLE_FIELDS,
@@ -82,32 +137,25 @@ export default function ListView() {
   const rowHeight = isListView ? 64 : 52;
 
   return (
-    <Box sx={{ width: '100%' }}>
-      <FormControlLabel
-        control={
-          <Checkbox
-            checked={isListView}
-            onChange={(event) => setIsListView(event.target.checked)}
-          />
-        }
-        label="Enable list view"
-      />
-      <Box
-        sx={{
-          width: '100%',
-          maxWidth: isListView ? 360 : undefined,
-          height: 600,
-          margin: '0 auto',
+    <div style={{ maxWidth: 360, height: 600 }}>
+      <DataGridPro
+        {...data}
+        loading={loading}
+        columns={columns}
+        rowHeight={rowHeight}
+        unstable_listView={isListView}
+        unstable_listColumn={listColDef}
+        slots={{
+          toolbar: Toolbar,
         }}
-      >
-        <DataGridPro
-          {...data}
-          columns={columns}
-          rowHeight={rowHeight}
-          unstable_listView={isListView}
-          unstable_listColumn={listColDef}
-        />
-      </Box>
-    </Box>
+        slotProps={{
+          toolbar: {
+            view,
+            onChangeView: setView,
+          },
+        }}
+        sx={{ backgroundColor: 'background.paper' }}
+      />
+    </div>
   );
 }
diff --git a/docs/data/data-grid/list-view/ListViewAdvanced.js b/docs/data/data-grid/list-view/ListViewAdvanced.js
@@ -13,6 +13,7 @@ import OpenIcon from '@mui/icons-material/Visibility';
 import useMediaQuery from '@mui/material/useMediaQuery';
 import CSSBaseline from '@mui/material/CssBaseline';
 import { randomId } from '@mui/x-data-grid-generator';
+import { useTheme } from '@mui/material/styles';
 import { FileIcon } from './components/FileIcon';
 import { DetailsDrawer } from './components/DetailsDrawer';
 import { ListCell } from './components/ListCell';
@@ -24,12 +25,16 @@ import { formatDate, formatSize, stringAvatar } from './utils';
 import { ActionDrawer } from './components/ActionDrawer';
 import { RenameDialog } from './components/RenameDialog';
 
-export default function ListViewAdvanced() {
+export default function ListViewAdvanced(props) {
   // This is used only for the example - renders the drawer inside the container
   const containerRef = React.useRef(null);
   const container = () => containerRef.current;
 
-  const isListView = useMediaQuery('(min-width: 700px)');
+  const theme = useTheme();
+  const isBelowMd = useMediaQuery(theme.breakpoints.down('md'));
+
+  const isDocsDemo = props.window !== undefined;
+  const isListView = isDocsDemo ? true : isBelowMd;
 
   const apiRef = useGridApiRef();
 

diff --git a/docs/data/data-grid/list-view/ListViewAdvanced.tsx b/docs/data/data-grid/list-view/ListViewAdvanced.tsx
@@ -17,6 +17,7 @@ import OpenIcon from '@mui/icons-material/Visibility';
 import useMediaQuery from '@mui/material/useMediaQuery';
 import CSSBaseline from '@mui/material/CssBaseline';
 import { randomId } from '@mui/x-data-grid-generator';
+import { useTheme } from '@mui/material/styles';
 import { FileIcon } from './components/FileIcon';
 import { DetailsDrawer } from './components/DetailsDrawer';
 import { ListCell } from './components/ListCell';
@@ -37,12 +38,21 @@ declare module '@mui/x-data-grid' {
   }
 }
 
-export default function ListViewAdvanced() {
+interface Props {
+  // Injected by the documentation to work in an iframe.
+  window?: () => Window;
+}
+
+export default function ListViewAdvanced(props: Props) {
   // This is used only for the example - renders the drawer inside the container
   const containerRef = React.useRef<HTMLDivElement>(null);
   const container = () => containerRef.current as HTMLElement;
 
-  const isListView = useMediaQuery('(min-width: 700px)');
+  const theme = useTheme();
+  const isBelowMd = useMediaQuery(theme.breakpoints.down('md'));
+
+  const isDocsDemo = props.window !== undefined;
+  const isListView = isDocsDemo ? true : isBelowMd;
 
   const apiRef = useGridApiRef();