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

package/src/components/CheckboxField/CheckboxField.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';
@@ -15,6 +15,7 @@ export const CheckboxField = React.forwardRef((props, ref) => {
     isLabelVisible,
     label,
     labelPosition,
+    renderAsRequired,
     required,
     validationState,
     validationText,
@@ -30,7 +31,7 @@ export const CheckboxField = React.forwardRef((props, ref) => {
         context && context.layout === 'horizontal' ? styles.isRootLayoutHorizontal : styles.isRootLayoutVertical,
         labelPosition === 'before' && styles.hasRootLabelBefore,
         disabled && styles.isRootDisabled,
-        required && styles.isRootRequired,
+        (renderAsRequired || required) && styles.isRootRequired,
         getRootValidationStateClassName(validationState, styles),
       )}
       htmlFor={id}
@@ -82,6 +83,7 @@ CheckboxField.defaultProps = {
   id: undefined,
   isLabelVisible: true,
   labelPosition: 'after',
+  renderAsRequired: false,
   required: false,
   validationState: null,
   validationText: null,
@@ -120,7 +122,11 @@ CheckboxField.propTypes = {
    */
   labelPosition: PropTypes.oneOf(['before', 'after']),
   /**
-   * 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,
   /**

package/src/components/CheckboxField/README.md

@@ -18,7 +18,13 @@ React.createElement(() => {
   return (
     <CheckboxField
       checked={agree}
-      label="I agree"
+      label={(
+          <>
+            I have read and agree with
+            {' '}
+            <TextLink href="#" label="terms and conditions" />
+          </>
+        )}
       onChange={() => setAgree(!agree)}
     />
   );
@@ -132,20 +138,44 @@ React.createElement(() => {
     <>
       <CheckboxField
         checked={agree}
-        label="I have read and agree with terms and conditions"
+        label={(
+          <>
+            I have read and agree with
+            {' '}
+            <TextLink href="#" label="terms and conditions" />
+          </>
+        )}
         onChange={() => setAgree(!agree)}
         validationState="valid"
       />
       <CheckboxField
         checked={agree}
-        label="I have read and agree with terms and conditions"
+        label={(
+          <>
+            I have read and agree with
+            {' '}
+            <TextLink href="#" label="terms and conditions" />
+          </>
+        )}
         onChange={() => setAgree(!agree)}
         validationState="warning"
-        validationText="Please wait 10 minutes until we verify your data."
+        validationText={(
+          <>
+            Please wait 10 minutes until we verify your data.
+            {' '}
+            <TextLink href="#" label="Cancel" />
+          </>
+        )}
       />
       <CheckboxField
         checked={agree}
-        label="I have read and agree with terms and conditions"
+        label={(
+          <>
+            I have read and agree with
+            {' '}
+            <TextLink href="#" label="terms and conditions" />
+          </>
+        )}
         onChange={() => setAgree(!agree)}
         required
         validationState="invalid"
@@ -156,6 +186,81 @@ React.createElement(() => {
 });
 ```
 
+### Required State
+
+The required state indicates that the input is mandatory. Required fields
+display an asterisk `*` after the label by default.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [agree, setAgree] = React.useState(true);
+  return (
+    <CheckboxField
+      checked={agree}
+      label="I agree"
+      onChange={() => setAgree(!agree)}
+      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 checked and unchecked 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 [optional, setOptional] = React.useState(false);
+  const [renderAsRequired, setRenderAsRequired] = React.useState(false);
+  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">
+        <CheckboxField
+          checked={optional}
+          label="This field is optional"
+          onChange={() => setOptional(!optional)}
+        />
+        <CheckboxField
+          checked={renderAsRequired}
+          label="This field is optional but looks like required"
+          onChange={() => setRenderAsRequired(!renderAsRequired)}
+          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
 
 Disabled state makes the input unavailable.

package/src/components/FileInputField/FileInputField.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';

package/src/components/FormLayout/FormLayout.jsx

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

package/src/components/FormLayout/FormLayoutCustomField.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 { getRootSizeClassName } from '../_helpers/getRootSizeClassName';

package/src/components/Grid/Grid.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 { generateResponsiveCustomProperties } from './_helpers/generateResponsiveCustomProperties';

package/src/components/Grid/Grid.module.scss

@@ -19,6 +19,9 @@
 //    `--rui-local-<PROPERTY>: var(--rui-local-<PROPERTY>-sm, var(--rui-local-<PROPERTY>-xs, <INITIAL FALLBACK>))`
 //
 // 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.
 
 @use "sass:map";
 @use "../../styles/tools/spacing";
@@ -35,8 +38,12 @@
         grid-template-rows: var(--rui-local-rows); // 2.
         grid-auto-flow: var(--rui-local-auto-flow); // 2.
         grid-gap: var(--rui-local-row-gap) var(--rui-local-column-gap); // 2.
-        place-content: var(--rui-local-align-content) var(--rui-local-justify-content); // 2.
-        place-items: var(--rui-local-align-items) var(--rui-local-justify-items); // 2.
+        // stylelint-disable declaration-block-no-redundant-longhand-properties -- 3.
+        align-content: var(--rui-local-align-content); // 2.
+        align-items: var(--rui-local-align-items); // 2.
+        justify-content: var(--rui-local-justify-content); // 2.
+        justify-items: var(--rui-local-justify-items); // 2.
+        // stylelint-enable declaration-block-no-redundant-longhand-properties
     }
 
     // stylelint-disable-next-line selector-max-universal -- Reset any previously added margins.

package/src/components/Grid/GridSpan.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 { generateResponsiveCustomProperties } from './_helpers/generateResponsiveCustomProperties';

package/src/components/InputGroup/InputGroup.jsx

@@ -3,8 +3,7 @@ import React, {
   useContext,
   useMemo,
 } from 'react';
-import { Text } from '../Text';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
@@ -12,6 +11,7 @@ import { getRootValidationStateClassName } from '../_helpers/getRootValidationSt
 import { isChildrenEmpty } from '../_helpers/isChildrenEmpty';
 import { resolveContextOrProp } from '../_helpers/resolveContextOrProp';
 import { FormLayoutContext } from '../FormLayout';
+import { Text } from '../Text';
 import { InputGroupContext } from './InputGroupContext';
 import styles from './InputGroup.module.scss';
 

package/src/components/InputGroup/InputGroup.module.scss

@@ -1,7 +1,9 @@
 // 1. The class name is intentionally singular because it's targeted by other mixins too.
 // 2. Use a block-level display mode to prevent extra white space below grouped inputs in Safari.
-// 3. Prevent individual inputs from overlapping inside narrow containers.
-// 4. Legends are tricky to style, let's use a `div` instead.
+// 3. Let wide input groups honor the minimum input width and overflow horizontally without wrapping and distorting
+//    the inputs.
+// 4. Prevent individual inputs from overlapping inside narrow containers.
+// 5. Legends are tricky to style, let's use a `div` instead.
 //    https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset#styling_with_css
 
 @use "../../styles/tools/form-fields/box-field-elements";
@@ -19,12 +21,12 @@
         @include foundation.fieldset();
     }
 
-    // 4.
+    // 5.
     .legend {
         @include accessibility.hide-text();
     }
 
-    // 4.
+    // 5.
     .label {
         @include foundation.label();
     }
@@ -63,11 +65,13 @@
     .isRootLayoutVertical,
     .isRootLayoutHorizontal {
         @include box-field-layout.vertical();
+
+        max-width: none; // 3.
     }
 
     .isRootLayoutVertical .field,
     .isRootLayoutHorizontal .field {
-        max-width: none; // 3.
+        max-width: none; // 4.
     }
 
     .isRootLayoutHorizontal {

package/src/components/Modal/Modal.jsx

@@ -1,7 +1,7 @@
 import PropTypes from 'prop-types';
 import React, { useRef } 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 { getPositionClassName } from './_helpers/getPositionClassName';

package/src/components/Modal/ModalBody.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 { isChildrenEmpty } from '../_helpers/isChildrenEmpty';

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.
    */