@underverse-ui/underverse 1.0.107 → 1.0.110

package/dist/index.js

@@ -7158,6 +7158,7 @@ import { ChevronLeft, ChevronRight as ChevronRight2, ChevronsLeft, ChevronsRight
 // src/components/Combobox.tsx
 import * as React24 from "react";
 import { useId as useId6 } from "react";
+import { useVirtualizer } from "@tanstack/react-virtual";
 import { ChevronDown, Search as Search4, SearchX, Check as Check3, X as X9 } from "lucide-react";
 import { Fragment as Fragment5, jsx as jsx29, jsxs as jsxs22 } from "react/jsx-runtime";
 var getOptionLabel = (option) => {
@@ -7178,6 +7179,20 @@ var getOptionDisabled = (option) => {
 var findOptionByValue = (options, value) => {
   return options.find((opt) => getOptionValue(opt) === value);
 };
+var comboboxScrollClassName = [
+  "scrollbar-thin",
+  "[scrollbar-width:thin]",
+  "[scrollbar-color:color-mix(in_oklch,var(--muted-foreground)_28%,transparent)_transparent]",
+  "[&::-webkit-scrollbar]:w-2",
+  "[&::-webkit-scrollbar-track]:bg-transparent",
+  "[&::-webkit-scrollbar-thumb]:rounded-full",
+  "[&::-webkit-scrollbar-thumb]:border-2",
+  "[&::-webkit-scrollbar-thumb]:border-solid",
+  "[&::-webkit-scrollbar-thumb]:border-transparent",
+  "[&::-webkit-scrollbar-thumb]:bg-clip-padding",
+  "[&::-webkit-scrollbar-thumb]:bg-muted-foreground/25",
+  "[&::-webkit-scrollbar-thumb:hover]:bg-muted-foreground/45"
+].join(" ");
 var Combobox = ({
   id,
   options,
@@ -7203,9 +7218,19 @@ var Combobox = ({
   groupBy,
   renderOption,
   renderValue,
+  selectedOption: selectedOptionProp,
   error,
   helperText,
-  useOverlayScrollbar = false
+  useOverlayScrollbar = true,
+  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);
@@ -7215,16 +7240,57 @@ var Combobox = ({
   useShadCNAnimations();
   const inputRef = React24.useRef(null);
   const optionsViewportRef = React24.useRef(null);
-  useOverlayScrollbarTarget(optionsViewportRef, { enabled: useOverlayScrollbar });
+  useOverlayScrollbarTarget(optionsViewportRef, { enabled: useOverlayScrollbar && !virtualized });
   const autoId = useId6();
   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 = 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);
@@ -7237,6 +7303,9 @@ var Combobox = ({
   };
   const handleClear = (e) => {
     e.stopPropagation();
+    clearValue();
+  };
+  const clearValue = () => {
     onChange(null);
     setOpen(false);
   };
@@ -7244,13 +7313,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 !== "";
@@ -7263,13 +7345,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",
@@ -7285,60 +7367,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__ */ jsx29("li", { className: "list-none", children: /* @__PURE__ */ jsxs22(
-      "button",
+    return /* @__PURE__ */ jsx29(
+      "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__ */ jsx29(
-            "span",
-            {
-              className: cn("shrink-0 flex items-center justify-center", iconSizeStyles[size], isSelected ? "text-primary" : "text-muted-foreground"),
-              children: itemIcon
-            }
-          ),
-          renderOption ? /* @__PURE__ */ jsx29("div", { className: "flex-1 min-w-0", children: renderOption(item, isSelected) }) : /* @__PURE__ */ jsxs22("div", { className: "flex-1 min-w-0", children: [
-            /* @__PURE__ */ jsx29("span", { className: "block truncate", children: itemLabel }),
-            itemDescription && /* @__PURE__ */ jsx29("span", { className: cn("block text-muted-foreground truncate mt-0.5", size === "sm" ? "text-[10px]" : "text-xs"), children: itemDescription })
-          ] }),
-          isSelected && showSelectedIcon && /* @__PURE__ */ jsx29("span", { className: "shrink-0 ml-auto", children: /* @__PURE__ */ jsx29(Check3, { 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__ */ jsxs22(
+          "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__ */ jsx29(
+                "span",
+                {
+                  className: cn("shrink-0 flex items-center justify-center", iconSizeStyles[size], isSelected ? "text-primary" : "text-muted-foreground"),
+                  children: itemIcon
+                }
+              ),
+              renderOption ? /* @__PURE__ */ jsx29("div", { className: "flex-1 min-w-0", children: renderOption(item, isSelected) }) : /* @__PURE__ */ jsxs22("div", { className: "flex-1 min-w-0", children: [
+                /* @__PURE__ */ jsx29("span", { className: "block truncate", children: itemLabel }),
+                itemDescription && /* @__PURE__ */ jsx29("span", { className: cn("block text-muted-foreground truncate mt-0.5", size === "sm" ? "text-[10px]" : "text-xs"), children: itemDescription })
+              ] }),
+              isSelected && showSelectedIcon && /* @__PURE__ */ jsx29("span", { className: "shrink-0 ml-auto", children: /* @__PURE__ */ jsx29(Check3, { className: cn(checkIconSizeStyles[size], "text-primary") }) })
+            ]
+          }
+        )
+      },
+      `${itemValue}-${index}`
+    );
   };
   const dropdownBody = /* @__PURE__ */ jsxs22(
     "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__ */ jsx29("div", { className: cn("relative border-b border-border/30", size === "sm" ? "p-2" : size === "lg" ? "p-3" : "p-2.5"), children: /* @__PURE__ */ jsxs22("div", { className: "relative", children: [
@@ -7359,24 +7456,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();
@@ -7399,7 +7491,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__ */ jsx29(X9, { className: cn(size === "sm" ? "h-3 w-3" : size === "lg" ? "h-4 w-4" : "h-3.5 w-3.5") })
             }
@@ -7409,14 +7504,22 @@ var Combobox = ({
           "div",
           {
             ref: optionsViewportRef,
+            id: `${resolvedId}-listbox`,
             role: "listbox",
             "aria-labelledby": labelId,
-            className: "overflow-y-auto overscroll-contain",
+            className: cn("overflow-y-auto overscroll-contain", (!useOverlayScrollbar || virtualized) && comboboxScrollClassName),
             style: { maxHeight },
             children: /* @__PURE__ */ jsx29("div", { className: cn(size === "sm" ? "p-1" : size === "lg" ? "p-2" : "p-1.5"), children: loading2 ? /* @__PURE__ */ jsx29("div", { className: "px-3 py-10 text-center", children: /* @__PURE__ */ jsxs22("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
               /* @__PURE__ */ jsx29("div", { className: "relative", children: /* @__PURE__ */ jsx29("div", { className: "w-10 h-10 rounded-full border-2 border-primary/20 border-t-primary animate-spin" }) }),
               /* @__PURE__ */ jsx29("span", { className: "text-sm text-muted-foreground", children: loadingText })
-            ] }) }) : filteredOptions.length > 0 ? groupedOptions ? (
+            ] }) }) : shouldPromptForSearch ? /* @__PURE__ */ jsx29("div", { className: "px-3 py-10 text-center", children: /* @__PURE__ */ jsxs22("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
+              /* @__PURE__ */ jsx29("div", { className: "w-12 h-12 rounded-full bg-muted/50 flex items-center justify-center", children: /* @__PURE__ */ jsx29(Search4, { className: "h-6 w-6 text-muted-foreground/60" }) }),
+              /* @__PURE__ */ jsx29("div", { className: "space-y-1", children: /* @__PURE__ */ jsxs22("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;
@@ -7430,7 +7533,14 @@ var Combobox = ({
               })()
             ) : (
               // Render flat options
-              /* @__PURE__ */ jsx29("ul", { className: "space-y-0.5", children: filteredOptions.map((item, index) => renderOptionItem(item, index)) })
+              /* @__PURE__ */ jsx29(
+                "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__ */ jsx29("div", { className: "px-3 py-10 text-center", children: /* @__PURE__ */ jsxs22("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
               /* @__PURE__ */ jsx29("div", { className: "w-12 h-12 rounded-full bg-muted/50 flex items-center justify-center", children: /* @__PURE__ */ jsx29(SearchX, { className: "h-6 w-6 text-muted-foreground/60" }) }),
               /* @__PURE__ */ jsxs22("div", { className: "space-y-1", children: [
@@ -7441,7 +7551,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"
                 }
@@ -7511,7 +7624,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"
@@ -8287,7 +8406,7 @@ function formatDateSmart(date, locale = "en") {
 }
 
 // src/components/DatePicker.tsx
-import { Calendar, ChevronLeft as ChevronLeft2, ChevronRight as ChevronRight3, Sparkles as Sparkles2, X as XIcon } from "lucide-react";
+import { Calendar, ChevronLeft as ChevronLeft2, ChevronRight as ChevronRight3, Sparkles, X as XIcon } from "lucide-react";
 import * as React28 from "react";
 import { useId as useId7 } from "react";
 import { Fragment as Fragment6, jsx as jsx34, jsxs as jsxs24 } from "react/jsx-runtime";
@@ -8666,7 +8785,7 @@ var DatePicker = ({
             isDateDisabled(/* @__PURE__ */ new Date()) && "opacity-50 cursor-not-allowed hover:scale-100 active:scale-100"
           ),
           children: [
-            /* @__PURE__ */ jsx34(Sparkles2, { className: sizeStyles8[size].actionIcon }),
+            /* @__PURE__ */ jsx34(Sparkles, { className: sizeStyles8[size].actionIcon }),
             todayLabel || t("today")
           ]
         }
@@ -9246,7 +9365,7 @@ var DateRangePicker = ({
             isTodayUnavailable && "opacity-50 cursor-not-allowed hover:scale-100 active:scale-100"
           ),
           children: [
-            /* @__PURE__ */ jsx34(Sparkles2, { className: sizeStyles8[size].actionIcon }),
+            /* @__PURE__ */ jsx34(Sparkles, { className: sizeStyles8[size].actionIcon }),
             t("today")
           ]
         }
@@ -15391,8 +15510,23 @@ function CalendarTimeline({
 // src/components/MultiCombobox.tsx
 import * as React39 from "react";
 import { useId as useId9 } from "react";
-import { ChevronDown as ChevronDown4, Search as Search5, Check as Check6, SearchX as SearchX2, Loader2 as Loader24, X as X13, Sparkles as Sparkles3 } from "lucide-react";
+import { useVirtualizer as useVirtualizer2 } from "@tanstack/react-virtual";
+import { ChevronDown as ChevronDown4, Search as Search5, Check as Check6, SearchX as SearchX2, Loader2 as Loader23, X as X13, Sparkles as Sparkles2 } from "lucide-react";
 import { Fragment as Fragment13, jsx as jsx45, jsxs as jsxs35 } from "react/jsx-runtime";
+var comboboxScrollClassName2 = [
+  "scrollbar-thin",
+  "[scrollbar-width:thin]",
+  "[scrollbar-color:color-mix(in_oklch,var(--muted-foreground)_28%,transparent)_transparent]",
+  "[&::-webkit-scrollbar]:w-2",
+  "[&::-webkit-scrollbar-track]:bg-transparent",
+  "[&::-webkit-scrollbar-thumb]:rounded-full",
+  "[&::-webkit-scrollbar-thumb]:border-2",
+  "[&::-webkit-scrollbar-thumb]:border-solid",
+  "[&::-webkit-scrollbar-thumb]:border-transparent",
+  "[&::-webkit-scrollbar-thumb]:bg-clip-padding",
+  "[&::-webkit-scrollbar-thumb]:bg-muted-foreground/25",
+  "[&::-webkit-scrollbar-thumb:hover]:bg-muted-foreground/45"
+].join(" ");
 var MultiCombobox = ({
   id,
   options,
@@ -15421,10 +15555,20 @@ var MultiCombobox = ({
   groupBy,
   renderOption,
   renderTag,
+  selectedOptions: selectedOptionsProp,
   error,
   helperText,
   maxTagsVisible = 3,
-  useOverlayScrollbar = false
+  useOverlayScrollbar = true,
+  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("");
@@ -15434,7 +15578,7 @@ var MultiCombobox = ({
   const inputRef = React39.useRef(null);
   const listRef = React39.useRef([]);
   const optionsListRef = React39.useRef(null);
-  useOverlayScrollbarTarget(optionsListRef, { enabled: useOverlayScrollbar });
+  useOverlayScrollbarTarget(optionsListRef, { enabled: useOverlayScrollbar && !virtualized });
   const triggerRef = React39.useRef(null);
   useShadCNAnimations();
   const normalizedOptions = React39.useMemo(
@@ -15443,23 +15587,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 = useVirtualizer2({
+    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;
@@ -15477,11 +15650,26 @@ var MultiCombobox = ({
   };
   const handleKeyDown2 = (e) => {
     if (!open) setOpen(true);
-    if (e.key === "Enter") {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      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 (activeIndex !== null && filtered[activeIndex]) {
-        toggleSelect(filtered[activeIndex].value);
+      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 = () => {
@@ -15498,8 +15686,24 @@ var MultiCombobox = ({
       setTimeout(() => {
         inputRef.current?.focus();
       }, 100);
+    } else if (!open) {
+      setQuery("");
+      setActiveIndex(null);
+      scrollVirtualListToStart();
+    }
+  }, [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.'
+      );
     }
-  }, [open, enableSearch]);
+  }, [maxInitialOptions, normalizedOptions.length, searchMode, virtualized]);
   const sizeStyles8 = {
     sm: {
       trigger: "h-8 px-3 py-1.5 text-sm md:h-7 md:text-xs",
@@ -15533,25 +15737,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__ */ jsx45(
         "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)
         },
@@ -15562,15 +15779,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,
@@ -15634,6 +15853,7 @@ var MultiCombobox = ({
           onChange: (e) => {
             setQuery(e.target.value);
             setActiveIndex(null);
+            scrollVirtualListToStart();
           },
           onKeyDown: handleKeyDown2,
           placeholder: searchPlaceholder,
@@ -15644,7 +15864,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__ */ jsx45(X13, { className: "w-4 h-4" })
         }
@@ -15658,37 +15881,63 @@ var MultiCombobox = ({
         "aria-multiselectable": "true",
         ref: optionsListRef,
         style: { maxHeight },
-        className: cn("overflow-y-auto p-1.5", size === "lg" ? "text-base" : size === "sm" ? "text-xs" : "text-sm"),
+        className: cn(
+          "overflow-y-auto p-1.5",
+          (!useOverlayScrollbar || virtualized) && comboboxScrollClassName2,
+          size === "lg" ? "text-base" : size === "sm" ? "text-xs" : "text-sm"
+        ),
         children: loading2 ? /* @__PURE__ */ jsx45("li", { className: "px-3 py-8 text-center", children: /* @__PURE__ */ jsxs35("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
           /* @__PURE__ */ jsxs35("div", { className: "relative", children: [
-            /* @__PURE__ */ jsx45(Loader24, { className: "h-8 w-8 animate-spin text-primary" }),
-            /* @__PURE__ */ jsx45(Sparkles3, { className: "h-4 w-4 text-primary/60 absolute -top-1 -right-1 animate-pulse" })
+            /* @__PURE__ */ jsx45(Loader23, { className: "h-8 w-8 animate-spin text-primary" }),
+            /* @__PURE__ */ jsx45(Sparkles2, { className: "h-4 w-4 text-primary/60 absolute -top-1 -right-1 animate-pulse" })
           ] }),
           /* @__PURE__ */ jsx45("span", { className: "text-muted-foreground font-medium", children: loadingText })
-        ] }) }) : filtered.length ? groupedOptions ? (
+        ] }) }) : shouldPromptForSearch ? /* @__PURE__ */ jsx45("li", { className: "px-3 py-8 text-center text-muted-foreground", children: /* @__PURE__ */ jsxs35("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
+          /* @__PURE__ */ jsx45(Search5, { className: "h-10 w-10 opacity-30 text-muted-foreground" }),
+          /* @__PURE__ */ jsxs35("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__ */ jsxs35("li", { className: "mb-2", children: [
             /* @__PURE__ */ jsx45("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__ */ jsx45("ul", { children: items.map((item) => renderOptionItem(item, filtered.indexOf(item))) })
+            /* @__PURE__ */ jsx45("ul", { children: items.map((item) => renderOptionItem(item, renderLimitedOptions.indexOf(item))) })
           ] }, group))
         ) : (
           // Render flat options
-          filtered.map((item, index) => renderOptionItem(item, index))
+          canVirtualize ? /* @__PURE__ */ jsx45("li", { role: "presentation", className: "list-none p-0", children: /* @__PURE__ */ jsx45("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__ */ jsx45("li", { className: cn("px-3 py-8 text-center text-muted-foreground"), children: /* @__PURE__ */ jsxs35("div", { className: "flex flex-col items-center gap-3 animate-in fade-in-0 zoom-in-95 duration-300", children: [
           /* @__PURE__ */ jsx45(SearchX2, { className: "h-10 w-10 opacity-30 text-muted-foreground" }),
           /* @__PURE__ */ jsxs35("div", { className: "space-y-1", children: [
             /* @__PURE__ */ jsx45("span", { className: "font-medium block", children: emptyText }),
             query && /* @__PURE__ */ jsx45("span", { className: "text-xs opacity-60", children: "Try a different search term" })
           ] }),
-          query && /* @__PURE__ */ jsxs35("button", { type: "button", onClick: () => setQuery(""), className: "text-xs text-primary hover:underline flex items-center gap-1", children: [
-            /* @__PURE__ */ jsx45(X13, { className: "w-3 h-3" }),
-            "Clear search"
-          ] })
+          query && /* @__PURE__ */ jsxs35(
+            "button",
+            {
+              type: "button",
+              onClick: () => {
+                setQuery("");
+                scrollVirtualListToStart();
+              },
+              className: "text-xs text-primary hover:underline flex items-center gap-1",
+              children: [
+                /* @__PURE__ */ jsx45(X13, { 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__ */ jsxs35(
@@ -17732,8 +17981,8 @@ function CategoryTreeSelect(props) {
 }
 
 // src/components/ImageUpload.tsx
-import { useState as useState32, useRef as useRef21, useCallback as useCallback16 } from "react";
-import { Upload, X as X15, Image as ImageIcon, Loader2 as Loader25, Check as Check7 } from "lucide-react";
+import { useState as useState32, useRef as useRef21, useCallback as useCallback18 } from "react";
+import { Upload, X as X15, Image as ImageIcon, Loader2 as Loader24, Check as Check7 } from "lucide-react";
 import { jsx as jsx50, jsxs as jsxs40 } from "react/jsx-runtime";
 function ImageUpload({
   onUpload,
@@ -17761,7 +18010,7 @@ function ImageUpload({
     md: "w-24 h-24",
     lg: "w-32 h-32"
   };
-  const handleDragOver = useCallback16(
+  const handleDragOver = useCallback18(
     (e) => {
       e.preventDefault();
       if (!disabled) {
@@ -17770,11 +18019,11 @@ function ImageUpload({
     },
     [disabled]
   );
-  const handleDragLeave = useCallback16((e) => {
+  const handleDragLeave = useCallback18((e) => {
     e.preventDefault();
     setIsDragging(false);
   }, []);
-  const handleFiles = useCallback16(
+  const handleFiles = useCallback18(
     async (files) => {
       if (files.length === 0) return;
       const validFiles = files.filter((file) => {
@@ -17841,7 +18090,7 @@ function ImageUpload({
     },
     [maxSize, addToast, onUpload]
   );
-  const handleDrop = useCallback16(
+  const handleDrop = useCallback18(
     (e) => {
       e.preventDefault();
       setIsDragging(false);
@@ -17851,7 +18100,7 @@ function ImageUpload({
     },
     [disabled, handleFiles]
   );
-  const handleFileSelect = useCallback16(
+  const handleFileSelect = useCallback18(
     (e) => {
       const files = Array.from(e.target.files || []);
       handleFiles(files);
@@ -17883,7 +18132,7 @@ function ImageUpload({
         onDrop: handleDrop,
         children: [
           uploading && /* @__PURE__ */ jsx50("div", { className: "absolute inset-0 bg-background/80 flex items-center justify-center rounded-2xl md:rounded-3xl", children: /* @__PURE__ */ jsxs40("div", { className: "flex items-center gap-3", children: [
-            /* @__PURE__ */ jsx50(Loader25, { className: "w-6 h-6 animate-spin text-primary" }),
+            /* @__PURE__ */ jsx50(Loader24, { className: "w-6 h-6 animate-spin text-primary" }),
             /* @__PURE__ */ jsx50("span", { className: "text-sm font-medium", children: "Uploading..." })
           ] }) }),
           /* @__PURE__ */ jsxs40("div", { className: "space-y-4", children: [
@@ -17967,11 +18216,11 @@ import {
   FileSpreadsheet,
   FileText,
   FileVideo,
-  Loader2 as Loader26,
+  Loader2 as Loader25,
   Trash2,
   Upload as Upload2
 } from "lucide-react";
-import { useCallback as useCallback17, useMemo as useMemo20, useRef as useRef22, useState as useState33 } from "react";
+import { useCallback as useCallback19, useMemo as useMemo20, useRef as useRef22, useState as useState33 } from "react";
 import { Fragment as Fragment16, jsx as jsx51, jsxs as jsxs41 } from "react/jsx-runtime";
 var formatFileSize = (bytes) => {
   if (bytes === 0) return "0 Bytes";
@@ -18116,7 +18365,7 @@ function FileUpload({
     []
   );
   const currentSize = sizeConfig[size];
-  const handleDragOver = useCallback17(
+  const handleDragOver = useCallback19(
     (e) => {
       e.preventDefault();
       e.stopPropagation();
@@ -18126,12 +18375,12 @@ function FileUpload({
     },
     [disabled]
   );
-  const handleDragLeave = useCallback17((e) => {
+  const handleDragLeave = useCallback19((e) => {
     e.preventDefault();
     e.stopPropagation();
     setIsDragging(false);
   }, []);
-  const processFiles = useCallback17(
+  const processFiles = useCallback19(
     async (fileList) => {
       if (fileList.length === 0) return;
       const remainingSlots = maxFiles - files.length;
@@ -18204,7 +18453,7 @@ function FileUpload({
     },
     [files, maxFiles, maxSize, uploadHandler, onUpload, onChange, addToast, t]
   );
-  const handleDrop = useCallback17(
+  const handleDrop = useCallback19(
     (e) => {
       e.preventDefault();
       e.stopPropagation();
@@ -18215,7 +18464,7 @@ function FileUpload({
     },
     [disabled, processFiles]
   );
-  const handleFileSelect = useCallback17(
+  const handleFileSelect = useCallback19(
     (e) => {
       const selectedFiles = Array.from(e.target.files || []);
       processFiles(selectedFiles);
@@ -18225,7 +18474,7 @@ function FileUpload({
     },
     [processFiles]
   );
-  const handleRemove = useCallback17(
+  const handleRemove = useCallback19(
     (fileId) => {
       setFiles((prev) => {
         const fileToRemove = prev.find((f) => f.id === fileId);
@@ -18243,7 +18492,7 @@ function FileUpload({
   const handleBrowseClick = () => {
     fileInputRef.current?.click();
   };
-  const handleRetry = useCallback17(
+  const handleRetry = useCallback19(
     (fileEntry) => {
       if (!uploadHandler || !fileEntry.file) return;
       processFiles([fileEntry.file]);
@@ -18282,7 +18531,7 @@ function FileUpload({
             /* @__PURE__ */ jsxs41("div", { className: "flex items-center gap-2", children: [
               /* @__PURE__ */ jsx51("span", { className: cn("text-muted-foreground", size === "lg" ? "text-sm" : "text-xs"), children: file.formattedSize }),
               file.status === "uploading" && /* @__PURE__ */ jsxs41("span", { className: "flex items-center gap-1 text-primary text-xs", children: [
-                /* @__PURE__ */ jsx51(Loader26, { className: "w-3 h-3 animate-spin" }),
+                /* @__PURE__ */ jsx51(Loader25, { className: "w-3 h-3 animate-spin" }),
                 file.progress,
                 "%"
               ] }),
@@ -25924,7 +26173,7 @@ var EditorToolbar = ({
 };
 
 // src/components/UEditor/menus.tsx
-import { useCallback as useCallback20, useEffect as useEffect34, useMemo as useMemo23, useRef as useRef31, useState as useState45 } from "react";
+import { useCallback as useCallback22, useEffect as useEffect34, useMemo as useMemo23, useRef as useRef31, useState as useState45 } from "react";
 import { createPortal as createPortal8 } from "react-dom";
 import {
   AlignCenter as AlignCenter2,
@@ -26216,7 +26465,7 @@ var CustomBubbleMenu = ({
   const menuRef = useRef31(null);
   const keepOpenRef = useRef31(false);
   const showTimeoutRef = useRef31(null);
-  const setKeepOpen = useCallback20((next) => {
+  const setKeepOpen = useCallback22((next) => {
     keepOpenRef.current = next;
     if (next) setIsVisible(true);
   }, []);