@react-ui-org/react-ui 0.63.0 → 0.64.0

package/src/components/FormLayout/README.md

@@ -14,7 +14,8 @@ And use it:
 
 ```docoff-react-preview
 <FormLayout>
-  <TextField label="A form element" />
+  <TextField label="A text field" />
+  <Button label="Submit" />
 </FormLayout>
 ```
 
@@ -27,18 +28,14 @@ one after another in a row by default.** The FormLayout component is there to
 make building **vertical and horizontal forms** easy. It uses the right tool for
 the job: the [CSS grid layout][grid].
 
-- Put **only form field components** from React UI inside the FormLayout and
-  make sure they are **direct descendants** of it (React [fragments] are
-  supported!). All React UI form components are ready for this use case and
-  don't need to be wrapped in any `div`s. Namely, the FormLayout supports the
-  following React UI components:
-  [CheckboxField](/components/CheckboxField),
-  [Radio](/components/Radio), [SelectField](/components/SelectField),
-  [TextArea](/components/TextArea), [TextField](/components/TextField),
-  and [Toggle](/components/Toggle).
-
-- Use the [FormLayoutCustomField](#custom-fields) component when you need to
-  place any **custom content** inside the FormLayout. This layout helper ensures
+- Put **only form field components or buttons** from React UI inside the
+  FormLayout and make sure they are **direct descendants** of it (React
+  [fragments][fragments] are supported!). All React UI form components are
+  [ready for this use case](#supported-form-fields), no wrapping `<div>`s are
+  needed.
+
+- To **place any custom content** inside the FormLayout, use the
+  [FormLayoutCustomField](#custom-fields) component. This layout helper ensures
   your content is properly spaced and aligned with other FormLayout elements.
   Do **not** try to put any custom HTML or React components directly into
   FormLayout without wrapping it with the FormLayoutCustomField first.
@@ -48,6 +45,132 @@ for your FormLayout. This prevents FormLayout from unexpectedly growing in
 browsers that [don't support][rui-232] [CSS subgrid][subgrid] in cases when
 there are longer validation messages or help texts.
 
+## Supported Form Fields
+
+The FormLayout supports buttons and all React UI form fields:
+[Button](/components/Button), [CheckboxField](/components/CheckboxField),
+[FileInputField](/components/FileInputField), [Radio](/components/Radio),
+[SelectField](/components/SelectField), [TextArea](/components/TextArea),
+[TextField](/components/TextField), and [Toggle](/components/Toggle).
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fieldLayout, setFieldLayout] = React.useState('horizontal');
+  const [fruit, setFruit] = React.useState('apple');
+  const [isDeliveryAddress, setIsDeliveryAddress] = React.useState(true);
+  const [receiveNewsletter, setReceiveNewsletter] = React.useState(true);
+  const options = [
+    {
+      label: 'Apple',
+      value: 'apple',
+    },
+    {
+      label: 'Banana',
+      value: 'banana',
+    },
+    {
+      label: 'Grapefruit',
+      value: 'grapefruit',
+    },
+  ];
+  return (
+    <div>
+      <Toolbar>
+        <ToolbarItem>
+          <ButtonGroup>
+            <Button
+              color={fieldLayout === 'horizontal' ? 'selected' : 'secondary'}
+              label="Horizontal layout"
+              onClick={() => setFieldLayout('horizontal')}
+            />
+            <Button
+              color={fieldLayout === 'vertical' ? 'selected' : 'secondary'}
+              label="Vertical layout"
+              onClick={() => setFieldLayout('vertical')}
+            />
+          </ButtonGroup>
+        </ToolbarItem>
+      </Toolbar>
+      <FormLayout fieldLayout={fieldLayout} labelWidth="auto">
+        <>
+          <TextField
+            label="First Name"
+          />
+          <TextField
+            label="Last Name"
+          />
+        </>
+        <TextField
+          helpText="Optional"
+          label="Email address"
+          type="email"
+        />
+        <>
+          <TextField
+            label="Address"
+            placeholder="Address line 1"
+          />
+          <TextField
+            isLabelVisible={false}
+            label="Address 2"
+            placeholder="Address line 2"
+          />
+          <TextField
+            inputSize={6}
+            label="ZIP"
+            validationState="invalid"
+            validationText="ZIP should be 5 to 6 digits long code."
+          />
+          <FormLayoutCustomField label="Country">
+            <span>Czech Republic</span>
+          </FormLayoutCustomField>
+          <CheckboxField
+            checked={isDeliveryAddress}
+            helpText="Uncheck if you wish to deliver to a different address."
+            label="This is my delivery address"
+            onChange={() => setIsDeliveryAddress(!isDeliveryAddress)}
+          />
+        </>
+        <SelectField
+          label="Your favourite fruit"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+        />
+        <TextArea
+          fullWidth
+          label="Message"
+          rows={3}
+        />
+        <FileInputField
+          id="my-file"
+          label="Attachment"
+          onFilesChanged={() => {}}
+        />
+        <Toggle
+          checked={receiveNewsletter}
+          helpText="Only once per week!"
+          label="Receive weekly newsletter"
+          onChange={() => setReceiveNewsletter(!receiveNewsletter)}
+          required
+        />
+        <Radio
+          label="And fruit again!"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+        />
+        <InputGroup label="Promo code">
+          <TextField label="Code" />
+          <Button label="Apply" color="secondary" priority="outline" />
+        </InputGroup>
+        <Button label="Submit" />
+      </FormLayout>
+    </div>
+  )
+});
+```
+
 ## Vertical Layout
 
 Vertical FormLayout works similar to single-column [Grid](/components/Grid)
@@ -59,6 +182,7 @@ layout, simply wrap your form fields with the FormLayout component:
   <TextField label="A form element" />
   <TextField label="Another form element" />
   <TextField label="Yet another one" />
+  <Button label="Submit" />
 </FormLayout>
 ```
 
@@ -73,6 +197,7 @@ viewport size onward and it forces the horizontal layout on the fields.
   <TextField label="A form element" />
   <TextField label="Another form element" />
   <TextField label="Yet another one" />
+  <Button label="Submit" />
 </FormLayout>
 ```
 
@@ -194,11 +319,9 @@ the FormLayout component.
 
 ```docoff-react-preview
 <FormLayout fieldLayout="horizontal" labelWidth="auto">
-  <TextField label="A form element" />
   <FormLayoutCustomField label="Optional custom field label">
     <docoff-placeholder bordered>Custom field content</docoff-placeholder>
   </FormLayoutCustomField>
-  <TextField label="Another form element" />
 </FormLayout>
 ```
 
@@ -207,6 +330,29 @@ and its styles may affect contained form fields through CSS cascade, don't
 forget to mirror the aforementioned properties to the contained form fields too
 as API options as such are **not** inherited.
 
+### Nested Fields Labels
+
+When placing box form fields — TextField, TextArea, SelectField, or
+FileInputField — inside a FormLayoutCustomField, their labels are hidden
+automatically.
+
+```docoff-react-preview
+<FormLayout fieldLayout="horizontal" labelWidth="auto">
+  <FormLayoutCustomField
+    innerFieldSize="medium"
+    label="Custom field with invisible label"
+  >
+    <TextField
+      label="This field's label is hidden"
+    />
+  </FormLayoutCustomField>
+</FormLayout>
+```
+
+ℹ️ Labels are hidden regardless of `fieldLayout`. In a horizontal FormLayout,
+the nested field's own label would conflict with the FormLayout grid and
+produce incorrect alignment, so it is always hidden for consistency.
+
 ### Label Alignment
 
 If you are in a situation with one or more box form fields inside your
@@ -218,18 +364,15 @@ this task.
 
 ```docoff-react-preview
 <FormLayout fieldLayout="horizontal" labelWidth="auto">
-  <TextField label="A form element" />
   <FormLayoutCustomField
     innerFieldSize="medium"
     label="Custom field label aligned to inner text input"
   >
     <TextField
-      isLabelVisible={false}
       label="A form element"
       placeholder="Text field with invisible label"
     />
   </FormLayoutCustomField>
-  <TextField label="Another form element" />
 </FormLayout>
 ```
 
@@ -240,14 +383,12 @@ provide labels with optional feedback style.
 
 ```docoff-react-preview
 <FormLayout fieldLayout="horizontal" labelWidth="auto">
-  <TextField label="A form element" />
   <FormLayoutCustomField
     label="Custom field label in valid state"
     validationState="valid"
   >
     <docoff-placeholder bordered>Custom field content</docoff-placeholder>
   </FormLayoutCustomField>
-  <TextField label="Another form element" />
 </FormLayout>
 ```
 
@@ -264,153 +405,19 @@ React.createElement(() => {
   const [isChecked, setIsChecked] = React.useState(false);
   return (
     <FormLayout fieldLayout="horizontal" labelWidth="auto">
-      <TextField label="A form element" />
       <FormLayoutCustomField
         fullWidth
-        label="Custom field label aligned with medium form field"
-        labelForId="my-text-field-custom-accessibility-2"
+        label="Custom field label associated with a text field"
+        labelForId="my-text-field-custom-accessibility"
         innerFieldSize="medium"
       >
-        <Toolbar align="middle" dense>
-          <ToolbarItem>
-            <TextField
-              isLabelVisible={false}
-              label="A form element"
-              placeholder="Text field with invisible label"
-            />
-          </ToolbarItem>
-          <ToolbarItem>
-            <CheckboxField
-              checked={isChecked}
-              label="Another form field"
-              onChange={() => setIsChecked(!isChecked)}
-            />
-          </ToolbarItem>
-        </Toolbar>
-      </FormLayoutCustomField>
-      <TextField label="Another form element" />
-    </FormLayout>
-  )
-});
-```
-
-## Full Example
-
-This is a demo of all components supported by FormLayout.
-
-```docoff-react-preview
-React.createElement(() => {
-  const [fieldLayout, setFieldLayout] = React.useState('horizontal');
-  const [fruit, setFruit] = React.useState('apple');
-  const [isDeliveryAddress, setIsDeliveryAddress] = React.useState(true);
-  const [receiveNewsletter, setReceiveNewsletter] = React.useState(true);
-  const options = [
-    {
-      label: 'Apple',
-      value: 'apple',
-    },
-    {
-      label: 'Banana',
-      value: 'banana',
-    },
-    {
-      label: 'Grapefruit',
-      value: 'grapefruit',
-    },
-  ];
-  return (
-    <div>
-      <Toolbar>
-        <ToolbarItem>
-          <ButtonGroup>
-            <Button
-              color={fieldLayout === 'horizontal' ? 'selected' : 'secondary'}
-              label="Horizontal layout"
-              onClick={() => setFieldLayout('horizontal')}
-            />
-            <Button
-              color={fieldLayout === 'vertical' ? 'selected' : 'secondary'}
-              label="Vertical layout"
-              onClick={() => setFieldLayout('vertical')}
-            />
-          </ButtonGroup>
-        </ToolbarItem>
-      </Toolbar>
-      <FormLayout fieldLayout={fieldLayout} labelWidth="auto">
-        <>
-          <TextField
-            label="First Name"
-          />
-          <TextField
-            label="Last Name"
-          />
-        </>
         <TextField
-          helpText="Optional"
-          label="Email address"
-          type="email"
+          id="my-text-field-custom-accessibility"
+          label="A form element"
+          placeholder="Text field with invisible label"
         />
-        <>
-          <TextField
-            label="Address"
-            placeholder="Address line 1"
-          />
-          <TextField
-            isLabelVisible={false}
-            label="Address 2"
-            placeholder="Address line 2"
-          />
-          <TextField
-            inputSize={6}
-            label="ZIP"
-            validationState="invalid"
-            validationText="ZIP should be 5 to 6 digits long code."
-          />
-          <FormLayoutCustomField label="Country">
-            <span>Czech Republic</span>
-          </FormLayoutCustomField>
-          <CheckboxField
-            checked={isDeliveryAddress}
-            helpText="Uncheck if you wish to deliver to a different address."
-            label="This is my delivery address"
-            onChange={() => setIsDeliveryAddress(!isDeliveryAddress)}
-          />
-        </>
-        <SelectField
-          label="Your favourite fruit"
-          onChange={(e) => setFruit(e.target.value)}
-          options={options}
-          value={fruit}
-        />
-        <TextArea
-          fullWidth
-          label="Message"
-          rows={3}
-        />
-        <FileInputField
-          id="my-file"
-          label="Attachment"
-          onFilesChanged={() => {}}
-        />
-        <Toggle
-          checked={receiveNewsletter}
-          helpText="Only once per week!"
-          label="Receive weekly newsletter"
-          onChange={() => setReceiveNewsletter(!receiveNewsletter)}
-          required
-        />
-        <Radio
-          label="And fruit again!"
-          onChange={(e) => setFruit(e.target.value)}
-          options={options}
-          value={fruit}
-        />
-        <InputGroup label="Promo code">
-          <TextField label="Code" />
-          <Button label="Apply" color="secondary" priority="outline" />
-        </InputGroup>
-      </FormLayout>
-    </div>
+      </FormLayoutCustomField>
+    </FormLayout>
   )
 });
 ```

package/src/components/FormLayout/index.js

@@ -1,3 +1,4 @@
 export { default as FormLayout } from './FormLayout';
 export { FormLayoutContext } from './FormLayoutContext';
+export { FormLayoutCustomFieldContext } from './FormLayoutCustomFieldContext';
 export { default as FormLayoutCustomField } from './FormLayoutCustomField';

package/src/components/Popover/Popover.jsx

@@ -105,6 +105,7 @@ Popover.propTypes = {
     top: PropTypes.string,
     'transform-origin': PropTypes.string,
     translate: PropTypes.string,
+    visibility: PropTypes.string,
   }),
   /**
    * If set, the popover will become controlled, meaning it will be hidden by default and will need a trigger to open.

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

@@ -13,6 +13,7 @@
 @layer components.popover {
     .root {
         position: absolute;
+        z-index: theme.$z-index;
         width: max-content;
         max-width: theme.$max-width;
         padding: theme.$padding;

package/src/components/Popover/README.md

@@ -178,10 +178,15 @@ position the popover. The allowed props are:
 - `left`
 - `translate`
 - `transform-origin`
+- `visibility`
 
 ⚠️ [`inset`][mdn-inset] is a shorthand for `top right bottom left`, not for
 `inset-*` properties.
 
+ℹ️ `visibility` can be used to hide the Popover before its initial position is
+computed, preventing a flash of the Popover in a wrong position. Set it to
+`hidden` initially, then remove or update it once the position is ready.
+
 As opposed to `top right bottom left` and the `inset` shorthand, `inset-*`
 properties are writing-direction aware.
 
@@ -307,6 +312,29 @@ React.createElement(() => {
 });
 ```
 
+## z-index
+
+By default, the Popover's `z-index` is `auto`, which means it participates in
+the stacking context of its nearest positioned ancestor. This works well in most
+cases, but can cause the Popover to appear behind other positioned elements such
+as sticky headers, fixed toolbars, or modals.
+
+When that happens, set `--rui-Popover__z-index` to a numeric value high enough
+to place the Popover above the conflicting layer. The override can be applied
+globally or scoped to a specific context:
+
+```css
+/* Global override */
+:root {
+  --rui-Popover__z-index: 1000;
+}
+
+/* Scoped override */
+.my-context {
+  --rui-Popover__z-index: 1000;
+}
+```
+
 ## Controlled Popover
 
 Popover API can be used to control visibility of Popover component. You need to
@@ -379,6 +407,7 @@ which enables [Advanced Positioning](#advanced-positioning).
 | `--rui-Popover__color`                               | Text color                                                   |
 | `--rui-Popover__background-color`                    | Background color                                             |
 | `--rui-Popover__box-shadow`                          | Popover box shadow                                           |
+| `--rui-Popover__z-index`                             | Popover z-index (default: `auto`)                            |
 
 [div-attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes
 [Floating UI]: https://floating-ui.com/docs/react-dom

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

@@ -12,6 +12,7 @@ export default (placementStyle) => {
     'left',
     'translate',
     'transform-origin',
+    'visibility',
   ];
 
   return Object.fromEntries(

package/src/components/Popover/_theme.scss

@@ -2,6 +2,7 @@
 
 @use "sass:math";
 
+$z-index: var(--rui-Popover__z-index);
 $max-width: var(--rui-Popover__max-width);
 $padding: var(--rui-Popover__padding);
 $border-width: var(--rui-Popover__border-width);

package/src/components/SelectField/SelectField.jsx

@@ -6,7 +6,10 @@ import { transferProps } from '../../helpers/transferProps';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
 import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
 import { resolveContextOrProp } from '../_helpers/resolveContextOrProp';
-import { FormLayoutContext } from '../FormLayout';
+import {
+  FormLayoutContext,
+  FormLayoutCustomFieldContext,
+} from '../FormLayout';
 import { InputGroupContext } from '../InputGroup/InputGroupContext';
 import { Option } from './_components/Option';
 import styles from './SelectField.module.scss';
@@ -31,6 +34,7 @@ export const SelectField = React.forwardRef((props, ref) => {
   } = props;
 
   const formLayoutContext = useContext(FormLayoutContext);
+  const formLayoutCustomFieldContext = useContext(FormLayoutCustomFieldContext);
   const inputGroupContext = useContext(InputGroupContext);
 
   return (
@@ -58,7 +62,7 @@ export const SelectField = React.forwardRef((props, ref) => {
       <div
         className={classNames(
           styles.label,
-          (!isLabelVisible || inputGroupContext) && styles.isLabelHidden,
+          (!isLabelVisible || inputGroupContext || formLayoutCustomFieldContext) && styles.isLabelHidden,
         )}
         id={id && `${id}__labelText`}
       >
@@ -181,7 +185,8 @@ SelectField.propTypes = {
    * If `false`, the label will be visually hidden (but remains accessible by assistive
    * technologies).
    *
-   * Automatically set to `false` when the component is rendered within `InputGroup` component.
+   * Automatically set to `false` when the component is rendered within `InputGroup` or
+   * `FormLayoutCustomField` component.
    */
   isLabelVisible: PropTypes.bool,
   /**

package/src/components/TextArea/TextArea.jsx

@@ -6,7 +6,10 @@ import { transferProps } from '../../helpers/transferProps';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
 import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
 import { resolveContextOrProp } from '../_helpers/resolveContextOrProp';
-import { FormLayoutContext } from '../FormLayout';
+import {
+  FormLayoutContext,
+  FormLayoutCustomFieldContext,
+} from '../FormLayout';
 import styles from './TextArea.module.scss';
 
 export const TextArea = React.forwardRef((props, ref) => {
@@ -27,6 +30,7 @@ export const TextArea = React.forwardRef((props, ref) => {
   } = props;
 
   const context = useContext(FormLayoutContext);
+  const formLayoutCustomFieldContext = useContext(FormLayoutCustomFieldContext);
 
   return (
     <label
@@ -49,7 +53,7 @@ export const TextArea = React.forwardRef((props, ref) => {
       <div
         className={classNames(
           styles.label,
-          !isLabelVisible && styles.isLabelHidden,
+          (!isLabelVisible || formLayoutCustomFieldContext) && styles.isLabelHidden,
         )}
         id={id && `${id}__labelText`}
       >
@@ -127,6 +131,9 @@ TextArea.propTypes = {
   /**
    * If `false`, the label will be visually hidden (but remains accessible by assistive
    * technologies).
+   *
+   * Automatically set to `false` when the component is rendered within `FormLayoutCustomField`
+   * component.
    */
   isLabelVisible: PropTypes.bool,
   /**

package/src/components/TextField/TextField.jsx

@@ -6,7 +6,10 @@ import { transferProps } from '../../helpers/transferProps';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
 import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
 import { resolveContextOrProp } from '../_helpers/resolveContextOrProp';
-import { FormLayoutContext } from '../FormLayout';
+import {
+  FormLayoutContext,
+  FormLayoutCustomFieldContext,
+} from '../FormLayout';
 import { InputGroupContext } from '../InputGroup/InputGroupContext';
 import styles from './TextField.module.scss';
 
@@ -31,6 +34,7 @@ export const TextField = React.forwardRef((props, ref) => {
     ...restProps
   } = props;
   const formLayoutContext = useContext(FormLayoutContext);
+  const formLayoutCustomFieldContext = useContext(FormLayoutCustomFieldContext);
   const inputGroupContext = useContext(InputGroupContext);
   const hasSmallInput = (inputSize !== undefined) && (inputSize <= SMALL_INPUT_SIZE);
 
@@ -62,7 +66,7 @@ export const TextField = React.forwardRef((props, ref) => {
       <div
         className={classNames(
           styles.label,
-          (!isLabelVisible || inputGroupContext) && styles.isLabelHidden,
+          (!isLabelVisible || inputGroupContext || formLayoutCustomFieldContext) && styles.isLabelHidden,
         )}
         id={id && `${id}__labelText`}
       >
@@ -153,7 +157,8 @@ TextField.propTypes = {
    * If `false`, the label will be visually hidden (but remains accessible by assistive
    * technologies).
    *
-   * Automatically set to `false` when the component is rendered within `InputGroup` component.
+   * Automatically set to `false` when the component is rendered within `InputGroup` or
+   * `FormLayoutCustomField` component.
    */
   isLabelVisible: PropTypes.bool,
   /**

package/src/styles/_utilities.scss

@@ -7,7 +7,11 @@
 
 @each $breakpoint in map.keys(breakpoint-settings.$values) {
     @include breakpoint.up($breakpoint) {
-        $infix: if(map.get(breakpoint-settings.$values, $breakpoint) == 0, "", "-#{$breakpoint}");
+        $infix: "";
+
+        @if map.get(breakpoint-settings.$values, $breakpoint) != 0 {
+            $infix: "-#{$breakpoint}";
+        }
 
         @each $key, $utility in utility-settings.$map {
             @if meta.type-of($utility) == "map" and (map.get($utility, responsive) == true or $infix == "") {