@multiplatform.one/forms 6.0.0

package/src/fields/Select/index.tsx

@@ -0,0 +1,1429 @@
+import type { KeyboardEvent, MouseEvent, ReactNode, RefObject, UIEvent } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, memo } from "react";
+import { CaretDownIcon, CheckIcon } from "@phosphor-icons/react";
+import {
+  useClick,
+  useDismiss,
+  useInteractions,
+  useListNavigation,
+  useRole,
+  useTypeahead,
+  FloatingFocusManager,
+} from "@floating-ui/react";
+import type { AnyFormApi } from "../../types";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import type { LabelProps, SizeTokens } from "tamagui";
+import { Paragraph, Text, View, YStack, isWeb, styled } from "tamagui";
+import { Chip, type ChipProps } from "../../Chip";
+import { Skeleton } from "../../Skeleton";
+import { Field, FieldLayout } from "../../fieldLayout";
+import { Input as InputParts } from "../../InputParts";
+import { formCommonColors, formInputColors } from "../../shared/colorRamps";
+import {
+  getFieldError,
+  getFieldHeight,
+  mergeFieldHandler,
+  useFormField,
+  useResolvedValidators,
+} from "../../shared/utils";
+import { SyncFocusToOpen, ScrollArrow } from "../../shared/floatingList";
+import {
+  FloatingPanel,
+  useFloatingPanel,
+  panelTransition,
+  panelViewportPadding,
+  useViewportGtSm,
+} from "../../FloatingPanel";
+import { zIndex } from "../../shared/zIndex";
+import { useDragScroll } from "../../shared/useDragScroll";
+import { useIsInTableCell } from "../../shared/tableCellContext";
+
+// ── Types ─────────────────────────────────────────────────────
+
+export interface SelectOption {
+  value: string;
+  label: string;
+  /** Optional group label for grouping options */
+  group?: string;
+}
+
+export interface SelectProps {
+  name?: string;
+  form?: AnyFormApi;
+  validators?: Record<string, unknown>;
+  label?: ReactNode;
+  labelProps?: Omit<LabelProps, "htmlFor" | "ref">;
+  helperText?: string;
+  error?: string | boolean;
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  size?: SizeTokens;
+  id?: string;
+  value?: string | string[];
+  defaultValue?: string | string[];
+  onValueChange?: (value: string | string[]) => void;
+  onBlur?: (...args: any[]) => void;
+  options: SelectOption[];
+  placeholder?: string;
+  groupLabel?: string;
+  multiple?: boolean;
+  /** Show dismiss button on badges to remove selected items (only applies when multiple=true) */
+  dismissible?: boolean;
+  /** When true, renders a skeleton placeholder instead of the select */
+  skeleton?: boolean;
+  "aria-label"?: string;
+  /** When true, uses compact sizing */
+  compact?: boolean;
+}
+
+// ── Lightweight item row (replaces heavy ListItem-based DropdownItem) ──
+
+const SelectRow = styled(View, {
+  name: "SelectRow",
+  flexDirection: "row",
+  alignItems: "center",
+  gap: "$2",
+  paddingHorizontal: "$3",
+  cursor: "default",
+  outlineStyle: "none" as any,
+  hoverStyle: { backgroundColor: formInputColors.background.focus },
+  focusStyle: { outlineStyle: "none" as any },
+  focusVisibleStyle: { outlineStyle: "none" as any },
+  variants: {
+    selected: {
+      true: { backgroundColor: formInputColors.background.base },
+      false: { backgroundColor: "transparent" },
+    },
+    active: {
+      true: { backgroundColor: formInputColors.background.focus },
+      false: {},
+    },
+    size: {
+      "...size": (val: any) => ({ height: val }),
+    },
+  } as const,
+});
+
+const GroupHeader = styled(Text, {
+  name: "SelectGroupHeader",
+  paddingHorizontal: "$3",
+  paddingVertical: "$2",
+  paddingTop: "$3",
+  fontWeight: "600",
+  fontSize: "$2",
+  opacity: 0.6,
+  numberOfLines: 1,
+  userSelect: "none",
+  cursor: "default",
+});
+
+// ── Helper to group options ───────────────────────────────────
+
+interface GroupedOption {
+  type: "option";
+  option: SelectOption;
+  flatIndex: number;
+}
+
+interface GroupHeaderItem {
+  type: "header";
+  label: string;
+}
+
+type GroupedItem = GroupedOption | GroupHeaderItem;
+
+function groupOptions(options: SelectOption[]): {
+  items: GroupedItem[];
+  flatOptions: SelectOption[];
+} {
+  const hasGroups = options.some((o) => o.group);
+  if (!hasGroups) {
+    return {
+      items: options.map((option, index) => ({
+        type: "option" as const,
+        option,
+        flatIndex: index,
+      })),
+      flatOptions: options,
+    };
+  }
+
+  // Separate grouped and ungrouped options
+  const ungrouped = options.filter((o) => !o.group);
+  const grouped = options.filter((o) => o.group);
+
+  // Group by group label
+  const groups = new Map<string, SelectOption[]>();
+  for (const option of grouped) {
+    const groupLabel = option.group!;
+    if (!groups.has(groupLabel)) {
+      groups.set(groupLabel, []);
+    }
+    groups.get(groupLabel)!.push(option);
+  }
+
+  // Build result
+  const items: GroupedItem[] = [];
+  const flatOptions: SelectOption[] = [];
+
+  // Add ungrouped first
+  for (const option of ungrouped) {
+    items.push({ type: "option", option, flatIndex: flatOptions.length });
+    flatOptions.push(option);
+  }
+
+  // Add grouped options with headers
+  for (const [groupLabel, groupOptions] of groups) {
+    items.push({ type: "header", label: groupLabel });
+    for (const option of groupOptions) {
+      items.push({ type: "option", option, flatIndex: flatOptions.length });
+      flatOptions.push(option);
+    }
+  }
+
+  return { items, flatOptions };
+}
+
+interface SelectItemHandlers {
+  getItemProps: any;
+  handleSelect: (index: number, event?: MouseEvent) => void;
+  setOpen: (open: boolean) => void;
+  knobProps: any;
+  textColor: any;
+  allowSelectRef: RefObject<boolean>;
+  allowMouseUpRef: RefObject<boolean>;
+  selectTimeoutRef: RefObject<ReturnType<typeof setTimeout> | null>;
+  isTypingRef: { current: { isTyping: boolean } };
+  listItemsRef: RefObject<Array<HTMLElement | null>>;
+  multiple?: boolean;
+}
+
+// ── Memoized option row ──────────────────────────────────────
+
+const SelectItem = memo(function SelectItem({
+  option,
+  index,
+  isSelected,
+  isActive,
+  suppressHover,
+  handlers,
+  setActiveIndex,
+  setControlledScrolling,
+  optionCount,
+}: {
+  option: SelectOption;
+  index: number;
+  isSelected: boolean;
+  isActive?: boolean;
+  suppressHover?: boolean;
+  handlers: RefObject<SelectItemHandlers>;
+  setActiveIndex: (index: number) => void;
+  setControlledScrolling: (scrolling: boolean) => void;
+  optionCount: number;
+}) {
+  const ctx = handlers.current;
+  const isDown = (k: string) => k === "ArrowDown" || k === "j";
+  const isUp = (k: string) => k === "ArrowUp" || k === "k";
+  return (
+    <SelectRow
+      ref={(node: any) => {
+        ctx.listItemsRef.current[index] = node;
+      }}
+      {...ctx.getItemProps({
+        onKeyDown(event: KeyboardEvent) {
+          if (event.key === "Enter" || event.key === " " || event.code === "Space") {
+            event.preventDefault();
+            event.stopPropagation();
+            ctx.handleSelect(index);
+            if (event.key === "Enter" || event.code === "Enter" || !ctx.multiple)
+              ctx.setOpen(false);
+          } else if (isDown(event.key) || isUp(event.key)) {
+            event.preventDefault();
+            event.stopPropagation();
+            if (optionCount === 0) return;
+            const nextIndex = isDown(event.key)
+              ? index + 1 >= optionCount
+                ? 0
+                : index + 1
+              : index - 1 < 0
+                ? optionCount - 1
+                : index - 1;
+            setActiveIndex(nextIndex);
+            setControlledScrolling(true);
+          }
+        },
+        onClick(event: MouseEvent) {
+          if (ctx.allowSelectRef.current) ctx.handleSelect(index, event);
+        },
+        onMouseUp() {
+          if (!ctx.allowMouseUpRef.current) {
+            ctx.allowMouseUpRef.current = true;
+            ctx.allowSelectRef.current = true;
+            return;
+          }
+          if (!ctx.multiple) {
+            if (ctx.allowSelectRef.current) ctx.handleSelect(index);
+          }
+          if (ctx.selectTimeoutRef.current) clearTimeout(ctx.selectTimeoutRef.current);
+          ctx.selectTimeoutRef.current = setTimeout(() => {
+            ctx.allowSelectRef.current = true;
+          });
+        },
+      })}
+      role="option"
+      tabIndex={-1}
+      selected={isSelected}
+      active={isActive}
+      aria-selected={isSelected}
+      data-state={isSelected ? "active" : "inactive"}
+      size={ctx.knobProps.sizeToken}
+      onMouseEnter={() => setActiveIndex(index)}
+      {...(suppressHover
+        ? {
+            hoverStyle: {
+              backgroundColor: isActive
+                ? formInputColors.background.focus
+                : isSelected
+                  ? formInputColors.background.base
+                  : "transparent",
+            },
+          }
+        : {
+            hoverStyle: {
+              backgroundColor: isSelected
+                ? formInputColors.background.base
+                : formInputColors.background.focus,
+            },
+          })}
+      {...(ctx.knobProps.transition ? { animation: ctx.knobProps.transition } : undefined)}
+    >
+      <Text
+        fontFamily={ctx.knobProps.body.fontFamily}
+        fontWeight={ctx.knobProps.body.fontWeight}
+        color={ctx.textColor}
+        numberOfLines={1}
+        flex={1}
+      >
+        {option.label}
+      </Text>
+      {isSelected && <CheckIcon size={14} />}
+    </SelectRow>
+  );
+});
+
+// ── Floating Select Core ─────────────────────────────────────
+
+interface FloatingSelectCoreProps {
+  options: SelectOption[];
+  value: string | string[] | undefined;
+  onValueChange?: (value: string | string[]) => void;
+  onBlur?: (...args: any[]) => void;
+  placeholder: string;
+  disabled?: boolean;
+  id?: string;
+  knobProps: ReturnType<typeof useResolvedKnobs>["knobProps"];
+  groupLabel?: string;
+  multiple?: boolean;
+  dismissible?: boolean;
+}
+function FloatingSelectCore({
+  options,
+  value,
+  onValueChange,
+  onBlur,
+  placeholder,
+  disabled,
+  id,
+  knobProps,
+  groupLabel,
+  multiple,
+  dismissible,
+}: FloatingSelectCoreProps) {
+  const inTableCell = useIsInTableCell();
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const [controlledScrolling, setControlledScrolling] = useState(false);
+
+  const labelCacheRef = useRef<Map<string, string>>(new Map());
+  for (const o of options) labelCacheRef.current.set(o.value, o.label);
+  const getLabel = useCallback((v: string) => labelCacheRef.current.get(v) ?? v, []);
+
+  const selectedValues = useMemo<string[]>(() => {
+    if (!multiple) return [];
+    const vals = Array.isArray(value) ? value : value ? [value] : [];
+    return [...vals].sort((a, b) => getLabel(a).localeCompare(getLabel(b)));
+  }, [multiple, value, getLabel]);
+
+  // Group options for rendering with headers
+  const { items: groupedItems, flatOptions } = useMemo(() => groupOptions(options), [options]);
+
+  const selectedIndex = useMemo(
+    () => (multiple ? -1 : options.findIndex((option) => option.value === value)),
+    [options, value, multiple],
+  );
+  const selectedOption = selectedIndex >= 0 ? options[selectedIndex] : undefined;
+
+  const isSelected = useCallback(
+    (optionValue: string) =>
+      multiple ? selectedValues.includes(optionValue) : optionValue === value,
+    [multiple, selectedValues, value],
+  );
+
+  const handleDismiss = useCallback(
+    (valueToRemove: string) => {
+      if (!multiple) return;
+      const current = Array.isArray(value) ? value : value ? [value] : [];
+      const next = current.filter((v) => v !== valueToRemove);
+      onValueChange?.(next);
+    },
+    [multiple, value, onValueChange],
+  );
+
+  const textColor = knobProps.textAccentColor;
+
+  const listItemsRef = useRef<Array<HTMLElement | null>>([]);
+  const listContentRef = useRef<Array<string | null>>(options.map((option) => option.label));
+  const allowSelectRef = useRef(false);
+  const allowMouseUpRef = useRef(true);
+  const selectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const stateRef = useRef({ isTyping: false });
+  const overlayStyle = useRef<Record<string, any> | null>(null);
+
+  useEffect(() => {
+    listContentRef.current = options.map((option) => option.label);
+  }, [options]);
+
+  const sortedOptionsRef = useRef<SelectOption[]>(options);
+  const computeSortedOptions = useCallback(() => {
+    if (!multiple) {
+      sortedOptionsRef.current = options;
+      return;
+    }
+    const selected = Array.isArray(value) ? value : value ? [value] : [];
+    if (selected.length === 0) {
+      sortedOptionsRef.current = options;
+      return;
+    }
+    const selectedSet = new Set(selected);
+    const first = options
+      .filter((o) => selectedSet.has(o.value))
+      .sort((a, b) => a.label.localeCompare(b.label));
+    const rest = options.filter((o) => !selectedSet.has(o.value));
+    sortedOptionsRef.current = [...first, ...rest];
+  }, [options, value, multiple]);
+
+  const programmaticScrollRef = useRef(0);
+  const pinnedTopRef = useRef(0);
+  const pinnedHeightRef = useRef(0);
+  const grownRef = useRef(false);
+  const growUpOnlyRef = useRef(false);
+  const growDownOnlyRef = useRef(false);
+  const lastScrollTopRef = useRef(0);
+
+  const repositionRef = useRef<(() => void) | null>(null);
+
+  const panel = useFloatingPanel({
+    open,
+    onOpenChange: setOpen,
+    disabled,
+    repositionRef,
+    wheelGrowRef: selectedIndex >= 0 ? grownRef : undefined,
+    onBeforeOpen: () => {
+      computeSortedOptions();
+      overlayStyle.current = null;
+      pinnedTopRef.current = 0;
+      pinnedHeightRef.current = 0;
+      grownRef.current = false;
+      growUpOnlyRef.current = false;
+      growDownOnlyRef.current = false;
+      lastScrollTopRef.current = 0;
+      programmaticScrollRef.current = 0;
+    },
+  });
+
+  const { scrollRef: dragScrollRef, dragProps } = useDragScroll({
+    direction: "vertical",
+  });
+
+  // Sync drag scroll ref with floating ref
+  useEffect(() => {
+    if (panel.refs.floating.current) {
+      (dragScrollRef as RefObject<HTMLElement | null>).current = panel.refs.floating.current;
+    }
+  }, [panel.refs.floating.current, dragScrollRef]);
+
+  useEffect(() => {
+    if (open) {
+      setActiveIndex(selectedIndex >= 0 ? selectedIndex : 0);
+    } else {
+      setActiveIndex(null);
+      setControlledScrolling(false);
+    }
+  }, [open, selectedIndex]);
+
+  const repositionOverlay = useCallback(() => {
+    const dropdownElement = panel.refs.floating.current;
+    const selectedItemIndex = selectedIndex >= 0 ? selectedIndex : 0;
+    const selectedItem = listItemsRef.current[selectedItemIndex];
+    const trigger = panel.triggerRef.current;
+    if (!dropdownElement || !selectedItem || !trigger) return;
+
+    const isInitial = panel.initializingRef.current;
+    if (isInitial) dropdownElement.style.transition = "none";
+
+    if (pinnedTopRef.current === 0 && pinnedHeightRef.current === 0) {
+      programmaticScrollRef.current++;
+      dropdownElement.scrollTop = 0;
+    }
+
+    const triggerBounds = trigger.getBoundingClientRect();
+    const viewportHeight = window.innerHeight;
+    const computedStyle = getComputedStyle(dropdownElement);
+    const borderTopWidth = parseFloat(computedStyle.borderTopWidth) || 0;
+    const borderBottomWidth = parseFloat(computedStyle.borderBottomWidth) || 0;
+    const totalBorderWidth = borderTopWidth + borderBottomWidth;
+    const scrollContentHeight = dropdownElement.scrollHeight;
+    const totalContentHeight = scrollContentHeight + totalBorderWidth;
+
+    let idealTop: number;
+    if (selectedIndex >= 0) {
+      idealTop = triggerBounds.top - borderTopWidth - selectedItem.offsetTop;
+    } else if (panel.placement.startsWith("top")) {
+      idealTop = triggerBounds.bottom - totalContentHeight;
+    } else {
+      idealTop = triggerBounds.top - borderTopWidth - (selectedItem.offsetTop ?? 0);
+    }
+    const idealBottom = idealTop + totalContentHeight;
+    const pinnedTop = Math.max(panelViewportPadding, idealTop);
+    const pinnedBottom = Math.min(viewportHeight - panelViewportPadding, idealBottom);
+    const pinnedHeight = Math.max(120, pinnedBottom - pinnedTop);
+
+    if (pinnedTopRef.current === 0 && pinnedHeightRef.current === 0) {
+      pinnedTopRef.current = pinnedTop;
+      pinnedHeightRef.current = pinnedHeight;
+    }
+
+    let top = pinnedTopRef.current;
+    let height = pinnedHeightRef.current;
+
+    if (grownRef.current) {
+      const canGrowDown = Math.max(0, viewportHeight - panelViewportPadding - (top + height));
+      height += canGrowDown;
+      const canGrowUp = Math.max(0, top - panelViewportPadding);
+      top -= canGrowUp;
+      height += canGrowUp;
+    }
+
+    if (growUpOnlyRef.current) {
+      const canGrowUp = Math.max(0, top - panelViewportPadding);
+      top -= canGrowUp;
+      height += canGrowUp;
+    }
+    if (growDownOnlyRef.current) {
+      const canGrowDown = Math.max(0, viewportHeight - panelViewportPadding - (top + height));
+      height += canGrowDown;
+    }
+
+    height = Math.min(height, viewportHeight - top - panelViewportPadding);
+    height = Math.min(height, totalContentHeight);
+    height = Math.max(120, height);
+
+    // When grown but content is shorter than viewport: anchor dropdown to bottom (gap above), dropup to top (gap below)
+    const availableViewport = viewportHeight - 2 * panelViewportPadding;
+    if (
+      (grownRef.current || growUpOnlyRef.current || growDownOnlyRef.current) &&
+      height < availableViewport
+    ) {
+      if (panel.placement.startsWith("top")) {
+        top = panelViewportPadding;
+      } else {
+        top = viewportHeight - panelViewportPadding - height;
+      }
+    }
+
+    const cachedOverlayStyle = overlayStyle.current;
+
+    if (
+      !cachedOverlayStyle ||
+      cachedOverlayStyle.top !== top ||
+      cachedOverlayStyle.maxHeight !== height
+    ) {
+      dropdownElement.style.top = `${top}px`;
+      dropdownElement.style.maxHeight = `${height}px`;
+      dropdownElement.style.height = "";
+      overlayStyle.current = { top, maxHeight: height };
+      void dropdownElement.offsetHeight;
+    }
+
+    if (!grownRef.current && !growUpOnlyRef.current && !growDownOnlyRef.current) {
+      const maxScrollTop = dropdownElement.scrollHeight - dropdownElement.clientHeight;
+      if (selectedIndex >= 0) {
+        const neededScroll = top + borderTopWidth + selectedItem.offsetTop - triggerBounds.top;
+        const clampedScrollTop = Math.max(0, Math.min(neededScroll, maxScrollTop));
+        if (Math.abs(dropdownElement.scrollTop - clampedScrollTop) > 0.5) {
+          programmaticScrollRef.current++;
+          dropdownElement.scrollTop = clampedScrollTop;
+        }
+        if (Math.abs(neededScroll - clampedScrollTop) > 0.5) {
+          const scrollDeficit = neededScroll - clampedScrollTop;
+          top -= scrollDeficit;
+          top = Math.max(panelViewportPadding, top);
+          const remainingContentHeight = totalContentHeight - clampedScrollTop;
+          const adjustedMaxHeight = Math.min(
+            remainingContentHeight,
+            viewportHeight - top - panelViewportPadding,
+          );
+          dropdownElement.style.top = `${top}px`;
+          dropdownElement.style.maxHeight = `${adjustedMaxHeight}px`;
+          overlayStyle.current = { top, maxHeight: adjustedMaxHeight };
+        }
+      }
+    }
+
+    panel.initializingRef.current = false;
+
+    void dropdownElement.offsetHeight;
+    if (isInitial) dropdownElement.style.transition = panelTransition;
+    requestAnimationFrame(() => {
+      if (dropdownElement) {
+        panel.updateArrows(dropdownElement);
+        requestAnimationFrame(() => {
+          if (dropdownElement) panel.updateArrows(dropdownElement);
+        });
+      }
+    });
+  }, [selectedIndex, panel.refs, panel.updateArrows, panel.placement, options.length]);
+
+  repositionRef.current = repositionOverlay;
+
+  useLayoutEffect(() => {
+    if (!open || !panel.mounted) return;
+    repositionOverlay();
+  }, [open, panel.mounted, selectedIndex, repositionOverlay, panel.y]);
+
+  const onMatch = useCallback(
+    (index: number) => {
+      if (open) {
+        setActiveIndex(index);
+      } else {
+        const matchedOption = options[index];
+        if (matchedOption) onValueChange?.(matchedOption.value);
+      }
+    },
+    [open, options, onValueChange],
+  );
+
+  const click = useClick(panel.context, { event: "mousedown", keyboardHandlers: false });
+  const dismiss = useDismiss(panel.context);
+  const role = useRole(panel.context, { role: "listbox" });
+  const listNav = useListNavigation(panel.context, {
+    listRef: listItemsRef,
+    activeIndex: activeIndex ?? 0,
+    selectedIndex: selectedIndex >= 0 ? selectedIndex : undefined,
+    onNavigate: (index) => {
+      if (index !== null) setActiveIndex(index);
+    },
+    scrollItemIntoView: false,
+    focusItemOnHover: false,
+  });
+  const typeahead = useTypeahead(panel.context, {
+    listRef: listContentRef,
+    onMatch,
+    selectedIndex: selectedIndex >= 0 ? selectedIndex : undefined,
+    activeIndex,
+    onTypingChange: (typing) => {
+      stateRef.current.isTyping = typing;
+    },
+  });
+
+  const { getReferenceProps, getFloatingProps, getItemProps } = useInteractions([
+    click,
+    dismiss,
+    role,
+    listNav,
+    typeahead,
+  ]);
+
+  useLayoutEffect(() => {
+    if (open) {
+      allowMouseUpRef.current = false;
+      selectTimeoutRef.current = setTimeout(() => {
+        allowSelectRef.current = true;
+        allowMouseUpRef.current = true;
+      }, 300);
+      return () => {
+        if (selectTimeoutRef.current) clearTimeout(selectTimeoutRef.current);
+      };
+    }
+    allowSelectRef.current = false;
+    allowMouseUpRef.current = true;
+  }, [open]);
+
+  useEffect(() => {
+    if (!open || activeIndex == null) return;
+    const floatingElement = panel.refs.floating.current;
+    const itemElement = listItemsRef.current[activeIndex];
+    if (controlledScrolling && floatingElement && itemElement) {
+      const containerRect = floatingElement.getBoundingClientRect();
+      const itemRect = itemElement.getBoundingClientRect();
+      if (itemRect.bottom > containerRect.bottom) {
+        floatingElement.scrollTop += itemRect.bottom - containerRect.bottom;
+      } else if (itemRect.top < containerRect.top) {
+        floatingElement.scrollTop -= containerRect.top - itemRect.top;
+      }
+    }
+    requestAnimationFrame(() => {
+      listItemsRef.current[activeIndex]?.focus({ preventScroll: true });
+      if (floatingElement) {
+        panel.updateArrows(floatingElement);
+      }
+    });
+  }, [open, controlledScrolling, activeIndex, panel.refs, panel.updateArrows]);
+
+  const lastSelectedIndexRef = useRef<number | null>(null);
+  const valueRef = useRef(value);
+  valueRef.current = value;
+
+  const handleSelect = useCallback(
+    (index: number, event?: MouseEvent) => {
+      const displayOptions = sortedOptionsRef.current;
+      const option = displayOptions[index];
+      if (!option) return;
+      if (multiple) {
+        const latestValue = valueRef.current;
+        const current = Array.isArray(latestValue) ? latestValue : latestValue ? [latestValue] : [];
+        if (event?.shiftKey && lastSelectedIndexRef.current != null) {
+          const from = Math.min(lastSelectedIndexRef.current, index);
+          const to = Math.max(lastSelectedIndexRef.current, index);
+          const rangeValues = displayOptions.slice(from, to + 1).map((o) => o.value);
+          const merged = new Set([...current, ...rangeValues]);
+          onValueChange?.([...merged]);
+        } else {
+          const next = current.includes(option.value)
+            ? current.filter((v) => v !== option.value)
+            : [...current, option.value];
+          onValueChange?.(next);
+          lastSelectedIndexRef.current = index;
+        }
+      } else {
+        onValueChange?.(option.value);
+        setOpen(false);
+        onBlur?.();
+      }
+    },
+    [onValueChange, onBlur, multiple],
+  );
+
+  const handleSelectByOption = useCallback(
+    (option: SelectOption) => {
+      const displayOptions = sortedOptionsRef.current;
+      const index = displayOptions.findIndex((o) => o.value === option.value);
+      if (index >= 0) handleSelect(index);
+    },
+    [handleSelect],
+  );
+
+  const handlersRef = useRef({} as SelectItemHandlers);
+  handlersRef.current = {
+    getItemProps,
+    handleSelect,
+    setOpen,
+    knobProps,
+    textColor,
+    allowSelectRef,
+    allowMouseUpRef,
+    selectTimeoutRef,
+    isTypingRef: stateRef,
+    listItemsRef,
+    multiple,
+  };
+
+  const referenceProps = getReferenceProps({
+    ref: panel.setReferenceRef,
+    onKeyDown(event: KeyboardEvent) {
+      if (
+        event.key === "Enter" ||
+        event.code === "Space" ||
+        event.key === " " ||
+        event.key === "ArrowDown" ||
+        event.key === "ArrowUp" ||
+        event.key === "j" ||
+        event.key === "k"
+      ) {
+        event.preventDefault();
+        setOpen(true);
+        setActiveIndex(selectedIndex >= 0 ? selectedIndex : 0);
+      }
+    },
+  });
+
+  const boxEventProps: Record<string, any> = {};
+  for (const [key, val] of Object.entries(referenceProps)) {
+    if (key === "ref" || typeof val === "function") {
+      boxEventProps[key] = val;
+    }
+    if (key.startsWith("aria-") || key === "role" || key === "tabIndex") {
+      boxEventProps[key] = val;
+    }
+  }
+  boxEventProps.tabIndex = disabled ? -1 : 0;
+  boxEventProps.role = "combobox";
+  boxEventProps["aria-haspopup"] = "listbox";
+  boxEventProps["aria-expanded"] = open;
+  boxEventProps["aria-autocomplete"] = "none";
+
+  const handleScroll = useCallback(
+    (event: UIEvent) => {
+      const el = event.target as HTMLElement;
+      panel.updateArrows(el);
+      if (panel.initializingRef.current || programmaticScrollRef.current > 0) {
+        if (programmaticScrollRef.current > 0) programmaticScrollRef.current--;
+        lastScrollTopRef.current = el.scrollTop;
+        return;
+      }
+      const arrowDir = panel.arrowScrollDirRef.current;
+      if (arrowDir) {
+        panel.arrowScrollDirRef.current = null;
+        lastScrollTopRef.current = el.scrollTop;
+        if (arrowDir === "down") {
+          growUpOnlyRef.current = true;
+        } else {
+          growDownOnlyRef.current = true;
+        }
+        repositionOverlay();
+        return;
+      }
+      const delta = el.scrollTop - lastScrollTopRef.current;
+      lastScrollTopRef.current = el.scrollTop;
+      if (delta !== 0) {
+        grownRef.current = true;
+        repositionOverlay();
+      }
+    },
+    [panel.updateArrows, repositionOverlay],
+  );
+
+  return (
+    <>
+      <InputParts.Box
+        {...boxEventProps}
+        data-testid="select-trigger"
+        cursor="pointer"
+        disabled={disabled}
+        size={knobProps.sizeToken}
+        {...(inTableCell
+          ? {}
+          : {
+              borderRadius: knobProps.borderRadius.borderRadius,
+              borderWidth: knobProps.borderRadius.borderWidth,
+            })}
+      >
+        <SyncFocusToOpen open={open} />
+        <View
+          flex={1}
+          paddingHorizontal="$3"
+          paddingVertical="$2"
+          id={id}
+          justifyContent={multiple && selectedValues.length > 0 ? "center" : "flex-start"}
+          alignItems={multiple && selectedValues.length > 0 ? "center" : "flex-start"}
+        >
+          {multiple && selectedValues.length > 0 ? (
+            <View
+              flexDirection="row"
+              flexWrap="nowrap"
+              gap="$1.5"
+              alignItems="center"
+              maxHeight={getFieldHeight(knobProps.sizeToken as SizeTokens) * 0.75}
+              overflow="hidden"
+              overflowX="auto"
+            >
+              {selectedValues.map((v) => (
+                <Chip
+                  key={v}
+                  size={
+                    ({ $3: "$2", $4: "$3", $5: "$4" }[knobProps.sizeToken] ??
+                      "$3") as ChipProps["size"]
+                  }
+                  color="gray"
+                  onDismiss={dismissible && !disabled ? () => handleDismiss(v) : undefined}
+                >
+                  {getLabel(v)}
+                </Chip>
+              ))}
+            </View>
+          ) : (
+            <Text
+              fontFamily={knobProps.body.fontFamily}
+              fontWeight={knobProps.body.fontWeight}
+              color={selectedOption ? textColor : formCommonColors.muted}
+              numberOfLines={1}
+              userSelect="none"
+            >
+              {selectedOption?.label ?? placeholder}
+            </Text>
+          )}
+        </View>
+        <View paddingRight="$2" alignSelf="center">
+          <CaretDownIcon size={16} />
+        </View>
+      </InputParts.Box>
+
+      {panel.mounted && (
+        <>
+          <FloatingFocusManager context={panel.context} modal={false} initialFocus={-1}>
+            <YStack
+              outlineWidth={0}
+              pointerEvents={panel.visible ? "auto" : "none"}
+              {...getFloatingProps({
+                ref: panel.refs.setFloating,
+                style: {
+                  position: panel.strategy,
+                  top: overlayStyle.current?.top ?? panel.y ?? 0,
+                  left: panel.x ?? 0,
+                  scrollbarWidth: "none" as any,
+                  zIndex: zIndex.dropdown,
+                  overflow: "auto",
+                  ...panel.floatingStyleRef.current,
+                  ...(overlayStyle.current ? { maxHeight: overlayStyle.current.maxHeight } : {}),
+                  boxShadow: "0px 8px 28px rgba(0,0,0,0.12), 0px 2px 6px rgba(0,0,0,0.04)",
+                  opacity: panel.visible ? 1 : 0,
+                  transform: panel.visible ? "scale(1)" : "scale(0.96)",
+                  transition: panelTransition,
+                  transformOrigin: panel.placement.startsWith("top") ? "bottom left" : "top left",
+                  ...dragProps.style,
+                },
+                onPointerDown: dragProps.onPointerDown,
+                onKeyDown(e: KeyboardEvent) {
+                  setControlledScrolling(true);
+                  const count = flatOptions.length;
+                  if (count === 0) return;
+                  const isDown = e.key === "ArrowDown" || e.key === "j";
+                  const isUp = e.key === "ArrowUp" || e.key === "k";
+                  if (isDown) {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    setActiveIndex((prev) => (prev == null ? 0 : prev + 1 >= count ? 0 : prev + 1));
+                  } else if (isUp) {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    setActiveIndex((prev) =>
+                      prev == null ? count - 1 : prev - 1 < 0 ? count - 1 : prev - 1,
+                    );
+                  } else if (e.key === "Enter" || e.key === " " || e.code === "Space") {
+                    e.preventDefault();
+                    e.stopPropagation();
+                    if (activeIndex != null) {
+                      const option = flatOptions[activeIndex];
+                      if (option) handleSelectByOption(option);
+                      if (e.key === "Enter" || e.code === "Enter" || !multiple) setOpen(false);
+                    }
+                  }
+                },
+                onContextMenu(event: MouseEvent) {
+                  event.preventDefault();
+                },
+                onScroll: handleScroll,
+              })}
+              backgroundColor="$background"
+              borderRadius={panel.dropdownRadius}
+              borderWidth={panel.hasBorder ? knobProps.borderRadius.borderWidth : 0}
+              borderColor={panel.hasBorder ? formInputColors.border.focus : "transparent"}
+              data-testid="select-dropdown"
+              paddingVertical={0}
+            >
+              <ScrollArrow
+                direction="up"
+                scrollRef={panel.refs.floating}
+                visible={panel.arrowUp}
+                arrowScrollDirRef={panel.arrowScrollDirRef}
+              />
+              {groupLabel && <GroupHeader color={textColor}>{groupLabel}</GroupHeader>}
+              {multiple
+                ? sortedOptionsRef.current.map((option, i) => (
+                    <SelectItem
+                      key={option.value}
+                      option={option}
+                      index={i}
+                      isSelected={isSelected(option.value)}
+                      isActive={i === activeIndex}
+                      suppressHover={activeIndex != null}
+                      handlers={handlersRef}
+                      setActiveIndex={setActiveIndex}
+                      setControlledScrolling={setControlledScrolling}
+                      optionCount={sortedOptionsRef.current.length}
+                    />
+                  ))
+                : groupedItems.map((item) =>
+                    item.type === "header" ? (
+                      <GroupHeader key={`header-${item.label}`} color={textColor}>
+                        {item.label}
+                      </GroupHeader>
+                    ) : (
+                      <SelectItem
+                        key={item.option.value}
+                        option={item.option}
+                        index={item.flatIndex}
+                        isSelected={isSelected(item.option.value)}
+                        isActive={item.flatIndex === activeIndex}
+                        suppressHover={activeIndex != null}
+                        handlers={handlersRef}
+                        setActiveIndex={setActiveIndex}
+                        setControlledScrolling={setControlledScrolling}
+                        optionCount={flatOptions.length}
+                      />
+                    ),
+                  )}
+              <ScrollArrow
+                direction="down"
+                scrollRef={panel.refs.floating}
+                visible={panel.arrowDown}
+                arrowScrollDirRef={panel.arrowScrollDirRef}
+              />
+            </YStack>
+          </FloatingFocusManager>
+        </>
+      )}
+    </>
+  );
+}
+
+// ── Native Select (Sheet-based for iOS/Android) ──────────────
+
+function NativeSelectCore({
+  options,
+  value,
+  onValueChange,
+  onBlur,
+  placeholder,
+  disabled,
+  id,
+  knobProps,
+  groupLabel,
+  multiple,
+  dismissible,
+}: FloatingSelectCoreProps) {
+  const inTableCell = useIsInTableCell();
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState<number | null>(0);
+  const listRef = useRef<HTMLElement | null>(null);
+
+  const labelCacheRef = useRef<Map<string, string>>(new Map());
+  for (const o of options) labelCacheRef.current.set(o.value, o.label);
+  const getLabel = useCallback((v: string) => labelCacheRef.current.get(v) ?? v, []);
+
+  const selectedValues = useMemo<string[]>(() => {
+    if (!multiple) return [];
+    const vals = Array.isArray(value) ? value : value ? [value] : [];
+    return [...vals].sort((a, b) => getLabel(a).localeCompare(getLabel(b)));
+  }, [multiple, value, getLabel]);
+
+  const selectedOption = useMemo(
+    () => (multiple ? undefined : options.find((o) => o.value === value)),
+    [options, value, multiple],
+  );
+
+  const isSelectedFn = useCallback(
+    (optionValue: string) =>
+      multiple ? selectedValues.includes(optionValue) : optionValue === value,
+    [multiple, selectedValues, value],
+  );
+
+  const handleDismiss = useCallback(
+    (valueToRemove: string) => {
+      if (!multiple) return;
+      const current = Array.isArray(value) ? value : value ? [value] : [];
+      const next = current.filter((v) => v !== valueToRemove);
+      onValueChange?.(next);
+    },
+    [multiple, value, onValueChange],
+  );
+
+  const textColor = knobProps.textAccentColor;
+  const sheetTransition = knobProps.transition ?? "medium";
+  const hasScrollableContent = options.length > 6;
+
+  const selectedIndex = options.findIndex((o) => o.value === value);
+  useEffect(() => {
+    if (open) {
+      setActiveIndex(selectedIndex >= 0 ? selectedIndex : 0);
+      requestAnimationFrame(() => listRef.current?.focus());
+    }
+  }, [open, selectedIndex]);
+
+  const handleSelect = useCallback(
+    (optionValue: string) => {
+      if (multiple) {
+        const current = Array.isArray(value) ? value : value ? [value] : [];
+        const next = current.includes(optionValue)
+          ? current.filter((v) => v !== optionValue)
+          : [...current, optionValue];
+        onValueChange?.(next);
+      } else {
+        onValueChange?.(optionValue);
+        setOpen(false);
+        onBlur?.();
+      }
+    },
+    [onValueChange, onBlur, multiple, value],
+  );
+
+  const handleListKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      const count = options.length;
+      if (count === 0) return;
+      const isDown = e.key === "ArrowDown" || e.key === "j";
+      const isUp = e.key === "ArrowUp" || e.key === "k";
+      if (isDown) {
+        e.preventDefault();
+        setActiveIndex((prev) => {
+          const next = prev == null ? 0 : prev + 1;
+          return next >= count ? 0 : next;
+        });
+      } else if (isUp) {
+        e.preventDefault();
+        setActiveIndex((prev) => {
+          const next = prev == null ? count - 1 : prev - 1;
+          return next < 0 ? count - 1 : next;
+        });
+      } else if (e.key === "Enter" || e.key === " " || e.code === "Space") {
+        e.preventDefault();
+        e.stopPropagation();
+        if (activeIndex != null) {
+          const option = options[activeIndex];
+          if (option) handleSelect(option.value);
+        }
+      }
+    },
+    [options, activeIndex, handleSelect],
+  );
+
+  const listContent = (
+    <View
+      ref={listRef as any}
+      tabIndex={0}
+      onKeyDown={handleListKeyDown}
+      outlineStyle="none"
+      flex={1}
+    >
+      {groupLabel && (
+        <Text
+          paddingHorizontal="$3"
+          paddingVertical="$2"
+          fontFamily={knobProps.body.fontFamily}
+          fontWeight="700"
+          color={textColor}
+          opacity={0.5}
+          numberOfLines={1}
+        >
+          {groupLabel}
+        </Text>
+      )}
+      {options.map((option, i) => {
+        const selected = isSelectedFn(option.value);
+        const active = i === activeIndex;
+        return (
+          <View
+            key={option.value}
+            flexDirection="row"
+            alignItems="center"
+            gap="$2"
+            paddingHorizontal="$3"
+            height={knobProps.sizeToken}
+            onPress={() => handleSelect(option.value)}
+            onMouseEnter={() => setActiveIndex(i)}
+            hoverStyle={
+              activeIndex != null
+                ? {
+                    backgroundColor: active
+                      ? formInputColors.background.focus
+                      : selected
+                        ? formInputColors.background.base
+                        : "transparent",
+                  }
+                : {
+                    backgroundColor: selected
+                      ? formInputColors.background.base
+                      : formInputColors.background.focus,
+                  }
+            }
+            backgroundColor={
+              active
+                ? formInputColors.background.focus
+                : selected
+                  ? formInputColors.background.base
+                  : "transparent"
+            }
+            pressStyle={{ backgroundColor: formInputColors.background.focus }}
+          >
+            <Text
+              fontFamily={knobProps.body.fontFamily}
+              fontWeight={knobProps.body.fontWeight}
+              color={textColor}
+              numberOfLines={1}
+              flex={1}
+            >
+              {option.label}
+            </Text>
+            {selected && <CheckIcon size={14} />}
+          </View>
+        );
+      })}
+    </View>
+  );
+
+  return (
+    <FloatingPanel
+      open={open}
+      onOpenChange={(val) => {
+        setOpen(val);
+        if (!val) onBlur?.();
+      }}
+      sheet
+      trigger={
+        <InputParts.Box
+          disabled={disabled}
+          size={knobProps.sizeToken}
+          {...(inTableCell
+            ? {}
+            : {
+                borderRadius: knobProps.borderRadius.borderRadius,
+                borderWidth: knobProps.borderRadius.borderWidth,
+              })}
+          data-testid="select-trigger"
+          tabIndex={disabled ? -1 : 0}
+          onKeyDown={(e: KeyboardEvent) => {
+            if (
+              ["Enter", " ", "ArrowDown", "ArrowUp", "j", "k"].includes(e.key) ||
+              e.code === "Space"
+            ) {
+              e.preventDefault();
+              if (!open) setOpen(true);
+            }
+          }}
+        >
+          <View
+            flex={1}
+            paddingHorizontal="$3"
+            paddingVertical="$2"
+            id={id}
+            justifyContent={multiple && selectedValues.length > 0 ? "center" : "flex-start"}
+            alignItems={multiple && selectedValues.length > 0 ? "center" : "flex-start"}
+          >
+            {multiple && selectedValues.length > 0 ? (
+              <View
+                flexDirection="row"
+                flexWrap="nowrap"
+                gap="$1.5"
+                alignItems="center"
+                maxHeight={getFieldHeight(knobProps.sizeToken as SizeTokens) * 0.75}
+                overflow="hidden"
+                overflowX="auto"
+              >
+                {selectedValues.map((v) => (
+                  <Chip
+                    key={v}
+                    size={
+                      ({ $3: "$2", $4: "$3", $5: "$4" }[knobProps.sizeToken] ??
+                        "$3") as ChipProps["size"]
+                    }
+                    color="gray"
+                    onDismiss={dismissible && !disabled ? () => handleDismiss(v) : undefined}
+                  >
+                    {getLabel(v)}
+                  </Chip>
+                ))}
+              </View>
+            ) : (
+              <Text
+                fontFamily={knobProps.body.fontFamily}
+                fontWeight={knobProps.body.fontWeight}
+                color={selectedOption ? textColor : formCommonColors.muted}
+                numberOfLines={1}
+              >
+                {selectedOption?.label ?? placeholder}
+              </Text>
+            )}
+          </View>
+          <View paddingRight="$2" alignSelf="center">
+            <CaretDownIcon size={16} />
+          </View>
+        </InputParts.Box>
+      }
+      scrollable={hasScrollableContent}
+      disabled={disabled}
+      contentPadding="none"
+      transition={typeof sheetTransition === "string" ? sheetTransition : "medium"}
+    >
+      {listContent}
+    </FloatingPanel>
+  );
+}
+
+// ── Select (public API) ──────────────────────────────────────
+
+export function Select({
+  name,
+  form: formProp,
+  validators,
+  label,
+  labelProps,
+  helperText,
+  error,
+  required,
+  disabled,
+  readOnly,
+  size: sizeProp,
+  id: idProp,
+  value,
+  defaultValue,
+  onValueChange,
+  onBlur,
+  options,
+  placeholder = "Select an option",
+  groupLabel,
+  multiple,
+  dismissible,
+  skeleton,
+  compact,
+  ...rest
+}: SelectProps) {
+  const { resolvedForm, knobProps, id } = useFormField({ form: formProp, id: idProp, compact });
+  const resolvedValidators = useResolvedValidators(required, validators, label, name);
+  const viewportGtSm = useViewportGtSm();
+  // Sheet on native and sm (viewport ≤860px). Floating on desktop.
+  const effectiveGtSm = typeof window !== "undefined" ? viewportGtSm : false;
+  const shouldUseSheet = !isWeb || !effectiveGtSm;
+
+  // Render skeleton placeholder
+  if (skeleton) {
+    return (
+      <InputParts size={sizeProp || knobProps.sizeToken}>
+        {label && <Skeleton variant="text" width="30%" height={14} />}
+        <Skeleton variant="rounded" width="100%" height={knobProps.sizeToken} />
+      </InputParts>
+    );
+  }
+
+  const renderReadOnly = (selectValue: string | string[] | undefined) => {
+    if (multiple && Array.isArray(selectValue)) {
+      const labels = selectValue
+        .map((v) => options.find((o) => o.value === v)?.label ?? v)
+        .join(", ");
+      return (
+        <Paragraph
+          fontSize={knobProps.sizeToken}
+          color={knobProps.textAccentColor}
+          paddingVertical="$2"
+          paddingHorizontal="$3"
+          fontFamily={knobProps.body.fontFamily}
+          fontWeight={knobProps.body.fontWeight}
+          aria-readonly="true"
+        >
+          {labels || "-"}
+        </Paragraph>
+      );
+    }
+    const sv = typeof selectValue === "string" ? selectValue : undefined;
+    const selectedOption = options.find((option) => option.value === sv);
+    const displayText = selectedOption?.label ?? (sv || "-");
+    return (
+      <Paragraph
+        fontSize={knobProps.sizeToken}
+        color={knobProps.textAccentColor}
+        paddingVertical="$2"
+        paddingHorizontal="$3"
+        fontFamily={knobProps.body.fontFamily}
+        fontWeight={knobProps.body.fontWeight}
+        borderRadius={knobProps.borderRadius.borderRadius}
+        borderWidth={knobProps.borderRadius.borderWidth}
+        {...(knobProps.outlined ? { backgroundColor: "transparent" } : undefined)}
+        aria-readonly="true"
+      >
+        {displayText}
+      </Paragraph>
+    );
+  };
+
+  const renderSelectContent = (
+    selectValue: string | string[] | undefined,
+    handleValueChange?: (val: any) => void,
+    handleBlur?: (...args: any[]) => void,
+  ) => {
+    if (readOnly) return renderReadOnly(selectValue);
+    const SelectCore = shouldUseSheet ? NativeSelectCore : FloatingSelectCore;
+    return (
+      <SelectCore
+        options={options}
+        value={selectValue}
+        onValueChange={(val) => {
+          if (disabled) return;
+          handleValueChange?.(val);
+          onValueChange?.(val);
+        }}
+        onBlur={handleBlur}
+        placeholder={placeholder}
+        disabled={disabled}
+        id={id}
+        knobProps={knobProps}
+        groupLabel={groupLabel}
+        multiple={multiple}
+        dismissible={dismissible}
+      />
+    );
+  };
+
+  if (!resolvedForm || !name) {
+    return (
+      <FieldLayout
+        id={id}
+        label={label}
+        labelProps={labelProps}
+        error={error}
+        helperText={helperText}
+        required={required}
+        size={sizeProp}
+        knobProps={knobProps as any}
+        {...rest}
+      >
+        <InputParts size={sizeProp || knobProps.sizeToken}>
+          {renderSelectContent(value ?? defaultValue, undefined, onBlur)}
+        </InputParts>
+      </FieldLayout>
+    );
+  }
+
+  return (
+    <Field
+      form={resolvedForm}
+      name={name}
+      defaultValue={defaultValue}
+      validators={resolvedValidators}
+    >
+      {(field) => {
+        const resolvedError = getFieldError(field, error);
+        return (
+          <FieldLayout
+            id={id}
+            label={label}
+            labelProps={labelProps}
+            error={resolvedError}
+            helperText={helperText}
+            required={required}
+            size={sizeProp}
+            knobProps={knobProps as any}
+            {...rest}
+          >
+            <InputParts size={sizeProp || knobProps.sizeToken}>
+              {renderSelectContent(
+                field.state.value as string | string[],
+                (val) => field.handleChange(val as any),
+                mergeFieldHandler(field, "handleBlur", onBlur),
+              )}
+            </InputParts>
+          </FieldLayout>
+        );
+      }}
+    </Field>
+  );
+}