@react-ui-org/react-ui 0.51.0 → 0.52.1

package/src/lib/components/Modal/Modal.jsx

@@ -1,12 +1,13 @@
 import PropTypes from 'prop-types';
-import React, {
-  useEffect,
-  useRef,
-} from 'react';
+import React, { useRef } from 'react';
 import { createPortal } from 'react-dom';
 import { withGlobalProps } from '../../provider';
 import { transferProps } from '../_helpers/transferProps';
 import { classNames } from '../../utils/classNames';
+import { getPositionClassName } from './_helpers/getPositionClassName';
+import { getSizeClassName } from './_helpers/getSizeClassName';
+import { useModalFocus } from './_hooks/useModalFocus';
+import { useModalScrollPrevention } from './_hooks/useModalScrollPrevention';
 import styles from './Modal.scss';
 
 const preRender = (
@@ -16,63 +17,34 @@ const preRender = (
   position,
   restProps,
   size,
-) => {
-  const sizeClass = (modalSize) => {
-    if (modalSize === 'small') {
-      return styles.isRootSizeSmall;
-    }
-
-    if (modalSize === 'medium') {
-      return styles.isRootSizeMedium;
-    }
-
-    if (modalSize === 'large') {
-      return styles.isRootSizeLarge;
-    }
-
-    if (modalSize === 'fullscreen') {
-      return styles.isRootSizeFullscreen;
-    }
-
-    return styles.isRootSizeAuto;
-  };
-
-  const positionClass = (modalPosition) => {
-    if (modalPosition === 'top') {
-      return styles.isRootPositionTop;
-    }
-
-    return styles.isRootPositionCenter;
-  };
-
-  return (
+) => (
+  <div
+    className={styles.backdrop}
+    onClick={(e) => {
+      e.preventDefault();
+      if (closeButtonRef?.current != null) {
+        closeButtonRef.current.click();
+      }
+    }}
+    role="presentation"
+  >
     <div
-      className={styles.backdrop}
-      onClick={() => {
-        if (closeButtonRef?.current != null) {
-          closeButtonRef.current.click();
-        }
+      {...transferProps(restProps)}
+      className={classNames(
+        styles.root,
+        getSizeClassName(size, styles),
+        getPositionClassName(position, styles),
+      )}
+      onClick={(e) => {
+        e.stopPropagation();
       }}
       role="presentation"
+      ref={childrenWrapperRef}
     >
-      <div
-        {...transferProps(restProps)}
-        className={classNames(
-          styles.root,
-          sizeClass(size),
-          positionClass(position),
-        )}
-        onClick={(e) => {
-          e.stopPropagation();
-        }}
-        role="presentation"
-        ref={childrenWrapperRef}
-      >
-        {children}
-      </div>
+      {children}
     </div>
-  );
-};
+  </div>
+);
 
 export const Modal = ({
   autoFocus,
@@ -80,52 +52,21 @@ export const Modal = ({
   closeButtonRef,
   portalId,
   position,
+  preventScrollUnderneath,
   primaryButtonRef,
   size,
   ...restProps
 }) => {
   const childrenWrapperRef = useRef();
 
-  const keyPressHandler = (e) => {
-    if (e.key === 'Escape' && closeButtonRef?.current != null) {
-      closeButtonRef.current.click();
-    }
-
-    if (e.key === 'Enter' && e.target.nodeName !== 'BUTTON' && primaryButtonRef?.current != null) {
-      primaryButtonRef.current.click();
-    }
-  };
-
-  useEffect(() => {
-    window.document.addEventListener('keydown', keyPressHandler, false);
-    const removeKeyPressHandler = () => {
-      window.document.removeEventListener('keydown', keyPressHandler, false);
-    };
-
-    // If `autoFocus` is set to `true`, following code finds first form field element
-    // (input, textarea or select) or primary button and auto focuses it. This is necessary
-    // to have focus on one of those elements to be able to submit form by pressing Enter key.
-    if (autoFocus) {
-      if (childrenWrapperRef?.current != null) {
-        const childrenWrapperElement = childrenWrapperRef.current;
-        const childrenElements = childrenWrapperElement.querySelectorAll('*');
-        const formFieldEl = Array.from(childrenElements).find(
-          (element) => ['INPUT', 'TEXTAREA', 'SELECT'].includes(element.nodeName) && !element.disabled,
-        );
-
-        if (formFieldEl) {
-          formFieldEl.focus();
-          return removeKeyPressHandler;
-        }
-      }
-
-      if (primaryButtonRef?.current != null) {
-        primaryButtonRef.current.focus();
-      }
-    }
+  useModalFocus(
+    autoFocus,
+    childrenWrapperRef,
+    primaryButtonRef,
+    closeButtonRef,
+  );
 
-    return removeKeyPressHandler;
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  useModalScrollPrevention(preventScrollUnderneath);
 
   if (portalId === null) {
     return preRender(
@@ -157,14 +98,16 @@ Modal.defaultProps = {
   closeButtonRef: null,
   portalId: null,
   position: 'center',
+  preventScrollUnderneath: 'default',
   primaryButtonRef: null,
   size: 'medium',
 };
 
 Modal.propTypes = {
   /**
-   * If `true`, focus the first input element in the modal or primary button (referenced by the `primaryButtonRef` prop)
-   * when the modal is opened.
+   * 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`,
+   * focus the Modal itself.
    */
   autoFocus: PropTypes.bool,
   /**
@@ -192,6 +135,24 @@ Modal.propTypes = {
    * Vertical position of the modal inside browser window.
    */
   position: PropTypes.oneOf(['top', 'center']),
+  /**
+   * Mode in which Modal prevents scroll of elements bellow:
+   * * `default` - Modal prevents scroll on the `body` element
+   * * `off` - Modal does not prevent any scroll
+   * * object
+   * * * `reset` - method called on Modal's unmount to reset scroll prevention
+   * * * `start` - method called on Modal's mount to custom scroll prevention
+   */
+  preventScrollUnderneath: PropTypes.oneOfType([
+    PropTypes.oneOf([
+      'default',
+      'off',
+    ]),
+    PropTypes.shape({
+      reset: PropTypes.func,
+      start: PropTypes.func,
+    }),
+  ]),
   /**
    * Reference to primary button element. It is used to submit modal when Enter key is pressed and as fallback
    * when `autoFocus` functionality does not find any input element to be focused.

package/src/lib/components/Modal/README.mdx

@@ -25,6 +25,7 @@ import {
   ModalTitle,
   Radio,
   ScrollView,
+  TextArea,
   TextField,
   Toolbar,
   ToolbarGroup,
@@ -116,12 +117,15 @@ See [API](#api) for all available options.
 
 - Modal **automatically focuses the first non-disabled form field** by default
   which allows users to confirm the modal by hitting the enter key. When no
-  field is found then the primary button (in the footer) is focused. To turn
-  this feature off, set the `autofocus` prop to `false`.
+  field is found then the primary button (in the footer) is focused. If there
+  are neither, it tries to focus any other focusable elements. In case there
+  are none, or [autoFocus](#autoFocus) is disabled, Modal itself is focused.
 
 - **Avoid stacking** of modals. While it may technically work, the modal is just
   not designed for that.
 
+📖 [Read more about modals at Nielsen Norman Group.][nng-modal]
+
 ## Composition
 
 Modal is decomposed into the following components:
@@ -822,24 +826,147 @@ can be closed by pressing the `Escape` key.
 
 To enable it, you just need to pass a reference to the buttons using
 `primaryButtonRef` and `closeButtonRef` props on Modal. The advantage of passing
-a reference to the button is that if the button is disabled, the key press will
-not fire the event.
-
-👉 We strongly recommend using this feature together with
-[Autofocus](#autofocus) for a better user experience.
+the reference to the button is that if the button is disabled, the key press
+will not fire the event.
 
 ## Autofocus
 
 Autofocus is implemented to enhance the user experience by automatically
-focussing an element within the modal.
+focusing an element within the Modal.
 
 How does it work? It tries to find `input`, `textarea`, and `select` elements
 inside of Modal and moves focus onto the first non-disabled one. If none is
 found and the `primaryButtonRef` prop on Modal is set, then the primary button
-is focused.
+is focused. If there are neither, it tries to focus any other focusable elements.
+In case there are none or `autoFocus` is disabled, Modal itself is focused.
 
-Autofocus is enabled by default, so if you want to control the focus of
-elements manually, set the `autoFocus` prop on Modal to `false`.
+<Playground>
+  {() => {
+    const [modalOpen, setModalOpen] = React.useState(null);
+    const modalPrimaryButtonRef = React.useRef();
+    const modalCloseButtonRef = React.useRef();
+    return (
+      <>
+        <Button
+          label="Launch modal with autofocus and form"
+          onClick={() => setModalOpen(1)}
+        />
+        <Button
+          label="Launch modal with autofocus"
+          onClick={() => setModalOpen(2)}
+        />
+        <Button
+          label="Launch modal with autofocus disabled"
+          onClick={() => setModalOpen(3)}
+        />
+        <div>
+          {modalOpen === 1 && (
+            <Modal
+              closeButtonRef={modalCloseButtonRef}
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with autoFocus and form</ModalTitle>
+                <ModalCloseButton onClick={() => setModalOpen(null)} />
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <FormLayout autoWidth fieldLayout="horizontal">
+                    <TextField
+                      disabled
+                      label="A form element"
+                    />
+                    <TextField label="Another form element" />
+                    <TextArea label="Yet another one" />
+                  </FormLayout>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Submit"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+          {modalOpen === 2 && (
+            <Modal
+              closeButtonRef={modalCloseButtonRef}
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with autoFocus enabled with no form</ModalTitle>
+                <ModalCloseButton onClick={() => setModalOpen(null)} />
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <p>
+                    This Modal autofocuses the primary button or any other
+                    focusable element.
+                  </p>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Acknowledge"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+          {modalOpen === 3 && (
+            <Modal
+              autoFocus={false}
+              closeButtonRef={modalCloseButtonRef}
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with autoFocus disabled</ModalTitle>
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <p>
+                    This Modal focuses the Modal element itself.
+                  </p>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Acknowledge"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+        </div>
+      </>
+    );
+  }}
+</Playground>
 
 ## Scrolling Long Content
 
@@ -959,7 +1086,7 @@ independent of the page itself. This can be done in three ways using the
         <div>
           {modalOpen && (
             <Modal
-              autoFocus={false}
+              autoFocus={modalScrolling !== 'none'}
               closeButtonRef={modalCloseButtonRef}
               primaryButtonRef={modalPrimaryButtonRef}
               size="small"
@@ -1003,9 +1130,154 @@ independent of the page itself. This can be done in three ways using the
 
 ### Long Content and Autofocus
 
-👉 If you wrap ModalContent with ScrollView, you may want to turn `autoFocus`
-off to prevent the modal from scrolling to the end immediately after being
-opened.
+👉 If you have a Modal with `scrolling` set to `none`, you may want to disable
+`autoFocus` to prevent the modal from scrolling to the end immediately after
+being opened.
+
+## Prevent Scrolling Underneath the Modal
+
+You can choose the mode in which Modal prevents the scroll of the page underneath.
+Default mode prevents scrolling on `<body>` element and accounts for the scrollbar
+width. If you choose `off`, there will be no scroll prevention. If you need more
+flexibility, define your methods `start` (called on Modal's mount) and `reset`
+(called on Modal unmount) wrapped by an object and handle scroll prevention
+yourself.
+
+<Playground>
+  {() => {
+    const [modalOpen, setModalOpen] = React.useState(null);
+    const modalPrimaryButtonRef = React.useRef();
+    const modalCloseButtonRef = React.useRef();
+    const customScrollPreventionObject = {
+      start: () => {
+        // YOUR CUSTOM SCROLL PREVENTING LOGIC GOES HERE
+        window.document.body.style.overflowY = 'hidden'
+      },
+      reset: () => {
+        // YOUR CUSTOM SCROLL RE-ENABLING LOGIC GOES HERE
+        window.document.body.style.overflowY = 'auto'
+      },
+    };
+    return (
+      <>
+        <Button
+          label="Launch modal with default scroll prevention"
+          onClick={() => setModalOpen(1)}
+        />
+        <Button
+          label="Launch modal with no scroll prevention"
+          onClick={() => setModalOpen(2)}
+        />
+        <Button
+          label="Launch modal with custom scroll prevention"
+          onClick={() => setModalOpen(3)}
+        />
+        <div>
+          {modalOpen === 1 && (
+            <Modal
+              closeButtonRef={modalCloseButtonRef}
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with default scroll prevention</ModalTitle>
+                <ModalCloseButton onClick={() => setModalOpen(null)} />
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <p>
+                    This Modal uses default scroll prevention on the document's
+                    <code>body</code> element.
+                  </p>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Acknowledge"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+          {modalOpen === 2 && (
+            <Modal
+              closeButtonRef={modalCloseButtonRef}
+              preventScrollUnderneath="off"
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with no scroll prevention</ModalTitle>
+                <ModalCloseButton onClick={() => setModalOpen(null)} />
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <p>
+                    This Modal does not prevent scrolling.
+                  </p>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Acknowledge"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+          {modalOpen === 3 && (
+            <Modal
+              closeButtonRef={modalCloseButtonRef}
+              preventScrollUnderneath={customScrollPreventionObject}
+              primaryButtonRef={modalPrimaryButtonRef}
+            >
+              <ModalHeader>
+                <ModalTitle>Modal with custom scroll prevention</ModalTitle>
+                <ModalCloseButton onClick={() => setModalOpen(null)} />
+              </ModalHeader>
+              <ModalBody>
+                <ModalContent>
+                  <p>
+                    This Modal uses provided custom functions to prevent scrolling
+                    and reset it on unmount.
+                  </p>
+                </ModalContent>
+              </ModalBody>
+              <ModalFooter>
+                <Button
+                  label="Acknowledge"
+                  onClick={() => setModalOpen(null)}
+                  ref={modalPrimaryButtonRef}
+                />
+                <Button
+                  color="secondary"
+                  label="Close"
+                  onClick={() => setModalOpen(null)}
+                  priority="outline"
+                  ref={modalCloseButtonRef}
+                />
+              </ModalFooter>
+            </Modal>
+          )}
+        </div>
+      </>
+    );
+  }}
+</Playground>
 
 <!-- markdownlint-disable MD024 -->
 
@@ -1081,6 +1353,7 @@ accessibility.
 | `--rui-Modal--fullscreen__width`                     | Width of fullscreen modal                                     |
 | `--rui-Modal--fullscreen__height`                    | Height of fullscreen modal                                    |
 
+[nng-modal]: https://www.nngroup.com/articles/modal-nonmodal-dialog/
 [React synthetic events]: https://reactjs.org/docs/events.html
 [div]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes
 [heading]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#attributes

package/src/lib/components/Modal/_helpers/getPositionClassName.js

@@ -0,0 +1,7 @@
+export const getPositionClassName = (modalPosition, styles) => {
+  if (modalPosition === 'top') {
+    return styles.isRootPositionTop;
+  }
+
+  return styles.isRootPositionCenter;
+};

package/src/lib/components/Modal/_helpers/getSizeClassName.js

@@ -0,0 +1,19 @@
+export const getSizeClassName = (modalSize, styles) => {
+  if (modalSize === 'small') {
+    return styles.isRootSizeSmall;
+  }
+
+  if (modalSize === 'medium') {
+    return styles.isRootSizeMedium;
+  }
+
+  if (modalSize === 'large') {
+    return styles.isRootSizeLarge;
+  }
+
+  if (modalSize === 'fullscreen') {
+    return styles.isRootSizeFullscreen;
+  }
+
+  return styles.isRootSizeAuto;
+};