@altruist03/ui 0.1.0 → 0.2.0

package/src/components/Selector/Selector.tsx

@@ -0,0 +1,1310 @@
+import React, { useState, useRef, useEffect, useCallback, useMemo, memo } from 'react';
+import { createPortal } from 'react-dom';
+import { getSelectorTokensFromResolved } from '../../tokens';
+import { useTokens } from '../../ThemeProvider/ThemeContext';
+import type { SelectorOption, SelectorProps } from './Selector.types';
+import { Badge } from '../Badge/Badge';
+import { Checkbox } from '../Checkbox/Checkbox';
+import { Skeleton } from '../Skeleton/Skeleton';
+
+const LIST_MAX_HEIGHT = 300;
+const ESTIMATED_OPTION_ROW_HEIGHT = 40;
+const ESTIMATED_GROUP_HEADING_HEIGHT = 32;
+const ESTIMATED_EMPTY_STATE_HEIGHT = 48;
+
+export type { SelectorOption, SelectorProps };
+
+/** Minimum gap between input and listbox; also used if spacing token is missing. */
+const LISTBOX_GAP_FALLBACK_PX = 8;
+/** Keep the listbox inside the viewport with this margin from the nearest viewport edge. */
+const VIEWPORT_EDGE_MARGIN_PX = 8;
+
+/** Scroll selected option inside the list only — `scrollIntoView` scrolls the window and grows page scroll. */
+function scrollListboxItemIntoView(list: HTMLUListElement, item: HTMLElement) {
+  const pad = 4;
+  const listRect = list.getBoundingClientRect();
+  const itemRect = item.getBoundingClientRect();
+  const itemTop = list.scrollTop + (itemRect.top - listRect.top);
+  const itemBottom = itemTop + itemRect.height;
+  const viewTop = list.scrollTop;
+  const viewBottom = viewTop + list.clientHeight;
+  if (itemTop < viewTop + pad) {
+    list.scrollTop = Math.max(0, itemTop - pad);
+  } else if (itemBottom > viewBottom - pad) {
+    list.scrollTop = Math.max(0, itemBottom - list.clientHeight + pad);
+  }
+}
+
+function getOptionLabelDefault(option: SelectorOption): string {
+  if (typeof option === 'string') return option;
+  return (option as { label?: string }).label ?? String(option);
+}
+
+function getOptionKey<T extends SelectorOption>(
+  option: T,
+  index: number,
+  getOptionLabel: (o: T) => string
+): string {
+  if (typeof option === 'object' && option !== null && 'id' in option) {
+    return String((option as { id?: string }).id);
+  }
+  return `${getOptionLabel(option)}-${index}`;
+}
+
+// ----- Option row (li): shows checkbox when multiple -----
+interface OptionItemProps<T extends SelectorOption> {
+  option: T;
+  optionLabel: string;
+  disabled: boolean;
+  index: number;
+  selected: boolean;
+  multiple: boolean;
+  onSelect: (option: T) => void;
+  renderOption?: (option: T, state: { index: number }) => React.ReactNode;
+  selectorTokens: ReturnType<typeof getSelectorTokensFromResolved>;
+  showFlag?: boolean;
+}
+
+function getOptionIsoCode(option: SelectorOption): string | null {
+  if (typeof option !== 'object' || option == null) return null;
+  const iso = (option as { iso?: unknown }).iso;
+  return typeof iso === 'string' && iso.trim() ? iso.toLowerCase() : null;
+}
+
+function OptionItemInner<T extends SelectorOption>({
+  option,
+  optionLabel,
+  disabled,
+  index,
+  selected,
+  multiple,
+  onSelect,
+  renderOption,
+  selectorTokens: selTokens,
+  showFlag = false,
+}: OptionItemProps<T>) {
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      if (!disabled) onSelect(option);
+    },
+    [option, onSelect, disabled]
+  );
+
+  const handleMouseEnter = useCallback(
+    (e: React.MouseEvent<HTMLLIElement>) => {
+      if (!disabled) e.currentTarget.style.backgroundColor = selTokens.optionHoverBackground;
+    },
+    [disabled, selTokens.optionHoverBackground]
+  );
+
+  const handleMouseLeave = useCallback((e: React.MouseEvent<HTMLLIElement>) => {
+    e.currentTarget.style.backgroundColor = 'transparent';
+  }, []);
+
+  const itemStyle = useMemo(
+    () => ({
+      padding: selTokens.optionPadding,
+      cursor: disabled ? 'not-allowed' : 'pointer',
+      opacity: disabled ? 0.6 : 1,
+      backgroundColor: 'transparent',
+      fontSize: selTokens.optionFontSize,
+      color: selTokens.optionColor,
+      listStyle: 'none' as const,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+    }),
+    [disabled, selTokens.optionPadding, selTokens.optionFontSize, selTokens.optionColor]
+  );
+
+  return (
+    <li
+      role="option"
+      aria-selected={selected}
+      aria-disabled={disabled}
+      onMouseDown={handleMouseDown}
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+      style={itemStyle}
+    >
+      <span style={{ display: 'flex', alignItems: 'center', minWidth: 0 }}>
+        {showFlag && getOptionIsoCode(option) && (
+          <img
+            loading="lazy"
+            width="24px"
+            style={{ marginRight: 8, flexShrink: 0 }}
+            srcSet={`https://flagcdn.com/w40/${getOptionIsoCode(option)}.png 2x`}
+            src={`https://flagcdn.com/w20/${getOptionIsoCode(option)}.png`}
+            alt={`${optionLabel} flag`}
+          />
+        )}
+        <span>{renderOption ? renderOption(option, { index }) : optionLabel}</span>
+      </span>
+      {multiple ?
+        <div style={{ marginLeft: 8, flexShrink: 0, pointerEvents: 'none' }}>
+          <Checkbox
+            label=""
+            checked={selected}
+            disabled={disabled}
+            id={`selector-checkbox-${index}`}
+          />
+        </div>
+      : selected ?
+        <div aria-hidden="true" style={{ marginLeft: 8, flexShrink: 0 }}>
+          {/* <FirebirdIcon name="dubble_check" size={16} /> */}
+        </div>
+      : null}
+    </li>
+  );
+}
+
+const OptionItem = memo(OptionItemInner) as typeof OptionItemInner;
+
+function getListboxStyle(
+  tokens: ReturnType<typeof getSelectorTokensFromResolved>
+): React.CSSProperties {
+  return {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+    background: tokens.listboxBackground,
+    border: tokens.listboxBorder,
+    borderRadius: tokens.listboxBorderRadius,
+    marginTop: 0,
+    padding: 0,
+    listStyle: 'none',
+    maxHeight: LIST_MAX_HEIGHT,
+    overflowY: 'auto',
+    // Prevent wheel/touch scroll from chaining to the page when reaching list edges,
+    // which would otherwise move the anchor input and force a position recompute.
+    overscrollBehavior: 'contain',
+    boxShadow: '0 4px 8px rgba(0,0,0,0.1)',
+    zIndex: 1400,
+  };
+}
+
+const getGroupHeadingStyle = (
+  tokens: ReturnType<typeof getSelectorTokensFromResolved>
+): React.CSSProperties => ({
+  padding: tokens.optionPadding,
+  fontSize: tokens.optionFontSize,
+  fontWeight: 600,
+  color: tokens.optionColor,
+  background: tokens.listboxGroupHeadingBackground,
+  position: 'sticky',
+  top: 0,
+  zIndex: 1,
+  borderBottom: tokens.listboxGroupHeadingBorder,
+});
+
+const defaultGroupListStyle: React.CSSProperties = {
+  listStyle: 'none',
+  margin: 0,
+  padding: 0,
+};
+
+function SelectorInner<T extends SelectorOption>(props: SelectorProps<T>) {
+  const {
+    multiple = false,
+    options = [],
+    value,
+    onChange,
+    label,
+    placeholder = 'Select...',
+    required = false,
+    error,
+    helperText,
+    disabled = false,
+    size = 'md',
+    color = 'grey',
+    noOptionsText = 'No options',
+    loading = false,
+    loadingText = 'Loading…',
+    isOptionDisabled,
+    getOptionLabel = getOptionLabelDefault as (option: T) => string,
+    renderOption,
+    groupBy,
+    renderGroup,
+    id,
+    limitTags = 1,
+    clearable = true,
+    filterOptions: filterOptionsProp,
+    onListboxScroll,
+    onOpenChange,
+    open,
+    skeletonLoading = false,
+    onKeyDown,
+    onInput,
+    showFlag = false,
+    autoComplete = 'off',
+    listboxMinWidth,
+    isOptionEqualToValue,
+  } = props;
+
+  const valueArray = useMemo(
+    () =>
+      multiple ?
+        Array.isArray(value) ?
+          value
+        : []
+      : value != null ? [value as T]
+      : [],
+    [multiple, value]
+  );
+  const hasValueSingle = !multiple && value != null;
+  const hasValuesMulti = multiple && valueArray.length > 0;
+
+  const [inputValue, setInputValue] = useState('');
+  const [isTyping, setIsTyping] = useState(false);
+  const [isOpen, setIsOpen] = useState(false);
+  const [isHovering, setIsHovering] = useState(false);
+  const [isFocused, setIsFocused] = useState(false);
+  const [listboxPosition, setListboxPosition] = useState<{
+    top: number;
+    left: number;
+    width: number;
+    placement: 'up' | 'down';
+    maxHeight: number;
+  } | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  /** Bounds of the combobox/input only (excludes label/helper); used so listbox gaps match the field edges. */
+  const inputAnchorRef = useRef<HTMLDivElement>(null);
+  const listboxRef = useRef<HTMLUListElement>(null);
+  const prevIsOpenForCallbackRef = useRef(isOpen);
+  const didSelectRef = useRef(false);
+  const multiWrapperRef = useRef<HTMLDivElement>(null);
+  const multiInputRef = useRef<HTMLInputElement>(null);
+  const mouseDownOnFieldRef = useRef(false);
+  const listboxPositionRafRef = useRef<number | null>(null);
+
+  const isEqual = useCallback(
+    (a: T, b: T) => (isOptionEqualToValue ? isOptionEqualToValue(a, b) : a === b),
+    [isOptionEqualToValue]
+  );
+
+  const valueSet = useMemo(() => new Set(valueArray), [valueArray]);
+
+  const isSelected = useCallback(
+    (option: T) => {
+      if (isOptionEqualToValue) return valueArray.some((v) => isOptionEqualToValue(v, option));
+      return valueSet.has(option);
+    },
+    [isOptionEqualToValue, valueArray, valueSet]
+  );
+
+  const searchString = isTyping || multiple ? inputValue : '';
+
+  const filterFn = useCallback(
+    (option: T) => {
+      const labelStr = getOptionLabel(option)?.toLowerCase();
+      return labelStr?.includes(searchString?.toLowerCase());
+    },
+    [searchString, getOptionLabel]
+  );
+
+  const filteredOptions = useMemo(
+    () =>
+      filterOptionsProp ?
+        filterOptionsProp(options, {
+          inputValue: searchString,
+          getOptionLabel,
+        })
+      : options.filter(filterFn),
+    [filterOptionsProp, options, searchString, getOptionLabel, filterFn]
+  );
+
+  const groupedFilteredOptions = useMemo(() => {
+    if (!groupBy) return null;
+    const map = new Map<string, T[]>();
+    for (const option of filteredOptions) {
+      const group = String(groupBy(option) ?? '');
+      const arr = map.get(group);
+      if (arr) arr.push(option);
+      else map.set(group, [option]);
+    }
+    return Array.from(map.entries()).map(([group, groupOptions]) => ({
+      group,
+      options: groupOptions,
+    }));
+  }, [filteredOptions, groupBy]);
+
+  const noDataFound = filteredOptions.length === 0 && !loading;
+  const resolvedTokens = useTokens();
+  const selectorTokens = getSelectorTokensFromResolved(resolvedTokens);
+  const listboxGapPx = useMemo(() => {
+    const raw = resolvedTokens?.foundation?.spacing?.['1'];
+    const n =
+      typeof raw === 'string' ? parseInt(raw.replace(/px$/i, ''), 10)
+      : typeof raw === 'number' ? raw
+      : NaN;
+    if (Number.isFinite(n) && n > 0) return n;
+    return LISTBOX_GAP_FALLBACK_PX;
+  }, [resolvedTokens]);
+  const badgeStyle: React.CSSProperties = {
+    backgroundColor: selectorTokens.chipBackground,
+  };
+  const inputHeight =
+    size === 'xs' ? parseInt(selectorTokens.inputHeightXs, 10)
+    : size === 'sm' ? parseInt(selectorTokens.inputHeightSm, 10)
+    : size === 'lg' ? parseInt(selectorTokens.inputHeightLg, 10)
+    : parseInt(selectorTokens.inputHeightMd, 10);
+  const inputPadding =
+    size === 'xs' ? selectorTokens.inputPaddingXs
+    : size === 'sm' ? selectorTokens.inputPaddingSm
+    : size === 'lg' ? selectorTokens.inputPaddingLg
+    : selectorTokens.inputPaddingMd;
+  const inputFontSize =
+    size === 'xs' ? selectorTokens.inputFontSizeXs
+    : size === 'sm' ? selectorTokens.inputFontSizeSm
+    : size === 'lg' ? selectorTokens.inputFontSizeLg
+    : selectorTokens.inputFontSizeMd;
+  const inputBorderRadius =
+    size === 'xs' ? selectorTokens.inputBorderRadiusXs
+    : size === 'sm' ? selectorTokens.inputBorderRadiusSm
+    : size === 'lg' ? selectorTokens.inputBorderRadiusLg
+    : selectorTokens.inputBorderRadiusMd;
+  const showClear =
+    clearable &&
+    (isOpen || (isHovering && !disabled)) &&
+    (multiple ? hasValuesMulti : hasValueSingle || inputValue !== '');
+  const selectedSingleIso =
+    !multiple && showFlag && value != null ? getOptionIsoCode(value as SelectorOption) : null;
+  const inputPaddingRight =
+    disabled ? 20
+    : showClear ? 56
+    : 36;
+  const inputPaddingLeft = selectedSingleIso ? '40px' : '20px';
+
+  const parsePaddingY = useCallback((padding: string) => {
+    // Expected: "6px 12px" or "6 12" etc; we only need the first value
+    const first =
+      String(padding ?? '')
+        .trim()
+        .split(/\s+/)[0] ?? '';
+    const n = parseInt(first, 10);
+    return Number.isFinite(n) ? n : 0;
+  }, []);
+  const wrapperPaddingY = parsePaddingY(inputPadding);
+  const visibleTags =
+    multiple && !isOpen && limitTags >= 0 ? valueArray.slice(0, limitTags) : valueArray;
+  const remainingCount =
+    multiple && !isOpen && limitTags >= 0 ? Math.max(0, valueArray.length - limitTags) : 0;
+
+  useEffect(() => {
+    if (multiple || isTyping) return;
+    if (value != null) {
+      setInputValue(getOptionLabel(value as T));
+    } else {
+      setInputValue('');
+    }
+  }, [multiple, value, getOptionLabel, isTyping]);
+
+  const updateListboxPosition = useCallback(
+    (useMeasuredHeight: boolean) => {
+      const anchor = containerRef.current;
+      if (!anchor) return;
+
+      const rect = anchor.getBoundingClientRect();
+      const inputRect = inputAnchorRef.current?.getBoundingClientRect();
+      const anchorTop = inputRect?.top ?? rect.top;
+      const anchorBottom = inputRect?.bottom ?? rect.bottom;
+
+      const viewportHeight = Math.max(
+        0,
+        window.innerHeight || document.documentElement.clientHeight
+      );
+
+      const headingCount =
+        groupedFilteredOptions ?
+          groupedFilteredOptions.reduce((count, group) => {
+            return group.group ? count + 1 : count;
+          }, 0)
+        : 0;
+      const estimatedListHeight =
+        noDataFound ? ESTIMATED_EMPTY_STATE_HEIGHT
+        : loading && filteredOptions.length === 0 ? ESTIMATED_EMPTY_STATE_HEIGHT
+        : filteredOptions.length * ESTIMATED_OPTION_ROW_HEIGHT +
+          headingCount * ESTIMATED_GROUP_HEADING_HEIGHT;
+      // Estimate the actual dropdown height so we don't force "up" placement
+      // just because LIST_MAX_HEIGHT is large.
+      const neededHeight = Math.min(
+        LIST_MAX_HEIGHT,
+        Math.max(ESTIMATED_EMPTY_STATE_HEIGHT, estimatedListHeight)
+      );
+
+      // Use scrollHeight (natural content height) instead of bounding rect height.
+      // bounding rect returns the already-clamped (visible) height when maxHeight kicks in,
+      // which creates a feedback loop: each reposition shrinks maxHeight further while the
+      // user scrolls inside the list. scrollHeight is stable regardless of the clamp.
+      const measuredHeight =
+        useMeasuredHeight && listboxRef.current ?
+          Math.min(listboxRef.current.scrollHeight, LIST_MAX_HEIGHT)
+        : undefined;
+      // Use real height when available; otherwise estimate for clamp math — not LIST_MAX_HEIGHT,
+      // or short lists get clamped as if 300px tall and sit far below the input.
+      const heightForPosition =
+        typeof measuredHeight === 'number' && measuredHeight > 0 ? measuredHeight : neededHeight;
+
+      const gap = listboxGapPx;
+      const edge = VIEWPORT_EDGE_MARGIN_PX;
+      // List top when opening down: always below the input by `gap` (never overlap the field).
+      const topDown = anchorBottom + gap;
+      // List top when opening up: list bottom sits `gap` px above the input top.
+      const topUp = anchorTop - gap - heightForPosition;
+
+      // Open down only if the full list fits below with a viewport margin; otherwise prefer up.
+      const fitsFullyBelow = topDown + heightForPosition <= viewportHeight - edge;
+      const fitsFullyAbove = topUp >= 0;
+
+      let placement: 'up' | 'down';
+      let top: number;
+
+      if (fitsFullyBelow) {
+        placement = 'down';
+        top = topDown;
+      } else if (fitsFullyAbove) {
+        placement = 'up';
+        top = topUp;
+      } else {
+        const roomBelow = viewportHeight - topDown - edge;
+        const roomAbove = anchorTop - gap - edge;
+        if (roomAbove > roomBelow) {
+          placement = 'up';
+          top = Math.max(0, topUp);
+        } else {
+          placement = 'down';
+          top = topDown;
+        }
+      }
+
+      const availableDown = Math.max(0, viewportHeight - top - edge);
+      const availableUp = Math.max(0, anchorTop - gap - top - edge);
+      const available = placement === 'down' ? availableDown : availableUp;
+      const maxHeight =
+        available > 0 ?
+          Math.min(LIST_MAX_HEIGHT, available)
+        : Math.min(LIST_MAX_HEIGHT, ESTIMATED_EMPTY_STATE_HEIGHT);
+
+      setListboxPosition({
+        top,
+        left: inputRect?.left ?? rect.left,
+        width: inputRect?.width ?? rect.width,
+        placement,
+        maxHeight,
+      });
+    },
+    [filteredOptions.length, groupedFilteredOptions, listboxGapPx, loading, noDataFound]
+  );
+
+  const scheduleListboxPositionUpdate = useCallback(() => {
+    if (listboxPositionRafRef.current != null) {
+      cancelAnimationFrame(listboxPositionRafRef.current);
+    }
+    listboxPositionRafRef.current = requestAnimationFrame(() => {
+      listboxPositionRafRef.current = null;
+      updateListboxPosition(true);
+    });
+  }, [updateListboxPosition]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      setIsTyping(false);
+      setListboxPosition(null);
+      return;
+    }
+
+    let active = true;
+    updateListboxPosition(false);
+
+    // Re-measure after mount (helps for the "up" case and shorter-than-max lists).
+    const measureTimeoutId = window.setTimeout(() => {
+      if (!active) return;
+      updateListboxPosition(true);
+    }, 0);
+
+    // Scroll selected option inside the listbox only (avoid window scroll / page height growth).
+    const scrollTimeoutId = window.setTimeout(() => {
+      if (!active) return;
+      const list = listboxRef.current;
+      if (!list) return;
+      const selectedItem = list.querySelector('[aria-selected="true"]');
+      if (selectedItem) {
+        scrollListboxItemIntoView(list, selectedItem as HTMLElement);
+      }
+    }, 50);
+
+    return () => {
+      active = false;
+      window.clearTimeout(measureTimeoutId);
+      window.clearTimeout(scrollTimeoutId);
+    };
+  }, [isOpen, updateListboxPosition]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleResize = () => {
+      scheduleListboxPositionUpdate();
+    };
+
+    const handleScroll = (event: Event) => {
+      // Ignore the listbox's own internal scroll — it doesn't move the anchor input,
+      // and re-measuring on every option-list scroll causes the dropdown to squeeze.
+      const target = event.target as Node | null;
+      if (target && listboxRef.current?.contains(target)) return;
+      scheduleListboxPositionUpdate();
+    };
+
+    // `capture: true` ensures we react to scroll events from scrollable ancestors.
+    window.addEventListener('resize', handleResize);
+    window.addEventListener('scroll', handleScroll, true);
+
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      window.removeEventListener('scroll', handleScroll, true);
+    };
+  }, [isOpen, scheduleListboxPositionUpdate]);
+
+  useEffect(() => {
+    return () => {
+      if (listboxPositionRafRef.current != null) {
+        cancelAnimationFrame(listboxPositionRafRef.current);
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (prevIsOpenForCallbackRef.current === isOpen) return;
+    prevIsOpenForCallbackRef.current = isOpen;
+    onOpenChange?.(isOpen);
+  }, [isOpen, onOpenChange]);
+
+  useEffect(() => {
+    if (typeof open !== 'boolean') return;
+    setIsOpen(open);
+  }, [open]);
+
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (
+        !containerRef.current?.contains(e.target as Node) &&
+        !listboxRef.current?.contains(e.target as Node)
+      ) {
+        setIsOpen(false);
+      }
+    };
+    const handleMouseUp = () => {
+      mouseDownOnFieldRef.current = false;
+    };
+    document.addEventListener('mousedown', handleClickOutside);
+    document.addEventListener('mouseup', handleMouseUp);
+    return () => {
+      document.removeEventListener('mousedown', handleClickOutside);
+      document.removeEventListener('mouseup', handleMouseUp);
+    };
+  }, []);
+
+  const handleInputChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      setInputValue(e.target.value);
+      setIsTyping(true);
+      setIsOpen(true);
+      onInput?.(e);
+    },
+    [onInput]
+  );
+
+  const handleSelect = useCallback(
+    (option: T) => {
+      if (isOptionDisabled?.(option)) return;
+      if (multiple) {
+        const next =
+          valueArray.some((v) => isEqual(v, option)) ?
+            valueArray.filter((v) => !isEqual(v, option))
+          : [...valueArray, option];
+        (onChange as (v: T[]) => void)?.(next);
+      } else {
+        didSelectRef.current = true;
+        setInputValue(getOptionLabel(option));
+        setIsTyping(false);
+        setIsOpen(false);
+        (onChange as (v: T | null) => void)?.(option);
+        setTimeout(() => {
+          didSelectRef.current = false;
+        }, 0);
+      }
+    },
+    [multiple, valueArray, onChange, getOptionLabel, isOptionDisabled]
+  );
+
+  const handleClear = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      setInputValue('');
+      setIsOpen(false);
+      if (multiple) {
+        (onChange as (v: T[]) => void)?.([]);
+      } else {
+        (onChange as (v: T | null) => void)?.(null);
+      }
+    },
+    [multiple, onChange]
+  );
+
+  const handleRemoveChip = useCallback(
+    (e: React.MouseEvent, option: T) => {
+      e.preventDefault();
+      e.stopPropagation();
+      if (disabled) return;
+      const next = valueArray.filter((v) => !isEqual(v, option));
+      (onChange as (v: T[]) => void)?.(next);
+    },
+    [valueArray, onChange, disabled]
+  );
+
+  const handleFocus = useCallback(() => {
+    setIsFocused(true);
+    if (disabled) return;
+    if (mouseDownOnFieldRef.current) return;
+    setIsOpen(true);
+  }, [disabled]);
+
+  const handleFieldMouseDown = useCallback(() => {
+    mouseDownOnFieldRef.current = true;
+  }, []);
+
+  const handleFieldClick = useCallback(
+    (e: React.MouseEvent) => {
+      mouseDownOnFieldRef.current = false;
+      if (disabled) return;
+      if ((e.target as HTMLElement).closest('button')) return;
+      setIsOpen((prev) => !prev);
+    },
+    [disabled]
+  );
+
+  const handleBlur = useCallback(() => {
+    setIsFocused(false);
+    if (multiple) return;
+    if (didSelectRef.current) return;
+    const valueLabel = value != null ? getOptionLabel(value as T) : '';
+    if (inputValue !== valueLabel) {
+      (onChange as (v: T | null) => void)?.(null);
+      setInputValue('');
+    }
+    setIsTyping(false);
+  }, [multiple, value, inputValue, getOptionLabel, onChange]);
+
+  const handleArrowClick = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      if (!disabled) setIsOpen((prev) => !prev);
+    },
+    [disabled]
+  );
+
+  const preventDefault = useCallback((e: React.MouseEvent) => {
+    e.preventDefault();
+  }, []);
+
+  const handleMultiWrapperMouseDown = useCallback(() => {
+    mouseDownOnFieldRef.current = true;
+  }, []);
+
+  const handleMultiWrapperClick = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      mouseDownOnFieldRef.current = false;
+      if (disabled) return;
+      if ((e.target as HTMLElement).closest('button')) return;
+      setIsOpen((prev) => !prev);
+      // Focus the input after a small delay to ensure it's rendered
+      setTimeout(() => {
+        multiInputRef.current?.focus();
+      }, 0);
+    },
+    [disabled]
+  );
+
+  const inputBackground =
+    color === 'white' ? selectorTokens.inputBackgroundWhite : selectorTokens.inputBackgroundWhite;
+  const wrapperBackground =
+    color === 'white' ? selectorTokens.wrapperBackgroundWhite : selectorTokens.wrapperBackground;
+
+  const inputStyle: React.CSSProperties = useMemo(
+    () => ({
+      width: '100%',
+      padding: inputPadding,
+      paddingLeft: inputPaddingLeft,
+      paddingRight: inputPaddingRight,
+      border:
+        error ? selectorTokens.inputBorderError
+        : isFocused ? selectorTokens.inputBorderActive
+        : '1px solid #c7ced6',
+      borderRadius: inputBorderRadius,
+      fontSize: inputFontSize,
+      minHeight: inputHeight,
+      maxHeight: inputHeight,
+      boxSizing: 'border-box',
+      backgroundColor: disabled ? selectorTokens.inputBackgroundDisabled : inputBackground,
+      outline: 'none',
+      boxShadow: 'none',
+      color: selectorTokens.inputColor,
+      opacity: disabled ? parseFloat(selectorTokens.inputDisabledOpacity) : 1,
+      cursor: disabled ? 'not-allowed' : undefined,
+    }),
+    [
+      inputPaddingRight,
+      inputPaddingLeft,
+      inputHeight,
+      inputPadding,
+      inputBorderRadius,
+      inputFontSize,
+      disabled,
+      isFocused,
+      error,
+      selectorTokens,
+      inputBackground,
+    ]
+  );
+
+  const wrapperStyle: React.CSSProperties = useMemo(
+    () => ({
+      display: 'flex',
+      flexWrap: 'wrap',
+      alignItems: 'center',
+      gap: 8,
+      minHeight: inputHeight,
+      paddingTop: wrapperPaddingY,
+      paddingBottom: wrapperPaddingY,
+      paddingLeft: valueArray.length === 0 ? 16 : 8,
+      paddingRight:
+        disabled ? 20
+        : showClear ? 56
+        : 36,
+      border:
+        error ? selectorTokens.inputBorderError
+        : isFocused ? selectorTokens.inputBorderActive
+        : '1px solid #c7ced6',
+      borderRadius: inputBorderRadius,
+      backgroundColor: disabled ? selectorTokens.wrapperBackgroundDisabled : wrapperBackground,
+      boxSizing: 'border-box',
+      boxShadow: 'none',
+      opacity: disabled ? parseFloat(selectorTokens.inputDisabledOpacity) : 1,
+    }),
+    [
+      inputHeight,
+      wrapperPaddingY,
+      showClear,
+      disabled,
+      valueArray.length,
+      selectorTokens,
+      wrapperBackground,
+      isFocused,
+      error,
+      inputBorderRadius,
+    ]
+  );
+
+  const chipStyle: React.CSSProperties = {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 6,
+    padding: '7px 12px 7px 8px',
+    fontSize: selectorTokens.chipFontSize,
+    backgroundColor: selectorTokens.chipBackground,
+    color: selectorTokens.chipColor,
+    borderRadius: selectorTokens.chipBorderRadius,
+  };
+
+  const handleClearButtonMouseEnter = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      if (!disabled) {
+        e.currentTarget.style.backgroundColor = selectorTokens.buttonHoverBackground;
+        e.currentTarget.style.color = selectorTokens.buttonHoverColor;
+      }
+    },
+    [disabled, selectorTokens.buttonHoverBackground, selectorTokens.buttonHoverColor]
+  );
+  const handleClearButtonMouseLeave = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      e.currentTarget.style.backgroundColor = 'transparent';
+      e.currentTarget.style.color = selectorTokens.buttonColor;
+    },
+    [selectorTokens.buttonColor]
+  );
+  const handleArrowButtonMouseEnter = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      if (!disabled) e.currentTarget.style.color = selectorTokens.buttonColor;
+    },
+    [disabled, selectorTokens.buttonColor]
+  );
+  const handleArrowButtonMouseLeave = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      e.currentTarget.style.color = selectorTokens.buttonColor;
+    },
+    [selectorTokens.buttonColor]
+  );
+
+  const iconButtonStyle: React.CSSProperties = {
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: 24,
+    height: 24,
+    padding: 0,
+    border: 'none',
+    background: 'transparent',
+    cursor: disabled ? 'not-allowed' : 'pointer',
+    color: selectorTokens.buttonColor,
+    borderRadius: '50%',
+  };
+
+  if (skeletonLoading) {
+    return (
+      <div
+        style={{
+          width: '100%',
+          position: 'relative',
+          fontFamily: 'sans-serif',
+        }}
+      >
+        {label && (
+          <label
+            style={{
+              display: 'block',
+              marginBottom: parseInt(selectorTokens.labelMarginBottom, 10),
+              fontSize: selectorTokens.labelFontSize,
+              fontWeight: selectorTokens.labelFontWeight,
+              color: selectorTokens.labelColor,
+            }}
+          >
+            {required && (
+              <span
+                style={{
+                  color: selectorTokens.labelRequiredColor,
+                  marginRight: 4,
+                }}
+              >
+                *
+              </span>
+            )}
+            {label}
+          </label>
+        )}
+        <Skeleton height={inputHeight} borderRadius={8} />
+      </div>
+    );
+  }
+
+  const resolvedHelperText = helperText ?? (typeof error === 'string' ? error : undefined);
+
+  return (
+    <div
+      ref={containerRef}
+      style={{ width: '100%', position: 'relative', fontFamily: 'sans-serif' }}
+    >
+      <style>
+        {`.selector-input::placeholder {
+          color: ${selectorTokens.helperColor};
+        }
+        .selector-listbox {
+          scrollbar-width: thin;
+          scrollbar-color: #C8D0D5 transparent;
+        }
+        .selector-listbox::-webkit-scrollbar {
+          width: 8px;
+        }
+        .selector-listbox::-webkit-scrollbar-track {
+          background: transparent;
+          border-radius: 4px;
+        }
+        .selector-listbox::-webkit-scrollbar-thumb {
+          background-color: #C8D0D5;
+          border-radius: 4px;
+        }
+        .selector-listbox::-webkit-scrollbar-thumb:hover {
+          background-color: #B0B8BD;
+        }
+        .selector-listbox::-webkit-scrollbar-button {
+          display: none !important;
+          width: 0 !important;
+          height: 0 !important;
+        }
+        .selector-listbox::-webkit-scrollbar-button:start:decrement,
+        .selector-listbox::-webkit-scrollbar-button:end:increment {
+          display: none !important;
+        }
+        .selector-listbox::-webkit-scrollbar-corner {
+          background: transparent;
+        }
+        .selector-listbox .custom-checkbox-label:empty {
+          display: none;
+        }
+        .selector-listbox .custom-checkbox-wrapper {
+          margin: 0;
+        }
+        .selector-listbox .custom-checkbox-label {
+          margin-left: 0;
+        }`}
+      </style>
+      {label && (
+        <label
+          onClick={(e) => {
+            if (disabled) return;
+            if (isOpen) {
+              setIsOpen(false);
+            } else {
+              e.preventDefault();
+            }
+          }}
+          style={{
+            display: 'block',
+            marginBottom: parseInt(selectorTokens.labelMarginBottom, 10),
+            fontSize: selectorTokens.labelFontSize,
+            fontWeight: selectorTokens.labelFontWeight,
+            color: selectorTokens.labelColor,
+            // opacity: disabled ? parseFloat(selectorTokens.inputDisabledOpacity) : 1,
+            cursor: 'default',
+          }}
+        >
+          {label}
+          {required && (
+            <span
+              style={{
+                color: selectorTokens.labelRequiredColor,
+                marginRight: 4,
+              }}
+            >
+              *
+            </span>
+          )}
+        </label>
+      )}
+      <div
+        ref={inputAnchorRef}
+        style={{ position: 'relative' }}
+        onMouseEnter={() => setIsHovering(true)}
+        onMouseLeave={() => setIsHovering(false)}
+      >
+        {multiple ?
+          <div
+            ref={multiWrapperRef}
+            role="combobox"
+            aria-expanded={isOpen}
+            aria-haspopup="listbox"
+            style={{
+              ...wrapperStyle,
+              cursor: disabled ? 'not-allowed' : 'text',
+            }}
+            onMouseDown={handleMultiWrapperMouseDown}
+            onClick={handleMultiWrapperClick}
+          >
+            {visibleTags.map((option) => {
+              const optionLabel = getOptionLabel(option);
+              const badgeSize =
+                size === 'xs' || size === 'sm' ? 'sm'
+                : size === 'lg' ? 'lg'
+                : 'md';
+              return (
+                <Badge
+                  key={getOptionKey(option, valueArray.indexOf(option), getOptionLabel)}
+                  size={badgeSize}
+                  onRemove={(e) => handleRemoveChip(e, option)}
+                  disabled={disabled}
+                  removeLabel={`Remove ${optionLabel}`}
+                  style={badgeStyle}
+                >
+                  {optionLabel}
+                </Badge>
+              );
+            })}
+            {remainingCount > 0 && (
+              <span
+                style={{
+                  ...chipStyle,
+                  backgroundColor: 'transparent',
+                  color: selectorTokens.chipColor,
+                  padding: '4px 0',
+                  fontSize: inputFontSize,
+                  fontWeight: 'normal',
+                }}
+              >
+                +{remainingCount}
+              </span>
+            )}
+            {(isOpen || valueArray.length === 0) && (
+              <input
+                ref={multiInputRef}
+                id={id}
+                required={required}
+                type="text"
+                autoComplete={autoComplete}
+                placeholder={valueArray.length === 0 ? placeholder : ''}
+                value={inputValue}
+                onChange={handleInputChange}
+                onKeyDown={(event) => {
+                  onKeyDown?.(event);
+                }}
+                onFocus={handleFocus}
+                onBlur={handleBlur}
+                onInvalid={(e) => {
+                  // Prevent browser-native validation bubble so custom helper text can be shown.
+                  e.preventDefault();
+                }}
+                disabled={disabled}
+                aria-invalid={!!error}
+                className="selector-input"
+                style={{
+                  flex: 1,
+                  minWidth: 60,
+                  border: 'none',
+                  outline: 'none',
+                  fontSize: selectorTokens.chipFontSize,
+                  backgroundColor: 'transparent',
+                  padding: 0,
+                  color: selectorTokens.inputColor,
+                }}
+              />
+            )}
+          </div>
+        : <input
+            id={id}
+            required={required}
+            type="text"
+            autoComplete={autoComplete}
+            placeholder={placeholder}
+            value={inputValue}
+            onChange={handleInputChange}
+            onFocus={handleFocus}
+            onMouseDown={handleFieldMouseDown}
+            onClick={handleFieldClick}
+            onBlur={handleBlur}
+            onInvalid={(e) => {
+              // Prevent browser-native validation bubble so custom helper text can be shown.
+              e.preventDefault();
+            }}
+            disabled={disabled}
+            aria-invalid={!!error}
+            className="selector-input"
+            style={inputStyle}
+          />
+        }
+        {!multiple && selectedSingleIso && (
+          <img
+            loading="lazy"
+            width="24px"
+            style={{
+              position: 'absolute',
+              left: 12,
+              top: '50%',
+              transform: 'translateY(-50%)',
+              pointerEvents: 'none',
+            }}
+            srcSet={`https://flagcdn.com/w40/${selectedSingleIso}.png 2x`}
+            src={`https://flagcdn.com/w20/${selectedSingleIso}.png`}
+            alt={`${inputValue || 'Selected'} flag`}
+          />
+        )}
+        {(showClear || !disabled) && (
+          <div
+            style={{
+              position: 'absolute',
+              right: 8,
+              top: '50%',
+              transform: 'translateY(-50%)',
+              zIndex: 1,
+              display: 'flex',
+              alignItems: 'center',
+              gap: 2,
+            }}
+          >
+            {showClear && (
+              <button
+                type="button"
+                onClick={handleClear}
+                onMouseDown={preventDefault}
+                disabled={disabled}
+                aria-label={multiple ? 'Clear all' : 'Clear'}
+                style={iconButtonStyle}
+                onMouseEnter={handleClearButtonMouseEnter}
+                onMouseLeave={handleClearButtonMouseLeave}
+              >
+                <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+                  <path d="M14 1.41L12.59 0L7 5.59L1.41 0L0 1.41L5.59 7L0 12.59L1.41 14L7 8.41L12.59 14L14 12.59L8.41 7L14 1.41z" />
+                </svg>
+              </button>
+            )}
+            {!disabled && (
+              <button
+                type="button"
+                onClick={handleArrowClick}
+                onMouseDown={preventDefault}
+                aria-label={isOpen ? 'Close dropdown' : 'Open dropdown'}
+                style={{
+                  ...iconButtonStyle,
+                  color: selectorTokens.buttonColor,
+                  transform: isOpen ? 'rotate(180deg)' : 'rotate(0deg)',
+                  transition: 'transform 0.2s',
+                }}
+                onMouseEnter={handleArrowButtonMouseEnter}
+                onMouseLeave={handleArrowButtonMouseLeave}
+              >
+                <svg
+                  width="16"
+                  height="16"
+                  viewBox="0 0 16 16"
+                  fill="none"
+                  xmlns="http://www.w3.org/2000/svg"
+                >
+                  <path
+                    d="M4 6L8 10L12 6"
+                    stroke="currentColor"
+                    strokeWidth="2.5"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                </svg>
+              </button>
+            )}
+          </div>
+        )}
+      </div>
+      {(!!error || !!resolvedHelperText) && (
+        <div
+          style={{
+            fontSize: selectorTokens.helperFontSize,
+            marginTop: 4,
+            color: error ? selectorTokens.helperErrorColor : selectorTokens.helperColor,
+          }}
+          role={error ? 'alert' : undefined}
+        >
+          {resolvedHelperText}
+        </div>
+      )}
+      {isOpen &&
+        listboxPosition &&
+        createPortal(
+          <ul
+            ref={listboxRef}
+            role="listbox"
+            aria-label={label ?? placeholder}
+            aria-multiselectable={multiple}
+            style={{
+              ...getListboxStyle(selectorTokens),
+              position: 'fixed',
+              top: listboxPosition.top,
+              left: listboxPosition.left,
+              width: Math.max(listboxPosition.width, listboxMinWidth ?? 0),
+              maxHeight: listboxPosition.maxHeight,
+              right: 'unset',
+            }}
+            className="selector-listbox"
+            onScroll={onListboxScroll}
+          >
+            {noDataFound && (
+              <li
+                style={{
+                  padding: selectorTokens.optionPadding,
+                  textAlign: 'center',
+                  color: selectorTokens.optionColor,
+                  fontSize: selectorTokens.optionFontSize,
+                }}
+              >
+                {noOptionsText}
+              </li>
+            )}
+            {!noDataFound &&
+              (groupedFilteredOptions ?
+                (() => {
+                  let globalIndex = 0;
+                  return groupedFilteredOptions.map(({ group, options }, groupIdx) => {
+                    const children = options.map((option) => {
+                      const optionIndex = globalIndex++;
+                      const disabledOption = isOptionDisabled?.(option) ?? false;
+                      const optionLabel = getOptionLabel(option);
+                      const selected = isSelected(option);
+                      return (
+                        <OptionItem
+                          key={getOptionKey(option, optionIndex, getOptionLabel)}
+                          option={option}
+                          optionLabel={optionLabel}
+                          disabled={disabledOption}
+                          index={optionIndex}
+                          selected={selected}
+                          multiple={multiple}
+                          onSelect={handleSelect}
+                          renderOption={renderOption}
+                          selectorTokens={selectorTokens}
+                          showFlag={showFlag}
+                        />
+                      );
+                    });
+
+                    const params = {
+                      key: `selector-group-${groupIdx}-${group}`,
+                      group,
+                      children,
+                    };
+
+                    if (!group) {
+                      return <React.Fragment key={params.key}>{children}</React.Fragment>;
+                    }
+
+                    return (
+                      <li key={params.key} style={{ listStyle: 'none' }}>
+                        <div style={getGroupHeadingStyle(selectorTokens)}>{group}</div>
+                        {renderGroup ?
+                          renderGroup(params)
+                        : <ul role="group" aria-label={group} style={defaultGroupListStyle}>
+                            {children}
+                          </ul>
+                        }
+                      </li>
+                    );
+                  });
+                })()
+              : filteredOptions.map((option, index) => {
+                  const disabledOption = isOptionDisabled?.(option) ?? false;
+                  const optionLabel = getOptionLabel(option);
+                  const selected = valueSet.has(option);
+                  return (
+                    <OptionItem
+                      key={getOptionKey(option, index, getOptionLabel)}
+                      option={option}
+                      optionLabel={optionLabel}
+                      disabled={disabledOption}
+                      index={index}
+                      selected={selected}
+                      multiple={multiple}
+                      onSelect={handleSelect}
+                      renderOption={renderOption}
+                      selectorTokens={selectorTokens}
+                      showFlag={showFlag}
+                    />
+                  );
+                }))}
+            {loading && !noDataFound && (
+              <li
+                style={{
+                  padding: selectorTokens.optionPadding,
+                  textAlign: 'center',
+                  color: selectorTokens.optionColor,
+                  fontSize: selectorTokens.optionFontSize,
+                }}
+              >
+                {loadingText}
+              </li>
+            )}
+          </ul>,
+          document.body
+        )}
+    </div>
+  );
+}
+
+const Selector = memo(SelectorInner) as typeof SelectorInner;
+export default Selector;