Build an async combobox based on react-select

[productdana]

Hello Paste team!

I've tried building an async combobox using the Combobox in paste to mimic the existing Async Subuser Select in SendGrid (based on react-select) but the logic is complicated and it seems like reinventing the wheel. The select we need should do a fetch whenever the input changes as we want a prefix search. As the input changes if the input matches any existing options it will filter for those options while still fetching in the background. If the input clears it shows the initial default options. The issues I'm running into with Combobox are timing issues (i.e. as user types in inputs and blanks it out quickly, it shows default options which then get overwritten by new options after the fetch completes). It gets a little tricky trying to only show "Loading..." as the only option if the input does not have a prefix match with any existing options too. We've also noticed a fetch still happens after selecting an option, and when we tried adding a check for whether or not the dropdown is open before fetching, we ran into more unexpected behavior.

We've decided to dial back on matching the same behavior as react-select with Combobox for now. However I was wondering if we've considered making an async select component in paste based on react-select.

[serifluous]

Hey @productdana , we're having a bit of trouble nailing down exactly which blockers you're having with the current combobox. Can you share a CodeSandbox example of how far you were able to get (if at all) with the Paste Combobox in achieving the things you're trying to do with Combobox? A list of the issues and what you tried so far would help, too!

[productdana]

Hey @serifluous do you happen to have access to SendGrid repos? https://github.com/sendgrid/mako/pull/3524/files is the PR (already merged). If you're able to pull it down you can run storybook. I was trying to mimic a react-select integration we use on a page in SendGrid that works as expected. We're fetching a list of users each time the input changes and the options displayed should be filtered based on prefix matching. If the input is blank we want to display all the default options (in the demo it's the list of subusers). If a user types something and then clears it out, sometimes the default options get overwritten after the fetch of new subusers finishes. Although it has a debounced fetch on input change, we want to show "Loading..." only if the current input doesn't prefix match the existing options. I tried using an isOpen check before the debounced fetch in onInputValueChange but that led to more funky behavior.

So the logic within onInputValueChange and onIsOpenChange needs some work still, and right now we're probably going to simplify it by showing "Loading..." whenever we're fetching and letting it fetch on future empty inputs too. React-select already does what we need it to do so it'd be nice if we can use that lib. I tried all this with the basic Combobox first by the way (without the useCombobox) and had issues with highlighted item not working as expected so switched to useCombobox.

[SiTaggart]

Hi @productdana

We don't have have access I'm afraid.

We did choose Downshift over all other combobox alternative specifically because it was much more closely aligned to the W3C ARIA spec, and much more flexible to our consuming teams. Via inversion of control, it allows us to support more teams, without creating a bottle neck on our team for additional specific data requirements or interactions.

What that does mean though, is there is an emphasis on the consuming team when they upgrade or switch, to do much more of the lifting. We're happy with this trade off for now as we're in no position to know how each business unit or product we support (All Console teams, Flex, SG etc) needs to handle their data and we're a super small team.

The downshift docs and community are pretty great too. We don't really do much to it apart from wrap it and rename somethings. Otherwise we expose the useCombobox hook "as is" for you to work with to meet your data requirements. It just means that for your team, moving from react-select is going to be some extra work because the APIs are totally different.

We'd be happy to support and learn from you during that process, especially around specific blockers, or bugs you encounter We've had a number of teams adopt it so far and we're always learning.

[productdana]

Hi @SiTaggart
Thanks for explaining the reasons for choosing Downshift. I think we may have been able to get combobox working good enough actually.

import React, { useState, useMemo, useCallback } from 'react';
import { Box } from '@twilio-paste/core/dist/box';
import { Combobox, useCombobox } from '@twilio-paste/core/combobox';
import debounce from 'lodash/debounce';
import { sortAlphabetically } from '../../../../../helpers/sortAlphabetically';
import { getSubusers, SubuserDto } from '../../services/getSubusers';
import './index.scss';

export interface AccountOption {
  label: string;
  username: string;
  isParent: boolean;
}

const loadingMsg = 'Loading...';
const noResultsFoundMsg = 'No results found.';

const noResultsFoundOption: AccountOption = {
  label: noResultsFoundMsg,
  username: '',
  isParent: false,
};
const loadingOption: AccountOption = {
  label: loadingMsg,
  username: '',
  isParent: false,
};

export interface AsyncComboboxProps {
  parentUsername: string;
  subusers: SubuserDto[];
  updateAccountOption: (username: string) => void;
}

export const AsyncCombobox: React.FC<AsyncComboboxProps> = ({
  parentUsername,
  subusers = [],
  updateAccountOption,
}) => {
  const parentOption = useMemo(() => {
    const option: AccountOption = {
      label: `${parentUsername} (parent)`,
      username: parentUsername,
      isParent: true,
    };

    return option;
  }, [parentUsername]);

  const formSubuserOptions = (subusersDto: SubuserDto[]): AccountOption[] =>
    subusersDto
      .map((subuserDto) => {
        const { username } = subuserDto;
        return {
          username,
          label: username,
          isParent: false,
        };
      })
      .sort((a: AccountOption, b: AccountOption) =>
        sortAlphabetically(a.username, b.username)
      );

  const subuserOptions = formSubuserOptions(subusers);
  const defaultOptions = [parentOption, ...subuserOptions];

  const [inputItems, setInputItems] = useState<AccountOption[]>(defaultOptions);
  const [hasError, setHasError] = useState(false);
  const [value, setValue] = useState(parentOption.username);
  const [selectedItem, setSelectedItem] = useState(parentOption);

  const handleOnSelectedItemChange = (changes: any) => {
    // workaround to disabling loading and no results options
    const isSelectableOption =
      changes.selectedItem.label !== loadingMsg &&
      changes.selectedItem.label !== noResultsFoundMsg;

    if (isSelectableOption) {
      setSelectedItem(changes.selectedItem);
      setInputItems(defaultOptions);
      // Call the parent update account callback prop too
      updateAccountOption(changes.selectedItem.username);
    }
  };

  const isInputValid = (inputValue: string, options: AccountOption[]) => {
    const validInput = options.find((option) => option.username === inputValue);
    return Boolean(validInput);
  };

  const hasValidInput = isInputValid(value, defaultOptions);

  const handleOnIsOpenChange = (changes: any) => {
    setInputItems(defaultOptions);
    if (!changes.isOpen && !hasValidInput) {
      // reset to last valid selection if input is invalid when dropdown is closed
      setValue(selectedItem.username);
    }
  };

  // input value will reference username but options in the dropdown will reference label
  const handleItemToString = (item: AccountOption) =>
    item ? item.username : '';

  // show filtered options that start with input (prefix match)
  const filterOptions = (currentInputValue: string, options: AccountOption[]) =>
    options.filter((item) =>
      item.username.toLowerCase().startsWith(currentInputValue.toLowerCase())
    );

  const handleError = () => {
    setHasError(true);
    closeMenu();
  };

  const getAllOptions = (inputVal: string) => {
    getSubusers(inputVal, handleError)
      .then((fetchedSubusers) => {
        const newSubuserOptions = formSubuserOptions(fetchedSubusers);
        const allOptions = [parentOption, ...newSubuserOptions];
        const optionsWithPrefixMatch = filterOptions(inputVal, allOptions);
        if (optionsWithPrefixMatch.length === 0) {
          setInputItems([noResultsFoundOption]);
        } else {
          setInputItems(optionsWithPrefixMatch);
        }
      })
      .catch((e) => {
        console.error('Error in getAllOptions:', e);
      });
  };

  const debouncedGetSubusers = useCallback(
    debounce((inputVal: string) => getAllOptions(inputVal), 300),
    []
  );
  const handleOnInputValueChange = ({ inputValue = '', isOpen = false }) => {
    setValue(inputValue);
    setHasError(false);

    // selecting an item triggers handleOnInputValueChange and we only care to fetch when dropdown is open
    if (isOpen) {
      setInputItems([loadingOption]);
      debouncedGetSubusers(inputValue);
    }
  };

  const { closeMenu, ...state } = useCombobox({
    items: inputItems,
    itemToString: handleItemToString,
    onIsOpenChange: handleOnIsOpenChange,
    onSelectedItemChange: handleOnSelectedItemChange,
    onInputValueChange: handleOnInputValueChange,
    inputValue: value,
    circularNavigation: true,
    defaultHighlightedIndex: inputItems.findIndex(
      (item) => item.username === selectedItem.username
    ),
    selectedItem,
  });

  return (
    <Box className="async-combobox-subuser">
      <Combobox
        state={state}
        items={inputItems}
        autocomplete
        labelText={<strong>Account</strong>}
        helpText={hasError ? 'Failed to fetch accounts. Please retry.' : ''}
        hasError={hasError}
        optionTemplate={(item: AccountOption) => <div>{item.label}</div>}
      />
    </Box>
  );
};

export default AsyncCombobox;

[SiTaggart]

That's awesome!! 🎉

Can I convince you to create a https://codesandbox.io/ using the Paste template (searchable in the templates) With a working example of an async Combobox?

Until we get to updating the Combobox docs I think people would find it really useful as a reference. 🙏