Merge pull request marmelab#10614 from marmelab/custom-notifications

Introduce `useCloseNotification` hook

Author: slax57

docs/useNotify.md

@@ -23,16 +23,6 @@ const NotifyButton = () => {
 };
 ```
 
-The hook takes no argument and returns a callback. The callback takes 2 arguments:
-
-- The message to display (a string, or a React node)
-- an `options` object with the following keys:
-    - `type`: The notification type (`info`, `success`, `error` or `warning` - the default is `info`)
-    - `messageArgs`: options to pass to the `translate` function (because notification messages are translated if your admin has an `i18nProvider`). It is useful for inserting variables into the translation.
-    - `undoable`: Set it to `true` if the notification should contain an "undo" button
-    - `autoHideDuration`: Duration (in milliseconds) after which the notification hides. Set it to `null` if the notification should not be dismissible.
-    - `multiLine`: Set it to `true` if the notification message should be shown in more than one line.
-    - `anchorOrigin`: The position of the notification. The default is `{ vertical: 'top', horizontal: 'right' }`. See [the Material UI documentation](https://mui.com/material-ui/react-snackbar/) for more details.
 
 Here are more examples of `notify` calls: 
 
@@ -47,6 +37,26 @@ notify('item.created', { type: 'info', messageArgs: { resource: 'post' } });
 notify('Element updated', { type: 'info', undoable: true });
 ```
 
+## Parameters
+
+The hook takes no argument and returns a callback. The callback takes 2 arguments:
+
+| Name | Required | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `message` | Required | `string` | - | The message to display (a string, or a React node) |
+| `options` |  | `object` | - | The options |
+
+The `options` is an object that can have the following properties:
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `anchorOrigin` | `object` | - | The position of the notification. The default is `{ vertical: 'bottom', horizontal: 'center' }`. See [the Material UI documentation](https://mui.com/material-ui/react-snackbar/) for more details. |
+| `autoHideDuration` | `number | null` | `4000` | Duration (in milliseconds) after which the notification hides. Set it to `null` if the notification should not be dismissible. |
+| `messageArgs` | `object` | - | options to pass to the `translate` function (because notification messages are translated if your admin has an `i18nProvider`). It is useful for inserting variables into the translation. |
+| `multiLine` | `boolean` | - | Set it to `true` if the notification message should be shown in more than one line. |
+| `undoable` | `boolean` | - | Set it to `true` if the notification should contain an "undo" button |
+| `type` | `string` | `info` | The notification type (`info`, `success`, `error` or `warning` - the default is `info`) |
+
 ## `anchorOrigin`
 
 You can change the default position of the notification by passing an `anchorOrigin` option. The value is passed to [the Material UI `<Snackbar anchorOrigin>`](https://mui.com/material-ui/react-snackbar/) prop.
@@ -180,7 +190,7 @@ This allows e.g. using [Material UI's `<Alert>` component](https://mui.com/mater
 
 ![useNotify with node](./img/use-notify-node.png)
 
-```jsx
+```tsx
 import { useSubscribe } from "@react-admin/ra-realtime";
 import { useNotify, useDataProvider } from "react-admin";
 import { Alert } from "@mui/material";
@@ -216,4 +226,48 @@ export const ConnectionWatcher = () => {
 };
 ```
 
-Note that if you use this ability to pass a React node, the message will not be translated - you'll have to translate it yourself using [`useTranslate`](./useTranslate.md).
+Note that if you use this ability to pass a React node, the message will not be translated - you'll have to translate it yourself using [`useTranslate`](./useTranslate.md).
+
+## Closing The Notification
+
+If you have custom actions in your notification element, you can leverage the `useCloseNotification` hook to close the notification programmatically:
+
+```tsx
+import { useFormContext } from 'react-hook-form';
+import { Button, useCloseNotification, useNotify } from 'react-admin';
+import { SnackbarContent } from '@mui/material';
+
+const SetFormValueButton = () => {
+    const { setValue } = useFormContext();
+    const notify = useNotify();
+
+    return (
+        <Button
+            onClick={() => {
+                setValue('myfield', 'a value');
+                notify(<SetFormValueNotification reset={() => setValue('myfield', '')} />);
+            }}
+            label="Set myfield value"
+        />
+    );
+};
+
+const SetFormValueNotification = ({ reset }: { reset:() => void }) => {
+    const closeNotification = useCloseNotification();
+
+    return (
+        <SnackbarContent
+            message="myfield changed"
+            action={
+                <Button
+                    onClick={() => {
+                        reset();
+                        closeNotification();
+                    }}
+                    label="Reset"
+                />
+            }
+        />
+    );
+};
+```

packages/ra-core/src/notification/CloseNotificationContext.ts

@@ -0,0 +1,6 @@
+import { createContext } from 'react';
+
+export type CloseNotificationContextValue = () => void;
+
+export const CloseNotificationContext =
+    createContext<CloseNotificationContextValue | null>(null);

packages/ra-core/src/notification/index.ts

@@ -1,7 +1,9 @@
 export * from './AddNotificationContext';
+export * from './CloseNotificationContext';
 export * from './NotificationContext';
 export * from './NotificationContextProvider';
 export * from './types';
 export * from './useAddNotificationContext';
+export * from './useCloseNotification';
 export * from './useNotificationContext';
 export * from './useNotify';

packages/ra-core/src/notification/useCloseNotification.ts

@@ -0,0 +1,12 @@
+import { useContext } from 'react';
+import { CloseNotificationContext } from './CloseNotificationContext';
+
+export const useCloseNotification = () => {
+    const closeNotification = useContext(CloseNotificationContext);
+    if (!closeNotification) {
+        throw new Error(
+            'useCloseNotification must be used within a CloseNotificationContext.Provider'
+        );
+    }
+    return closeNotification;
+};

packages/ra-ui-materialui/src/layout/Notification.spec.tsx

@@ -1,7 +1,10 @@
 import * as React from 'react';
-import { render, screen } from '@testing-library/react';
+import { render, screen, waitFor } from '@testing-library/react';
 
-import { ConsecutiveUndoable } from './Notification.stories';
+import {
+    ConsecutiveUndoable,
+    CustomNotificationWithAction,
+} from './Notification.stories';
 
 describe('<Notification />', () => {
     it('should confirm the first undoable notification when a second one starts', async () => {
@@ -30,4 +33,14 @@ describe('<Notification />', () => {
         // the second delete hasn't been called
         expect(deleteOne).toHaveBeenCalledTimes(1);
     });
+    it('allows custom notifications to close themselves', async () => {
+        const consoleLog = jest.spyOn(console, 'log').mockImplementation();
+        render(<CustomNotificationWithAction />);
+        await screen.findByText('Applied automatic changes');
+        screen.getByText('Cancel').click();
+        await waitFor(() => {
+            expect(screen.queryByText('Applied automatic changes')).toBeNull();
+        });
+        expect(consoleLog).toHaveBeenCalledWith('Custom action');
+    });
 });

packages/ra-ui-materialui/src/layout/Notification.stories.tsx

@@ -1,11 +1,18 @@
 import * as React from 'react';
 import {
-    useNotify,
+    CoreAdminContext,
     NotificationContextProvider,
     useDelete,
-    CoreAdminContext,
+    useNotify,
+    useCloseNotification,
 } from 'ra-core';
-import { Alert, Button, Stack } from '@mui/material';
+import {
+    Alert,
+    Button,
+    SnackbarContent,
+    SnackbarContentProps,
+    Stack,
+} from '@mui/material';
 
 import { Notification } from './Notification';
 
@@ -202,3 +209,37 @@ export const ConsecutiveUndoable = ({
         <Notification />
     </CoreAdminContext>
 );
+
+// forwardRef is required for Snackbar to work (transitions) in React 18
+const CustomNotificationWithActionContent = React.forwardRef<
+    HTMLDivElement,
+    SnackbarContentProps
+>((props, ref) => {
+    const closeNotification = useCloseNotification();
+    const handleClick = () => {
+        console.log('Custom action');
+        closeNotification();
+    };
+    return (
+        <SnackbarContent
+            message="Applied automatic changes"
+            action={<Button onClick={handleClick}>Cancel</Button>}
+            {...props}
+            ref={ref}
+        />
+    );
+});
+
+const CustomNotificationElementWithAction = () => {
+    const notify = useNotify();
+    React.useEffect(() => {
+        notify(<CustomNotificationWithActionContent />);
+    }, [notify]);
+    return null;
+};
+
+export const CustomNotificationWithAction = () => (
+    <Wrapper>
+        <CustomNotificationElementWithAction />
+    </Wrapper>
+);

packages/ra-ui-materialui/src/layout/Notification.tsx

@@ -5,11 +5,12 @@ import { Button, Snackbar, SnackbarProps, SnackbarOrigin } from '@mui/material';
 import clsx from 'clsx';
 
 import {
-    useNotificationContext,
-    undoableEventEmitter,
-    useTranslate,
+    CloseNotificationContext,
     NotificationPayload,
+    undoableEventEmitter,
+    useNotificationContext,
     useTakeUndoableMutation,
+    useTranslate,
 } from 'ra-core';
 
 const defaultAnchorOrigin: SnackbarOrigin = {
@@ -120,52 +121,57 @@ export const Notification = (props: NotificationProps) => {
     } = notificationOptions || {};
 
     return (
-        <StyledSnackbar
-            className={className}
-            open={open}
-            message={
-                message &&
-                typeof message === 'string' &&
-                translate(message, messageArgs)
-            }
-            autoHideDuration={
-                // Only apply the default autoHideDuration when autoHideDurationFromMessage is undefined
-                // as 0 and null are valid values
-                autoHideDurationFromMessage === undefined
-                    ? autoHideDuration
-                    : autoHideDurationFromMessage ?? undefined
-            }
-            disableWindowBlurListener={undoable}
-            TransitionProps={{ onExited: handleExited }}
-            onClose={handleRequestClose}
-            ContentProps={{
-                className: clsx(NotificationClasses[typeFromMessage || type], {
-                    [NotificationClasses.multiLine]:
-                        multilineFromMessage || multiLine,
-                }),
-            }}
-            action={
-                undoable ? (
-                    <Button
-                        color="primary"
-                        className={NotificationClasses.undo}
-                        size="small"
-                        onClick={handleUndo}
-                    >
-                        <>{translate('ra.action.undo')}</>
-                    </Button>
-                ) : null
-            }
-            anchorOrigin={anchorOrigin}
-            {...rest}
-            {...options}
-        >
-            {message &&
-            typeof message !== 'string' &&
-            React.isValidElement(message)
-                ? message
-                : undefined}
-        </StyledSnackbar>
+        <CloseNotificationContext.Provider value={handleRequestClose}>
+            <StyledSnackbar
+                className={className}
+                open={open}
+                message={
+                    message &&
+                    typeof message === 'string' &&
+                    translate(message, messageArgs)
+                }
+                autoHideDuration={
+                    // Only apply the default autoHideDuration when autoHideDurationFromMessage is undefined
+                    // as 0 and null are valid values
+                    autoHideDurationFromMessage === undefined
+                        ? autoHideDuration
+                        : autoHideDurationFromMessage ?? undefined
+                }
+                disableWindowBlurListener={undoable}
+                TransitionProps={{ onExited: handleExited }}
+                onClose={handleRequestClose}
+                ContentProps={{
+                    className: clsx(
+                        NotificationClasses[typeFromMessage || type],
+                        {
+                            [NotificationClasses.multiLine]:
+                                multilineFromMessage || multiLine,
+                        }
+                    ),
+                }}
+                action={
+                    undoable ? (
+                        <Button
+                            color="primary"
+                            className={NotificationClasses.undo}
+                            size="small"
+                            onClick={handleUndo}
+                        >
+                            <>{translate('ra.action.undo')}</>
+                        </Button>
+                    ) : null
+                }
+                anchorOrigin={anchorOrigin}
+                {...rest}
+                {...options}
+            >
+                {message &&
+                typeof message !== 'string' &&
+                React.isValidElement(message)
+                    ? message
+                    : undefined}
+            </StyledSnackbar>
+        </CloseNotificationContext.Provider>
     );
 };