document and test render prop on ReferenceManyField

Author: ThieryMichel

docs/ReferenceManyField.md

@@ -89,7 +89,8 @@ This example leverages [`<SingleFieldList>`](./SingleFieldList.md) to display an
 
 | Prop           | Required | Type                                                                              | Default                          | Description                                                                         |
 | -------------- | -------- | --------------------------------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
-| `children`     | Required | `Element`                                                                         | -                                | One or several elements that render a list of records based on a `ListContext`      |
+| `children`     | Required if no render | `Element`                                                                         | -                                | One or several elements that render a list of records based on a `ListContext`      |
+| `render`     | Required if no children | `(listContext) => Element`                                                                         | -                                | Function that receives a `ListContext` and render elements      |
 | `debounce`     | Optional | `number`                                                                          | 500                              | debounce time in ms for the `setFilters` callbacks                                  |
 | `empty`        | Optional | `ReactNode`                                                                       | -                                | Element to display when there are no related records.                                |
 | `filter`       | Optional | `Object`                                                                          | -                                | Filters to use when fetching the related records, passed to `getManyReference()`    |
@@ -163,6 +164,71 @@ export const AuthorShow = () => (
 );
 ```
 
+## `render`
+
+Alternatively to children you can pass a render prop to `<ReferenceManyField>`. The render prop will receive the list context as its argument, allowing to inline the render logic for both the list and the pagination.
+When receiving a render prop the `<ReferenceManyField>` component will ignore the children and the pagination property.
+
+```jsx
+import { Show, SimpleShowLayout, ReferenceManyField, DataTable, TextField, DateField } from 'react-admin';
+
+const CustomAuthorView = ({
+    source,
+    children,
+}: {
+    source: string;
+}) => {
+    const context = useListController();
+
+    if (context.isPending) {
+        return <p>Loading...</p>;
+    }
+
+    if (context.error) {
+        return <p className="error">{context.error.toString()}</p>;
+    }
+    return (
+        <p>
+            {listContext.data?.map((datum, index) => (
+                <li key={index}>{datum[source]}</li>
+            ))}
+        </p>
+    );
+};
+
+const AuthorShow = () => (
+    <Show>
+        <SimpleShowLayout>
+            <TextField source="first_name" />
+            <TextField source="last_name" />
+            <ReferenceManyField
+                reference="books"
+                target="author_id"
+                render={
+                    (context) => {
+
+                        if (context.isPending) {
+                            return <p>Loading...</p>;
+                        }
+
+                        if (context.error) {
+                            return <p className="error">{context.error.toString()}</p>;
+                        }
+                        return (
+                            <p>
+                                {listContext.data?.map((author, index) => (
+                                    <li key={index}>{author.name}</li>
+                                ))}
+                            </p>
+                        );
+                    }
+                }
+            />
+        </SimpleShowLayout>
+    </Show>
+);
+```
+
 ## `debounce`
 
 By default, `<ReferenceManyField>` does not refresh the data as soon as the user enters data in the filter form. Instead, it waits for half a second of user inactivity (via `lodash.debounce`) before calling the `dataProvider` on filter change. This is to prevent repeated (and useless) calls to the API.

packages/ra-ui-materialui/src/field/ReferenceManyField.spec.tsx

@@ -14,6 +14,7 @@ import {
     Empty,
     WithPagination,
     WithPaginationAndSelectAllLimit,
+    WithRenderProp,
 } from './ReferenceManyField.stories';
 
 const theme = createTheme();
@@ -206,6 +207,20 @@ describe('<ReferenceManyField />', () => {
         });
     });
 
+    it('should use render prop when provides', async () => {
+        render(<WithRenderProp />);
+        await waitFor(() => {
+            expect(screen.queryAllByRole('progressbar')).toHaveLength(0);
+        });
+        const items = await screen.findAllByRole('listitem');
+        expect(items).toHaveLength(5);
+        expect(items[0].textContent).toEqual('War and Peace');
+        expect(items[1].textContent).toEqual('Anna Karenina');
+        expect(items[2].textContent).toEqual('Resurrection');
+        expect(items[3].textContent).toEqual('The Idiot');
+        expect(items[4].textContent).toEqual('The Last Day of a Condemned');
+    });
+
     describe('pagination', () => {
         it('should render pagination based on total from getManyReference', async () => {
             const data = [

packages/ra-ui-materialui/src/field/ReferenceManyField.stories.tsx

@@ -286,3 +286,30 @@ export const FullApp = () => (
         </Admin>
     </TestMemoryRouter>
 );
+
+export const WithRenderProp = () => (
+    <Wrapper>
+        <ReferenceManyField
+            reference="books"
+            target="author_id"
+            render={({ error, isPending, data }) => {
+                if (isPending) {
+                    return <p>Loading...</p>;
+                }
+
+                if (error) {
+                    return <p style={{ color: 'red' }}>{error.message}</p>;
+                }
+                return (
+                    <>
+                        {data?.map((datum, index) => (
+                            <li role="listitem" key={index}>
+                                {datum.title}
+                            </li>
+                        ))}
+                    </>
+                );
+            }}
+        />
+    </Wrapper>
+);