@react-ui-org/react-ui 0.51.0 → 0.52.0

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

@@ -0,0 +1,278 @@
+---
+name: InputGroup
+menu: 'Layouts'
+route: /components/input-group
+---
+
+# InputGroup
+
+InputGroup visually groups related form fields and actions together.
+
+import {
+  Playground,
+  Props,
+} from 'docz'
+import Icon from '../../../docs/_components/Icon'
+import {
+  Button,
+  InputGroup,
+  SelectField,
+  TextField,
+} from '../..'
+
+## Basic Usage
+
+To implement the InputGroup component, you need to import it first:
+
+```js
+import { InputGroup } from '@react-ui-org/react-ui';
+```
+
+And use it:
+
+<Playground>
+  {() => {
+    const [fruit, setFruit] = React.useState('apple');
+    const options = [
+      {
+        label: 'Apple',
+        value: 'apple',
+      },
+      {
+        label: 'Pear',
+        value: 'pear',
+      },
+      {
+        label: 'Cherry',
+        value: 'cherry',
+      },
+    ];
+    return (
+      <InputGroup label="Your favourite fruit">
+        <SelectField
+          label="Your favourite fruit"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+        />
+        <TextField
+          label="Variety"
+          placeholder="Eg. Golden delicious"
+        />
+        <Button label="Submit" />
+      </InputGroup>
+    );
+  }}
+</Playground>
+
+See [API](#api) for all available options.
+
+## General Guidelines
+
+- Use input group to group **related fields and actions** that a user can take.
+  Input fields and buttons should not be grouped just to save space on the
+  screen.
+
+- While the number of child inputs is not limited, keep in mind the layout of
+  InputGroup is currently **not responsive: the inputs do not shrink nor wrap**.
+  Make sure your inputs fit their container, especially on small screens.
+
+- In the background, InputGroup uses the [`fieldset`][fieldset] element. Not
+  only it improves the [accessibility] of the group, it also allows you to make
+  use of its built-in features like disabling all nested inputs or pairing the
+  group with a form outside. Consult [the MDN docs][fieldset] to learn more.
+
+- InputGroup currently **supports grouping of**
+  [TextField](/components/text-field), [SelectField](/components/select-field),
+  and [Button](/components/button) components.
+
+- To group [Buttons](/components/button) only, use the
+  [ButtonGroup](/components/button-group) component which is designed
+  specifically for that purpose.
+
+## Sizes
+
+All existing field and button sizes are also available on the input group level:
+small, medium, and large.
+
+<Playground>
+  <InputGroup
+    label="Small size"
+    size="small"
+  >
+    <TextField label="Input" />
+    <Button label="Submit" />
+  </InputGroup>
+  <InputGroup label="Medium size">
+    <TextField label="Input" />
+    <Button label="Submit" />
+  </InputGroup>
+  <InputGroup
+    label="Large size"
+    size="large"
+  >
+    <TextField label="Input" />
+    <Button label="Submit" />
+  </InputGroup>
+</Playground>
+
+### Shared Property
+
+You can set the `size` property directly on InputGroup to be shared for all
+fields and buttons inside the group. This property is then passed over to
+individual elements. At the same time, it **cannot be overridden** on the
+fields' or buttons' level. While technically possible, from the design point of
+view it's undesirable to group elements of totally different types or sizes.
+
+## Invisible Label
+
+In some cases, it may be convenient to visually hide the group label. The label
+remains accessible to assistive technologies. Labels of individual inputs are
+always visually hidden.
+
+While it may be acceptable for login screens with just a few fields or for other
+simple forms, it's dangerous to hide labels from users in most cases. Keep in
+mind you should **provide another visual clue** so users know what to fill into
+the input.
+
+<Playground>
+  <InputGroup
+    isLabelVisible={false}
+    label="First and last name"
+  >
+    <TextField
+      label="First name"
+      placeholder="Eg. John"
+    />
+    <TextField
+      label="Last name"
+      placeholder="Eg. Doe"
+    />
+    <Button label="Submit" />
+  </InputGroup>
+</Playground>
+
+## Horizontal layout
+
+The default vertical layout is very easy to use and work with. However, there
+are situations where horizontal layout suits better — and that's why React UI
+supports this kind of layout as well.
+
+<Playground>
+  <InputGroup
+    label="Horizontal layout"
+    layout="horizontal"
+  >
+    <TextField label="Label" />
+    <Button label="Submit" />
+  </InputGroup>
+</Playground>
+
+## States
+
+### Disabled State
+
+Disables all fields and buttons inside the group.
+
+<Playground>
+  <InputGroup disabled label="Disabled group">
+    <TextField label="Label" />
+    <Button label="Submit" />
+  </InputGroup>
+</Playground>
+
+### Validation States
+
+Validation states visually present the result of validation of the grouped
+inputs. Input group's validation state is taken from its child inputs. You
+should always **provide validation messages for states other than valid**
+directly through `validationTexts` prop so users know what happened and what
+action they should take or what options they have. These messages are not
+semantically tied to the `children` elements, the connection should be expressed
+in textual form in the actual message. The individual `children` elements must
+not show any `validationText`, they only show their respective `validationState`.
+Validation messages passed to input elements' `validationText` prop will be
+ignored.
+
+<Playground>
+  <InputGroup
+    label="First and last name"
+    validationTexts={[
+      "First name must be filled in.",
+      "Last name must be filled in.",
+    ]}
+  >
+    <TextField
+      label="First name"
+      placeholder="Eg. John"
+      validationState="invalid"
+    />
+    <TextField
+      label="Last name"
+      placeholder="Eg. Doe"
+      validationState="invalid"
+    />
+    <Button label="Submit" />
+  </InputGroup>
+  <InputGroup
+    label="First and last name"
+    validationTexts={[
+      "Last name should not include any digits.",
+    ]}
+  >
+    <TextField
+      label="First name"
+      placeholder="Eg. John"
+      value="John"
+    />
+    <TextField
+      label="Last name"
+      placeholder="Eg. Doe"
+      validationState="warning"
+      value="123Doe"
+    />
+    <Button label="Submit" />
+  </InputGroup>
+  <InputGroup label="First and last name">
+    <TextField
+      label="First name"
+      placeholder="Eg. John"
+      validationState="valid"
+      value="John"
+    />
+    <TextField
+      label="Last name"
+      placeholder="Eg. Doe"
+      validationState="valid"
+      value="Doe"
+    />
+    <Button label="Submit" />
+  </InputGroup>
+</Playground>
+
+## Forwarding HTML Attributes
+
+In addition to the options below in the [component's API](#api) section, you
+can specify [React synthetic events] or **any HTML attribute you like.** All
+attributes that don't interfere with the API are forwarded to the `<div>` HTML
+element which wraps elements to be grouped. This enables making the component
+interactive and helps to improve its accessibility.
+
+👉 Refer to the MDN reference for the full list of supported attributes of the
+[div] element.
+
+## API
+
+<Props table of={InputGroup} />
+
+## Theming
+
+| Custom Property                                                    | Description                                    |
+|--------------------------------------------------------------------|------------------------------------------------|
+| `--rui-InputGroup__gap`                                            | Gap between elements                           |
+| `--rui-InputGroup__inner-border-radius`                            | Inner border radius of elements                |
+
+[fieldset]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset
+[accessibility]: https://www.w3.org/WAI/tutorials/forms/grouping/
+[React synthetic events]: https://reactjs.org/docs/events.html
+[div]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div#attributes

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

@@ -0,0 +1,2 @@
+$gap: var(--rui-InputGroup__gap);
+$inner-border-radius: var(--rui-InputGroup__inner-border-radius);

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

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

package/src/lib/components/Modal/Modal.jsx

@@ -1,12 +1,13 @@
 import PropTypes from 'prop-types';
-import React, {
-  useEffect,
-  useRef,
-} from 'react';
+import React, { useRef } from 'react';
 import { createPortal } from 'react-dom';
 import { withGlobalProps } from '../../provider';
 import { transferProps } from '../_helpers/transferProps';
 import { classNames } from '../../utils/classNames';
+import { getPositionClassName } from './_helpers/getPositionClassName';
+import { getSizeClassName } from './_helpers/getSizeClassName';
+import { useModalFocus } from './_hooks/useModalFocus';
+import { useModalScrollPrevention } from './_hooks/useModalScrollPrevention';
 import styles from './Modal.scss';
 
 const preRender = (
@@ -16,63 +17,34 @@ const preRender = (
   position,
   restProps,
   size,
-) => {
-  const sizeClass = (modalSize) => {
-    if (modalSize === 'small') {
-      return styles.isRootSizeSmall;
-    }
-
-    if (modalSize === 'medium') {
-      return styles.isRootSizeMedium;
-    }
-
-    if (modalSize === 'large') {
-      return styles.isRootSizeLarge;
-    }
-
-    if (modalSize === 'fullscreen') {
-      return styles.isRootSizeFullscreen;
-    }
-
-    return styles.isRootSizeAuto;
-  };
-
-  const positionClass = (modalPosition) => {
-    if (modalPosition === 'top') {
-      return styles.isRootPositionTop;
-    }
-
-    return styles.isRootPositionCenter;
-  };
-
-  return (
+) => (
+  <div
+    className={styles.backdrop}
+    onClick={(e) => {
+      e.preventDefault();
+      if (closeButtonRef?.current != null) {
+        closeButtonRef.current.click();
+      }
+    }}
+    role="presentation"
+  >
     <div
-      className={styles.backdrop}
-      onClick={() => {
-        if (closeButtonRef?.current != null) {
-          closeButtonRef.current.click();
-        }
+      {...transferProps(restProps)}
+      className={classNames(
+        styles.root,
+        getSizeClassName(size, styles),
+        getPositionClassName(position, styles),
+      )}
+      onClick={(e) => {
+        e.stopPropagation();
       }}
       role="presentation"
+      ref={childrenWrapperRef}
     >
-      <div
-        {...transferProps(restProps)}
-        className={classNames(
-          styles.root,
-          sizeClass(size),
-          positionClass(position),
-        )}
-        onClick={(e) => {
-          e.stopPropagation();
-        }}
-        role="presentation"
-        ref={childrenWrapperRef}
-      >
-        {children}
-      </div>
+      {children}
     </div>
-  );
-};
+  </div>
+);
 
 export const Modal = ({
   autoFocus,
@@ -80,52 +52,21 @@ export const Modal = ({
   closeButtonRef,
   portalId,
   position,
+  preventScrollUnderneath,
   primaryButtonRef,
   size,
   ...restProps
 }) => {
   const childrenWrapperRef = useRef();
 
-  const keyPressHandler = (e) => {
-    if (e.key === 'Escape' && closeButtonRef?.current != null) {
-      closeButtonRef.current.click();
-    }
-
-    if (e.key === 'Enter' && e.target.nodeName !== 'BUTTON' && primaryButtonRef?.current != null) {
-      primaryButtonRef.current.click();
-    }
-  };
-
-  useEffect(() => {
-    window.document.addEventListener('keydown', keyPressHandler, false);
-    const removeKeyPressHandler = () => {
-      window.document.removeEventListener('keydown', keyPressHandler, false);
-    };
-
-    // If `autoFocus` is set to `true`, following code finds first form field element
-    // (input, textarea or select) or primary button and auto focuses it. This is necessary
-    // to have focus on one of those elements to be able to submit form by pressing Enter key.
-    if (autoFocus) {
-      if (childrenWrapperRef?.current != null) {
-        const childrenWrapperElement = childrenWrapperRef.current;
-        const childrenElements = childrenWrapperElement.querySelectorAll('*');
-        const formFieldEl = Array.from(childrenElements).find(
-          (element) => ['INPUT', 'TEXTAREA', 'SELECT'].includes(element.nodeName) && !element.disabled,
-        );
-
-        if (formFieldEl) {
-          formFieldEl.focus();
-          return removeKeyPressHandler;
-        }
-      }
-
-      if (primaryButtonRef?.current != null) {
-        primaryButtonRef.current.focus();
-      }
-    }
+  useModalFocus(
+    autoFocus,
+    childrenWrapperRef,
+    primaryButtonRef,
+    closeButtonRef,
+  );
 
-    return removeKeyPressHandler;
-  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+  useModalScrollPrevention(preventScrollUnderneath);
 
   if (portalId === null) {
     return preRender(
@@ -157,14 +98,16 @@ Modal.defaultProps = {
   closeButtonRef: null,
   portalId: null,
   position: 'center',
+  preventScrollUnderneath: 'default',
   primaryButtonRef: null,
   size: 'medium',
 };
 
 Modal.propTypes = {
   /**
-   * If `true`, focus the first input element in the modal or primary button (referenced by the `primaryButtonRef` prop)
-   * when the modal is opened.
+   * If `true`, focus the first input element in the `Modal`, or primary button (referenced by the `primaryButtonRef`
+   * prop), or other focusable element when the `Modal` is opened. If there are none or `autoFocus` is set to `false`,
+   * focus the Modal itself.
    */
   autoFocus: PropTypes.bool,
   /**
@@ -192,6 +135,24 @@ Modal.propTypes = {
    * Vertical position of the modal inside browser window.
    */
   position: PropTypes.oneOf(['top', 'center']),
+  /**
+   * Mode in which Modal prevents scroll of elements bellow:
+   * * `default` - Modal prevents scroll on the `body` element
+   * * `off` - Modal does not prevent any scroll
+   * * object
+   * * * `reset` - method called on Modal's unmount to reset scroll prevention
+   * * * `start` - method called on Modal's mount to custom scroll prevention
+   */
+  preventScrollUnderneath: PropTypes.oneOfType([
+    PropTypes.oneOf([
+      'default',
+      'off',
+    ]),
+    PropTypes.shape({
+      reset: PropTypes.func,
+      start: PropTypes.func,
+    }),
+  ]),
   /**
    * Reference to primary button element. It is used to submit modal when Enter key is pressed and as fallback
    * when `autoFocus` functionality does not find any input element to be focused.