Add support for offline/local first applications

cypress/e2e/edit.cy.js

@@ -47,7 +47,11 @@ describe('Edit Page', () => {
         it('should redirect to list page after edit success', () => {
             // For some unknown reason, the click on submit didn't work in cypress
             // so we submit with enter
-            EditPostPage.setInputValue('input', 'title', 'Lorem Ipsum{enter}');
+            EditPostPage.setInputValue(
+                'input',
+                'title',
+                'Lorem Ipsum again{enter}'
+            );
             cy.url().should('match', /\/#\/posts$/);
         });
 

cypress/support/CreatePage.js

@@ -11,13 +11,14 @@ export default url => ({
         inputs: `.ra-input`,
         richTextInputError: '.create-page .ra-rich-text-input-error',
         snackbar: 'div[role="alert"]',
-        submitButton: ".create-page div[role='toolbar'] button[type='submit']",
+        submitButton:
+            ".create-page div[role='toolbar'] div:first-child button[type='submit']",
         submitAndShowButton:
-            ".create-page form div[role='toolbar'] button[type='button']:nth-child(2)",
+            ".create-page form div[role='toolbar'] div:first-child button[type='button']:nth-child(2)",
         submitAndAddButton:
-            ".create-page form div[role='toolbar'] button[type='button']:nth-child(3)",
+            ".create-page form div[role='toolbar'] div:first-child button[type='button']:nth-child(3)",
         submitCommentable:
-            ".create-page form div[role='toolbar'] button[type='button']:last-child",
+            ".create-page form div[role='toolbar'] div:first-child button[type='button']:last-child",
         descInput: '.ProseMirror',
         tab: index => `.form-tab:nth-of-type(${index})`,
         title: '#react-admin-title',

docs/DataProviders.md

@@ -888,3 +888,133 @@ export default App;
 ```
 
 **Tip**: This example uses the function version of `setState` (`setDataProvider(() => dataProvider)`) instead of the more classic version (`setDataProvider(dataProvider)`). This is because some legacy Data Providers are actually functions, and `setState` would call them immediately on mount.
+
+## Offline Support
+
+React-admin supports offline/local-first applications. To enable this feature, install the following react-query packages:
+
+```sh
+yarn add @tanstack/react-query-persist-client @tanstack/query-sync-storage-persister
+```
+
+Then, register default functions for react-admin mutations on the `QueryClient` to enable resumable mutations (mutations triggered while offline). React-admin provides the `addOfflineSupportToQueryClient` function for this:
+
+```ts
+// in src/queryClient.ts
+import { addOfflineSupportToQueryClient } from 'react-admin';
+import { QueryClient } from '@tanstack/react-query';
+import { dataProvider } from './dataProvider';
+
+export const queryClient = new QueryClient();
+
+const queryClientWithOfflineSupport = addOfflineSupportToQueryClient({
+    queryClient,
+    dataProvider,
+    resources: ['posts', 'comments'],
+});
+```
+
+Then, wrap your `<Admin>` inside a [`<PersistQueryClientProvider>`](https://tanstack.com/query/latest/docs/framework/react/plugins/persistQueryClient#persistqueryclientprovider):
+
+{% raw %}
+```tsx
+// in src/App.tsx
+import { Admin, Resource } from 'react-admin';
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
+import { queryClient } from './queryClient';
+import { dataProvider } from './dataProvider';
+import { posts } from './posts';
+import { comments } from './comments';
+
+const localStoragePersister = createSyncStoragePersister({
+    storage: window.localStorage,
+});
+
+export const App = () => (
+    <PersistQueryClientProvider
+        client={queryClient}
+        persistOptions={{ persister: localStoragePersister }}
+        onSuccess={() => {
+            // resume mutations after initial restore from localStorage is successful
+            queryClient.resumePausedMutations();
+        }}
+    >
+        <Admin queryClient={queryClient} dataProvider={dataProvider}>
+            <Resource name="posts" {...posts} />
+            <Resource name="comments" {...comments} />
+        </Admin>
+    </PersistQueryClientProvider>
+)
+```
+{% endraw %}
+
+This is enough to make all the standard react-admin features support offline scenarios.
+
+## Adding Offline Support To Custom Mutations
+
+If you have [custom mutations](./Actions.md#calling-custom-methods) on your dataProvider, you can enable offline support for them too. For instance, if your `dataProvider` exposes a `banUser()` method:
+
+```ts
+const dataProvider = {
+    getList: /* ... */,
+    getOne: /* ... */,
+    getMany: /* ... */,
+    getManyReference: /* ... */,
+    create: /* ... */,
+    update: /* ... */,
+    updateMany: /* ... */,
+    delete: /* ... */,
+    deleteMany: /* ... */,
+    banUser: (userId: string) => {
+        return fetch(`/api/user/${userId}/ban`, { method: 'POST' })
+            .then(response => response.json());
+    },
+}
+
+export type MyDataProvider = DataProvider & {
+    banUser: (userId: string) => Promise<{ data: RaRecord }>
+}
+```
+
+First, you must set a `mutationKey` for this mutation:
+
+{% raw %}
+```tsx
+const BanUserButton = ({ userId }: { userId: string }) => {
+    const dataProvider = useDataProvider();
+    const { mutate, isPending } = useMutation({
+        mutationKey: 'banUser'
+        mutationFn: (userId) => dataProvider.banUser(userId)
+    });
+    return <Button label="Ban" onClick={() => mutate(userId)} disabled={isPending} />;
+};
+```
+{% endraw %}
+
+**Tip**: Note that unlike the [_Calling Custom Methods_ example](./Actions.md#calling-custom-methods), we passed `userId` to the `mutate` function. This is necessary so that React Query passes it too to the default function when resuming the mutation.
+
+Then, register a default function for it:
+
+```ts
+// in src/queryClient.ts
+import { addOfflineSupportToQueryClient } from 'react-admin';
+import { QueryClient } from '@tanstack/react-query';
+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
+import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
+import { dataProvider } from './dataProvider';
+
+const baseQueryClient = new QueryClient();
+
+export const queryClient = addOfflineSupportToQueryClient({
+    queryClient,
+    dataProvider,
+    resources: ['posts', 'comments'],
+});
+
+queryClient.setMutationDefaults('banUser', {
+    mutationFn: async (userId) => {
+        return dataProviderFn.banUser(userId);
+    },
+});
+```

docs/DataTable.md

@@ -53,12 +53,13 @@ Each `<DataTable.Col>` defines one column of the table: its `source` (used for s
 | `empty`              | Optional | Element                 | `<Empty>`             | The component to render when the list is empty.                 |
 | `expand`             | Optional | Element                 |                       | The component rendering the expand panel for each row.   |
 | `expandSingle`       | Optional | Boolean                 | `false`               | Whether to allow only one expanded row at a time.             |
-| `head`               | Optional | Element                 | `<DataTable Header>`   | The component rendering the table header.                |
+| `head`               | Optional | Element                 | `<DataTable Header>`  | The component rendering the table header.                |
 | `hiddenColumns`      | Optional | Array                   | `[]`                  | The list of columns to hide by default.                          |
 | `foot`               | Optional | Element                 |                       | The component rendering the table footer.                |
 | `hover`              | Optional | Boolean                 | `true`                | Whether to highlight the row under the mouse.                 |
 | `isRowExpandable`    | Optional | Function                | `() => true`          | A function that returns whether a row is expandable.          |
 | `isRowSelectable`    | Optional | Function                | `() => true`          | A function that returns whether a row is selectable.          |
+| `offline`            | Optional | Element                 | `<Offline>`           | The content rendered to render when data could not be fetched because of connectivity issues. |
 | `rowClick`           | Optional | mixed                   |                       | The action to trigger when the user clicks on a row.          |
 | `rowSx`              | Optional | Function                |                       | A function that returns the `sx` prop to apply to a row.        |
 | `size`               | Optional | `'small'` or `'medium'` | `'small'`             | The size of the table.                                        |
@@ -754,6 +755,40 @@ export const PostList = () => (
 ```
 {% endraw %}
 
+## `offline`
+
+It's possible that a `<DataTable>` will have no records to display because of connectivity issues. In that case, `<DataTable>` will display the following message:
+
+> No connectivity. Could not fetch data.
+
+You can customize this message via react-admin's [translation system](./Translation.md), by setting a custom translation for the `ra.notification.offline` key.
+
+```tsx
+const messages = {
+    ra: {
+        notification: {
+            offline: "No network. Data couldn't be fetched.",
+        }
+    }
+}
+```
+
+If you need to go beyond text, pass a custom element as the `<DataTable offline>` prop:
+
+```tsx
+const Offline = () => (
+    <p>No network. Data couldn't be fetched.</p>
+);
+
+const BookList = () => (
+    <List>
+        <DataTable offline={<Offline />}>
+            ...
+        </DataTable>
+    </List>
+);
+```
+
 ## `rowClick`
 
 By default, `<DataTable>` uses the current [resource definition](https://marmelab.com/react-admin/Resource.html) to determine what to do when the user clicks on a row. If the resource has a `show` page, a row click redirects to the Show view. If the resource has an `edit` page, a row click redirects to the Edit view. Otherwise, the row is not clickable.

docs/Datagrid.md

@@ -59,6 +59,7 @@ Both are [Enterprise Edition](https://react-admin-ee.marmelab.com) components.
 | `hover`              | Optional | Boolean                 | `true`                | Whether to highlight the row under the mouse.                 |
 | `isRowExpandable`    | Optional | Function                | `() => true`          | A function that returns whether a row is expandable.          |
 | `isRowSelectable`    | Optional | Function                | `() => true`          | A function that returns whether a row is selectable.          |
+| `offline`            | Optional | Element                 | `<Offline>`           | The content rendered to render when data could not be fetched because of connectivity issues. |
 | `optimized`          | Optional | Boolean                 | `false`               | Whether to optimize the rendering of the table.               |
 | `rowClick`           | Optional | mixed                   |                       | The action to trigger when the user clicks on a row.          |
 | `rowStyle`           | Optional | Function                |                       | A function that returns the style to apply to a row.          |
@@ -642,6 +643,40 @@ export const PostList = () => (
 ```
 {% endraw %}
 
+## `offline`
+
+It's possible that a `<Datagrid>` will have no records to display because of connectivity issues. In that case, `<Datagrid>` will display the following message:
+
+> No connectivity. Could not fetch data.
+
+You can customize this message via react-admin's [translation system](./Translation.md), by setting a custom translation for the `ra.notification.offline` key.
+
+```tsx
+const messages = {
+    ra: {
+        notification: {
+            offline: "No network. Data couldn't be fetched.",
+        }
+    }
+}
+```
+
+If you need to go beyond text, pass a custom element as the `<Datagrid offline>` prop:
+
+```tsx
+const CustomOffline = () => <div>No network. Data couldn't be fetched.</div>;
+
+const PostList = () => (
+    <List>
+        <Datagrid offline={<CustomOffline />}>
+            <TextField source="id" />
+            <TextField source="title" />
+            <TextField source="views" />
+        </Datagrid>
+    </List>
+);
+```
+
 ## `optimized`
 
 When displaying large pages of data, you might experience some performance issues.

docs/Edit.md

@@ -62,22 +62,25 @@ export default App;
 
 You can customize the `<Edit>` component using the following props:
 
-* [`actions`](#actions): override the actions toolbar with a custom component
-* [`aside`](#aside): component to render aside to the main content
-* `children`: the components that renders the form
-* `className`: passed to the root component
-* [`component`](#component): override the root component
-* [`disableAuthentication`](#disableauthentication): disable the authentication check
-* [`emptyWhileLoading`](#emptywhileloading): Set to `true` to return `null` while the edit is loading.
-* [`id`](#id): the id of the record to edit
-* [`mutationMode`](#mutationmode): switch to optimistic or pessimistic mutations (undoable by default)
-* [`mutationOptions`](#mutationoptions): options for the `dataProvider.update()` call
-* [`queryOptions`](#queryoptions): options for the `dataProvider.getOne()` call
-* [`redirect`](#redirect): change the redirect location after successful creation
-* [`resource`](#resource): override the name of the resource to create
-* [`sx`](#sx-css-api): Override the styles
-* [`title`](#title): override the page title
-* [`transform`](#transform): transform the form data before calling `dataProvider.update()`
+| Prop                    | Required | Type                                  | Default               | Description                                                   |
+| ----------------------- | -------- | ------------------------------------- | --------------------- | ------------------------------------------------------------- |
+| `actions`               |          | `ReactNode`                           |                       | override the actions toolbar with a custom component |
+| `aside`                 |          | `ReactNode`                           |                       | component to render aside to the main content |
+| `children`              |          | `ReactNode`                           |                       | The components that renders the form |
+| `className`             |          | `string`                              |                       | passed to the root component |
+| `component`             |          | `Component`                           |                       | override the root component |
+| `disableAuthentication` |          | `boolean`                             |                       | disable the authentication check |
+| `emptyWhileLoading`     |          | `boolean`                             |                       | Set to `true` to return `null` while the edit is loading. |
+| `id`                    |          | `string | number`                     |                       | the id of the record to edit |
+| `mutationMode`          |          | `pessimistic | optimistic | undoable` |                       | switch to optimistic or pessimistic mutations (undoable by default) |
+| `mutationOptions`       |          | `object`                              |                       | options for the `dataProvider.update()` call |
+| `offline`               |          | `ReactNode`                           | `<Offline>`           | The content rendered to render when data could not be fetched because of connectivity issues |
+| `queryOptions`          |          | `object`                              |                       | options for the `dataProvider.getOne()` call |
+| `redirect`              |          | `string | Function | false`           |                       | change the redirect location after successful creation |
+| `resource`              |          | `string`                              |                       | override the name of the resource to create |
+| `sx`                    |          | `object`                              |                       | Override the styles |
+| `title`                 |          | `ReactNode`                           |                       | override the page title |
+| `transform`             |          | `Function`                            |                       | transform the form data before calling `dataProvider.update()` |
 
 ## `actions`
 
@@ -490,6 +493,38 @@ The default `onError` function is:
 
 **Tip**: If you want to have different failure side effects based on the button clicked by the user, you can set the `mutationOptions` prop on the `<SaveButton>` component, too.
 
+## `offline`
+
+It's possible that a `<Edit>` will have no records to display because of connectivity issues. In that case, `<Edit>` will display the following message:
+
+> No connectivity. Could not fetch data.
+
+You can customize this message via react-admin's [translation system](./Translation.md), by setting a custom translation for the `ra.notification.offline` key.
+
+```tsx
+const messages = {
+    ra: {
+        notification: {
+            offline: "No network. Data couldn't be fetched.",
+        }
+    }
+}
+```
+
+If you need to go beyond text, pass a custom element as the `<Edit offline>` prop:
+
+```tsx
+const Offline = () => (
+    <p>No network. Data couldn't be fetched.</p>
+);
+
+const BookEdit = () => (
+    <Edit offline={<Offline />}>
+            ...
+    </Edit>
+);
+```
+
 ## `queryOptions`
 
 `<Edit>` calls `dataProvider.getOne()` on mount via react-query's `useQuery` hook. You can customize the options you pass to this hook by setting the `queryOptions` prop.
@@ -500,7 +535,7 @@ This can be useful e.g. to pass [a custom `meta`](./Actions.md#meta-parameter) t
 ```jsx
 import { Edit, SimpleForm } from 'react-admin';
 
-export const PostShow = () => (
+export const PostEdit = () => (
     <Edit queryOptions={{ meta: { foo: 'bar' } }}>
         <SimpleForm>
             ...