Re-implement Modal component using HTMLDialogElement (#461)

Author: bedrich-schindler

src/components/Grid/Grid.module.scss

@@ -20,8 +20,8 @@
 //
 // 2. Apply custom property value that is defined within current breakpoint, see 1.
 //
-// 3. Intentionally use longhand properties because the custom property fallback mechanism evaluates `initial` values as
-//    empty. That makes the other value of the shorthand property unexpectedly used for both axes.
+// 3. Intentionally use longhand properties because the custom property fallback mechanism evaluates `initial` values
+//    as empty. That makes the other value of the shorthand property unexpectedly used for both axes.
 
 @use "sass:map";
 @use "../../styles/tools/spacing";

src/components/Modal/Modal.jsx

@@ -1,9 +1,18 @@
 import PropTypes from 'prop-types';
-import React, { useRef } from 'react';
+import React, {
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+} from 'react';
 import { createPortal } from 'react-dom';
 import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
+import { dialogOnCancelHandler } from './_helpers/dialogOnCancelHandler';
+import { dialogOnClickHandler } from './_helpers/dialogOnClickHandler';
+import { dialogOnCloseHandler } from './_helpers/dialogOnCloseHandler';
+import { dialogOnKeyDownHandler } from './_helpers/dialogOnKeyDownHandler';
 import { getPositionClassName } from './_helpers/getPositionClassName';
 import { getSizeClassName } from './_helpers/getSizeClassName';
 import { useModalFocus } from './_hooks/useModalFocus';
@@ -12,90 +21,121 @@ import styles from './Modal.module.scss';
 
 const preRender = (
   children,
-  childrenWrapperRef,
-  closeButtonRef,
+  dialogRef,
   position,
-  restProps,
   size,
+  events,
+  restProps,
 ) => (
-  <div
-    className={styles.backdrop}
-    onClick={(e) => {
-      e.preventDefault();
-      if (closeButtonRef?.current != null) {
-        closeButtonRef.current.click();
-      }
-    }}
-    role="presentation"
+  <dialog
+    {...transferProps(restProps)}
+    {...transferProps(events)}
+    className={classNames(
+      styles.root,
+      getSizeClassName(size, styles),
+      getPositionClassName(position, styles),
+    )}
+    ref={dialogRef}
   >
-    <div
-      {...transferProps(restProps)}
-      className={classNames(
-        styles.root,
-        getSizeClassName(size, styles),
-        getPositionClassName(position, styles),
-      )}
-      onClick={(e) => {
-        e.stopPropagation();
-      }}
-      ref={childrenWrapperRef}
-      role="presentation"
-    >
-      {children}
-    </div>
-  </div>
+    {children}
+  </dialog>
 );
 
 export const Modal = ({
+  allowCloseOnBackdropClick,
+  allowCloseOnEscapeKey,
+  allowPrimaryActionOnEnterKey,
   autoFocus,
   children,
   closeButtonRef,
+  dialogRef,
   portalId,
   position,
   preventScrollUnderneath,
   primaryButtonRef,
   size,
   ...restProps
 }) => {
-  const childrenWrapperRef = useRef();
+  const internalDialogRef = useRef();
 
-  useModalFocus(
-    autoFocus,
-    childrenWrapperRef,
-    primaryButtonRef,
-    closeButtonRef,
-  );
+  useEffect(() => {
+    internalDialogRef.current.showModal();
+  }, []);
 
+  // We need to have a reference to the dialog element to be able to call its methods,
+  // but at the same time we want to expose this reference to the parent component for
+  // case someone wants to call dialog methods from outside the component.
+  useImperativeHandle(dialogRef, () => internalDialogRef.current);
+
+  useModalFocus(autoFocus, internalDialogRef, primaryButtonRef);
   useModalScrollPrevention(preventScrollUnderneath);
 
+  const onCancel = useCallback(
+    (e) => dialogOnCancelHandler(e, closeButtonRef, restProps.onCancel),
+    [closeButtonRef, restProps.onCancel],
+  );
+  const onClick = useCallback(
+    (e) => dialogOnClickHandler(e, closeButtonRef, internalDialogRef, allowCloseOnBackdropClick),
+    [allowCloseOnBackdropClick, closeButtonRef, internalDialogRef],
+  );
+  const onClose = useCallback(
+    (e) => dialogOnCloseHandler(e, closeButtonRef, restProps.onClose),
+    [closeButtonRef, restProps.onClose],
+  );
+  const onKeyDown = useCallback(
+    (e) => dialogOnKeyDownHandler(
+      e,
+      closeButtonRef,
+      primaryButtonRef,
+      allowCloseOnEscapeKey,
+      allowPrimaryActionOnEnterKey,
+    ),
+    [
+      allowCloseOnEscapeKey,
+      allowPrimaryActionOnEnterKey,
+      closeButtonRef,
+      primaryButtonRef,
+    ],
+  );
+  const events = {
+    onCancel,
+    onClick,
+    onClose,
+    onKeyDown,
+  };
+
   if (portalId === null) {
     return preRender(
       children,
-      childrenWrapperRef,
-      closeButtonRef,
+      internalDialogRef,
       position,
-      restProps,
       size,
+      events,
+      restProps,
     );
   }
 
   return createPortal(
     preRender(
       children,
-      childrenWrapperRef,
-      closeButtonRef,
+      internalDialogRef,
       position,
-      restProps,
       size,
+      events,
+      restProps,
     ),
     document.getElementById(portalId),
   );
 };
 
 Modal.defaultProps = {
+  allowCloseOnBackdropClick: true,
+  allowCloseOnEscapeKey: true,
+  allowPrimaryActionOnEnterKey: true,
   autoFocus: true,
   children: null,
   closeButtonRef: null,
+  dialogRef: null,
   portalId: null,
   position: 'center',
   preventScrollUnderneath: window.document.body,
@@ -104,6 +144,18 @@ Modal.defaultProps = {
 };
 
 Modal.propTypes = {
+  /**
+   * If `true`, the `Modal` can be closed by clicking on the backdrop.
+   */
+  allowCloseOnBackdropClick: PropTypes.bool,
+  /**
+   * If `true`, the `Modal` can be closed by pressing the Escape key.
+   */
+  allowCloseOnEscapeKey: PropTypes.bool,
+  /**
+   * If `true`, the `Modal` can be submitted by pressing the Enter key.
+   */
+  allowPrimaryActionOnEnterKey: PropTypes.bool,
   /**
    * If `true`, focus the first input element in the `Modal`, or primary button (referenced by the `primaryButtonRef`
    * prop), or other focusable element when the `Modal` is opened. If there are none or `autoFocus` is set to `false`,
@@ -121,12 +173,20 @@ Modal.propTypes = {
    */
   children: PropTypes.node,
   /**
-   * Reference to close button element. It is used to close modal when Escape key is pressed or the backdrop is clicked.
+   * Reference to close button element. It is used to close modal when Escape key is pressed
+   * or the backdrop is clicked.
    */
   closeButtonRef: PropTypes.shape({
     // eslint-disable-next-line react/forbid-prop-types
     current: PropTypes.any,
   }),
+  /**
+   * Reference to dialog element
+   */
+  dialogRef: PropTypes.shape({
+    // eslint-disable-next-line react/forbid-prop-types
+    current: PropTypes.any,
+  }),
   /**
    * If set, modal is rendered in the React Portal with that ID.
    */

src/components/Modal/Modal.module.scss

@@ -1,9 +1,15 @@
+// 1. Modal uses <dialog> element that uses the browser's built-in dialog functionality, so that:
+//    * visibility of the .root element and its backdrop is managed by the browser
+//    * positioning of the .root element and its backdrop is managed by the browser
+//    * z-index of the .root element and its backdrop is not needed as dialog is rendered in browser's Top layer
+
 @use "sass:map";
 @use "../../styles/theme/typography";
 @use "../../styles/tools/accessibility";
 @use "../../styles/tools/breakpoint";
 @use "../../styles/tools/reset";
 @use "../../styles/tools/spacing";
+@use "animations";
 @use "settings";
 @use "theme";
 
@@ -13,33 +19,37 @@
         --rui-local-max-width: calc(100% - (2 * var(--rui-local-outer-spacing)));
         --rui-local-max-height: calc(100% - (2 * var(--rui-local-outer-spacing)));
 
-        position: fixed;
-        left: 50%;
-        z-index: settings.$z-index;
-        display: flex;
         flex-direction: column;
         max-width: var(--rui-local-max-width);
         max-height: var(--rui-local-max-height);
+        padding: 0;
         overflow-y: auto;
+        color: inherit;
+        border-width: 0;
         border-radius: settings.$border-radius;
         background: theme.$background;
         box-shadow: theme.$box-shadow;
-        transform: translateX(-50%);
         overscroll-behavior: contain;
 
         @include breakpoint.up(sm) {
             --rui-local-outer-spacing: #{theme.$outer-spacing-sm};
         }
     }
 
-    .backdrop {
-        position: fixed;
-        top: 0;
-        left: 0;
-        z-index: settings.$backdrop-z-index;
-        width: 100vw;
-        height: 100vh;
+    .root[open] {
+        display: flex;
+
+        @media (prefers-reduced-motion: no-preference) {
+            animation: fade-in theme.$animation-duration ease-out;
+        }
+    }
+
+    .root[open]::backdrop {
         background: theme.$backdrop-background;
+
+        @media (prefers-reduced-motion: no-preference) {
+            animation: inherit;
+        }
     }
 
     .isRootSizeSmall {
@@ -64,17 +74,12 @@
     }
 
     .isRootSizeAuto {
-        width: auto;
         min-width: min(var(--rui-local-max-width), #{map.get(theme.$sizes, auto, min-width)});
         max-width: min(var(--rui-local-max-width), #{map.get(theme.$sizes, auto, max-width)});
     }
 
-    .isRootPositionCenter {
-        top: 50%;
-        transform: translate(-50%, -50%);
-    }
-
     .isRootPositionTop {
         top: var(--rui-local-outer-spacing);
+        bottom: auto;
     }
 }