Merge pull request #8711 from marmelab/doc-confirm

[Doc] Improve `<Confirm>` documentation

Author: slax57

docs/Confirm.md

@@ -7,41 +7,47 @@ title: "The Confirm Component"
 
 `<Confirm>` leverages MUI's [`<Dialog>` component](https://mui.com/components/dialogs) to implement a confirmation popup.
 
-![Confirm dialog](./img/confirm-dialog.png)
+![Confirm dialog](./img/confirm.webp)
+
+## Usage
+
+To ask a confirmation to the user before performing an action, have the action button open a `<Confirm>`.
+
+For instance, here is how to build a delete button that removes the record after asking for confirmation:
 
 ```jsx
 import { useState } from 'react';
 import {
     Button,
     Confirm,
-    useListContext,
-    useUpdateMany,
+    useRecordContext,
+    useDelete,
 } from 'react-admin';
 
-const CustomUpdatePostsButton = () => {
-    const { selectedIds } = useListContext();
+const BulkResetViewsButton = () => {
+    const record = useRecordContext();
     const [open, setOpen] = useState(false);
 
-    const [updateMany, { isLoading }] = useUpdateMany(
+    const [remove, { isLoading }] = useDelete(
         'posts',
-        { ids: selectedIds, data: { views: 0 } }
+        { id: record && record.id }
     );
 
     const handleClick = () => setOpen(true);
     const handleDialogClose = () => setOpen(false);
     const handleConfirm = () => {
-        updateMany();
+        remove();
         setOpen(false);
     };
 
     return (
         <>
-            <Button label="Update Posts" onClick={handleClick} />
+            <Button label="Delete" onClick={handleClick} />
             <Confirm
                 isOpen={open}
                 loading={isLoading}
-                title="Update View Count"
-                content="Are you sure you want to update these posts?"
+                title={`Delete post #${record && record.id}`}
+                content="Are you sure you want to delete this item?"
                 onConfirm={handleConfirm}
                 onClose={handleDialogClose}
             />
@@ -50,20 +56,21 @@ const CustomUpdatePostsButton = () => {
 };
 ```
 
+## Props
+
 | Prop               | Required | Type                             | Default               | Description                                                        |
 |--------------------|----------|----------------------------------|-----------------------|--------------------------------------------------------------------|
-| `className`        | Optional | `string`                         | -                     | Class name to customize the look and feel of the dialog itself     |
+| `title`            | Required | `string`                         | -                     | Title of the dialog                                                |
+| `content`          | Required | `ReactNode`                      | -                     | Body of the dialog                                                 |
+| `onClose`          | Required | `MouseEventHandler`              | -                     | onClick event handler of the cancel button                         |
+| `onConfirm`        | Required | `MouseEventHandler`              | -                     | onClick event handler of the confirm button                        |
 | `isOpen`           | Optional | `boolean`                        | `false`               | `true` to show the dialog, `false` to hide it                      |
 | `loading`          | Optional | `boolean`                        | `false`               | Boolean to be applied to the `disabled` prop of the action buttons |
-| `content`          | Required | `ReactNode`                      | -                     | Body of the dialog                                                 |
 | `cancel`           | Optional | `string`                         | 'ra.action.cancel'    | Label of the cancel button                                         |
 | `confirm`          | Optional | `string`                         | 'ra.action.confirm'   | Label of the confirm button                                        |
 | `confirmColor`     | Optional | `string`                         | 'primary'             | Color of the confirm button                                        |
 | `ConfirmIcon`      | Optional | `ReactElement`                   | `<CheckCircle/>`      | Icon element of the confirm button                                 |
 | `CancelIcon`       | Optional | `ReactElement`                   | `<ErrorOutlineIcon/>` | Icon element of the cancel button                                  |
-| `onClose`          | Required | `MouseEventHandler`              | -                     | onClick event handler of the cancel button                         |
-| `onConfirm`        | Required | `MouseEventHandler`              | -                     | onClick event handler of the confirm button                        |
-| `title`            | Required | `string`                         | -                     | Title of the dialog                                                |
 | `translateOptions` | Optional | `{ id?: string, name?: string }` | {}                    | Custom id and name to be used in the dialog title                  |
 | `sx`               | Optional | `SxProps`                        | ''                    | MUI shortcut for defining custom styles with access to the theme   |
 
@@ -79,3 +86,38 @@ The `<Confirm>` component accepts the usual `className` prop. You can also overr
 | `& .RaConfirm-confirmWarning`   | Applied to the confirm button when `confirmColor` is `warning` |
 
 To override the style of all instances of `<Confirm>` using the [MUI style overrides](https://mui.com/customization/globals/#css), use the `RaConfirm` key.
+
+## Delete With Confirmation
+
+React-admin's `<DeleteButton>` lets user delete the current record [in an optimistic way](./Features.md#optimistic-updates-and-undo): after clicking the button, users see a notification for the deletion with an "undo" link to cancel the deletion. 
+
+Alternately, you can force the user to confirm the deletion by using `<DeleteButton mutationMode="pessimistic">`. Under the hood, this leverages the `<Confirm>` component to ask for confirmation before deleting the record.
+
+```jsx
+import { List, Datagrid, TextField, DeleteButton } from 'react-admin';
+
+const PostList = () => (
+    <List>
+        <Datagrid>
+            <TextField source="id" />
+            <TextField source="title" />
+            <DeleteButton mutationMode="pessimistic" />
+        </Datagrid>
+    </List>
+);
+```
+
+The same goes for deleting multiple records in a [bulk action](./Datagrid.md#bulkactionbuttons): use `<BulkDeleteButton mutationMode="pessimistic">` to ask a confirmation before the deletion.
+
+```jsx
+import { List, Datagrid, TextField, BulkDeleteButton } from 'react-admin';
+
+const PostList = () => (
+    <List>
+        <Datagrid PostBulkActionButtons={<BulkDeleteButton mutationMode="pessimistic" />}>
+            <TextField source="id" />
+            <TextField source="title" />
+        </Datagrid>
+    </List>
+);
+```

docs/Datagrid.md

@@ -193,7 +193,7 @@ const ResetViewsButton = () => (
 export default ResetViewsButton;
 ```
 
-You can also implement the same `<ResetViewsButton>` behind a confirmation dialog by using the [`mutationMode`](./Edit.md#mutationmode) prop:
+You can also implement the same `<ResetViewsButton>` behind a [confirmation dialog](./Confirm.md) by using the [`mutationMode`](./Edit.md#mutationmode) prop:
 
 ```diff
 // in ./ResetViewsButton.js

docs/Edit.md

@@ -230,7 +230,7 @@ const PostEdit = () => (
 
 **Tip**: When using any other mode than `undoable`, the `<DeleteButton>` displays a confirmation dialog before calling the dataProvider. 
 
-**Tip**: If you want a confirmation dialog for the Delete button but don't mind undoable Edits, then pass a [custom toolbar](./SimpleForm.md#toolbar) to the form, as follows:
+**Tip**: If you want a [confirmation dialog](./Confirm.md) for the Delete button but don't mind undoable Edits, then pass a [custom toolbar](./SimpleForm.md#toolbar) to the form, as follows:
 
 {% raw %}
 ```jsx

docs/img/confirm.webp

@@ -224,8 +224,8 @@
   <li {% if page.path == 'HorizontalMenu.md' %} class="active" {% endif %}><a class="nav-link" href="./HorizontalMenu.html"><code>&lt;HorizontalMenu&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
   <li {% if page.path == 'Breadcrumb.md' %} class="active" {% endif %}><a class="nav-link" href="./Breadcrumb.html"><code>&lt;Breadcrumb&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
   <li {% if page.path == 'Search.md' %} class="active" {% endif %}><a class="nav-link" href="./Search.html"><code>&lt;Search&gt;</code><img class="premium" src="./img/premium.svg" /></a></li>
+  <li {% if page.path == 'Confirm.md' %} class="active" {% endif %}><a class="nav-link" href="./Confirm.html"><code>&lt;Confirm&gt;</code></a></li>
   <li {% if page.path == 'Buttons.md' %} class="active" {% endif %}><a class="nav-link" href="./Buttons.html">Buttons</a></li>
-  <li {% if page.path == 'Confirm.md' %} class="active" {% endif %}><a class="nav-link" href="./Confirm.html">Confirm</a></li>
 </ul>
 
 <ul><div>Realtime</div>

docs/navigation.html

@@ -0,0 +1,136 @@
+import * as React from 'react';
+import polyglotI18nProvider from 'ra-i18n-polyglot';
+import englishMessages from 'ra-language-english';
+import frenchMessages from 'ra-language-french';
+import { Resource } from 'ra-core';
+import fakeRestDataProvider from 'ra-data-fakerest';
+import { createMemoryHistory } from 'history';
+
+import { DeleteWithConfirmButton } from './DeleteWithConfirmButton';
+import { AdminContext } from '../AdminContext';
+import { AdminUI } from '../AdminUI';
+import { List, Datagrid } from '../list';
+import { TextField } from '../field';
+
+export default { title: 'ra-ui-materialui/button/DeleteWithConfirmButton' };
+
+const i18nProvider = polyglotI18nProvider(
+    locale =>
+        locale === 'fr'
+            ? {
+                  ...frenchMessages,
+                  resources: {
+                      books: {
+                          name: 'Livre |||| Livres',
+                          fields: {
+                              id: 'Id',
+                              title: 'Titre',
+                              author: 'Auteur',
+                              year: 'Année',
+                          },
+                      },
+                  },
+              }
+            : englishMessages,
+    'en' // Default locale
+);
+
+const dataProvider = fakeRestDataProvider({
+    books: [
+        {
+            id: 1,
+            title: 'War and Peace',
+            author: 'Leo Tolstoy',
+            year: 1869,
+        },
+        {
+            id: 2,
+            title: 'Pride and Predjudice',
+            author: 'Jane Austen',
+            year: 1813,
+        },
+        {
+            id: 3,
+            title: 'The Picture of Dorian Gray',
+            author: 'Oscar Wilde',
+            year: 1890,
+        },
+        {
+            id: 4,
+            title: 'Le Petit Prince',
+            author: 'Antoine de Saint-Exupéry',
+            year: 1943,
+        },
+        {
+            id: 5,
+            title: "Alice's Adventures in Wonderland",
+            author: 'Lewis Carroll',
+            year: 1865,
+        },
+        {
+            id: 6,
+            title: 'Madame Bovary',
+            author: 'Gustave Flaubert',
+            year: 1856,
+        },
+        {
+            id: 7,
+            title: 'The Lord of the Rings',
+            author: 'J. R. R. Tolkien',
+            year: 1954,
+        },
+        {
+            id: 8,
+            title: "Harry Potter and the Philosopher's Stone",
+            author: 'J. K. Rowling',
+            year: 1997,
+        },
+        {
+            id: 9,
+            title: 'The Alchemist',
+            author: 'Paulo Coelho',
+            year: 1988,
+        },
+        {
+            id: 10,
+            title: 'A Catcher in the Rye',
+            author: 'J. D. Salinger',
+            year: 1951,
+        },
+        {
+            id: 11,
+            title: 'Ulysses',
+            author: 'James Joyce',
+            year: 1922,
+        },
+    ],
+    authors: [],
+});
+
+const history = createMemoryHistory({ initialEntries: ['/books'] });
+
+const BookList = () => {
+    return (
+        <List>
+            <Datagrid>
+                <TextField source="id" />
+                <TextField source="title" />
+                <TextField source="author" />
+                <TextField source="year" />
+                <DeleteWithConfirmButton />
+            </Datagrid>
+        </List>
+    );
+};
+
+export const Basic = () => (
+    <AdminContext
+        dataProvider={dataProvider}
+        i18nProvider={i18nProvider}
+        history={history}
+    >
+        <AdminUI>
+            <Resource name="books" list={BookList} />
+        </AdminUI>
+    </AdminContext>
+);