selective-ui 1.1.6 → 1.2.1

package/dist/selective-ui.esm.js

@@ -1,4 +1,4 @@
-/*! Selective UI v1.1.6 | MIT License */
+/*! Selective UI v1.2.1 | MIT License */
 /**
  * @class
  */
@@ -6,6 +6,7 @@ class iStorage {
     constructor() {
         this.defaultConfig = {
             showPanel: true,
+            virtualScroll: true,
             accessoryStyle: "top",
             multiple: false,
             minWidth: "50px",
@@ -402,8 +403,8 @@ class Libs {
      * matching element properties or data-* attributes when present.
      *
      * @param {HTMLElement} element - Source element providing overrides.
-     * @param {object} options - Default configuration to be merged.
-     * @returns {object} - Final configuration after element overrides.
+     * @param {SelectiveOptions} options - Default configuration to be merged.
+     * @returns {SelectiveOptions} - Final configuration after element overrides.
      */
     static buildConfig(element, options) {
         const myOptions = this.jsCopyObject(options);
@@ -497,7 +498,7 @@ class Libs {
      * Sets or updates the binder map entry for a given element.
      *
      * @param {HTMLElement} item - Element key to associate with the binder map.
-     * @param {unknown} bindMap - Value to store in the binder map.
+     * @param {BinderMap} bindMap - Value to store in the binder map.
      */
     static setBinderMap(item, bindMap) {
         this.iStorage.bindedMap.set(item, bindMap);
@@ -524,7 +525,7 @@ class Libs {
      * Sets or updates the unbinder map entry for a given element.
      *
      * @param {HTMLElement} item - Element key to associate with the unbinder map.
-     * @param {unknown} bindMap - Value to store in the unbinder map.
+     * @param {BinderMap} bindMap - Value to store in the unbinder map.
      */
     static setUnbinderMap(item, bindMap) {
         this.iStorage.unbindedMap.set(item, bindMap);
@@ -629,7 +630,7 @@ class Libs {
                 const group = child;
                 result.push(group);
                 Array.from(group.children).forEach((option) => {
-                    option.__parentGroup = group;
+                    option["__parentGroup"] = group;
                     result.push(option);
                 });
             }
@@ -1269,6 +1270,11 @@ class Popup {
         this._optionsContainer = null;
         this._scrollListener = null;
         this._hideLoadHandle = null;
+        this.virtualScrollConfig = {
+            estimateItemHeight: 36,
+            overscan: 8,
+            dynamicHeights: true
+        };
         this._modelManager = modelManager;
         if (select && options) {
             this.init(select, options);
@@ -1313,8 +1319,16 @@ class Popup {
         this._optionsContainer = nodeMounted.tags.OptionsContainer;
         this._parent = Libs.getBinderMap(select);
         this.options = options;
+        const recyclerViewOpt = options.virtualScroll
+            ? {
+                scrollEl: this.node,
+                estimateItemHeight: this.virtualScrollConfig.estimateItemHeight,
+                overscan: this.virtualScrollConfig.overscan,
+                dynamicHeights: this.virtualScrollConfig.dynamicHeights
+            }
+            : {};
         // Load ModelManager resources into container
-        this._modelManager.load(this._optionsContainer, { isMultiple: options.multiple });
+        this._modelManager.load(this._optionsContainer, { isMultiple: options.multiple }, recyclerViewOpt);
         const MMResources = this._modelManager.getResources();
         this.optionAdapter = MMResources.adapter;
         this.recyclerView = MMResources.recyclerView;
@@ -1463,6 +1477,8 @@ class Popup {
                 };
                 this._resizeObser.connect(this._parent.container.tags.ViewPanel);
                 callback?.();
+                const rv = this.recyclerView;
+                rv?.resume?.();
             },
         });
     }
@@ -1473,6 +1489,8 @@ class Popup {
     close(callback = null) {
         if (!this.isCreated || !this.options || !this._resizeObser || !this._effSvc)
             return;
+        const rv = this.recyclerView;
+        rv?.suspend?.();
         this._resizeObser.disconnect();
         this._effSvc.collapse({
             duration: this.options.animationtime,
@@ -1751,6 +1769,7 @@ class SearchBox {
                 isControlKey = true;
                 this.onEsc?.();
             }
+            e.stopPropagation();
         });
         inputEl.addEventListener("input", () => {
             if (isControlKey)
@@ -2060,8 +2079,7 @@ class EffectorImpl {
     resize(config) {
         if (!this.element)
             return this;
-        if (this._resizeTimeout)
-            clearTimeout(this._resizeTimeout);
+        this.cancel();
         const { duration = 200, width, left, top, maxHeight, realHeight, position = "bottom", animate = true, onComplete, } = config;
         const currentPosition = this.element.classList.contains("position-top") ? "top" : "bottom";
         const isPositionChanged = currentPosition !== position;
@@ -2071,7 +2089,7 @@ class EffectorImpl {
         if (isPositionChanged) {
             this.element.style.transition = `top ${duration}ms ease-out, height ${duration}ms ease-out, max-height ${duration}ms ease-out;`;
         }
-        requestAnimationFrame(() => {
+        setTimeout(() => {
             const styles = {
                 width: `${width}px`,
                 left: `${left}px`,
@@ -2087,14 +2105,14 @@ class EffectorImpl {
             else {
                 this._resizeTimeout = setTimeout(() => {
                     if (this.element?.style) {
-                        this.element.style.transition = "none";
+                        this.element.style.transition = null;
                     }
                 }, duration);
             }
             Object.assign(this.element.style, styles);
             if (animate && (isPositionChanged || heightDiff > 1)) {
                 this._resizeTimeout = setTimeout(() => {
-                    this.element.style.transition = "none";
+                    this.element.style.transition = null;
                     if (isPositionChanged)
                         delete this.element.style.transition;
                     onComplete?.();
@@ -2105,7 +2123,7 @@ class EffectorImpl {
                     delete this.element.style.transition;
                 onComplete?.();
             }
-        });
+        }, 20);
         return this;
     }
     /**
@@ -2140,11 +2158,11 @@ class Model {
      * @param {TView|null} [view=null] - The associated view responsible for rendering the model.
      */
     constructor(options, targetElement = null, view = null) {
-        /** @type {TTarget | null} */
         this.targetElement = null;
         this.view = null;
         this.position = -1;
         this.isInit = false;
+        this.isRemoved = false;
         this.options = options;
         this.targetElement = targetElement;
         this.view = view;
@@ -2158,11 +2176,26 @@ class Model {
         this.targetElement = targetElement;
         this.onTargetChanged();
     }
+    /**
+     * Cleans up references and invokes the removal hook when the model is no longer needed.
+     */
+    remove() {
+        this.targetElement = null;
+        this.view?.getView()?.remove?.();
+        this.view = null;
+        this.isRemoved = true;
+        this.onRemove();
+    }
     /**
      * Hook invoked whenever the target element changes.
      * Override in subclasses to react to attribute/content updates (e.g., text, disabled state).
      */
     onTargetChanged() { }
+    /**
+     * Hook invoked whenever the target element is removed.
+     * Override in subclasses to react to removal of the element.
+     */
+    onRemove() { }
 }
 
 /**
@@ -2285,17 +2318,28 @@ class GroupModel extends Model {
 }
 
 /**
- * @extends {Model<HTMLOptionElement, OptionViewTags, OptionView>}
+ * @extends {Model<HTMLOptionElement, OptionViewTags, OptionView, SelectiveOptions>}
  */
 class OptionModel extends Model {
-    constructor() {
-        super(...arguments);
+    /**
+     * Constructs a Model instance with configuration options and optional bindings to a target element and view.
+     * Stores references for later updates and rendering.
+     *
+     * @param {SelectiveOptions} options - Configuration options for the model.
+     * @param {HTMLOptionElement|null} [targetElement=null] - The underlying element (e.g., <option> or group node).
+     * @param {OptionView|null} [view=null] - The associated view responsible for rendering the model.
+     */
+    constructor(options, targetElement = null, view = null) {
+        super(options, targetElement, view);
         this._privOnSelected = [];
         this._privOnInternalSelected = [];
         this._privOnVisibilityChanged = [];
         this._visible = true;
         this._highlighted = false;
         this.group = null;
+        (async () => {
+            this.textToFind = Libs.string2normalize(this.textContent.toLowerCase());
+        })();
     }
     /**
      * Returns the image source from dataset (imgsrc or image), or an empty string if absent.
@@ -2469,6 +2513,7 @@ class OptionModel extends Model {
      * and synchronizes initial selected state to the view.
      */
     onTargetChanged() {
+        this.textToFind = Libs.string2normalize(this.textContent.toLowerCase());
         if (!this.view)
             return;
         const labelContent = this.view.view.tags.LabelContent;
@@ -2612,7 +2657,7 @@ class ModelManager {
             // Adapter expects TModel[], but this manager's list is GroupModel|OptionModel.
             this._privAdapterHandle.syncFromSource(this._privModelList);
         }
-        this.refresh();
+        this.refresh(false);
     }
     /**
      * Requests a view refresh if an adapter has been initialized,
@@ -2621,7 +2666,7 @@ class ModelManager {
     notify() {
         if (!this._privAdapterHandle)
             return;
-        this.refresh();
+        this.refresh(false);
     }
     /**
      * Initializes adapter and recycler view instances, attaches them to a container element,
@@ -2631,8 +2676,8 @@ class ModelManager {
         this._privAdapterHandle = new this._privAdapter(this._privModelList);
         Object.assign(this._privAdapterHandle, adapterOpt);
         this._privRecyclerViewHandle = new this._privRecyclerView(viewElement);
-        this._privRecyclerViewHandle.setAdapter(this._privAdapterHandle);
         Object.assign(this._privRecyclerViewHandle, recyclerViewOpt);
+        this._privRecyclerViewHandle.setAdapter(this._privAdapterHandle);
     }
     /**
      * Diffs existing models against new <optgroup>/<option> data to update in place:
@@ -2713,18 +2758,21 @@ class ModelManager {
                 position++;
             }
         });
+        let isUpdate = true;
         oldGroupMap.forEach((removedGroup) => {
-            removedGroup.view?.getView?.()?.remove?.();
+            isUpdate = false;
+            removedGroup.remove();
         });
         oldOptionMap.forEach((removedOption) => {
-            removedOption.view?.getView?.()?.remove?.();
+            isUpdate = false;
+            removedOption.remove();
         });
         this._privModelList = newModels;
         if (this._privAdapterHandle) {
             this._privAdapterHandle.updateData(this._privModelList);
         }
         this.onUpdated();
-        this.refresh();
+        this.refresh(isUpdate);
     }
     /**
      * Hook invoked after the manager completes an update or refresh cycle.
@@ -2743,11 +2791,13 @@ class ModelManager {
     /**
      * Re-renders the recycler view if present and invokes the post-refresh hook.
      * No-op if the recycler view is not initialized.
+     *
+     * @param isUpdate - Indicates if this refresh is due to an update operation.
      */
-    refresh() {
+    refresh(isUpdate) {
         if (!this._privRecyclerViewHandle)
             return;
-        this._privRecyclerViewHandle.refresh();
+        this._privRecyclerViewHandle.refresh(isUpdate);
         this.onUpdated();
     }
     /**
@@ -2840,8 +2890,10 @@ class RecyclerView {
     /**
      * Forces a re-render of the current adapter state into the container.
      * Useful when visual updates are required without changing the data.
+     *
+     * @param isUpdate - Indicates if this refresh is due to an update operation.
      */
-    refresh() {
+    refresh(isUpdate) {
         this.render();
     }
 }
@@ -3159,9 +3211,7 @@ class SearchController {
         }
         let hasVisibleItems = false;
         flatOptions.forEach((opt) => {
-            const text = String(opt.textContent ?? opt.text ?? "").toLowerCase();
-            const textNA = Libs.string2normalize(text);
-            const isVisible = lower === "" || text.includes(lower) || textNA.includes(lowerNA);
+            const isVisible = lower === "" || opt.textToFind.includes(lowerNA);
             opt.visible = isVisible;
             if (isVisible)
                 hasVisibleItems = true;
@@ -3585,11 +3635,11 @@ class Adapter {
      */
     onViewHolder(item, viewer, position) {
         const v = viewer;
-        if (!item.isInit) {
-            v?.render?.();
+        if (item.isInit) {
+            v?.update?.();
         }
         else {
-            v?.update?.();
+            v?.render?.();
         }
     }
     /**
@@ -4131,6 +4181,19 @@ class MixedAdapter extends Adapter {
         this.groups = [];
         this.flatOptions = [];
         this._buildFlatStructure();
+        Libs.callbackScheduler.on(`sche_vis_${this.adapterKey}`, () => {
+            const visibleCount = this.flatOptions.filter((item) => item.visible).length;
+            const totalCount = this.flatOptions.length;
+            this._visibilityChangedCallbacks.forEach((callback) => {
+                callback({
+                    visibleCount,
+                    totalCount,
+                    hasVisible: visibleCount > 0,
+                    isEmpty: totalCount === 0,
+                });
+            });
+            Libs.callbackScheduler.run(`sche_vis_proxy_${this.adapterKey}`);
+        }, { debounce: 10 });
     }
     /**
      * Build flat list of all options for navigation
@@ -4366,16 +4429,7 @@ class MixedAdapter extends Adapter {
      * Computes visible and total counts, then emits aggregated state.
      */
     _notifyVisibilityChanged() {
-        const visibleCount = this.flatOptions.filter((item) => item.visible).length;
-        const totalCount = this.flatOptions.length;
-        this._visibilityChangedCallbacks.forEach((callback) => {
-            callback({
-                visibleCount,
-                totalCount,
-                hasVisible: visibleCount > 0,
-                isEmpty: totalCount === 0,
-            });
-        });
+        Libs.callbackScheduler.run(`sche_vis_${this.adapterKey}`);
     }
     /**
      * Computes and returns current visibility statistics for options.
@@ -4456,14 +4510,18 @@ class MixedAdapter extends Adapter {
         }
         for (let i = index; i < this.flatOptions.length; i++) {
             const item = this.flatOptions[i];
-            if (!item.visible)
+            if (!item?.visible)
                 continue;
             item.highlighted = true;
             this._currentHighlightIndex = i;
             if (isScrollToView) {
                 const el = item.view?.getView?.();
-                if (el)
-                    el.scrollIntoView({ block: "center", behavior: "smooth" });
+                if (el) {
+                    el.scrollIntoView({ block: 'center', behavior: 'smooth' });
+                }
+                else {
+                    this.recyclerView?.ensureRendered?.(i, { scrollIntoView: true });
+                }
             }
             this.onHighlightChange(i, item.view?.getView?.()?.id);
             return;
@@ -4481,6 +4539,673 @@ class MixedAdapter extends Adapter {
     onCollapsedChange(model, collapsed) { }
 }
 
+/**
+ * Fenwick tree (Binary Indexed Tree) for efficient prefix sum queries.
+ * Supports O(log n) update and query operations for cumulative item heights.
+ * Uses 1-based indexing internally for BIT operations.
+ */
+class Fenwick {
+    constructor(n = 0) {
+        this.bit = [];
+        this.n = 0;
+        this.reset(n);
+    }
+    /** Resets tree to new size, clearing all values. */
+    reset(n) {
+        this.n = n;
+        this.bit = new Array(n + 1).fill(0);
+    }
+    /** Adds delta to element at 1-based index i. */
+    add(i, delta) {
+        for (let x = i; x <= this.n; x += x & -x)
+            this.bit[x] += delta;
+    }
+    /** Returns prefix sum for range [1..i]. */
+    sum(i) {
+        let s = 0;
+        for (let x = i; x > 0; x -= x & -x)
+            s += this.bit[x];
+        return s;
+    }
+    /** Returns sum in range [l..r] (1-based, inclusive). */
+    rangeSum(l, r) {
+        return r < l ? 0 : this.sum(r) - this.sum(l - 1);
+    }
+    /** Builds tree from 0-based array in O(n log n). */
+    buildFrom(arr) {
+        this.reset(arr.length);
+        arr.forEach((val, i) => this.add(i + 1, val));
+    }
+    /**
+     * Binary search to find largest index where prefix sum <= target.
+     * Returns count of items that fit within target height.
+     */
+    lowerBoundPrefix(target) {
+        let idx = 0, bitMask = 1;
+        while (bitMask << 1 <= this.n)
+            bitMask <<= 1;
+        let cur = 0;
+        for (let step = bitMask; step !== 0; step >>= 1) {
+            const next = idx + step;
+            if (next <= this.n && cur + this.bit[next] <= target) {
+                idx = next;
+                cur += this.bit[next];
+            }
+        }
+        return idx;
+    }
+}
+/**
+ * Virtual RecyclerView with efficient windowing and dynamic height support.
+ *
+ * Only renders items visible in viewport plus overscan buffer, using padding
+ * elements to simulate scroll height. Supports variable item heights with
+ * adaptive estimation and maintains scroll position during height changes.
+ *
+ * @template TItem - Model type for list items
+ * @template TAdapter - Adapter managing item views
+ */
+class VirtualRecyclerView extends RecyclerView {
+    /** Creates virtual recycler view with optional root element. */
+    constructor(viewElement = null) {
+        super(viewElement);
+        this.opts = {
+            scrollEl: undefined,
+            estimateItemHeight: 36,
+            overscan: 8,
+            dynamicHeights: true,
+            adaptiveEstimate: true,
+        };
+        this.heightCache = [];
+        this.fenwick = new Fenwick(0);
+        this.created = new Map();
+        this.firstMeasured = false;
+        this.start = 0;
+        this.end = -1;
+        this._rafId = null;
+        this._measureRaf = null;
+        this._updating = false;
+        this._suppressResize = false;
+        this._lastRenderCount = 0;
+        this._suspended = false;
+        this._resumeResizeAfter = false;
+        this._stickyCacheTick = 0;
+        this._stickyCacheVal = 0;
+        this.measuredSum = 0;
+        this.measuredCount = 0;
+    }
+    /** Updates virtualization settings (overscan, heights, etc). */
+    configure(opts) {
+        this.opts = { ...this.opts, ...opts };
+    }
+    /**
+     * Binds adapter and initializes virtualization scaffold.
+     * Removes previous adapter if exists, sets up scroll listeners and DOM structure.
+     */
+    setAdapter(adapter) {
+        if (this.adapter)
+            this.dispose();
+        super.setAdapter(adapter);
+        adapter.recyclerView = this;
+        if (!this.viewElement)
+            return;
+        this.viewElement.replaceChildren();
+        const nodeMounted = Libs.mountNode({
+            PadTop: { tag: { node: "div", classList: "selective-ui-virtual-pad-top" } },
+            ItemsHost: { tag: { node: "div", classList: "selective-ui-virtual-items" } },
+            PadBottom: { tag: { node: "div", classList: "selective-ui-virtual-pad-bottom" } },
+        }, this.viewElement);
+        this.PadTop = nodeMounted.PadTop;
+        this.ItemsHost = nodeMounted.ItemsHost;
+        this.PadBottom = nodeMounted.PadBottom;
+        this.scrollEl = this.opts.scrollEl
+            ?? this.viewElement.closest(".selective-ui-popup")
+            ?? this.viewElement.parentElement;
+        if (!this.scrollEl)
+            throw new Error("VirtualRecyclerView: scrollEl not found");
+        this._boundOnScroll = this.onScroll.bind(this);
+        this.scrollEl.addEventListener("scroll", this._boundOnScroll, { passive: true });
+        this.refresh(false);
+        this.attachResizeObserverOnce();
+        adapter?.onVisibilityChanged?.(() => this.refreshItem());
+    }
+    /**
+     * Pauses scroll/resize processing to prevent updates during batch operations.
+     * Cancels pending frames and disconnects observers.
+     */
+    suspend() {
+        this._suspended = true;
+        this.cancelFrames();
+        if (this.scrollEl && this._boundOnScroll) {
+            this.scrollEl.removeEventListener("scroll", this._boundOnScroll);
+        }
+        if (this.resizeObs) {
+            this.resizeObs.disconnect();
+            this._resumeResizeAfter = true;
+        }
+    }
+    /**
+     * Resumes scroll/resize processing after suspension.
+     * Re-attaches listeners and schedules window update.
+     */
+    resume() {
+        this._suspended = false;
+        if (this.scrollEl && this._boundOnScroll) {
+            this.scrollEl.addEventListener("scroll", this._boundOnScroll, { passive: true });
+        }
+        if (this._resumeResizeAfter) {
+            this.attachResizeObserverOnce();
+            this._resumeResizeAfter = false;
+        }
+        this.scheduleUpdateWindow();
+    }
+    /**
+     * Rebuilds internal state and schedules render update.
+     * Probes initial item height on first run, rebuilds Fenwick tree.
+     *
+     * @param isUpdate - True if called from data update, false on initial setup
+     */
+    refresh(isUpdate) {
+        if (!this.adapter || !this.viewElement)
+            return;
+        if (!isUpdate)
+            this.refreshItem();
+        const count = this.adapter.itemCount();
+        this._lastRenderCount = count;
+        if (count === 0) {
+            this.resetState();
+            return;
+        }
+        this.heightCache.length = count;
+        if (!this.firstMeasured) {
+            this.probeInitialHeight();
+            this.firstMeasured = true;
+        }
+        this.rebuildFenwick(count);
+        this.scheduleUpdateWindow();
+    }
+    /**
+     * Ensures item at index is rendered and optionally scrolls into view.
+     * Useful for programmatic navigation to specific items.
+     */
+    ensureRendered(index, opt) {
+        this.mountRange(index, index);
+        if (opt?.scrollIntoView)
+            this.scrollToIndex(index);
+    }
+    /**
+     * Scrolls container to make item at index visible.
+     * Calculates target scroll position accounting for container offset.
+     */
+    scrollToIndex(index) {
+        const count = this.adapter?.itemCount?.() ?? 0;
+        if (count <= 0)
+            return;
+        const topInContainer = this.offsetTopOf(index);
+        const containerTop = this.containerTopInScroll();
+        const target = containerTop + topInContainer;
+        const maxScroll = Math.max(0, this.scrollEl.scrollHeight - this.scrollEl.clientHeight);
+        this.scrollEl.scrollTop = Math.min(Math.max(0, target), maxScroll);
+    }
+    /**
+     * Cleans up all resources: listeners, observers, DOM elements.
+     * Call before removing component to prevent memory leaks.
+     */
+    dispose() {
+        this.cancelFrames();
+        if (this.scrollEl && this._boundOnScroll) {
+            this.scrollEl.removeEventListener("scroll", this._boundOnScroll);
+        }
+        this.resizeObs?.disconnect();
+        this.created.forEach(el => el.remove());
+        this.created.clear();
+    }
+    /**
+     * Hard reset after visibility changes (e.g., search/filter cleared).
+     * Rebuilds all height structures and remounts visible window.
+     * Essential for fixing padding calculations after bulk visibility changes.
+     */
+    refreshItem() {
+        if (!this.adapter)
+            return;
+        const count = this.adapter.itemCount();
+        if (count <= 0)
+            return;
+        this.suspend();
+        this.resetState();
+        this.cleanupInvisibleItems();
+        this.recomputeMeasuredStats(count);
+        this.rebuildFenwick(count);
+        this.start = 0;
+        this.end = -1;
+        this.resume();
+    }
+    /** Cancels all pending animation frames. */
+    cancelFrames() {
+        if (this._rafId != null) {
+            cancelAnimationFrame(this._rafId);
+            this._rafId = null;
+        }
+        if (this._measureRaf != null) {
+            cancelAnimationFrame(this._measureRaf);
+            this._measureRaf = null;
+        }
+    }
+    /** Resets all internal state: DOM, caches, measurements. */
+    resetState() {
+        this.created.forEach(el => el.remove());
+        this.created.clear();
+        this.heightCache = [];
+        this.fenwick.reset(0);
+        this.PadTop.style.height = "0px";
+        this.PadBottom.style.height = "0px";
+        this.firstMeasured = false;
+        this.measuredSum = 0;
+        this.measuredCount = 0;
+    }
+    /**
+     * Measures first item to set initial height estimate.
+     * Removes probe element if dynamic heights disabled.
+     */
+    probeInitialHeight() {
+        const probe = 0;
+        this.mountIndexOnce(probe);
+        const el = this.created.get(probe);
+        if (!el)
+            return;
+        const h = this.measureOuterHeight(el);
+        if (!isNaN(h))
+            this.opts.estimateItemHeight = h;
+        if (!this.opts.dynamicHeights) {
+            el.remove();
+            this.created.delete(probe);
+            const item = this.adapter.items[probe];
+            if (item) {
+                item.isInit = false;
+                item.view = null;
+            }
+        }
+    }
+    /**
+     * Checks if item is visible (not filtered/hidden).
+     * Defaults to visible if property undefined.
+     */
+    isIndexVisible(index) {
+        const item = this.adapter?.items?.[index];
+        return item?.visible ?? true;
+    }
+    /**
+     * Finds next visible item index starting from given index.
+     * Returns -1 if no visible items found.
+     */
+    nextVisibleFrom(index, count) {
+        for (let i = Math.max(0, index); i < count; i++) {
+            if (this.isIndexVisible(i))
+                return i;
+        }
+        return -1;
+    }
+    /**
+     * Recalculates total measured height and count from cache.
+     * Only counts visible items for adaptive estimation.
+     */
+    recomputeMeasuredStats(count) {
+        this.measuredSum = 0;
+        this.measuredCount = 0;
+        for (let i = 0; i < count; i++) {
+            if (!this.isIndexVisible(i))
+                continue;
+            const h = this.heightCache[i];
+            if (h != null) {
+                this.measuredSum += h;
+                this.measuredCount++;
+            }
+        }
+    }
+    /** Returns view container's top offset relative to scroll container. */
+    containerTopInScroll() {
+        const a = this.viewElement.getBoundingClientRect();
+        const b = this.scrollEl.getBoundingClientRect();
+        return a.top - b.top + this.scrollEl.scrollTop;
+    }
+    /**
+     * Returns sticky header height with 16ms cache to avoid DOM thrashing.
+     * Used to adjust viewport calculations.
+     */
+    stickyTopHeight() {
+        const now = performance.now();
+        if (now - this._stickyCacheTick < 16)
+            return this._stickyCacheVal;
+        const sticky = this.scrollEl.querySelector(".selective-ui-option-handle:not(.hide)");
+        this._stickyCacheVal = sticky?.offsetHeight ?? 0;
+        this._stickyCacheTick = now;
+        return this._stickyCacheVal;
+    }
+    /** Schedules window update on next frame if not already scheduled. */
+    scheduleUpdateWindow() {
+        if (this._rafId != null || this._suspended)
+            return;
+        this._rafId = requestAnimationFrame(() => {
+            this._rafId = null;
+            this.updateWindowInternal();
+        });
+    }
+    /**
+     * Measures element's total height including margins.
+     * Used for accurate item height tracking.
+     */
+    measureOuterHeight(el) {
+        const rect = el.getBoundingClientRect();
+        const style = getComputedStyle(el);
+        const mt = parseFloat(style.marginTop) || 0;
+        const mb = parseFloat(style.marginBottom) || 0;
+        return Math.max(1, rect.height + mt + mb);
+    }
+    /**
+     * Returns height estimate for unmeasured items.
+     * Uses adaptive average if enabled, otherwise fixed estimate.
+     */
+    getEstimate() {
+        if (this.opts.adaptiveEstimate && this.measuredCount > 0) {
+            return Math.max(1, this.measuredSum / this.measuredCount);
+        }
+        return this.opts.estimateItemHeight;
+    }
+    /**
+     * Rebuilds Fenwick tree with current heights and estimates.
+     * Invisible items get 0 height, others use cached or estimated height.
+     */
+    rebuildFenwick(count) {
+        const est = this.getEstimate();
+        const arr = Array.from({ length: count }, (_, i) => this.isIndexVisible(i) ? (this.heightCache[i] ?? est) : 0);
+        this.fenwick.buildFrom(arr);
+    }
+    /**
+     * Updates cached height at index and applies delta to Fenwick tree.
+     * Updates running average for adaptive estimation.
+     *
+     * @returns True if height changed beyond epsilon threshold
+     */
+    updateHeightAt(index, newH) {
+        if (!this.isIndexVisible(index))
+            return false;
+        const est = this.getEstimate();
+        const oldH = this.heightCache[index] ?? est;
+        if (Math.abs(newH - oldH) <= VirtualRecyclerView.EPS)
+            return false;
+        const prevMeasured = this.heightCache[index];
+        if (prevMeasured == null) {
+            this.measuredSum += newH;
+            this.measuredCount++;
+        }
+        else {
+            this.measuredSum += newH - prevMeasured;
+        }
+        this.heightCache[index] = newH;
+        this.fenwick.add(index + 1, newH - oldH);
+        return true;
+    }
+    /**
+     * Finds first visible item at or after scroll offset.
+     * Uses Fenwick binary search then adjusts for visibility.
+     */
+    findFirstVisibleIndex(stRel, count) {
+        const k = this.fenwick.lowerBoundPrefix(Math.max(0, stRel));
+        const raw = Math.min(count - 1, k);
+        const v = this.nextVisibleFrom(raw, count);
+        return v === -1 ? Math.max(0, raw) : v;
+    }
+    /**
+     * Inserts element into DOM maintaining index order.
+     * Tries adjacent siblings first, then scans for insertion point.
+     */
+    insertIntoHostByIndex(index, el) {
+        el.setAttribute(VirtualRecyclerView.ATTR_INDEX, String(index));
+        const prev = this.created.get(index - 1);
+        if (prev?.parentElement === this.ItemsHost) {
+            prev.after(el);
+            return;
+        }
+        const next = this.created.get(index + 1);
+        if (next?.parentElement === this.ItemsHost) {
+            this.ItemsHost.insertBefore(el, next);
+            return;
+        }
+        const children = Array.from(this.ItemsHost.children);
+        for (const child of children) {
+            const v = child.getAttribute(VirtualRecyclerView.ATTR_INDEX);
+            if (v && Number(v) > index) {
+                this.ItemsHost.insertBefore(el, child);
+                return;
+            }
+        }
+        this.ItemsHost.appendChild(el);
+    }
+    /**
+     * Ensures element is in correct DOM position for its index.
+     * Reinserts if siblings indicate wrong position.
+     */
+    ensureDomOrder(index, el) {
+        if (el.parentElement !== this.ItemsHost) {
+            this.insertIntoHostByIndex(index, el);
+            return;
+        }
+        el.setAttribute(VirtualRecyclerView.ATTR_INDEX, String(index));
+        const prev = el.previousElementSibling;
+        const next = el.nextElementSibling;
+        const needsReorder = (prev && Number(prev.getAttribute(VirtualRecyclerView.ATTR_INDEX)) > index) ||
+            (next && Number(next.getAttribute(VirtualRecyclerView.ATTR_INDEX)) < index);
+        if (needsReorder) {
+            el.remove();
+            this.insertIntoHostByIndex(index, el);
+        }
+    }
+    /**
+     * Attaches ResizeObserver to measure items when they resize.
+     * Singleton pattern - only creates once per instance.
+     */
+    attachResizeObserverOnce() {
+        if (this.resizeObs)
+            return;
+        this.resizeObs = new ResizeObserver(() => {
+            if (this._suppressResize || this._suspended || !this.adapter || this._measureRaf != null)
+                return;
+            this._measureRaf = requestAnimationFrame(() => {
+                this._measureRaf = null;
+                this.measureVisibleAndUpdate();
+            });
+        });
+        this.resizeObs.observe(this.ItemsHost);
+    }
+    /**
+     * Measures all currently rendered items and updates height cache.
+     * Triggers window update if any heights changed.
+     */
+    measureVisibleAndUpdate() {
+        if (!this.adapter)
+            return;
+        const count = this.adapter.itemCount();
+        if (count <= 0)
+            return;
+        let changed = false;
+        for (let i = this.start; i <= this.end; i++) {
+            if (!this.isIndexVisible(i))
+                continue;
+            const item = this.adapter.items[i];
+            const el = item?.view?.getView?.();
+            if (!el)
+                continue;
+            const newH = this.measureOuterHeight(el);
+            if (this.updateHeightAt(i, newH))
+                changed = true;
+        }
+        if (changed) {
+            if (this.opts.adaptiveEstimate)
+                this.rebuildFenwick(count);
+            this.scheduleUpdateWindow();
+        }
+    }
+    /** Scroll event handler - schedules render update. */
+    onScroll() {
+        this.scheduleUpdateWindow();
+    }
+    /**
+     * Core rendering logic - calculates and updates visible window.
+     *
+     * 1. Calculates viewport bounds accounting for scroll and sticky headers
+     * 2. Uses anchor item to prevent scroll jumping during height changes
+     * 3. Determines start/end indices with overscan buffer
+     * 4. Mounts/unmounts items as needed
+     * 5. Measures visible items if dynamic heights enabled
+     * 6. Updates padding elements to maintain total scroll height
+     * 7. Adjusts scroll position to maintain anchor item position
+     */
+    updateWindowInternal() {
+        if (this._updating || this._suspended)
+            return;
+        this._updating = true;
+        try {
+            if (!this.adapter)
+                return;
+            const count = this.adapter.itemCount();
+            if (count <= 0)
+                return;
+            if (this._lastRenderCount !== count) {
+                this._lastRenderCount = count;
+                this.heightCache.length = count;
+                this.rebuildFenwick(count);
+            }
+            const containerTop = this.containerTopInScroll();
+            const stRel = Math.max(0, this.scrollEl.scrollTop - containerTop);
+            const stickyH = this.stickyTopHeight();
+            const vhEff = Math.max(0, this.scrollEl.clientHeight - stickyH);
+            const anchorIndex = this.findFirstVisibleIndex(stRel, count);
+            const anchorTop = this.offsetTopOf(anchorIndex);
+            const anchorDelta = containerTop + anchorTop - this.scrollEl.scrollTop;
+            const firstVis = this.findFirstVisibleIndex(stRel, count);
+            if (firstVis === -1) {
+                this.resetState();
+                return;
+            }
+            const est = this.getEstimate();
+            const overscanPx = this.opts.overscan * est;
+            let startIndex = this.nextVisibleFrom(Math.min(count - 1, this.fenwick.lowerBoundPrefix(Math.max(0, stRel - overscanPx))), count) ?? firstVis;
+            let endIndex = Math.min(count - 1, this.fenwick.lowerBoundPrefix(stRel + vhEff + overscanPx));
+            if (startIndex === this.start && endIndex === this.end)
+                return;
+            this.start = startIndex;
+            this.end = endIndex;
+            this._suppressResize = true;
+            try {
+                this.mountRange(this.start, this.end);
+                this.unmountOutside(this.start, this.end);
+                if (this.opts.dynamicHeights)
+                    this.measureVisibleAndUpdate();
+                const topPx = this.offsetTopOf(this.start);
+                const windowPx = this.windowHeight(this.start, this.end);
+                const total = this.totalHeight(count);
+                const bottomPx = Math.max(0, total - topPx - windowPx);
+                this.PadTop.style.height = `${topPx}px`;
+                this.PadBottom.style.height = `${bottomPx}px`;
+            }
+            finally {
+                this._suppressResize = false;
+            }
+            const anchorTopNew = this.offsetTopOf(anchorIndex);
+            const targetScroll = this.containerTopInScroll() + anchorTopNew - anchorDelta;
+            const maxScroll = Math.max(0, this.scrollEl.scrollHeight - this.scrollEl.clientHeight);
+            const clamped = Math.min(Math.max(0, targetScroll), maxScroll);
+            if (Math.abs(this.scrollEl.scrollTop - clamped) > 0.5) {
+                this.scrollEl.scrollTop = clamped;
+            }
+        }
+        finally {
+            this._updating = false;
+        }
+    }
+    /** Mounts all items in inclusive range [start..end]. */
+    mountRange(start, end) {
+        for (let i = start; i <= end; i++)
+            this.mountIndexOnce(i);
+    }
+    /**
+     * Mounts single item, reusing existing element if available.
+     * Creates view holder on first mount, rebinds on subsequent renders.
+     */
+    mountIndexOnce(index) {
+        if (!this.isIndexVisible(index)) {
+            const existing = this.created.get(index);
+            if (existing?.parentElement === this.ItemsHost)
+                existing.remove();
+            this.created.delete(index);
+            return;
+        }
+        const item = this.adapter.items[index];
+        if (!item)
+            return;
+        const existing = this.created.get(index);
+        if (existing) {
+            if (!item?.view) {
+                existing.remove();
+                this.created.delete(index);
+            }
+            else {
+                this.ensureDomOrder(index, existing);
+                this.adapter.onViewHolder(item, item.view, index);
+            }
+            return;
+        }
+        if (!item.isInit) {
+            const viewer = this.adapter.viewHolder(this.ItemsHost, item);
+            item.view = viewer;
+            this.adapter.onViewHolder(item, viewer, index);
+            item.isInit = true;
+        }
+        else if (item.view) {
+            this.adapter.onViewHolder(item, item.view, index);
+        }
+        const el = item.view?.getView?.();
+        if (el) {
+            this.ensureDomOrder(index, el);
+            this.created.set(index, el);
+        }
+    }
+    /** Removes all mounted items outside [start..end] range. */
+    unmountOutside(start, end) {
+        this.created.forEach((el, idx) => {
+            if (idx < start || idx > end) {
+                if (el.parentElement === this.ItemsHost)
+                    el.remove();
+                this.created.delete(idx);
+            }
+        });
+    }
+    /** Removes all items marked as invisible from DOM. */
+    cleanupInvisibleItems() {
+        this.created.forEach((el, idx) => {
+            if (!this.isIndexVisible(idx)) {
+                if (el.parentElement === this.ItemsHost)
+                    el.remove();
+                this.created.delete(idx);
+            }
+        });
+    }
+    /** Returns cumulative height from start to top of item at index. */
+    offsetTopOf(index) {
+        return this.fenwick.sum(index);
+    }
+    /** Returns total height of items in range [start..end]. */
+    windowHeight(start, end) {
+        return this.fenwick.rangeSum(start + 1, end + 1);
+    }
+    /** Returns total scrollable height for all items. */
+    totalHeight(count) {
+        return this.fenwick.sum(count);
+    }
+}
+VirtualRecyclerView.EPS = 0.5;
+VirtualRecyclerView.ATTR_INDEX = "data-vindex";
+
 /**
  * @class
  */
@@ -4610,7 +5335,12 @@ class SelectBox {
         select.classList.add("init");
         // ModelManager setup
         optionModelManager.setupAdapter(MixedAdapter);
-        optionModelManager.setupRecyclerView(RecyclerView);
+        if (options.virtualScroll) {
+            optionModelManager.setupRecyclerView(VirtualRecyclerView);
+        }
+        else {
+            optionModelManager.setupRecyclerView(RecyclerView);
+        }
         optionModelManager.createModelResources(Libs.parseSelectToArray(select));
         optionModelManager.onUpdated = () => {
             container.popup?.triggerResize?.();
@@ -4670,6 +5400,7 @@ class SelectBox {
             searchController.setAjax(options.ajax);
         }
         const optionAdapter = container.popup.optionAdapter;
+        let hightlightTimer = null;
         const searchHandle = (keyword, isTrigger) => {
             if (!isTrigger && keyword === "") {
                 searchController.clear();
@@ -4680,12 +5411,16 @@ class SelectBox {
                 searchController
                     .search(keyword)
                     .then((result) => {
-                    container.popup?.triggerResize?.();
-                    if (result?.hasResults) {
-                        setTimeout(() => {
-                            optionAdapter.resetHighlight();
-                        }, options.animationtime ? options.animationtime + 10 : 0);
-                    }
+                    clearTimeout(hightlightTimer);
+                    Libs.callbackScheduler.on(`sche_vis_proxy_${optionAdapter.adapterKey}`, () => {
+                        container.popup?.triggerResize?.();
+                        if (result?.hasResults) {
+                            hightlightTimer = setTimeout(() => {
+                                optionAdapter.resetHighlight();
+                                container.popup?.triggerResize?.();
+                            }, options.animationtime ?? 0);
+                        }
+                    }, { debounce: 10 });
                 })
                     .catch((error) => {
                     console.error("Search error:", error);
@@ -4696,16 +5431,18 @@ class SelectBox {
         searchbox.onSearch = (keyword, isTrigger) => {
             if (!searchController.compareSearchTrigger(keyword))
                 return;
+            if (searchHandleTimer)
+                clearTimeout(searchHandleTimer);
             if (searchController.isAjax()) {
-                if (searchHandleTimer)
-                    clearTimeout(searchHandleTimer);
                 container.popup?.showLoading?.();
                 searchHandleTimer = setTimeout(() => {
                     searchHandle(keyword, isTrigger);
                 }, options.delaysearchtime ?? 0);
             }
             else {
-                searchHandle(keyword, isTrigger);
+                searchHandleTimer = setTimeout(() => {
+                    searchHandle(keyword, isTrigger);
+                }, 10);
             }
         };
         searchController.setPopup(container.popup);
@@ -5222,7 +5959,7 @@ class Selective {
         this.bindedQueries.set(query, merged);
         const doneToken = Libs.randomString();
         Libs.callbackScheduler.on(doneToken, () => {
-            iEvents.callEvent([this.find(query)], ...merged.on.load);
+            iEvents.callEvent([this.find(query)], ...(merged.on.load));
             Libs.callbackScheduler.clear(doneToken);
             merged.on.load = [];
         });
@@ -5516,7 +6253,7 @@ const SECLASS = new Selective();
  *
  * Declared as `const` literal type to enable strict typing and easy tree-shaking.
  */
-const version = "1.1.6";
+const version = "1.2.1";
 /**
  * Library name identifier.
  *