feat(dropdowns): introduce Multiselect component (#439)

Author: Austin Green

.lintstagedrc

@@ -0,0 +1,18 @@
+{
+  "*.{js,ts,tsx}": [
+    "stylelint",
+    "eslint",
+    "jest --config=utils/test/jest.config.js --findRelatedTests",
+    "prettier --write",
+    "git add"
+  ],
+  "!(*CHANGELOG).md": [
+    "markdownlint",
+    "prettier --write",
+    "git add"
+  ],
+  "**/package.json": [
+    "prettier-package-json --write",
+    "git add"
+  ]
+}

lint-staged.config.js

@@ -0,0 +1,138 @@
+The `Multiselect` component renders a customizable "tag" for each selected item.
+
+This can be any element, but the surrounding field is designed to work with
+our standard `Tag` component.
+
+```jsx static
+<Dropdown>
+  <Field>
+    <Label>Example Multiselect</Label>
+    <Multiselect
+      renderItem={({ value, removeValue }) => (
+        <Tag size="large">
+          {value} <Close onClick={() => removeValue()} />
+        </Tag>
+      )}
+    />
+  </Field>
+  <Menu>{/** customizable items **/}</Menu>
+</Dropdown>
+```
+
+```js
+const debounce = require('lodash.debounce');
+const { Tag, Close } = require('@zendeskgarden/react-tags/src');
+
+const options = [
+  'Aster',
+  "Bachelor's button",
+  'Celosia',
+  'Dusty miller',
+  'Everlasting winged',
+  "Four o'clock",
+  'Geranium',
+  'Honesty',
+  'Impatiens',
+  'Johnny jump-up',
+  'Kale',
+  'Lobelia',
+  'Marigold',
+  'Nasturtium',
+  'Ocimum (basil)',
+  'Petunia',
+  'Quaking grass',
+  'Rose moss',
+  'Salvia',
+  'Torenia',
+  'Ursinia',
+  'Verbena',
+  'Wax begonia',
+  'Xeranthemum',
+  'Yellow cosmos',
+  'Zinnia'
+];
+
+function ExampleAutocomplete() {
+  const [selectedItems, setSelectedItems] = React.useState([
+    options[0],
+    options[1],
+    options[2],
+    options[3],
+    options[4],
+    options[5]
+  ]);
+  const [inputValue, setInputValue] = React.useState('');
+  const [isLoading, setIsLoading] = React.useState(false);
+  const [matchingOptions, setMatchingOptions] = React.useState(options);
+
+  /**
+   * Debounce filtering
+   */
+  const filterMatchingOptionsRef = React.useRef(
+    debounce(value => {
+      const matchingOptions = options.filter(option => {
+        return (
+          option
+            .trim()
+            .toLowerCase()
+            .indexOf(value.trim().toLowerCase()) !== -1
+        );
+      });
+
+      setMatchingOptions(matchingOptions);
+      setIsLoading(false);
+    }, 300)
+  );
+
+  React.useEffect(() => {
+    setIsLoading(true);
+    filterMatchingOptionsRef.current(inputValue);
+  }, [inputValue]);
+
+  const renderOptions = () => {
+    if (isLoading) {
+      return <Item disabled>Loading items...</Item>;
+    }
+
+    if (matchingOptions.length === 0) {
+      return <Item disabled>No matches found</Item>;
+    }
+
+    return matchingOptions.map(option => (
+      <Item key={option} value={option}>
+        <span>{option}</span>
+      </Item>
+    ));
+  };
+
+  return (
+    <Dropdown
+      inputValue={inputValue}
+      selectedItems={selectedItems}
+      onSelect={items => setSelectedItems(items)}
+      downshiftProps={{ defaultHighlightedIndex: 0 }}
+      onStateChange={changes => {
+        if (Object.prototype.hasOwnProperty.call(changes, 'inputValue')) {
+          setInputValue(changes.inputValue);
+        }
+      }}
+    >
+      <Field>
+        <Label>Multiselect with debounce</Label>
+        <Hint>This example includes basic debounce logic</Hint>
+        <Multiselect
+          small
+          renderItem={({ value, removeValue }) => (
+            <Tag>
+              {value} <Close onClick={() => removeValue()} />
+            </Tag>
+          )}
+        />
+      </Field>
+      <Menu small>{renderOptions()}</Menu>
+    </Dropdown>
+  );
+}
+
+<ExampleAutocomplete />;
+```

packages/dropdowns/src/examples/autocomplete.md renamed to packages/dropdowns/examples/autocomplete.md

@@ -20,6 +20,7 @@
   },
   "types": "./dist/typings/index.d.ts",
   "dependencies": {
+    "@zendeskgarden/container-selection": "^1.1.5",
     "@zendeskgarden/container-utilities": "^0.1.2",
     "classnames": "^2.2.5",
     "downshift": "^3.2.7",
@@ -51,6 +52,6 @@
     "access": "public"
   },
   "zendeskgarden:library": "GardenDropdowns",
-  "zendeskgarden:max_size": "31 kB",
+  "zendeskgarden:max_size": "35 kB",
   "zendeskgarden:src": "src/index.ts"
 }

packages/dropdowns/src/examples/examples.md renamed to packages/dropdowns/examples/examples.md

@@ -37,20 +37,6 @@ const ExampleDropdown = (props: IDropdownProps) => (
 
 describe('Dropdown', () => {
   describe('Custom keyboard nav', () => {
-    it('selects item on TAB key', () => {
-      const onSelectSpy = jest.fn();
-      const { container, getByTestId } = render(<ExampleDropdown onSelect={onSelectSpy} />);
-
-      const trigger = getByTestId('trigger');
-      const input = container.querySelector('input');
-
-      fireEvent.click(trigger);
-      fireEvent.keyDown(input!, { key: 'ArrowDown', keyCode: 40 });
-      fireEvent.keyDown(input!, { key: 'Tab', keyCode: 9 });
-
-      expect(onSelectSpy.mock.calls[0][0]).toBe('previous-item');
-    });
-
     it('selects previous item on left arrow key in LTR mode', () => {
       const onSelectSpy = jest.fn();
       const { container, getByTestId } = render(<ExampleDropdown onSelect={onSelectSpy} />);

packages/dropdowns/src/examples/menu.md renamed to packages/dropdowns/examples/menu.md

@@ -12,6 +12,9 @@ import { Manager } from 'react-popper';
 import { withTheme, isRtl } from '@zendeskgarden/react-theming';
 import { KEY_CODES, composeEventHandlers } from '@zendeskgarden/container-utilities';
 
+export const REMOVE_ITEM_STATE_TYPE = 'REMOVE_ITEM';
+export const TAB_SELECT_ITEM_STATE_TYPE = 'TAB_ITEM';
+
 export interface IDropdownContext {
   itemIndexRef: React.MutableRefObject<number>;
   previousItemRef: React.MutableRefObject<any>;
@@ -20,6 +23,7 @@ export interface IDropdownContext {
   popperReferenceElementRef: React.MutableRefObject<any>;
   selectedItems?: any[];
   downshift: ControllerStateAndHelpers<any>;
+  containsMultiselectRef: React.MutableRefObject<boolean>;
 }
 
 export const DropdownContext = React.createContext<IDropdownContext | undefined>(undefined);
@@ -64,32 +68,30 @@ const Dropdown: React.FunctionComponent<IDropdownProps> = props => {
   const previousItemRef = useRef<number | undefined>(undefined);
   const previousIndexRef = useRef<number | undefined>(undefined);
   const nextItemsHashRef = useRef<object>({});
+  const containsMultiselectRef = useRef(false);
 
   // Used to inform Menu (Popper) that a full-width menu is needed
   const popperReferenceElementRef = useRef<any>(null);
 
   /**
    * Add additional keyboard nav to the basics provided by Downshift
    **/
-  const customGetInputProps = ({ onKeyDown, ...other }: any, downshift: any, rtl: any) => {
+  const customGetInputProps = (
+    { onKeyDown, ...other }: any,
+    downshift: ControllerStateAndHelpers<any>,
+    rtl: any
+  ) => {
     return {
-      onKeyDown: composeEventHandlers(onKeyDown, (e: any) => {
+      onKeyDown: composeEventHandlers(onKeyDown, (e: KeyboardEvent) => {
         const PREVIOUS_KEY = rtl ? KEY_CODES.RIGHT : KEY_CODES.LEFT;
         const NEXT_KEY = rtl ? KEY_CODES.LEFT : KEY_CODES.RIGHT;
 
         if (downshift.isOpen) {
-          // Select highlighted item on TAB
-          if (e.keyCode === KEY_CODES.TAB) {
-            e.preventDefault();
-            e.stopPropagation();
-
-            downshift.selectHighlightedItem();
-          }
-
           // Select previous item if available
           if (
             e.keyCode === PREVIOUS_KEY &&
             previousIndexRef.current !== null &&
+            previousIndexRef.current !== undefined &&
             !downshift.inputValue
           ) {
             e.preventDefault();
@@ -106,7 +108,7 @@ const Dropdown: React.FunctionComponent<IDropdownProps> = props => {
               e.preventDefault();
               e.stopPropagation();
 
-              downshift.selectItemAtIndex(downshift.highlightedIndex);
+              downshift.selectItemAtIndex(downshift.highlightedIndex!);
             }
           }
         } else if (
@@ -184,15 +186,26 @@ const Dropdown: React.FunctionComponent<IDropdownProps> = props => {
           switch (changes.type) {
             case Downshift.stateChangeTypes.controlledPropUpdatedSelectedItem:
             case Downshift.stateChangeTypes.mouseUp:
-            case Downshift.stateChangeTypes.keyDownEnter:
-            case Downshift.stateChangeTypes.clickItem:
-            case Downshift.stateChangeTypes.clickButton:
             case Downshift.stateChangeTypes.keyDownSpaceButton:
             case Downshift.stateChangeTypes.blurButton:
               return {
                 ...changes,
                 inputValue: ''
               };
+            case Downshift.stateChangeTypes.keyDownEnter:
+            case Downshift.stateChangeTypes.clickItem:
+            case TAB_SELECT_ITEM_STATE_TYPE as any: {
+              const updatedState = { ...changes, inputValue: '' };
+
+              if (containsMultiselectRef.current) {
+                updatedState.isOpen = true;
+                updatedState.highlightedIndex = _state.highlightedIndex;
+              }
+
+              return updatedState;
+            }
+            case REMOVE_ITEM_STATE_TYPE as any:
+              return { ...changes, isOpen: false };
             default:
               return changes;
           }
@@ -208,7 +221,8 @@ const Dropdown: React.FunctionComponent<IDropdownProps> = props => {
               nextItemsHashRef,
               popperReferenceElementRef,
               selectedItems,
-              downshift: transformDownshift(downshift)
+              downshift: transformDownshift(downshift),
+              containsMultiselectRef
             }}
           >
             {children}