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

package/src/components/Modal/ModalCloseButton.jsx

@@ -1,9 +1,7 @@
 import PropTypes from 'prop-types';
 import React, { useContext } from 'react';
-import {
-  RUIContext,
-  withGlobalProps,
-} from '../../provider';
+import { TranslationsContext } from '../../providers/translations';
+import { withGlobalProps } from '../../providers/globalProps';
 import { transferProps } from '../../utils/transferProps';
 import styles from './ModalCloseButton.module.scss';
 
@@ -13,7 +11,7 @@ export const ModalCloseButton = React.forwardRef((props, ref) => {
     ...restProps
   } = props;
 
-  const { translations } = useContext(RUIContext);
+  const translations = useContext(TranslationsContext);
 
   return (
     <button

package/src/components/Modal/ModalContent.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { transferProps } from '../../utils/transferProps';
 import { isChildrenEmpty } from '../_helpers/isChildrenEmpty';
 import styles from './ModalContent.module.scss';

package/src/components/Modal/ModalFooter.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { getJustifyClassName } from './_helpers/getJustifyClassName';

package/src/components/Modal/ModalHeader.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { getJustifyClassName } from './_helpers/getJustifyClassName';

package/src/components/Modal/ModalTitle.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { transferProps } from '../../utils/transferProps';
 import styles from './ModalTitle.module.scss';
 

package/src/components/Modal/README.md

@@ -30,7 +30,7 @@ React.createElement(() => {
     React UI docs. You may not need it in your application.
   */}
   return (
-    <RUIProvider globalProps={{
+    <GlobalPropsProvider globalProps={{
       Modal: { preventScrollUnderneath: window.document.documentElement }
     }}>
       <Button
@@ -72,7 +72,7 @@ React.createElement(() => {
           </Modal>
         )}
       </div>
-    </RUIProvider>
+    </GlobalPropsProvider>
   );
 });
 ```
@@ -126,7 +126,7 @@ React.createElement(() => {
     React UI docs. You may not need it in your application.
   */}
   return (
-    <RUIProvider globalProps={{
+    <GlobalPropsProvider globalProps={{
       Modal: { preventScrollUnderneath: window.document.documentElement }
     }}>
       <Button
@@ -247,7 +247,7 @@ React.createElement(() => {
           </Modal>
         )}
       </div>
-    </RUIProvider>
+    </GlobalPropsProvider>
   );
 });
 ```
@@ -281,7 +281,7 @@ React.createElement(() => {
     React UI docs. You may not need it in your application.
   */}
   return (
-    <RUIProvider globalProps={{
+    <GlobalPropsProvider globalProps={{
       Modal: { preventScrollUnderneath: window.document.documentElement }
     }}>
       <Button
@@ -374,7 +374,7 @@ React.createElement(() => {
           </Modal>
         )}
       </div>
-    </RUIProvider>
+    </GlobalPropsProvider>
   );
 });
 ```
@@ -415,7 +415,7 @@ React.createElement(() => {
     React UI docs. You may not need it in your application.
   */}
   return (
-    <RUIProvider globalProps={{
+    <GlobalPropsProvider globalProps={{
       Modal: { preventScrollUnderneath: window.document.documentElement }
     }}>
       <Button
@@ -517,7 +517,7 @@ React.createElement(() => {
           </Modal>
         )}
       </div>
-    </RUIProvider>
+    </GlobalPropsProvider>
   );
 });
 ```
@@ -538,7 +538,7 @@ React.createElement(() => {
     React UI docs. You may not need it in your application.
   */}
   return (
-    <RUIProvider globalProps={{
+    <GlobalPropsProvider globalProps={{
       Modal: { preventScrollUnderneath: window.document.documentElement }
     }}>
       <Button
@@ -605,7 +605,7 @@ React.createElement(() => {
           </Modal>
         )}
       </div>
-    </RUIProvider>
+    </GlobalPropsProvider>
   );
 });
 ```
@@ -622,7 +622,7 @@ React.createElement(() => {
     React UI docs. You may not need it in your application.
   */}
   return (
-    <RUIProvider globalProps={{
+    <GlobalPropsProvider globalProps={{
       Modal: { preventScrollUnderneath: window.document.documentElement }
     }}>
       <Button
@@ -665,7 +665,7 @@ React.createElement(() => {
           </Modal>
         )}
       </div>
-    </RUIProvider>
+    </GlobalPropsProvider>
   );
 });
 ```
@@ -690,7 +690,7 @@ React.createElement(() => {
     React UI docs. You may not need it in your application.
   */}
   return (
-    <RUIProvider globalProps={{
+    <GlobalPropsProvider globalProps={{
       Modal: { preventScrollUnderneath: window.document.documentElement }
     }}>
       <Button
@@ -734,7 +734,7 @@ React.createElement(() => {
           </Modal>
         )}
       </div>
-    </RUIProvider>
+    </GlobalPropsProvider>
   );
 });
 ```
@@ -754,7 +754,7 @@ React.createElement(() => {
     React UI docs. You may not need it in your application.
   */}
   return (
-    <RUIProvider globalProps={{
+    <GlobalPropsProvider globalProps={{
       Modal: { preventScrollUnderneath: window.document.documentElement }
     }}>
       <Button
@@ -807,7 +807,7 @@ React.createElement(() => {
           </Modal>
         )}
       </div>
-    </RUIProvider>
+    </GlobalPropsProvider>
   );
 });
 ```
@@ -936,7 +936,7 @@ React.createElement(() => {
     React UI docs. You may not need it in your application.
   */}
   return (
-    <RUIProvider globalProps={{
+    <GlobalPropsProvider globalProps={{
       Modal: { preventScrollUnderneath: window.document.documentElement }
     }}>
       <Button
@@ -999,7 +999,7 @@ React.createElement(() => {
           </Modal>
         )}
       </div>
-    </RUIProvider>
+    </GlobalPropsProvider>
   );
 });
 ```

package/src/components/Paper/Paper.jsx

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

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 { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
+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,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { transferProps } from '../../utils/transferProps';
 import styles from './PopoverWrapper.module.scss';
 

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

package/src/components/Popover/_helpers/cleanPlacementStyle.js

@@ -0,0 +1,20 @@
+export default (placementStyle) => {
+  const validProps = [
+    'position',
+    'inset',
+    'inset-inline-start',
+    'inset-inline-end',
+    'inset-block-start',
+    'inset-block-end',
+    'top',
+    'right',
+    'bottom',
+    'left',
+    'translate',
+    'transform-origin',
+  ];
+
+  return Object.fromEntries(
+    Object.entries(placementStyle).filter(([prop]) => validProps.includes(prop)),
+  );
+};

package/src/components/Radio/README.md

@@ -237,6 +237,109 @@ have.
   })
 ```
 
+### Required State
+
+The required state indicates that the input is mandatory.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fruit, setFruit] = React.useState('apple');
+  return (
+    <Radio
+      label="Your favourite fruit"
+      onChange={(e) => setFruit(e.target.value)}
+      options={[
+        {
+          label: 'Apple',
+          value: 'apple',
+        },
+        {
+          label: 'Banana',
+          value: 'banana',
+        },
+        {
+          label: 'Grapefruit',
+          value: 'grapefruit',
+        },
+      ]}
+      value={fruit}
+      required
+    />
+  );
+})
+```
+
+#### Styling the Required State
+
+All form fields in React UI can be
+[styled](/docs/customize/theming/forms/#required-state)
+to indicate the required state.
+
+However, you may find yourself in a situation where a form field is valid in
+both selected and unselected states, for example to turn on or off a feature.
+If your project uses the label color as the primary means to indicate the
+required state of input fields and the usual asterisk `*` is omitted, you may
+want to keep the label color consistent for both states to avoid confusion.
+
+For this edge case, there is the `renderAsRequired` prop:
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fruit, setFruit] = React.useState('apple');
+  const options = [
+    {
+      label: 'Apple',
+      value: 'apple',
+    },
+    {
+      label: 'Banana',
+      value: 'banana',
+    },
+    {
+      label: 'Grapefruit',
+      value: 'grapefruit',
+    },
+  ];
+  return (
+   <React.Fragment>
+      <style>
+      {`
+        .example {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 1rem 0.5rem;
+        }
+
+        .example--themed-form-fields {
+          --rui-FormField__label__color: var(--rui-color-text-secondary);
+          --rui-FormField--required__label__color: var(--rui-color-text-primary);
+          --rui-FormField--required__sign: '';
+        }
+      `}
+      </style>
+      <div class="example example--themed-form-fields">
+        <Radio
+          label="This field is optional"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+        />
+        <Radio
+          label="This field is optional but looks like required"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+          renderAsRequired
+        />
+      </div>
+    </React.Fragment>
+  );
+})
+```
+
+It renders the field as if it was required, but doesn't add the `required`
+attribute to the actual input.
+
 ### Disabled State
 
 It's possible to disable just some options or the whole set.

package/src/components/Radio/Radio.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React, { useContext } from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
@@ -16,6 +16,7 @@ export const Radio = ({
   label,
   layout,
   options,
+  renderAsRequired,
   required,
   validationState,
   validationText,
@@ -33,7 +34,7 @@ export const Radio = ({
           ? styles.isRootLayoutHorizontal
           : styles.isRootLayoutVertical,
         disabled && styles.isRootDisabled,
-        required && styles.isRootRequired,
+        (renderAsRequired || required) && styles.isRootRequired,
         getRootValidationStateClassName(validationState, styles),
       )}
       disabled={disabled}
@@ -116,6 +117,7 @@ Radio.defaultProps = {
   id: undefined,
   isLabelVisible: true,
   layout: 'vertical',
+  renderAsRequired: false,
   required: false,
   validationState: null,
   validationText: null,
@@ -181,7 +183,11 @@ Radio.propTypes = {
     ]),
   })).isRequired,
   /**
-   * If `true`, the input will be required.
+   * If `true`, the input will be rendered as if it was required.
+   */
+  renderAsRequired: PropTypes.bool,
+  /**
+   * If `true`, the input will be made and rendered as required, regardless of the `renderAsRequired` prop.
    */
   required: PropTypes.bool,
   /**