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

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,54 +55,76 @@
         }
     }
 
+    // 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: 100%;
+        bottom: calc(100% + #{theme.$arrow-gap} - #{theme.$arrow-safe-rendering-overlap});
     }
 
     .isRootAtBottom {
-        top: 100%;
+        top: calc(100% + #{theme.$arrow-gap} - #{theme.$arrow-safe-rendering-overlap});
     }
 
     .isRootAtLeft {
-        right: 100%;
+        right: calc(100% + #{theme.$arrow-gap} - #{theme.$arrow-safe-rendering-overlap});
     }
 
     .isRootAtRight {
-        left: 100%;
+        left: calc(100% + #{theme.$arrow-gap} - #{theme.$arrow-safe-rendering-overlap});
     }
 
     // Arrows
     .isRootAtTop > .arrow {
-        top: 100%;
+        top: calc(100% - #{theme.$arrow-safe-rendering-overlap});
     }
 
     .isRootAtBottom > .arrow {
-        bottom: 100%;
+        bottom: calc(100% - #{theme.$arrow-safe-rendering-overlap});
     }
 
     .isRootAtLeft > .arrow {
-        left: 100%;
+        left: calc(100% - #{theme.$arrow-safe-rendering-overlap});
     }
 
     .isRootAtRight > .arrow {
-        right: 100%;
+        right: calc(100% - #{theme.$arrow-safe-rendering-overlap});
     }
 
     // Side alignments: top
     .isRootAtTop.isRootAtCenter {
         left: 50%;
-        transform: translate(-50%, #{-1 * theme.$arrow-height});
+        transform: translate(-50%, calc(-1 * #{theme.$arrow-height}));
     }
 
     .isRootAtTop.isRootAtStart {
         left: 0;
-        transform: translate(0, #{-1 * theme.$arrow-height});
+        transform: translate(0, calc(-1 * #{theme.$arrow-height}));
     }
 
     .isRootAtTop.isRootAtEnd {
         right: 0;
-        transform: translate(0, #{-1 * theme.$arrow-height});
+        transform: translate(0, calc(-1 * #{theme.$arrow-height}));
     }
 
     .isRootAtTop.isRootAtCenter > .arrow {
@@ -148,17 +176,17 @@
     // Side alignments: left
     .isRootAtLeft.isRootAtCenter {
         top: 50%;
-        transform: translate(#{-1 * theme.$arrow-height}, -50%);
+        transform: translate(calc(-1 * #{theme.$arrow-height}), -50%);
     }
 
     .isRootAtLeft.isRootAtStart {
         top: 0;
-        transform: translate(#{-1 * theme.$arrow-height}, 0);
+        transform: translate(calc(-1 * #{theme.$arrow-height}), 0);
     }
 
     .isRootAtLeft.isRootAtEnd {
         bottom: 0;
-        transform: translate(#{-1 * theme.$arrow-height}, 0);
+        transform: translate(calc(-1 * #{theme.$arrow-height}), 0);
     }
 
     .isRootAtLeft.isRootAtCenter > .arrow {
@@ -212,27 +240,27 @@
     .isRootControlled.isRootAtBottom,
     .isRootControlled.isRootAtLeft,
     .isRootControlled.isRootAtRight {
-        inset: unset; // 1.
+        inset: unset; // 4.
     }
 
     .isRootControlled.isRootAtTop {
-        transform: translate(0, #{-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(#{-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/Popover/_theme.scss

@@ -11,6 +11,8 @@ $color: var(--rui-Popover__color);
 $background-color: var(--rui-Popover__background-color);
 $box-shadow: var(--rui-Popover__box-shadow);
 
-$arrow-width: 1rem;
-$arrow-height: math.div($arrow-width, 2); // 1.
+$arrow-safe-rendering-overlap: 1px;
+$arrow-gap: 1px;
+$arrow-width: calc(1rem + #{$arrow-safe-rendering-overlap * 2});
+$arrow-height: calc($arrow-width / 2); // 1.
 $arrow-corner-offset: 0.75rem;

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

package/src/components/Radio/Radio.module.scss

@@ -52,6 +52,10 @@
         @include foundation.label-required();
     }
 
+    .isRootRequired .optionLabel {
+        @include foundation.label-required($show-require-sign: false);
+    }
+
     // States
     .isRootStateInvalid {
         @include variants.validation(invalid);

package/src/components/ScrollView/ScrollView.jsx

@@ -6,10 +6,8 @@ import React, {
   useRef,
   useState,
 } from 'react';
-import {
-  RUIContext,
-  withGlobalProps,
-} from '../../provider';
+import { TranslationsContext } from '../../providers/translations';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { getElementsPositionDifference } from './_helpers/getElementsPositionDifference';
@@ -48,7 +46,7 @@ export const ScrollView = React.forwardRef((props, ref) => {
     ...restProps
   } = props;
 
-  const { translations } = useContext(RUIContext);
+  const translations = useContext(TranslationsContext);
 
   const [isAutoScrollInProgress, setIsAutoScrollInProgress] = useState(false);
   const [isScrolledAtStart, setIsScrolledAtStart] = useState(false);

package/src/components/SelectField/README.md

@@ -592,6 +592,109 @@ React.createElement(() => {
 })
 ```
 
+### Required State
+
+The required state indicates that the input is mandatory.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fruit, setFruit] = React.useState('apple');
+  return (
+    <SelectField
+      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">
+      <SelectField
+          label="This field is optional"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+        />
+        <SelectField
+          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 input.

package/src/components/SelectField/SelectField.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';
@@ -21,6 +21,7 @@ export const SelectField = React.forwardRef((props, ref) => {
     label,
     layout,
     options,
+    renderAsRequired,
     required,
     size,
     validationState,
@@ -43,7 +44,7 @@ export const SelectField = React.forwardRef((props, ref) => {
           ? styles.isRootLayoutHorizontal
           : styles.isRootLayoutVertical,
         inputGroupContext && styles.isRootGrouped,
-        required && styles.isRootRequired,
+        (renderAsRequired || required) && styles.isRootRequired,
         getRootSizeClassName(
           resolveContextOrProp(inputGroupContext && inputGroupContext.size, size),
           styles,
@@ -136,6 +137,7 @@ SelectField.defaultProps = {
   id: undefined,
   isLabelVisible: true,
   layout: 'vertical',
+  renderAsRequired: false,
   required: false,
   size: 'medium',
   validationState: null,
@@ -227,7 +229,11 @@ SelectField.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,
   /**

package/src/components/Table/Table.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 { TableHeaderCell } from './_components/TableHeaderCell';
 import { TableBodyCell } from './_components/TableBodyCell';

package/src/components/Tabs/Tabs.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 './Tabs.module.scss';
 

package/src/components/Tabs/TabsItem.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 './TabsItem.module.scss';

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