@react-ui-org/react-ui 0.46.0 → 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/Radio.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React, { useContext } from 'react';
-import { withProviderContext } from '../../provider';
+import { withGlobalProps } from '../../provider';
 import { classNames } from '../../utils/classNames';
 import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
 import { resolveContextOrProp } from '../_helpers/resolveContextOrProp';
@@ -184,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/ScrollView/README.mdx

@@ -20,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
 
@@ -433,7 +430,7 @@ we use in the [Modal](/components/modal#scrolling-long-content) component.
 
 ## API
 
-<Props table of={ParsableScrollView} />
+<Props table of={ScrollView} />
 
 ## Theming
 

package/src/lib/components/ScrollView/ScrollView.jsx

@@ -1,11 +1,15 @@
 import PropTypes from 'prop-types';
 import React, {
+  useContext,
   useEffect,
   useLayoutEffect,
   useRef,
   useState,
 } from 'react';
-import { withProviderContext } from '../../provider';
+import {
+  RUIContext,
+  withGlobalProps,
+} from '../../provider';
 import { classNames } from '../../utils/classNames';
 import { getElementsPositionDifference } from './_helpers/getElementsPositionDifference';
 import { useLoadResize } from './_hooks/useLoadResizeHook';
@@ -34,9 +38,10 @@ export const ScrollView = (props) => {
     scrollbar,
     shadowColor,
     shadowSize,
-    translations,
   } = props;
 
+  const { translations } = useContext(RUIContext);
+
   const [isAutoScrollInProgress, setIsAutoScrollInProgress] = useState(false);
   const [isScrolledAtStart, setIsScrolledAtStart] = useState(false);
   const [isScrolledAtEnd, setIsScrolledAtEnd] = useState(false);
@@ -237,7 +242,7 @@ export const ScrollView = (props) => {
               'prev',
               arrowsScrollStep,
             )}
-            title={translations.previous}
+            title={translations.ScrollView.previous}
             id={id && `${id}__arrowPrevButton`}
           >
             {customPrevArrow || (
@@ -254,7 +259,7 @@ export const ScrollView = (props) => {
               'next',
               arrowsScrollStep,
             )}
-            title={translations.next}
+            title={translations.ScrollView.next}
             id={id && `${id}__arrowNextButton`}
           >
             {customNextArrow || (
@@ -374,15 +379,8 @@ ScrollView.propTypes = {
    * mode.
    */
   shadowSize: PropTypes.string,
-  /**
-   * Translations required by the component.
-   */
-  translations: PropTypes.shape({
-    next: PropTypes.string.isRequired,
-    previous: PropTypes.string.isRequired,
-  }).isRequired,
 };
 
-export const ScrollViewWithContext = withProviderContext(ScrollView, 'ScrollView');
+export const ScrollViewWithGlobalProps = withGlobalProps(ScrollView, 'ScrollView');
 
-export default ScrollViewWithContext;
+export default ScrollViewWithGlobalProps;

package/src/lib/components/SelectField/SelectField.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React, { useContext } from 'react';
-import { withProviderContext } from '../../provider';
+import { withGlobalProps } from '../../provider';
 import { classNames } from '../../utils/classNames';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
 import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
@@ -215,6 +215,6 @@ SelectField.propTypes = {
   variant: PropTypes.oneOf(['filled', 'outline']),
 };
 
-export const SelectFieldWithContext = withForwardedRef(withProviderContext(SelectField, 'SelectField'));
+export const SelectFieldWithGlobalProps = withForwardedRef(withGlobalProps(SelectField, 'SelectField'));
 
-export default SelectFieldWithContext;
+export default SelectFieldWithGlobalProps;

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

@@ -77,7 +77,7 @@ See [API](#api) for all available options.
 
 - Tables are **good for displaying complex tabular data.** For simpler data sets
   or even plain key-value pairs, consider using the
-  [List](/components/list) component.
+  [Grid](/components/grid) component.
 
 - Tables make **lots of information easier to scan and compare.** If you have
   fewer sections and want to emphasize each group more, consider using

package/src/lib/components/Table/Table.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../provider';
+import { withGlobalProps } from '../../provider';
 import Button from '../Button';
 import styles from './Table.scss';
 
@@ -145,6 +145,6 @@ Table.propTypes = {
   }),
 };
 
-export const TableWithContext = withProviderContext(Table, 'Table');
+export const TableWithGlobalProps = withGlobalProps(Table, 'Table');
 
-export default TableWithContext;
+export default TableWithGlobalProps;

package/src/lib/components/Tabs/Tabs.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../provider';
+import { withGlobalProps } from '../../provider';
 import styles from './Tabs.scss';
 
 export const Tabs = ({
@@ -33,6 +33,6 @@ Tabs.propTypes = {
   id: PropTypes.string,
 };
 
-export const TabsWithContext = withProviderContext(Tabs, 'Tabs');
+export const TabsWithGlobalProps = withGlobalProps(Tabs, 'Tabs');
 
-export default TabsWithContext;
+export default TabsWithGlobalProps;

package/src/lib/components/Tabs/TabsItem.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../provider';
+import { withGlobalProps } from '../../provider';
 import { classNames } from '../../utils/classNames';
 import styles from './TabsItem.scss';
 
@@ -83,6 +83,6 @@ TabsItem.propTypes = {
   onClick: PropTypes.func,
 };
 
-export const TabsItemWithContext = withProviderContext(TabsItem, 'TabsItem');
+export const TabsItemWithGlobalProps = withGlobalProps(TabsItem, 'TabsItem');
 
-export default TabsItemWithContext;
+export default TabsItemWithGlobalProps;

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

@@ -154,7 +154,7 @@ will override automatic break point selection in `auto` mode when present.
               <span id="word-wrapping-options-label">Word wrapping:</span>
             </ToolbarItem>
             <ToolbarItem>
-              <ButtonGroup aria-labelledby="#word-wrapping-options-label">
+              <ButtonGroup aria-labelledby="word-wrapping-options-label">
                 <Button
                   color={wordWrapping === 'normal' ? 'dark' : 'primary'}
                   label="normal"
@@ -178,7 +178,7 @@ will override automatic break point selection in `auto` mode when present.
               <span id="hyphens-options-label">Hyphens:</span>
             </ToolbarItem>
             <ToolbarItem>
-              <ButtonGroup aria-labelledby="#hyphens-options-label">
+              <ButtonGroup aria-labelledby="hyphens-options-label">
                 <Button
                   color={hyphens === 'none' ? 'dark' : 'primary'}
                   label="none"

package/src/lib/components/Text/Text.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withProviderContext } from '../../provider';
+import { withGlobalProps } from '../../provider';
 import { classNames } from '../../utils/classNames';
 import { isChildrenEmpty } from '../_helpers/isChildrenEmpty';
 import { getRootClampClassName } from './_helpers/getRootClampClassName';
@@ -75,6 +75,6 @@ Text.propTypes = {
   wordWrapping: PropTypes.oneOf(['normal', 'long-words', 'anywhere']),
 };
 
-export const TextWithContext = withProviderContext(Text, 'Text');
+export const TextWithGlobalProps = withGlobalProps(Text, 'Text');
 
-export default TextWithContext;
+export default TextWithGlobalProps;

package/src/lib/components/TextArea/TextArea.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React, { useContext } from 'react';
-import { withProviderContext } from '../../provider';
+import { withGlobalProps } from '../../provider';
 import { classNames } from '../../utils/classNames';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
 import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
@@ -202,6 +202,6 @@ TextArea.propTypes = {
   variant: PropTypes.oneOf(['filled', 'outline']),
 };
 
-export const TextAreaWithContext = withForwardedRef(withProviderContext(TextArea, 'TextArea'));
+export const TextAreaWithGlobalProps = withForwardedRef(withGlobalProps(TextArea, 'TextArea'));
 
-export default TextAreaWithContext;
+export default TextAreaWithGlobalProps;