Improve doc and stories about facets

Author: fzaninotto

docs/List.md

@@ -1144,37 +1144,58 @@ const ProductList = () => (
 
 If `dataProvider.getList()` returns additional metadata in the response under the `meta` key, you can access it in the list view using the `meta` property of the `ListContext`.
 
-This is often used by APIs to return statistics or other metadata about the list of records.
+![List metadata](./img/List-facets.png)
+
+This is often used by APIs to return facets, aggregations, statistics, or other metadata about the list of records.
 
 ```tsx
-// dataProvider.getLists('posts') returns response like
+// dataProvider.getLists('books') returns response like
 // {
 //     data: [ ... ],
 //     total: 293,
 //     meta: {
-//         facets: [
-//             { value: 'Novels', count: 245 },
-//             { value: 'Essays', count: 23 },
-//             { value: 'Short stories', count: 25 },
+//         genres: [
+//             { value: 'Fictions', count: 134 },
+//             { value: 'Essays', count: 24 },
+//         ],
+//         centuries: [
+//             { value: '18th', count: 23 },
+//             { value: '19th', count: 78 },
+//             { value: '20th', count: 57 },
+//             { value: '21st', count: 34 },
 //         ],
 //     },
 // }
 const Facets = () => {
     const { isLoading, error, meta } = useListContext();
     if (isLoading || error) return null;
-    const facets = meta.facets;
     return (
-        <Stack direction="row" gap={3} mt={2} ml={1}>
-            {facets.map(facet => (
-                <Badge
-                    key={facet.value}
-                    badgeContent={facet.count}
-                    color="primary"
-                >
-                    <Chip label={facet.value} size="small" />
-                </Badge>
-            ))}
-        </Stack>
+        <Box>
+            <Typography variant="subtitle2">
+                Genres
+            </Typography>
+            <Typography component="ul">
+                {meta.genres.map(facet => (
+                    <li key={facet.value}>
+                        <Link href="#">
+                            {facet.value} ({facet.count})
+                        </Link>
+                    </li>
+                ))}
+            </Typography>
+            <Typography variant="subtitle2">
+                Century
+            </Typography>
+            <Typography component="ul">
+                {meta.centuries.map(facet => (
+                    <li key={facet.value}>
+                        <Link href="#">
+                            {facet.value} ({facet.count})
+                        </Link>
+                    </li>
+                ))}
+            </Typography>
+        </Box>
     );
 };
 ```

docs/img/List-facets.png

@@ -296,25 +296,25 @@ describe('<List />', () => {
     describe('title', () => {
         it('should display by default the title of the resource', async () => {
             render(<Basic />);
-            await screen.findByText('War and Peace');
+            await screen.findByText('War and Peace (1869)');
             screen.getAllByText('Books');
         });
 
         it('should render custom title string when defined', async () => {
             render(<Title />);
-            await screen.findByText('War and Peace');
+            await screen.findByText('War and Peace (1869)');
             screen.getByText('Custom list title');
         });
 
         it('should render custom title element when defined', async () => {
             render(<TitleElement />);
-            await screen.findByText('War and Peace');
+            await screen.findByText('War and Peace (1869)');
             screen.getByText('Custom list title');
         });
 
         it('should not render default title when false', async () => {
             render(<TitleFalse />);
-            await screen.findByText('War and Peace');
+            await screen.findByText('War and Peace (1869)');
             screen.getByText('Books');
         });
     });

packages/ra-ui-materialui/src/list/List.spec.tsx

@@ -7,17 +7,10 @@ import {
     TestMemoryRouter,
 } from 'ra-core';
 import fakeRestDataProvider from 'ra-data-fakerest';
-import {
-    Box,
-    Card,
-    Stack,
-    Typography,
-    Button,
-    Badge,
-    Chip,
-} from '@mui/material';
+import { Box, Card, Typography, Button, Link as MuiLink } from '@mui/material';
 
 import { List } from './List';
+import { SimpleList } from './SimpleList';
 import { ListActions } from './ListActions';
 import { Datagrid } from './datagrid';
 import { TextField } from '../field';
@@ -37,100 +30,125 @@ const data = {
             title: 'War and Peace',
             author: 'Leo Tolstoy',
             year: 1869,
+            summary:
+                'A historical novel that intertwines the lives of Russian aristocrats with the events of the Napoleonic wars.',
         },
         {
             id: 2,
-            title: 'Pride and Predjudice',
+            title: 'Pride and Prejudice',
             author: 'Jane Austen',
             year: 1813,
+            summary:
+                'A romantic novel exploring the themes of class, family, and societal expectations through the story of Elizabeth Bennet and Mr. Darcy.',
         },
         {
             id: 3,
             title: 'The Picture of Dorian Gray',
             author: 'Oscar Wilde',
             year: 1890,
+            summary:
+                'A philosophical tale about a man who remains youthful while a portrait of him ages, reflecting his moral corruption.',
         },
         {
             id: 4,
             title: 'Le Petit Prince',
             author: 'Antoine de Saint-Exupéry',
             year: 1943,
+            summary:
+                'A poetic and philosophical story about a young prince’s journey across planets, exploring themes of innocence and human nature.',
         },
         {
             id: 5,
             title: "Alice's Adventures in Wonderland",
             author: 'Lewis Carroll',
             year: 1865,
+            summary:
+                'A fantasy tale where Alice falls into a whimsical world, encountering strange creatures and exploring absurd adventures.',
         },
         {
             id: 6,
             title: 'Madame Bovary',
             author: 'Gustave Flaubert',
             year: 1856,
+            summary:
+                'A story of a dissatisfied woman trapped in provincial life, leading her to pursue romantic fantasies with tragic consequences.',
         },
         {
             id: 7,
             title: 'The Lord of the Rings',
             author: 'J. R. R. Tolkien',
             year: 1954,
+            summary:
+                'An epic fantasy novel following a group of heroes as they attempt to destroy a powerful ring and defeat the dark lord Sauron.',
         },
         {
             id: 8,
             title: "Harry Potter and the Philosopher's Stone",
             author: 'J. K. Rowling',
             year: 1997,
+            summary:
+                'The beginning of Harry Potter’s magical journey at Hogwarts, where he uncovers secrets about his past and faces dark forces.',
         },
         {
             id: 9,
             title: 'The Alchemist',
             author: 'Paulo Coelho',
             year: 1988,
+            summary:
+                'A spiritual novel that follows a young shepherd on a journey to find treasure, exploring themes of destiny and self-discovery.',
         },
         {
             id: 10,
-            title: 'A Catcher in the Rye',
+            title: 'The Catcher in the Rye',
             author: 'J. D. Salinger',
             year: 1951,
+            summary:
+                'A coming-of-age story about Holden Caulfield, a rebellious teenager navigating feelings of alienation and identity in post-war America.',
         },
         {
             id: 11,
             title: 'Ulysses',
             author: 'James Joyce',
             year: 1922,
+            summary:
+                'A modernist novel that chronicles the experiences of Leopold Bloom in Dublin, reflecting the complexity of human thought and life.',
         },
         {
             id: 12,
             title: 'One Hundred Years of Solitude',
             author: 'Gabriel García Márquez',
             year: 1967,
+            summary:
+                'A multi-generational tale of the Buendía family, blending reality and magic in the fictional town of Macondo.',
         },
         {
             id: 13,
             title: 'Snow Country',
             author: 'Yasunari Kawabata',
             year: 1956,
+            summary:
+                'A tragic love story set in Japan’s remote snowy regions, exploring beauty, isolation, and fleeting relationships.',
         },
     ],
     authors: [],
 };
+
 const dataProvider = fakeRestDataProvider(data);
 
 const BookList = () => {
-    const { data, error, isPending } = useListContext();
+    const { error, isPending } = useListContext();
     if (isPending) {
         return <div>Loading...</div>;
     }
     if (error) {
         return <div>Error: {error.message}</div>;
     }
     return (
-        <Stack spacing={2} sx={{ padding: 2 }}>
-            {data.map(book => (
-                <Typography key={book.id}>
-                    <i>{book.title}</i>, by {book.author} ({book.year})
-                </Typography>
-            ))}
-        </Stack>
+        <SimpleList
+            primaryText="%{title} (%{year})"
+            secondaryText="%{summary}"
+            tertiaryText={record => record.year}
+        />
     );
 };
 
@@ -610,19 +628,41 @@ export const ErrorInFetch = () => (
 const Facets = () => {
     const { isLoading, error, meta } = useListContext();
     if (isLoading || error) return null;
-    const facets = meta.facets;
     return (
-        <Stack direction="row" gap={3} mt={2} ml={1}>
-            {facets.map(facet => (
-                <Badge
-                    key={facet.value}
-                    badgeContent={facet.count}
-                    color="primary"
-                >
-                    <Chip label={facet.value} size="small" />
-                </Badge>
-            ))}
-        </Stack>
+        <Box order={-1} width={200} mt={7}>
+            <Typography variant="subtitle2" gutterBottom>
+                Genres
+            </Typography>
+            <Typography
+                component="ul"
+                p={0}
+                sx={{ listStylePosition: 'inside' }}
+            >
+                {meta.genres.map(facet => (
+                    <li key={facet.value}>
+                        <MuiLink href="#">
+                            {facet.value} ({facet.count})
+                        </MuiLink>
+                    </li>
+                ))}
+            </Typography>
+            <Typography variant="subtitle2" gutterBottom mt={2}>
+                Century
+            </Typography>
+            <Typography
+                component="ul"
+                p={0}
+                sx={{ listStylePosition: 'inside' }}
+            >
+                {meta.centuries.map(facet => (
+                    <li key={facet.value}>
+                        <MuiLink href="#">
+                            {facet.value} ({facet.count})
+                        </MuiLink>
+                    </li>
+                ))}
+            </Typography>
+        </Box>
     );
 };
 export const ResponseMetadata = () => (
@@ -635,10 +675,15 @@ export const ResponseMetadata = () => (
                     return {
                         ...result,
                         meta: {
-                            facets: [
-                                { value: 'Novels', count: 13 },
-                                { value: 'Essays', count: 0 },
-                                { value: 'Short stories', count: 0 },
+                            genres: [
+                                { value: 'Fictions', count: 168 },
+                                { value: 'Essays', count: 24 },
+                            ],
+                            centuries: [
+                                { value: '18th', count: 23 },
+                                { value: '19th', count: 78 },
+                                { value: '20th', count: 57 },
+                                { value: '21st', count: 34 },
                             ],
                         },
                     };
@@ -648,8 +693,7 @@ export const ResponseMetadata = () => (
             <Resource
                 name="books"
                 list={
-                    <List>
-                        <Facets />
+                    <List aside={<Facets />}>
                         <BookList />
                     </List>
                 }