Add offline support to <ReferenceArrayInputBase> and <ReferenceArrayInput>

Author: djhi

docs/ReferenceArrayInput.md

@@ -105,6 +105,7 @@ See the [`children`](#children) section for more details.
 | `enableGet Choices` | Optional | `({q: string}) => boolean`                  | `() => true`                       | Function taking the `filterValues` and returning a boolean to enable the `getList` call.                           |
 | `filter`           | Optional | `Object`                                    | `{}`                               | Permanent filters to use for getting the suggestion list                                                            |
 | `label`            | Optional | `string`                                    | -                                  | Useful only when `ReferenceArrayInput` is in a Filter array, the label is used as the Filter label.                 |
+| `offline`          | Optional | `ReactNode`                                 | -                                  | What to render when there is no network connectivity when loading the record |
 | `page`             | Optional | `number`                                    | 1                                  | The current page number                                                                                             |
 | `perPage`          | Optional | `number`                                    | 25                                 | Number of suggestions to show                                                                                       |
 | `queryOptions`     | Optional | [`UseQueryOptions`](https://tanstack.com/query/v5/docs/react/reference/useQuery) | `{}` | `react-query` client options     |
@@ -217,6 +218,26 @@ const filters = [
 ];
 ```
 
+## `offline`
+
+`<ReferenceArrayInput>` can display a custom message when the referenced record is missing because there is no network connectivity, thanks to the `offline` prop.
+
+```jsx
+<ReferenceArrayInput source="tags_ids" reference="tags" offline="No network, could not fetch data" />
+```
+
+`<ReferenceArrayInput>` renders the `offline` element when:
+
+- the referenced record is missing (no record in the `tags` table with the right `tags_ids`), and
+- there is no network connectivity
+
+You can pass either a React element or a string to the `offline` prop:
+
+```jsx
+<ReferenceArrayInput source="tags_ids" reference="tags" offline={<span>No network, could not fetch data</span>} />
+<ReferenceArrayInput source="tags_ids" reference="tags" offline="No network, could not fetch data" />
+```
+
 ## `parse`
 
 By default, children of `<ReferenceArrayInput>` transform the empty form value (an empty string) into `null` before passing it to the `dataProvider`. 

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

@@ -1,7 +1,7 @@
 import * as React from 'react';
-import { render, screen, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { testDataProvider } from 'ra-core';
-import { Basic, WithError } from './ReferenceArrayInputBase.stories';
+import { Basic, Offline, WithError } from './ReferenceArrayInputBase.stories';
 
 describe('<ReferenceArrayInputBase>', () => {
     afterEach(async () => {
@@ -51,4 +51,13 @@ describe('<ReferenceArrayInputBase>', () => {
             });
         });
     });
+
+    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('Architecture');
+    });
 });

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

@@ -20,9 +20,10 @@ import {
     ChoicesProps,
     useChoicesContext,
 } from '../../form';
-import { useGetRecordRepresentation } from '../..';
+import { useGetRecordRepresentation, useIsOffline } from '../..';
+import { onlineManager } from '@tanstack/react-query';
 
-export default { title: 'ra-core/controller/ReferenceArrayInputBase' };
+export default { title: 'ra-core/controller/input/ReferenceArrayInputBase' };
 
 const tags = [
     { id: 0, name: '3D' },
@@ -234,3 +235,80 @@ export const WithError = () => (
         </CoreAdmin>
     </TestMemoryRouter>
 );
+
+export const Offline = () => (
+    <TestMemoryRouter initialEntries={['/posts/create']}>
+        <CoreAdmin
+            dataProvider={defaultDataProvider}
+            i18nProvider={i18nProvider}
+        >
+            <Resource
+                name="posts"
+                create={
+                    <CreateBase resource="posts" record={{ tags_ids: [1, 3] }}>
+                        <h1>Create Post</h1>
+                        <Form>
+                            <div
+                                style={{
+                                    width: '200px',
+                                    display: 'flex',
+                                    flexDirection: 'column',
+                                    gap: '10px',
+                                }}
+                            >
+                                <RenderChildOnDemand>
+                                    <ReferenceArrayInputBase
+                                        reference="tags"
+                                        resource="posts"
+                                        source="tags_ids"
+                                        offline={
+                                            <p>
+                                                You are offline, cannot load
+                                                data
+                                            </p>
+                                        }
+                                    >
+                                        <CheckboxGroupInput optionText="name" />
+                                    </ReferenceArrayInputBase>
+                                </RenderChildOnDemand>
+                                <SimulateOfflineButton />
+                            </div>
+                        </Form>
+                    </CreateBase>
+                }
+            />
+        </CoreAdmin>
+    </TestMemoryRouter>
+);
+
+const SimulateOfflineButton = () => {
+    const isOffline = useIsOffline();
+    return (
+        <button
+            type="button"
+            onClick={event => {
+                event.preventDefault();
+                onlineManager.setOnline(isOffline);
+            }}
+        >
+            {isOffline ? 'Simulate online' : 'Simulate offline'}
+        </button>
+    );
+};
+
+const RenderChildOnDemand = ({ children }) => {
+    const [showChild, setShowChild] = React.useState(false);
+    return (
+        <>
+            <button
+                onClick={event => {
+                    event.preventDefault();
+                    setShowChild(!showChild);
+                }}
+            >
+                Toggle Child
+            </button>
+            {showChild && <div>{children}</div>}
+        </>
+    );
+};

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

@@ -79,7 +79,14 @@ import { ChoicesContextValue } from '../../form';
 export const ReferenceArrayInputBase = <RecordType extends RaRecord = any>(
     props: ReferenceArrayInputBaseProps<RecordType>
 ) => {
-    const { children, filter = defaultFilter, reference, render, sort } = props;
+    const {
+        children,
+        filter = defaultFilter,
+        offline,
+        reference,
+        render,
+        sort,
+    } = props;
     if (children && React.Children.count(children) !== 1) {
         throw new Error(
             '<ReferenceArrayInputBase> only accepts a single child (like <AutocompleteArrayInput>)'
@@ -97,11 +104,21 @@ export const ReferenceArrayInputBase = <RecordType extends RaRecord = any>(
         sort,
         filter,
     });
+    const { isPaused, isPending } = controllerProps;
+    // isPending is true: there's no cached data and no query attempt was finished yet
+    // isPaused is true: the query was paused (e.g. due to a network issue)
+    // Both true: we're offline and have no data to show
+    const shouldRenderOffline =
+        isPaused && isPending && offline !== undefined && offline !== false;
 
     return (
         <ResourceContextProvider value={reference}>
             <ChoicesContextProvider value={controllerProps}>
-                {render ? render(controllerProps) : children}
+                {shouldRenderOffline
+                    ? offline
+                    : render
+                      ? render(controllerProps)
+                      : children}
             </ChoicesContextProvider>
         </ResourceContextProvider>
     );
@@ -114,4 +131,5 @@ export interface ReferenceArrayInputBaseProps<RecordType extends RaRecord = any>
         UseReferenceArrayInputParams<RecordType> {
     children?: React.ReactNode;
     render?: (context: ChoicesContextValue<RecordType>) => React.ReactNode;
+    offline?: React.ReactNode;
 }

packages/ra-core/src/controller/input/useReferenceArrayInputController.ts

@@ -61,7 +61,9 @@ export const useReferenceArrayInputController = <
         error: errorGetMany,
         isLoading: isLoadingGetMany,
         isFetching: isFetchingGetMany,
+        isPaused: isPausedGetMany,
         isPending: isPendingGetMany,
+        isPlaceholderData: isPlaceholderDataGetMany,
         refetch: refetchGetMany,
     } = useGetManyAggregate<RecordType>(
         reference,
@@ -99,7 +101,9 @@ export const useReferenceArrayInputController = <
         error: errorGetList,
         isLoading: isLoadingGetList,
         isFetching: isFetchingGetList,
+        isPaused: isPausedGetList,
         isPending: isPendingGetList,
+        isPlaceholderData: isPlaceholderDataGetList,
         refetch: refetchGetMatching,
     } = useGetList<RecordType>(
         reference,
@@ -153,7 +157,9 @@ export const useReferenceArrayInputController = <
         hideFilter: paramsModifiers.hideFilter,
         isFetching: isFetchingGetMany || isFetchingGetList,
         isLoading: isLoadingGetMany || isLoadingGetList,
+        isPaused: isPausedGetMany || isPausedGetList,
         isPending: isPendingGetMany || isPendingGetList,
+        isPlaceholderData: isPlaceholderDataGetMany || isPlaceholderDataGetList,
         page: params.page,
         perPage: params.perPage,
         refetch,

packages/ra-ui-materialui/src/input/ReferenceArrayInput.stories.tsx

@@ -5,6 +5,7 @@ import {
     Resource,
     testDataProvider,
     TestMemoryRouter,
+    useIsOffline,
 } from 'ra-core';
 import polyglotI18nProvider from 'ra-i18n-polyglot';
 import englishMessages from 'ra-language-english';
@@ -20,6 +21,7 @@ import { ReferenceArrayInput } from './ReferenceArrayInput';
 import { AutocompleteArrayInput } from './AutocompleteArrayInput';
 import { SelectArrayInput } from './SelectArrayInput';
 import { CheckboxGroupInput } from './CheckboxGroupInput';
+import { onlineManager } from '@tanstack/react-query';
 
 export default { title: 'ra-ui-materialui/input/ReferenceArrayInput' };
 
@@ -274,3 +276,65 @@ export const DifferentIdTypes = () => {
         </AdminContext>
     );
 };
+
+export const Offline = () => {
+    const fakeData = {
+        bands: [{ id: 1, name: 'band_1', members: [1, '2'] }],
+        artists: [
+            { id: 1, name: 'artist_1' },
+            { id: 2, name: 'artist_2' },
+            { id: 3, name: 'artist_3' },
+        ],
+    };
+    return (
+        <TestMemoryRouter>
+            <AdminContext
+                dataProvider={fakeRestProvider(
+                    fakeData,
+                    process.env.NODE_ENV !== 'test'
+                )}
+                i18nProvider={i18nProvider}
+            >
+                <>
+                    <Edit resource="bands" id={1} sx={{ width: 600 }}>
+                        <SimpleForm>
+                            <RenderChildOnDemand>
+                                <ReferenceArrayInput
+                                    source="members"
+                                    reference="artists"
+                                />
+                            </RenderChildOnDemand>
+                        </SimpleForm>
+                    </Edit>
+                    <p>
+                        <SimulateOfflineButton />
+                    </p>
+                </>
+            </AdminContext>
+        </TestMemoryRouter>
+    );
+};
+
+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 type="button" onClick={() => setShowChild(!showChild)}>
+                Toggle Child
+            </button>
+            {showChild && <div>{children}</div>}
+        </>
+    );
+};

packages/ra-ui-materialui/src/input/ReferenceArrayInput.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { ReferenceArrayInputBase, ReferenceArrayInputBaseProps } from 'ra-core';
 import { AutocompleteArrayInput } from './AutocompleteArrayInput';
+import { Offline } from '../Offline';
 
 /**
  * An Input component for fields containing a list of references to another resource.
@@ -70,19 +71,26 @@ import { AutocompleteArrayInput } from './AutocompleteArrayInput';
  * a `setFilters` function. You can call this function to filter the results.
  */
 export const ReferenceArrayInput = (props: ReferenceArrayInputProps) => {
-    const { children = defaultChildren, ...rest } = props;
+    const {
+        children = defaultChildren,
+        offline = defaultOffline,
+        ...rest
+    } = props;
     if (React.Children.count(children) !== 1) {
         throw new Error(
             '<ReferenceArrayInput> only accepts a single child (like <AutocompleteArrayInput>)'
         );
     }
 
     return (
-        <ReferenceArrayInputBase {...rest}>{children}</ReferenceArrayInputBase>
+        <ReferenceArrayInputBase {...rest} offline={offline}>
+            {children}
+        </ReferenceArrayInputBase>
     );
 };
 
 const defaultChildren = <AutocompleteArrayInput />;
+const defaultOffline = <Offline variant="inline" />;
 
 export interface ReferenceArrayInputProps extends ReferenceArrayInputBaseProps {
     label?: string;