@underverse-ui/underverse 1.0.106 → 1.0.109

package/dist/index.cjs

@@ -7343,6 +7343,7 @@ var import_lucide_react14 = require("lucide-react");
 // src/components/Combobox.tsx
 var React24 = __toESM(require("react"), 1);
 var import_react15 = require("react");
+var import_react_virtual = require("@tanstack/react-virtual");
 var import_lucide_react13 = require("lucide-react");
 var import_jsx_runtime29 = require("react/jsx-runtime");
 var getOptionLabel = (option) => {
@@ -7388,9 +7389,19 @@ var Combobox = ({
   groupBy,
   renderOption,
   renderValue,
+  selectedOption: selectedOptionProp,
   error,
   helperText,
-  useOverlayScrollbar = false
+  useOverlayScrollbar = false,
+  virtualized = false,
+  estimatedItemHeight = 44,
+  overscan = 8,
+  searchMode = "auto",
+  onSearchChange,
+  searchDebounceMs = 0,
+  minSearchLength = 0,
+  maxInitialOptions,
+  showSearchPromptWhenEmptyQuery = false
 }) => {
   const tv = useSmartTranslations("ValidationInput");
   const [open, setOpen] = React24.useState(false);
@@ -7404,12 +7415,53 @@ var Combobox = ({
   const autoId = (0, import_react15.useId)();
   const resolvedId = id ? String(id) : `combobox-${autoId}`;
   const labelId = label ? `${resolvedId}-label` : void 0;
-  const enableSearch = options.length > 10;
+  const enableSearch = options.length > 10 || searchMode === "manual" || minSearchLength > 0 || !!onSearchChange;
+  const trimmedQuery = query.trim();
+  const queryMeetsMinimum = trimmedQuery.length >= minSearchLength;
+  const shouldPromptForSearch = minSearchLength > 0 && !queryMeetsMinimum && (searchMode === "manual" || showSearchPromptWhenEmptyQuery);
   const filteredOptions = React24.useMemo(
-    () => enableSearch ? options.filter((o) => getOptionLabel(o).toLowerCase().includes(query.trim().toLowerCase())) : options,
-    [options, query, enableSearch]
+    () => {
+      if (shouldPromptForSearch) return [];
+      if (!enableSearch || searchMode === "manual") return options;
+      const normalizedQuery = trimmedQuery.toLowerCase();
+      if (!normalizedQuery) return options;
+      return options.filter((o) => getOptionLabel(o).toLowerCase().includes(normalizedQuery));
+    },
+    [enableSearch, options, searchMode, shouldPromptForSearch, trimmedQuery]
+  );
+  const renderLimitedOptions = React24.useMemo(
+    () => {
+      if (trimmedQuery || maxInitialOptions === void 0 || maxInitialOptions < 1) {
+        return filteredOptions;
+      }
+      return filteredOptions.slice(0, maxInitialOptions);
+    },
+    [filteredOptions, maxInitialOptions, trimmedQuery]
   );
+  const canVirtualize = virtualized && !groupBy;
+  const optionVirtualizer = (0, import_react_virtual.useVirtualizer)({
+    count: canVirtualize ? renderLimitedOptions.length : 0,
+    getScrollElement: () => optionsViewportRef.current,
+    estimateSize: () => estimatedItemHeight,
+    initialRect: { width: 0, height: maxHeight },
+    overscan,
+    enabled: canVirtualize
+  });
+  const virtualItems = canVirtualize ? optionVirtualizer.getVirtualItems() : [];
   const triggerRef = React24.useRef(null);
+  const scrollVirtualListToIndex = React24.useCallback((index) => {
+    if (!canVirtualize || renderLimitedOptions.length === 0) return;
+    optionVirtualizer.scrollToIndex(index, { align: "auto" });
+  }, [canVirtualize, optionVirtualizer, renderLimitedOptions.length]);
+  const scrollVirtualListToStart = React24.useCallback(() => {
+    scrollVirtualListToIndex(0);
+  }, [scrollVirtualListToIndex]);
+  const moveActiveIndex = React24.useCallback((direction) => {
+    if (renderLimitedOptions.length === 0) return;
+    const next = activeIndex === null ? direction === 1 ? 0 : renderLimitedOptions.length - 1 : (activeIndex + direction + renderLimitedOptions.length) % renderLimitedOptions.length;
+    setActiveIndex(next);
+    scrollVirtualListToIndex(next);
+  }, [activeIndex, renderLimitedOptions.length, scrollVirtualListToIndex]);
   const handleSelect = (option) => {
     if (getOptionDisabled(option)) return;
     const val = getOptionValue(option);
@@ -7422,6 +7474,9 @@ var Combobox = ({
   };
   const handleClear = (e) => {
     e.stopPropagation();
+    clearValue();
+  };
+  const clearValue = () => {
     onChange(null);
     setOpen(false);
   };
@@ -7429,13 +7484,26 @@ var Combobox = ({
     if (!open) {
       setQuery("");
       setActiveIndex(null);
+      scrollVirtualListToStart();
     } else if (enableSearch) {
       setTimeout(() => {
         inputRef.current?.focus();
       }, 100);
     }
-  }, [open, enableSearch]);
-  const selectedOption = findOptionByValue(options, value);
+  }, [enableSearch, open, scrollVirtualListToStart]);
+  React24.useEffect(() => {
+    if (!onSearchChange) return void 0;
+    const timeoutId = window.setTimeout(() => onSearchChange(query), searchDebounceMs);
+    return () => window.clearTimeout(timeoutId);
+  }, [onSearchChange, query, searchDebounceMs]);
+  React24.useEffect(() => {
+    if (process.env.NODE_ENV !== "production" && options.length > 300 && !virtualized && searchMode !== "manual" && maxInitialOptions === void 0) {
+      console.warn(
+        '[Underverse UI] Combobox received more than 300 options without virtualization, manual search, or maxInitialOptions. Use virtualized, searchMode="manual", or maxInitialOptions to avoid rendering a large dropdown.'
+      );
+    }
+  }, [maxInitialOptions, options.length, searchMode, virtualized]);
+  const selectedOption = findOptionByValue(options, value) ?? (selectedOptionProp && getOptionValue(selectedOptionProp) === value ? selectedOptionProp : void 0);
   const displayValue = selectedOption ? getOptionLabel(selectedOption) : "";
   const selectedIcon = selectedOption ? getOptionIcon(selectedOption) : void 0;
   const hasValue = value !== void 0 && value !== null && value !== "";
@@ -7448,13 +7516,13 @@ var Combobox = ({
   const groupedOptions = React24.useMemo(() => {
     if (!groupBy) return null;
     const groups = {};
-    filteredOptions.forEach((opt) => {
+    renderLimitedOptions.forEach((opt) => {
       const group = groupBy(opt);
       if (!groups[group]) groups[group] = [];
       groups[group].push(opt);
     });
     return groups;
-  }, [filteredOptions, groupBy]);
+  }, [renderLimitedOptions, groupBy]);
   const itemSizeStyles = {
     sm: "px-2.5 py-1.5 text-xs gap-2",
     md: "px-3 py-2.5 text-sm gap-3",
@@ -7470,60 +7538,75 @@ var Combobox = ({
     md: "h-4 w-4",
     lg: "h-5 w-5"
   };
-  const renderOptionItem = (item, index) => {
+  const renderOptionItem = (item, index, virtualItem) => {
     const itemValue = getOptionValue(item);
     const itemLabel = getOptionLabel(item);
     const itemIcon = getOptionIcon(item);
     const itemDescription = getOptionDescription(item);
     const itemDisabled = getOptionDisabled(item);
     const isSelected = itemValue === value;
-    return /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("li", { className: "list-none", children: /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)(
-      "button",
+    return /* @__PURE__ */ (0, import_jsx_runtime29.jsx)(
+      "li",
       {
-        id: `combobox-item-${index}`,
-        type: "button",
-        role: "option",
-        tabIndex: -1,
-        disabled: itemDisabled,
-        "aria-selected": isSelected,
-        onClick: () => handleSelect(item),
-        style: {
-          animationDelay: open ? `${Math.min(index * 15, 150)}ms` : "0ms"
-        },
-        className: cn(
-          "dropdown-item group flex w-full items-center rounded-full text-left",
-          itemSizeStyles[size],
-          "outline-none focus:outline-none focus-visible:outline-none",
-          "transition-all duration-150",
-          !itemDisabled && "cursor-pointer hover:bg-accent/70 hover:shadow-sm",
-          !itemDisabled && "focus:bg-accent/80 focus:text-accent-foreground",
-          index === activeIndex && !itemDisabled && "bg-accent/60",
-          isSelected && "bg-primary/10 text-primary font-medium",
-          itemDisabled && "opacity-50 cursor-not-allowed"
-        ),
-        children: [
-          itemIcon && /* @__PURE__ */ (0, import_jsx_runtime29.jsx)(
-            "span",
-            {
-              className: cn("shrink-0 flex items-center justify-center", iconSizeStyles[size], isSelected ? "text-primary" : "text-muted-foreground"),
-              children: itemIcon
-            }
-          ),
-          renderOption ? /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: "flex-1 min-w-0", children: renderOption(item, isSelected) }) : /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)("div", { className: "flex-1 min-w-0", children: [
-            /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("span", { className: "block truncate", children: itemLabel }),
-            itemDescription && /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("span", { className: cn("block text-muted-foreground truncate mt-0.5", size === "sm" ? "text-[10px]" : "text-xs"), children: itemDescription })
-          ] }),
-          isSelected && showSelectedIcon && /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("span", { className: "shrink-0 ml-auto", children: /* @__PURE__ */ (0, import_jsx_runtime29.jsx)(import_lucide_react13.Check, { className: cn(checkIconSizeStyles[size], "text-primary") }) })
-        ]
-      }
-    ) }, `${itemValue}-${index}`);
+        ref: virtualItem ? optionVirtualizer.measureElement : void 0,
+        "data-index": virtualItem?.index,
+        className: "list-none",
+        style: virtualItem ? {
+          position: "absolute",
+          top: 0,
+          left: 0,
+          width: "100%",
+          transform: `translateY(${virtualItem.start}px)`
+        } : void 0,
+        children: /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)(
+          "button",
+          {
+            id: `${resolvedId}-item-${index}`,
+            type: "button",
+            role: "option",
+            tabIndex: -1,
+            disabled: itemDisabled,
+            "aria-selected": isSelected,
+            onClick: () => handleSelect(item),
+            style: {
+              animationDelay: open ? `${Math.min(index * 15, 150)}ms` : "0ms"
+            },
+            className: cn(
+              "dropdown-item group flex w-full items-center rounded-full text-left",
+              itemSizeStyles[size],
+              "outline-none focus:outline-none focus-visible:outline-none",
+              "transition-all duration-150",
+              !itemDisabled && "cursor-pointer hover:bg-accent/70 hover:shadow-sm",
+              !itemDisabled && "focus:bg-accent/80 focus:text-accent-foreground",
+              index === activeIndex && !itemDisabled && "bg-accent/60",
+              isSelected && "bg-primary/10 text-primary font-medium",
+              itemDisabled && "opacity-50 cursor-not-allowed"
+            ),
+            children: [
+              itemIcon && /* @__PURE__ */ (0, import_jsx_runtime29.jsx)(
+                "span",
+                {
+                  className: cn("shrink-0 flex items-center justify-center", iconSizeStyles[size], isSelected ? "text-primary" : "text-muted-foreground"),
+                  children: itemIcon
+                }
+              ),
+              renderOption ? /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: "flex-1 min-w-0", children: renderOption(item, isSelected) }) : /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)("div", { className: "flex-1 min-w-0", children: [
+                /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("span", { className: "block truncate", children: itemLabel }),
+                itemDescription && /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("span", { className: cn("block text-muted-foreground truncate mt-0.5", size === "sm" ? "text-[10px]" : "text-xs"), children: itemDescription })
+              ] }),
+              isSelected && showSelectedIcon && /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("span", { className: "shrink-0 ml-auto", children: /* @__PURE__ */ (0, import_jsx_runtime29.jsx)(import_lucide_react13.Check, { className: cn(checkIconSizeStyles[size], "text-primary") }) })
+            ]
+          }
+        )
+      },
+      `${itemValue}-${index}`
+    );
   };
   const dropdownBody = /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)(
     "div",
     {
       "data-combobox-dropdown": true,
       "data-state": open ? "open" : "closed",
-      id: `${resolvedId}-listbox`,
       className: "w-full rounded-2xl md:rounded-3xl overflow-hidden",
       children: [
         enableSearch && /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: cn("relative border-b border-border/30", size === "sm" ? "p-2" : size === "lg" ? "p-3" : "p-2.5"), children: /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)("div", { className: "relative", children: [
@@ -7544,24 +7627,19 @@ var Combobox = ({
               onChange: (e) => {
                 setQuery(e.target.value);
                 setActiveIndex(null);
+                scrollVirtualListToStart();
               },
               onKeyDown: (e) => {
                 if (e.key === "ArrowDown") {
                   e.preventDefault();
-                  setActiveIndex((prev) => {
-                    const next = prev === null ? 0 : prev + 1;
-                    return next >= filteredOptions.length ? 0 : next;
-                  });
+                  moveActiveIndex(1);
                 } else if (e.key === "ArrowUp") {
                   e.preventDefault();
-                  setActiveIndex((prev) => {
-                    const next = prev === null ? filteredOptions.length - 1 : prev - 1;
-                    return next < 0 ? filteredOptions.length - 1 : next;
-                  });
+                  moveActiveIndex(-1);
                 } else if (e.key === "Enter") {
                   e.preventDefault();
-                  if (activeIndex !== null && filteredOptions[activeIndex] && !getOptionDisabled(filteredOptions[activeIndex])) {
-                    handleSelect(filteredOptions[activeIndex]);
+                  if (activeIndex !== null && renderLimitedOptions[activeIndex] && !getOptionDisabled(renderLimitedOptions[activeIndex])) {
+                    handleSelect(renderLimitedOptions[activeIndex]);
                   }
                 } else if (e.key === "Escape") {
                   e.preventDefault();
@@ -7584,7 +7662,10 @@ var Combobox = ({
             "button",
             {
               type: "button",
-              onClick: () => setQuery(""),
+              onClick: () => {
+                setQuery("");
+                scrollVirtualListToStart();
+              },
               className: "absolute right-3 top-1/2 -translate-y-1/2 p-0.5 rounded-md hover:bg-muted text-muted-foreground hover:text-foreground transition-colors",
               children: /* @__PURE__ */ (0, import_jsx_runtime29.jsx)(import_lucide_react13.X, { className: cn(size === "sm" ? "h-3 w-3" : size === "lg" ? "h-4 w-4" : "h-3.5 w-3.5") })
             }
@@ -7594,6 +7675,7 @@ var Combobox = ({
           "div",
           {
             ref: optionsViewportRef,
+            id: `${resolvedId}-listbox`,
             role: "listbox",
             "aria-labelledby": labelId,
             className: "overflow-y-auto overscroll-contain",
@@ -7601,7 +7683,14 @@ var Combobox = ({
             children: /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: cn(size === "sm" ? "p-1" : size === "lg" ? "p-2" : "p-1.5"), children: loading2 ? /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: "px-3 py-10 text-center", children: /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
               /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: "relative", children: /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: "w-10 h-10 rounded-full border-2 border-primary/20 border-t-primary animate-spin" }) }),
               /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("span", { className: "text-sm text-muted-foreground", children: loadingText })
-            ] }) }) : filteredOptions.length > 0 ? groupedOptions ? (
+            ] }) }) : shouldPromptForSearch ? /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: "px-3 py-10 text-center", children: /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
+              /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: "w-12 h-12 rounded-full bg-muted/50 flex items-center justify-center", children: /* @__PURE__ */ (0, import_jsx_runtime29.jsx)(import_lucide_react13.Search, { className: "h-6 w-6 text-muted-foreground/60" }) }),
+              /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: "space-y-1", children: /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)("span", { className: "block text-sm font-medium text-foreground", children: [
+                "Type at least ",
+                minSearchLength,
+                " characters to search"
+              ] }) })
+            ] }) }) : renderLimitedOptions.length > 0 ? groupedOptions ? (
               // Render grouped options with global index tracking
               (() => {
                 let globalIndex = 0;
@@ -7615,7 +7704,14 @@ var Combobox = ({
               })()
             ) : (
               // Render flat options
-              /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("ul", { className: "space-y-0.5", children: filteredOptions.map((item, index) => renderOptionItem(item, index)) })
+              /* @__PURE__ */ (0, import_jsx_runtime29.jsx)(
+                "ul",
+                {
+                  className: "space-y-0.5",
+                  style: canVirtualize ? { height: `${optionVirtualizer.getTotalSize()}px`, position: "relative" } : void 0,
+                  children: canVirtualize ? virtualItems.map((virtualItem) => renderOptionItem(renderLimitedOptions[virtualItem.index], virtualItem.index, virtualItem)) : renderLimitedOptions.map((item, index) => renderOptionItem(item, index))
+                }
+              )
             ) : /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: "px-3 py-10 text-center", children: /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
               /* @__PURE__ */ (0, import_jsx_runtime29.jsx)("div", { className: "w-12 h-12 rounded-full bg-muted/50 flex items-center justify-center", children: /* @__PURE__ */ (0, import_jsx_runtime29.jsx)(import_lucide_react13.SearchX, { className: "h-6 w-6 text-muted-foreground/60" }) }),
               /* @__PURE__ */ (0, import_jsx_runtime29.jsxs)("div", { className: "space-y-1", children: [
@@ -7626,7 +7722,10 @@ var Combobox = ({
                 "button",
                 {
                   type: "button",
-                  onClick: () => setQuery(""),
+                  onClick: () => {
+                    setQuery("");
+                    scrollVirtualListToStart();
+                  },
                   className: "px-3 py-1.5 text-xs font-medium text-primary bg-primary/10 rounded-full hover:bg-primary/20 transition-colors",
                   children: "Clear search"
                 }
@@ -7696,7 +7795,13 @@ var Combobox = ({
           tabIndex: 0,
           "aria-label": "Clear selection",
           onClick: handleClear,
-          onKeyDown: (e) => (e.key === "Enter" || e.key === " ") && handleClear(e),
+          onKeyDown: (e) => {
+            if (e.key === "Enter" || e.key === " ") {
+              e.preventDefault();
+              e.stopPropagation();
+              clearValue();
+            }
+          },
           className: cn(
             "opacity-0 group-hover:opacity-100 transition-all duration-200",
             "p-1 rounded-lg hover:bg-destructive/10 text-muted-foreground hover:text-destructive"
@@ -15576,6 +15681,7 @@ function CalendarTimeline({
 // src/components/MultiCombobox.tsx
 var React39 = __toESM(require("react"), 1);
 var import_react20 = require("react");
+var import_react_virtual2 = require("@tanstack/react-virtual");
 var import_lucide_react24 = require("lucide-react");
 var import_jsx_runtime45 = require("react/jsx-runtime");
 var MultiCombobox = ({
@@ -15606,10 +15712,20 @@ var MultiCombobox = ({
   groupBy,
   renderOption,
   renderTag,
+  selectedOptions: selectedOptionsProp,
   error,
   helperText,
   maxTagsVisible = 3,
-  useOverlayScrollbar = false
+  useOverlayScrollbar = false,
+  virtualized = false,
+  estimatedItemHeight = 44,
+  overscan = 8,
+  searchMode = "auto",
+  onSearchChange,
+  searchDebounceMs = 0,
+  minSearchLength = 0,
+  maxInitialOptions,
+  showSearchPromptWhenEmptyQuery = false
 }) => {
   const tv = useSmartTranslations("ValidationInput");
   const [query, setQuery] = React39.useState("");
@@ -15628,23 +15744,52 @@ var MultiCombobox = ({
     ),
     [options]
   );
-  const enableSearch = normalizedOptions.length > 10;
-  const filtered = React39.useMemo(
-    () => enableSearch ? normalizedOptions.filter(
-      (opt) => opt.label.toLowerCase().includes(query.trim().toLowerCase()) || opt.description?.toLowerCase().includes(query.trim().toLowerCase())
-    ) : normalizedOptions,
-    [normalizedOptions, query, enableSearch]
-  );
+  const enableSearch = normalizedOptions.length > 10 || searchMode === "manual" || minSearchLength > 0 || !!onSearchChange;
+  const trimmedQuery = query.trim();
+  const queryMeetsMinimum = trimmedQuery.length >= minSearchLength;
+  const shouldPromptForSearch = minSearchLength > 0 && !queryMeetsMinimum && (searchMode === "manual" || showSearchPromptWhenEmptyQuery);
+  const filtered = React39.useMemo(() => {
+    if (shouldPromptForSearch) return [];
+    if (!enableSearch || searchMode === "manual") return normalizedOptions;
+    const normalizedQuery = trimmedQuery.toLowerCase();
+    if (!normalizedQuery) return normalizedOptions;
+    return normalizedOptions.filter(
+      (opt) => opt.label.toLowerCase().includes(normalizedQuery) || opt.description?.toLowerCase().includes(normalizedQuery)
+    );
+  }, [enableSearch, normalizedOptions, searchMode, shouldPromptForSearch, trimmedQuery]);
+  const renderLimitedOptions = React39.useMemo(() => {
+    if (trimmedQuery || maxInitialOptions === void 0 || maxInitialOptions < 1) {
+      return filtered;
+    }
+    return filtered.slice(0, maxInitialOptions);
+  }, [filtered, maxInitialOptions, trimmedQuery]);
+  const canVirtualize = virtualized && !groupBy;
+  const optionVirtualizer = (0, import_react_virtual2.useVirtualizer)({
+    count: canVirtualize ? renderLimitedOptions.length : 0,
+    getScrollElement: () => optionsListRef.current,
+    estimateSize: () => estimatedItemHeight,
+    initialRect: { width: 0, height: maxHeight },
+    overscan,
+    enabled: canVirtualize
+  });
+  const virtualItems = canVirtualize ? optionVirtualizer.getVirtualItems() : [];
+  const scrollVirtualListToIndex = React39.useCallback((index) => {
+    if (!canVirtualize || renderLimitedOptions.length === 0) return;
+    optionVirtualizer.scrollToIndex(index, { align: "auto" });
+  }, [canVirtualize, optionVirtualizer, renderLimitedOptions.length]);
+  const scrollVirtualListToStart = React39.useCallback(() => {
+    scrollVirtualListToIndex(0);
+  }, [scrollVirtualListToIndex]);
   const groupedOptions = React39.useMemo(() => {
     if (!groupBy) return null;
     const groups = /* @__PURE__ */ new Map();
-    filtered.forEach((opt) => {
+    renderLimitedOptions.forEach((opt) => {
       const group = groupBy(opt);
       if (!groups.has(group)) groups.set(group, []);
       groups.get(group).push(opt);
     });
     return groups;
-  }, [filtered, groupBy]);
+  }, [renderLimitedOptions, groupBy]);
   const toggleSelect = (optionValue) => {
     const option = normalizedOptions.find((o) => o.value === optionValue);
     if (option?.disabled || disabledOptions.includes(optionValue)) return;
@@ -15662,11 +15807,26 @@ var MultiCombobox = ({
   };
   const handleKeyDown2 = (e) => {
     if (!open) setOpen(true);
-    if (e.key === "Enter") {
+    if (e.key === "ArrowDown") {
       e.preventDefault();
-      if (activeIndex !== null && filtered[activeIndex]) {
-        toggleSelect(filtered[activeIndex].value);
+      if (renderLimitedOptions.length === 0) return;
+      const next = activeIndex === null ? 0 : (activeIndex + 1) % renderLimitedOptions.length;
+      setActiveIndex(next);
+      scrollVirtualListToIndex(next);
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      if (renderLimitedOptions.length === 0) return;
+      const next = activeIndex === null ? renderLimitedOptions.length - 1 : (activeIndex - 1 + renderLimitedOptions.length) % renderLimitedOptions.length;
+      setActiveIndex(next);
+      scrollVirtualListToIndex(next);
+    } else if (e.key === "Enter") {
+      e.preventDefault();
+      if (activeIndex !== null && renderLimitedOptions[activeIndex]) {
+        toggleSelect(renderLimitedOptions[activeIndex].value);
       }
+    } else if (e.key === "Escape") {
+      e.preventDefault();
+      setOpen(false);
     }
   };
   const handleClearAll = () => {
@@ -15683,8 +15843,24 @@ var MultiCombobox = ({
       setTimeout(() => {
         inputRef.current?.focus();
       }, 100);
+    } else if (!open) {
+      setQuery("");
+      setActiveIndex(null);
+      scrollVirtualListToStart();
     }
-  }, [open, enableSearch]);
+  }, [enableSearch, open, scrollVirtualListToStart]);
+  React39.useEffect(() => {
+    if (!onSearchChange) return void 0;
+    const timeoutId = window.setTimeout(() => onSearchChange(query), searchDebounceMs);
+    return () => window.clearTimeout(timeoutId);
+  }, [onSearchChange, query, searchDebounceMs]);
+  React39.useEffect(() => {
+    if (process.env.NODE_ENV !== "production" && normalizedOptions.length > 300 && !virtualized && searchMode !== "manual" && maxInitialOptions === void 0) {
+      console.warn(
+        '[Underverse UI] MultiCombobox received more than 300 options without virtualization, manual search, or maxInitialOptions. Use virtualized, searchMode="manual", or maxInitialOptions to avoid rendering a large dropdown.'
+      );
+    }
+  }, [maxInitialOptions, normalizedOptions.length, searchMode, virtualized]);
   const sizeStyles8 = {
     sm: {
       trigger: "h-8 px-3 py-1.5 text-sm md:h-7 md:text-xs",
@@ -15718,25 +15894,38 @@ var MultiCombobox = ({
   const labelId = label ? `${resolvedId}-label` : void 0;
   const labelSize = size === "sm" ? "text-xs" : size === "lg" ? "text-base" : "text-sm";
   const listboxId = `${resolvedId}-listbox`;
-  const renderOptionItem = (item, index) => {
+  const renderOptionItem = (item, index, virtualItem) => {
     const isSelected = value.includes(item.value);
     const isDisabled = item.disabled || disabledOptions.includes(item.value);
     const optionIcon = item.icon;
     const optionDesc = item.description;
+    const itemStyle = {
+      animationDelay: open ? `${Math.min(index * 20, 200)}ms` : "0ms",
+      ...virtualItem ? {
+        position: "absolute",
+        top: 0,
+        left: 0,
+        width: "100%",
+        transform: `translateY(${virtualItem.start}px)`
+      } : {}
+    };
+    const measureRef = virtualItem ? optionVirtualizer.measureElement : void 0;
     if (renderOption) {
       return /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(
         "li",
         {
           ref: (node) => {
+            measureRef?.(node);
             listRef.current[index] = node;
           },
+          "data-index": virtualItem?.index,
+          style: itemStyle,
           onClick: (e) => {
             e.preventDefault();
             e.stopPropagation();
             if (!isDisabled) toggleSelect(item.value);
             inputRef.current?.focus();
           },
-          style: { animationDelay: open ? `${Math.min(index * 20, 200)}ms` : "0ms" },
           className: cn("dropdown-item", isDisabled && "opacity-50 cursor-not-allowed pointer-events-none"),
           children: renderOption(item, isSelected)
         },
@@ -15747,15 +15936,17 @@ var MultiCombobox = ({
       "li",
       {
         ref: (node) => {
+          measureRef?.(node);
           listRef.current[index] = node;
         },
+        "data-index": virtualItem?.index,
+        style: itemStyle,
         onClick: (e) => {
           e.preventDefault();
           e.stopPropagation();
           if (!isDisabled) toggleSelect(item.value);
           inputRef.current?.focus();
         },
-        style: { animationDelay: open ? `${Math.min(index * 20, 200)}ms` : "0ms" },
         className: cn(
           "dropdown-item flex cursor-pointer items-center gap-3 rounded-full transition-all duration-200",
           sizeStyles8[size].item,
@@ -15819,6 +16010,7 @@ var MultiCombobox = ({
           onChange: (e) => {
             setQuery(e.target.value);
             setActiveIndex(null);
+            scrollVirtualListToStart();
           },
           onKeyDown: handleKeyDown2,
           placeholder: searchPlaceholder,
@@ -15829,7 +16021,10 @@ var MultiCombobox = ({
         "button",
         {
           type: "button",
-          onClick: () => setQuery(""),
+          onClick: () => {
+            setQuery("");
+            scrollVirtualListToStart();
+          },
           className: "absolute right-3 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground transition-colors",
           children: /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(import_lucide_react24.X, { className: "w-4 h-4" })
         }
@@ -15850,30 +16045,52 @@ var MultiCombobox = ({
             /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(import_lucide_react24.Sparkles, { className: "h-4 w-4 text-primary/60 absolute -top-1 -right-1 animate-pulse" })
           ] }),
           /* @__PURE__ */ (0, import_jsx_runtime45.jsx)("span", { className: "text-muted-foreground font-medium", children: loadingText })
-        ] }) }) : filtered.length ? groupedOptions ? (
+        ] }) }) : shouldPromptForSearch ? /* @__PURE__ */ (0, import_jsx_runtime45.jsx)("li", { className: "px-3 py-8 text-center text-muted-foreground", children: /* @__PURE__ */ (0, import_jsx_runtime45.jsxs)("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
+          /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(import_lucide_react24.Search, { className: "h-10 w-10 opacity-30 text-muted-foreground" }),
+          /* @__PURE__ */ (0, import_jsx_runtime45.jsxs)("span", { className: "font-medium block text-foreground", children: [
+            "Type at least ",
+            minSearchLength,
+            " characters to search"
+          ] })
+        ] }) }) : renderLimitedOptions.length ? groupedOptions ? (
           // Render grouped options
           Array.from(groupedOptions.entries()).map(([group, items]) => /* @__PURE__ */ (0, import_jsx_runtime45.jsxs)("li", { className: "mb-2", children: [
             /* @__PURE__ */ (0, import_jsx_runtime45.jsx)("div", { className: "px-3 py-1.5 text-xs font-semibold text-muted-foreground uppercase tracking-wider sticky top-0 bg-popover/95 backdrop-blur-sm", children: group }),
-            /* @__PURE__ */ (0, import_jsx_runtime45.jsx)("ul", { children: items.map((item) => renderOptionItem(item, filtered.indexOf(item))) })
+            /* @__PURE__ */ (0, import_jsx_runtime45.jsx)("ul", { children: items.map((item) => renderOptionItem(item, renderLimitedOptions.indexOf(item))) })
           ] }, group))
         ) : (
           // Render flat options
-          filtered.map((item, index) => renderOptionItem(item, index))
+          canVirtualize ? /* @__PURE__ */ (0, import_jsx_runtime45.jsx)("li", { role: "presentation", className: "list-none p-0", children: /* @__PURE__ */ (0, import_jsx_runtime45.jsx)("ul", { className: "relative", style: { height: `${optionVirtualizer.getTotalSize()}px` }, children: virtualItems.map((virtualItem) => renderOptionItem(renderLimitedOptions[virtualItem.index], virtualItem.index, virtualItem)) }) }) : renderLimitedOptions.map((item, index) => renderOptionItem(item, index))
         ) : /* @__PURE__ */ (0, import_jsx_runtime45.jsx)("li", { className: cn("px-3 py-8 text-center text-muted-foreground"), children: /* @__PURE__ */ (0, import_jsx_runtime45.jsxs)("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
           /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(import_lucide_react24.SearchX, { className: "h-10 w-10 opacity-30 text-muted-foreground" }),
           /* @__PURE__ */ (0, import_jsx_runtime45.jsxs)("div", { className: "space-y-1", children: [
             /* @__PURE__ */ (0, import_jsx_runtime45.jsx)("span", { className: "font-medium block", children: emptyText }),
             query && /* @__PURE__ */ (0, import_jsx_runtime45.jsx)("span", { className: "text-xs opacity-60", children: "Try a different search term" })
           ] }),
-          query && /* @__PURE__ */ (0, import_jsx_runtime45.jsxs)("button", { type: "button", onClick: () => setQuery(""), className: "text-xs text-primary hover:underline flex items-center gap-1", children: [
-            /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(import_lucide_react24.X, { className: "w-3 h-3" }),
-            "Clear search"
-          ] })
+          query && /* @__PURE__ */ (0, import_jsx_runtime45.jsxs)(
+            "button",
+            {
+              type: "button",
+              onClick: () => {
+                setQuery("");
+                scrollVirtualListToStart();
+              },
+              className: "text-xs text-primary hover:underline flex items-center gap-1",
+              children: [
+                /* @__PURE__ */ (0, import_jsx_runtime45.jsx)(import_lucide_react24.X, { className: "w-3 h-3" }),
+                "Clear search"
+              ]
+            }
+          )
         ] }) })
       }
     )
   ] });
-  const selectedOptions = value.map((v) => normalizedOptions.find((o) => o.value === v)).filter(Boolean);
+  const selectedOptionFallbackMap = React39.useMemo(
+    () => new Map((selectedOptionsProp ?? []).map((option) => [option.value, option])),
+    [selectedOptionsProp]
+  );
+  const selectedOptions = value.map((v) => normalizedOptions.find((o) => o.value === v) ?? selectedOptionFallbackMap.get(v)).filter(Boolean);
   const visibleTags = maxTagsVisible ? selectedOptions.slice(0, maxTagsVisible) : selectedOptions;
   const hiddenCount = maxTagsVisible ? Math.max(0, selectedOptions.length - maxTagsVisible) : 0;
   const triggerButton = /* @__PURE__ */ (0, import_jsx_runtime45.jsxs)(