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

package/src/components/CheckboxField/README.md

@@ -18,7 +18,13 @@ React.createElement(() => {
   return (
     <CheckboxField
       checked={agree}
-      label="I agree"
+      label={(
+          <>
+            I have read and agree with
+            {' '}
+            <TextLink href="#" label="terms and conditions" />
+          </>
+        )}
       onChange={() => setAgree(!agree)}
     />
   );
@@ -132,20 +138,44 @@ React.createElement(() => {
     <>
       <CheckboxField
         checked={agree}
-        label="I have read and agree with terms and conditions"
+        label={(
+          <>
+            I have read and agree with
+            {' '}
+            <TextLink href="#" label="terms and conditions" />
+          </>
+        )}
         onChange={() => setAgree(!agree)}
         validationState="valid"
       />
       <CheckboxField
         checked={agree}
-        label="I have read and agree with terms and conditions"
+        label={(
+          <>
+            I have read and agree with
+            {' '}
+            <TextLink href="#" label="terms and conditions" />
+          </>
+        )}
         onChange={() => setAgree(!agree)}
         validationState="warning"
-        validationText="Please wait 10 minutes until we verify your data."
+        validationText={(
+          <>
+            Please wait 10 minutes until we verify your data.
+            {' '}
+            <TextLink href="#" label="Cancel" />
+          </>
+        )}
       />
       <CheckboxField
         checked={agree}
-        label="I have read and agree with terms and conditions"
+        label={(
+          <>
+            I have read and agree with
+            {' '}
+            <TextLink href="#" label="terms and conditions" />
+          </>
+        )}
         onChange={() => setAgree(!agree)}
         required
         validationState="invalid"
@@ -156,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.

package/src/components/FileInputField/FileInputField.jsx

@@ -1,10 +1,19 @@
 import PropTypes from 'prop-types';
-import React, { useContext } from 'react';
-import { withGlobalProps } from '../../provider';
-import { classNames } from '../../utils/classNames';
-import { transferProps } from '../../utils/transferProps';
+import React, {
+  useContext,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+import { withGlobalProps } from '../../providers/globalProps';
+import { classNames } from '../../helpers/classNames';
+import { transferProps } from '../../helpers/transferProps';
+import { TranslationsContext } from '../../providers/translations';
+import { getRootSizeClassName } from '../_helpers/getRootSizeClassName';
 import { getRootValidationStateClassName } from '../_helpers/getRootValidationStateClassName';
 import { resolveContextOrProp } from '../_helpers/resolveContextOrProp';
+import { InputGroupContext } from '../InputGroup';
+import { Text } from '../Text';
 import { FormLayoutContext } from '../FormLayout';
 import styles from './FileInputField.module.scss';
 
@@ -17,54 +26,156 @@ export const FileInputField = React.forwardRef((props, ref) => {
     isLabelVisible,
     label,
     layout,
+    multiple,
+    onFilesChanged,
     required,
+    size,
     validationState,
     validationText,
     ...restProps
   } = props;
 
-  const context = useContext(FormLayoutContext);
+  const internalInputRef = useRef();
+
+  // We need to have a reference to the input element to be able to call its methods,
+  // but at the same time we want to expose this reference to the parent component for
+  // case someone wants to call input methods from outside the component.
+  useImperativeHandle(ref, () => internalInputRef.current);
+
+  const formLayoutContext = useContext(FormLayoutContext);
+  const inputGroupContext = useContext(InputGroupContext);
+  const translations = useContext(TranslationsContext);
+
+  const [selectedFileNames, setSelectedFileNames] = useState([]);
+  const [isDragging, setIsDragging] = useState(false);
+
+  const handleFileChange = (files, event) => {
+    if (files.length === 0) {
+      setSelectedFileNames([]);
+      return;
+    }
+
+    // Mimic the native behavior of the `input` element: if multiple files are selected and the input
+    // does not accept multiple files, no files are processed.
+    if (files.length > 1 && !multiple) {
+      setSelectedFileNames([]);
+      return;
+    }
+
+    const fileNames = [];
+
+    [...files].forEach((file) => {
+      fileNames.push(file.name);
+    });
+
+    setSelectedFileNames(fileNames);
+    onFilesChanged(files, event);
+  };
+
+  const handleInputChange = (event) => {
+    handleFileChange(event.target.files, event);
+  };
+
+  const handleClick = () => {
+    internalInputRef?.current.click();
+  };
+
+  const handleDrop = (event) => {
+    event.preventDefault();
+    handleFileChange(event.dataTransfer.files, event);
+    setIsDragging(false);
+  };
+
+  const handleDragOver = (event) => {
+    if (!isDragging) {
+      setIsDragging(true);
+    }
+    event.preventDefault();
+  };
+
+  const handleDragLeave = () => {
+    if (isDragging) {
+      setIsDragging(false);
+    }
+  };
 
   return (
-    <label
+    <div
       className={classNames(
         styles.root,
         fullWidth && styles.isRootFullWidth,
-        context && styles.isRootInFormLayout,
-        resolveContextOrProp(context && context.layout, layout) === 'horizontal'
+        formLayoutContext && styles.isRootInFormLayout,
+        resolveContextOrProp(formLayoutContext && formLayoutContext.layout, layout) === 'horizontal'
           ? styles.isRootLayoutHorizontal
           : styles.isRootLayoutVertical,
-        disabled && styles.isRootDisabled,
+        resolveContextOrProp(inputGroupContext && inputGroupContext.disabled, disabled) && styles.isRootDisabled,
+        inputGroupContext && styles.isRootGrouped,
+        isDragging && styles.isRootDragging,
         required && styles.isRootRequired,
+        getRootSizeClassName(
+          resolveContextOrProp(inputGroupContext && inputGroupContext.size, size),
+          styles,
+        ),
         getRootValidationStateClassName(validationState, styles),
       )}
-      htmlFor={id}
-      id={id && `${id}__label`}
+      id={`${id}__root`}
+      onDragLeave={!disabled ? handleDragLeave : undefined}
+      onDragOver={!disabled ? handleDragOver : undefined}
+      onDrop={!disabled ? handleDrop : undefined}
     >
-      <div
+      <label
         className={classNames(
           styles.label,
-          !isLabelVisible && styles.isLabelHidden,
+          (!isLabelVisible || inputGroupContext) && styles.isLabelHidden,
         )}
-        id={id && `${id}__labelText`}
+        htmlFor={id}
+        id={`${id}__labelText`}
       >
         {label}
-      </div>
+      </label>
       <div className={styles.field}>
         <div className={styles.inputContainer}>
           <input
             {...transferProps(restProps)}
-            disabled={disabled}
+            className={styles.input}
+            disabled={resolveContextOrProp(inputGroupContext && inputGroupContext.disabled, disabled)}
             id={id}
-            ref={ref}
+            multiple={multiple}
+            onChange={handleInputChange}
+            ref={internalInputRef}
             required={required}
+            tabIndex={-1}
             type="file"
           />
+          <button
+            className={styles.dropZone}
+            disabled={resolveContextOrProp(inputGroupContext && inputGroupContext.disabled, disabled)}
+            onClick={handleClick}
+            type="button"
+          >
+            <Text lines={1}>
+              {!selectedFileNames.length && (
+                <>
+                  <span className={styles.dropZoneLink}>{translations.FileInputField.browse}</span>
+                  {' '}
+                  {translations.FileInputField.drop}
+                </>
+              )}
+              {selectedFileNames.length === 1 && selectedFileNames[0]}
+              {selectedFileNames.length > 1 && (
+                <>
+                  {selectedFileNames.length}
+                  {' '}
+                  {translations.FileInputField.filesSelected}
+                </>
+              )}
+            </Text>
+          </button>
         </div>
         {helpText && (
           <div
             className={styles.helpText}
-            id={id && `${id}__helpText`}
+            id={`${id}__helpText`}
           >
             {helpText}
           </div>
@@ -72,13 +183,13 @@ export const FileInputField = React.forwardRef((props, ref) => {
         {validationText && (
           <div
             className={styles.validationText}
-            id={id && `${id}__validationText`}
+            id={`${id}__validationText`}
           >
             {validationText}
           </div>
         )}
       </div>
-    </label>
+    </div>
   );
 });
 
@@ -86,10 +197,11 @@ FileInputField.defaultProps = {
   disabled: false,
   fullWidth: false,
   helpText: null,
-  id: undefined,
   isLabelVisible: true,
   layout: 'vertical',
+  multiple: false,
   required: false,
+  size: 'medium',
   validationState: null,
   validationText: null,
 };
@@ -116,7 +228,7 @@ FileInputField.propTypes = {
    * * `<ID>__helpText`
    * * `<ID>__validationText`
    */
-  id: PropTypes.string,
+  id: PropTypes.string.isRequired,
   /**
    * If `false`, the label will be visually hidden (but remains accessible by assistive
    * technologies).
@@ -134,10 +246,24 @@ FileInputField.propTypes = {
    *
    */
   layout: PropTypes.oneOf(['horizontal', 'vertical']),
+  /**
+   * If `true`, the input will accept multiple files.
+   */
+  multiple: PropTypes.bool,
+  /**
+   * Callback fired when the value of the input changes.
+   */
+  onFilesChanged: PropTypes.func.isRequired,
   /**
    * If `true`, the input will be required.
    */
   required: PropTypes.bool,
+  /**
+   * Size of the field.
+   *
+   * Ignored if the component is rendered within `InputGroup` component as the value is inherited in such case.
+   */
+  size: PropTypes.oneOf(['small', 'medium', 'large']),
   /**
    * Alter the field to provide feedback based on validation result.
    */

package/src/components/FileInputField/FileInputField.module.scss

@@ -1,8 +1,16 @@
+// 1. The drop zone is constructed as a button to support keyboard operation.
+// 2. Prevent pointer events on all children of the root element to not to trigger drag events on children.
+
 @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/links";
+@use "../../styles/tools/transition";
+@use "../../styles/tools/reset";
+@use "settings";
 
 @layer components.file-input-field {
     // Foundation
@@ -18,6 +26,54 @@
         @include box-field-elements.input-container();
     }
 
+    .input {
+        @include accessibility.hide-text();
+    }
+
+    .dropZone {
+        --rui-local-color: #{settings.$drop-zone-color};
+        --rui-local-border-color: #{settings.$drop-zone-border-color};
+        --rui-local-background: #{settings.$drop-zone-background-color};
+
+        @include reset.button(); // 1.
+        @include box-field-elements.base();
+
+        display: flex;
+        align-items: center;
+        justify-content: start;
+        font-weight: settings.$drop-zone-font-weight;
+        font-size: var(--rui-local-font-size);
+        line-height: settings.$drop-zone-line-height;
+        font-family: settings.$drop-zone-font-family;
+        border-style: dashed;
+    }
+
+    .isRootDragging .dropZone {
+        --rui-local-border-color: #{settings.$drop-zone-dragging-border-color};
+    }
+
+    .isRootDisabled .dropZone {
+        cursor: settings.$drop-zone-disabled-cursor;
+    }
+
+    .root:not(.isRootDisabled, .isRootDragging) .dropZone:hover {
+        --rui-local-border-color: #{settings.$drop-zone-hover-border-color};
+    }
+
+    .root:not(.isRootDisabled, .isRootDragging) .dropZone:active {
+        --rui-local-border-color: #{settings.$drop-zone-active-border-color};
+    }
+
+    .dropZoneLink {
+        @include links.base();
+
+        &::before {
+            content: "";
+            position: absolute;
+            inset: 0;
+        }
+    }
+
     .helpText,
     .validationText {
         @include foundation.help-text();
@@ -28,6 +84,18 @@
     }
 
     // States
+    .isRootDisabled {
+        --rui-local-color: #{settings.$drop-zone-disabled-color};
+        --rui-local-border-color: #{settings.$drop-zone-disabled-border-color};
+        --rui-local-background: #{settings.$drop-zone-disabled-background-color};
+
+        @include variants.disabled-state();
+    }
+
+    .isRootDisabled .dropZoneLink {
+        cursor: inherit;
+    }
+
     .isRootStateInvalid {
         @include variants.validation(invalid);
     }
@@ -56,10 +124,28 @@
     }
 
     .isRootFullWidth {
-        @include box-field-layout.full-width();
+        @include box-field-layout.full-width($input-element-selector: ".dropZone");
     }
 
     .isRootInFormLayout {
         @include box-field-layout.in-form-layout();
     }
+
+    // Sizes
+    .isRootSizeSmall {
+        @include box-field-sizes.size(small);
+    }
+
+    .isRootSizeMedium {
+        @include box-field-sizes.size(medium);
+    }
+
+    .isRootSizeLarge {
+        @include box-field-sizes.size(large);
+    }
+
+    // Groups
+    .isRootGrouped {
+        @include box-field-elements.in-group-layout($input-element-selector: ".dropZone");
+    }
 }

package/src/components/FileInputField/README.md

@@ -13,7 +13,7 @@ import { FileInputField } from '@react-ui-org/react-ui';
 And use it:
 
 ```docoff-react-preview
-<FileInputField label="Attachment" />
+<FileInputField id="my-file" label="Attachment" onFilesChanged={() => {}} />
 ```
 
 See [API](#api) for all available options.
@@ -48,12 +48,37 @@ layout perspective, FileInputFields work just like any other form fields.
 
 ## Sizes
 
+Aside from the default (medium) size, two additional sizes are available: small
+and large.
+
+```docoff-react-preview
+<FileInputField
+  id="my-file-small"
+  label="Attachment"
+  onFilesChanged={() => {}}
+  size="small"
+/>
+<FileInputField
+  id="my-file-medium"
+  label="Attachment"
+  onFilesChanged={() => {}}
+/>
+<FileInputField
+  id="my-file-large"
+  label="Attachment"
+  onFilesChanged={() => {}}
+  size="large"
+/>
+```
+
 Full-width fields span the full width of a parent:
 
 ```docoff-react-preview
 <FileInputField
   fullWidth
+  id="my-file"
   label="First name"
+  onFilesChanged={() => {}}
 />
 ```
 
@@ -68,8 +93,10 @@ dangerous to hide labels from users in most cases. Keep in mind you should
 
 ```docoff-react-preview
 <FileInputField
+  id="my-file"
   isLabelVisible={false}
   label="Attachment"
+  onFilesChanged={() => {}}
 />
 ```
 
@@ -81,14 +108,18 @@ supports this kind of layout as well.
 
 ```docoff-react-preview
 <FileInputField
+  id="my-file-horizontal"
   label="Attachment"
   layout="horizontal"
+  onFilesChanged={() => {}}
 />
 <FileInputField
   fullWidth
+  id="my-file-horizontal-full-width"
   isLabelVisible={false}
   label="Attachment"
   layout="horizontal"
+  onFilesChanged={() => {}}
 />
 ```
 
@@ -100,18 +131,24 @@ filled.
 ```docoff-react-preview
 <FileInputField
   helpText="Choose one or more files to upload."
+  id="my-file-help-text"
   label="Attachment"
+  onFilesChanged={() => {}}
 />
 <FileInputField
   helpText="Choose one or more files to upload."
+  id="my-file-help-text-horizontal"
   label="Attachment"
   layout="horizontal"
+  onFilesChanged={() => {}}
 />
 <FileInputField
   fullWidth
   helpText="Choose one or more files to upload."
+  id="my-file-help-text-horizontal-full-width"
   label="Attachment"
   layout="horizontal"
+  onFilesChanged={() => {}}
 />
 ```
 
@@ -126,17 +163,23 @@ have.
 
 ```docoff-react-preview
 <FileInputField
+  id="my-file-valid"
   label="Attachment"
+  onFilesChanged={() => {}}
   validationState="valid"
   validationText="Looks good!"
 />
 <FileInputField
+  id="my-file-invalid"
   label="Attachment"
+  onFilesChanged={() => {}}
   validationState="invalid"
   validationText="Your file is too big. Please select something smaller."
 />
 <FileInputField
+  id="my-file-warning"
   label="Attachment"
+  onFilesChanged={() => {}}
   validationState="warning"
   validationText={`
     You selected more than 10 files.
@@ -152,7 +195,44 @@ It's possible to disable the whole input.
 ```docoff-react-preview
 <FileInputField
   disabled
+  id="my-file"
   label="Attachment"
+  onFilesChanged={() => {}}
+/>
+```
+
+## Handling Files
+
+Files selected by the user are handled by providing a custom function to the
+`onFilesChanged` prop. The `onFilesChanged` function is then called on the
+`change` event of the `input` element and on the `drop` event of the root
+`div` element.
+
+```docoff-react-preview
+<FileInputField
+  id="my-file"
+  label="Attachment"
+  onFilesChanged={(files, event) => {
+    // Do something with the files…
+    console.log('Files selected:', files);
+  }}
+/>
+```
+
+### Multiple Files
+
+By default, users can select only one file. To allow selecting multiple files,
+set the `multiple` prop to `true`.
+
+```docoff-react-preview
+<FileInputField
+  id="my-files"
+  label="Attachment"
+  multiple
+  onFilesChanged={(files, event) => {
+    // Do something with the files…
+    console.log('Files selected:', files);
+  }}
 />
 ```
 
@@ -172,8 +252,9 @@ to improve its accessibility.
     Choose up to 10 files. Allowed extensions are .pdf, .jpg, .jpeg, or .png.
     Size limit is 10 MB.
   `}
+  id="my-file"
   label="Attachment"
-  multiple
+  onFilesChanged={() => {}}
 />
 ```