@transferwise/components 0.0.0-experimental-d6b038b → 0.0.0-experimental-c84454a

package/src/inputs/SelectInput.tsx

@@ -0,0 +1,1269 @@
+import {
+  Listbox as ListboxBase,
+  ListboxButton,
+  ListboxOption,
+  ListboxOptions,
+} from '@headlessui/react';
+import { Check, ChevronDown, Cross, CrossCircle } from '@transferwise/icons';
+import { clsx } from 'clsx';
+import mergeProps from 'merge-props';
+import {
+  createContext,
+  forwardRef,
+  ReactNode,
+  useContext,
+  useDeferredValue,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { useIntl } from 'react-intl';
+import { Virtualizer, type VirtualizerHandle } from 'virtua';
+
+import { useEffectEvent } from '../common/hooks/useEffectEvent';
+import { useScreenSize } from '../common/hooks/useScreenSize';
+import { PolymorphicWithOverrides } from '../common/polymorphicWithOverrides/PolymorphicWithOverrides';
+import { Breakpoint } from '../common/propsValues/breakpoint';
+import dateTriggerMessages from '../dateLookup/dateTrigger/DateTrigger.messages';
+import { Merge } from '../utils';
+
+import { BottomSheet } from './_BottomSheet';
+import { ButtonInput } from './_ButtonInput';
+import { Popover } from './_Popover';
+import { useInputAttributes, WithInputAttributesProps } from './contexts';
+import { InputGroup } from './InputGroup';
+import { SearchInput } from './SearchInput';
+import messages from './SelectInput.messages';
+import Header from '../header';
+import Section from '../section';
+import { ButtonProps } from '../button/Button.types';
+
+const MAX_ITEMS_WITHOUT_VIRTUALIZATION = 50;
+
+function searchableString(value: string) {
+  return (
+    value
+      .trim()
+      .replace(/\s+/gu, ' ')
+      // NFD converts an Å to A +  ̊ (and other special characters)
+      .normalize('NFD')
+      // and then this replaces the  ̊ with nothing (and other special characters)
+      .replace(/[\u0300-\u036f]/g, '')
+      .toLowerCase()
+  );
+}
+
+function inferSearchableStrings(value: unknown) {
+  if (typeof value === 'string') {
+    return [searchableString(value)];
+  }
+
+  if (typeof value === 'object' && value != null) {
+    return Object.values(value)
+      .filter((innerValue) => typeof innerValue === 'string')
+      .map((innerValue) => searchableString(innerValue));
+  }
+
+  return [];
+}
+
+export interface SelectInputOptionItem<T = string> {
+  type: 'option';
+  value: T;
+  filterMatchers?: readonly string[];
+  disabled?: boolean;
+}
+
+export interface SelectInputGroupItem<T = string> {
+  type: 'group';
+  label: ReactNode;
+  options: readonly SelectInputOptionItem<T>[];
+  action?: {
+    label: string;
+    onClick: ButtonProps['onClick'];
+  };
+}
+
+export interface SelectInputSeparatorItem {
+  type: 'separator';
+}
+
+export type SelectInputItem<T = string> =
+  | SelectInputOptionItem<T>
+  | SelectInputGroupItem<T>
+  | SelectInputSeparatorItem;
+
+function dedupeSelectInputOptionItem<T>(
+  item: SelectInputOptionItem<T>,
+  existingValues: Set<T>,
+  compareValues?: (a: T, b: T) => boolean,
+): SelectInputOptionItem<T | undefined> {
+  const isDuplicate = compareValues
+    ? Array.from(existingValues).some((existingValue) => compareValues(item.value, existingValue))
+    : existingValues.has(item.value);
+
+  if (!isDuplicate) {
+    existingValues.add(item.value);
+    return item;
+  }
+  return { ...item, value: undefined };
+}
+
+/**
+ * Sets the `value` of duplicate option items to `undefined`, hiding them when
+ * rendered. Indexes are kept intact within groups to preserve the active item
+ * between filter changes when possible.
+ */
+function dedupeSelectInputItems<T>(
+  items: readonly SelectInputItem<T>[],
+  compareValues?: (a: T, b: T) => boolean,
+): SelectInputItem<T | undefined>[] {
+  const existingValues = new Set<T>();
+
+  return items.map((item) => {
+    switch (item.type) {
+      case 'option': {
+        return dedupeSelectInputOptionItem(item, existingValues, compareValues);
+      }
+      case 'group': {
+        return {
+          ...item,
+          options: item.options.map((option) =>
+            dedupeSelectInputOptionItem(option, existingValues, compareValues),
+          ),
+        };
+      }
+      default:
+    }
+    return item;
+  });
+}
+
+function selectInputOptionItemIncludesNeedle<T>(item: SelectInputOptionItem<T>, needle: string) {
+  return inferSearchableStrings(item.filterMatchers ?? item.value).some((haystack) =>
+    haystack.includes(needle),
+  );
+}
+
+function filterSelectInputItems<T>(
+  items: readonly SelectInputItem<T>[],
+  predicate: (item: SelectInputOptionItem<T>) => boolean,
+) {
+  return items.filter((item) => {
+    switch (item.type) {
+      case 'option': {
+        return predicate(item);
+      }
+      case 'group': {
+        return item.options.some((option) => predicate(option));
+      }
+      default:
+    }
+    return false;
+  });
+}
+
+/**
+ * Flattens and sorts filtered options using the provided comparator.
+ * Extracts all options from groups, filters out undefined values (deduplicated items),
+ * sorts them, and returns as a flat list of option items.
+ */
+function sortSelectInputItems<T>(
+  items: readonly SelectInputItem<T | undefined>[],
+  compareFn: (
+    a: SelectInputOptionItem<NonNullable<T>>,
+    b: SelectInputOptionItem<NonNullable<T>>,
+    searchQuery: string,
+  ) => number,
+  searchQuery: string,
+): SelectInputItem<NonNullable<T>>[] {
+  const flattenedOption = items.flatMap((item) => {
+    if (item.type === 'option') {
+      return item.value !== undefined ? [item as SelectInputOptionItem<NonNullable<T>>] : [];
+    }
+
+    if (item.type === 'group') {
+      return item.options.filter(
+        (option): option is SelectInputOptionItem<NonNullable<T>> => option.value !== undefined,
+      );
+    }
+
+    return [];
+  });
+
+  // eslint-disable-next-line functional/immutable-data
+  return flattenedOption.sort((a, b) => compareFn(a, b, searchQuery));
+}
+
+/**
+ * A prebuilt sort function for `sortFilteredOptions` that sorts options by relevance to the search query.
+ * Prioritizes: exact matches > starts with > contains > alphabetical.
+ *
+ * @param getLabel - Function to extract the label string from the option value. Defaults to using `title` property.
+ *
+ * @example
+ * ```tsx
+ * <SelectInput
+ *   filterable
+ *   sortFilteredOptions={sortByRelevance((value) => value.name)}
+ *   // ...
+ * />
+ * ```
+ */
+export function sortByRelevance<T>(
+  getLabel: (value: T) => string = (value) => (value as { title: string }).title,
+): (a: SelectInputOptionItem<T>, b: SelectInputOptionItem<T>, searchQuery: string) => number {
+  return (a, b, searchQuery) => {
+    const normalizedQuery = searchQuery.toLowerCase();
+    const labelA = getLabel(a.value).toLowerCase();
+    const labelB = getLabel(b.value).toLowerCase();
+
+    // Prioritize exact matches
+    const aExactMatch = labelA === normalizedQuery;
+    const bExactMatch = labelB === normalizedQuery;
+    if (aExactMatch && !bExactMatch) return -1;
+    if (!aExactMatch && bExactMatch) return 1;
+
+    // Then prioritize options where label starts with the search query
+    const aStartsWith = labelA.startsWith(normalizedQuery);
+    const bStartsWith = labelB.startsWith(normalizedQuery);
+    if (aStartsWith && !bStartsWith) return -1;
+    if (!aStartsWith && bStartsWith) return 1;
+
+    // Then prioritize options where label contains the search query
+    const aContains = labelA.includes(normalizedQuery);
+    const bContains = labelB.includes(normalizedQuery);
+    if (aContains && !bContains) return -1;
+    if (!aContains && bContains) return 1;
+
+    // Finally sort alphabetically
+    return labelA.localeCompare(labelB);
+  };
+}
+
+export interface SelectInputProps<T = string, M extends boolean = false> {
+  id?: string;
+  /**
+   * Sets the `data-wds-parent` attribute on the listbox container, which is needed for complex components like DateInput to correctly manage event handling.
+   * @internal
+   */
+  parentId?: string;
+  name?: string;
+  multiple?: M;
+  placeholder?: string;
+  items: readonly SelectInputItem<NonNullable<T>>[];
+  /**
+   * Enables browser autocomplete integration through the search input.
+   * Accepts standard HTML autocomplete values (e.g., "country-name", "address-level1").
+   *
+   * Requires `filterable={true}` to enable the search input.
+   *
+   * @example
+   * <SelectInput
+   *   name="country"
+   *   autocomplete="country-name"
+   *   filterable={true}
+   *   items={[{
+   *     type: 'option',
+   *     value: 'GB',
+   *     filterMatchers: ['United Kingdom', 'UK']
+   *   }]}
+   * />
+   */
+  autocomplete?: string;
+  defaultValue?: M extends true ? readonly T[] : T;
+  value?: M extends true ? readonly T[] : T;
+  compareValues?:
+    | (keyof NonNullable<T> & string)
+    | ((a: T | undefined, b: T | undefined) => boolean);
+  renderValue?: (value: NonNullable<T>, withinTrigger: boolean) => React.ReactNode;
+  renderFooter?: (args: {
+    resultsEmpty: boolean;
+    queryNormalized: string | null | undefined;
+  }) => React.ReactNode;
+  renderTrigger?: (args: {
+    content: React.ReactNode;
+    placeholderShown: boolean;
+    clear: (() => void) | undefined;
+    disabled: boolean;
+    size: 'sm' | 'md' | 'lg';
+    className: string | undefined;
+  }) => React.ReactNode;
+  filterable?: boolean;
+  filterPlaceholder?: string;
+  sortFilteredOptions?: (
+    a: SelectInputOptionItem<NonNullable<T>>,
+    b: SelectInputOptionItem<NonNullable<T>>,
+    searchQuery: string,
+  ) => number;
+  disabled?: boolean;
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+  UNSAFE_triggerButtonProps?: WithInputAttributesProps['inputAttributes'] & {
+    'aria-label'?: string;
+  };
+  /** Ref to the select trigger button element. */
+  triggerRef?: React.MutableRefObject<HTMLButtonElement | null>;
+  onFilterChange?: (args: { query: string; queryNormalized: string | null }) => void;
+  onChange?: (value: M extends true ? T[] : T) => void;
+  onOpen?: () => void;
+  onClose?: () => void;
+  onClear?: () => void;
+}
+
+const defaultRenderTrigger = (({ content, placeholderShown, clear, disabled, size, className }) => (
+  <InputGroup
+    addonEnd={{
+      content: (
+        <span className={clsx('np-select-input-addon-container', disabled && 'disabled')}>
+          {clear != null && !placeholderShown ? (
+            <>
+              <SelectInputClearButton
+                onClick={(event) => {
+                  event.preventDefault();
+                  clear();
+                }}
+              />
+              <span className="np-select-input-addon-separator" />
+            </>
+          ) : null}
+
+          <span className="np-select-input-addon">
+            <ChevronDown size={16} />
+          </span>
+        </span>
+      ),
+      initialContentWidth: 24 + 4,
+      padding: 'sm',
+    }}
+    disabled={disabled}
+    className={className}
+  >
+    <SelectInputTriggerButton as={ButtonInput} size={size}>
+      <span
+        className={clsx(
+          'np-select-input-content',
+          placeholderShown && 'np-select-input-placeholder',
+        )}
+      >
+        {content}
+      </span>
+    </SelectInputTriggerButton>
+  </InputGroup>
+)) satisfies SelectInputProps['renderTrigger'];
+
+interface SelectInputClearButtonProps extends Pick<
+  React.ComponentPropsWithoutRef<'button'>,
+  'className' | 'onClick'
+> {}
+
+function SelectInputClearButton({ className, onClick }: SelectInputClearButtonProps) {
+  const intl = useIntl();
+
+  return (
+    <button
+      type="button"
+      aria-label={intl.formatMessage(dateTriggerMessages.ariaLabel)}
+      className={clsx(className, 'np-select-input-addon np-select-input-addon--interactive')}
+      onClick={onClick}
+    >
+      <Cross size={16} />
+    </button>
+  );
+}
+
+const noop = () => {};
+
+export function SelectInput<T = string, M extends boolean = false>({
+  id: idProp,
+  parentId,
+  name,
+  multiple,
+  placeholder,
+  autocomplete,
+  items,
+  defaultValue,
+  value: controlledValue,
+  compareValues,
+  renderValue = String,
+  renderFooter,
+  renderTrigger = defaultRenderTrigger,
+  filterable,
+  filterPlaceholder,
+  sortFilteredOptions,
+  disabled,
+  size = 'md',
+  className,
+  UNSAFE_triggerButtonProps,
+  triggerRef: externalTriggerRef,
+  onFilterChange = noop,
+  onChange,
+  onOpen,
+  onClose,
+  onClear,
+}: SelectInputProps<T, M>) {
+  const inputAttributes = useInputAttributes({ nonLabelable: true });
+  const id = idProp ?? inputAttributes.id;
+
+  const [open, setOpen] = useState(false);
+
+  const initialized = useRef(false);
+  const handleClose = useEffectEvent(onClose ?? (() => {}));
+  const handleOpen = useEffectEvent(onOpen ?? (() => {}));
+  useEffect(() => {
+    if (initialized.current) {
+      if (open) {
+        handleOpen?.();
+      } else {
+        handleClose?.();
+      }
+    } else {
+      initialized.current = true;
+    }
+  }, [handleClose, handleOpen, open]);
+
+  const [filterQuery, _setFilterQuery] = useState('');
+  const deferredFilterQuery = useDeferredValue(filterQuery);
+  const setFilterQuery = useEffectEvent((query: string) => {
+    _setFilterQuery(query);
+    if (query !== filterQuery) {
+      onFilterChange({
+        query,
+        queryNormalized: query ? searchableString(query) : null,
+      });
+    }
+  });
+
+  const internalTriggerRef = useRef<HTMLButtonElement | null>(null);
+
+  const screenSm = useScreenSize(Breakpoint.SMALL);
+  const OptionsOverlay = screenSm ? Popover : BottomSheet;
+
+  const searchInputRef = useRef<HTMLInputElement>(null);
+  const listboxRef = useRef<HTMLDivElement>(null);
+  const controllerRef = filterable ? searchInputRef : listboxRef;
+
+  /**
+   * Attempts to resolve the `listbox` label
+   * @see https://storybook.wise.design/?path=/docs/forms-selectinput-accessibility--docs#labelling
+   */
+  const getListBoxLabelProps = (): {
+    listBoxLabel?: string;
+    listBoxLabelledBy?: string;
+  } => {
+    if (UNSAFE_triggerButtonProps?.['aria-label']) {
+      return {
+        listBoxLabel: UNSAFE_triggerButtonProps['aria-label'],
+      };
+    }
+
+    if (UNSAFE_triggerButtonProps?.['aria-labelledby']) {
+      return {
+        listBoxLabelledBy: UNSAFE_triggerButtonProps['aria-labelledby'],
+      };
+    }
+
+    if (inputAttributes['aria-labelledby']) {
+      return {
+        listBoxLabelledBy: inputAttributes['aria-labelledby'],
+      };
+    }
+
+    return {};
+  };
+
+  return (
+    <ListboxBase
+      name={name}
+      multiple={multiple}
+      defaultValue={defaultValue as M extends true ? T[] : T}
+      value={controlledValue as M extends true ? T[] : T}
+      by={compareValues}
+      disabled={disabled}
+      onChange={
+        ((value) => {
+          if (!multiple) {
+            setOpen(false);
+          }
+          onChange?.(value);
+        }) satisfies SelectInputProps<T, M>['onChange']
+      }
+    >
+      {({ disabled: uiDisabled, value }) => {
+        const placeholderShown =
+          multiple && Array.isArray(value) ? value.length === 0 : value == null;
+        return (
+          <OptionsOverlay
+            placement="bottom-start"
+            open={open}
+            renderTrigger={({ ref, getInteractionProps }) => (
+              <SelectInputTriggerButtonPropsContext.Provider
+                // eslint-disable-next-line react/jsx-no-constructed-context-values
+                value={{
+                  ref: (node) => {
+                    ref(node);
+                    if (externalTriggerRef) {
+                      // eslint-disable-next-line no-param-reassign
+                      externalTriggerRef.current = node;
+                    } else {
+                      internalTriggerRef.current = node;
+                    }
+                  },
+                  ...inputAttributes,
+                  ...UNSAFE_triggerButtonProps,
+                  id,
+                  ...mergeProps(
+                    {
+                      onClick: () => {
+                        setOpen((prev) => !prev);
+                      },
+                      onKeyDown: (event: React.KeyboardEvent) => {
+                        if (
+                          event.key === ' ' ||
+                          event.key === 'Enter' ||
+                          event.key === 'ArrowDown' ||
+                          event.key === 'ArrowUp'
+                        ) {
+                          setOpen((prev) => !prev);
+                        }
+                      },
+                    },
+                    getInteractionProps(),
+                  ),
+                }}
+              >
+                {renderTrigger({
+                  content: !placeholderShown ? (
+                    <SelectInputOptionContentWithinTriggerContext.Provider value>
+                      {multiple && Array.isArray(value)
+                        ? (value as readonly NonNullable<T>[])
+                            .map((option) => renderValue(option, true))
+                            .filter((node) => node != null)
+                            .join(', ')
+                        : renderValue(value as NonNullable<T>, true)}
+                    </SelectInputOptionContentWithinTriggerContext.Provider>
+                  ) : (
+                    placeholder
+                  ),
+                  placeholderShown,
+                  clear:
+                    onClear != null
+                      ? () => {
+                          onClear();
+                          (externalTriggerRef?.current ?? internalTriggerRef.current)?.focus({
+                            preventScroll: true,
+                          });
+                        }
+                      : undefined,
+                  disabled: uiDisabled,
+                  size,
+                  className,
+                })}
+              </SelectInputTriggerButtonPropsContext.Provider>
+            )}
+            initialFocusRef={controllerRef}
+            size={filterable ? 'lg' : 'md'}
+            padding="none"
+            onClose={() => {
+              setOpen(false);
+            }}
+            onCloseEnd={() => {
+              setFilterQuery('');
+            }}
+          >
+            <SelectInputOptions
+              id={id ? `${id}Search` : undefined}
+              parentId={parentId}
+              items={items}
+              compareValues={compareValues}
+              renderValue={renderValue}
+              renderFooter={renderFooter}
+              filterable={filterable}
+              filterPlaceholder={filterPlaceholder}
+              sortFilteredOptions={sortFilteredOptions}
+              searchInputRef={searchInputRef}
+              listboxRef={listboxRef}
+              filterQuery={deferredFilterQuery}
+              autocomplete={autocomplete}
+              name={name}
+              onFilterChange={setFilterQuery}
+              onAutocompleteSelect={(matchedValue) => {
+                onChange?.(matchedValue as M extends true ? T[] : T);
+                if (!multiple) {
+                  setOpen(false);
+                }
+              }}
+              {...getListBoxLabelProps()}
+            />
+          </OptionsOverlay>
+        );
+      }}
+    </ListboxBase>
+  );
+}
+
+SelectInput.sortByRelevance = sortByRelevance;
+
+const SelectInputTriggerButtonPropsContext = createContext<{
+  ref?: React.ForwardedRef<HTMLButtonElement | null>;
+  id?: string;
+  onClick?: (event: React.MouseEvent) => void;
+  onKeyDown?: (event: React.KeyboardEvent) => void;
+  [key: string]: unknown;
+}>({});
+
+type SelectInputTriggerButtonElementType = 'button' | React.ComponentType;
+
+export type SelectInputTriggerButtonProps<
+  T extends SelectInputTriggerButtonElementType = 'button',
+> = Merge<React.ComponentPropsWithoutRef<T>, { as?: T }>;
+
+export function SelectInputTriggerButton<T extends SelectInputTriggerButtonElementType = 'button'>({
+  as = 'button' as T,
+  ...restProps
+}: SelectInputTriggerButtonProps<T>) {
+  const { ref, onClick, onKeyDown, ...interactionProps } = useContext(
+    SelectInputTriggerButtonPropsContext,
+  );
+
+  return (
+    <ListboxButton
+      ref={ref}
+      as={PolymorphicWithOverrides}
+      role="combobox"
+      __overrides={{ as, ...interactionProps }}
+      {...mergeProps({ onClick, onKeyDown }, restProps)}
+    />
+  );
+}
+
+interface SelectInputOptionsContainerProps extends React.ComponentPropsWithRef<'div'> {
+  onAriaActiveDescendantChange: (value: React.AriaAttributes['aria-activedescendant']) => void;
+}
+
+const SelectInputOptionsContainer = forwardRef(function SelectInputOptionsContainer(
+  {
+    'aria-orientation': ariaOrientation,
+    'aria-activedescendant': ariaActiveDescendant,
+    role,
+    tabIndex,
+    onAriaActiveDescendantChange,
+    onKeyDown,
+    ...restProps
+  }: SelectInputOptionsContainerProps,
+  ref: React.ForwardedRef<HTMLDivElement | null>,
+) {
+  const handleAriaActiveDescendantChange = useEffectEvent(onAriaActiveDescendantChange);
+  useEffect(() => {
+    handleAriaActiveDescendantChange(ariaActiveDescendant);
+  }, [ariaActiveDescendant, handleAriaActiveDescendantChange]);
+
+  return (
+    <div
+      ref={ref}
+      role="none"
+      onKeyDown={(event) => {
+        // Prevent confirmation close without an active item
+        if (event.key === 'Enter' && ariaActiveDescendant == null) {
+          return;
+        }
+
+        // Required to make ListBox focusable
+        if (event.key === 'Tab') {
+          return;
+        }
+
+        // Prevent absorbing Escape early
+        if (event.key === 'Escape') {
+          onKeyDown?.({
+            ...event,
+            preventDefault: () => {},
+            stopPropagation: () => {},
+          });
+          return;
+        }
+
+        onKeyDown?.(event);
+      }}
+      {...restProps}
+    />
+  );
+});
+
+interface SelectInputOptionsProps<T = string> extends Pick<
+  SelectInputProps<T>,
+  | 'items'
+  | 'renderValue'
+  | 'renderFooter'
+  | 'filterable'
+  | 'filterPlaceholder'
+  | 'id'
+  | 'parentId'
+  | 'compareValues'
+  | 'sortFilteredOptions'
+> {
+  searchInputRef: React.MutableRefObject<HTMLInputElement | null>;
+  listboxRef: React.MutableRefObject<HTMLDivElement | null>;
+  filterQuery: string;
+  onFilterChange: (query: string) => void;
+  listBoxLabel?: string;
+  listBoxLabelledBy?: string;
+  autocomplete?: string;
+  name?: string;
+  onAutocompleteSelect?: (value: T) => void;
+}
+
+function SelectInputOptions<T = string>({
+  id,
+  parentId,
+  items,
+  compareValues: compareValuesProp,
+  renderValue = String,
+  renderFooter,
+  filterable = false,
+  filterPlaceholder,
+  sortFilteredOptions,
+  searchInputRef,
+  listboxRef,
+  filterQuery,
+  onFilterChange,
+  listBoxLabel,
+  listBoxLabelledBy,
+  autocomplete,
+  name,
+  onAutocompleteSelect,
+}: SelectInputOptionsProps<T>) {
+  const intl = useIntl();
+  const virtualiserHandlerRef = useRef<VirtualizerHandle>(null);
+  const controllerRef = filterable ? searchInputRef : listboxRef;
+  const [initialRender, setInitialRender] = useState(true);
+
+  const needle = useMemo(() => {
+    if (filterable) {
+      return filterQuery ? searchableString(filterQuery) : null;
+    }
+    return undefined;
+  }, [filterQuery, filterable]);
+  useEffect(() => {
+    if (needle) {
+      // Ensure having an active option while filtering.
+      // Without `requestAnimationFrame` upon which React depends for scheduling
+      // updates, the active status would only show for a split second and then
+      // disappear inadvertently.
+      requestAnimationFrame(() => {
+        if (
+          controllerRef.current != null &&
+          !controllerRef.current.hasAttribute('aria-activedescendant')
+        ) {
+          // Activate first option via synthetic key press
+          controllerRef.current.dispatchEvent(
+            new KeyboardEvent('keydown', { key: 'Home', bubbles: true }),
+          );
+        }
+      });
+    }
+  }, [controllerRef, needle]);
+
+  const compareValues = useMemo(() => {
+    if (!compareValuesProp) {
+      return undefined;
+    }
+
+    if (typeof compareValuesProp === 'function') {
+      return (a: NonNullable<T>, b: NonNullable<T>) => compareValuesProp(a, b);
+    }
+
+    const key = compareValuesProp;
+    return (a: NonNullable<T>, b: NonNullable<T>) => {
+      if (typeof a === 'object' && a != null && typeof b === 'object' && b != null) {
+        return (a as Record<string, unknown>)[key] === (b as Record<string, unknown>)[key];
+      }
+      return a === b;
+    };
+  }, [compareValuesProp]);
+
+  const filteredItems: readonly SelectInputItem<NonNullable<T> | undefined>[] = useMemo(() => {
+    if (needle == null) {
+      return items;
+    }
+
+    const dedupedItems = dedupeSelectInputItems(items, compareValues);
+
+    if (sortFilteredOptions) {
+      // When sorting, filter out non-matching items completely to avoid ghost items
+      const filtered = dedupedItems.map((item) => {
+        if (item.type === 'option') {
+          return selectInputOptionItemIncludesNeedle(item, needle)
+            ? item
+            : { ...item, value: undefined };
+        }
+        if (item.type === 'group') {
+          return {
+            ...item,
+            options: item.options.map((option) =>
+              selectInputOptionItemIncludesNeedle(option, needle)
+                ? option
+                : { ...option, value: undefined },
+            ),
+          };
+        }
+        return item;
+      });
+
+      return sortSelectInputItems(filtered, sortFilteredOptions, filterQuery);
+    }
+
+    return filterSelectInputItems(dedupedItems, (item) =>
+      selectInputOptionItemIncludesNeedle(item, needle),
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [needle, items, compareValues]);
+  const resultsEmpty = needle != null && filteredItems.length === 0;
+
+  const virtualized = filteredItems.length > MAX_ITEMS_WITHOUT_VIRTUALIZATION;
+
+  // Items shown once shall be kept mounted until the needle changes, otherwise
+  // the scroll position may jump around inadvertently. Pattern adopted from:
+  // https://inokawa.github.io/virtua/?path=/story/advanced-keep-offscreen-items--append-only
+  const [mountedIndexes, setMountedIndexes] = useState<number[]>([]);
+  const prevNeedleRef = useRef(needle);
+
+  useEffect(() => {
+    const needleChanged = prevNeedleRef.current !== needle;
+    prevNeedleRef.current = needle;
+
+    if (needleChanged) {
+      // Reset mounted indexes when search changes to avoid stale scroll positions
+      setMountedIndexes([]);
+      return;
+    }
+
+    // Ensure the 'End' key works as intended by keeping the last item mounted.
+    // Skipped on needle change to prevent auto-scrolling on search.
+    if (filteredItems.length > 0) {
+      setMountedIndexes((prevMountedIndexes) => {
+        const indexes = new Set(prevMountedIndexes);
+        indexes.add(filteredItems.length - 1);
+        return [...indexes]; // Sorting is redundant by nature here
+      });
+    }
+  }, [needle, filteredItems.length]);
+
+  const listboxContainerRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (listboxContainerRef.current != null) {
+      listboxContainerRef.current.style.setProperty(
+        '--initial-height',
+        `${listboxContainerRef.current.offsetHeight}px`,
+      );
+    }
+  }, []);
+
+  useEffect(() => {
+    setInitialRender(false);
+  }, []);
+
+  const showStatus = resultsEmpty;
+  const statusId = useId();
+  const listboxId = useId();
+
+  const getItemNode = (index: number) => {
+    const item = filteredItems[index];
+    return (
+      <SelectInputItemView key={index} item={item} renderValue={renderValue} needle={needle} />
+    );
+  };
+
+  const findMatchingItem = (autocompleteValue: string): T | null => {
+    const flatOptions = items
+      .flatMap((item) =>
+        item.type === 'group' ? item.options : item.type === 'option' ? [item] : [],
+      )
+      .filter(
+        (item): item is SelectInputOptionItem<NonNullable<T>> =>
+          item.type === 'option' && item.value != null,
+      );
+
+    const exactMatch = flatOptions.find(
+      (option) =>
+        String(option.value) === autocompleteValue ||
+        option.filterMatchers?.some((matcher) => matcher === autocompleteValue),
+    );
+
+    if (exactMatch) {
+      return exactMatch.value;
+    }
+
+    const fuzzyMatch = flatOptions.find((option) =>
+      option.filterMatchers?.some((matcher) =>
+        matcher.toLowerCase().includes(autocompleteValue.toLowerCase()),
+      ),
+    );
+
+    return fuzzyMatch ? fuzzyMatch.value : null;
+  };
+
+  return (
+    <ListboxOptions
+      modal
+      as={SelectInputOptionsContainer}
+      static
+      className="np-select-input-options-container"
+      onAriaActiveDescendantChange={(value: React.AriaAttributes['aria-activedescendant']) => {
+        if (controllerRef.current != null) {
+          if (!initialRender && value != null) {
+            controllerRef.current.setAttribute('aria-activedescendant', value);
+          } else {
+            controllerRef.current.removeAttribute('aria-activedescendant');
+          }
+        }
+      }}
+    >
+      {filterable ? (
+        <div className="np-select-input-query-container">
+          <SearchInput
+            ref={searchInputRef}
+            id={id}
+            name={name}
+            autoComplete={autocomplete}
+            role="combobox"
+            shape="rectangle"
+            placeholder={filterPlaceholder}
+            aria-label={filterPlaceholder}
+            defaultValue={filterQuery}
+            aria-autocomplete="list"
+            aria-expanded
+            aria-controls={listboxId}
+            aria-describedby={showStatus ? statusId : undefined}
+            onKeyDown={(event) => {
+              // Prevent interfering with the matcher of Headless UI
+              // https://mathiasbynens.be/notes/javascript-unicode#regex
+              if (/^.$/u.test(event.key)) {
+                event.stopPropagation();
+              }
+            }}
+            onChange={(event) => {
+              // Free up resources and ensure not to go out of bounds when the
+              // resulting item count is less than before
+              const inputValue = event.currentTarget.value;
+
+              // Free up resources and ensure not to go out of bounds
+              setMountedIndexes([]);
+              onFilterChange(inputValue);
+            }}
+            onInput={(event) => {
+              const inputValue = event.currentTarget.value;
+              const inputElement = event.currentTarget;
+
+              if (autocomplete && onAutocompleteSelect && inputValue) {
+                setTimeout(() => {
+                  if (inputElement.value === inputValue && inputValue.length > 2) {
+                    const matchedValue = findMatchingItem(inputValue);
+                    if (matchedValue !== null) {
+                      onAutocompleteSelect(matchedValue);
+                    }
+                  }
+                }, 50);
+              }
+            }}
+          />
+        </div>
+      ) : null}
+
+      <section
+        ref={listboxContainerRef}
+        tabIndex={-1}
+        className={clsx(
+          'np-select-input-listbox-container',
+          virtualized && 'np-select-input-listbox-container--virtualized',
+          needle == null && // Groups aren't shown when filtering
+            items.some((item) => item.type === 'group') &&
+            'np-select-input-listbox-container--has-group',
+        )}
+        data-wds-parent={parentId ?? undefined}
+      >
+        {resultsEmpty ? (
+          <div id={statusId} className="np-select-input-options-status">
+            <CrossCircle size={16} className="np-select-input-options-status-icon" />
+            {intl.formatMessage(messages.noResultsFound)}
+          </div>
+        ) : null}
+
+        <div
+          ref={listboxRef}
+          id={listboxId}
+          role="listbox"
+          aria-orientation="vertical"
+          aria-label={listBoxLabel}
+          aria-labelledby={listBoxLabelledBy}
+          tabIndex={0}
+          className="np-select-input-listbox"
+        >
+          {!virtualized ? (
+            filteredItems.map((_, index) => getItemNode(index))
+          ) : (
+            <Virtualizer
+              ref={virtualiserHandlerRef}
+              data={filteredItems}
+              keepMounted={mountedIndexes}
+              scrollRef={listboxRef} // `VList` doesn't expose this
+              onScroll={async () => {
+                if (!virtualiserHandlerRef.current) return;
+
+                const startIndex = virtualiserHandlerRef.current.findItemIndex(
+                  virtualiserHandlerRef.current.scrollOffset,
+                );
+                const endIndex = virtualiserHandlerRef.current.findItemIndex(
+                  virtualiserHandlerRef.current.scrollOffset +
+                    virtualiserHandlerRef.current.viewportSize,
+                );
+
+                setMountedIndexes((prevMountedIndexes) => {
+                  const indexes = new Set(prevMountedIndexes);
+
+                  for (let index = startIndex; index <= endIndex; index += 1) {
+                    indexes.add(index);
+                  }
+
+                  return [...indexes].sort((a, b) => a - b);
+                });
+              }}
+            >
+              {(item, index) => (
+                // The position of each item can't be inferred by browsers when
+                // virtualizing, as some of the items may not be in the DOM
+                <SelectInputItemsCountContext.Provider value={filteredItems.length}>
+                  <SelectInputItemPositionContext.Provider value={index + 1}>
+                    {getItemNode(index)}
+                  </SelectInputItemPositionContext.Provider>
+                </SelectInputItemsCountContext.Provider>
+              )}
+            </Virtualizer>
+          )}
+        </div>
+
+        {renderFooter != null ? (
+          <footer className="np-select-input-footer">
+            <div
+              role="none"
+              onKeyDown={(event) => {
+                // Prevent interfering with Headless UI
+                if (event.key !== 'Escape') {
+                  event.stopPropagation();
+                }
+              }}
+            >
+              {renderFooter({
+                resultsEmpty,
+                queryNormalized: needle,
+              })}
+            </div>
+          </footer>
+        ) : null}
+      </section>
+    </ListboxOptions>
+  );
+}
+
+interface SelectInputItemViewProps<
+  T = string,
+  I extends SelectInputItem<T | undefined> = SelectInputItem<T | undefined>,
+> extends Required<Pick<SelectInputProps<T>, 'renderValue'>> {
+  item: I;
+  needle: string | null | undefined;
+}
+
+function SelectInputItemView<T = string>({
+  item,
+  renderValue,
+  needle,
+}: SelectInputItemViewProps<T>) {
+  switch (item.type) {
+    case 'option': {
+      if (
+        item.value != null &&
+        (needle == null || selectInputOptionItemIncludesNeedle(item, needle))
+      ) {
+        return (
+          <SelectInputOption value={item.value} disabled={item.disabled}>
+            {renderValue(item.value, false)}
+          </SelectInputOption>
+        );
+      }
+      break;
+    }
+    case 'group': {
+      return <SelectInputGroupItemView item={item} renderValue={renderValue} needle={needle} />;
+    }
+    case 'separator': {
+      if (needle == null) {
+        return <hr className="np-select-input-separator-item" />;
+      }
+      break;
+    }
+  }
+  return null;
+}
+
+interface SelectInputGroupItemViewProps<T = string> extends SelectInputItemViewProps<
+  T,
+  SelectInputGroupItem<T | undefined>
+> {}
+
+function SelectInputGroupItemView<T = string>({
+  item,
+  renderValue,
+  needle,
+}: SelectInputGroupItemViewProps<T>) {
+  const headerId = useId();
+
+  const header = (
+    <Header
+      as="header"
+      role="none"
+      id={headerId}
+      title={item.label}
+      // @ts-expect-error when we migrate ActionButton to new Button this should be sorted
+      action={
+        item.action && {
+          text: item.action.label,
+          onClick: item.action.onClick,
+        }
+      }
+      className="np-select-input-group-item-header p-x-1"
+    />
+  );
+
+  return (
+    // An empty container may be rendered when no options match `needle`
+    // However, pre-filtering would result in worse performance overall
+    <Section
+      as="section"
+      role="group"
+      aria-labelledby={headerId}
+      className={clsx('m-y-0', needle === null && 'np-select-input-group-item--without-needle')}
+    >
+      {needle == null ? header : null}
+      {item.options.map((option, index) => (
+        <SelectInputItemView
+          // eslint-disable-next-line react/no-array-index-key
+          key={index}
+          item={option}
+          renderValue={renderValue}
+          needle={needle}
+        />
+      ))}
+    </Section>
+  );
+}
+
+const SelectInputItemsCountContext = createContext<number | undefined>(undefined);
+const SelectInputItemPositionContext = createContext<number | undefined>(undefined);
+
+interface SelectInputOptionProps<T = string> {
+  value: T;
+  disabled?: boolean;
+  children?: React.ReactNode;
+}
+
+function SelectInputOption<T = string>({ value, disabled, children }: SelectInputOptionProps<T>) {
+  const itemsCount = useContext(SelectInputItemsCountContext);
+  const itemPosition = useContext(SelectInputItemPositionContext);
+  return (
+    <ListboxOption
+      as="div"
+      value={value}
+      aria-setsize={itemsCount}
+      aria-posinset={itemPosition}
+      disabled={disabled}
+      className={({ active, disabled: uiDisabled }) =>
+        clsx(
+          'np-select-input-option-container np-text-body-large',
+          active && 'np-select-input-option-container--active',
+          uiDisabled && 'np-select-input-option-container--disabled',
+        )
+      }
+    >
+      {({ selected }) => (
+        <>
+          <div className="np-select-input-option">{children}</div>
+          <Check
+            size={16}
+            className={clsx(
+              'np-select-input-option-check',
+              !selected && 'np-select-input-option-check--not-selected',
+            )}
+          />
+        </>
+      )}
+    </ListboxOption>
+  );
+}
+
+const SelectInputOptionContentWithinTriggerContext = createContext(false);
+
+export interface SelectInputOptionContentProps {
+  title: React.ReactNode;
+  note?: string;
+  description?: string;
+  icon?: React.ReactNode;
+}
+
+export function SelectInputOptionContent({
+  title,
+  note,
+  description,
+  icon,
+}: SelectInputOptionContentProps) {
+  const withinTrigger = useContext(SelectInputOptionContentWithinTriggerContext);
+
+  return (
+    <div
+      className={clsx(
+        'np-select-input-option-content-container',
+        (note || description) && 'np-text-body-large',
+      )}
+    >
+      {icon ? (
+        <div
+          className={clsx(
+            'np-select-input-option-content-icon',
+            !withinTrigger && 'np-select-input-option-content-icon--not-within-trigger',
+          )}
+        >
+          {icon}
+        </div>
+      ) : null}
+
+      <div className="np-select-input-option-content-text">
+        <div
+          className={clsx(
+            'np-select-input-option-content-text-line-1',
+            withinTrigger && 'np-select-input-option-content-text-within-trigger',
+          )}
+        >
+          <div className="d-inline">{title}</div>
+          {note ? (
+            <span className="np-select-input-option-content-text-secondary np-text-body-default">
+              {note}
+            </span>
+          ) : null}
+        </div>
+
+        {description ? (
+          <div
+            className={clsx(
+              'np-select-input-option-content-text-secondary np-text-body-default',
+              withinTrigger &&
+                'np-select-input-option-content-text-within-trigger np-select-input-option-description-in-trigger',
+            )}
+          >
+            {description}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}