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

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;
+};

package/src/lib/components/Modal/_hooks/useModalFocus.js

@@ -0,0 +1,126 @@
+import { useEffect } from 'react';
+
+export const useModalFocus = (
+  autoFocus,
+  childrenWrapperRef,
+  primaryButtonRef,
+  closeButtonRef,
+) => {
+  useEffect(
+    () => {
+      // Following code finds all focusable elements and among them first not disabled form
+      // field element (input, textarea or select) or primary button and focuses it. This is
+      // necessary to have focus on one of those elements to be able to submit the form
+      // by pressing Enter key. If there are neither, it tries to focus any other focusable
+      // elements. In case there are none or `autoFocus` is disabled, childrenWrapperElement
+      // (Modal itself) is focused.
+
+      const childrenWrapperElement = childrenWrapperRef.current;
+
+      if (childrenWrapperElement == null) {
+        return () => {};
+      }
+
+      const childrenFocusableElements = Array.from(
+        childrenWrapperElement.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'),
+      );
+
+      const firstFocusableElement = childrenFocusableElements[0];
+      const lastFocusableElement = childrenFocusableElements[childrenFocusableElements.length - 1];
+
+      const resolveFocusBeforeListener = () => {
+        if (!autoFocus || childrenFocusableElements.length === 0) {
+          childrenWrapperElement.tabIndex = -1;
+          childrenWrapperElement.focus();
+          return;
+        }
+
+        const firstFormFieldEl = childrenFocusableElements.find(
+          (element) => ['INPUT', 'TEXTAREA', 'SELECT'].includes(element.nodeName) && !element.disabled,
+        );
+
+        if (firstFormFieldEl) {
+          firstFormFieldEl.focus();
+          return;
+        }
+
+        if (primaryButtonRef?.current != null) {
+          primaryButtonRef.current.focus();
+          return;
+        }
+
+        firstFocusableElement.focus();
+      };
+
+      const keyPressHandler = (e) => {
+        if (e.key === 'Escape' && closeButtonRef?.current != null) {
+          closeButtonRef.current.click();
+          return;
+        }
+
+        if (
+          e.key === 'Enter'
+          && e.target.nodeName !== 'BUTTON'
+          && e.target.nodeName !== 'TEXTAREA'
+          && e.target.nodeName !== 'A'
+          && primaryButtonRef?.current != null
+        ) {
+          primaryButtonRef.current.click();
+          return;
+        }
+
+        // Following code traps focus inside Modal
+
+        if (e.key !== 'Tab') {
+          return;
+        }
+
+        if (childrenFocusableElements.length === 0) {
+          childrenWrapperElement.focus();
+          e.preventDefault();
+          return;
+        }
+
+        if (
+          ![
+            ...childrenFocusableElements,
+            childrenWrapperElement,
+          ]
+            .includes(window.document.activeElement)
+        ) {
+          firstFocusableElement.focus();
+          e.preventDefault();
+          return;
+        }
+
+        if (!e.shiftKey && window.document.activeElement === lastFocusableElement) {
+          firstFocusableElement.focus();
+          e.preventDefault();
+          return;
+        }
+
+        if (e.shiftKey
+          && (
+            window.document.activeElement === firstFocusableElement
+            || window.document.activeElement === childrenWrapperElement
+          )
+        ) {
+          lastFocusableElement.focus();
+          e.preventDefault();
+        }
+      };
+
+      resolveFocusBeforeListener();
+
+      window.document.addEventListener('keydown', keyPressHandler, false);
+
+      return () => window.document.removeEventListener('keydown', keyPressHandler, false);
+    },
+    [
+      autoFocus,
+      childrenWrapperRef,
+      primaryButtonRef,
+      closeButtonRef,
+    ],
+  );
+};

package/src/lib/components/Modal/_hooks/useModalScrollPrevention.js

@@ -0,0 +1,35 @@
+import { useLayoutEffect } from 'react';
+
+export const useModalScrollPrevention = (preventScrollUnderneath) => {
+  useLayoutEffect(
+    () => {
+      if (preventScrollUnderneath === 'off') {
+        return () => {};
+      }
+
+      if (preventScrollUnderneath === 'default') {
+        const scrollbarWidth = Math.abs(window.innerWidth - window.document.documentElement.clientWidth);
+        const prevOverflow = window.document.body.style.overflow;
+        const prevPaddingRight = window.document.body.style.paddingRight;
+
+        window.document.body.style.overflow = 'hidden';
+
+        if (Number.isNaN(parseInt(prevPaddingRight, 10))) {
+          window.document.body.style.paddingRight = `${scrollbarWidth}px`;
+        } else {
+          window.document.body.style.paddingRight = `calc(${prevPaddingRight} + ${scrollbarWidth}px)`;
+        }
+
+        return () => {
+          window.document.body.style.overflow = prevOverflow;
+          window.document.body.style.paddingRight = prevPaddingRight;
+        };
+      }
+
+      preventScrollUnderneath?.start();
+
+      return preventScrollUnderneath?.reset;
+    },
+    [preventScrollUnderneath],
+  );
+};

package/src/lib/components/Modal/_settings.scss

@@ -3,7 +3,7 @@
 @use "../../styles/theme/borders";
 @use "../../styles/theme/typography";
 
-$border-radius: borders.$radius;
+$border-radius: borders.$radius-2;
 $z-index: z-indexes.$modal;
 $backdrop-z-index: z-indexes.$modal-backdrop;
 $title-font-size: map.get(typography.$font-size-values, 2);

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

@@ -77,7 +77,12 @@ See [API](#api) for all available options.
 - Use **clear, calm error messages** when there's a problem with what they
   entered.
 
-📖 [Read more about checkboxes and radios at Nielsen Norman Group.](https://www.nngroup.com/articles/checkboxes-vs-radio-buttons/)
+- In the background, Radio uses the [`fieldset`][fieldset] element. Not only it
+  improves the [accessibility] of the group, it also allows you to make use of
+  its built-in features like disabling all nested inputs or pairing the group
+  with a form outside. Consult [the MDN docs][fieldset] to learn more.
+
+📖 [Read more about checkboxes and radios at Nielsen Norman Group.][nng-radio]
 
 ## Invisible Label
 
@@ -308,5 +313,8 @@ options. On top of that, the following options are available for Radio.
 | `--rui-FormField--check__input--radio__border-radius`              | Input corner radius                            |
 | `--rui-FormField--check__input--radio--checked__background-image` | Checked input background image (inline, URL, …) |
 
+[nng-radio]: https://www.nngroup.com/articles/checkboxes-vs-radio-buttons/
+[fieldset]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset
+[accessibility]: https://www.w3.org/WAI/tutorials/forms/grouping/
 [React synthetic events]: https://reactjs.org/docs/events.html
 [radio]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio#additional_attributes