@transferwise/components 46.130.2 → 46.131.0

package/src/inputs/SelectInput/SelectInput.tsx

@@ -0,0 +1,257 @@
+import mergeProps from 'merge-props';
+import { useEffect, useRef, useState, useDeferredValue } from 'react';
+import { Listbox as ListboxBase } from '@headlessui/react';
+import { useScreenSize } from '../../common/hooks/useScreenSize';
+import { Breakpoint } from '../../common/propsValues/breakpoint';
+import { useEffectEvent } from '../../common/hooks/useEffectEvent';
+import { useInputAttributes } from '../contexts';
+
+import { SelectInputBottomSheet } from './BottomSheet';
+import { SelectInputPopover } from './Popover';
+import { SelectInputOptions } from './Options';
+import { DefaultRenderTrigger } from './DefaultRenderTrigger';
+
+import {
+  SelectInputOptionContentWithinTriggerContext,
+  SelectInputTriggerButtonPropsContext,
+} from './SelectInput.contexts';
+import { searchableString, sortByRelevance } from './SelectInput.utils';
+import { SelectInputProps } from './SelectInput.types';
+
+const noop = () => {};
+
+/**
+ * SelectInput component allows users to select an option from a dropdown list.
+ * Supports filtering, multiple selection, and customization.
+ */
+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 ? SelectInputPopover : SelectInputBottomSheet;
+
+  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;
+                    }
+                  },
+                  size,
+                  ...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>
+  );
+}
+
+// Attach sortByRelevance to the component for convenience
+SelectInput.sortByRelevance = sortByRelevance;

package/src/inputs/SelectInput/SelectInput.types.ts

@@ -0,0 +1,113 @@
+import React, { ReactNode } from 'react';
+import { ButtonProps } from '../../button/Button.types';
+import { WithInputAttributesProps } from './SelectInput.contexts';
+
+// Item interfaces
+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;
+
+// Main component props
+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;
+}
+
+export type {
+  SelectInputTriggerButtonElementType,
+  SelectInputTriggerButtonProps,
+} from './TriggerButton';
+export type { SelectInputClearButtonProps } from './ClearButton';
+export type { SelectInputOptionContentProps } from './OptionContent';
+export type { SelectInputOptionProps } from './Option';
+export type { SelectInputItemViewProps } from './ItemView';
+export type { SelectInputGroupItemViewProps } from './ItemView/GroupItemView';
+export type { SelectInputOptionsProps } from './Options';
+export type { SelectInputOptionsContainerProps } from './Options/OptionsContainer';

package/src/inputs/SelectInput/SelectInput.utils.ts

@@ -0,0 +1,205 @@
+import { SelectInputItem, SelectInputOptionItem } from './SelectInput.types';
+
+export const MAX_ITEMS_WITHOUT_VIRTUALIZATION = 50;
+
+/**
+ * Converts a string to a normalized, searchable format by:
+ * - Trimming whitespace
+ * - Normalizing whitespace (convert multiple spaces to single space)
+ * - Converting to NFD normalization form to handle diacritics
+ * - Removing combining diacritical marks
+ * - Converting to lowercase
+ */
+export 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()
+  );
+}
+
+/**
+ * Extracts searchable strings from a value.
+ * - If the value is a string, returns a normalized version.
+ * - If the value is an object, extracts all string values and normalizes them.
+ * - Otherwise returns an empty array.
+ */
+export 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 [];
+}
+
+/**
+ * Sets the value of a duplicate option item to undefined, effectively hiding it when rendered.
+ */
+export 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.
+ */
+export 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;
+  });
+}
+
+/**
+ * Checks if a SelectInputOptionItem matches the search needle.
+ */
+export function selectInputOptionItemIncludesNeedle<T>(
+  item: SelectInputOptionItem<T>,
+  needle: string,
+) {
+  return inferSearchableStrings(item.filterMatchers ?? item.value).some((haystack) =>
+    haystack.includes(needle),
+  );
+}
+
+/**
+ * Filters SelectInputItems based on the provided predicate function.
+ * For group items, it checks if any of their options match the predicate.
+ */
+export 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.
+ */
+export 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);
+  };
+}

package/src/inputs/SelectInput/TriggerButton/SelectInputTriggerButton.tsx

@@ -0,0 +1,36 @@
+import { ListboxButton } from '@headlessui/react';
+import mergeProps from 'merge-props';
+import { useContext } from 'react';
+import { PolymorphicWithOverrides } from '../../../common/polymorphicWithOverrides/PolymorphicWithOverrides';
+import { Merge } from '../../../utils';
+import { SelectInputTriggerButtonPropsContext } from '../SelectInput.contexts';
+
+export type SelectInputTriggerButtonElementType = 'button' | React.ComponentType;
+
+export type SelectInputTriggerButtonProps<
+  T extends SelectInputTriggerButtonElementType = 'button',
+> = Merge<React.ComponentPropsWithoutRef<T>, { as?: T }>;
+
+/**
+ * The trigger button component for SelectInput.
+ * Uses Headless UI's ListboxButton with polymorphic support to allow
+ * rendering as different element types.
+ */
+export function SelectInputTriggerButton<T extends SelectInputTriggerButtonElementType = 'button'>({
+  as = 'button' as T,
+  ...restProps
+}: SelectInputTriggerButtonProps<T>) {
+  const { ref, onClick, onKeyDown, size, ...interactionProps } = useContext(
+    SelectInputTriggerButtonPropsContext,
+  );
+
+  return (
+    <ListboxButton
+      ref={ref}
+      as={PolymorphicWithOverrides}
+      role="combobox"
+      __overrides={{ as, size, ...interactionProps } as Record<string, unknown>}
+      {...mergeProps({ onClick, onKeyDown }, restProps)}
+    />
+  );
+}

package/src/inputs/SelectInput/TriggerButton/index.ts

@@ -0,0 +1,5 @@
+export { SelectInputTriggerButton } from './SelectInputTriggerButton';
+export type {
+  SelectInputTriggerButtonElementType,
+  SelectInputTriggerButtonProps,
+} from './SelectInputTriggerButton';

package/src/inputs/{SelectInput.docs.mdx → SelectInput/_stories/SelectInput.docs.mdx}

@@ -1,5 +1,4 @@
 import { Meta } from '@storybook/addon-docs/blocks';
-import { MoneyInput } from '..';
 
 <Meta title="Forms/SelectInput/Accessibility" />
 

package/src/inputs/{SelectInput.story.tsx → SelectInput/_stories/SelectInput.story.tsx}

@@ -5,19 +5,19 @@ import { Flag } from '@wise/art';
 import { clsx } from 'clsx';
 import { useState } from 'react';
 
-import Button from '../button';
-import { getMonthNames } from '../common/dateUtils';
-import Drawer from '../drawer';
-import { Field } from '../field/Field';
-import Modal from '../modal';
-import { wait } from '../test-utils/wait';
+import Button from '../../../button';
+import { getMonthNames } from '../../../common/dateUtils';
+import Drawer from '../../../drawer';
+import { Field } from '../../../field/Field';
+import Modal from '../../../modal';
+import { wait } from '../../../test-utils/wait';
 import {
   SelectInput,
   type SelectInputItem,
   SelectInputOptionContent,
   type SelectInputProps,
   SelectInputTriggerButton,
-} from './SelectInput';
+} from '..';
 
 const meta = {
   title: 'Forms/SelectInput',
@@ -35,7 +35,10 @@ const meta = {
       },
     },
   },
-  parameters: { actions: { argTypesRegex: '' } },
+  parameters: {
+    docs: { toc: true },
+    actions: { argTypesRegex: '' },
+  },
 } satisfies Meta<typeof SelectInput>;
 export default meta;
 

package/src/inputs/{SelectInput.test.story.tsx → SelectInput/_stories/SelectInput.test.story.tsx}

@@ -2,16 +2,12 @@ import type { Meta, StoryObj } from '@storybook/react-webpack5';
 import { fireEvent, fn, type Mock, screen, userEvent, within } from 'storybook/test';
 import { useState } from 'react';
 
-import { allModes } from '../../.storybook/modes';
-import Body from '../body';
-import { Field } from '../field/Field';
-import { lorem5, lorem500 } from '../test-utils';
-import {
-  SelectInput,
-  SelectInputOptionContent,
-  type SelectInputProps,
-  sortByRelevance,
-} from './SelectInput';
+import { allModes } from '../../../../.storybook/modes';
+import Body from '../../../body';
+import { Field } from '../../../field/Field';
+import { lorem5, lorem500 } from '../../../test-utils';
+import { sortByRelevance } from '../SelectInput.utils';
+import { SelectInput, SelectInputOptionContent, type SelectInputProps } from '..';
 
 const meta = {
   title: 'Forms/SelectInput/Tests',