[Autocomplete] Adding multi sections support

UNRELEASED.md

@@ -14,6 +14,7 @@ Use [the changelog guidelines](https://git.io/polaris-changelog-guidelines) to f
 ### Enhancements
 
 - Added `id` prop to `Layout` and `Heading` for hash linking ([#4307](https://github.com/Shopify/polaris-react/pull/4307))
+- Added support for multi-sectioned options in `Autocomplete` [#4221](https://github.com/Shopify/polaris-react/pull/4221)
 
 ### Bug fixes
 

src/components/Autocomplete/Autocomplete.scss

@@ -7,3 +7,9 @@
   width: 100%;
   padding: spacing(tight) spacing();
 }
+
+.SectionWrapper {
+  > *:not(:first-child) {
+    margin-top: spacing(tight);
+  }
+}

src/components/Autocomplete/Autocomplete.tsx

@@ -1,19 +1,24 @@
 import React, {useMemo, useCallback} from 'react';
+import type {
+  ActionListItemDescriptor,
+  OptionDescriptor,
+  SectionDescriptor,
+} from 'types';
 
-import type {ActionListItemDescriptor} from '../../types';
-import type {OptionDescriptor} from '../OptionList';
 import type {PopoverProps} from '../Popover';
+import {isSection} from '../../utilities/options';
 import {useI18n} from '../../utilities/i18n';
 import {ComboBox} from '../ComboBox';
 import {ListBox} from '../ListBox';
 
-import {MappedOption, MappedAction} from './components';
+import {MappedAction, MappedOption} from './components';
+import styles from './Autocomplete.scss';
 
 export interface AutocompleteProps {
   /** A unique identifier for the Autocomplete */
   id?: string;
   /** Collection of options to be listed */
-  options: OptionDescriptor[];
+  options: SectionDescriptor[] | OptionDescriptor[];
   /** The selected options */
   selected: string[];
   /** The text field component attached to the list of options */
@@ -61,18 +66,56 @@ export const Autocomplete: React.FunctionComponent<AutocompleteProps> & {
 }: AutocompleteProps) {
   const i18n = useI18n();
 
+  const buildMappedOptionFromOption = useCallback(
+    (options: OptionDescriptor[]) => {
+      return options.map((option) => (
+        <MappedOption
+          {...option}
+          key={option.id || option.value}
+          selected={selected.includes(option.value)}
+          singleSelection={!allowMultiple}
+        />
+      ));
+    },
+    [selected, allowMultiple],
+  );
+
   const optionsMarkup = useMemo(() => {
     const conditionalOptions = loading && !willLoadMoreResults ? [] : options;
+
+    if (isSection(conditionalOptions)) {
+      const noOptionsAvailable = conditionalOptions.every(
+        ({options}) => options.length === 0,
+      );
+
+      if (noOptionsAvailable) {
+        return null;
+      }
+
+      const optionsMarkup = conditionalOptions.map(({options, title}) => {
+        if (options.length === 0) {
+          return null;
+        }
+
+        const optionMarkup = buildMappedOptionFromOption(options);
+
+        return (
+          <ListBox.Section
+            divider={false}
+            title={<ListBox.Header>{title}</ListBox.Header>}
+            key={title}
+          >
+            {optionMarkup}
+          </ListBox.Section>
+        );
+      });
+
+      return <div className={styles.SectionWrapper}>{optionsMarkup}</div>;
+    }
+
     const optionList =
       conditionalOptions.length > 0
-        ? conditionalOptions.map((option) => (
-            <MappedOption
-              {...option}
-              key={option.id || option.value}
-              selected={selected.includes(option.value)}
-              singleSelection={!allowMultiple}
-            />
-          ))
+        ? buildMappedOptionFromOption(conditionalOptions)
         : null;
 
     if (listTitle) {
@@ -92,8 +135,7 @@ export const Autocomplete: React.FunctionComponent<AutocompleteProps> & {
     loading,
     options,
     willLoadMoreResults,
-    allowMultiple,
-    selected,
+    buildMappedOptionFromOption,
   ]);
 
   const loadingMarkup = loading ? (

src/components/Autocomplete/README.md

@@ -202,6 +202,101 @@ function MultiAutocompleteExample() {
 }
 ```
 
+### Multiple sections autocomplete
+
+Use to help merchants complete text input quickly from a multiple sections list of options.
+
+```jsx
+function AutocompleteExample() {
+  const deselectedOptions = useMemo(
+    () => [
+      {
+        title: 'Frequently used',
+        options: [
+          {value: 'ups', label: 'UPS'},
+          {value: 'usps', label: 'USPS'},
+        ],
+      },
+      {
+        title: 'All carriers',
+        options: [
+          {value: 'dhl', label: 'DHL Express'},
+          {value: 'canada_post', label: 'Canada Post'},
+        ],
+      },
+    ],
+    [],
+  );
+  const [selectedOptions, setSelectedOptions] = useState([]);
+  const [inputValue, setInputValue] = useState('');
+  const [options, setOptions] = useState(deselectedOptions);
+
+  const updateText = useCallback(
+    (value) => {
+      setInputValue(value);
+
+      if (value === '') {
+        setOptions(deselectedOptions);
+        return;
+      }
+
+      const filterRegex = new RegExp(value, 'i');
+      const resultOptions = [];
+
+      deselectedOptions.forEach((opt) => {
+        const lol = opt.options.filter((option) =>
+          option.label?.match?.(filterRegex),
+        );
+
+        resultOptions.push({
+          title: opt.title,
+          options: lol,
+        });
+      });
+
+      setOptions(resultOptions);
+    },
+    [deselectedOptions],
+  );
+
+  const updateSelection = useCallback(
+    (selected) => {
+      const selectedValue = selected.map((selectedItem) => {
+        const matchedOption = options.find((option) => {
+          return option.value.match(selectedItem);
+        });
+        return matchedOption && matchedOption.label;
+      });
+
+      setSelectedOptions(selected);
+      setInputValue(selectedValue[0]);
+    },
+    [options],
+  );
+
+  const textField = (
+    <Autocomplete.TextField
+      onChange={updateText}
+      label="Tags"
+      value={inputValue}
+      prefix={<Icon source={SearchMinor} color="base" />}
+      placeholder="Search"
+    />
+  );
+
+  return (
+    <div style={{height: '225px'}}>
+      <Autocomplete
+        textField={textField}
+        selected={selectedOptions}
+        options={options}
+        onSelect={updateSelection}
+      />
+    </div>
+  );
+}
+```
+
 ### Autocomplete with loading
 
 Use to indicate loading state to merchants while option data is processing.

src/components/Autocomplete/components/MappedOption/MappedOption.tsx

@@ -1,8 +1,7 @@
 import React, {memo} from 'react';
 
+import type {OptionDescriptor, ArrayElement} from '../../../../types';
 import {ListBox} from '../../../ListBox';
-import type {OptionDescriptor} from '../../../OptionList';
-import type {ArrayElement} from '../../../../types';
 import {classNames} from '../../../../utilities/css';
 
 import styles from './MappedOption.scss';

src/components/Autocomplete/tests/Autocomplete.test.tsx

@@ -3,7 +3,7 @@ import {mountWithApp, ReactTestingElement, CustomRoot} from 'test-utilities';
 import {KeypressListener} from 'components';
 
 import {TextField} from '../../TextField';
-import {Key} from '../../../types';
+import {Key, SectionDescriptor} from '../../../types';
 import {MappedOption, MappedAction} from '../components';
 import {ComboBoxTextFieldContext} from '../../../utilities/combo-box';
 import {Autocomplete} from '../Autocomplete';
@@ -488,6 +488,78 @@ describe('<Autocomplete/>', () => {
     });
   });
 
+  describe('Multiple sections', () => {
+    const multipleSectionsOptions: SectionDescriptor[] = [
+      {
+        title: 'Pizzas',
+        options: [
+          {value: 'cheese_pizza', label: 'Cheese Pizza'},
+          {value: 'macaroni_pizza', label: 'Macaroni Pizza'},
+        ],
+      },
+      {
+        title: 'Pastas',
+        options: [
+          {value: 'spaghetti', label: 'Spaghetti'},
+          {value: 'conchiglie', label: 'Conchiglie'},
+          {value: 'Bucatini', label: 'Bucatini'},
+        ],
+      },
+    ];
+
+    it('renders one ListBox.Option for each option provided on all sections', () => {
+      const allOptionsLength = multipleSectionsOptions.reduce(
+        (lengthAccumulated, {options}) => {
+          return lengthAccumulated + options.length;
+        },
+        0,
+      );
+
+      const autocomplete = mountWithApp(
+        <Autocomplete {...defaultProps} options={multipleSectionsOptions} />,
+      );
+
+      triggerFocus(autocomplete.find(ComboBox));
+
+      expect(autocomplete).toContainReactComponentTimes(
+        ListBox.Option,
+        allOptionsLength,
+      );
+    });
+
+    it('renders one ListBox.Section for each section', () => {
+      const autocomplete = mountWithApp(
+        <Autocomplete {...defaultProps} options={multipleSectionsOptions} />,
+      );
+
+      triggerFocus(autocomplete.find(ComboBox));
+      expect(autocomplete).toContainReactComponentTimes(
+        ListBox.Section,
+        multipleSectionsOptions.length,
+      );
+    });
+
+    it('does not show section options and title if no options are provided', () => {
+      const sectionWithNoOption: SectionDescriptor = {
+        title: 'Candies',
+        options: [],
+      };
+
+      const newOptions = [...multipleSectionsOptions, sectionWithNoOption];
+
+      const autocomplete = mountWithApp(
+        <Autocomplete {...defaultProps} options={newOptions} />,
+      );
+
+      triggerFocus(autocomplete.find(ComboBox));
+
+      expect(autocomplete).toContainReactComponentTimes(
+        ListBox.Section,
+        newOptions.length - 1,
+      );
+    });
+  });
+
   function noop() {}
 
   function renderTextField() {

src/components/OptionList/OptionList.tsx

@@ -1,39 +1,14 @@
 import React, {useState, useCallback} from 'react';
+import type {Descriptor, OptionDescriptor, SectionDescriptor} from 'types';
 
+import {isSection} from '../../utilities/options';
 import {arraysAreEqual} from '../../utilities/arrays';
-import type {IconProps} from '../Icon';
-import type {AvatarProps} from '../Avatar';
-import type {ThumbnailProps} from '../Thumbnail';
 import {useUniqueId} from '../../utilities/unique-id';
 import {useDeepEffect} from '../../utilities/use-deep-effect';
 
 import {Option} from './components';
 import styles from './OptionList.scss';
 
-export interface OptionDescriptor {
-  /** Value of the option */
-  value: string;
-  /** Display label for the option */
-  label: React.ReactNode;
-  /** Whether the option is disabled or not */
-  disabled?: boolean;
-  /** Whether the option is active or not */
-  active?: boolean;
-  /** Unique identifier for the option */
-  id?: string;
-  /** Media to display to the left of the option content */
-  media?: React.ReactElement<IconProps | ThumbnailProps | AvatarProps>;
-}
-
-interface SectionDescriptor {
-  /** Collection of options within the section */
-  options: OptionDescriptor[];
-  /** Section title */
-  title?: string;
-}
-
-type Descriptor = OptionDescriptor | SectionDescriptor;
-
 export interface OptionListProps {
   /** A unique identifier for the option list */
   id?: string;
@@ -179,13 +154,6 @@ function createNormalizedOptions(
   ];
 }
 
-function isSection(arr: Descriptor[]): arr is SectionDescriptor[] {
-  return (
-    typeof arr[0] === 'object' &&
-    Object.prototype.hasOwnProperty.call(arr[0], 'options')
-  );
-}
-
 function optionArraysAreEqual(
   firstArray: Descriptor[],
   secondArray: Descriptor[],

src/components/OptionList/tests/OptionList.test.tsx

@@ -3,7 +3,8 @@ import React from 'react';
 import {mountWithAppProvider} from 'test-utilities/legacy';
 
 import {Option} from '../components';
-import {OptionList, OptionListProps, OptionDescriptor} from '../OptionList';
+import {OptionList, OptionListProps} from '../OptionList';
+import type {OptionDescriptor} from '../../../types';
 
 describe('<OptionList />', () => {
   const defaultProps: OptionListProps = {