@adobe-commerce/elsie 1.6.0-alpha999 → 1.6.0-beta2

package/src/components/MultiSelect/MultiSelect.tsx

@@ -0,0 +1,763 @@
+/********************************************************************
+ *  Copyright 2025 Adobe
+ *  All Rights Reserved.
+ *
+ * NOTICE:  Adobe permits you to use, modify, and distribute this
+ * file in accordance with the terms of the Adobe license agreement
+ * accompanying it.
+ *******************************************************************/
+
+import { FunctionComponent } from 'preact';
+import { Button, Tag } from '@adobe-commerce/elsie/components';
+import { classes } from '@adobe-commerce/elsie/lib';
+import { ChevronDown, Close, Check } from '@adobe-commerce/elsie/icons';
+import { useText } from 'preact-i18n';
+import {
+  useState,
+  useCallback,
+  useEffect,
+  useRef,
+  useMemo,
+} from 'preact/hooks';
+import { JSX } from 'preact/compat';
+import '@adobe-commerce/elsie/components/MultiSelect/MultiSelect.css';
+
+type OptionValue = string | number;
+
+interface Option {
+  label: string;
+  value: OptionValue;
+  disabled?: boolean;
+}
+
+type SelectedValues = OptionValue[];
+
+// Utility functions
+const filterOptions = (options: Option[], searchTerm: string): Option[] => {
+  return options.filter((option) =>
+    option.label.toLowerCase().includes(searchTerm.toLowerCase())
+  );
+};
+
+const getSelectedLabels = (
+  value: SelectedValues,
+  options: Option[]
+): (string | OptionValue)[] => {
+  return value.map((v) => {
+    const option = options.find((opt) => opt.value === v);
+    return option ? option.label : v;
+  });
+};
+
+const generateIds = (id: string, name: string, floatingLabel?: string) => {
+  const baseId = id || name;
+  return {
+    listboxId: `${baseId}-listbox`,
+    searchInputId: `${baseId}-search`,
+    labelId: floatingLabel ? `${baseId}-label` : undefined,
+    selectedDescriptionId: `${name}-selected-description`,
+  };
+};
+
+const useAccessibilityAnnouncements = () => {
+  const [announcement, setAnnouncement] = useState('');
+
+  const announce = useCallback((message: string) => {
+    setAnnouncement(message);
+    setTimeout(() => setAnnouncement(''), 1000);
+  }, []);
+
+  return { announcement, announce };
+};
+
+const useKeyboardNavigation = (
+  filteredOptions: Option[],
+  focusedIndex: number,
+  setFocusedIndex: (value: number | ((prev: number) => number)) => void,
+  dropdownRef: { current: HTMLDivElement | null }
+) => {
+  // Scroll focused item into view
+  useEffect(() => {
+    if (focusedIndex >= 0 && dropdownRef.current) {
+      const items = dropdownRef.current.querySelectorAll('[data-option-index]');
+      if (items[focusedIndex]) {
+        items[focusedIndex].scrollIntoView({
+          block: 'nearest',
+          behavior: 'smooth',
+        });
+      }
+    }
+  }, [focusedIndex, dropdownRef]);
+
+  const navigate = useCallback(
+    (direction: 'up' | 'down') => {
+      setFocusedIndex((prev) => {
+        const step = direction === 'up' ? -1 : 1;
+        let nextIndex = prev + step;
+
+        // Skip disabled options in the current direction
+        while (
+          nextIndex >= 0 &&
+          nextIndex < filteredOptions.length &&
+          filteredOptions[nextIndex]?.disabled
+        ) {
+          nextIndex += step;
+        }
+
+        // If we found a valid option, return it
+        if (nextIndex >= 0 && nextIndex < filteredOptions.length) {
+          return nextIndex;
+        }
+
+        // Wrap around: find the first enabled option from the opposite end
+        if (direction === 'up') {
+          for (let i = filteredOptions.length - 1; i >= 0; i--) {
+            if (!filteredOptions[i]?.disabled) return i;
+          }
+        } else {
+          for (let i = 0; i < filteredOptions.length; i++) {
+            if (!filteredOptions[i]?.disabled) return i;
+          }
+        }
+
+        return -1;
+      });
+    },
+    [filteredOptions, setFocusedIndex]
+  );
+
+  return { navigate };
+};
+
+export interface MultiSelectProps {
+  options: Option[];
+  value: SelectedValues;
+  onChange: (value: SelectedValues) => void;
+  placeholder?: string;
+  selectAllText?: string;
+  deselectAllText?: string;
+  noResultsText?: string;
+  name?: string;
+  disabled?: boolean;
+  className?: string;
+  maxHeight?: number;
+  floatingLabel?: string;
+  error?: boolean;
+  success?: boolean;
+  id?: string;
+}
+
+export const MultiSelect: FunctionComponent<MultiSelectProps> = ({
+  options = [],
+  value = [],
+  onChange = () => {},
+  id = '',
+  className = '',
+  selectAllText = '',
+  deselectAllText = '',
+  placeholder = '',
+  noResultsText = '',
+  floatingLabel = '',
+  name = 'multi-select-sdk',
+  error = false,
+  success = false,
+  disabled = false,
+  maxHeight = 300,
+}) => {
+  const translations = useText({
+    selectAll: 'Dropin.MultiSelect.selectAll',
+    deselectAll: 'Dropin.MultiSelect.deselectAll',
+    placeholder: 'Dropin.MultiSelect.placeholder',
+    noResultsText: 'Dropin.MultiSelect.noResultsText',
+    removed: 'Dropin.MultiSelect.ariaLabel.removed',
+    added: 'Dropin.MultiSelect.ariaLabel.added',
+    itemsSelected: 'Dropin.MultiSelect.ariaLabel.itemsSelected',
+    itemsAdded: 'Dropin.MultiSelect.ariaLabel.itemsAdded',
+    itemsRemoved: 'Dropin.MultiSelect.ariaLabel.itemsRemoved',
+    selectedTotal: 'Dropin.MultiSelect.ariaLabel.selectedTotal',
+    noResultsFor: 'Dropin.MultiSelect.ariaLabel.noResultsFor',
+    optionsAvailable: 'Dropin.MultiSelect.ariaLabel.optionsAvailable',
+    dropdownExpanded: 'Dropin.MultiSelect.ariaLabel.dropdownExpanded',
+    useArrowKeys: 'Dropin.MultiSelect.ariaLabel.useArrowKeys',
+    removeFromSelection: 'Dropin.MultiSelect.ariaLabel.removeFromSelection',
+    fromSelection: 'Dropin.MultiSelect.ariaLabel.fromSelection',
+    selectedItem: 'Dropin.MultiSelect.ariaLabel.selectedItem',
+    inField: 'Dropin.MultiSelect.ariaLabel.inField',
+    selectedItems: 'Dropin.MultiSelect.ariaLabel.selectedItems',
+    scrollableOptionsList: 'Dropin.MultiSelect.ariaLabel.scrollableOptionsList',
+    selectOptions: 'Dropin.MultiSelect.ariaLabel.selectOptions',
+    itemAction: 'Dropin.MultiSelect.ariaLabel.itemAction',
+    bulkAdded: 'Dropin.MultiSelect.ariaLabel.bulkAdded',
+    bulkRemoved: 'Dropin.MultiSelect.ariaLabel.bulkRemoved',
+    dropdownExpandedWithOptions:
+      'Dropin.MultiSelect.ariaLabel.dropdownExpandedWithOptions',
+    selectedItemInField: 'Dropin.MultiSelect.ariaLabel.selectedItemInField',
+    removeFromSelectionWithText:
+      'Dropin.MultiSelect.ariaLabel.removeFromSelectionWithText',
+    itemsSelectedDescription:
+      'Dropin.MultiSelect.ariaLabel.itemsSelectedDescription',
+    noItemsSelected: 'Dropin.MultiSelect.ariaLabel.noItemsSelected',
+  });
+
+  const [isOpen, setIsOpen] = useState(false);
+  const [searchTerm, setSearchTerm] = useState('');
+  const [focusedIndex, setFocusedIndex] = useState(-1);
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const searchInputRef = useRef<HTMLInputElement>(null);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  const { announcement, announce } = useAccessibilityAnnouncements();
+
+  // Helper function to close dropdown and optionally reset search state
+  const closeDropdown = useCallback((resetSearch = false) => {
+    setIsOpen(false);
+    if (resetSearch) {
+      setSearchTerm('');
+    }
+    setFocusedIndex(-1);
+  }, []);
+
+  // Filter options based on the search term
+  const filteredOptions = useMemo(
+    () => filterOptions(options, searchTerm),
+    [options, searchTerm]
+  );
+
+  // Keyboard navigation
+  const { navigate } = useKeyboardNavigation(
+    filteredOptions,
+    focusedIndex,
+    setFocusedIndex,
+    dropdownRef
+  );
+
+  // Close dropdown on the outside click
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (
+        containerRef.current &&
+        event.target &&
+        !containerRef.current.contains(event.target as Node)
+      ) {
+        closeDropdown(true); // Reset search when clicking outside
+      }
+    };
+
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, [closeDropdown]);
+
+  // Toggle dropdown on container click (excluding tags)
+  const handleContainerClick = (event: MouseEvent) => {
+    if (
+      !disabled &&
+      searchInputRef.current &&
+      event.target &&
+      !(event.target as Element).closest('[data-tag]')
+    ) {
+      if (isOpen) {
+        closeDropdown(false); // Don't reset search when clicking inside
+      } else {
+        searchInputRef.current.focus();
+        setIsOpen(true);
+      }
+    }
+  };
+
+  // Handle option selection/deselection
+  const handleSelect = useCallback(
+    (optionValue: OptionValue) => {
+      const option = options.find((opt) => opt.value === optionValue);
+
+      const isCurrentlySelected = value.includes(optionValue);
+      const newValue = isCurrentlySelected
+        ? value.filter((v) => v !== optionValue)
+        : [...value, optionValue];
+
+      onChange(newValue);
+      searchInputRef.current?.focus();
+
+      // A11y - Announce the selection change
+      if (option) {
+        const action = isCurrentlySelected
+          ? translations.removed
+          : translations.added;
+        announce(
+          translations.itemAction
+            .replace('{label}', option.label)
+            .replace('{action}', action)
+            .replace('{count}', newValue.length.toString())
+        );
+      }
+    },
+    [value, onChange, options, announce, translations]
+  );
+
+  // Handle option deselection via the Tag button
+  const handleRemoveTag = (event: MouseEvent, optionValue: OptionValue) => {
+    event.stopPropagation();
+    const option = options.find((opt) => opt.value === optionValue);
+    const newValue = value.filter((v) => v !== optionValue);
+    onChange(newValue);
+    searchInputRef.current?.focus();
+
+    // A11y - Announce the selection change
+    if (option) {
+      announce(
+        translations.itemAction
+          .replace('{label}', option.label)
+          .replace('{action}', translations.removed)
+          .replace('{count}', newValue.length.toString())
+      );
+    }
+  };
+
+  const handleSelectAll = (event: MouseEvent) => {
+    event.preventDefault();
+    const allFilteredValues = filteredOptions.map((opt) => opt.value);
+    const currentValueSet = new Set(value);
+    const newSelections = allFilteredValues.filter(
+      (val) => !currentValueSet.has(val)
+    );
+    const newValue = [...value, ...newSelections];
+    onChange(newValue);
+
+    // Announce the bulk selection
+    if (newSelections.length > 0) {
+      announce(
+        translations.bulkAdded
+          .replace('{count}', newSelections.length.toString())
+          .replace('{total}', newValue.length.toString())
+      );
+    }
+  };
+
+  const handleDeselectAll = (event: MouseEvent) => {
+    event.preventDefault();
+    const filteredValues = new Set(filteredOptions.map((opt) => opt.value));
+    const removedCount = value.filter((v) => filteredValues.has(v)).length;
+    const newValue = value.filter((v) => !filteredValues.has(v));
+    onChange(newValue);
+
+    // A11y - Announce the bulk deselection
+    if (removedCount > 0) {
+      announce(
+        translations.bulkRemoved
+          .replace('{count}', removedCount.toString())
+          .replace('{total}', newValue.length.toString())
+      );
+    }
+  };
+
+  // A11y - Keyboard navigation
+  const handleInputKeyDown = (
+    event: JSX.TargetedKeyboardEvent<HTMLInputElement>
+  ) => {
+    // Handle backspace to remove the last tag
+    if (event.key === 'Backspace' && searchTerm === '' && value.length > 0) {
+      event.preventDefault();
+      const newValue = value.slice(0, -1);
+      onChange(newValue);
+      return;
+    }
+
+    if (!isOpen && (event.key === 'ArrowDown' || event.key === 'Enter')) {
+      event.preventDefault();
+      setIsOpen(true);
+      return;
+    }
+
+    if (isOpen) {
+      switch (event.key) {
+        case 'ArrowDown':
+          event.preventDefault();
+          navigate('down');
+          break;
+        case 'ArrowUp':
+          event.preventDefault();
+          navigate('up');
+          break;
+        case 'Enter':
+          event.preventDefault();
+          if (focusedIndex >= 0 && focusedIndex < filteredOptions.length) {
+            const focusedOption = filteredOptions[focusedIndex];
+            if (!focusedOption?.disabled) {
+              handleSelect(focusedOption.value);
+            }
+          } else if (
+            filteredOptions.length === 1 &&
+            !filteredOptions[0]?.disabled
+          ) {
+            handleSelect(filteredOptions[0].value);
+          }
+          break;
+        case 'Escape':
+          event.preventDefault();
+          closeDropdown(true); // Reset search on Escape
+          break;
+        case 'Tab':
+          closeDropdown(true); // Reset search on Tab (leaving component)
+          break;
+      }
+    }
+  };
+
+  // Array with labels of all selected options
+  const selectedLabels = useMemo(
+    () => getSelectedLabels(value, options),
+    [value, options]
+  );
+
+  // A11y - Generate unique IDs
+  const { listboxId, searchInputId, labelId, selectedDescriptionId } =
+    generateIds(id, name, floatingLabel);
+  const currentFocusedId =
+    focusedIndex >= 0 ? `${listboxId}-option-${focusedIndex}` : '';
+
+  // Check if any items are selected (regardless of filtering)
+  const hasSelection = useMemo(() => value.length > 0, [value]);
+
+  useEffect(() => {
+    if (searchTerm && !isOpen) {
+      setIsOpen(true);
+    }
+  }, [isOpen, searchTerm]);
+
+  // Announce filtered results
+  useEffect(() => {
+    if (isOpen && searchTerm) {
+      const count = filteredOptions.length;
+      if (count === 0) {
+        announce(`${translations.noResultsFor} "${searchTerm}"`);
+      } else {
+        announce(`${count} ${translations.optionsAvailable}`);
+      }
+    }
+  }, [filteredOptions.length, searchTerm, isOpen, announce, translations]);
+
+  useEffect(() => {
+    if (isOpen && searchInputRef.current) {
+      searchInputRef.current.focus();
+      // Announce when dropdown opens with available options
+      if (filteredOptions.length > 0) {
+        announce(
+          translations.dropdownExpandedWithOptions
+            .replace('{count}', filteredOptions.length.toString())
+            .replace('{s}', filteredOptions.length === 1 ? '' : 's')
+        );
+      }
+    }
+  }, [
+    isOpen,
+    selectedLabels.length,
+    filteredOptions.length,
+    announce,
+    translations,
+  ]);
+
+  const renderSelectedTags = () => (
+    <>
+      {selectedLabels.map((label, index) => {
+        const totalSelected = value.length;
+        const fieldContext = floatingLabel ? `${floatingLabel}: ` : '';
+        // Use i18n translations for selected items text
+        const selectedItemsText =
+          totalSelected === 1
+            ? `${fieldContext}${translations.itemsSelected
+                .replace('{count}', '1')
+                .replace('{labels}', String(label))
+                .replace('{s}', '')}`
+            : `${fieldContext}${translations.itemsSelected
+                .replace('{count}', totalSelected.toString())
+                .replace('{labels}', selectedLabels.join(', '))
+                .replace('{s}', totalSelected === 1 ? '' : 's')}`;
+
+        return (
+          <Tag
+            key={value[index]}
+            data-tag="true"
+            className="dropin-multi-select__tag"
+            role="group"
+            aria-label={
+              floatingLabel
+                ? translations.selectedItemInField
+                    .replace('{label}', String(label))
+                    .replace('{field}', floatingLabel)
+                : `${translations.selectedItem} ${String(label)}`
+            }
+          >
+            <span aria-hidden="true">{label}</span>
+            <button
+              type="button"
+              onClick={(e) => handleRemoveTag(e, value[index])}
+              className="dropin-multi-select__tag-remove"
+              disabled={disabled}
+              aria-label={translations.removeFromSelectionWithText
+                .replace('{label}', String(label))
+                .replace('{text}', selectedItemsText)}
+            >
+              <Close size={12} aria-hidden="true" />
+            </button>
+          </Tag>
+        );
+      })}
+    </>
+  );
+
+  const renderSearchInput = () => (
+    <input
+      id={searchInputId}
+      ref={searchInputRef}
+      type="text"
+      role="combobox"
+      aria-haspopup="listbox"
+      aria-expanded={isOpen}
+      aria-controls={listboxId}
+      className={classes([
+        'dropin-multi-select__search',
+        ['dropin-multi-select__search--with-floating-label', !!floatingLabel],
+      ])}
+      placeholder={
+        value.length === 0 ? placeholder || translations.placeholder : ''
+      }
+      value={searchTerm}
+      onChange={(e: JSX.TargetedEvent<HTMLInputElement, Event>) => {
+        const target = e.target as HTMLInputElement;
+        setSearchTerm(target.value);
+        setFocusedIndex(-1);
+      }}
+      onKeyDown={handleInputKeyDown}
+      onFocus={() => setIsOpen(true)}
+      disabled={disabled}
+      style={{
+        minWidth: searchTerm ? `${searchTerm.length * 8 + 20}px` : '40px',
+      }}
+      aria-autocomplete="list"
+      aria-activedescendant={
+        isOpen && currentFocusedId ? currentFocusedId : undefined
+      }
+      {...(labelId
+        ? { 'aria-labelledby': labelId }
+        : {
+            'aria-label':
+              floatingLabel ||
+              placeholder ||
+              translations.placeholder ||
+              translations.selectOptions,
+          })}
+      aria-describedby={selectedDescriptionId}
+    />
+  );
+
+  const renderDropdownControls = () => (
+    <div className="dropin-multi-select__controls">
+      <Button
+        variant="tertiary"
+        type="button"
+        className="dropin-multi-select__button dropin-multi-select__button--select-all"
+        onMouseDown={handleSelectAll}
+        data-testid="multi-select-select-all"
+      >
+        {selectAllText || translations.selectAll}
+      </Button>
+      {' | '}
+      <Button
+        variant="tertiary"
+        type="button"
+        className="dropin-multi-select__button dropin-multi-select__button--deselect-all"
+        onMouseDown={handleDeselectAll}
+        disabled={!hasSelection}
+        data-testid="multi-select-deselect-all"
+      >
+        {deselectAllText || translations.deselectAll}
+      </Button>
+    </div>
+  );
+
+  const renderOptionsList = () => (
+    <ul
+      className="dropin-multi-select__list"
+      id={listboxId}
+      role="listbox"
+      aria-multiselectable="true"
+      aria-label={floatingLabel || placeholder || translations.placeholder}
+    >
+      {filteredOptions.map((option, index) => {
+        const isSelected = value.includes(option.value);
+        const isFocused = index === focusedIndex;
+        const optionId = `${listboxId}-option-${index}`;
+
+        return (
+          <li
+            key={option.value}
+            id={optionId}
+            data-option-index={index}
+            data-testid={`multi-select-option-${index}`}
+            className={classes([
+              'dropin-multi-select__option',
+              ['dropin-multi-select__option--focused', isFocused],
+              ['dropin-multi-select__option--selected', isSelected],
+              ['dropin-multi-select__option--disabled', option.disabled],
+            ])}
+            onClick={() => {
+              if (!option.disabled) {
+                handleSelect(option.value);
+              }
+            }}
+            onMouseEnter={() => !option.disabled && setFocusedIndex(index)}
+            role="option"
+            aria-selected={isSelected}
+            aria-disabled={option.disabled}
+          >
+            <span
+              className={classes([
+                'dropin-multi-select__option-label',
+                [
+                  'dropin-multi-select__option-label--disabled',
+                  option.disabled,
+                ],
+              ])}
+            >
+              {option.label}
+            </span>
+            {isSelected && (
+              <Check
+                width={16}
+                height={16}
+                className="dropin-multi-select__check-icon"
+                aria-hidden="true"
+              />
+            )}
+          </li>
+        );
+      })}
+    </ul>
+  );
+
+  return (
+    <div
+      ref={containerRef}
+      data-testid="multi-select"
+      className={classes(['dropin-multi-select', className])}
+    >
+      {/* Single hidden input with comma-separated values for form submission */}
+      <input
+        id={id || name}
+        type="hidden"
+        name={name}
+        data-testid="multi-select-hidden-input"
+        value={value.join(',')}
+        disabled={disabled}
+        aria-hidden="true"
+      />
+      <div
+        className={classes([
+          'dropin-multi-select__container',
+          ['dropin-multi-select__container--open', isOpen],
+          ['dropin-multi-select__container--disabled', disabled],
+          ['dropin-multi-select__container--error', error],
+          ['dropin-multi-select__container--success', success],
+          [
+            'dropin-multi-select__container--with-floating-label',
+            !!floatingLabel,
+          ],
+          [
+            'dropin-multi-select__container--has-value',
+            !!(floatingLabel && (value.length > 0 || searchTerm.length > 0)),
+          ],
+        ])}
+        onMouseDown={handleContainerClick}
+        data-testid="multi-select-container"
+      >
+        <div
+          className={classes([
+            'dropin-multi-select__tags-area',
+            [
+              'dropin-multi-select__tags-area--has-values',
+              selectedLabels.length > 0,
+            ],
+          ])}
+          data-testid="multi-select-tags-area"
+          role="group"
+          aria-label={translations.selectedItems}
+        >
+          {/* Screen-reader-only description of selected items */}
+          <div
+            id={selectedDescriptionId}
+            className="dropin-multi-select__sr-only"
+            aria-live="polite"
+            aria-atomic="true"
+          >
+            {value.length > 0
+              ? translations.itemsSelectedDescription
+                  .replace('{count}', value.length.toString())
+                  .replace('{s}', value.length === 1 ? '' : 's')
+                  .replace('{labels}', selectedLabels.join(', '))
+              : translations.noItemsSelected}
+          </div>
+
+          {renderSelectedTags()}
+          {renderSearchInput()}
+          {floatingLabel ? (
+            <label
+              className="dropin-multi-select__floating-label"
+              htmlFor={searchInputId}
+              id={labelId}
+            >
+              {floatingLabel}
+            </label>
+          ) : null}
+        </div>
+        <ChevronDown
+          className={classes([
+            'dropin-multi-select__chevron',
+            ['dropin-multi-select__chevron--open', isOpen],
+          ])}
+        />
+      </div>
+
+      {isOpen && (
+        <div
+          className="dropin-multi-select__dropdown"
+          data-testid="multi-select-dropdown"
+        >
+          {filteredOptions.length > 0 && renderDropdownControls()}
+
+          <div
+            ref={dropdownRef}
+            className="dropin-multi-select__options"
+            data-testid="multi-select-options"
+            style={{ maxHeight: `${maxHeight}px` }}
+            tabIndex={0}
+            role="region"
+            aria-label={translations.scrollableOptionsList}
+          >
+            {filteredOptions.length === 0 ? (
+              <div
+                className="dropin-multi-select__no-results"
+                data-testid="multi-select-no-results"
+                role="status"
+                aria-live="polite"
+              >
+                {noResultsText || translations.noResultsText}{' '}
+                {searchTerm && `"${searchTerm}"`}
+              </div>
+            ) : (
+              renderOptionsList()
+            )}
+          </div>
+        </div>
+      )}
+
+      {/* Live region for screen reader announcements */}
+      <div
+        className="dropin-multi-select__announcements dropin-multi-select__sr-only"
+        aria-live="assertive"
+        aria-atomic="true"
+      >
+        {announcement}
+      </div>
+    </div>
+  );
+};