@react-ui-org/react-ui 0.57.0 → 0.59.0

package/src/components/Modal/_animations.scss

@@ -0,0 +1,9 @@
+@keyframes fade-in {
+    0% {
+        opacity: 0;
+    }
+
+    100% {
+        opacity: 1;
+    }
+}

package/src/components/Modal/_helpers/dialogOnCancelHandler.js

@@ -0,0 +1,28 @@
+// Disable coverage for the following function
+/* istanbul ignore next */
+
+/**
+ * Handles the cancel event of the dialog which is fired when the user presses the Escape key or triggers cancel event
+ * by native dialog mechanism.
+ *
+ * It prevents the default behaviour of the native dialog and closes the dialog manually by clicking the close button,
+ * if the close button is not disabled.
+ *
+ * @param e
+ * @param closeButtonRef
+ * @param onCancelHandler
+ */
+export const dialogOnCancelHandler = (e, closeButtonRef, onCancelHandler = undefined) => {
+  // Prevent the default behaviour of the event as we want to close dialog manually.
+  e.preventDefault();
+
+  // If the close button is not disabled, close the modal.
+  if (closeButtonRef?.current != null && closeButtonRef?.current?.disabled === false) {
+    closeButtonRef.current.click();
+  }
+
+  // This is a custom handler that is passed as a prop to the Modal component
+  if (onCancelHandler) {
+    onCancelHandler(e);
+  }
+};

package/src/components/Modal/_helpers/dialogOnClickHandler.js

@@ -0,0 +1,46 @@
+// Disable coverage for the following function
+/* istanbul ignore next */
+
+/**
+ * Handles the click event of the dialog which is fired when the user clicks on the dialog or on its descendants.
+ *
+ * This handler is used to close the dialog when the user clicks on the backdrop, if it is allowed to close
+ * on backdrop click and the close button is not disabled.
+ *
+ * @param e
+ * @param closeButtonRef
+ * @param dialogRef
+ * @param allowCloseOnBackdropClick
+ */
+export const dialogOnClickHandler = (
+  e,
+  closeButtonRef,
+  dialogRef,
+  allowCloseOnBackdropClick,
+) => {
+  // If it is not allowed to close modal on backdrop click, do nothing.
+  if (!allowCloseOnBackdropClick) {
+    return;
+  }
+
+  // Detection of the click on the backdrop is based on the following conditions:
+  // 1. The click target is the dialog itself. This prevents detection of clicks on the dialog's children.
+  // 2. The click is outside the dialog's boundaries.
+  const dialogRect = dialogRef.current.getBoundingClientRect();
+  const isClickedOnBackdrop = dialogRef.current === e.target && (
+    e.clientX < dialogRect.left
+    || e.clientX > dialogRect.right
+    || e.clientY < dialogRect.top
+    || e.clientY > dialogRect.bottom
+  );
+
+  // If user does not click on the backdrop, do nothing.
+  if (!isClickedOnBackdrop) {
+    return;
+  }
+
+  // If the close button is not disabled, close the modal.
+  if (closeButtonRef?.current != null && closeButtonRef?.current?.disabled === false) {
+    closeButtonRef.current.click();
+  }
+};

package/src/components/Modal/_helpers/dialogOnCloseHandler.js

@@ -0,0 +1,28 @@
+// Disable coverage for the following function
+/* istanbul ignore next */
+
+/**
+ * Handles the close event of the dialog which is fired when the user presses the Escape key or triggers close event
+ * by native dialog mechanism.
+ *
+ * It prevents the default behaviour of the native dialog and closes the dialog manually by clicking the close button,
+ * if the close button is not disabled.
+ *
+ * @param e
+ * @param closeButtonRef
+ * @param onCloseHandler
+ */
+export const dialogOnCloseHandler = (e, closeButtonRef, onCloseHandler = undefined) => {
+  // Prevent the default behaviour of the event as we want to close dialog manually.
+  e.preventDefault();
+
+  // If the close button is not disabled, close the modal.
+  if (closeButtonRef?.current != null && closeButtonRef?.current?.disabled === false) {
+    closeButtonRef.current.click();
+  }
+
+  // This is a custom handler that is passed as a prop to the Modal component
+  if (onCloseHandler) {
+    onCloseHandler(e);
+  }
+};

package/src/components/Modal/_helpers/dialogOnKeyDownHandler.js

@@ -0,0 +1,62 @@
+// Disable coverage for the following function
+/* istanbul ignore next */
+
+/**
+ * Handles the keydown event of the dialog which is fired when the user presses a key within the dialog.
+ *
+ * This handler is used to stop propagation of the Escape key press, if it is not allowed to close
+ * on Escape key and the close button is disabled.
+ *
+ * It is also used to trigger the primary action when the user presses the Enter key, if it is allowed to trigger
+ * the primary action on Enter key and the primary button is not disabled. This applies only when the focused
+ * element is an input or select as other elements should not trigger the primary action. Textarea is omitted
+ * as Enter key is used for new line.
+ *
+ * @param e
+ * @param closeButtonRef
+ * @param primaryButtonRef
+ * @param allowCloseOnEscapeKey
+ * @param allowPrimaryActionOnEnterKey
+ */
+export const dialogOnKeyDownHandler = (
+  e,
+  closeButtonRef,
+  primaryButtonRef,
+  allowCloseOnEscapeKey,
+  allowPrimaryActionOnEnterKey,
+) => {
+  if (e.key === 'Escape') {
+    // Prevent closing the modal using the Escape key when one of the following conditions is met:
+    // 1. The close button is not present
+    // 2. The close button is disabled
+    // 3. `allowCloseOnEscapeKey` is set to `false`
+    //
+    // ⚠️ Else-if statement calling `closeButtonRef.current.click()` is necessary due to missing support
+    // of close event in happy-dom library. When this is fixed, the `else` statement can be removed
+    // as the `closeButtonRef.current.click()` will be handled by `dialogOnCancelHandler.js`.
+    if (
+      closeButtonRef?.current == null
+      || closeButtonRef?.current?.disabled === true
+      || !allowCloseOnEscapeKey
+    ) {
+      e.preventDefault();
+    } else if (process?.env?.NODE_ENV === 'test') {
+      closeButtonRef.current.click();
+    }
+  }
+
+  // Trigger the primary action when the Enter key is pressed and the following conditions are met:
+  // 1. The primary button is present
+  // 2. The primary button is not disabled
+  // 3. `allowPrimaryActionOnEnterKey` is set to `true`
+  // 4. The focused element is an input or select (text area is omitted as Enter key is used for new line)
+  if (
+    e.key === 'Enter'
+    && primaryButtonRef?.current != null
+    && primaryButtonRef?.current?.disabled === false
+    && allowPrimaryActionOnEnterKey
+    && ['INPUT', 'SELECT'].includes(e.target.nodeName)
+  ) {
+    primaryButtonRef.current.click();
+  }
+};

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

@@ -3,5 +3,5 @@ export const getPositionClassName = (modalPosition, styles) => {
     return styles.isRootPositionTop;
   }
 
-  return styles.isRootPositionCenter;
+  return null;
 };

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

@@ -2,9 +2,8 @@ import { useEffect } from 'react';
 
 export const useModalFocus = (
   autoFocus,
-  childrenWrapperRef,
+  dialogRef,
   primaryButtonRef,
-  closeButtonRef,
 ) => {
   useEffect(
     () => {
@@ -12,115 +11,49 @@ export const useModalFocus = (
       // 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
+      // elements. In case there are none or `autoFocus` is disabled, dialogElement
       // (Modal itself) is focused.
 
-      const childrenWrapperElement = childrenWrapperRef.current;
+      const dialogElement = dialogRef.current;
 
-      if (childrenWrapperElement == null) {
+      if (dialogElement == null) {
         return () => {};
       }
 
       const childrenFocusableElements = Array.from(
-        childrenWrapperElement.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'),
+        dialogElement.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 (!autoFocus || childrenFocusableElements.length === 0) {
+        dialogElement.tabIndex = -1;
+        dialogElement.focus();
+        return () => {};
+      }
 
-        if (!e.shiftKey && window.document.activeElement === lastFocusableElement) {
-          firstFocusableElement.focus();
-          e.preventDefault();
-          return;
-        }
+      const firstFormFieldEl = childrenFocusableElements.find(
+        (element) => ['INPUT', 'TEXTAREA', 'SELECT'].includes(element.nodeName) && !element.disabled,
+      );
 
-        if (e.shiftKey
-          && (
-            window.document.activeElement === firstFocusableElement
-            || window.document.activeElement === childrenWrapperElement
-          )
-        ) {
-          lastFocusableElement.focus();
-          e.preventDefault();
-        }
-      };
+      if (firstFormFieldEl) {
+        firstFormFieldEl.focus();
+        return () => {};
+      }
 
-      resolveFocusBeforeListener();
+      if (primaryButtonRef?.current != null && primaryButtonRef?.current?.disabled === false) {
+        primaryButtonRef.current.focus();
+        return () => {};
+      }
 
-      window.document.addEventListener('keydown', keyPressHandler, false);
+      firstFocusableElement.focus();
 
-      return () => window.document.removeEventListener('keydown', keyPressHandler, false);
+      return () => {};
     },
     [
       autoFocus,
-      childrenWrapperRef,
+      dialogRef,
       primaryButtonRef,
-      closeButtonRef,
     ],
   );
 };

package/src/components/Modal/_settings.scss

@@ -1,9 +1,10 @@
 @use "sass:map";
-@use "../../styles/settings/z-indexes";
+@use "../../styles/settings/collections";
 @use "../../styles/theme/borders";
 @use "../../styles/theme/typography";
 
+$border-width: borders.$width;
 $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);
+$colors: collections.$feedback-colors;
+$themeable-properties: border-color, background-color;

package/src/components/Modal/_theme.scss

@@ -10,6 +10,7 @@ $footer-gap: var(--rui-Modal__footer__gap);
 $backdrop-background: var(--rui-Modal__backdrop__background);
 $outer-spacing-xs: var(--rui-Modal__outer-spacing--xs);
 $outer-spacing-sm: var(--rui-Modal__outer-spacing--sm);
+$animation-duration: var(--rui-Modal__animation__duration);
 
 $sizes: (
     auto: (

package/src/components/Paper/Paper.jsx

@@ -1,8 +1,8 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
-import { classNames } from '../../utils/classNames';
-import { transferProps } from '../../utils/transferProps';
+import { withGlobalProps } from '../../providers/globalProps';
+import { classNames } from '../../helpers/classNames/classNames';
+import { transferProps } from '../../helpers/transferProps';
 import styles from './Paper.module.scss';
 
 export const Paper = ({

package/src/components/Popover/Popover.jsx

@@ -1,9 +1,10 @@
 import PropTypes from 'prop-types';
 import React from 'react';
 import { createPortal } from 'react-dom';
-import { withGlobalProps } from '../../provider';
-import { classNames } from '../../utils/classNames';
-import { transferProps } from '../../utils/transferProps';
+import { transferProps } from '../../helpers/transferProps';
+import { classNames } from '../../helpers/classNames';
+import { withGlobalProps } from '../../providers/globalProps';
+import cleanPlacementStyle from './_helpers/cleanPlacementStyle';
 import getRootSideClassName from './_helpers/getRootSideClassName';
 import getRootAlignmentClassName from './_helpers/getRootAlignmentClassName';
 import styles from './Popover.module.scss';
@@ -12,24 +13,42 @@ export const Popover = React.forwardRef((props, ref) => {
   const {
     placement,
     children,
+    placementStyle,
+    popoverTargetId,
     portalId,
     ...restProps
   } = props;
 
   const PopoverEl = (
-    <div
-      {...transferProps(restProps)}
-      className={classNames(
-        styles.root,
-        ref && styles.isRootControlled,
-        getRootSideClassName(placement, styles),
-        getRootAlignmentClassName(placement, styles),
+    <>
+      {/**
+        * This hack is needed because the default behavior of the Popover API is to place the popover into a
+        * top-layer. It is currently not possible to position an element in the top-layer relative to a normal element.
+        * This will create a hidden browser popover, then with CSS it will open and close the RUI popover.
+        */}
+      {!!popoverTargetId && (
+        <div
+          className={styles.helper}
+          id={popoverTargetId}
+          popover="auto"
+        />
       )}
-      ref={ref}
-    >
-      {children}
-      <span className={styles.arrow} />
-    </div>
+      <div
+        {...transferProps(restProps)}
+        className={classNames(
+          styles.root,
+          ref && styles.isRootControlled,
+          popoverTargetId && styles.controlledPopover,
+          getRootSideClassName(placement, styles),
+          getRootAlignmentClassName(placement, styles),
+        )}
+        ref={ref}
+        style={placementStyle ? cleanPlacementStyle(placementStyle) : null}
+      >
+        {children}
+        <span className={styles.arrow} />
+      </div>
+    </>
   );
 
   if (portalId === null) {
@@ -41,6 +60,8 @@ export const Popover = React.forwardRef((props, ref) => {
 
 Popover.defaultProps = {
   placement: 'bottom',
+  placementStyle: null,
+  popoverTargetId: null,
   portalId: null,
 };
 
@@ -67,6 +88,30 @@ Popover.propTypes = {
     'left-start',
     'left-end',
   ]),
+  /**
+   * Used for positioning the popover with a library like Floating UI. It is filtered,
+   * then passed to the popover as the `style` prop.
+   */
+  placementStyle: PropTypes.shape({
+    bottom: PropTypes.string,
+    inset: PropTypes.string,
+    'inset-block-end': PropTypes.string,
+    'inset-block-start': PropTypes.string,
+    'inset-inline-end': PropTypes.string,
+    'inset-inline-start': PropTypes.string,
+    left: PropTypes.string,
+    position: PropTypes.string,
+    right: PropTypes.string,
+    top: PropTypes.string,
+    'transform-origin': PropTypes.string,
+    translate: PropTypes.string,
+  }),
+  /**
+   * If set, the popover will become controlled, meaning it will be hidden by default and will need a trigger to open.
+   * This sets the ID of the internal helper element for the popover.
+   * Assign the same ID to `popovertarget` of a trigger to make it open and close.
+   */
+  popoverTargetId: PropTypes.string,
   /**
    * If set, popover is rendered in the React Portal with that ID.
    */

package/src/components/Popover/Popover.module.scss

@@ -1,6 +1,12 @@
-// 1. Reset positioning for controlled variant.
-// 2. Shift Popover so there is space for the arrow between Popover and reference element.
-// 3. Add top offset in case it's not defined by external library.
+// 1. Hide the popover by default. This is needed because the popover is
+//    controlled via CSS with the help of the helper popover. The popover can't
+//    be displayed directly, because relative positioning doesn't work with
+//    elements on the top-layer, so this CSS hack is needed.
+// 2. Hide the popover helper element.
+// 3. If the popover helper is open, show the actual popover.
+// 4. Reset positioning for controlled variant.
+// 5. Shift Popover so there is space for the arrow between Popover and reference element.
+// 6. Add top offset in case it's not defined by external library.
 
 @use "theme";
 
@@ -49,6 +55,28 @@
         }
     }
 
+    // Controlled popover
+    .controlledPopover {
+        display: none; // 1.
+    }
+
+    .helper {
+        position: fixed; // 2.
+        inset: unset;
+        top: 0;
+        right: 0;
+        width: auto;
+        height: auto;
+        padding: 0;
+        border: none;
+        background: transparent;
+        pointer-events: none;
+    }
+
+    .helper:popover-open ~ .controlledPopover {
+        display: block; // 3.
+    }
+
     // Sides
     .isRootAtTop {
         bottom: calc(100% + #{theme.$arrow-gap} - #{theme.$arrow-safe-rendering-overlap});
@@ -212,27 +240,27 @@
     .isRootControlled.isRootAtBottom,
     .isRootControlled.isRootAtLeft,
     .isRootControlled.isRootAtRight {
-        inset: unset; // 1.
+        inset: unset; // 4.
     }
 
     .isRootControlled.isRootAtTop {
-        transform: translate(0, calc(-1 * #{theme.$arrow-height})); // 2.
+        transform: translate(0, calc(-1 * #{theme.$arrow-height})); // 5.
     }
 
     .isRootControlled.isRootAtBottom {
-        transform: translate(0, #{theme.$arrow-height}); // 2.
+        transform: translate(0, #{theme.$arrow-height}); // 5.
     }
 
     .isRootControlled.isRootAtLeft {
-        transform: translate(calc(-1 * #{theme.$arrow-height}), 0); // 2.
+        transform: translate(calc(-1 * #{theme.$arrow-height}), 0); // 5.
     }
 
     .isRootControlled.isRootAtRight {
-        transform: translate(#{theme.$arrow-height}, 0); // 2.
+        transform: translate(#{theme.$arrow-height}, 0); // 5.
     }
 
     .isRootControlled.isRootAtLeft.isRootAtStart,
     .isRootControlled.isRootAtRight.isRootAtStart {
-        top: 0; // 3.
+        top: 0; // 6.
     }
 }

package/src/components/Popover/PopoverWrapper.jsx

@@ -1,7 +1,7 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
-import { transferProps } from '../../utils/transferProps';
+import { withGlobalProps } from '../../providers/globalProps';
+import { transferProps } from '../../helpers/transferProps';
 import styles from './PopoverWrapper.module.scss';
 
 export const PopoverWrapper = ({

package/src/components/Popover/README.md

@@ -162,6 +162,29 @@ automatically, including smart position updates to ensure Popover visibility,
 we recommend to involve an external library designed specifically for this
 purpose.
 
+To position the popover, you need to provide the `placementStyle` prop with the
+style you want to apply to the popover. This prop should only be used to
+position the popover. The allowed props are:
+
+- `position`
+- `inset`
+- `inset-inline-start`
+- `inset-inline-end`
+- `inset-block-start`
+- `inset-block-end`
+- `top`
+- `right`
+- `bottom`
+- `left`
+- `translate`
+- `transform-origin`
+
+⚠️ [`inset`][mdn-inset] is a shorthand for `top right bottom left`, not for
+`inset-*` properties.
+
+As opposed to `top right bottom left` and the `inset` shorthand, `inset-*`
+properties are writing-direction aware.
+
 ℹ️ The following example is using external library [Floating UI]. To use
 Floating UI, install it first:
 
@@ -267,10 +290,10 @@ React.createElement(() => {
             <Popover
               id="my-advanced-popover"
               placement={finalPlacement}
-              style={{
+              placementStyle={{
                 position: strategy,
-                top: y ? y : '',
-                left: x ? x : '',
+                top: `${y}px`,
+                left: `${x}px`,
               }}
               ref={floating}
             >
@@ -284,6 +307,39 @@ React.createElement(() => {
 });
 ```
 
+## Controlled Popover
+
+Popover API can be used to control visibility of Popover component. You need to
+set `id` on the trigger element and matching `popoverTargetId` attribute on the
+Popover component. This leverages the browser's Popover API to control the
+popover, automatically closing it when the trigger or the backdrop is pressed.
+
+```docoff-react-preview
+React.createElement(() => {
+  // All inline styles in this example are for demonstration purposes only.
+  return (
+    <div
+      style={{
+        display: 'grid',
+        placeContent: 'center',
+        minWidth: '20rem',
+        minHeight: '10rem',
+      }}
+    >
+      <PopoverWrapper>
+        <Button
+          label="Want to see a popover? Click me!"
+          popovertarget="my-popover-helper"
+        />
+        <Popover id="my-popover" popoverTargetId="my-popover-helper">
+            Hello there!
+        </Popover>
+      </PopoverWrapper>
+    </div>
+  );
+});
+```
+
 ## Forwarding HTML Attributes
 
 In addition to the options below in the [component's API](#api) section, you
@@ -326,5 +382,6 @@ which enables [Advanced Positioning](#advanced-positioning).
 
 [div-attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes
 [Floating UI]: https://floating-ui.com/docs/react-dom
+[mdn-inset]: https://developer.mozilla.org/en-US/docs/Web/CSS/inset
 [React common props]: https://react.dev/reference/react-dom/components/common#common-props
 [ref]: https://reactjs.org/docs/refs-and-the-dom.html