Document standalone usage of WithListContext and fix error element property.

Author: Madeorsk

docs/WithListContext.md

@@ -12,13 +12,13 @@ Use it to render a list of records already fetched.
 
 ## Usage
 
-The most common use case for `<WithListContext>` is to build a custom list view on-the-fly, without creating a new component, in a place where records are available inside a `ListContext`. 
+The most common use case for `<WithListContext>` is to build a custom list view on-the-fly, without creating a new component, in a place where records are available inside a `ListContext`.
 
 For instance, a list of book tags fetched via [`<ReferenceArrayField>`](./ReferenceArrayField.md): 
 
 ```jsx
 import { List, DataTable, ReferenceArrayField, WithListContext } from 'react-admin';
-import { Chip, Stack } from '@mui/material';
+import { Chip, Stack, Typography } from '@mui/material';
 
 const BookList = () => (
     <List>
@@ -27,15 +27,18 @@ const BookList = () => (
             <DataTable.Col source="title" />
             <DataTable.Col source="tag_ids" label="Tags">
                 <ReferenceArrayField reference="tags" source="tag_ids">
-                    <WithListContext render={({ isPending, data }) => (
-                        !isPending && (
+                    <WithListContext
+                        loading={<Typography>Loading tags...</Typography>}
+												errorElement={<Typography>Error while loading tags</Typography>}
+												empty={<Typography>No associated tags</Typography>}
+                        render={({ data }) => (
                             <Stack direction="row" spacing={1}>
                                 {data.map(tag => (
                                     <Chip key={tag.id} label={tag.name} />
                                 ))}
                             </Stack>
-                        )
-                    )} />
+                        )}
+                    />
                 </ReferenceArrayField>
             </DataTable.Col>
         </DataTable>
@@ -45,10 +48,11 @@ const BookList = () => (
 
 ![List of tags](./img/reference-array-field.png)
 
-The equivalent with `useListContext` would require an intermediate component:
+The equivalent with `useListContext` would require an intermediate component, manually handling the loading, error, and empty states:
 
 ```jsx
 import { List, DataTable, ReferenceArrayField, WithListContext } from 'react-admin';
+import { Chip, Stack, Typography } from '@mui/material';
 
 const BookList = () => (
     <List>
@@ -65,31 +69,71 @@ const BookList = () => (
 );
 
 const TagList = () => {
-    const { isPending, data } = useListContext();
-    return isPending 
-        ? null
-        : (
-            <Stack direction="row" spacing={1}>
-                {data.map(tag => (
-                    <Chip key={tag.id} label={tag.name} />
-                ))}
-            </Stack>
-        );
+    const { isPending, error, data, total } = useListContext();
+    
+    if (isPending) {
+				return <Typography>Loading tags...</Typography>;
+		}
+    
+    if (error) {
+				return <Typography>Error while loading tags</Typography>;
+		}
+    
+    if (data == null || data.length === 0 || total === 0) {
+				return <Typography>No associated tags</Typography>;
+		}
+    
+    return (
+        <Stack direction="row" spacing={1}>
+            {data.map(tag => (
+                <Chip key={tag.id} label={tag.name} />
+            ))}
+        </Stack>
+    );
 };
 ```
 
 Whether you use `<WithListContext>` or `useListContext` is a matter of coding style.
 
+## Standalone usage
+
+You can also use `<WithListContext>` outside of a `ListContext` by filling `data`, `total`, `error`, and `isPending` properties manually.
+
+```jsx
+import { WithListContext } from 'react-admin';
+import { Chip, Stack, Typography } from '@mui/material';
+
+const TagList = ({data, isPending}) => (
+		<WithListContext
+				data={data}
+				isPending={isPending}
+        loading={<Typography>Loading tags...</Typography>}
+				empty={<Typography>No associated tags</Typography>}
+				render={({ data }) => (
+						<Stack direction="row" spacing={1}>
+								{data.map(tag => (
+										<Chip key={tag.id} label={tag.name} />
+								))}
+						</Stack>
+				)}
+		/>
+);
+```
+
 ## Props
 
 `<WithListContext>` accepts a single `render` prop, which should be a function.
 
-| Prop      | Required | Type           | Default | Description                                             |
-|-----------|----------|----------------|---------|---------------------------------------------------------|
-| `empty`   | Optional | `ReactElement` |         | The component to display when the data is empty.        |
-| `error`   | Optional | `ReactElement` |         | The component to display in case of error.              |
-| `loading` | Optional | `ReactElement` |         | The component to display while checking authorizations. |
-| `render`  | Required | `function`     |         | The function to render the data                         |
+| Prop           | Required | Type           | Default | Description                                               |
+|----------------|----------|----------------|---------|-----------------------------------------------------------|
+| `data`         | Optional | `RecordType[]` |         | The list data in standalone usage.                        |
+| `empty`        | Optional | `ReactNode`    |         | The component to display when the data is empty.          |
+| `error`        | Optional | `Error`        |         | The error in standalone usage.                            |
+| `errorElement` | Optional | `ReactNode`    |         | The component to display in case of error.                |
+| `isPending`    | Optional | `boolean`      |         | Determine if the list is loading in standalone usage.     |
+| `loading`      | Optional | `ReactNode`    |         | The component to display while checking authorizations.   |
+| `render`       | Required | `function`     |         | The function to render the data                           |
+| `total`        | Optional | `number`       |         | The total number of data in the list in standalone usage. |
 
 ## `empty`
 
@@ -114,26 +158,26 @@ If `empty` is not provided, the render function will be called with empty data.
 />
 ```
 
-## `error`
+## `errorElement`
 
-Use `error` to display a message when an error is thrown.
+Use `errorElement` to display a message when an error is thrown.
 
-If `error` is not provided, the render function will be called with the error.
+If `errorElement` is not provided, the render function will be called with the error.
 
 ```jsx
 <WithListContext
-  error={<p>Error while loading books...</p>}
-  render={({ data }) => (
-      <ul>
-          {data.map(book => (
-              <li key={book.id}>
-                  <i>{book.title}</i>, published on
-                  {book.published_at}
-              </li>
-          ))}
-      </ul>
-  )}
-  loading={<p>Loading...</p>}
+    errorElement={<p>Error while loading books...</p>}
+    render={({ data }) => (
+        <ul>
+            {data.map(book => (
+                <li key={book.id}>
+                    <i>{book.title}</i>, published on
+                    {book.published_at}
+                </li>
+            ))}
+        </ul>
+    )}
+    loading={<p>Loading...</p>}
 />
 ```
 

packages/ra-core/src/controller/list/WithListContext.tsx

@@ -22,7 +22,7 @@ import { useListContextWithProps } from './useListContextWithProps';
 export const WithListContext = <RecordType extends RaRecord>({
     empty,
     loading,
-    error: errorElement,
+    errorElement,
     render,
     ...props
 }: WithListContextProps<RecordType>) => {
@@ -55,5 +55,5 @@ export type WithListContextProps<RecordType extends RaRecord> = Partial<
     ) => ReactElement | false | null;
     empty?: React.ReactNode;
     loading?: React.ReactNode;
-    error?: React.ReactNode;
+    errorElement?: React.ReactNode;
 };