@altruist03/ui 0.1.0 → 0.2.1

package/src/components/SelectScroll/SelectScroll.tsx

@@ -0,0 +1,1119 @@
+import React, { useState, useRef, useEffect, useLayoutEffect, useCallback, useMemo } from 'react';
+import { createPortal } from 'react-dom';
+import { getSelectScrollTokensFromResolved } from '../../tokens';
+import { useTokens } from '../../ThemeProvider/ThemeContext';
+import { Checkbox } from '../Checkbox/Checkbox';
+import { lockScroll, unlockScroll } from '../../utils/scrollLock';
+
+const LIST_MAX_HEIGHT = 300;
+const NO_OPTIONS_TEXT = 'No options';
+
+export type SelectScrollOption = string | { label?: string; [key: string]: unknown };
+
+export interface SelectScrollProps<T = SelectScrollOption> {
+  placeholder?: string;
+  options?: T[];
+  isDisabled?: boolean;
+  onChange?: (value: T | null) => void;
+  value?: T | null;
+  required?: boolean;
+  isOptionDisabled?: (option: T) => boolean;
+  loading?: boolean;
+  onScroll?: (e: React.UIEvent<HTMLUListElement>) => void;
+  /** Called when list is scrolled near bottom (e.g. to load next page). Pass your API/loadMore function from parent. */
+  onLoadMore?: () => void;
+  /** API method to load more: (pageNum, append) => void. Use with loadMorePage, onLoadMorePageChange, loadMoreHasMore. */
+  loadMoreMethod?: (pageNum: number, append: boolean) => void;
+  /** Current page when using loadMoreMethod (parent state). */
+  loadMorePage?: number;
+  /** Callback when page changes (e.g. setPage from parent). */
+  onLoadMorePageChange?: (nextPage: number) => void;
+  /** Whether more data is available when using loadMoreMethod. */
+  loadMoreHasMore?: boolean;
+  label?: string;
+  size?: 'sm' | 'md' | 'lg';
+  getOptionLabel?: (option: T) => string;
+  isInvalid?: boolean;
+  error?: string;
+  /** Shown below input when not in error state (when isInvalid is false). */
+  helperText?: string;
+  renderOption?: (option: T, state: { index: number }) => React.ReactNode;
+  onInputChange?: (value: string) => void;
+  customRenderOptionView?: (option: T) => React.ReactNode;
+  onBlur?: (e: React.FocusEvent) => void;
+  id?: string;
+  noOptionsText?: string;
+  loadingText?: string;
+  style?: React.CSSProperties;
+  /** Custom filter: (options, { inputValue, getOptionLabel }) => filtered options. When not provided, filters by input matching option label. */
+  filterOptions?: (
+    options: T[],
+    state: { inputValue: string; getOptionLabel: (option: T) => string }
+  ) => T[];
+  /**
+   * When true (default), options are treated as server-driven: no client-side label filtering.
+   * Use `onApiSearch` for debounced backend search; pair with `onInputChange` if you need a ref to the latest typed value for scroll/load-more.
+   */
+  isApiSearch?: boolean;
+  /** Debounce (ms) before calling `onApiSearch` after typing. Default 1000. Ignored when `isApiSearch` is false or `onApiSearch` is omitted. */
+  apiSearchDebounceMs?: number;
+  /** Called after debounce with the trimmed search string. Reset lists and fetch page 0 in the parent. */
+  onApiSearch?: (searchTerm: string) => void;
+  /** Background color variant */
+  color?: 'grey' | 'white';
+  /** Fires after mount is skipped; use for lazy load when `true` and cleanup when `false` (e.g. restore server list). */
+  onOpenChange?: (open: boolean) => void;
+  /** Shows clear (X) action and allows clearing when true. */
+  clearable?: boolean;
+  /** Custom equality for highlighting the selected option. Defaults to matching `value`/`id`, then label. */
+  isOptionEqual?: (option: T, value: T) => boolean;
+}
+
+function getOptionLabelDefault(option: SelectScrollOption): string {
+  if (typeof option === 'string') return option;
+  return (option as { label?: string }).label ?? String(option);
+}
+
+function getOptionValueKey(option: SelectScrollOption): string | null {
+  if (option == null) return null;
+  if (typeof option !== 'object') return String(option);
+  const record = option as { value?: unknown; id?: unknown };
+  if (record.value != null && record.value !== '') return String(record.value);
+  if (record.id != null && record.id !== '') return String(record.id);
+  return null;
+}
+
+function areSelectOptionsEqual<T>(
+  option: T,
+  selected: T,
+  getOptionLabel: (option: T) => string
+): boolean {
+  if (option === selected) return true;
+  if (typeof option !== 'object' || typeof selected !== 'object' || !option || !selected) {
+    return getOptionLabel(option) === getOptionLabel(selected);
+  }
+  const optionKey = getOptionValueKey(option as SelectScrollOption);
+  const selectedKey = getOptionValueKey(selected as SelectScrollOption);
+  if (optionKey != null && selectedKey != null) return optionKey === selectedKey;
+  return getOptionLabel(option) === getOptionLabel(selected);
+}
+
+// Memoized option row to avoid re-rendering all items when list updates
+interface OptionItemProps<T = SelectScrollOption> {
+  option: T;
+  optionLabel: string;
+  disabled: boolean;
+  selected: boolean;
+  index: number;
+  onSelect: (option: T) => void;
+  renderOption?: (option: T, state: { index: number }) => React.ReactNode;
+  customRenderOptionView?: (option: T) => React.ReactNode;
+  scrollTokens: ReturnType<typeof getSelectScrollTokensFromResolved>;
+}
+
+function OptionItemInner<T extends SelectScrollOption>(props: OptionItemProps<T>) {
+  const {
+    option,
+    optionLabel,
+    disabled,
+    selected,
+    index,
+    onSelect,
+    renderOption,
+    customRenderOptionView,
+    scrollTokens: tokens,
+  } = props;
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      onSelect(option);
+    },
+    [option, onSelect]
+  );
+  const handleMouseEnter = useCallback(
+    (e: React.MouseEvent<HTMLLIElement>) => {
+      if (!disabled) e.currentTarget.style.backgroundColor = tokens.optionHoverBackground;
+    },
+    [disabled, tokens.optionHoverBackground]
+  );
+
+  const handleMouseLeave = useCallback((e: React.MouseEvent<HTMLLIElement>) => {
+    e.currentTarget.style.backgroundColor = 'transparent';
+  }, []);
+
+  const itemStyle = useMemo(
+    () => ({
+      padding: tokens.optionPadding,
+      cursor: disabled ? 'not-allowed' : 'pointer',
+      opacity: disabled ? 0.6 : 1,
+      backgroundColor: 'transparent',
+      fontSize: tokens.optionFontSize,
+      color: tokens.optionColor,
+      listStyle: 'none' as const,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+    }),
+    [disabled, tokens.optionPadding, tokens.optionFontSize, tokens.optionColor]
+  );
+
+  return (
+    <li
+      role="option"
+      aria-disabled={disabled}
+      aria-selected={selected}
+      onMouseDown={handleMouseDown}
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+      style={itemStyle}
+    >
+      <span>
+        {renderOption ?
+          renderOption(option, { index })
+        : customRenderOptionView ?
+          customRenderOptionView(option)
+        : optionLabel}
+      </span>
+      {selected && (
+        <div style={{ marginLeft: 8, flexShrink: 0 }}>
+          <Checkbox
+            label=""
+            checked={selected}
+            disabled={disabled}
+            onChange={() => onSelect(option)}
+            id={`select-scroll-checkbox-${index}`}
+          />
+        </div>
+      )}
+    </li>
+  );
+}
+
+const OptionItem = React.memo(OptionItemInner) as typeof OptionItemInner;
+
+function SelectScrollInner<T extends SelectScrollOption = SelectScrollOption>(
+  props: SelectScrollProps<T>
+) {
+  const {
+    placeholder = 'Select...',
+    options: optionsProp,
+    isDisabled = false,
+    onChange,
+    value,
+    required = false,
+    isOptionDisabled,
+    loading: loadingProp = false,
+    onScroll: onScrollProp,
+    onLoadMore: onLoadMoreProp,
+    loadMoreMethod: loadMoreMethodProp,
+    loadMorePage,
+    onLoadMorePageChange,
+    loadMoreHasMore = true,
+    label,
+    size = 'md',
+    getOptionLabel = getOptionLabelDefault as (option: T) => string,
+    isInvalid = false,
+    error,
+    helperText,
+    renderOption,
+    onInputChange,
+    customRenderOptionView,
+    onBlur,
+    id,
+    noOptionsText = NO_OPTIONS_TEXT,
+    loadingText = 'Fetching more data...',
+    style,
+    filterOptions: filterOptionsProp,
+    color = 'grey',
+    onOpenChange,
+    clearable = true,
+    isApiSearch = true,
+    apiSearchDebounceMs = 1000,
+    onApiSearch,
+    isOptionEqual,
+  } = props;
+
+  const onOpenChangeRef = useRef(onOpenChange);
+  onOpenChangeRef.current = onOpenChange;
+  const openChangeSkipMountRef = useRef(true);
+
+  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';
+  } | null>(null);
+  const hasListboxPosition = Boolean(listboxPosition);
+  const containerRef = useRef<HTMLDivElement>(null);
+  // Used for dropdown positioning (must be the input area, not the whole component including label).
+  const fieldAnchorRef = useRef<HTMLDivElement>(null);
+  const listRef = useRef<HTMLUListElement | null>(null);
+  const didSelectRef = useRef(false);
+  const lastSelectedLabelRef = useRef<string>('');
+  const mouseDownOnFieldRef = useRef(false);
+  const listboxPositionRafRef = useRef<number | null>(null);
+  const apiSearchInputRef = useRef('');
+  const apiSearchTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  /** Tracks previous `value` so we only clear the input when a real selection was cleared, not on every re-render while searching (unstable `getOptionLabel` + `value === null`). */
+  const prevControlledValueRef = useRef<T | null | undefined>(undefined);
+  const getOptionLabelRef = useRef(getOptionLabel);
+  getOptionLabelRef.current = getOptionLabel;
+
+  const clearApiSearchTimer = useCallback(() => {
+    if (apiSearchTimerRef.current) {
+      clearTimeout(apiSearchTimerRef.current);
+      apiSearchTimerRef.current = null;
+    }
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      clearApiSearchTimer();
+    };
+  }, [clearApiSearchTimer]);
+
+  // Prevent background/page vertical scrolling while the dropdown list is open.
+  useEffect(() => {
+    if (!isOpen) return;
+    if (typeof document === 'undefined' || typeof window === 'undefined') return;
+
+    lockScroll();
+
+    return () => {
+      unlockScroll();
+    };
+  }, [isOpen]);
+
+  const options = useMemo(() => optionsProp ?? [], [optionsProp]);
+  const loading = !!loadingProp;
+
+  const useClientFilter = !isApiSearch;
+  const searchString = useClientFilter && isTyping ? inputValue.toLowerCase() : '';
+
+  const filterFn = useCallback(
+    (option: T) => {
+      const labelStr = getOptionLabel(option).toLowerCase();
+      return labelStr.includes(searchString);
+    },
+    [searchString, getOptionLabel]
+  );
+
+  const filteredOptions = useMemo(() => {
+    if (isApiSearch) {
+      return filterOptionsProp ?
+          filterOptionsProp(options, {
+            inputValue: '',
+            getOptionLabel,
+          })
+        : options;
+    }
+    return filterOptionsProp ?
+        filterOptionsProp(options, {
+          inputValue: searchString,
+          getOptionLabel,
+        })
+      : options.filter(filterFn);
+  }, [isApiSearch, filterOptionsProp, options, searchString, getOptionLabel, filterFn]);
+  const noDataFound = useMemo(
+    () => filteredOptions.length === 0 && !loading,
+    [filteredOptions.length, loading]
+  );
+
+  const resolvedTokens = useTokens();
+  const scrollTokens = getSelectScrollTokensFromResolved(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;
+    return Number.isFinite(n) ? n : 0;
+  }, [resolvedTokens]);
+
+  const updateListboxPosition = useCallback(() => {
+    const anchor = fieldAnchorRef.current;
+    if (!anchor) return;
+
+    const rect = anchor.getBoundingClientRect();
+    const viewportHeight = Math.max(0, window.innerHeight || document.documentElement.clientHeight);
+
+    const spaceBelow = viewportHeight - rect.bottom;
+    const spaceAbove = rect.top;
+
+    // Prefer the real list height whenever the list is mounted so placement matches
+    // 1-row vs full lists (avoids choosing "up" using 300px then jumping when measured).
+    const measuredHeight =
+      listRef.current ?
+        [
+          listRef.current.clientHeight,
+          listRef.current.offsetHeight,
+          listRef.current.getBoundingClientRect().height,
+        ].find((h) => typeof h === 'number' && h > 0)
+      : undefined;
+    const heightToUse =
+      typeof measuredHeight === 'number' && measuredHeight > 0 ? measuredHeight : LIST_MAX_HEIGHT;
+
+    const neededHeight = heightToUse;
+
+    let placement: 'up' | 'down';
+    if (spaceBelow >= neededHeight + listboxGapPx) {
+      placement = 'down';
+    } else if (spaceAbove >= neededHeight + listboxGapPx) {
+      placement = 'up';
+    } else {
+      // If both sides are insufficient, pick whichever has more room.
+      placement = spaceBelow >= spaceAbove ? 'down' : 'up';
+    }
+
+    let top: number;
+    const maxTop = viewportHeight - heightToUse;
+    if (placement === 'down') {
+      const desiredTop = rect.bottom + listboxGapPx;
+      top = Math.max(0, Math.min(desiredTop, maxTop));
+    } else {
+      const desiredTop = rect.top - listboxGapPx - heightToUse;
+      top = Math.max(0, Math.min(desiredTop, maxTop));
+    }
+
+    setListboxPosition({
+      top,
+      left: rect.left,
+      width: rect.width,
+      placement,
+    });
+  }, [listboxGapPx]);
+
+  const scheduleListboxPositionUpdate = useCallback(() => {
+    if (listboxPositionRafRef.current != null) {
+      cancelAnimationFrame(listboxPositionRafRef.current);
+    }
+    listboxPositionRafRef.current = requestAnimationFrame(() => {
+      listboxPositionRafRef.current = null;
+      updateListboxPosition();
+    });
+  }, [updateListboxPosition]);
+
+  const setListRef = useCallback(
+    (node: HTMLUListElement | null) => {
+      listRef.current = node;
+      if (node && isOpen) {
+        // When the portal/list mounts, immediately re-position using the real list height.
+        scheduleListboxPositionUpdate();
+      }
+    },
+    [isOpen, scheduleListboxPositionUpdate]
+  );
+
+  const handleListScroll = useCallback(
+    (e: React.UIEvent<HTMLUListElement>) => {
+      const list = e.currentTarget;
+      const nearBottom = list.scrollHeight - list.scrollTop <= list.clientHeight + 50;
+      if (nearBottom) {
+        if (
+          loadMoreMethodProp &&
+          loadMorePage != null &&
+          onLoadMorePageChange &&
+          loadMoreHasMore &&
+          !loadingProp
+        ) {
+          const nextPage = loadMorePage + 1;
+          loadMoreMethodProp(nextPage, true);
+          onLoadMorePageChange(nextPage);
+        } else {
+          onLoadMoreProp?.();
+        }
+      }
+      onScrollProp?.(e);
+    },
+    [
+      onScrollProp,
+      onLoadMoreProp,
+      loadMoreMethodProp,
+      loadMorePage,
+      onLoadMorePageChange,
+      loadMoreHasMore,
+      loadingProp,
+    ]
+  );
+
+  const handleInputChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const v = e.target.value;
+      setInputValue(v);
+      setIsTyping(true);
+      setIsOpen(true);
+      onInputChange?.(v);
+
+      if (clearable && v === '' && value != null) {
+        lastSelectedLabelRef.current = '';
+        prevControlledValueRef.current = null;
+        onChange?.(null);
+      }
+
+      if (isApiSearch && onApiSearch) {
+        apiSearchInputRef.current = v;
+        clearApiSearchTimer();
+        apiSearchTimerRef.current = setTimeout(() => {
+          apiSearchTimerRef.current = null;
+          const term = (apiSearchInputRef.current || '').trim();
+          onApiSearch(term);
+        }, apiSearchDebounceMs);
+      }
+    },
+    [
+      onInputChange,
+      isApiSearch,
+      onApiSearch,
+      apiSearchDebounceMs,
+      clearApiSearchTimer,
+      clearable,
+      value,
+      onChange,
+    ]
+  );
+
+  const handleSelect = useCallback(
+    (option: T) => {
+      if (isOptionDisabled?.(option)) return;
+      const label = getOptionLabel(option);
+      didSelectRef.current = true;
+      lastSelectedLabelRef.current = label;
+      if (isApiSearch && onApiSearch) {
+        clearApiSearchTimer();
+      }
+      setInputValue(label);
+      setIsTyping(false);
+      setIsOpen(false);
+      onChange?.(option);
+      setTimeout(() => {
+        didSelectRef.current = false;
+      }, 0);
+    },
+    [onChange, getOptionLabel, isOptionDisabled, isApiSearch, onApiSearch, clearApiSearchTimer]
+  );
+
+  const handleFocus = useCallback(() => {
+    setIsFocused(true);
+    if (isDisabled) return;
+    if (mouseDownOnFieldRef.current) return;
+    setIsOpen(true);
+  }, [isDisabled]);
+
+  const handleFieldMouseDown = useCallback(() => {
+    mouseDownOnFieldRef.current = true;
+  }, []);
+
+  const handleFieldClick = useCallback(
+    (e: React.MouseEvent) => {
+      mouseDownOnFieldRef.current = false;
+      if (isDisabled) return;
+      if ((e.target as HTMLElement).closest('button')) return;
+      setIsOpen((prev) => !prev);
+    },
+    [isDisabled]
+  );
+
+  const handleBlurInternal = useCallback(
+    (e: React.FocusEvent<HTMLInputElement>) => {
+      setIsFocused(false);
+      setIsTyping(false);
+      // Don't clear when user just selected an option (blur can fire before parent updates value)
+      if (didSelectRef.current) {
+        didSelectRef.current = false;
+        onBlur?.(e);
+        return;
+      }
+      // Effective selection: use value from props, or last selected label (so click-outside doesn't clear)
+      const valueLabel = value != null ? getOptionLabel(value) : lastSelectedLabelRef.current;
+      const normalizedInput = inputValue.trim();
+      if (normalizedInput === '') {
+        if (!clearable) {
+          // clearable=false means typed deletion/backspace should not remove selection.
+          setInputValue(valueLabel);
+          onBlur?.(e);
+          return;
+        }
+        onChange?.(null);
+        setInputValue('');
+        lastSelectedLabelRef.current = '';
+      } else if (inputValue !== valueLabel) {
+        // User left partial/manual text: preserve the current selected option.
+        setInputValue(valueLabel);
+      }
+      onBlur?.(e);
+    },
+    [value, inputValue, getOptionLabel, onChange, onBlur, clearable]
+  );
+
+  const handleClear = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      lastSelectedLabelRef.current = '';
+      if (isApiSearch && onApiSearch) {
+        clearApiSearchTimer();
+        apiSearchInputRef.current = '';
+        onApiSearch('');
+      }
+      setInputValue('');
+      setIsTyping(false);
+      setIsOpen(false);
+      onChange?.(null);
+    },
+    [onChange, isApiSearch, onApiSearch, clearApiSearchTimer]
+  );
+
+  const handleArrowClick = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      if (!isDisabled) setIsOpen((prev) => !prev);
+    },
+    [isDisabled]
+  );
+
+  const handleMouseEnterWrapper = useCallback(() => setIsHovering(true), []);
+  const handleMouseLeaveWrapper = useCallback(() => setIsHovering(false), []);
+
+  const preventDefault = useCallback((e: React.MouseEvent) => {
+    e.preventDefault();
+  }, []);
+  const handleClearButtonMouseEnter = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      if (!isDisabled) {
+        e.currentTarget.style.backgroundColor = scrollTokens.buttonHoverBackground;
+        e.currentTarget.style.color = scrollTokens.buttonHoverColor;
+      }
+    },
+    [isDisabled, scrollTokens.buttonHoverBackground, scrollTokens.buttonHoverColor]
+  );
+  const handleClearButtonMouseLeave = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      e.currentTarget.style.backgroundColor = 'transparent';
+      e.currentTarget.style.color = scrollTokens.buttonColor;
+    },
+    [scrollTokens.buttonColor]
+  );
+  const handleArrowButtonMouseEnter = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      if (!isDisabled) e.currentTarget.style.color = scrollTokens.buttonColor;
+    },
+    [isDisabled, scrollTokens.buttonColor]
+  );
+  const handleArrowButtonMouseLeave = useCallback(
+    (e: React.MouseEvent<HTMLButtonElement>) => {
+      e.currentTarget.style.color = scrollTokens.buttonColor;
+    },
+    [scrollTokens.buttonColor]
+  );
+
+  useEffect(() => {
+    if (isTyping) return;
+
+    if (value != null) {
+      if (prevControlledValueRef.current !== value) {
+        const label = getOptionLabelRef.current(value);
+        setInputValue(label);
+        lastSelectedLabelRef.current = label;
+        prevControlledValueRef.current = value;
+      }
+      return;
+    }
+
+    const hadSelection = prevControlledValueRef.current != null;
+    prevControlledValueRef.current = null;
+
+    if (hadSelection) {
+      setInputValue('');
+      lastSelectedLabelRef.current = '';
+      return;
+    }
+
+    if (isApiSearch && onApiSearch) {
+      return;
+    }
+
+    setInputValue('');
+    lastSelectedLabelRef.current = '';
+  }, [value, isApiSearch, onApiSearch, isTyping]);
+
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (
+        !containerRef.current?.contains(e.target as Node) &&
+        !listRef.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);
+    };
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!isOpen) {
+      setIsTyping(false);
+      setListboxPosition(null);
+      return;
+    }
+
+    let active = true;
+    updateListboxPosition();
+
+    // Re-measure after mount (helps for the "up" case and shorter-than-max lists).
+    // Use two rAFs to ensure the portal has rendered and layout has settled.
+    const raf1 = window.requestAnimationFrame(() => {
+      if (!active) return;
+      window.requestAnimationFrame(() => {
+        if (!active) return;
+        updateListboxPosition();
+      });
+    });
+
+    return () => {
+      active = false;
+      window.cancelAnimationFrame(raf1);
+    };
+  }, [isOpen, updateListboxPosition, filteredOptions.length, loading, noDataFound]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    if (value == null) return;
+    const raf1 = window.requestAnimationFrame(() => {
+      window.requestAnimationFrame(() => {
+        if (!listRef.current) return;
+        const selectedItem = listRef.current.querySelector('[aria-selected="true"]');
+        if (selectedItem) {
+          (selectedItem as HTMLElement).scrollIntoView({
+            block: 'nearest',
+            behavior: 'auto',
+          });
+        }
+      });
+    });
+
+    return () => {
+      window.cancelAnimationFrame(raf1);
+    };
+  }, [isOpen, value]);
+
+  /** Re-run when list height changes (async data, skeleton row, 1 vs many rows) without re-opening. */
+  useLayoutEffect(() => {
+    if (!isOpen || !hasListboxPosition) return;
+    const el = listRef.current;
+    if (!el || typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver(() => {
+      scheduleListboxPositionUpdate();
+    });
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [
+    isOpen,
+    hasListboxPosition,
+    scheduleListboxPositionUpdate,
+    filteredOptions.length,
+    loading,
+    noDataFound,
+  ]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      if (isApiSearch && onApiSearch) {
+        clearApiSearchTimer();
+        if (apiSearchInputRef.current !== '') {
+          apiSearchInputRef.current = '';
+          onApiSearch('');
+        }
+      }
+    }
+  }, [isOpen, isApiSearch, onApiSearch, clearApiSearchTimer]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    const handleWindowChange = () => {
+      scheduleListboxPositionUpdate();
+    };
+
+    window.addEventListener('resize', handleWindowChange);
+    window.addEventListener('scroll', handleWindowChange, true);
+
+    return () => {
+      window.removeEventListener('resize', handleWindowChange);
+      window.removeEventListener('scroll', handleWindowChange, true);
+    };
+  }, [isOpen, scheduleListboxPositionUpdate]);
+
+  useEffect(() => {
+    return () => {
+      if (listboxPositionRafRef.current != null) {
+        cancelAnimationFrame(listboxPositionRafRef.current);
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (openChangeSkipMountRef.current) {
+      openChangeSkipMountRef.current = false;
+      return;
+    }
+    onOpenChangeRef.current?.(isOpen);
+  }, [isOpen]);
+
+  const hasValue = value != null;
+  const showClearButton =
+    clearable && (isOpen || (isHovering && !isDisabled)) && (hasValue || inputValue !== '');
+  // Reserve space for the right-side controls so the field doesn't "shift" when the clear (X) appears.
+  const inputPaddingRight = 56;
+  const inputHeight =
+    size === 'sm' ? parseInt(scrollTokens.inputHeightSm, 10)
+    : size === 'lg' ? parseInt(scrollTokens.inputHeightLg, 10)
+    : parseInt(scrollTokens.inputHeightMd, 10);
+  const inputPadding =
+    size === 'sm' ? scrollTokens.inputPaddingSm
+    : size === 'lg' ? scrollTokens.inputPaddingLg
+    : scrollTokens.inputPaddingMd;
+  const inputFontSize =
+    size === 'sm' ? scrollTokens.inputFontSizeSm
+    : size === 'lg' ? scrollTokens.inputFontSizeLg
+    : scrollTokens.inputFontSizeMd;
+
+  const containerStyle = useMemo(
+    () => ({
+      width: '100%',
+      position: 'relative' as const,
+      fontFamily: 'sans-serif',
+      ...style,
+    }),
+    [style]
+  );
+
+  const inputStyle = useMemo(
+    () => ({
+      width: '100%',
+      padding: inputPadding,
+      paddingRight: inputPaddingRight,
+      border:
+        isInvalid ? scrollTokens.inputBorderError
+        : isFocused ? scrollTokens.inputBorderActive
+        : '1px solid #c7ced6',
+      borderRadius: scrollTokens.inputBorderRadius,
+      fontSize: inputFontSize,
+      minHeight: inputHeight,
+      boxSizing: 'border-box' as const,
+      backgroundColor:
+        color === 'white' ? scrollTokens.inputBackgroundWhite : scrollTokens.inputBackgroundWhite,
+      outline: 'none',
+      boxShadow: 'none',
+      color: isDisabled ? scrollTokens.inputColor : scrollTokens.inputColor,
+    }),
+    [
+      inputPaddingRight,
+      inputPadding,
+      inputFontSize,
+      isInvalid,
+      isFocused,
+      inputHeight,
+      isDisabled,
+      scrollTokens,
+      color,
+    ]
+  );
+
+  const listboxStyle = useMemo(
+    () => ({
+      position: 'absolute' as const,
+      top: 0,
+      left: 0,
+      right: 0,
+      // background: scrollTokens.listboxBackground,
+      background: '#ffffff',
+      // border: scrollTokens.listboxBorder,
+      border: '1px solid #c7ced6',
+      borderRadius: scrollTokens.listboxBorderRadius,
+      marginTop: 0,
+      padding: 0,
+      listStyle: 'none' as const,
+      maxHeight: LIST_MAX_HEIGHT,
+      overflowY: 'auto' as const,
+      boxShadow: '0 4px 8px rgba(0,0,0,0.1)',
+      zIndex: 1000002,
+    }),
+    [scrollTokens]
+  );
+
+  return (
+    <div ref={containerRef} style={containerStyle}>
+      <style>
+        {`.select-scroll-input::placeholder {
+          color: ${scrollTokens.placeholderColor};
+        }
+        .select-scroll-input:disabled::placeholder {
+          color: #c7ced6;
+        }
+        .select-scroll-listbox {
+          scrollbar-width: thin;
+          scrollbar-color: #C8D0D5 transparent;
+        }
+        .select-scroll-listbox::-webkit-scrollbar {
+          width: 8px;
+        }
+        .select-scroll-listbox::-webkit-scrollbar-track {
+          background: transparent;
+          border-radius: 4px;
+        }
+        .select-scroll-listbox::-webkit-scrollbar-thumb {
+          background-color: #C8D0D5;
+          border-radius: 4px;
+        }
+        .select-scroll-listbox::-webkit-scrollbar-thumb:hover {
+          background-color: #B0B8BD;
+        }
+        .select-scroll-listbox::-webkit-scrollbar-button {
+          display: none !important;
+          width: 0 !important;
+          height: 0 !important;
+        }
+        .select-scroll-listbox::-webkit-scrollbar-button:start:decrement,
+        .select-scroll-listbox::-webkit-scrollbar-button:end:increment {
+          display: none !important;
+        }
+        .select-scroll-listbox::-webkit-scrollbar-corner {
+          background: transparent;
+        }`}
+      </style>
+      {label && (
+        <label
+          onClick={(e) => {
+            if (isDisabled) return;
+            if (isOpen) {
+              setIsOpen(false);
+            } else {
+              e.preventDefault();
+            }
+          }}
+          style={{
+            display: 'block',
+            marginBottom: parseInt(scrollTokens.labelMarginBottom, 10),
+            fontSize: scrollTokens.labelFontSize,
+            fontWeight: scrollTokens.labelFontWeight,
+            color: isDisabled ? scrollTokens.labelColor : scrollTokens.labelColor,
+            cursor: 'default',
+          }}
+        >
+          {label}
+          {required && (
+            <span style={{ color: scrollTokens.labelRequiredColor, marginRight: 4 }}>*</span>
+          )}
+        </label>
+      )}
+      <div
+        style={{ position: 'relative' }}
+        ref={fieldAnchorRef}
+        onMouseEnter={handleMouseEnterWrapper}
+        onMouseLeave={handleMouseLeaveWrapper}
+      >
+        <input
+          id={id}
+          type="text"
+          autoComplete="off"
+          placeholder={placeholder}
+          value={inputValue}
+          onChange={handleInputChange}
+          onFocus={handleFocus}
+          onMouseDown={handleFieldMouseDown}
+          onClick={handleFieldClick}
+          onBlur={handleBlurInternal}
+          disabled={isDisabled}
+          aria-invalid={isInvalid}
+          aria-required={required}
+          style={inputStyle}
+          className="select-scroll-input"
+        />
+        <div
+          style={{
+            position: 'absolute',
+            right: 8,
+            top: '50%',
+            transform: 'translateY(-50%)',
+            zIndex: 1,
+            display: 'flex',
+            alignItems: 'center',
+            gap: 2,
+          }}
+        >
+          {showClearButton && (
+            <button
+              type="button"
+              onClick={handleClear}
+              onMouseDown={preventDefault}
+              disabled={isDisabled}
+              aria-label="Clear selection"
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                width: 24,
+                height: 24,
+                padding: 0,
+                border: 'none',
+                background: 'transparent',
+                cursor: isDisabled ? 'not-allowed' : 'pointer',
+                color: scrollTokens.buttonColor,
+                borderRadius: '50%',
+              }}
+              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>
+          )}
+          <button
+            type="button"
+            onClick={handleArrowClick}
+            onMouseDown={preventDefault}
+            disabled={isDisabled}
+            aria-label={isOpen ? 'Close dropdown' : 'Open dropdown'}
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: 24,
+              height: 24,
+              padding: 0,
+              border: 'none',
+              background: 'transparent',
+              cursor: isDisabled ? 'not-allowed' : 'pointer',
+              color: isDisabled ? scrollTokens.buttonColor : scrollTokens.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>
+      {(isInvalid && error) || (!isInvalid && helperText) ?
+        <div
+          style={{
+            fontSize: scrollTokens.helperFontSize,
+            marginTop: 4,
+            color:
+              isInvalid ? scrollTokens.helperErrorColor
+              : isDisabled ? scrollTokens.inputColor
+              : scrollTokens.helperColor,
+          }}
+          role={isInvalid ? 'alert' : undefined}
+        >
+          {isInvalid && error ? error : helperText}
+        </div>
+      : null}
+      {isOpen &&
+        listboxPosition &&
+        createPortal(
+          <ul
+            ref={setListRef}
+            onScroll={handleListScroll}
+            role="listbox"
+            aria-label={label ?? placeholder}
+            style={{
+              ...listboxStyle,
+              position: 'fixed',
+              top: listboxPosition.top,
+              left: listboxPosition.left,
+              width: listboxPosition.width,
+              right: 'unset',
+            }}
+            className="select-scroll-listbox"
+          >
+            {noDataFound && (
+              <li
+                style={{
+                  padding: scrollTokens.optionPadding,
+                  textAlign: 'center',
+                  color: scrollTokens.optionColor,
+                  fontSize: scrollTokens.optionFontSize,
+                }}
+              >
+                {noOptionsText}
+              </li>
+            )}
+            {!noDataFound &&
+              filteredOptions.map((option, index) => {
+                const disabled = isOptionDisabled?.(option) ?? false;
+                const optionLabel = getOptionLabel(option);
+                const isSelected =
+                  value !== undefined &&
+                  value !== null &&
+                  (isOptionEqual ?
+                    isOptionEqual(option, value)
+                  : areSelectOptionsEqual(option, value, getOptionLabel));
+                const optionValueKey = getOptionValueKey(option as SelectScrollOption);
+                const key = optionValueKey ?? `${optionLabel}-${index}`;
+                return (
+                  <OptionItem
+                    key={key}
+                    option={option}
+                    optionLabel={optionLabel}
+                    disabled={disabled}
+                    selected={isSelected}
+                    index={index}
+                    onSelect={handleSelect}
+                    renderOption={renderOption}
+                    customRenderOptionView={customRenderOptionView}
+                    scrollTokens={scrollTokens}
+                  />
+                );
+              })}
+            {loading && !noDataFound && (
+              <li
+                style={{
+                  padding: scrollTokens.optionPadding,
+                  textAlign: 'center',
+                  color: scrollTokens.optionColor,
+                  fontSize: scrollTokens.optionFontSize,
+                }}
+              >
+                {loadingText}
+              </li>
+            )}
+          </ul>,
+          document.body
+        )}
+    </div>
+  );
+}
+
+const SelectScroll = React.memo(SelectScrollInner) as typeof SelectScrollInner;
+export default SelectScroll;