@carbon/react 0.17.0 → 1.0.0-rc.0

package/es/components/MultiSelect/next/FilterableMultiSelect.js

@@ -0,0 +1,532 @@
+/**
+ * Copyright IBM Corp. 2016, 2021
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { slicedToArray as _slicedToArray, defineProperty as _defineProperty, extends as _extends, objectSpread2 as _objectSpread2 } from '../../../_virtual/_rollupPluginBabelHelpers.js';
+import { WarningFilled, WarningAltFilled } from '@carbon/icons-react';
+import cx from 'classnames';
+import Downshift from 'downshift';
+import isEqual from 'lodash.isequal';
+import PropTypes from 'prop-types';
+import React__default, { useState, useRef } from 'react';
+import { defaultFilterItems } from '../../ComboBox/tools/filter.js';
+import { sortingPropTypes } from '../MultiSelectPropTypes.js';
+import '../../ListBox/index.js';
+import Selection from '../../../internal/Selection.js';
+import { mapDownshiftProps } from '../../../tools/createPropAdapter.js';
+import { defaultItemToString } from '../tools/itemToString.js';
+import mergeRefs from '../../../tools/mergeRefs.js';
+import { useId } from '../../../internal/useId.js';
+import { defaultCompareItems, defaultSortItems } from '../tools/sorting.js';
+import { useFeatureFlag } from '../../FeatureFlags/index.js';
+import { usePrefix } from '../../../internal/usePrefix.js';
+import { match } from '../../../internal/keyboard/match.js';
+import ListBoxSelection from '../../ListBox/next/ListBoxSelection.js';
+import ListBoxTrigger from '../../ListBox/next/ListBoxTrigger.js';
+import ListBox from '../../ListBox/ListBox.js';
+import { ListBoxSize } from '../../ListBox/ListBoxPropTypes.js';
+import { Space } from '../../../internal/keyboard/keys.js';
+
+var FilterableMultiSelect = /*#__PURE__*/React__default.forwardRef(function FilterableMultiSelect(_ref, ref) {
+  var _cx, _cx2, _cx3, _cx4;
+
+  var ariaLabel = _ref.ariaLabel,
+      containerClassName = _ref.className,
+      compareItems = _ref.compareItems,
+      direction = _ref.direction,
+      disabled = _ref.disabled,
+      downshiftProps = _ref.downshiftProps,
+      filterItems = _ref.filterItems,
+      helperText = _ref.helperText,
+      hideLabel = _ref.hideLabel,
+      id = _ref.id,
+      initialSelectedItems = _ref.initialSelectedItems,
+      invalid = _ref.invalid,
+      invalidText = _ref.invalidText,
+      items = _ref.items,
+      ItemToElement = _ref.itemToElement,
+      itemToString = _ref.itemToString,
+      light = _ref.light,
+      locale = _ref.locale,
+      open = _ref.open,
+      onChange = _ref.onChange,
+      onMenuChange = _ref.onMenuChange,
+      placeholder = _ref.placeholder,
+      titleText = _ref.titleText,
+      type = _ref.type,
+      selectionFeedback = _ref.selectionFeedback,
+      size = _ref.size,
+      sortItems = _ref.sortItems,
+      translateWithId = _ref.translateWithId,
+      useTitleInItem = _ref.useTitleInItem,
+      warn = _ref.warn,
+      warnText = _ref.warnText;
+
+  var _useState = useState(open),
+      _useState2 = _slicedToArray(_useState, 2),
+      isOpen = _useState2[0],
+      setIsOpen = _useState2[1];
+
+  var _useState3 = useState(open),
+      _useState4 = _slicedToArray(_useState3, 2),
+      prevOpen = _useState4[0],
+      setPrevOpen = _useState4[1];
+
+  var _useState5 = useState(''),
+      _useState6 = _slicedToArray(_useState5, 2),
+      inputValue = _useState6[0],
+      setInputValue = _useState6[1];
+
+  var _useState7 = useState([]),
+      _useState8 = _slicedToArray(_useState7, 2),
+      topItems = _useState8[0],
+      setTopItems = _useState8[1];
+
+  var _useState9 = useState(false),
+      _useState10 = _slicedToArray(_useState9, 2),
+      inputFocused = _useState10[0],
+      setInputFocused = _useState10[1];
+
+  var _useState11 = useState(null),
+      _useState12 = _slicedToArray(_useState11, 2),
+      highlightedIndex = _useState12[0],
+      setHighlightedIndex = _useState12[1];
+
+  var textInput = useRef();
+  var filterableMultiSelectInstanceId = useId();
+  var enabled = useFeatureFlag('enable-v11-release');
+  var prefix = usePrefix();
+
+  if (prevOpen !== open) {
+    setIsOpen(open);
+    setPrevOpen(open);
+  }
+
+  var inline = type === 'inline';
+  var showWarning = !invalid && warn;
+  var wrapperClasses = cx("".concat(prefix, "--multi-select__wrapper"), "".concat(prefix, "--list-box__wrapper"), [enabled ? containerClassName : null], (_cx = {}, _defineProperty(_cx, "".concat(prefix, "--multi-select__wrapper--inline"), inline), _defineProperty(_cx, "".concat(prefix, "--list-box__wrapper--inline"), inline), _defineProperty(_cx, "".concat(prefix, "--multi-select__wrapper--inline--invalid"), inline && invalid), _defineProperty(_cx, "".concat(prefix, "--list-box__wrapper--inline--invalid"), inline && invalid), _defineProperty(_cx, "".concat(prefix, "--list-box--up"), direction === 'top'), _cx));
+  var helperId = !helperText ? undefined : "filterablemultiselect-helper-text-".concat(filterableMultiSelectInstanceId);
+  var labelId = "".concat(id, "-label");
+  var titleClasses = cx((_cx2 = {}, _defineProperty(_cx2, "".concat(prefix, "--label"), true), _defineProperty(_cx2, "".concat(prefix, "--label--disabled"), disabled), _defineProperty(_cx2, "".concat(prefix, "--visually-hidden"), hideLabel), _cx2));
+  var helperClasses = cx((_cx3 = {}, _defineProperty(_cx3, "".concat(prefix, "--form__helper-text"), true), _defineProperty(_cx3, "".concat(prefix, "--form__helper-text--disabled"), disabled), _cx3));
+  var inputClasses = cx((_cx4 = {}, _defineProperty(_cx4, "".concat(prefix, "--text-input"), true), _defineProperty(_cx4, "".concat(prefix, "--text-input--empty"), !inputValue), _defineProperty(_cx4, "".concat(prefix, "--text-input--light"), light), _cx4));
+  var helper = helperText ? /*#__PURE__*/React__default.createElement("div", {
+    id: helperId,
+    className: helperClasses
+  }, helperText) : null;
+  var menuId = "".concat(id, "__menu");
+  var inputId = "".concat(id, "-input");
+
+  function handleOnChange(changes) {
+    if (onChange) {
+      onChange(changes);
+    }
+  }
+
+  function handleOnMenuChange(forceIsOpen) {
+    var nextIsOpen = forceIsOpen !== null && forceIsOpen !== void 0 ? forceIsOpen : !isOpen;
+    setIsOpen(nextIsOpen);
+
+    if (onMenuChange) {
+      onMenuChange(nextIsOpen);
+    }
+  }
+
+  function handleOnOuterClick() {
+    handleOnMenuChange(false);
+  }
+
+  function handleOnStateChange(changes, downshift) {
+    if (changes.isOpen && !isOpen) {
+      setTopItems(downshift.selectedItem);
+    }
+
+    var type = changes.type;
+    var stateChangeTypes = Downshift.stateChangeTypes;
+
+    switch (type) {
+      case stateChangeTypes.keyDownArrowDown:
+      case stateChangeTypes.keyDownArrowUp:
+      case stateChangeTypes.keyDownHome:
+      case stateChangeTypes.keyDownEnd:
+        setHighlightedIndex(changes.highlightedIndex !== undefined ? changes.highlightedIndex : null);
+
+        if (stateChangeTypes.keyDownArrowDown === type && !isOpen) {
+          handleOnMenuChange(true);
+        }
+
+        break;
+
+      case stateChangeTypes.keyDownEscape:
+        handleOnMenuChange(false);
+        break;
+    }
+  }
+
+  function handleOnInputValueChange(inputValue, _ref2) {
+    var type = _ref2.type;
+
+    if (type !== Downshift.stateChangeTypes.changeInput) {
+      return;
+    }
+
+    if (Array.isArray(inputValue)) {
+      clearInputValue();
+    } else {
+      setInputValue(inputValue);
+    }
+
+    if (inputValue && !isOpen) {
+      handleOnMenuChange(true);
+    } else if (!inputValue && isOpen) {
+      handleOnMenuChange(false);
+    }
+  }
+
+  function clearInputValue() {
+    setInputValue('');
+
+    if (textInput.current) {
+      textInput.current.focus();
+    }
+  }
+
+  return /*#__PURE__*/React__default.createElement(Selection, {
+    disabled: disabled,
+    onChange: handleOnChange,
+    initialSelectedItems: initialSelectedItems,
+    render: function render(_ref3) {
+      var selectedItems = _ref3.selectedItems,
+          onItemChange = _ref3.onItemChange,
+          _clearSelection = _ref3.clearSelection;
+      return /*#__PURE__*/React__default.createElement(Downshift, _extends({}, mapDownshiftProps(downshiftProps), {
+        highlightedIndex: highlightedIndex,
+        id: id,
+        isOpen: isOpen,
+        inputValue: inputValue,
+        onInputValueChange: handleOnInputValueChange,
+        onChange: function onChange(selectedItem) {
+          if (selectedItem !== null) {
+            onItemChange(selectedItem);
+          }
+        },
+        itemToString: itemToString,
+        onStateChange: handleOnStateChange,
+        onOuterClick: handleOnOuterClick,
+        selectedItem: selectedItems,
+        labelId: labelId,
+        menuId: menuId,
+        inputId: inputId
+      }), function (_ref4) {
+        var _cx5;
+
+        var getInputProps = _ref4.getInputProps,
+            getItemProps = _ref4.getItemProps,
+            getLabelProps = _ref4.getLabelProps,
+            getMenuProps = _ref4.getMenuProps,
+            getRootProps = _ref4.getRootProps,
+            getToggleButtonProps = _ref4.getToggleButtonProps,
+            isOpen = _ref4.isOpen,
+            inputValue = _ref4.inputValue,
+            selectedItem = _ref4.selectedItem;
+        var className = cx("".concat(prefix, "--multi-select"), "".concat(prefix, "--combo-box"), "".concat(prefix, "--multi-select--filterable"), [enabled ? null : containerClassName], (_cx5 = {}, _defineProperty(_cx5, "".concat(prefix, "--multi-select--invalid"), invalid), _defineProperty(_cx5, "".concat(prefix, "--multi-select--open"), isOpen), _defineProperty(_cx5, "".concat(prefix, "--multi-select--inline"), inline), _defineProperty(_cx5, "".concat(prefix, "--multi-select--selected"), selectedItem.length > 0), _defineProperty(_cx5, "".concat(prefix, "--multi-select--filterable--input-focused"), inputFocused), _cx5));
+        var rootProps = getRootProps({}, {
+          suppressRefError: true
+        });
+        var labelProps = getLabelProps();
+        var buttonProps = getToggleButtonProps({
+          disabled: disabled,
+          onClick: function onClick() {
+            handleOnMenuChange(!isOpen);
+
+            if (textInput.current) {
+              textInput.current.focus();
+            }
+          },
+          // When we moved the "root node" of Downshift to the <input> for
+          // ARIA 1.2 compliance, we unfortunately hit this branch for the
+          // "mouseup" event that downshift listens to:
+          // https://github.com/downshift-js/downshift/blob/v5.2.1/src/downshift.js#L1051-L1065
+          //
+          // As a result, it will reset the state of the component and so we
+          // stop the event from propagating to prevent this. This allows the
+          // toggleMenu behavior for the toggleButton to correctly open and
+          // close the menu.
+          onMouseUp: function onMouseUp(event) {
+            event.stopPropagation();
+          }
+        });
+        var inputProps = getInputProps({
+          'aria-controls': isOpen ? menuId : null,
+          'aria-describedby': helperText ? helperId : null,
+          // Remove excess aria `aria-labelledby`. HTML <label for>
+          // provides this aria information.
+          'aria-labelledby': null,
+          disabled: disabled,
+          placeholder: placeholder,
+          onClick: function onClick() {
+            handleOnMenuChange(true);
+          },
+          onKeyDown: function onKeyDown(event) {
+            if (match(event, Space)) {
+              event.stopPropagation();
+            }
+          },
+          onFocus: function onFocus() {
+            setInputFocused(true);
+          },
+          onBlur: function onBlur() {
+            setInputFocused(false);
+          }
+        });
+        var menuProps = getMenuProps({
+          'aria-label': ariaLabel
+        }, {
+          suppressRefError: true
+        });
+        return /*#__PURE__*/React__default.createElement("div", {
+          className: wrapperClasses
+        }, titleText ? /*#__PURE__*/React__default.createElement("label", _extends({
+          className: titleClasses
+        }, labelProps), titleText) : null, /*#__PURE__*/React__default.createElement(ListBox, {
+          className: className,
+          disabled: disabled,
+          light: light,
+          ref: ref,
+          invalid: invalid,
+          invalidText: invalidText,
+          warn: warn,
+          warnText: warnText,
+          isOpen: isOpen,
+          size: size
+        }, /*#__PURE__*/React__default.createElement("div", {
+          className: "".concat(prefix, "--list-box__field")
+        }, selectedItem.length > 0 && /*#__PURE__*/React__default.createElement(ListBoxSelection, {
+          clearSelection: function clearSelection() {
+            _clearSelection();
+
+            if (textInput.current) {
+              textInput.current.focus();
+            }
+          },
+          selectionCount: selectedItem.length,
+          translateWithId: translateWithId,
+          disabled: disabled
+        }), /*#__PURE__*/React__default.createElement("input", _extends({
+          className: inputClasses
+        }, rootProps, inputProps, {
+          ref: mergeRefs(textInput, rootProps.ref)
+        })), invalid && /*#__PURE__*/React__default.createElement(WarningFilled, {
+          className: "".concat(prefix, "--list-box__invalid-icon")
+        }), showWarning && /*#__PURE__*/React__default.createElement(WarningAltFilled, {
+          className: "".concat(prefix, "--list-box__invalid-icon ").concat(prefix, "--list-box__invalid-icon--warning")
+        }), inputValue && /*#__PURE__*/React__default.createElement(ListBoxSelection, {
+          clearSelection: clearInputValue,
+          disabled: disabled,
+          translateWithId: translateWithId,
+          onMouseUp: function onMouseUp(event) {
+            // If we do not stop this event from propagating,
+            // it seems like Downshift takes our event and
+            // prevents us from getting `onClick` /
+            // `clearSelection` from the underlying <button> in
+            // ListBoxSelection
+            event.stopPropagation();
+          }
+        }), /*#__PURE__*/React__default.createElement(ListBoxTrigger, _extends({}, buttonProps, {
+          isOpen: isOpen,
+          translateWithId: translateWithId
+        }))), isOpen ? /*#__PURE__*/React__default.createElement(ListBox.Menu, menuProps, sortItems(filterItems(items, {
+          itemToString: itemToString,
+          inputValue: inputValue
+        }), {
+          selectedItems: {
+            top: selectedItems,
+            fixed: [],
+            'top-after-reopen': topItems
+          }[selectionFeedback],
+          itemToString: itemToString,
+          compareItems: compareItems,
+          locale: locale
+        }).map(function (item, index) {
+          var itemProps = getItemProps({
+            item: item,
+            disabled: item.disabled
+          });
+          var itemText = itemToString(item);
+          var isChecked = selectedItem.filter(function (selected) {
+            return isEqual(selected, item);
+          }).length > 0;
+          return /*#__PURE__*/React__default.createElement(ListBox.MenuItem, _extends({
+            key: itemProps.id,
+            "aria-label": itemText,
+            isActive: isChecked,
+            isHighlighted: highlightedIndex === index,
+            title: itemText
+          }, itemProps), /*#__PURE__*/React__default.createElement("div", {
+            className: "".concat(prefix, "--checkbox-wrapper")
+          }, /*#__PURE__*/React__default.createElement("span", {
+            title: useTitleInItem ? itemText : null,
+            className: "".concat(prefix, "--checkbox-label"),
+            "data-contained-checkbox-state": isChecked,
+            id: "".concat(itemProps.id, "-item")
+          }, ItemToElement ? /*#__PURE__*/React__default.createElement(ItemToElement, _extends({
+            key: itemProps.id
+          }, item)) : itemText)));
+        })) : null), !inline && !invalid && !warn ? helper : null);
+      });
+    }
+  });
+});
+FilterableMultiSelect.propTypes = _objectSpread2(_objectSpread2({
+  /**
+   * 'aria-label' of the ListBox component.
+   */
+  ariaLabel: PropTypes.string,
+
+  /**
+   * Specify the direction of the multiselect dropdown. Can be either top or bottom.
+   */
+  direction: PropTypes.oneOf(['top', 'bottom']),
+
+  /**
+   * Disable the control
+   */
+  disabled: PropTypes.bool,
+
+  /**
+   * Additional props passed to Downshift
+   */
+  downshiftProps: PropTypes.shape(Downshift.propTypes),
+
+  /**
+   * Specify whether the title text should be hidden or not
+   */
+  hideLabel: PropTypes.bool,
+
+  /**
+   * Specify a custom `id`
+   */
+  id: PropTypes.string.isRequired,
+
+  /**
+   * Allow users to pass in arbitrary items from their collection that are
+   * pre-selected
+   */
+  initialSelectedItems: PropTypes.array,
+
+  /**
+   * Is the current selection invalid?
+   */
+  invalid: PropTypes.bool,
+
+  /**
+   * If invalid, what is the error?
+   */
+  invalidText: PropTypes.node,
+
+  /**
+   * Function to render items as custom components instead of strings.
+   * Defaults to null and is overridden by a getter
+   */
+  itemToElement: PropTypes.func,
+
+  /**
+   * Helper function passed to downshift that allows the library to render a
+   * given item to a string label. By default, it extracts the `label` field
+   * from a given item to serve as the item label in the list.
+   */
+  itemToString: PropTypes.func,
+
+  /**
+   * We try to stay as generic as possible here to allow individuals to pass
+   * in a collection of whatever kind of data structure they prefer
+   */
+  items: PropTypes.array.isRequired,
+
+  /**
+   * `true` to use the light version.
+   */
+  light: PropTypes.bool,
+
+  /**
+   * Specify the locale of the control. Used for the default `compareItems`
+   * used for sorting the list of items in the control.
+   */
+  locale: PropTypes.string,
+
+  /**
+   * `onChange` is a utility for this controlled component to communicate to a
+   * consuming component what kind of internal state changes are occurring.
+   */
+  onChange: PropTypes.func,
+
+  /**
+   * `onMenuChange` is a utility for this controlled component to communicate to a
+   * consuming component that the menu was opened(`true`)/closed(`false`).
+   */
+  onMenuChange: PropTypes.func,
+
+  /**
+   * Initialize the component with an open(`true`)/closed(`false`) menu.
+   */
+  open: PropTypes.bool,
+
+  /**
+   * Generic `placeholder` that will be used as the textual representation of
+   * what this field is for
+   */
+  placeholder: PropTypes.string,
+
+  /**
+   * Specify feedback (mode) of the selection.
+   * `top`: selected item jumps to top
+   * `fixed`: selected item stays at it's position
+   * `top-after-reopen`: selected item jump to top after reopen dropdown
+   */
+  selectionFeedback: PropTypes.oneOf(['top', 'fixed', 'top-after-reopen']),
+
+  /**
+   * Specify the size of the ListBox. Currently supports either `sm`, `md` or `lg` as an option.
+   */
+  size: ListBoxSize
+}, sortingPropTypes), {}, {
+  /**
+   * Callback function for translating ListBoxMenuIcon SVG title
+   */
+  translateWithId: PropTypes.func,
+
+  /**
+   * Specify title to show title on hover
+   */
+  useTitleInItem: PropTypes.bool,
+
+  /**
+   * Specify whether the control is currently in warning state
+   */
+  warn: PropTypes.bool,
+
+  /**
+   * Provide the text that is displayed when the control is in warning state
+   */
+  warnText: PropTypes.node
+});
+FilterableMultiSelect.defaultProps = {
+  ariaLabel: 'Choose an item',
+  compareItems: defaultCompareItems,
+  direction: 'bottom',
+  disabled: false,
+  filterItems: defaultFilterItems,
+  initialSelectedItems: [],
+  itemToString: defaultItemToString,
+  locale: 'en',
+  sortItems: defaultSortItems,
+  light: false,
+  open: false,
+  selectionFeedback: 'top-after-reopen'
+};
+var FilterableMultiSelectNext = FilterableMultiSelect;
+
+export { FilterableMultiSelectNext as default };

package/es/components/MultiSelect/tools/itemToString.js

@@ -0,0 +1,24 @@
+/**
+ * Copyright IBM Corp. 2016, 2021
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { typeof as _typeof } from '../../../_virtual/_rollupPluginBabelHelpers.js';
+import invariant from 'invariant';
+
+var itemToString = function itemToString(item) {
+  !(typeof item.label === 'string') ? process.env.NODE_ENV !== "production" ? invariant(false, '[MultiSelect] the default `itemToString` method expected to receive ' + 'an item with a `label` field of type `string`. Instead received: `%s`', _typeof(item.label)) : invariant(false) : void 0;
+  return item.label || '';
+};
+
+var defaultItemToString = function defaultItemToString(item) {
+  if (Array.isArray(item)) {
+    return item.map(itemToString);
+  }
+
+  return itemToString(item);
+};
+
+export { defaultItemToString };

package/es/components/MultiSelect/tools/sorting.js

@@ -0,0 +1,53 @@
+/**
+ * Copyright IBM Corp. 2016, 2021
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Use the local `localCompare` with the `numeric` option to sort two,
+ * potentially alpha-numeric, strings in a list of items.
+ *
+ * @param {string} itemA
+ * @param {string} itemB
+ * @param {object} options
+ * @param {string} options.locale
+ * @returns {number}
+ */
+var defaultCompareItems = function defaultCompareItems(itemA, itemB, _ref) {
+  var locale = _ref.locale;
+  return itemA.localeCompare(itemB, locale, {
+    numeric: true
+  });
+};
+/**
+ * Default sorting algorithm for options in a selection control
+ */
+
+var defaultSortItems = function defaultSortItems(items, _ref2) {
+  var _ref2$selectedItems = _ref2.selectedItems,
+      selectedItems = _ref2$selectedItems === void 0 ? [] : _ref2$selectedItems,
+      itemToString = _ref2.itemToString,
+      compareItems = _ref2.compareItems,
+      _ref2$locale = _ref2.locale,
+      locale = _ref2$locale === void 0 ? 'en' : _ref2$locale;
+  return items.sort(function (itemA, itemB) {
+    var hasItemA = selectedItems.includes(itemA);
+    var hasItemB = selectedItems.includes(itemB); // Prefer whichever item is in the `selectedItems` array first
+
+    if (hasItemA && !hasItemB) {
+      return -1;
+    }
+
+    if (hasItemB && !hasItemA) {
+      return 1;
+    }
+
+    return compareItems(itemToString(itemA), itemToString(itemB), {
+      locale: locale
+    });
+  });
+};
+
+export { defaultCompareItems, defaultSortItems };