Allow check fields and selectable fields to render as required #487

src/components/CheckboxField/CheckboxField.jsx

@@ -15,6 +15,7 @@ export const CheckboxField = React.forwardRef((props, ref) => {
     isLabelVisible,
     label,
     labelPosition,
+    renderAsRequired,
     required,
     validationState,
     validationText,
@@ -30,7 +31,7 @@ export const CheckboxField = React.forwardRef((props, ref) => {
         context && context.layout === 'horizontal' ? styles.isRootLayoutHorizontal : styles.isRootLayoutVertical,
         labelPosition === 'before' && styles.hasRootLabelBefore,
         disabled && styles.isRootDisabled,
-        required && styles.isRootRequired,
+        (renderAsRequired || required) && styles.isRootRequired,
         getRootValidationStateClassName(validationState, styles),
       )}
       htmlFor={id}
@@ -82,6 +83,7 @@ CheckboxField.defaultProps = {
   id: undefined,
   isLabelVisible: true,
   labelPosition: 'after',
+  renderAsRequired: false,
   required: false,
   validationState: null,
   validationText: null,
@@ -120,7 +122,11 @@ CheckboxField.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,
   /**

src/components/CheckboxField/README.md

@@ -186,6 +186,81 @@ React.createElement(() => {
 });
 ```
 
+### Required State
+
+The required state indicates that the input is mandatory. Required fields
+display an asterisk `*` after the label by default.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [agree, setAgree] = React.useState(true);
+  return (
+    <CheckboxField
+      checked={agree}
+      label="I agree"
+      onChange={() => setAgree(!agree)}
+      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">
+        <CheckboxField
+          checked={optional}
+          label="This field is optional"
+          onChange={() => setOptional(!optional)}
+        />
+        <CheckboxField
+          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.

src/components/CheckboxField/__tests__/CheckboxField.test.jsx

@@ -11,6 +11,7 @@ import { helpTextPropTest } from '../../../../tests/propTests/helpTextPropTest';
 import { formLayoutProviderTest } from '../../../../tests/providerTests/formLayoutProviderTest';
 import { isLabelVisibleTest } from '../../../../tests/propTests/isLabelVisibleTest';
 import { labelPropTest } from '../../../../tests/propTests/labelPropTest';
+import { renderAsRequiredPropTest } from '../../../../tests/propTests/renderAsRequiredPropTest';
 import { requiredPropTest } from '../../../../tests/propTests/requiredPropTest';
 import { validationStatePropTest } from '../../../../tests/propTests/validationStatePropTest';
 import { validationTextPropTest } from '../../../../tests/propTests/validationTextPropTest';
@@ -43,6 +44,7 @@ describe('rendering', () => {
     ],
     ...isLabelVisibleTest(),
     ...labelPropTest(),
+    ...renderAsRequiredPropTest,
     ...requiredPropTest,
     ...validationStatePropTest,
     ...validationTextPropTest,

src/components/Radio/README.md

@@ -237,6 +237,109 @@ have.
   })
 ```
 
+### Required State
+
+The required state indicates that the input is mandatory.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [fruit, setFruit] = React.useState('apple');
+  return (
+    <Radio
+      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">
+        <Radio
+          label="This field is optional"
+          onChange={(e) => setFruit(e.target.value)}
+          options={options}
+          value={fruit}
+        />
+        <Radio
+          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 set.

src/components/Radio/Radio.jsx

@@ -16,6 +16,7 @@ export const Radio = ({
   label,
   layout,
   options,
+  renderAsRequired,
   required,
   validationState,
   validationText,
@@ -33,7 +34,7 @@ export const Radio = ({
           ? styles.isRootLayoutHorizontal
           : styles.isRootLayoutVertical,
         disabled && styles.isRootDisabled,
-        required && styles.isRootRequired,
+        (renderAsRequired || required) && styles.isRootRequired,
         getRootValidationStateClassName(validationState, styles),
       )}
       disabled={disabled}
@@ -116,6 +117,7 @@ Radio.defaultProps = {
   id: undefined,
   isLabelVisible: true,
   layout: 'vertical',
+  renderAsRequired: false,
   required: false,
   validationState: null,
   validationText: null,
@@ -181,7 +183,11 @@ Radio.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,
   /**

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

src/components/Radio/__tests__/Radio.test.jsx

@@ -10,6 +10,7 @@ import { formLayoutProviderTest } from '../../../../tests/providerTests/formLayo
 import { isLabelVisibleTest } from '../../../../tests/propTests/isLabelVisibleTest';
 import { labelPropTest } from '../../../../tests/propTests/labelPropTest';
 import { layoutPropTest } from '../../../../tests/propTests/layoutPropTest';
+import { renderAsRequiredPropTest } from '../../../../tests/propTests/renderAsRequiredPropTest';
 import { requiredPropTest } from '../../../../tests/propTests/requiredPropTest';
 import { validationStatePropTest } from '../../../../tests/propTests/validationStatePropTest';
 import { validationTextPropTest } from '../../../../tests/propTests/validationTextPropTest';
@@ -83,6 +84,7 @@ describe('rendering', () => {
         expect(within(rootElement).getByLabelText('option 2')).toBeDisabled();
       },
     ],
+    ...renderAsRequiredPropTest,
     ...requiredPropTest,
     ...validationStatePropTest,
     ...validationTextPropTest,