@openedx/paragon 22.0.0-alpha.24 → 22.1.0

package/src/Form/FormAutosuggest.jsx

@@ -1,9 +1,10 @@
 import React, {
-  useEffect, useState, useRef,
+  useEffect, useState, useRef, forwardRef, useImperativeHandle,
 } from 'react';
 import PropTypes from 'prop-types';
 import { v4 as uuidv4 } from 'uuid';
 import { useIntl } from 'react-intl';
+import { requiredWhen } from '../utils/propTypes';
 import { KeyboardArrowUp, KeyboardArrowDown } from '../../icons';
 import Icon from '../Icon';
 import { FormGroupContextProvider, useFormGroupContext } from './FormGroupContext';
@@ -14,292 +15,353 @@ import Spinner from '../Spinner';
 import useArrowKeyNavigation from '../hooks/useArrowKeyNavigation';
 import messages from './messages';
 
-function FormAutosuggest({
-  children,
-  arrowKeyNavigationSelector,
-  ignoredArrowKeysNames,
-  screenReaderText,
-  value,
-  isLoading,
-  errorMessageText,
-  onChange,
-  onSelected,
-  helpMessage,
-  ...props
-}) {
-  const intl = useIntl();
-  const formControlRef = useRef();
-  const parentRef = useArrowKeyNavigation({
-    selectors: arrowKeyNavigationSelector,
-    ignoredKeys: ignoredArrowKeysNames,
-  });
-  const [isMenuClosed, setIsMenuClosed] = useState(true);
-  const [isActive, setIsActive] = useState(false);
-  const [state, setState] = useState({
-    displayValue: value || '',
-    errorMessage: '',
-    dropDownItems: [],
-  });
-  const [activeMenuItemId, setActiveMenuItemId] = useState(null);
-
-  const handleMenuItemFocus = (menuItemId) => {
-    setActiveMenuItemId(menuItemId);
-  };
-
-  const handleItemClick = (e, onClick) => {
-    const clickedValue = e.currentTarget.getAttribute('data-value');
-
-    if (onSelected && clickedValue !== value) {
-      onSelected(clickedValue);
-    }
+const FormAutosuggest = forwardRef(
+  (
+    {
+      children,
+      arrowKeyNavigationSelector,
+      ignoredArrowKeysNames,
+      screenReaderText,
+      value,
+      isLoading,
+      isValueRequired,
+      valueRequiredErrorMessageText,
+      isSelectionRequired,
+      selectionRequiredErrorMessageText,
+      hasCustomError,
+      customErrorMessageText,
+      onChange,
+      helpMessage,
+      ...props
+    },
+    ref,
+  ) => {
+    const intl = useIntl();
+    const formControlRef = useRef();
+    const parentRef = useArrowKeyNavigation({
+      selectors: arrowKeyNavigationSelector,
+      ignoredKeys: ignoredArrowKeysNames,
+    });
+    const [isDropdownExpanded, setIsDropdownExpanded] = useState(false);
+    const [isActive, setIsActive] = useState(false);
+    const [hasValue, setHasValue] = useState(false);
+    const [hasSelection, setHasSelection] = useState(false);
+    const [displayValue, setDisplayValue] = useState(value?.userProvidedText || '');
+    const [dropdownItems, setDropdownItems] = useState([]);
+    const [activeMenuItemId, setActiveMenuItemId] = useState(null);
+    const [isValid, setIsValid] = useState(true);
+    const [errorMessage, setErrorMessage] = useState('');
+
+    const handleMenuItemFocus = (menuItemId) => {
+      setActiveMenuItemId(menuItemId);
+    };
 
-    setState(prevState => ({
-      ...prevState,
-      dropDownItems: [],
-      displayValue: clickedValue,
-    }));
+    const collapseDropdown = () => {
+      setDropdownItems([]);
+      setIsDropdownExpanded(false);
+      setActiveMenuItemId(null);
+    };
 
-    setIsMenuClosed(true);
+    const handleItemSelect = (e, onClick) => {
+      const selectedValue = e.currentTarget.getAttribute('data-value');
+      const selectedId = e.currentTarget.id;
 
-    if (onClick) {
-      onClick(e);
-    }
-  };
-
-  function getItems(strToFind = '') {
-    let childrenOpt = React.Children.map(children, (child) => {
-      // eslint-disable-next-line no-shadow
-      const { children, onClick, ...rest } = child.props;
-      const menuItemId = uuidv4();
-
-      return React.cloneElement(child, {
-        ...rest,
-        children,
-        'data-value': children,
-        onClick: (e) => handleItemClick(e, onClick),
-        id: menuItemId,
-        onFocus: () => handleMenuItemFocus(menuItemId),
-      });
-    });
-
-    if (strToFind.length > 0) {
-      childrenOpt = childrenOpt
-        .filter((opt) => (opt.props.children.toLowerCase().includes(strToFind.toLowerCase())));
-    }
+      setHasValue(true);
+      setHasSelection(true);
+      setDisplayValue(selectedValue);
 
-    return childrenOpt;
-  }
+      if (onChange && (!value || (value && selectedValue !== value.selectionValue))) {
+        onChange({
+          userProvidedText: selectedValue,
+          selectionValue: selectedValue,
+          selectionId: selectedId,
+        });
+      }
 
-  const handleExpand = () => {
-    setIsMenuClosed(!isMenuClosed);
+      collapseDropdown();
 
-    const newState = {
-      dropDownItems: [],
+      if (onClick) {
+        onClick(e);
+      }
     };
 
-    if (isMenuClosed) {
-      setIsActive(true);
-      newState.dropDownItems = getItems(state.displayValue);
-      newState.errorMessage = '';
-    }
-
-    setState(prevState => ({
-      ...prevState,
-      ...newState,
-    }));
-  };
-
-  const iconToggle = (
-    <IconButton
-      className="pgn__form-autosuggest__icon-button"
-      data-testid="autosuggest-iconbutton"
-      tabindex="-1"
-      src={isMenuClosed ? KeyboardArrowDown : KeyboardArrowUp}
-      iconAs={Icon}
-      size="sm"
-      variant="secondary"
-      alt={isMenuClosed
-        ? intl.formatMessage(messages.iconButtonOpened)
-        : intl.formatMessage(messages.iconButtonClosed)}
-      onClick={(e) => handleExpand(e, isMenuClosed)}
-    />
-  );
-
-  const leaveControl = () => {
-    setIsActive(false);
-
-    setState(prevState => ({
-      ...prevState,
-      dropDownItems: [],
-      errorMessage: !state.displayValue ? errorMessageText : '',
-    }));
+    function getItems(strToFind = '') {
+      let childrenOpt = React.Children.map(children, (child) => {
+        const { children: childChildren, onClick, ...rest } = child.props;
+        const menuItemId = child.props.id ?? uuidv4();
+
+        return React.cloneElement(child, {
+          ...rest,
+          childChildren,
+          'data-value': childChildren,
+          onClick: (e) => handleItemSelect(e, onClick),
+          id: menuItemId,
+          onFocus: () => handleMenuItemFocus(menuItemId),
+        });
+      });
 
-    setIsMenuClosed(true);
-  };
+      if (strToFind.length > 0) {
+        childrenOpt = childrenOpt
+          .filter((opt) => (opt.props.children.toLowerCase().includes(strToFind.toLowerCase())));
+      }
 
-  const handleDocumentClick = (e) => {
-    if (parentRef.current && !parentRef.current.contains(e.target) && isActive) {
-      leaveControl();
+      return childrenOpt;
     }
-  };
 
-  const keyDownHandler = e => {
-    if (e.key === 'Escape' && isActive) {
-      e.preventDefault();
+    const expandDropdown = () => {
+      setDropdownItems(getItems(displayValue));
+      setIsValid(true);
+      setErrorMessage('');
+      setIsDropdownExpanded(true);
+    };
 
-      if (formControlRef) {
-        formControlRef.current.focus();
+    const toggleDropdown = () => {
+      if (isDropdownExpanded) {
+        collapseDropdown();
+      } else {
+        expandDropdown();
       }
+    };
 
-      setState(prevState => ({
-        ...prevState,
-        dropDownItems: [],
-      }));
+    const iconToggle = (
+      <IconButton
+        className="pgn__form-autosuggest__icon-button"
+        data-testid="autosuggest-iconbutton"
+        tabIndex="-1"
+        src={isDropdownExpanded ? KeyboardArrowUp : KeyboardArrowDown}
+        iconAs={Icon}
+        size="sm"
+        variant="secondary"
+        alt={isDropdownExpanded
+          ? intl.formatMessage(messages.iconButtonClosed)
+          : intl.formatMessage(messages.iconButtonOpened)}
+        onClick={toggleDropdown}
+      />
+    );
+
+    const enterControl = () => {
+      setIsActive(true);
+    };
 
-      setIsMenuClosed(true);
-    }
-    if (e.key === 'Tab' && isActive) {
-      leaveControl();
-    }
-  };
+    const updateErrorStateAndErrorMessage = () => {
+      if (hasCustomError) {
+        setIsValid(false);
+        setErrorMessage(customErrorMessageText);
+        return;
+      }
 
-  useEffect(() => {
-    document.addEventListener('keydown', keyDownHandler);
-    document.addEventListener('click', handleDocumentClick, true);
+      if (isValueRequired && !hasValue) {
+        setIsValid(false);
+        setErrorMessage(valueRequiredErrorMessageText);
+        return;
+      }
+
+      if (hasValue && isSelectionRequired && !hasSelection) {
+        setIsValid(false);
+        setErrorMessage(selectionRequiredErrorMessageText);
+        return;
+      }
 
-    return () => {
-      document.removeEventListener('click', handleDocumentClick, true);
-      document.removeEventListener('keydown', keyDownHandler);
+      setIsValid(true);
+      setErrorMessage('');
     };
-  });
-
-  useEffect(() => {
-    if (value || value === '') {
-      setState(prevState => ({
-        ...prevState,
-        displayValue: value,
-      }));
-    }
-  }, [value]);
 
-  const setDisplayValue = (itemValue) => {
-    const optValue = [];
+    useImperativeHandle(ref, () => ({
+      // expose updateErrorStateAndErrorMessage so consumers can trigger validation
+      // when changing the value of the control externally
+      updateErrorStateAndErrorMessage,
+    }));
 
-    children.forEach(opt => {
-      optValue.push(opt.props.children);
-    });
+    const leaveControl = () => {
+      setIsActive(false);
+      collapseDropdown();
+      updateErrorStateAndErrorMessage();
+    };
 
-    const normalized = itemValue.toLowerCase();
-    const opt = optValue.find((o) => o.toLowerCase() === normalized);
+    const keyDownHandler = e => {
+      if (!isActive) {
+        return;
+      }
 
-    setState(prevState => ({
-      ...prevState,
-      displayValue: opt || itemValue,
-    }));
-  };
+      if (e.key === 'Escape') {
+        e.preventDefault();
 
-  const handleClick = (e) => {
-    setIsActive(true);
-    const dropDownItems = getItems(e.target.value);
+        if (formControlRef) {
+          formControlRef.current.focus();
+        }
 
-    if (dropDownItems.length > 1) {
-      setState(prevState => ({
-        ...prevState,
-        dropDownItems,
-        errorMessage: '',
-      }));
+        collapseDropdown();
+        return;
+      }
 
-      setIsMenuClosed(false);
-    }
-  };
+      if (e.key === 'Tab') {
+        leaveControl();
+      }
+    };
 
-  const handleOnChange = (e) => {
-    const findStr = e.target.value;
+    const handleDocumentClick = (e) => {
+      if (parentRef.current && !parentRef.current.contains(e.target) && isActive) {
+        leaveControl();
+      }
+    };
+
+    useEffect(() => {
+      document.addEventListener('keydown', keyDownHandler);
+      document.addEventListener('click', handleDocumentClick, true);
 
-    if (onChange) { onChange(findStr); }
+      return () => {
+        document.removeEventListener('click', handleDocumentClick, true);
+        document.removeEventListener('keydown', keyDownHandler);
+      };
+    });
 
-    if (findStr.length) {
-      const filteredItems = getItems(findStr);
-      setState(prevState => ({
-        ...prevState,
-        dropDownItems: filteredItems,
-        errorMessage: '',
-      }));
+    useEffect(() => {
+      setDisplayValue(value ? value.userProvidedText ?? '' : '');
+      setHasValue(!!value && !!value.userProvidedText);
+      setHasSelection(!!value && !!value.selectionValue);
+    }, [value]);
 
-      setIsMenuClosed(false);
-    } else {
-      setState(prevState => ({
-        ...prevState,
-        dropDownItems: [],
-      }));
+    const handleTextboxClick = () => {
+      expandDropdown();
+    };
 
-      setIsMenuClosed(true);
-    }
+    const handleTextInput = (e) => {
+      const userProvidedText = e.target.value;
+
+      // If the user has removed all text from the textbox
+      if (!userProvidedText.length) {
+      // reset to a "no text, nothing selected" state
+        setDisplayValue('');
+        setHasValue(false);
+        setHasSelection(false);
+
+        // clear and close the dropdown
+        setDropdownItems([]);
+        collapseDropdown();
+
+        // if the consumer has provided an onChange handler
+        if (onChange) {
+        // send a default empty object
+          onChange({
+            userProvidedText: '',
+            selectionValue: '',
+            selectionId: '',
+          });
+        }
+        return;
+      }
 
-    setDisplayValue(e.target.value);
-  };
+      // the user has entered text, we have a value
+      setHasValue(true);
+
+      // filter dropdown based on entered text
+      const filteredItems = getItems(userProvidedText);
+      setDropdownItems(filteredItems);
+
+      // check for matches in the dropdown
+      const matchingDropdownItem = filteredItems.find((o) => (
+        o.props.children.toLowerCase() === userProvidedText.toLowerCase()
+      ));
+
+      // if we didn't find a match
+      if (!matchingDropdownItem) {
+      // no match means no selection
+        setHasSelection(false);
+
+        // set the text in the state
+        setDisplayValue(userProvidedText);
+
+        // if the consumer has provided an onChange handler
+        if (onChange) {
+        // send an object with the user provided text only
+          onChange({
+            userProvidedText,
+            selectionValue: '',
+            selectionId: '',
+          });
+        }
+        return;
+      }
 
-  const { getControlProps } = useFormGroupContext();
-  const controlProps = getControlProps(props);
+      // we found a match, we have a selection!
+      setHasSelection(true);
+
+      // set the display value based on the item in the dropdown
+      // this matters because we match case insensitively
+      setDisplayValue(matchingDropdownItem.props.children);
+
+      // if the consumer has provided an onChange handler
+      if (onChange) {
+      // send an object with the selected item values
+        onChange({
+          userProvidedText: matchingDropdownItem.props.children,
+          selectionValue: matchingDropdownItem.props.children,
+          selectionId: matchingDropdownItem.props.id,
+        });
+      }
+    };
 
-  return (
-    <div className="pgn__form-autosuggest__wrapper" ref={parentRef}>
-      <div aria-live="assertive" className="sr-only" data-testid="autosuggest-screen-reader-options-count">
-        {`${state.dropDownItems.length} options found`}
-      </div>
-      <FormGroupContextProvider
-        controlId={controlProps.id}
-        isInvalid={!!state.errorMessage}
-      >
-        <FormControl
-          ref={formControlRef}
-          aria-expanded={(state.dropDownItems.length > 0).toString()}
-          aria-owns="pgn__form-autosuggest__dropdown-box"
-          role="combobox"
-          aria-autocomplete="list"
-          autoComplete="off"
-          value={state.displayValue}
-          aria-invalid={state.errorMessage}
-          aria-activedescendant={activeMenuItemId}
-          onChange={handleOnChange}
-          onClick={handleClick}
-          trailingElement={iconToggle}
-          data-testid="autosuggest-textbox-input"
-          {...controlProps}
-        />
-
-        {helpMessage && !state.errorMessage && (
+    const { getControlProps } = useFormGroupContext();
+    const controlProps = getControlProps(props);
+
+    return (
+      <div className="pgn__form-autosuggest__wrapper" ref={parentRef} onFocus={enterControl}>
+        <div aria-live="assertive" className="sr-only" data-testid="autosuggest-screen-reader-options-count">
+          {`${dropdownItems.length} options found`}
+        </div>
+        <FormGroupContextProvider
+          controlId={controlProps.id}
+          isInvalid={!isValid}
+        >
+          <FormControl
+            ref={formControlRef}
+            aria-expanded={(dropdownItems.length > 0).toString()}
+            aria-owns="pgn__form-autosuggest__dropdown-box"
+            role="combobox"
+            aria-autocomplete="list"
+            autoComplete="off"
+            value={displayValue}
+            aria-invalid={errorMessage}
+            aria-activedescendant={activeMenuItemId}
+            onChange={handleTextInput}
+            onClick={handleTextboxClick}
+            trailingElement={iconToggle}
+            data-testid="autosuggest-textbox-input"
+            {...controlProps}
+          />
+
+          {helpMessage && isValid && (
           <FormControlFeedback type="default">
             {helpMessage}
           </FormControlFeedback>
-        )}
+          )}
 
-        {state.errorMessage && (
+          {!isValid && (
           <FormControlFeedback type="invalid" feedback-for={controlProps.name}>
-            {errorMessageText}
+            {errorMessage}
           </FormControlFeedback>
-        )}
-      </FormGroupContextProvider>
-
-      <ul
-        id="pgn__form-autosuggest__dropdown-box"
-        className="pgn__form-autosuggest__dropdown"
-        role="listbox"
-      >
-        {isLoading ? (
-          <div className="pgn__form-autosuggest__dropdown-loading">
-            <Spinner
-              animation="border"
-              variant="dark"
-              screenReaderText={screenReaderText}
-              data-testid="autosuggest-loading-spinner"
-            />
-          </div>
-        ) : state.dropDownItems.length > 0 && state.dropDownItems}
-      </ul>
-    </div>
-  );
-}
+          )}
+        </FormGroupContextProvider>
+        <ul
+          id="pgn__form-autosuggest__dropdown-box"
+          className="pgn__form-autosuggest__dropdown"
+          role="listbox"
+        >
+          {isLoading ? (
+            <div className="pgn__form-autosuggest__dropdown-loading">
+              <Spinner
+                animation="border"
+                variant="dark"
+                screenReaderText={screenReaderText}
+                data-testid="autosuggest-loading-spinner"
+              />
+            </div>
+          ) : dropdownItems.length > 0 && dropdownItems}
+        </ul>
+      </div>
+    );
+  },
+);
 
 FormAutosuggest.defaultProps = {
   arrowKeyNavigationSelector: 'a:not(:disabled),li:not(:disabled, .btn-icon),input:not(:disabled)',
@@ -308,11 +370,15 @@ FormAutosuggest.defaultProps = {
   className: null,
   floatingLabel: null,
   onChange: null,
-  onSelected: null,
   helpMessage: '',
   placeholder: '',
   value: null,
-  errorMessageText: null,
+  isValueRequired: false,
+  valueRequiredErrorMessageText: null,
+  isSelectionRequired: false,
+  selectionRequiredErrorMessageText: null,
+  hasCustomError: false,
+  customErrorMessageText: null,
   readOnly: false,
   children: null,
   name: 'form-autosuggest',
@@ -340,9 +406,23 @@ FormAutosuggest.propTypes = {
   /** Specifies the placeholder text for the input. */
   placeholder: PropTypes.string,
   /** Specifies values for the input. */
-  value: PropTypes.string,
-  /** Informs user has errors. */
-  errorMessageText: PropTypes.string,
+  value: PropTypes.shape({
+    userProvidedText: PropTypes.string,
+    selectionValue: PropTypes.string,
+    selectionId: PropTypes.string,
+  }),
+  /** Specifies if empty values trigger an error state */
+  isValueRequired: PropTypes.bool,
+  /** Informs user they must input a value. */
+  valueRequiredErrorMessageText: requiredWhen(PropTypes.string, 'isValueRequired'),
+  /** Specifies if freeform values trigger an error state */
+  isSelectionRequired: PropTypes.bool,
+  /** Informs user they must make a selection. */
+  selectionRequiredErrorMessageText: requiredWhen(PropTypes.string, 'isSelectionRequired'),
+  /** Specifies the control is in a consumer provided error state */
+  hasCustomError: PropTypes.bool,
+  /** Informs user of other errors. */
+  customErrorMessageText: requiredWhen(PropTypes.string, 'hasCustomError'),
   /** Specifies the name of the base input element. */
   name: PropTypes.string,
   /** Selected list item is read-only. */
@@ -351,8 +431,6 @@ FormAutosuggest.propTypes = {
   children: PropTypes.node,
   /** Specifies the screen reader text */
   screenReaderText: PropTypes.string,
-  /** Function that receives the selected value. */
-  onSelected: PropTypes.func,
 };
 
 export default FormAutosuggest;