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

package/src/lib/components/InputGroup/InputGroup.jsx

@@ -0,0 +1,170 @@
+import PropTypes from 'prop-types';
+import React, { useContext } from 'react';
+import { Text } from '../Text';
+import { withGlobalProps } from '../../provider';
+import { classNames } from '../../utils/classNames';
+import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
+import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
+import { isChildrenEmpty } from '../_helpers/isChildrenEmpty';
+import { resolveContextOrProp } from '../_helpers/resolveContextOrProp';
+import { transferProps } from '../_helpers/transferProps';
+import { FormLayoutContext } from '../FormLayout';
+import { InputGroupContext } from './InputGroupContext';
+import styles from './InputGroup.scss';
+
+export const InputGroup = ({
+  children,
+  disabled,
+  id,
+  isLabelVisible,
+  label,
+  layout,
+  size,
+  validationTexts,
+  ...restProps
+}) => {
+  const formLayoutContext = useContext(FormLayoutContext);
+
+  if (isChildrenEmpty(children)) {
+    return null;
+  }
+
+  const validationState = children.reduce(
+    (state, child) => {
+      if (state === 'invalid' || (state === 'warning' && child.props.validationState === 'valid')) {
+        return state;
+      }
+      return child.props.validationState ?? state;
+    },
+    null,
+  );
+
+  return (
+    <fieldset
+      {...transferProps(restProps)}
+      id={id}
+      className={classNames(
+        styles.root,
+        formLayoutContext && styles.isRootInFormLayout,
+        resolveContextOrProp(formLayoutContext && formLayoutContext.layout, layout) === 'horizontal'
+          ? styles.isRootLayoutHorizontal
+          : styles.isRootLayoutVertical,
+        disabled && styles.isRootDisabled,
+        getRootSizeClassName(size, styles),
+        getRootValidationStateClassName(validationState, styles),
+      )}
+      disabled={disabled}
+    >
+      <legend
+        className={styles.legend}
+        id={id && `${id}__label`}
+      >
+        {label}
+      </legend>
+      <div
+        aria-hidden
+        className={classNames(
+          styles.label,
+          !isLabelVisible && styles.isLabelHidden,
+        )}
+        id={id && `${id}__displayLabel`}
+      >
+        {label}
+      </div>
+      <div className={styles.field}>
+        <div
+          className={styles.inputGroup}
+          id={id && `${id}__group`}
+        >
+          <InputGroupContext.Provider
+            value={{
+              disabled,
+              layout,
+              size,
+            }}
+          >
+            {children}
+          </InputGroupContext.Provider>
+        </div>
+        {validationTexts && (
+          <ul
+            className={styles.validationText}
+            id={id && `${id}__validationTexts`}
+          >
+            {validationTexts.map((validationText) => (
+              <li key={validationText}>
+                <Text blockLevel>
+                  {validationText}
+                </Text>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </fieldset>
+  );
+};
+
+InputGroup.defaultProps = {
+  children: null,
+  disabled: false,
+  id: undefined,
+  isLabelVisible: true,
+  layout: 'vertical',
+  size: 'medium',
+  validationTexts: null,
+};
+
+InputGroup.propTypes = {
+  /**
+   * Supported elements to be grouped:
+   * * `Button`
+   * * `SelectField`
+   * * `TextField`
+   *
+   * If none are provided nothing is rendered.
+   */
+  children: PropTypes.node,
+  /**
+   * If `true`, the whole input group with all nested inputs and buttons will be disabled.
+   */
+  disabled: PropTypes.bool,
+  /**
+   * ID of the root HTML element.
+   *
+   * Also serves as base for ids of nested elements:
+   * * `<ID>__label`
+   * * `<ID>__displayLabel`
+   * * `<ID>__group`
+   * * `<ID>__validationTexts`
+   */
+  id: PropTypes.string,
+  /**
+   * If `false`, the label will be visually hidden (but remains accessible by assistive
+   * technologies).
+   */
+  isLabelVisible: PropTypes.bool,
+  /**
+   * Input group label.
+   */
+  label: PropTypes.string.isRequired,
+  /**
+   * Layout of the group.
+   *
+   * Ignored if the component is rendered within `FormLayout` component
+   * as the value is inherited in such case.
+   */
+  layout: PropTypes.oneOf(['horizontal', 'vertical']),
+  /**
+   * Size of the `children` elements.
+   */
+  size: PropTypes.oneOf(['small', 'medium', 'large']),
+  /**
+   * An array of validation messages to be displayed.
+   */
+  validationTexts: PropTypes.node,
+};
+
+export const InputGroupWithGlobalProps = withGlobalProps(InputGroup, 'InputGroup');
+
+export default InputGroupWithGlobalProps;

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

@@ -0,0 +1,92 @@
+// 1. The class name is intentionally singular because it's targeted by other mixins too.
+// 2. Use a block-level display mode to prevent extra white space below grouped inputs in Safari.
+// 3. Prevent individual inputs from overlapping inside narrow containers.
+// 4. Legends are tricky to style, let's use a `div` instead.
+//    https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset#styling_with_css
+
+@use "../../styles/tools/form-fields/box-field-elements";
+@use "../../styles/tools/form-fields/box-field-layout";
+@use "../../styles/tools/form-fields/box-field-sizes";
+@use "../../styles/tools/form-fields/foundation";
+@use "../../styles/tools/form-fields/variants";
+@use "../../styles/tools/accessibility";
+@use "../../styles/tools/reset";
+@use "theme";
+
+.root {
+    @include foundation.root();
+    @include foundation.fieldset();
+}
+
+// 4.
+.legend {
+    @include accessibility.hide-text();
+}
+
+// 4.
+.label {
+    @include foundation.label();
+}
+
+.inputGroup {
+    --rui-local-inner-border-radius: #{theme.$inner-border-radius};
+
+    display: flex; // 2.
+    gap: theme.$gap;
+}
+
+// 1.
+.validationText {
+    @include reset.list();
+    @include foundation.help-text();
+}
+
+// States
+.isRootStateInvalid {
+    @include variants.validation(invalid);
+}
+
+.isRootStateValid {
+    @include variants.validation(valid);
+}
+
+.isRootStateWarning {
+    @include variants.validation(warning);
+}
+
+// Invisible label
+.isLabelHidden {
+    @include accessibility.hide-text();
+}
+
+// Layouts
+.isRootLayoutVertical,
+.isRootLayoutHorizontal {
+    @include box-field-layout.vertical();
+}
+
+.isRootLayoutVertical .field,
+.isRootLayoutHorizontal .field {
+    max-width: none; // 3.
+}
+
+.isRootLayoutHorizontal {
+    @include box-field-layout.horizontal();
+}
+
+.isRootInFormLayout {
+    @include box-field-layout.in-form-layout($is-fieldset: true);
+}
+
+// Sizes
+.isRootSizeSmall {
+    @include box-field-sizes.size(small, $has-input: false);
+}
+
+.isRootSizeMedium {
+    @include box-field-sizes.size(medium, $has-input: false);
+}
+
+.isRootSizeLarge {
+    @include box-field-sizes.size(large, $has-input: false);
+}

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

@@ -0,0 +1,3 @@
+import React from 'react';
+
+export const InputGroupContext = React.createContext(null);

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';