Custom Multi-select combobox

[beamery-tomht]

Hello!

NB: This closely relates to #2162 #1637 and #2218 #1922

I've been working on a custom MultiSelect component for a separate design system and using react-aria and stately heavily. We found your discussions in this repository stating that this feature doesn't exist in react-spectrum yet, it's on your roadmap, and you're looking into a11y concerns. All good.

I'd really appreciate any feedback on the approach we've taken. Any guidance for our own approach here on a11y issues, implementation improvements, anything really... Would love to get some insights from the react-spectrum team on this.

A few features we're incorporating:

• Select "none" option is inserted at the top of the list of items
• The Combobox input filters results displayed but not results "selected"
• Leveraging react-aria for keyboard event handling

Some issues we're concerned with:

• We couldn't find an alternative to writing our own onKeyDown handler for the input that duplicates some logic. This is for keyboard events for navigating and selecting
• We tried writing a custom Item type with getCollectionNode to apply some defaults

Some questions we have:

• The responsibility differences between a ListItem and Item (or our custom Item) are unclear. We don't know whether to focus on custom ListItem components, custom Items or both.
• When implementing different types of options in the multi-select, for example, options with checkboxes, options without checkboxes, the select-none option, separators, etc.... We're not sure if this should be different Item components or something that lives in a single custom item
• We're not sure how best to implement a "loading skeleton" feature on each Item. We'll probably use the ListItem component here but would the Item be better suited and provide wrapping around the rendered prop with ReactElements?

Here's a working implementation we have in a little test that we've been exploring.

const noneKey = 'NONE_KEY';

type DefaultItem = { id: string; label: string; variant?: 'none' };

interface MSProps<T extends DefaultItem> {
  items: T[];
  defaultSelectedKeys?: Array<string | number>;
}

type ListItemProps<T> = {
  state: ListState<T>;
  listItem: Node<T>;
} & HTMLAttributes<HTMLElement>;

function NormalListItem<T extends DefaultItem = DefaultItem>({
  state,
  listItem,
}: ListItemProps<T>) {
  const ref = useRef<HTMLDivElement>(null);
  const { optionProps, isSelected, isFocused } = useOption(
    { key: listItem.key },
    state,
    ref,
  );
  return (
    <div
      ref={ref}
      role='listitem'
      {...mergeProps(optionProps)}
      style={{
        outline: isFocused ? '1px solid blue' : 'none',
        backgroundColor: isSelected ? 'orange' : 'transparent',
      }}
    >
      {listItem.rendered}
    </div>
  );
}

function NoneListItem<T extends DefaultItem = DefaultItem>({
  state,
  listItem,
}: ListItemProps<T>) {
  const ref = useRef<HTMLDivElement>(null);
  const { optionProps, isFocused } = useOption(
    { key: listItem.key },
    state,
    ref,
  );
  const { selectionManager } = state;
  return (
    <div
      ref={ref}
      role='listitem'
      {...mergeProps(optionProps, listItem.props)}
      onClick={() => selectionManager.clearSelection()}
      onKeyDown={() => selectionManager.clearSelection()}
      style={{
        outline: isFocused ? '1px solid blue' : 'none',
        backgroundColor:
          selectionManager.selectedKeys.size === 0 ? 'orange' : 'transparent',
      }}
    >
      {listItem.rendered}
    </div>
  );
}

type ListBoxProps<T> = {
  listRef: React.RefObject<HTMLDivElement>;
  state: ListState<T>;
  options: Node<T>[];
} & HTMLAttributes<HTMLElement>;

function ListBox<T extends DefaultItem = DefaultItem>({
  listRef,
  state,
  options,
}: ListBoxProps<T>) {
  const listBox = useListBox(
    {
      shouldFocusOnHover: true,
      label: 'shush',
    },
    state,
    listRef,
  );
  return (
    <div
      className='multiselect'
      ref={listRef}
      {...mergeProps(listBox.listBoxProps /* , menuTrigger.menuProps */)}
    >
      {options.map((i) =>
        i.value.variant === 'none' ? (
          <NoneListItem key={i.key} listItem={i} state={state} />
        ) : (
          <NormalListItem key={i.key} listItem={i} state={state} />
        ),
      )}
    </div>
  );
}

interface OptionsProps {
  children: ReactNode;
  label?: string;
  textValue?: string;
  variant?: string;
}

// eslint-disable-next-line @typescript-eslint/no-unused-vars
function Option(props: OptionsProps) {
  return null;
}

Option.getCollectionNode = function* getCollectionNode({
  label,
  children,
  textValue,
  ...props
}: OptionsProps) {
  yield {
    type: 'item', // needs to be `item` for the ListCollection
    textValue:
      textValue ||
      label ||
      (typeof children === 'string' ? children : '') ||
      '',
    rendered: children,
    hasChildNodes: false,
    props: {
      'aria-label': label,
      ...props,
    },
  };
};

function MultiSelect<T extends DefaultItem = DefaultItem>({
  items,
  defaultSelectedKeys,
}: MSProps<T>) {
  const [filterString, setFilterString] = useState<string>('');
  const listRef = useRef<HTMLDivElement>(null);
  // eslint-disable-next-line @typescript-eslint/unbound-method
  const { contains } = useFilter({ sensitivity: 'base' });
  const listState = useListState({
    items: [{ id: noneKey, label: 'None', variant: 'none' } as T, ...items],
    children: (i: T) => (
      <Option label={i.label} variant={i.variant}>
        {i.label}
      </Option>
    ),
    defaultSelectedKeys,
    selectionMode: 'multiple',
    filter: (nodes) =>
      Array.from(nodes).filter(
        (item) =>
          item.value.variant === 'none' ||
          contains(item.textValue, filterString),
      ),
  });
  const options = useMemo(
    () => Array.from(listState.collection),
    [listState.collection, filterString],
  );
  // const buttonRef = useRef<HTMLElement>(null);
  // const menuState = useMenuTriggerState({});
  // const menuTrigger = useMenuTrigger(
  //   {
  //     type: 'listbox',
  //   },
  //   menuState,
  //   buttonRef,
  // );
  const { selectionManager } = listState;

  // have to duplicate the internal logic for the input keyboard events :(
  const onKeyDown: KeyboardEventHandler<HTMLInputElement> = (e) => {
    switch (e.key) {
      case 'Enter': {
        const item = listState.collection.getItem(selectionManager.focusedKey);
        if (item.value.variant === 'none') {
          selectionManager.clearSelection();
        } else {
          selectionManager.toggleSelection(selectionManager.focusedKey);
        }
        break;
      }
      case 'ArrowDown': {
        const nextKey =
          listState.collection.getKeyAfter(selectionManager.focusedKey) ||
          listState.collection.getFirstKey();
        nextKey && selectionManager.setFocusedKey(nextKey);
        break;
      }
      case 'ArrowUp': {
        const prevKey =
          listState.collection.getKeyBefore(selectionManager.focusedKey) ||
          listState.collection.getLastKey();
        prevKey && selectionManager.setFocusedKey(prevKey);
        break;
      }
      default:
        break;
    }
  };
  return (
    <>
      <small>
        Selected: {/* this is a bit fragile */}
        {Array.from(selectionManager.selectedKeys)
          .map((key) => items.find((item) => item.id === key)?.label)
          .filter(Boolean)
          .join(', ')}
      </small>
      <hr />
      <input
        type='text'
        value={filterString}
        onChange={(e) => setFilterString(e.target.value)}
        onKeyDown={onKeyDown}
        onBlur={() => selectionManager.setFocusedKey('')}
      />
      <ListBox listRef={listRef} options={options} state={listState} />
    </>
  );
}

describe('Combobox / Playground', () => {
  it('renders', () => {
    cy.viewport(500, 400);

    type Entity = {
      id: string;
      label: string;
    };

    const items: Entity[] = [
      { id: '1', label: 'Aerospace' },
      { id: '2', label: 'Mechanical' },
      { id: '3', label: 'Civil' },
      { id: '4', label: 'Biomedical' },
      { id: '5', label: 'Nuclear' },
      { id: '6', label: 'Industrial' },
      { id: '7', label: 'Chemical' },
      { id: '8', label: 'Agricultural' },
      { id: '9', label: 'Electrical' },
      { id: '10', label: 'Permacultural' },
    ];

    mountWithTheme(
      <MultiSelect items={items} defaultSelectedKeys={['2', '4']} />,
    );
  });
});