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,170 @@ 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';
+
+const baseQueryClient = new QueryClient();
+
+export const queryClient = addOfflineSupportToQueryClient({
+    queryClient: baseQueryClient,
+    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: baseQueryClient,
+    dataProvider,
+    resources: ['posts', 'comments'],
+});
+
+queryClient.setMutationDefaults('banUser', {
+    mutationFn: async (userId) => {
+        return dataProvider.banUser(userId);
+    },
+});
+```
+
+## Handling Errors For Resumed Mutations
+
+If you enabled offline support, users might trigger mutations while being actually offline. When they're back online, react-query will _resume_ those mutations and they might fail for other reasons (server side validation or errors). However, as users might have navigated away from the page that triggered the mutation, they won't see any notification.
+
+To handle this scenario, you must register default `onError` side effects for all mutations (react-admin default ones or custom). If you want to leverage react-admin notifications, you can use a custom layout:
+
+```tsx
+// in src/Layout.tsx
+export const MyLayout = ({ children }: { children: React.ReactNode }) => {
+    const queryClient = useQueryClient();
+    const notify = useNotify();
+
+    React.useEffect(() => {
+        const mutationKeyFilter = []; // An empty array targets all mutations 
+        queryClient.setMutationDefaults([], {
+            onSettled(data, error) {
+                if (error) {
+                    notify(error.message, { type: 'error' });
+                }
+            },
+        });
+    }, [queryClient, notify]);
+
+    return (
+        <Layout>
+            {children}
+        </Layout>
+    );
+}
+```
+
+Note that this simple example will only show the error message as it was received. Users may not have the context to understand the error (what record or operation it relates to).
+Here are some ideas for a better user experience:
+
+- make sure your messages allow users to go to the pages related to the errors (you can leverage [custom notifications](./useNotify.md#custom-notification-content) for that)
+- store the notifications somewhere (server side or not) and show them in a custom page with proper links, etc.

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>
             ...