Add offline support to <ReferenceInputBase>, <ReferenceInput> and <AutocompleteInput>

Author: djhi

docs/AutocompleteInput.md

@@ -67,6 +67,7 @@ The form value for the source must be the selected value, e.g.
 | `isPending`                | Optional | `boolean`             | `false`                                                             | If `true`, the component will display a loading indicator.                                                                                                                                                          |
 | `inputText`                | Optional | `Function`            | `-`                                                                 | Required if `optionText` is a custom Component, this function must return the text displayed for the current selection.                                                                                             |
 | `matchSuggestion`          | Optional | `Function`            | `-`                                                                 | Required if `optionText` is a React element. Function returning a boolean indicating whether a choice matches the filter. `(filter, choice) => boolean`                                                             |
+| `offline`                  | Optional | `ReactNode`         | -        | What to render when there is no network connectivity when fetching the choices |
 | `onChange`                 | Optional | `Function`            | `-`                                                                 | A function called with the new value, along with the selected record, when the input value changes |
 | `onCreate`                 | Optional | `Function`            | `-`                                                                 | A function called with the current filter value when users choose to create a new choice.                                                                                                                           |
 | `optionText`               | Optional | `string` | `Function` | `Component` |  `undefined` | `record Representation` | Field name of record to display in the suggestion item or function using the choice object as argument                                                                                                              |
@@ -340,6 +341,27 @@ const UserCountry = () => {
 }
 ```
 
+## `offline`
+
+`<AutocompleteInput>` can display a custom message when it can't fetch the choices because there is no network connectivity, thanks to the `offline` prop.
+
+```jsx
+<ReferenceInput source="user_id" reference="users">
+    <AutocompleteInput offline={<span>No network, could not fetch data</span>} />
+</ReferenceInput>
+```
+
+You can pass either a React element or a string to the `offline` prop:
+
+```jsx
+<ReferenceInput source="user_id" reference="users">
+    <AutocompleteInput offline={<span>No network, could not fetch data</span>} />
+</ReferenceInput>
+<ReferenceInput source="user_id" reference="users">
+    <AutocompleteInput offline="No network, could not fetch data" />
+</ReferenceInput>
+```
+
 ## `onChange`
 
 Use the `onChange` prop to get notified when the input value changes.

docs/ReferenceInput.md

@@ -110,6 +110,7 @@ See the [`children`](#children) section for more details.
 | `label`            | Optional | `string`                                    | -                                | Useful only when `ReferenceInput` is in a Filter array, the label is used as the Filter label. |
 | `page`             | Optional | `number`                                    | 1                                | The current page number                                                                        |
 | `perPage`          | Optional | `number`                                    | 25                               | Number of suggestions to show                                                                  |
+| `offline`          | Optional | `ReactNode`         | -        | What to render when there is no network connectivity when loading the record |
 | `queryOptions`     | Optional | [`UseQueryOptions`](https://tanstack.com/query/v5/docs/react/reference/useQuery)                       | `{}`                             | `react-query` client options                                                                   |
 | `sort`             | Optional | `{ field: String, order: 'ASC' or 'DESC' }` | `{ field:'id', order:'DESC' }` | How to order the list of suggestions                                                           |
 
@@ -191,6 +192,26 @@ const filters = [
 ];
 ```
 
+## `offline`
+
+`<ReferenceInput>` can display a custom message when the referenced record is missing because there is no network connectivity, thanks to the `offline` prop.
+
+```jsx
+<ReferenceInput source="user_id" reference="users" offline="No network, could not fetch data" />
+```
+
+`<ReferenceInput>` renders the `offline` element when:
+
+- the referenced record is missing (no record in the `users` table with the right `user_id`), and
+- there is no network connectivity
+
+You can pass either a React element or a string to the `offline` prop:
+
+```jsx
+<ReferenceInput source="user_id" reference="users" offline={<span>No network, could not fetch data</span>} />
+<ReferenceInput source="user_id" reference="users" offline="No network, could not fetch data" />
+```
+
 ## `parse`
 
 By default, children of `<ReferenceInput>` transform the empty form value (an empty string) into `null` before passing it to the `dataProvider`. 

packages/ra-core/src/controller/input/ReferenceInputBase.spec.tsx

@@ -17,6 +17,7 @@ import {
     SelfReference,
     QueryOptions,
     Meta,
+    Offline,
 } from './ReferenceInputBase.stories';
 
 describe('<ReferenceInputBase />', () => {
@@ -68,8 +69,8 @@ describe('<ReferenceInputBase />', () => {
             return <div>{resource}</div>;
         };
         const dataProvider = testDataProvider({
-            // @ts-ignore
             getList: () =>
+                // @ts-ignore
                 Promise.resolve({ data: [{ id: 1 }, { id: 2 }], total: 2 }),
         });
         render(
@@ -92,8 +93,8 @@ describe('<ReferenceInputBase />', () => {
             return <div aria-label="total">{total}</div>;
         };
         const dataProvider = testDataProvider({
-            // @ts-ignore
             getList: () =>
+                // @ts-ignore
                 Promise.resolve({ data: [{ id: 1 }, { id: 2 }], total: 2 }),
         });
         render(
@@ -187,6 +188,15 @@ describe('<ReferenceInputBase />', () => {
         screen.getByText('Save').click();
         await screen.findByText('Proust', undefined, { timeout: 5000 });
     });
+
+    it('should render the offline prop node when offline', async () => {
+        render(<Offline />);
+        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('lorem');
+    });
 });
 
 const AutocompleteInput = (

packages/ra-core/src/controller/input/ReferenceInputBase.stories.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { QueryClient } from '@tanstack/react-query';
+import { onlineManager, QueryClient } from '@tanstack/react-query';
 import polyglotI18nProvider from 'ra-i18n-polyglot';
 import englishMessages from 'ra-language-english';
 import fakeRestDataProvider from 'ra-data-fakerest';
@@ -22,6 +22,7 @@ import {
     ListBase,
     Resource,
     testDataProvider,
+    useIsOffline,
     useListContext,
     useRedirect,
 } from '../..';
@@ -213,7 +214,7 @@ const dataProvider = testDataProvider({
                         data: tags,
                         total: tags.length,
                     }),
-                1500
+                process.env.NODE_ENV === 'test' ? 0 : 1500
             );
         }),
     // @ts-ignore
@@ -522,3 +523,54 @@ export const Meta = ({
         </CoreAdmin>
     </TestMemoryRouter>
 );
+
+export const Offline = () => (
+    <CoreAdminContext dataProvider={dataProvider} i18nProvider={i18nProvider}>
+        <Form onSubmit={() => {}} defaultValues={{ tag_ids: [5] }}>
+            <div
+                style={{
+                    width: '200px',
+                    display: 'flex',
+                    flexDirection: 'column',
+                    gap: '10px',
+                }}
+            >
+                <RenderChildOnDemand>
+                    <ReferenceInputBase
+                        reference="tags"
+                        resource="posts"
+                        source="tag_ids"
+                        offline={<p>You are offline, cannot load data</p>}
+                    >
+                        <SelectInput optionText="name" />
+                    </ReferenceInputBase>
+                </RenderChildOnDemand>
+                <SimulateOfflineButton />
+            </div>
+        </Form>
+    </CoreAdminContext>
+);
+
+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>}
+        </>
+    );
+};

packages/ra-core/src/controller/input/ReferenceInputBase.tsx

@@ -70,6 +70,7 @@ export const ReferenceInputBase = (props: ReferenceInputBaseProps) => {
         reference,
         sort = { field: 'id', order: 'DESC' },
         filter = {},
+        offline,
     } = props;
 
     const controllerProps = useReferenceInputController({
@@ -78,10 +79,18 @@ export const ReferenceInputBase = (props: ReferenceInputBaseProps) => {
         filter,
     });
 
+    const { isPaused, allChoices } = controllerProps;
+
+    const shouldRenderOffline =
+        isPaused &&
+        allChoices == null &&
+        offline !== false &&
+        offline !== undefined;
+
     return (
         <ResourceContextProvider value={reference}>
             <ChoicesContextProvider value={controllerProps}>
-                {children}
+                {shouldRenderOffline ? offline : children}
             </ChoicesContextProvider>
         </ResourceContextProvider>
     );
@@ -91,4 +100,5 @@ export interface ReferenceInputBaseProps
     extends InputProps,
         UseReferenceInputControllerParams {
     children?: ReactNode;
+    offline?: ReactNode;
 }