Merge pull request #10865 from marmelab/offline-support-reference-many-field

Add offline support to `<ReferenceManyFieldBase>`

Author: fzaninotto

docs/ReferenceManyFieldBase.md

@@ -94,6 +94,7 @@ export const PostList = () => (
 | `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()`    |
+| `offline`      | Optional | `ReactNode`                                                                       | -                                | Element to display when there are no related records because of lack of network connectivity. |
 | `perPage`      | Optional | `number`                                                                          | 25                               | Maximum number of referenced records to fetch                                       |
 | `queryOptions` | Optional | [`UseQuery Options`](https://tanstack.com/query/v3/docs/react/reference/useQuery) | `{}`                             | `react-query` options for the `getMany` query                                       |
 | `reference`    | Required | `string`                                                                          | -                                | The name of the resource for the referenced records, e.g. 'books'                   |
@@ -135,45 +136,6 @@ export const AuthorShow = () => (
 );
 ```
 
-## `render`
-
-Alternatively, you can pass a `render` function prop instead of children. The `render` prop will receive the `ListContext` as arguments, allowing to inline the render logic.
-When receiving a `render` function prop the `<ReferenceManyFieldBase>` component will ignore the children property.
-
-```jsx
-import { ShowBase, ReferenceManyFieldBase } from 'react-admin';
-
-const AuthorShow = () => (
-    <ShowBase>
-        <ReferenceManyFieldBase
-            reference="books"
-            target="author_id"
-            render={
-                ({ isPending, error, data }) => {
-
-                    if (isPending) {
-                        return <p>Loading...</p>;
-                    }
-
-                    if (error) {
-                        return <p className="error">{error.toString()}</p>;
-                    }
-                    return (
-                        <ul>
-                            {data.map((book, index) => (
-                                <li key={index}>
-                                    <i>{book.title}</i>, published on{' '}{book.published_at}
-                                </li>
-                            ))}
-                        </ul>
-                    );
-                }
-            }
-        />
-    </ShowBase>
-);
-```
-
 ## `debounce`
 
 By default, `<ReferenceManyFieldBase>` 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.
@@ -191,7 +153,7 @@ const PostCommentsField = () => (
 
 ## `empty`
 
-Use `empty` to customize the text displayed when the related record is empty.
+Use `empty` to customize the text displayed when there are no related records.
 
 ```jsx
 <ReferenceManyFieldBase
@@ -203,18 +165,6 @@ Use `empty` to customize the text displayed when the related record is empty.
 </ReferenceManyFieldBase>
 ```
 
-`empty` also accepts a translation key.
-
-```jsx
-<ReferenceManyFieldBase
-    reference="books"
-    target="author_id"
-    empty="resources.authors.fields.books.empty"
->
-    ...
-</ReferenceManyFieldBase>
-```
-
 `empty` also accepts a `ReactNode`.
 
 ```jsx
@@ -245,6 +195,32 @@ You can filter the query used to populate the possible values. Use the `filter`
 
 {% endraw %}
 
+## `offline`
+
+Use `offline` to customize the text displayed when there are no related records because of lack of network connectivity.
+
+```jsx
+<ReferenceManyFieldBase
+    reference="books"
+    target="author_id"
+    offline="Offline, could not load data"
+>
+    ...
+</ReferenceManyFieldBase>
+```
+
+`offline` also accepts a `ReactNode`.
+
+```jsx
+<ReferenceManyFieldBase
+    reference="books"
+    target="author_id"
+    empty={<p>Offline, could not load data</p>}
+>
+    ...
+</ReferenceManyFieldBase>
+```
+
 ## `perPage`
 
 By default, react-admin restricts the possible values to 25 and displays no pagination control. You can change the limit by setting the `perPage` prop:
@@ -281,6 +257,45 @@ For instance, if you want to display the `books` of a given `author`, the `refer
 </ReferenceManyFieldBase>
 ```
 
+## `render`
+
+Alternatively, you can pass a `render` function prop instead of children. The `render` prop will receive the `ListContext` as arguments, allowing to inline the render logic.
+When receiving a `render` function prop the `<ReferenceManyFieldBase>` component will ignore the children property.
+
+```jsx
+import { ShowBase, ReferenceManyFieldBase } from 'react-admin';
+
+const AuthorShow = () => (
+    <ShowBase>
+        <ReferenceManyFieldBase
+            reference="books"
+            target="author_id"
+            render={
+                ({ isPending, error, data }) => {
+
+                    if (isPending) {
+                        return <p>Loading...</p>;
+                    }
+
+                    if (error) {
+                        return <p className="error">{error.toString()}</p>;
+                    }
+                    return (
+                        <ul>
+                            {data.map((book, index) => (
+                                <li key={index}>
+                                    <i>{book.title}</i>, published on{' '}{book.published_at}
+                                </li>
+                            ))}
+                        </ul>
+                    );
+                }
+            }
+        />
+    </ShowBase>
+);
+```
+
 ## `sort`
 
 By default, it orders the possible values by id desc. You can change this order by setting the `sort` prop (an object with `field` and `order` properties).

packages/ra-core/src/controller/field/ReferenceManyFieldBase.spec.tsx

@@ -1,9 +1,10 @@
 import * as React from 'react';
-import { render, screen, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import {
     Basic,
     Errored,
     Loading,
+    Offline,
     WithRenderProp,
 } from './ReferenceManyFieldBase.stories';
 
@@ -138,4 +139,21 @@ describe('ReferenceManyFieldBase', () => {
             });
         });
     });
+
+    it('should render the offline prop node when offline', async () => {
+        render(<Offline offline={<p>You are offline, cannot load data</p>} />);
+        fireEvent.click(await screen.findByText('Simulate offline'));
+        fireEvent.click(await screen.findByText('Toggle Child'));
+        await screen.findByText('You are offline, cannot load data');
+        fireEvent.click(await screen.findByText('Simulate online'));
+        await screen.findByText('War and Peace');
+    });
+    it('should allow children to handle the offline state', async () => {
+        render(<Offline offline={undefined} />);
+        fireEvent.click(await screen.findByText('Simulate offline'));
+        fireEvent.click(await screen.findByText('Toggle Child'));
+        await screen.findByText('AuthorList: Offline. Could not load data');
+        fireEvent.click(await screen.findByText('Simulate online'));
+        await screen.findByText('War and Peace');
+    });
 });

packages/ra-core/src/controller/field/ReferenceManyFieldBase.stories.tsx

@@ -1,13 +1,13 @@
 import * as React from 'react';
-import { QueryClient } from '@tanstack/react-query';
+import { onlineManager, QueryClient } from '@tanstack/react-query';
 import { CoreAdmin } from '../../core/CoreAdmin';
 import { Resource } from '../../core/Resource';
 import { ShowBase } from '../../controller/show/ShowBase';
 import { TestMemoryRouter } from '../../routing';
 import { ReferenceManyFieldBase } from './ReferenceManyFieldBase';
 import { ListBase, ListIterator, useListContext } from '../list';
-import { DataTableBase } from '../../dataTable';
 import fakeRestDataProvider from 'ra-data-fakerest';
+import { useIsOffline } from '../../core';
 
 export default {
     title: 'ra-core/controller/field/ReferenceManyFieldBase',
@@ -308,13 +308,102 @@ export const WithRenderProp = ({
     </TestMemoryRouter>
 );
 
+export const Offline = ({ offline }) => {
+    return (
+        <TestMemoryRouter initialEntries={['/authors/1/show']}>
+            <CoreAdmin
+                dataProvider={dataProviderWithAuthors}
+                queryClient={
+                    new QueryClient({
+                        defaultOptions: {
+                            queries: {
+                                retry: false,
+                            },
+                        },
+                    })
+                }
+            >
+                <Resource name="books" />
+                <Resource
+                    name="authors"
+                    show={
+                        <ShowBase>
+                            <RenderChildOnDemand>
+                                <ReferenceManyFieldBase
+                                    target="author"
+                                    source="id"
+                                    reference="books"
+                                    offline={offline}
+                                >
+                                    <AuthorList source="title" />
+                                </ReferenceManyFieldBase>
+                            </RenderChildOnDemand>
+                            <p>
+                                <SimulateOfflineButton />
+                            </p>
+                        </ShowBase>
+                    }
+                />
+            </CoreAdmin>
+        </TestMemoryRouter>
+    );
+};
+
+Offline.args = {
+    offline: 'let children handle offline state',
+};
+
+Offline.argTypes = {
+    offline: {
+        control: { type: 'radio' },
+        options: [
+            'let children handle offline state',
+            'handle offline state in ReferenceManyFieldBase',
+        ],
+        mapping: {
+            'let children handle offline state': undefined,
+            'handle offline state in ReferenceManyFieldBase': (
+                <p>You are offline, cannot load data</p>
+            ),
+        },
+    },
+};
+
+const SimulateOfflineButton = () => {
+    const isOffline = useIsOffline();
+    return (
+        <button
+            type="button"
+            onClick={() => onlineManager.setOnline(isOffline)}
+        >
+            {isOffline ? 'Simulate online' : 'Simulate offline'}
+        </button>
+    );
+};
+
+const RenderChildOnDemand = ({ children }) => {
+    const [showChild, setShowChild] = React.useState(false);
+    return (
+        <>
+            <button onClick={() => setShowChild(!showChild)}>
+                Toggle Child
+            </button>
+            {showChild && <div>{children}</div>}
+        </>
+    );
+};
+
 const AuthorList = ({ source }) => {
-    const { isPending, error, data } = useListContext();
+    const { isPaused, isPending, error, data } = useListContext();
 
-    if (isPending) {
+    if (isPending && !isPaused) {
         return <p>Loading...</p>;
     }
 
+    if (isPaused) {
+        return <p>AuthorList: Offline. Could not load data</p>;
+    }
+
     if (error) {
         return <p style={{ color: 'red' }}>{error.toString()}</p>;
     }