@react-ui-org/react-ui 0.57.0 → 0.58.0

package/src/components/Radio/Radio.module.scss

@@ -52,6 +52,10 @@
         @include foundation.label-required();
     }
 
+    .isRootRequired .optionLabel {
+        @include foundation.label-required($show-require-sign: false);
+    }
+
     // States
     .isRootStateInvalid {
         @include variants.validation(invalid);

package/src/components/ScrollView/ScrollView.jsx

@@ -6,10 +6,8 @@ import React, {
   useRef,
   useState,
 } from 'react';
-import {
-  RUIContext,
-  withGlobalProps,
-} from '../../provider';
+import { TranslationsContext } from '../../providers/translations';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { getElementsPositionDifference } from './_helpers/getElementsPositionDifference';
@@ -48,7 +46,7 @@ export const ScrollView = React.forwardRef((props, ref) => {
     ...restProps
   } = props;
 
-  const { translations } = useContext(RUIContext);
+  const translations = useContext(TranslationsContext);
 
   const [isAutoScrollInProgress, setIsAutoScrollInProgress] = useState(false);
   const [isScrolledAtStart, setIsScrolledAtStart] = useState(false);

package/src/components/SelectField/README.md

@@ -592,6 +592,109 @@ React.createElement(() => {
 })
 ```
 
+### Required State
+
+The required state indicates that the input is mandatory.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fruit, setFruit] = React.useState('apple');
+  return (
+    <SelectField
+      label="Your favourite fruit"
+      onChange={(e) => setFruit(e.target.value)}
+      options={[
+        {
+          label: 'Apple',
+          value: 'apple',
+        },
+        {
+          label: 'Banana',
+          value: 'banana',
+        },
+        {
+          label: 'Grapefruit',
+          value: 'grapefruit',
+        },
+      ]}
+      value={fruit}
+      required
+    />
+  );
+});
+```
+
+#### Styling the Required State
+
+All form fields in React UI can be
+[styled](/docs/customize/theming/forms/#required-state)
+to indicate the required state.
+
+However, you may find yourself in a situation where a form field is valid in
+both selected and unselected states, for example to turn on or off a feature.
+If your project uses the label color as the primary means to indicate the
+required state of input fields and the usual asterisk `*` is omitted, you may
+want to keep the label color consistent for both states to avoid confusion.
+
+For this edge case, there is the `renderAsRequired` prop:
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fruit, setFruit] = React.useState('apple');
+  const options = [
+    {
+      label: 'Apple',
+      value: 'apple',
+    },
+    {
+      label: 'Banana',
+      value: 'banana',
+    },
+    {
+      label: 'Grapefruit',
+      value: 'grapefruit',
+    },
+  ];
+  return (
+   <React.Fragment>
+      <style>
+      {`
+        .example {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 1rem 0.5rem;
+        }
+
+        .example--themed-form-fields {
+          --rui-FormField__label__color: var(--rui-color-text-secondary);
+          --rui-FormField--required__label__color: var(--rui-color-text-primary);
+          --rui-FormField--required__sign: '';
+        }
+      `}
+      </style>
+      <div class="example example--themed-form-fields">
+      <SelectField
+          label="This field is optional"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+        />
+        <SelectField
+          label="This field is optional but looks like required"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+          renderAsRequired
+        />
+      </div>
+    </React.Fragment>
+  );
+});
+```
+
+It renders the field as if it was required, but doesn't add the `required`
+attribute to the actual input.
+
 ### Disabled State
 
 It's possible to disable just some options or the whole input.

package/src/components/SelectField/SelectField.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React, { useContext } from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
@@ -21,6 +21,7 @@ export const SelectField = React.forwardRef((props, ref) => {
     label,
     layout,
     options,
+    renderAsRequired,
     required,
     size,
     validationState,
@@ -43,7 +44,7 @@ export const SelectField = React.forwardRef((props, ref) => {
           ? styles.isRootLayoutHorizontal
           : styles.isRootLayoutVertical,
         inputGroupContext && styles.isRootGrouped,
-        required && styles.isRootRequired,
+        (renderAsRequired || required) && styles.isRootRequired,
         getRootSizeClassName(
           resolveContextOrProp(inputGroupContext && inputGroupContext.size, size),
           styles,
@@ -136,6 +137,7 @@ SelectField.defaultProps = {
   id: undefined,
   isLabelVisible: true,
   layout: 'vertical',
+  renderAsRequired: false,
   required: false,
   size: 'medium',
   validationState: null,
@@ -227,7 +229,11 @@ SelectField.propTypes = {
     })),
   ]).isRequired,
   /**
-   * If `true`, the input will be required.
+   * If `true`, the input will be rendered as if it was required.
+   */
+  renderAsRequired: PropTypes.bool,
+  /**
+   * If `true`, the input will be made and rendered as required, regardless of the `renderAsRequired` prop.
    */
   required: PropTypes.bool,
   /**

package/src/components/Table/Table.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { transferProps } from '../../utils/transferProps';
 import { TableHeaderCell } from './_components/TableHeaderCell';
 import { TableBodyCell } from './_components/TableBodyCell';

package/src/components/Tabs/Tabs.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { transferProps } from '../../utils/transferProps';
 import styles from './Tabs.module.scss';
 

package/src/components/Tabs/TabsItem.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import styles from './TabsItem.module.scss';

package/src/components/Text/Text.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { isChildrenEmpty } from '../_helpers/isChildrenEmpty';

package/src/components/TextArea/TextArea.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React, { useContext } from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';

package/src/components/TextField/README.md

@@ -388,7 +388,13 @@ have.
   label="User name"
   onChange={() => {}}
   validationState="warning"
-  validationText="Account with this name already exists, pick a different one."
+  validationText={(
+    <>
+      Account with this name already exists, pick a different one.
+      {' '}
+      <TextLink href="#" label="Forgot your password?" />
+    </>
+  )}
   value="joe"
   required
 />
@@ -411,7 +417,13 @@ have.
   label="User name"
   onChange={() => {}}
   validationState="warning"
-  validationText="Account with this name already exists, pick a different one."
+  validationText={(
+    <>
+      Account with this name already exists, pick a different one.
+      {' '}
+      <TextLink href="#" label="Forgot your password?" />
+    </>
+  )}
   variant="filled"
   value="joe"
   required

package/src/components/TextField/TextField.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React, { useContext } from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';

package/src/components/TextLink/README.md

@@ -64,13 +64,20 @@ helps to improve its accessibility.
 
 ## Theming
 
+ℹ️ The TextLink component is context-aware and can inherit text color from its
+parent component. This applies for components using
+[Feedback color collection](/docs/foundation/collections#colors) and for
+components in any of the supported
+[validation states](/docs/foundation/colors#validation-states).
+In such cases, the custom properties marked with an asterisk (\*) are ignored.
+
 | Custom Property                           | Description                         |
 |-------------------------------------------|-------------------------------------|
-| `--rui-TextLink__color`                   | Text color                          |
+| `--rui-TextLink__color` \*                | Text color                          |
 | `--rui-TextLink__text-decoration`         | Text decoration, e.g. underline     |
-| `--rui-TextLink--hover__color`            | Text color on hover                 |
+| `--rui-TextLink--hover__color` \*         | Text color on hover                 |
 | `--rui-TextLink--hover__text-decoration`  | Text decoration on hover            |
-| `--rui-TextLink--active__color`           | Text color in the active state      |
+| `--rui-TextLink--active__color` \*        | Text color in the active state      |
 | `--rui-TextLink--active__text-decoration` | Text decoration in the active state |
 
 [a-attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes

package/src/components/TextLink/TextLink.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { transferProps } from '../../utils/transferProps';
 import styles from './TextLink.module.scss';
 

package/src/components/TextLink/_theme.scss

@@ -1,6 +1,6 @@
-$color: var(--rui-TextLink__color);
+$color: var(--rui-local-link-color, var(--rui-TextLink__color));
 $text-decoration: var(--rui-TextLink__text-decoration);
-$hover-color: var(--rui-TextLink--hover__color);
+$hover-color: var(--rui-local-link-color-hover, var(--rui-TextLink--hover__color));
 $hover-text-decoration: var(--rui-TextLink--hover__text-decoration);
-$active-color: var(--rui-TextLink--active__color);
+$active-color: var(--rui-local-link-color-active, var(--rui-TextLink--active__color));
 $active-text-decoration: var(--rui-TextLink--active__text-decoration);

package/src/components/Toggle/README.md

@@ -148,13 +148,95 @@ React.createElement(() => {
         label="Listen in studio quality"
         onChange={() => setStudioQuality(!studioQuality)}
         validationState="invalid"
-        validationText="Please upgrade your plan to make this option available."
+        validationText={(
+          <>
+            Please
+            {' '}
+            <TextLink href="#" label="upgrade your plan" />
+            {' '}
+            to make this option available.
+          </>
+        )}
       />
     </>
   );
 });
 ```
 
+### Required State
+
+The required state indicates that the input is mandatory.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [studioQuality, setStudioQuality] = React.useState(true);
+  return (
+    <Toggle
+      checked={studioQuality}
+      label="Listen in studio quality"
+      onChange={() => setStudioQuality(!studioQuality)}
+      required
+    />
+  );
+});
+```
+
+#### Styling the Required State
+
+All form fields in React UI can be
+[styled](/docs/customize/theming/forms/#required-state)
+to indicate the required state.
+
+However, you may find yourself in a situation where a form field is valid in
+both checked and unchecked states, for example to turn on or off a feature.
+If your project uses the label color as the primary means to indicate the
+required state of input fields and the usual asterisk `*` is omitted, you may
+want to keep the label color consistent for both states to avoid confusion.
+
+For this edge case, there is the `renderAsRequired` prop:
+
+```docoff-react-preview
+React.createElement(() => {
+  const [optional, setOptional] = React.useState(false);
+  const [renderAsRequired, setRenderAsRequired] = React.useState(false);
+  return (
+    <React.Fragment>
+      <style>
+      {`
+        .example {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 1rem 0.5rem;
+        }
+
+        .example--themed-form-fields {
+          --rui-FormField__label__color: var(--rui-color-text-secondary);
+          --rui-FormField--required__label__color: var(--rui-color-text-primary);
+          --rui-FormField--required__sign: '';
+        }
+      `}
+      </style>
+      <div class="example example--themed-form-fields">
+       <Toggle
+          checked={optional}
+          label="This field is optional"
+          onChange={() => setOptional(!optional)}
+        />
+        <Toggle
+          checked={renderAsRequired}
+          label="This field is optional but looks like required"
+          onChange={() => setRenderAsRequired(!renderAsRequired)}
+          renderAsRequired
+        />
+      </div>
+    </React.Fragment>
+  );
+});
+```
+
+It renders the field as if it was required, but doesn't add the `required`
+attribute to the actual input.
+
 ### Disabled State
 
 Disabled state makes the input unavailable.

package/src/components/Toggle/Toggle.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React, { useContext } from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
@@ -15,6 +15,7 @@ export const Toggle = React.forwardRef((props, ref) => {
     isLabelVisible,
     label,
     labelPosition,
+    renderAsRequired,
     required,
     validationState,
     validationText,
@@ -31,7 +32,7 @@ export const Toggle = React.forwardRef((props, ref) => {
         context && context.layout === 'horizontal' ? styles.isRootLayoutHorizontal : styles.isRootLayoutVertical,
         labelPosition === 'before' && styles.hasRootLabelBefore,
         disabled && styles.isRootDisabled,
-        required && styles.isRootRequired,
+        (required || renderAsRequired) && styles.isRootRequired,
         getRootValidationStateClassName(validationState, styles),
       )}
       htmlFor={id}
@@ -84,6 +85,7 @@ Toggle.defaultProps = {
   id: undefined,
   isLabelVisible: true,
   labelPosition: 'after',
+  renderAsRequired: false,
   required: false,
   validationState: null,
   validationText: null,
@@ -120,7 +122,11 @@ Toggle.propTypes = {
    */
   labelPosition: PropTypes.oneOf(['before', 'after']),
   /**
-   * If `true`, the input will be required.
+   * If `true`, the input will be rendered as if it was required.
+   */
+  renderAsRequired: PropTypes.bool,
+  /**
+   * If `true`, the input will be made and rendered as required, regardless of the `renderAsRequired` prop.
    */
   required: PropTypes.bool,
   /**

package/src/components/Toolbar/Toolbar.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { isChildrenEmpty } from '../_helpers/isChildrenEmpty';

package/src/components/Toolbar/ToolbarGroup.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
 import { isChildrenEmpty } from '../_helpers/isChildrenEmpty';

package/src/components/Toolbar/ToolbarItem.jsx

@@ -2,7 +2,7 @@ import PropTypes from 'prop-types';
 import React from 'react';
 import { classNames } from '../../utils/classNames';
 import { transferProps } from '../../utils/transferProps';
-import { withGlobalProps } from '../../provider';
+import { withGlobalProps } from '../../providers/globalProps';
 import { isChildrenEmpty } from '../_helpers/isChildrenEmpty';
 import styles from './Toolbar.module.scss';
 

package/src/components/_helpers/resolveContextOrProp.js

@@ -1,7 +1,10 @@
 export const resolveContextOrProp = (contextValue, propValue) => {
-  if (contextValue != null) {
-    return contextValue;
+  // We need to test:
+  //  * `false` - for when the `contextValue` is boolean
+  //  * `null` - for when the `contextValue` is non-boolean
+  if (contextValue === false || contextValue === null) {
+    return propValue;
   }
 
-  return propValue;
+  return contextValue;
 };

package/src/index.js

@@ -57,8 +57,9 @@ export {
   ToolbarItem,
 } from './components/Toolbar';
 
-// Provider
-export { RUIProvider } from './provider';
+// Providers
+export { GlobalPropsProvider } from './providers/globalProps';
+export { TranslationsProvider } from './providers/translations';
 
 // Utils
 export { classNames } from './utils/classNames';

package/src/providers/globalProps/GlobalPropsContext.jsx

@@ -0,0 +1,5 @@
+import React from 'react';
+
+const GlobalPropsContext = React.createContext({});
+
+export default GlobalPropsContext;

package/src/providers/globalProps/GlobalPropsProvider.jsx

@@ -0,0 +1,33 @@
+import PropTypes from 'prop-types';
+import React, {
+  useContext,
+} from 'react';
+import { mergeDeep } from '../../utils/mergeDeep';
+import GlobalPropsContext from './GlobalPropsContext';
+
+const GlobalPropsProvider = ({
+  children,
+  globalProps,
+}) => {
+  const contextGlobalProps = useContext(GlobalPropsContext);
+
+  return (
+    <GlobalPropsContext.Provider
+      value={mergeDeep(contextGlobalProps, globalProps)}
+    >
+      {children}
+    </GlobalPropsContext.Provider>
+  );
+};
+
+GlobalPropsProvider.defaultProps = {
+  children: null,
+  globalProps: {},
+};
+
+GlobalPropsProvider.propTypes = {
+  children: PropTypes.node,
+  globalProps: PropTypes.shape({}),
+};
+
+export default GlobalPropsProvider;

package/src/providers/globalProps/index.js

@@ -0,0 +1,3 @@
+export { default as GlobalPropsContext } from './GlobalPropsContext';
+export { default as GlobalPropsProvider } from './GlobalPropsProvider';
+export { default as withGlobalProps } from './withGlobalProps';

package/src/{provider → providers/globalProps}/withGlobalProps.jsx

@@ -1,26 +1,24 @@
 import PropTypes from 'prop-types';
-import React from 'react';
-import RUIContext from './RUIContext';
+import React, {
+  useContext,
+} from 'react';
+import GlobalPropsContext from './GlobalPropsContext';
 
 export default (Component, componentName) => {
   const WithGlobalPropsComponent = ({
     forwardedRef,
     ...rest
-  }) => (
-    <RUIContext.Consumer>
-      {({ globalProps }) => {
-        const contextGlobalProps = globalProps ? globalProps[componentName] : null;
+  }) => {
+    const contextGlobalProps = useContext(GlobalPropsContext);
 
-        return (
-          <Component
-            {...contextGlobalProps}
-            {...rest}
-            ref={forwardedRef}
-          />
-        );
-      }}
-    </RUIContext.Consumer>
-  );
+    return (
+      <Component
+        {...contextGlobalProps[componentName] || {}}
+        {...rest}
+        ref={forwardedRef}
+      />
+    );
+  };
 
   WithGlobalPropsComponent.defaultProps = {
     forwardedRef: undefined,
@@ -29,6 +27,8 @@ export default (Component, componentName) => {
   WithGlobalPropsComponent.propTypes = {
     forwardedRef: PropTypes.oneOfType([
       PropTypes.func,
+
+      // The props can be of any type and here we need to support them all
       // eslint-disable-next-line react/forbid-prop-types
       PropTypes.shape({ current: PropTypes.any }),
     ]),

package/src/providers/translations/TranslationsContext.jsx

@@ -0,0 +1,6 @@
+import React from 'react';
+import defaultTranslations from '../../translations/en';
+
+const RUIContext = React.createContext(defaultTranslations);
+
+export default RUIContext;

package/src/providers/translations/TranslationsProvider.jsx

@@ -0,0 +1,33 @@
+import PropTypes from 'prop-types';
+import React, {
+  useContext,
+} from 'react';
+import { mergeDeep } from '../../utils/mergeDeep';
+import TranslationsContext from './TranslationsContext';
+
+const TranslationsProvider = ({
+  children,
+  translations,
+}) => {
+  const contextTranslations = useContext(TranslationsContext);
+
+  return (
+    <TranslationsContext.Provider
+      value={mergeDeep(contextTranslations, translations)}
+    >
+      {children}
+    </TranslationsContext.Provider>
+  );
+};
+
+TranslationsProvider.defaultProps = {
+  children: null,
+  translations: {},
+};
+
+TranslationsProvider.propTypes = {
+  children: PropTypes.node,
+  translations: PropTypes.shape({}),
+};
+
+export default TranslationsProvider;

package/src/providers/translations/index.js

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