@react-ui-org/react-ui 0.44.1 → 0.47.0

package/src/lib/components/Popover/PopoverWrapper.jsx

@@ -0,0 +1,46 @@
+import PropTypes from 'prop-types';
+import React from 'react';
+import { withGlobalProps } from '../../provider';
+import withForwardedRef from '../withForwardedRef';
+import styles from './Popover.scss';
+
+export const PopoverWrapper = ({
+  children,
+  id,
+  tag: Tag,
+  ...restProps
+}) => (
+  <Tag
+    className={styles.wrapper}
+    id={id}
+    {...restProps}
+  >
+    {children}
+  </Tag>
+);
+
+PopoverWrapper.defaultProps = {
+  id: undefined,
+  tag: 'div',
+};
+
+PopoverWrapper.propTypes = {
+  /**
+   * Popover reference and the Popover itself.
+   */
+  children: PropTypes.node.isRequired,
+  /**
+   * ID of the root HTML element.
+   */
+  id: PropTypes.string,
+  /**
+   * HTML tag to render. Can be any valid HTML tag of your choice, usually a
+   * [block-level element](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements).
+   */
+  tag: PropTypes.string,
+};
+
+export const PopoverWrapperWithContext = withForwardedRef(withGlobalProps(PopoverWrapper, 'PopoverWrapper'));
+
+export default PopoverWrapperWithContext;
+

package/src/lib/components/Popover/README.mdx

@@ -0,0 +1,333 @@
+---
+name: Popover
+menu: 'Miscellaneous'
+route: /components/popover
+---
+
+# Popover
+
+import {
+  useFloating,
+  autoUpdate,
+  flip,
+} from '@floating-ui/react-dom'
+import {
+  Playground,
+  Props,
+} from 'docz'
+import { Placeholder } from '../../../docs/_components/Placeholder/Placeholder'
+import { Button } from '../Button/Button'
+import { ButtonGroup } from '../ButtonGroup/ButtonGroup'
+import { SelectField } from '../SelectField/SelectField'
+import { Toolbar } from '../Toolbar/Toolbar'
+import { ToolbarItem } from '../Toolbar/ToolbarItem'
+import { Popover } from './Popover'
+import { PopoverWrapper } from './PopoverWrapper'
+
+Popover displays additional information without interrupting user flow.
+
+## Basic Usage
+
+To implement the Popover component, you need to import it first:
+
+```js
+import { Popover, PopoverWrapper } from '@react-ui-org/react-ui';
+```
+
+And use it:
+
+<Playground>
+{() => {
+  const [isPopoverOpen, setIsPopoverOpen] = React.useState(false);
+  // All inline styles in this example are for demonstration purposes only.
+  return (
+    <div
+      style={{
+        display: 'grid',
+        placeContent: 'center',
+        minWidth: '20rem',
+        minHeight: '10rem',
+      }}
+    >
+      <PopoverWrapper>
+        <Button
+          aria-describedby={isPopoverOpen ? 'my-popover' : undefined}
+          label="Want to see a popover? Click me!"
+          onClick={() => setIsPopoverOpen(!isPopoverOpen)}
+        />
+        {isPopoverOpen && (
+          <Popover id="my-popover">
+            Hello there!
+          </Popover>
+        )}
+      </PopoverWrapper>
+    </div>
+  );
+}}
+</Playground>
+
+See [API](#api) for all available options.
+
+## Placement
+
+Available placements are: top, right, bottom, and left. Additionally, all basic
+placements can be aligned to the center (default, no suffix), start (e.g.
+`top-start`), or end (e.g. `bottom-end`). Check Popover [API](#api) for the
+complete list of accepted values.
+
+<Playground>
+{() => {
+  const [align, setAlign] = React.useState('');
+  // All inline styles in this example are for demonstration purposes only.
+  return (
+    <>
+      <Toolbar align="baseline">
+        <ToolbarItem>
+          <span id="alignment-options-label">Alignment:</span>
+        </ToolbarItem>
+        <ToolbarItem>
+          <ButtonGroup aria-labelledby="alignment-options-label">
+            <Button
+              color={align === '-start' ? 'dark' : 'primary'}
+              label="start"
+              onClick={() => setAlign('-start')}
+            />
+            <Button
+              color={align === '' ? 'dark' : 'primary'}
+              label="center"
+              onClick={() => setAlign('')}
+            />
+            <Button
+              color={align === '-end' ? 'dark' : 'primary'}
+              label="end"
+              onClick={() => setAlign('-end')}
+            />
+          </ButtonGroup>
+        </ToolbarItem>
+      </Toolbar>
+      <div
+        style={{
+          display: 'grid',
+          placeContent: 'center',
+          minWidth: '20rem',
+          minHeight: '15rem',
+        }}
+      >
+        <PopoverWrapper>
+          <Placeholder bordered aria-describedby="my-popover-top">
+            Popovers
+            <br />
+            all day long…
+          </Placeholder>
+          <Popover id="my-popover-top" placement={`top${align}`}>
+            Top side
+          </Popover>
+          <Popover id="my-popover-right" placement={`right${align}`}>
+            Right side
+          </Popover>
+          <Popover id="my-popover-bottom" placement={`bottom${align}`}>
+            Bottom side
+          </Popover>
+          <Popover id="my-popover-left" placement={`left${align}`}>
+            Left side
+          </Popover>
+        </PopoverWrapper>
+      </div>
+    </>
+  );
+}}
+</Playground>
+
+## PopoverWrapper
+
+PopoverWrapper is an optional wrapper to make positioning of Popover even
+easier.
+
+By default, Popover is placed relative to the closest parent element with
+`position: relative` or `position: absolute`. Maybe you already have one of
+these in your CSS. PopoverWrapper is here for situations when you don't.
+
+```jsx
+<PopoverWrapper>
+  <Button
+    aria-describedby={isPopoverOpen ? 'my-popover' : undefined}
+    label="Want to see a popover? Click me!"
+    onClick={() => setIsPopoverOpen(!isPopoverOpen)}
+  />
+  {isPopoverOpen && <Popover id="my-popover">Hello there!</Popover>}
+</PopoverWrapper>
+```
+
+How do you know you may need PopoverWrapper?
+
+- You are **not** rendering Popover in a React portal.
+- You are using Popover in a complex layout and it does not pop up where you
+  need it.
+- You are using Floating UI with `absolute` positioning strategy (see
+  [Advanced Positioning](#advanced-positioning) below) and your Popover keeps to
+  be misplaced.
+- You have no idea what CSS `position` is and just want to get it working.
+
+To sum it up, usually you will need either PopoverWrapper around your content or
+`position: [ relative | absolute ]` somewhere in your CSS (but you never need
+both!). Nevertheless, in the simplest situations, like in a single-column page
+layout, you may not need either of these at all.
+
+Head to PopoverWrapper [API](#popoverwrapper-api) for all available options.
+
+## Advanced Positioning
+
+While the basic setup can be sufficient in some scenarios, dropping a Popover
+usually won't be so easy. To handle all tricky situations and edge cases
+automatically, including smart position updates to ensure Popover visibility,
+we recommend to involve an external library designed specifically for this
+purpose.
+
+ℹ️ The following example is using external library [Floating UI]. To use
+Floating UI, install it first:
+
+```shell
+npm install --save @floating-ui/react-dom
+```
+
+And import it along with Popover, e.g.:
+
+```js
+import {
+  useFloating,
+  autoUpdate,
+  flip,
+} from '@floating-ui/react-dom';
+import { Popover } from '@react-ui-org/react-ui';
+```
+
+As opposed to the [basic setup](#placement), Popover will be placed according to
+its triggering component (`reference`), but still recognizing the closest parent
+element with `position: relative` or `position: absolute` if there is any.
+
+Popover reacts on the `forwardedRef` option, necessary for advanced positioning:
+when `forwardedRef` is set, Popover resets its built-in positioning and relies
+on provided `style`.
+
+👉 Please consult [Floating UI] documentation to understand how it works and to
+get an idea of all possible cases you may need to cover.
+
+🖱 Try scrolling the example to see how Popover placement is updated.
+
+<Playground>
+  {() => {
+    const [isPopoverOpen, setIsPopoverOpen] = React.useState(false);
+    const [placement, setPlacement] = React.useState('top');
+    const {
+      x,
+      y,
+      reference,
+      floating,
+      placement: finalPlacement,
+      strategy,
+    } = useFloating({
+      placement,
+      middleware: [flip()],
+      whileElementsMounted: autoUpdate,
+    });
+    const placementOptions = [
+      'top',
+      'top-start',
+      'top-end',
+      'right',
+      'right-start',
+      'right-end',
+      'bottom',
+      'bottom-start',
+      'bottom-end',
+      'left',
+      'left-start',
+      'left-end',
+    ];
+    // All inline styles in this example EXCEPT Popover `style` are for
+    // demonstration purposes only.
+    return (
+      <>
+        <Toolbar>
+          <ToolbarItem>
+            <SelectField
+              label="Suggested placement:"
+              onChange={e => setPlacement(e.target.value)}
+              options={placementOptions.map((el) => ({
+                label: el,
+                value: el,
+              }))}
+              value={placement}
+            />
+          </ToolbarItem>
+          <ToolbarItem>
+            <div className="mb-2">Final placement:</div>
+            <code>{finalPlacement}</code>
+          </ToolbarItem>
+        </Toolbar>
+        <div
+          style={{
+            width: '40rem',
+            maxWidth: '100%',
+            height: '10rem',
+            overflow: 'auto',
+          }}
+        >
+          <div
+            style={{
+              position: 'relative',
+              width: '60rem',
+              height: '20rem',
+              paddingBlock: '7rem',
+              textAlign: 'center',
+            }}
+          >
+            <Button
+              aria-describedby={isPopoverOpen ? 'my-advanced-popover' : undefined}
+              forwardedRef={reference}
+              label="Trigger Popover"
+              onClick={() => setIsPopoverOpen(!isPopoverOpen)}
+            />
+            {isPopoverOpen && (
+              <Popover
+                forwardedRef={floating}
+                id="my-advanced-popover"
+                placement={finalPlacement}
+                style={{
+                  position: strategy,
+                  top: y ? y : '',
+                  left: x ? x : '',
+                }}
+              >
+                Auto-flipping Popover
+              </Popover>
+            )}
+          </div>
+        </div>
+      </>
+    );
+  }}
+</Playground>
+
+## API
+
+<Props table of={Popover} />
+
+### PopoverWrapper API
+
+<Props table of={PopoverWrapper} />
+
+## Theming
+
+| Custom Property                                      | Description                                                  |
+|------------------------------------------------------|--------------------------------------------------------------|
+| `--rui-Popover__width`                               | Popover width                                                |
+| `--rui-Popover__padding`                             | Popover padding                                              |
+| `--rui-Popover__border-width`                        | Border width                                                 |
+| `--rui-Popover__border-color`                        | Border color                                                 |
+| `--rui-Popover__border-radius`                       | Corner radius                                                |
+| `--rui-Popover__color`                               | Text color                                                   |
+| `--rui-Popover__background-color`                    | Background color                                             |
+| `--rui-Popover__box-shadow`                          | Popover box shadow                                           |
+
+[Floating UI]: https://floating-ui.com/docs/react-dom

package/src/lib/components/Popover/_helpers/getRootAlignmentClassName.js

@@ -0,0 +1,13 @@
+export default (placement, styles) => {
+  const alignment = placement.split('-')[1];
+
+  if (alignment === 'start') {
+    return styles.isRootAtStart;
+  }
+
+  if (alignment === 'end') {
+    return styles.isRootAtEnd;
+  }
+
+  return styles.isRootAtCenter;
+};

package/src/lib/components/Popover/_helpers/getRootSideClassName.js

@@ -0,0 +1,17 @@
+export default (placement, styles) => {
+  const side = placement.split('-')[0];
+
+  if (side === 'top') {
+    return styles.isRootAtTop;
+  }
+
+  if (side === 'right') {
+    return styles.isRootAtRight;
+  }
+
+  if (side === 'bottom') {
+    return styles.isRootAtBottom;
+  }
+
+  return styles.isRootAtLeft;
+};

package/src/lib/components/Popover/_theme.scss

@@ -0,0 +1,16 @@
+// 1. Height must be linked to width to create 90-degree angle.
+
+@use "sass:math";
+
+$width: var(--rui-Popover__width);
+$padding: var(--rui-Popover__padding);
+$border-width: var(--rui-Popover__border-width);
+$border-color: var(--rui-Popover__border-color);
+$border-radius: var(--rui-Popover__border-radius);
+$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-corner-offset: 0.75rem;

package/src/lib/components/Popover/index.js

@@ -0,0 +1,2 @@
+export { default as Popover } from './Popover';
+export { default as PopoverWrapper } from './PopoverWrapper';

package/src/lib/components/Radio/README.mdx

@@ -287,7 +287,7 @@ It's possible to disable just some options or the whole set.
 
 In addition to the options below, you can specify [React synthetic events] or
 any custom HTML attributes that do not interfere with the API, and they will be
-passed to the `input` HTML element. This enables making the component
+passed to the `<input>` HTML element. This enables making the component
 interactive and helps improve its accessibility.
 
 <Props table of={Radio} />

package/src/lib/components/Radio/Radio.jsx

@@ -1,9 +1,10 @@
 import PropTypes from 'prop-types';
 import React, { useContext } from 'react';
-import getRootValidationStateClassName from '../../helpers/getRootValidationStateClassName';
-import { resolveContextOrProp } from '../../helpers/resolveContextOrProp';
-import { withProviderContext } from '../../provider';
-import transferProps from '../../utils/transferProps';
+import { withGlobalProps } from '../../provider';
+import { classNames } from '../../utils/classNames';
+import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
+import { resolveContextOrProp } from '../_helpers/resolveContextOrProp';
+import { transferProps } from '../_helpers/transferProps';
 import { FormLayoutContext } from '../FormLayout';
 import styles from './Radio.scss';
 
@@ -25,23 +26,23 @@ export const Radio = ({
 
   return (
     <div
-      className={[
+      className={classNames(
         styles.root,
-        context ? styles.isRootInFormLayout : '',
+        context && styles.isRootInFormLayout,
         resolveContextOrProp(context && context.layout, layout) === 'horizontal'
           ? styles.rootLayoutHorizontal
           : styles.rootLayoutVertical,
-        disabled ? styles.isRootDisabled : '',
-        required ? styles.isRootRequired : '',
+        disabled && styles.isRootDisabled,
+        required && styles.isRootRequired,
         getRootValidationStateClassName(validationState, styles),
-      ].join(' ')}
+      )}
       id={id}
     >
       <div
-        className={[
+        className={classNames(
           styles.label,
-          isLabelVisible ? '' : styles.isLabelHidden,
-        ].join(' ')}
+          !isLabelVisible && styles.isLabelHidden,
+        )}
         id={id && `${id}__labelText`}
       >
         {label}
@@ -183,6 +184,6 @@ Radio.propTypes = {
   ]),
 };
 
-export const RadioWithContext = withProviderContext(Radio, 'Radio');
+export const RadioWithGlobalProps = withGlobalProps(Radio, 'Radio');
 
-export default RadioWithContext;
+export default RadioWithGlobalProps;

package/src/lib/components/Radio/Radio.scss

@@ -1,78 +1,78 @@
-@use '../../styles/tools/form-fields/box-field-elements';
-@use '../../styles/tools/form-fields/box-field-layout';
-@use '../../styles/tools/form-fields/foundation';
-@use '../../styles/tools/form-fields/inline-field-elements';
-@use '../../styles/tools/form-fields/inline-field-layout';
-@use '../../styles/tools/form-fields/variants';
-@use '../../styles/tools/accessibility';
-@use '../../styles/tools/reset';
-@use '../../styles/tools/spacing';
+@use "../../styles/tools/form-fields/box-field-elements";
+@use "../../styles/tools/form-fields/box-field-layout";
+@use "../../styles/tools/form-fields/foundation";
+@use "../../styles/tools/form-fields/inline-field-elements";
+@use "../../styles/tools/form-fields/inline-field-layout";
+@use "../../styles/tools/form-fields/variants";
+@use "../../styles/tools/accessibility";
+@use "../../styles/tools/reset";
+@use "../../styles/tools/spacing";
 
 // Foundation
 .root {
-  @include foundation.root();
-  @include variants.visual(check);
+    @include foundation.root();
+    @include variants.visual(check);
 }
 
 .label,
 .optionLabel {
-  @include foundation.label();
+    @include foundation.label();
 }
 
 .list {
-  @include reset.list();
+    @include reset.list();
 }
 
 .option {
-  @include inline-field-layout.field();
-  @include inline-field-elements.min-tap-target($type: radio);
+    @include inline-field-layout.field($type: radio);
+    @include inline-field-elements.min-tap-target($type: radio);
 }
 
 .input {
-  @include inline-field-elements.check-input($type: radio);
+    @include inline-field-elements.check-input($type: radio);
 }
 
 .helpText,
 .validationText {
-  @include foundation.help-text();
+    @include foundation.help-text();
 }
 
 .isRootRequired .label {
-  @include foundation.label-required();
+    @include foundation.label-required();
 }
 
 // States
 .isRootStateInvalid {
-  @include variants.validation(invalid);
+    @include variants.validation(invalid);
 }
 
 .isRootStateValid {
-  @include variants.validation(valid);
+    @include variants.validation(valid);
 }
 
 .isRootStateWarning {
-  @include variants.validation(warning);
+    @include variants.validation(warning);
 }
 
 // Invisible label
 .isLabelHidden {
-  @include accessibility.hide-text();
+    @include accessibility.hide-text();
 }
 
 // Layouts
 .rootLayoutVertical,
 .rootLayoutHorizontal {
-  @include box-field-layout.vertical($has-list: true);
+    @include box-field-layout.vertical($has-list: true);
 }
 
 .rootLayoutHorizontal {
-  @include box-field-layout.horizontal($has-min-tap-target: true);
+    @include box-field-layout.horizontal($has-min-tap-target: true);
 }
 
 .isRootFullWidth {
-  @include box-field-layout.full-width();
+    @include box-field-layout.full-width();
 }
 
 .isRootInFormLayout {
-  @include box-field-layout.in-form-layout();
+    @include box-field-layout.in-form-layout();
 }

package/src/lib/components/ScrollView/README.mdx

@@ -8,6 +8,9 @@ route: /components/scroll-view
 
 ScrollView makes long content scrollable.
 
+👉 Please note that HTML is rendered even when no children are provided.
+This is needed to allow the autoscroll feature to work.
+
 import {
   Playground,
   Props,
@@ -17,10 +20,7 @@ import Button from '../Button'
 import Radio from '../Radio'
 import { Toolbar } from '../Toolbar/Toolbar'
 import { ToolbarItem } from '../Toolbar/ToolbarItem'
-import {
-  ScrollViewWithContext as ScrollView,
-  ScrollView as ParsableScrollView,
-} from './ScrollView'
+import { ScrollView } from './ScrollView'
 
 ## Basic Usage
 
@@ -430,7 +430,7 @@ we use in the [Modal](/components/modal#scrolling-long-content) component.
 
 ## API
 
-<Props table of={ParsableScrollView} />
+<Props table of={ScrollView} />
 
 ## Theming