selective-ui 1.4.0 → 1.4.2

package/dist/selective-ui.esm.js

@@ -1,4 +1,4 @@
-/*! Selective UI v1.4.0 | MIT License */
+/*! Selective UI v1.4.2 | MIT License */
 /**
  * @class
  */
@@ -147,7 +147,7 @@ class CallbackScheduler {
      *
      * @public
      * @param {TimerKey} key - Group identifier for callbacks.
-     * @param {(payload: any[] | null) => void} callback - Function to execute after debounce timeout.
+     * @param {(payload?: any[]) => void} callback - Function to execute after debounce timeout.
      * @param {TimerOptions} [options={}] - Scheduling options (`debounce`, `once`).
      * @returns {void}
      */
@@ -235,7 +235,8 @@ class CallbackScheduler {
                             await resp;
                         }
                     }
-                    catch { }
+                    catch {
+                    }
                     finally {
                         if (entry.once) {
                             executes[i] = undefined;
@@ -368,9 +369,11 @@ class Libs {
      * @param {boolean} systemNodeCreate - If true, do not clone; use original node.
      * @returns {HTMLElement} - The processed element.
      */
-    static nodeCloner(node = document.documentElement, _nodeOption = null, systemNodeCreate = false) {
+    static nodeCloner(node = document.documentElement, _nodeOption, systemNodeCreate = false) {
         const nodeOption = { ...(_nodeOption ?? {}) };
-        const element_creation = systemNodeCreate ? node : node.cloneNode(true);
+        const element_creation = systemNodeCreate
+            ? node
+            : node.cloneNode(true);
         const classList = nodeOption.classList;
         if (typeof classList === "string") {
             element_creation.classList.add(classList);
@@ -442,11 +445,13 @@ class Libs {
      * @param {TTags|Object} [recursiveTemp={}] - Accumulator for tag references.
      * @returns {TTags} - Tag map or the final mount result.
      */
-    static mountNode(rawObj, parentE = null, isPrepend = false, isRecusive = false, recursiveTemp = {}) {
+    static mountNode(rawObj, parentE, isPrepend = false, isRecusive = false, recursiveTemp = {}) {
         let view = null;
         for (const key in rawObj) {
             const singleObj = rawObj[key];
-            const tag = singleObj?.tag?.tagName ? singleObj.tag : this.nodeCreator(singleObj.tag);
+            const tag = singleObj?.tag?.tagName
+                ? singleObj.tag
+                : this.nodeCreator(singleObj.tag);
             recursiveTemp[key] = tag;
             if (singleObj?.child)
                 this.mountNode(singleObj.child, tag, false, false, recursiveTemp);
@@ -663,7 +668,8 @@ class Libs {
                     n.removeAttribute(name);
                     return;
                 }
-                if (/^(href|src|xlink:href)$/i.test(name) && /^javascript:/i.test(value)) {
+                if (/^(href|src|xlink:href)$/i.test(name) &&
+                    /^javascript:/i.test(value)) {
                     n.removeAttribute(name);
                 }
             }
@@ -693,7 +699,10 @@ class Libs {
     static string2normalize(str) {
         if (str == null)
             return "";
-        const s = String(str).toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "");
+        const s = String(str)
+            .toLowerCase()
+            .normalize("NFD")
+            .replace(/[\u0300-\u036f]/g, "");
         return s.replace(/đ/g, "d").replace(/Đ/g, "d");
     }
     /**
@@ -735,7 +744,8 @@ class Libs {
      */
     static IsIOS() {
         const ua = navigator.userAgent;
-        return /iP(hone|ad|od)/.test(ua) || (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1);
+        return (/iP(hone|ad|od)/.test(ua) ||
+            (navigator.platform === "MacIntel" && navigator.maxTouchPoints > 1));
     }
     /**
      * Converts an arbitrary CSS size value into pixel units by measuring a temporary element.
@@ -757,14 +767,16 @@ class Libs {
         if (v.endsWith("rem"))
             return fs * parseFloat(v) + "px";
         // fallback: DOM measure
-        const el = this.nodeCreator({ node: "div", style: { height: v, opacity: "0" } });
+        const el = this.nodeCreator({
+            node: "div",
+            style: { height: v, opacity: "0" },
+        });
         document.body.appendChild(el);
         const px = el.offsetHeight + "px";
         el.remove();
         return px;
     }
 }
-Libs._iStorage = null;
 /**
  * Schedules and batches function executions keyed by name, with debounced timers.
  * Provides setExecute(), clearExecute(), and run() to manage deferred callbacks.
@@ -960,8 +972,9 @@ class Refresher {
      *
      * @param select - Native `<select>` element used as the sizing reference and option source.
      * @param view - View panel element whose inline styles will be updated.
+     * @param isWidthOnly - If true, only the width will be updated; height will be left unchanged.
      */
-    static resizeBox(select, view) {
+    static resizeBox(select, view, isWidthOnly = false) {
         const bindedMap = Libs.getBinderMap(select);
         if (!bindedMap?.options)
             return;
@@ -981,7 +994,12 @@ class Refresher {
             width = options.width;
         if (cfgHeight > 0)
             height = options.height;
-        Object.assign(view.style, { width, height, minWidth, minHeight });
+        if (isWidthOnly) {
+            Object.assign(view.style, { width, maxWidth: width, minWidth });
+        }
+        else {
+            Object.assign(view.style, { width, height, maxWidth: width, minWidth, minHeight });
+        }
     }
 }
 
@@ -1291,25 +1309,6 @@ class PlaceHolder extends Lifecycle {
      */
     constructor(options) {
         super();
-        /**
-         * Root DOM element for the placeholder.
-         *
-         * Created during {@link initialize}. Removed from the DOM during {@link destroy}.
-         * `null` before initialization and after destruction.
-         */
-        this.node = null;
-        /**
-         * Configuration snapshot used to render and optionally persist placeholder content.
-         *
-         * Key fields used by this component:
-         * - `placeholder`: initial/current placeholder text/markup
-         * - `allowHtml`: controls whether HTML is rendered or stripped
-         *
-         * Cleared during {@link destroy}.
-         *
-         * @internal
-         */
-        this.options = null;
         if (options)
             this.initialize(options);
     }
@@ -1534,34 +1533,8 @@ class OptionHandle extends Lifecycle {
      *
      * @param options - Feature flags and labels for the two actions.
      */
-    constructor(options = null) {
+    constructor(options) {
         super();
-        /**
-         * Result returned by {@link Libs.mountNode}.
-         *
-         * Stores the mounted view structure so the component can keep a stable reference
-         * to its created DOM nodes. `null` before {@link initialize}.
-         *
-         * @internal
-         */
-        this.nodeMounted = null;
-        /**
-         * Root element of this control.
-         *
-         * Created during {@link initialize}. This node is used by {@link show}/{@link hide}
-         * and removed during {@link destroy}.
-         */
-        this.node = null;
-        /**
-         * Configuration snapshot used for:
-         * - labels (`textSelectAll`, `textDeselectAll`)
-         * - feature flags (`multiple`, `selectall`)
-         *
-         * Treated as read-only after initialization; cleared on {@link destroy}.
-         *
-         * @internal
-         */
-        this.options = null;
         /**
          * Callback list invoked when the "Select all" control is activated.
          *
@@ -1649,7 +1622,8 @@ class OptionHandle extends Lifecycle {
     available() {
         if (!this.options)
             return false;
-        return Libs.string2Boolean(this.options.multiple) && Libs.string2Boolean(this.options.selectall);
+        return (Libs.string2Boolean(this.options.multiple) &&
+            Libs.string2Boolean(this.options.selectall));
     }
     /**
      * Re-evaluates visibility and advances the lifecycle update step.
@@ -1706,7 +1680,7 @@ class OptionHandle extends Lifecycle {
      *
      * @param action - Callback invoked on activation; ignored when not a function.
      */
-    onSelectAll(action = null) {
+    onSelectAll(action) {
         if (typeof action === "function") {
             this.actionOnSelectAll.push(action);
         }
@@ -1722,7 +1696,7 @@ class OptionHandle extends Lifecycle {
      *
      * @param action - Callback invoked on activation; ignored when not a function.
      */
-    onDeSelectAll(action = null) {
+    onDeSelectAll(action) {
         if (typeof action === "function") {
             this.actionOnDeSelectAll.push(action);
         }
@@ -1790,26 +1764,10 @@ class EmptyState extends Lifecycle {
      * If `options` are provided, initialization runs immediately (creates {@link node} and
      * transitions to `INITIALIZED`).
      *
-     * @param {SelectiveOptions | null} [options=null] - Configuration containing empty state messages.
+     * @param {SelectiveOptions} [options=null] - Configuration containing empty state messages.
      */
-    constructor(options = null) {
+    constructor(options) {
         super();
-        /**
-         * Root DOM element for the empty state UI.
-         *
-         * - Created during {@link initialize}.
-         * - Intended to be appended by the parent container (component does not auto-attach).
-         * - Removed from DOM during {@link destroy}.
-         */
-        this.node = null;
-        /**
-         * Configuration source for empty state messages.
-         *
-         * Expected to provide at least:
-         * - `textNoData` (for `"nodata"`)
-         * - `textNotFound` (for `"notfound"`)
-         */
-        this.options = null;
         if (options)
             this.initialize(options);
     }
@@ -1935,25 +1893,10 @@ class LoadingState extends Lifecycle {
      * If `options` are provided, initialization runs immediately (creates {@link node} and
      * transitions to `INITIALIZED`).
      *
-     * @param {SelectiveOptions | null} [options=null] - Configuration containing the loading message text.
+     * @param {SelectiveOptions} [options=null] - Configuration containing the loading message text.
      */
-    constructor(options = null) {
+    constructor(options) {
         super();
-        /**
-         * Root DOM element for the loading state UI.
-         *
-         * - Created during {@link initialize}.
-         * - Intended to be appended by the parent container (component does not auto-attach).
-         * - Removed from DOM during {@link destroy}.
-         */
-        this.node = null;
-        /**
-         * Configuration source for loading message text.
-         *
-         * Expected to provide:
-         * - `textLoading` (displayed while loading is active)
-         */
-        this.options = null;
         if (options)
             this.initialize(options);
     }
@@ -2111,27 +2054,6 @@ class ResizeObserverService {
          * It does **not** indicate that observers are currently attached (see {@link connect}).
          */
         this.isInit = false;
-        /**
-         * The currently bound DOM element being observed.
-         *
-         * @remarks
-         * Set by {@link connect} and cleared by {@link disconnect}.
-         */
-        this.element = null;
-        /**
-         * Underlying `ResizeObserver` instance.
-         *
-         * @remarks
-         * Allocated on {@link connect}. Disconnected and nulled on {@link disconnect}.
-         */
-        this.resizeObserver = null;
-        /**
-         * Underlying `MutationObserver` instance watching `style` and `class` attribute changes.
-         *
-         * @remarks
-         * Allocated on {@link connect}. Disconnected and nulled on {@link disconnect}.
-         */
-        this.mutationObserver = null;
         this.isInit = true;
         this.boundUpdateChanged = this.updateChanged.bind(this);
     }
@@ -2177,7 +2099,8 @@ class ResizeObserverService {
             return;
         }
         const rect = el.getBoundingClientRect();
-        const style = typeof window !== "undefined" && typeof window.getComputedStyle === "function"
+        const style = typeof window !== "undefined" &&
+            typeof window.getComputedStyle === "function"
             ? window.getComputedStyle(el)
             : null;
         const metrics = {
@@ -2309,36 +2232,10 @@ class Popup extends Lifecycle {
      * @param options - Configuration options (panel sizing, flags, texts, etc.).
      * @param modelManager - Model manager that supplies the adapter and recycler view.
      */
-    constructor(select = null, options = null, modelManager = null) {
+    constructor(select, options, modelManager) {
         super();
-        /** Active configuration for the popup behavior and text labels */
-        this.options = null;
         /** Indicates whether the popup DOM has been attached to the document body at least once */
         this.isCreated = false;
-        /** Mixed adapter handling items/models and visibility stats */
-        this.optionAdapter = null;
-        /** Root popup container (the floating panel) */
-        this.node = null;
-        /** Effector service used to measure/animate the popup */
-        this.effSvc = null;
-        /** Resize observer to react to parent panel size changes */
-        this.resizeObser = null;
-        /** Binder map for parent elements (anchors to compute placement from) */
-        this.parent = null;
-        /** Header control exposing "Select All / Deselect All" actions */
-        this.optionHandle = null;
-        /** "Empty / Not found" feedback component */
-        this.emptyState = null;
-        /** Loading indicator component */
-        this.loadingState = null;
-        /** Virtualized recycler view for performant lists */
-        this.recyclerView = null;
-        /** Container that holds the list of options */
-        this.optionsContainer = null;
-        /** Scroll handler used by infinite scroll */
-        this.scrollListener = null;
-        /** Handle to defer hiding the loading indicator */
-        this.hideLoadHandle = null;
         /** Default virtual scroll configuration (tuned for typical option heights) */
         this.virtualScrollConfig = {
             /** Estimated item height in pixels (improves initial layout calculation) */
@@ -2346,7 +2243,7 @@ class Popup extends Lifecycle {
             /** Number of extra items to render above/below the viewport */
             overscan: 8,
             /** Whether the list contains items with dynamic (non-uniform) heights */
-            dynamicHeights: true
+            dynamicHeights: true,
         };
         this.modelManager = modelManager;
         if (select && options) {
@@ -2393,7 +2290,8 @@ class Popup extends Lifecycle {
             },
         }, null);
         this.node = nodeMounted.view;
-        this.optionsContainer = nodeMounted.tags.OptionsContainer;
+        this.optionsContainer = nodeMounted.tags
+            .OptionsContainer;
         this.parent = Libs.getBinderMap(select);
         this.options = options;
         this.init();
@@ -2402,7 +2300,7 @@ class Popup extends Lifecycle {
                 scrollEl: this.node,
                 estimateItemHeight: this.virtualScrollConfig.estimateItemHeight,
                 overscan: this.virtualScrollConfig.overscan,
-                dynamicHeights: this.virtualScrollConfig.dynamicHeights
+                dynamicHeights: this.virtualScrollConfig.dynamicHeights,
             }
             : {};
         // Load ModelManager resources into the list container
@@ -2429,7 +2327,11 @@ class Popup extends Lifecycle {
      * - Triggers a resize to accommodate layout changes
      */
     async showLoading() {
-        if (!this.options || !this.loadingState || !this.optionHandle || !this.optionAdapter || !this.modelManager)
+        if (!this.options ||
+            !this.loadingState ||
+            !this.optionHandle ||
+            !this.optionAdapter ||
+            !this.modelManager)
             return;
         if (this.hideLoadHandle)
             clearTimeout(this.hideLoadHandle);
@@ -2447,7 +2349,10 @@ class Popup extends Lifecycle {
      * Debounce: Uses `animationtime` as a short delay before hiding the loading indicator.
      */
     async hideLoading() {
-        if (!this.options || !this.loadingState || !this.optionAdapter || !this.modelManager)
+        if (!this.options ||
+            !this.loadingState ||
+            !this.optionAdapter ||
+            !this.modelManager)
             return;
         if (this.hideLoadHandle)
             clearTimeout(this.hideLoadHandle);
@@ -2488,7 +2393,10 @@ class Popup extends Lifecycle {
      * @param stats - Optionally provide precomputed visibility stats.
      */
     updateEmptyState(stats) {
-        if (!this.optionAdapter || !this.emptyState || !this.optionHandle || !this.optionsContainer)
+        if (!this.optionAdapter ||
+            !this.emptyState ||
+            !this.optionHandle ||
+            !this.optionsContainer)
             return;
         const s = stats ?? this.optionAdapter.getVisibilityStats();
         if (s.isEmpty) {
@@ -2572,8 +2480,12 @@ class Popup extends Lifecycle {
      * @param callback - Optional callback invoked when the opening animation completes.
      * @param isShowEmptyState - If true, applies the empty/not-found state before animation.
      */
-    open(callback = null, isShowEmptyState) {
-        if (!this.node || !this.options || !this.optionHandle || !this.parent || !this.effSvc)
+    open(callback, isShowEmptyState) {
+        if (!this.node ||
+            !this.options ||
+            !this.optionHandle ||
+            !this.parent ||
+            !this.effSvc)
             return;
         // Ensure one-time initialization
         this.load();
@@ -2622,8 +2534,11 @@ class Popup extends Lifecycle {
      *
      * @param callback - Optional callback invoked when the closing animation completes.
      */
-    close(callback = null) {
-        if (!this.isCreated || !this.options || !this.resizeObser || !this.effSvc)
+    close(callback) {
+        if (!this.isCreated ||
+            !this.options ||
+            !this.resizeObser ||
+            !this.effSvc)
             return;
         const rv = this.recyclerView;
         rv?.suspend?.();
@@ -2782,7 +2697,9 @@ class Popup extends Lifecycle {
         let maxHeight = configMaxHeight;
         let realHeight = Math.min(contentHeight, maxHeight);
         const heightOri = spaceBelow - safeMargin;
-        if (realHeight >= configMinHeight ? heightOri >= configMinHeight : heightOri >= realHeight) {
+        if (realHeight >= configMinHeight
+            ? heightOri >= configMinHeight
+            : heightOri >= realHeight) {
             position = "bottom";
             maxHeight = Math.min(spaceBelow - safeMargin, configMaxHeight);
         }
@@ -2882,78 +2799,8 @@ class SearchBox extends Lifecycle {
      *
      * @param options - Configuration such as placeholder, accessibility IDs, and flags.
      */
-    constructor(options = null) {
+    constructor(options) {
         super();
-        /**
-         * The mount result returned by {@link Libs.mountNode}.
-         *
-         * Provides typed access to created DOM tags (e.g., `SearchInput`) and the root view.
-         * `null` before initialization and after destruction.
-         *
-         * @internal
-         */
-        this.nodeMounted = null;
-        /**
-         * Root container node of this component.
-         *
-         * Created during {@link initialize} and removed during {@link destroy}.
-         * Visibility is controlled by adding/removing the `hide` class.
-         */
-        this.node = null;
-        /**
-         * The `<input type="search">` element used to capture user queries.
-         *
-         * Cached for imperative operations (focus, placeholder updates, ARIA updates).
-         * `null` before initialization and after destruction.
-         *
-         * @internal
-         */
-        this.SearchInput = null;
-        /**
-         * External "search changed" hook.
-         *
-         * Invoked when the user edits text (via the `input` event) and the edit is not
-         * part of a handled control-key sequence (e.g., ArrowUp/Down/Tab/Enter/Escape).
-         *
-         * Ownership:
-         * - Implementations typically filter adapter/model state and refresh the list.
-         */
-        this.onSearch = null;
-        /**
-         * Options snapshot used for behavior toggles and attributes.
-         *
-         * Key fields typically consumed here:
-         * - `placeholder`: initial placeholder string
-         * - `searchable`: toggles readOnly + focus behavior on {@link show}
-         * - `SEID_LIST`: used as `aria-controls` value to bind to listbox container
-         *
-         * Cleared during {@link destroy}.
-         *
-         * @internal
-         */
-        this.options = null;
-        /**
-         * External navigation hook for list traversal.
-         *
-         * Called with:
-         * - `+1` for forward (ArrowDown / Tab)
-         * - `-1` for backward (ArrowUp)
-         *
-         * Typical consumers update highlight/active option in Adapter/RecyclerView.
-         */
-        this.onNavigate = null;
-        /**
-         * External "commit" hook (Enter key).
-         *
-         * Typical consumers confirm selection of the highlighted option or submit the current state.
-         */
-        this.onEnter = null;
-        /**
-         * External "cancel" hook (Escape key).
-         *
-         * Typical consumers close the popup, clear highlight, or reset interaction mode.
-         */
-        this.onEsc = null;
         this.options = options;
         if (options)
             this.initialize(options);
@@ -3219,17 +3066,7 @@ class EffectorImpl {
      *
      * @param query - CSS selector or element to control. When `null`, instance starts unbound.
      */
-    constructor(query = null) {
-        /**
-         * Timeout used to finalize expand/collapse/swipe animations.
-         * Cleared by {@link cancel}.
-         */
-        this.timeOut = null;
-        /**
-         * Timeout used to clear transitions after resize in non-animated scenarios.
-         * Cleared by {@link cancel}.
-         */
-        this.resizeTimeout = null;
+    constructor(query) {
         /**
          * Internal animation flag set while a timed animation is in-flight.
          *
@@ -3413,7 +3250,9 @@ class EffectorImpl {
         const { duration = 200, onComplete } = config;
         const currentHeight = this.element.offsetHeight;
         const currentTop = this.element.offsetTop;
-        const position = this.element.classList.contains("position-top") ? "top" : "bottom";
+        const position = this.element.classList.contains("position-top")
+            ? "top"
+            : "bottom";
         const isScrollable = this.element.scrollHeight - this.element.offsetHeight > 0;
         const finalTop = position === "top" ? currentTop + currentHeight : currentTop;
         requestAnimationFrame(() => {
@@ -3551,7 +3390,9 @@ class EffectorImpl {
             return this;
         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 currentPosition = this.element.classList.contains("position-top")
+            ? "top"
+            : "bottom";
         const isPositionChanged = currentPosition !== position;
         const isScrollable = this.element.scrollHeight > maxHeight;
         this.element.classList.toggle("position-top", position === "top");
@@ -3667,25 +3508,11 @@ class Model extends Lifecycle {
      * - Calls {@link Lifecycle.init} immediately (`NEW → INITIALIZED`).
      *
      * @param {TOptions} options - Configuration options for the model.
-     * @param {TTarget | null} [targetElement=null] - Optional DOM element to bind.
-     * @param {TView | null} [view=null] - Optional view responsible for rendering this model.
+     * @param {TTarget} [targetElement=null] - Optional DOM element to bind.
+     * @param {TView} [view=null] - Optional view responsible for rendering this model.
      */
-    constructor(options, targetElement = null, view = null) {
+    constructor(options, targetElement, view) {
         super();
-        /**
-         * The currently bound target DOM element.
-         *
-         * This element typically represents the source-of-truth node in the host DOM (e.g., a native `<option>`).
-         * May be replaced via {@link updateTarget} during reconciliation.
-         */
-        this.targetElement = null;
-        /**
-         * View instance responsible for rendering this model.
-         *
-         * Ownership: this model will destroy the view on {@link destroy}.
-         * The view may be attached/assigned by external orchestrators (Adapter/RecyclerView) after construction.
-         */
-        this.view = null;
         /**
          * Position index used by list infrastructure for ordering/tracking.
          * Semantics are library-specific (e.g., top-level index or adapter position).
@@ -3717,7 +3544,7 @@ class Model extends Lifecycle {
      * - Assigns {@link targetElement}.
      * - Calls {@link Lifecycle.update} (guarded by lifecycle state).
      *
-     * @param {TTarget | null} targetElement - The new DOM element to associate with this model.
+     * @param {TTarget} targetElement - The new DOM element to associate with this model.
      * @returns {void}
      */
     updateTarget(targetElement) {
@@ -3917,7 +3744,7 @@ class GroupModel extends Model {
         if (this.is(LifecycleState.DESTROYED)) {
             return;
         }
-        this.items.forEach(item => {
+        this.items.forEach((item) => {
             item.destroy();
         });
         this.items = [];
@@ -4041,10 +3868,10 @@ class OptionModel extends Model {
      * Creates an option model.
      *
      * @param {SelectiveOptions} options - Shared configuration for models/views.
-     * @param {HTMLOptionElement | null} [targetElement=null] - Backing `<option>` element.
-     * @param {OptionView | null} [view=null] - Optional view used to render this model.
+     * @param {HTMLOptionElement} [targetElement=null] - Backing `<option>` element.
+     * @param {OptionView} [view=null] - Optional view used to render this model.
      */
-    constructor(options, targetElement = null, view = null) {
+    constructor(options, targetElement, view) {
         super(options, targetElement, view);
         /**
          * External selection subscribers (emitted by the {@link selected} setter).
@@ -4068,11 +3895,6 @@ class OptionModel extends Model {
         this._visible = true;
         /** Highlight flag used for keyboard navigation / hover. */
         this._highlighted = false;
-        /**
-         * Parent group model (if this option belongs to a group).
-         * Assigned by grouping logic (e.g., GroupModel/MixedAdapter).
-         */
-        this.group = null;
     }
     /**
      * Initializes the model and precomputes the search key.
@@ -4201,6 +4023,32 @@ class OptionModel extends Model {
         }
         iEvents.callEvent([this, value], ...this.privOnInternalSelected);
     }
+    /**
+     * Resolved display mask for this option.
+     *
+     * The mask is the primary render label used by the UI layer and supports
+     * optional inline tag translation / rich HTML rendering.
+     *
+     * Source priority:
+     * 1. `data-mask` (`dataset.mask`)
+     * 2. Native `<option>` text content (`targetElement.text`)
+     *
+     * Processing pipeline:
+     * - Raw content is first passed through {@link Libs.tagTranslate}.
+     * - When `options.allowHtml === true`, translated HTML is preserved.
+     * - Otherwise, all markup is stripped via {@link Libs.stripHtml}.
+     *
+     * Unlike {@link text}, this getter prioritizes the custom dataset mask,
+     * making it suitable for display overrides without mutating the native
+     * `<option>` label.
+     *
+     * @returns {string} Render-ready option label.
+     */
+    get mask() {
+        const raw = this.dataset?.mask ?? this.targetElement?.text ?? "";
+        const translated = Libs.tagTranslate(raw);
+        return this.options.allowHtml ? translated : Libs.stripHtml(translated);
+    }
     /**
      * Display label for rendering (with tag translation and HTML policy).
      *
@@ -4214,7 +4062,7 @@ class OptionModel extends Model {
      * @returns {string}
      */
     get text() {
-        const raw = this.dataset?.mask ?? this.targetElement?.text ?? "";
+        const raw = this.targetElement?.text ?? this.dataset?.mask ?? "";
         const translated = Libs.tagTranslate(raw);
         return this.options.allowHtml ? translated : Libs.stripHtml(translated);
     }
@@ -4227,7 +4075,9 @@ class OptionModel extends Model {
      * @returns {string}
      */
     get textContent() {
-        return this.options.allowHtml ? Libs.stripHtml(this.text).trim() : this.text.trim();
+        return this.options.allowHtml
+            ? Libs.stripHtml(this.text).trim()
+            : this.text.trim();
     }
     /**
      * Dataset object of the backing `<option>` element.
@@ -4408,8 +4258,6 @@ class ModelManager extends Lifecycle {
     constructor(options) {
         super();
         this.privModelList = [];
-        this.privAdapterHandle = null;
-        this.privRecyclerViewHandle = null;
         this.options = null;
         this.oldPosition = 0;
         this.options = options;
@@ -4461,7 +4309,9 @@ class ModelManager extends Lifecycle {
             else if (data.tagName === "OPTION") {
                 const optionModel = new OptionModel(this.options, data);
                 const parentGroup = data["__parentGroup"];
-                if (parentGroup && currentGroup && parentGroup === currentGroup.targetElement) {
+                if (parentGroup &&
+                    currentGroup &&
+                    parentGroup === currentGroup.targetElement) {
                     currentGroup.addItem(optionModel);
                     optionModel.group = currentGroup;
                 }
@@ -4886,44 +4736,10 @@ class AccessoryBox extends Lifecycle {
     /**
      * Creates an AccessoryBox and optionally initializes it with configuration.
      *
-     * @param {SelectiveOptions | null} [options=null] - Configuration controlling placement/visibility and texts.
+     * @param {SelectiveOptions} [options=null] - Configuration controlling placement/visibility and texts.
      */
-    constructor(options = null) {
+    constructor(options) {
         super();
-        /**
-         * Mounted structure returned by the node mounting helper.
-         * Contains the root element (`view`) and any tag handles (if present).
-         */
-        this.nodeMounted = null;
-        /**
-         * Root DOM element of the accessory box (hidden by default).
-         * Created during {@link init} and removed during {@link destroy}.
-         */
-        this.node = null;
-        /**
-         * Component configuration (texts, behavior, placement).
-         * This component reads:
-         * - `accessoryStyle` ("top" or default bottom)
-         * - `accessoryVisible` (enable/disable)
-         * - `multiple` (multi-select mode)
-         * - `textAccessoryDeselect` (a11y label prefix)
-         */
-        this.options = null;
-        /**
-         * The Select UI mask element used as the positioning reference.
-         * Provided by {@link setRoot}.
-         */
-        this.selectUIMask = null;
-        /**
-         * Parent container that hosts both the Select UI mask and the accessory box.
-         * Computed from `selectUIMask.parentElement`.
-         */
-        this.parentMask = null;
-        /**
-         * ModelManager used to run selection pipelines and coordinate state updates.
-         * This component does not own selection state; it delegates to the model layer.
-         */
-        this.modelManager = null;
         /**
          * Current selected option models rendered as chips.
          * This is a cached snapshot used for show/hide decisions and re-rendering.
@@ -5231,15 +5047,6 @@ class SearchController extends Lifecycle {
      */
     constructor(selectElement, modelManager, selectBox) {
         super();
-        /**
-         * AJAX configuration; when `null`, {@link search} falls back to local filtering.
-         * @see {@link setAjax}
-         */
-        this.ajaxConfig = null;
-        /** Abort handle used to cancel an in-flight AJAX request when a newer request starts. */
-        this.abortController = null;
-        /** Optional popup handle used for showing/hiding loading UI during remote operations. */
-        this.popup = null;
         /**
          * SelectBox handle used by custom data builder functions that require Selective context.
          * NOTE: This is a reference; the controller does not own/destroy the SelectBox.
@@ -5303,7 +5110,11 @@ class SearchController extends Lifecycle {
      */
     async loadByValues(values) {
         if (!this.ajaxConfig) {
-            return { success: false, items: [], message: "Ajax not configured" };
+            return {
+                success: false,
+                items: [],
+                message: "Ajax not configured",
+            };
         }
         const valuesArray = Array.isArray(values) ? values : [values];
         if (valuesArray.length === 0)
@@ -5320,7 +5131,7 @@ class SearchController extends Lifecycle {
                     load_by_values: "1",
                     ...(typeof cfg.data === "function"
                         ? cfg.data.bind(this.selectBox.Selective.find(this.selectBox.container.targetElement))("", 0)
-                        : cfg.data ?? {}),
+                        : (cfg.data ?? {})),
                 };
             }
             let response;
@@ -5330,7 +5141,9 @@ class SearchController extends Lifecycle {
                 response = await fetch(cfg.url, {
                     method: "POST",
                     body: formData,
-                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    headers: {
+                        "Content-Type": "application/x-www-form-urlencoded",
+                    },
                 });
             }
             else {
@@ -5367,7 +5180,7 @@ class SearchController extends Lifecycle {
      * Configures AJAX settings used for remote searching and pagination.
      * Setting `null` disables AJAX mode and causes {@link search} to use local filtering.
      *
-     * @param {AjaxConfig | null} config - AJAX configuration (endpoint, method, data builders, keepSelected, ...).
+     * @param {AjaxConfig} config - AJAX configuration (endpoint, method, data builders, keepSelected, ...).
      * @returns {void}
      */
     setAjax(config) {
@@ -5557,7 +5370,12 @@ class SearchController extends Lifecycle {
                 payload.selectedValue = selectedValues;
         }
         else {
-            payload = { search: keyword, page, selectedValue: selectedValues, ...(cfg.data ?? {}) };
+            payload = {
+                search: keyword,
+                page,
+                selectedValue: selectedValues,
+                ...(cfg.data ?? {}),
+            };
         }
         try {
             let response;
@@ -5567,13 +5385,17 @@ class SearchController extends Lifecycle {
                 response = await fetch(cfg.url, {
                     method: "POST",
                     body: formData,
-                    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                    headers: {
+                        "Content-Type": "application/x-www-form-urlencoded",
+                    },
                     signal: this.abortController.signal,
                 });
             }
             else {
                 const params = new URLSearchParams(payload).toString();
-                response = await fetch(`${cfg.url}?${params}`, { signal: this.abortController.signal });
+                response = await fetch(`${cfg.url}?${params}`, {
+                    signal: this.abortController.signal,
+                });
             }
             const data = await response.json();
             const result = this.parseResponse(data);
@@ -5647,7 +5469,7 @@ class SearchController extends Lifecycle {
                 hasPagination = true;
                 page = parseInt(data.page ?? 0, 10);
                 totalPages = parseInt(data.totalPages ?? data.total_page ?? 1, 10);
-                hasMore = data.hasMore ?? (page < totalPages - 1);
+                hasMore = data.hasMore ?? page < totalPages - 1;
             }
         }
         else if (Array.isArray(data)) {
@@ -5658,23 +5480,39 @@ class SearchController extends Lifecycle {
             if (data.pagination) {
                 hasPagination = true;
                 page = parseInt(data.pagination.page ?? 0, 10);
-                totalPages = parseInt(data.pagination.totalPages ?? data.pagination.total_page ?? 1, 10);
-                hasMore = data.pagination.hasMore ?? (page < totalPages - 1);
+                totalPages = parseInt(data.pagination.totalPages ??
+                    data.pagination.total_page ??
+                    1, 10);
+                hasMore = data.pagination.hasMore ?? page < totalPages - 1;
             }
         }
         const normalized = items.map((item) => {
-            if (item instanceof HTMLOptionElement || item instanceof HTMLOptGroupElement)
+            if (item instanceof HTMLOptionElement ||
+                item instanceof HTMLOptGroupElement)
                 return item;
-            if (item.type === "optgroup" || item.isGroup || item.group || item.label) {
+            if (item.type === "optgroup" ||
+                item.isGroup ||
+                item.group ||
+                item.label) {
                 const label = item.label ?? item.name ?? item.title ?? "";
                 const dataObj = item.data ?? {};
                 const opts = (item.options ?? item.items ?? []).map((opt) => ({
                     value: opt.value ?? opt.id ?? opt.key ?? "",
-                    text: opt.text ?? opt.label ?? opt.name ?? opt.title ?? "",
+                    text: opt.text ??
+                        opt.label ??
+                        opt.name ??
+                        opt.title ??
+                        "",
                     selected: opt.selected ?? false,
-                    data: opt.data ?? (opt.imgsrc ? { imgsrc: opt.imgsrc } : {}),
+                    data: opt.data ??
+                        (opt.imgsrc ? { imgsrc: opt.imgsrc } : {}),
                 }));
-                return { type: "optgroup", label, data: dataObj, options: opts };
+                return {
+                    type: "optgroup",
+                    label,
+                    data: dataObj,
+                    options: opts,
+                };
             }
             const dataObj = item.data ?? {};
             if (item?.imgsrc)
@@ -5716,9 +5554,12 @@ class SearchController extends Lifecycle {
             select.innerHTML = "";
         items.forEach((item) => {
             // Skip empty item (defensive guard)
-            if ((item["type"] === "option" || !item["type"]) && item["value"] === "" && item["text"] === "")
+            if ((item["type"] === "option" || !item["type"]) &&
+                item["value"] === "" &&
+                item["text"] === "")
                 return;
-            if (item instanceof HTMLOptionElement || item instanceof HTMLOptGroupElement) {
+            if (item instanceof HTMLOptionElement ||
+                item instanceof HTMLOptGroupElement) {
                 select.appendChild(item);
                 return;
             }
@@ -5740,7 +5581,8 @@ class SearchController extends Lifecycle {
                                 option.dataset[key] = String(opt.data[key]);
                             });
                         }
-                        if (opt.selected || (keepSelected && oldSelected.includes(option.value))) {
+                        if (opt.selected ||
+                            (keepSelected && oldSelected.includes(option.value))) {
                             option.selected = true;
                         }
                         optgroup.appendChild(option);
@@ -5757,7 +5599,8 @@ class SearchController extends Lifecycle {
                         option.dataset[key] = String(item.data[key]);
                     });
                 }
-                if (item.selected || (keepSelected && oldSelected.includes(option.value))) {
+                if (item.selected ||
+                    (keepSelected && oldSelected.includes(option.value))) {
                     option.selected = true;
                 }
                 select.appendChild(option);
@@ -5833,16 +5676,6 @@ class SelectObserver {
      * @param {HTMLSelectElement} select - The `<select>` element to observe for mutations.
      */
     constructor(select) {
-        /**
-         * Debounce timer handle for batching rapid mutations.
-         *
-         * - Cleared and reset on each mutation event.
-         * - Invokes {@link handleChange} after {@link _DEBOUNCE_DELAY} milliseconds of inactivity.
-         * - Nulled during {@link disconnect}.
-         *
-         * @private
-         */
-        this.debounceTimer = null;
         /**
          * Debounce delay in milliseconds.
          *
@@ -5983,16 +5816,12 @@ class DatasetObserver {
      * @param element - The element whose `data-*` attributes will be observed.
      */
     constructor(element) {
-        /**
-         * Debounce timer handle for coalescing rapid attribute mutations.
-         * Cleared/replaced whenever a new relevant mutation arrives within the debounce window.
-         */
-        this.debounceTimer = null;
         this.element = element;
         this.observer = new MutationObserver((mutations) => {
             let datasetChanged = false;
             for (const mutation of mutations) {
-                if (mutation.type === "attributes" && mutation.attributeName?.startsWith("data-")) {
+                if (mutation.type === "attributes" &&
+                    mutation.attributeName?.startsWith("data-")) {
                     datasetChanged = true;
                     break;
                 }
@@ -6141,6 +5970,16 @@ class Adapter extends Lifecycle {
          * This flag is intentionally generic and is coordinated by higher-level components.
          */
         this.isSkipEvent = false;
+        /**
+         * Tracks all scheduler keys registered by this adapter instance via
+         * {@link onPropChanging} and {@link onPropChanged}.
+         *
+         * Used during {@link destroy} to clean up all associated pipelines
+         * from the global {@link Libs.callbackScheduler}.
+         *
+         * Keys are deduplicated automatically by Set semantics.
+         */
+        this.callbackSchedulerList = new Set();
         this.items = items;
         this.init();
     }
@@ -6182,7 +6021,9 @@ class Adapter extends Lifecycle {
      * @see {@link changingProp}
      */
     onPropChanging(propName, callback) {
-        Libs.callbackScheduler.on(`${propName}ing_${this.adapterKey}`, callback, { debounce: 0 });
+        const key = `${propName}ing_${this.adapterKey}`;
+        Libs.callbackScheduler.on(key, callback, { debounce: 0 });
+        this.callbackSchedulerList.add(key);
     }
     /**
      * Registers a **post-change** callback for a property pipeline.
@@ -6198,7 +6039,11 @@ class Adapter extends Lifecycle {
      * @see {@link changeProp}
      */
     onPropChanged(propName, callback) {
-        Libs.callbackScheduler.on(`${propName}_${this.adapterKey}`, callback, { debounce: 0 });
+        const key = `${propName}_${this.adapterKey}`;
+        Libs.callbackScheduler.on(key, callback, {
+            debounce: 0,
+        });
+        this.callbackSchedulerList.add(key);
     }
     /**
      * Triggers the **post-change** pipeline for a given property.
@@ -6233,7 +6078,7 @@ class Adapter extends Lifecycle {
      *
      * @param {HTMLElement} parent - Container element that will host the viewer.
      * @param {TItem} item - The model for which the viewer is created.
-     * @returns {TViewer | null} The created viewer instance; `null` by default.
+     * @returns {TViewer} The created viewer instance; `null` by default.
      */
     viewHolder(parent, item) {
         return null;
@@ -6339,11 +6184,16 @@ class Adapter extends Lifecycle {
         if (this.is(LifecycleState.DESTROYED)) {
             return;
         }
+        this.callbackSchedulerList.forEach((key) => {
+            Libs.callbackScheduler.off(key);
+        });
+        this.callbackSchedulerList.clear();
         this.recyclerView = null;
-        this.items.forEach(item => {
+        this.items.forEach((item) => {
             item?.destroy?.();
         });
         this.items = [];
+        super.destroy();
     }
 }
 
@@ -6395,20 +6245,6 @@ class View extends Lifecycle {
      */
     constructor(parent) {
         super();
-        /**
-         * Host container element into which this view's root element is rendered/attached.
-         *
-         * This reference is captured at construction time and cleared on {@link destroy}.
-         */
-        this.parent = null;
-        /**
-         * Mounted view result containing:
-         * - `view`: the root element of this view
-         * - `tags`: a strongly-typed map of child elements for fast access
-         *
-         * This is expected to be assigned by subclasses (or a mount helper) before {@link getView} is called.
-         */
-        this.view = null;
         this.parent = parent;
         this.init();
     }
@@ -6509,29 +6345,6 @@ class GroupView extends View {
      */
     constructor(parent, options) {
         super(parent);
-        /**
-         * Strongly-typed reference to the mounted group view structure.
-         *
-         * Structure:
-         * - **view**: Root container element.
-         * - **tags**: Named references to header and items container.
-         *
-         * Lifecycle:
-         * - `null` until {@link mount} completes.
-         * - Cleared during {@link destroy}.
-         *
-         * @public
-         */
-        this.view = null;
-        /**
-         * Parsed configuration (bound from the `<select>` element via binder map).
-         *
-         * Provides feature flags (multiple/disabled/readonly/visible/virtualScroll/ajax/autoclose…),
-         * a11y ids (e.g. `SEID_LIST`, `SEID_HOLDER`) and user callbacks under `options.on`.
-         *
-         * @internal
-         */
-        this.options = null;
         this.options = options;
     }
     /**
@@ -6625,10 +6438,10 @@ class GroupView extends View {
      * - Safe to call multiple times with same value (idempotent).
      *
      * @public
-     * @param {string | null} [label=null] - New label to display; `null` preserves current label.
+     * @param {string} [label=null] - New label to display; `null` preserves current label.
      * @returns {void}
      */
-    updateLabel(label = null) {
+    updateLabel(label) {
         if (!this.view)
             return;
         const headerEl = this.view.tags.GroupHeader;
@@ -6675,7 +6488,7 @@ class GroupView extends View {
         if (!this.view)
             return;
         const items = this.view.tags.GroupItems;
-        const visibleItems = Array.from(items.children).filter(child => !child.classList.contains("hide"));
+        const visibleItems = Array.from(items.children).filter((child) => !child.classList.contains("hide"));
         this.view.view.classList.toggle("hide", visibleItems.length === 0);
     }
     /**
@@ -6789,57 +6602,6 @@ class OptionView extends View {
      */
     constructor(parent, options) {
         super(parent);
-        /**
-         * Strongly-typed reference to the mounted option view structure.
-         *
-         * Structure:
-         * - **view**: Root container element.
-         * - **tags**: Named references to input, image (conditional), label, label content.
-         *
-         * Lifecycle:
-         * - `null` until {@link mount} completes.
-         * - Cleared during {@link destroy}.
-         *
-         * @public
-         */
-        this.view = null;
-        /**
-         * Parsed configuration (bound from the `<select>` element via binder map).
-         *
-         * Provides feature flags (multiple/disabled/readonly/visible/virtualScroll/ajax/autoclose…),
-         * a11y ids (e.g. `SEID_LIST`, `SEID_HOLDER`) and user callbacks under `options.on`.
-         *
-         * @internal
-         */
-        this.options = null;
-        /**
-         * Internal configuration object (Proxy target).
-         *
-         * Lifecycle:
-         * - Initialized during {@link initialize} with default values.
-         * - Mutated via {@link configProxy} Proxy trap.
-         *
-         * Notes:
-         * - **Should not be mutated directly**; use {@link configProxy} or typed setters.
-         * - Contains default values for layout, image, and alignment.
-         *
-         * @private
-         */
-        this.config = null;
-        /**
-         * Reactive Proxy wrapper around {@link config}.
-         *
-         * Behavior:
-         * - Intercepts property assignments via `set` trap.
-         * - Triggers {@link applyPartialChange} for diffed values when {@link isRendered} is `true`.
-         * - Prevents redundant DOM updates when value hasn't changed.
-         *
-         * Usage:
-         * - Accessed via {@link optionConfig} getter or typed setters ({@link isMultiple}, {@link hasImage}).
-         *
-         * @private
-         */
-        this.configProxy = null;
         /**
          * Flag indicating whether the initial render has completed.
          *
@@ -7004,24 +6766,30 @@ class OptionView extends View {
      * - Each changed property triggers {@link applyPartialChange} individually.
      *
      * @public
-     * @param {OptionConfigPatch | null} config - Partial configuration patch; `null` is no-op.
+     * @param {OptionConfigPatch} config - Partial configuration patch; `null` is no-op.
      * @returns {void}
      */
     set optionConfig(config) {
         if (!config || !this.configProxy || !this.config)
             return;
         const changes = {};
-        if (config.imageWidth !== undefined && config.imageWidth !== this.config.imageWidth)
+        if (config.imageWidth !== undefined &&
+            config.imageWidth !== this.config.imageWidth)
             changes.imageWidth = config.imageWidth;
-        if (config.imageHeight !== undefined && config.imageHeight !== this.config.imageHeight)
+        if (config.imageHeight !== undefined &&
+            config.imageHeight !== this.config.imageHeight)
             changes.imageHeight = config.imageHeight;
-        if (config.imageBorderRadius !== undefined && config.imageBorderRadius !== this.config.imageBorderRadius)
+        if (config.imageBorderRadius !== undefined &&
+            config.imageBorderRadius !== this.config.imageBorderRadius)
             changes.imageBorderRadius = config.imageBorderRadius;
-        if (config.imagePosition !== undefined && config.imagePosition !== this.config.imagePosition)
+        if (config.imagePosition !== undefined &&
+            config.imagePosition !== this.config.imagePosition)
             changes.imagePosition = config.imagePosition;
-        if (config.labelValign !== undefined && config.labelValign !== this.config.labelValign)
+        if (config.labelValign !== undefined &&
+            config.labelValign !== this.config.labelValign)
             changes.labelValign = config.labelValign;
-        if (config.labelHalign !== undefined && config.labelHalign !== this.config.labelHalign)
+        if (config.labelHalign !== undefined &&
+            config.labelHalign !== this.config.labelHalign)
             changes.labelHalign = config.labelHalign;
         if (Object.keys(changes).length > 0) {
             Object.assign(this.configProxy, changes);
@@ -7195,9 +6963,11 @@ class OptionView extends View {
             case "imageBorderRadius": {
                 const img = v.tags?.OptionImage;
                 if (img) {
-                    const styleProp = prop === "imageWidth" ? "width" :
-                        prop === "imageHeight" ? "height" :
-                            "borderRadius";
+                    const styleProp = prop === "imageWidth"
+                        ? "width"
+                        : prop === "imageHeight"
+                            ? "height"
+                            : "borderRadius";
                     img.style[styleProp] = String(newValue);
                 }
                 break;
@@ -7318,15 +7088,6 @@ class MixedAdapter extends Adapter {
         super(items);
         /** Whether the adapter operates in multi-selection mode. */
         this.isMultiple = false;
-        /**
-         * Parsed configuration (bound from the `<select>` element via binder map).
-         *
-         * Provides feature flags (multiple/disabled/readonly/visible/virtualScroll/ajax/autoclose…),
-         * a11y ids (e.g. `SEID_LIST`, `SEID_HOLDER`) and user callbacks under `options.on`.
-         *
-         * @internal
-         */
-        this.options = null;
         /**
          * Subscribers for aggregated visibility statistics.
          * Fired via a debounced scheduler to avoid repeated recomputation during batch updates.
@@ -7337,11 +7098,6 @@ class MixedAdapter extends Adapter {
          * `-1` indicates "no highlight".
          */
         this.currentHighlightIndex = -1;
-        /**
-         * Cached pointer to the selected option in single-select mode.
-         * Used to efficiently clear previous selection when selecting a new option.
-         */
-        this.selectedItemSingle = null;
         /** Top-level group models (if any). */
         this.groups = [];
         /**
@@ -7430,7 +7186,7 @@ class MixedAdapter extends Adapter {
      * - Performs one-time listener binding guarded by `item.isInit`.
      *
      * @param {MixedItem} item - {@link GroupModel} or {@link OptionModel}.
-     * @param {GroupView | OptionView | null} viewer - The view instance that will render the model.
+     * @param {GroupView | OptionView} viewer - The view instance that will render the model.
      * @param {number} position - Position in the top-level mixed list.
      * @returns {void}
      * @override
@@ -7657,7 +7413,7 @@ class MixedAdapter extends Adapter {
             return;
         }
         Libs.callbackScheduler.clear(`sche_vis_${this.adapterKey}`);
-        this.groups.forEach(group => {
+        this.groups.forEach((group) => {
             group.destroy();
         });
         this.visibilityChangedCallbacks = [];
@@ -7737,7 +7493,7 @@ class MixedAdapter extends Adapter {
      * @returns {void}
      */
     resetHighlight() {
-        this.setHighlight(0);
+        this.setHighlight(0, false);
     }
     /**
      * Moves highlight among **visible** options and optionally scrolls the new target into view.
@@ -7780,7 +7536,8 @@ class MixedAdapter extends Adapter {
      * @returns {void}
      */
     selectHighlighted() {
-        if (this.currentHighlightIndex > -1 && this.flatOptions[this.currentHighlightIndex]) {
+        if (this.currentHighlightIndex > -1 &&
+            this.flatOptions[this.currentHighlightIndex]) {
             const item = this.flatOptions[this.currentHighlightIndex];
             if (item.visible) {
                 const viewEl = item.view?.getView?.();
@@ -7817,7 +7574,8 @@ class MixedAdapter extends Adapter {
         else {
             index = 0;
         }
-        if (this.currentHighlightIndex > -1 && this.flatOptions[this.currentHighlightIndex]) {
+        if (this.currentHighlightIndex > -1 &&
+            this.flatOptions[this.currentHighlightIndex]) {
             this.flatOptions[this.currentHighlightIndex].highlighted = false;
         }
         for (let i = index; i < this.flatOptions.length; i++) {
@@ -7828,12 +7586,13 @@ class MixedAdapter extends Adapter {
             this.currentHighlightIndex = i;
             if (isScrollToView) {
                 const el = item.view?.getView?.();
-                if (el) {
-                    el.scrollIntoView({ block: 'center', behavior: 'smooth' });
+                if (el?.isConnected) {
+                    el.scrollIntoView({ block: "center", behavior: "smooth" });
                 }
                 else {
-                    // If virtualized, ensure the item is rendered before trying to scroll.
-                    this.recyclerView?.ensureRendered?.(i, { scrollIntoView: true });
+                    this.recyclerView?.ensureRendered?.(i, {
+                        scrollIntoView: true,
+                    });
                 }
             }
             this.onHighlightChange(i, item.view?.getView?.()?.id);
@@ -8062,9 +7821,9 @@ class VirtualRecyclerView extends RecyclerView {
      *
      * Note: The virtualization scaffold is built when an adapter is set via {@link setAdapter}.
      *
-     * @param {HTMLDivElement | null} [viewElement=null] - Optional root container for the recycler view.
+     * @param {HTMLDivElement} [viewElement=null] - Optional root container for the recycler view.
      */
-    constructor(viewElement = null) {
+    constructor(viewElement) {
         super(viewElement);
         /**
          * Virtualization settings (materialized to `Required<VirtualOptions>`).
@@ -8100,15 +7859,18 @@ class VirtualRecyclerView extends RecyclerView {
         this.start = 0;
         /** Current window end (inclusive). -1 means not initialized. */
         this.end = -1;
-        /** Pending animation frame ids for window and measurement. */
-        this.rafId = null;
-        this.measureRaf = null;
         /** Re-entrancy/suspension flags used to prevent feedback loops. */
         this.updating = false;
         this.suppressResize = false;
         this.lastRenderCount = 0;
         this.suspended = false;
         this.resumeResizeAfter = false;
+        /**
+         * When set, scrollToIndex() will be called after the next measureVisibleAndUpdate()
+         * completes and Fenwick has been updated with real heights.
+         * Set by ensureRendered() and cleared after the corrective scroll fires.
+         */
+        this.pendingScrollToIndex = null;
         /** Small cache for sticky header height (≈16ms TTL) to limit layout reads. */
         this.stickyCacheTick = 0;
         this.stickyCacheVal = 0;
@@ -8157,20 +7919,29 @@ class VirtualRecyclerView extends RecyclerView {
             return;
         this.viewElement.replaceChildren();
         const nodeMounted = Libs.mountNode({
-            PadTop: { tag: { node: "div", classList: "seui-virtual-pad-top" } },
-            ItemsHost: { tag: { node: "div", classList: "seui-virtual-items" } },
-            PadBottom: { tag: { node: "div", classList: "seui-virtual-pad-bottom" } },
+            PadTop: {
+                tag: { node: "div", classList: "seui-virtual-pad-top" },
+            },
+            ItemsHost: {
+                tag: { node: "div", classList: "seui-virtual-items" },
+            },
+            PadBottom: {
+                tag: { node: "div", classList: "seui-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(".seui-popup")
-            ?? this.viewElement.parentElement;
+        this.scrollEl =
+            this.opts.scrollEl ??
+                this.viewElement.closest(".seui-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.scrollEl.addEventListener("scroll", this.boundOnScroll, {
+            passive: true,
+        });
         this.refresh(false);
         this.attachResizeObserverOnce();
         adapter?.onVisibilityChanged?.(() => this.refreshItem());
@@ -8209,7 +7980,9 @@ class VirtualRecyclerView extends RecyclerView {
     resume() {
         this.suspended = false;
         if (this.scrollEl && this.boundOnScroll) {
-            this.scrollEl.addEventListener("scroll", this.boundOnScroll, { passive: true });
+            this.scrollEl.addEventListener("scroll", this.boundOnScroll, {
+                passive: true,
+            });
         }
         if (this.resumeResizeAfter) {
             this.attachResizeObserverOnce();
@@ -8264,9 +8037,19 @@ class VirtualRecyclerView extends RecyclerView {
      * @returns {void}
      */
     ensureRendered(index, opt) {
-        this.mountRange(index, index);
-        if (opt?.scrollIntoView)
-            this.scrollToIndex(index);
+        if (!opt?.scrollIntoView) {
+            // No scroll requested — mount only (legacy path, used by probes).
+            this.mountRange(index, index);
+            return;
+        }
+        // Pass 1: instant — brings window to vicinity, triggers measure.
+        // Must be instant so Pass 2 smooth scroll isn't interrupted mid-animation.
+        this.scrollToIndex(index, "instant");
+        // Pass 2: measureVisibleAndUpdate() will consume this and fire a corrective
+        // smooth scroll after Fenwick has been updated with real heights.
+        // rv.resume() is guaranteed to run before this callback (popup.open onComplete
+        // calls rv.resume() first), so the window is already rendered when we arrive here.
+        this.pendingScrollToIndex = index;
     }
     /**
      * Scrolls the scroll container to align the item at `index` into view.
@@ -8280,15 +8063,25 @@ class VirtualRecyclerView extends RecyclerView {
      * @param {number} index - Item index to bring into view.
      * @returns {void}
      */
-    scrollToIndex(index) {
+    scrollToIndex(index, behavior = "smooth") {
         const count = this.adapter?.itemCount?.() ?? 0;
         if (count <= 0)
             return;
         const topInContainer = this.offsetTopOf(index);
         const containerTop = this.containerTopInScroll();
-        const target = containerTop + topInContainer;
+        const stickyH = this.stickyTopHeight();
+        const viewportH = Math.max(0, this.scrollEl.clientHeight - stickyH);
+        // item height from cache, or current estimate for unmeasured items
+        const est = this.getEstimate();
+        const itemH = this.heightCache[index] ?? est;
+        // Align item center to viewport center (below any sticky header).
+        // viewportH already excludes stickyH, so no further offset needed.
+        // Equivalent to scrollIntoView({ block: "center" }).
+        const centeredTarget = containerTop + topInContainer
+            - (viewportH - itemH) / 3;
         const maxScroll = Math.max(0, this.scrollEl.scrollHeight - this.scrollEl.clientHeight);
-        this.scrollEl.scrollTop = Math.min(Math.max(0, target), maxScroll);
+        const clamped = Math.min(Math.max(0, centeredTarget), maxScroll);
+        this.scrollEl.scrollTo({ top: clamped, behavior });
     }
     /**
      * Disposes runtime resources without destroying the instance.
@@ -8307,7 +8100,7 @@ class VirtualRecyclerView extends RecyclerView {
             this.scrollEl.removeEventListener("scroll", this.boundOnScroll);
         }
         this.resizeObs?.disconnect();
-        this.created.forEach(el => el.remove());
+        this.created.forEach((el) => el.remove());
         this.created.clear();
     }
     /**
@@ -8355,9 +8148,22 @@ class VirtualRecyclerView extends RecyclerView {
         if (count <= 0)
             return;
         this.suspend();
-        this.resetState();
+        this.pendingScrollToIndex = null;
+        // When visibility changes (search filter applied or cleared), heightCache may
+        // contain heights measured while only a subset of items was visible. Re-using
+        // these partial measurements in rebuildFenwick() causes incorrect prefix sums
+        // (e.g. items measured while scrolled into a filtered window have real heights,
+        // while surrounding items still use estimates — creating an uneven Fenwick).
+        //
+        // Safe fix: clear heightCache entirely on visibility change. The adaptive
+        // estimator will re-seed from probeInitialHeight() on the next render, and
+        // items will be re-measured as they scroll into view.
+        this.heightCache = [];
+        this.measuredSum = 0;
+        this.measuredCount = 0;
+        this.firstMeasured = false;
+        this.resetDOM();
         this.cleanupInvisibleItems();
-        this.recomputeMeasuredStats(count);
         this.rebuildFenwick(count);
         this.start = 0;
         this.end = -1;
@@ -8375,7 +8181,30 @@ class VirtualRecyclerView extends RecyclerView {
         }
     }
     /**
-     * Resets internal state: mounted elements, caches, Fenwick sums, padding, and estimator stats.
+     * Resets DOM nodes, Fenwick sums, padding, and estimator stats — but preserves {@link heightCache}.
+     *
+     * Use this inside {@link refreshItem} so that {@link recomputeMeasuredStats} can still
+     * read previously measured heights before the Fenwick tree is rebuilt.
+     *
+     * DOM side effects:
+     * - Removes all currently mounted item elements tracked in {@link created}.
+     * - Resets pad heights to `0px`.
+     *
+     * @returns {void}
+     */
+    resetDOM() {
+        this.created.forEach((el) => el.remove());
+        this.created.clear();
+        this.fenwick.reset(0);
+        this.PadTop.style.height = "0px";
+        this.PadBottom.style.height = "0px";
+        this.firstMeasured = false;
+    }
+    /**
+     * Full reset: clears DOM nodes, Fenwick sums, padding, estimator stats, AND {@link heightCache}.
+     *
+     * Use this for complete teardown (e.g., adapter swap, destroy sequence) where all
+     * cached measurements should be discarded.
      *
      * DOM side effects:
      * - Removes all currently mounted item elements tracked in {@link created}.
@@ -8384,7 +8213,7 @@ class VirtualRecyclerView extends RecyclerView {
      * @returns {void}
      */
     resetState() {
-        this.created.forEach(el => el.remove());
+        this.created.forEach((el) => el.remove());
         this.created.clear();
         this.heightCache = [];
         this.fenwick.reset(0);
@@ -8658,8 +8487,12 @@ class VirtualRecyclerView extends RecyclerView {
         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);
+        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);
@@ -8681,7 +8514,10 @@ class VirtualRecyclerView extends RecyclerView {
         if (this.resizeObs)
             return;
         this.resizeObs = new ResizeObserver(() => {
-            if (this.suppressResize || this.suspended || !this.adapter || this.measureRaf != null)
+            if (this.suppressResize ||
+                this.suspended ||
+                !this.adapter ||
+                this.measureRaf != null)
                 return;
             this.measureRaf = requestAnimationFrame(() => {
                 this.measureRaf = null;
@@ -8722,6 +8558,15 @@ class VirtualRecyclerView extends RecyclerView {
                 this.rebuildFenwick(count);
             this.scheduleUpdateWindow();
         }
+        // Corrective scroll: if ensureRendered() registered a target index, fire
+        // scrollToIndex() now that real heights are in Fenwick. Clear the target
+        // first to prevent infinite re-triggering (scrollToIndex may cause another
+        // measure cycle, but heights won't change so changed === false next time).
+        if (this.pendingScrollToIndex !== null) {
+            const target = this.pendingScrollToIndex;
+            this.pendingScrollToIndex = null;
+            this.scrollToIndex(target, "smooth");
+        }
     }
     /**
      * Scroll event handler. Schedules a window update on the next frame.
@@ -9010,31 +8855,6 @@ class SelectBox extends Lifecycle {
          * @internal
          */
         this.oldValue = null;
-        /**
-         * Root wrapper DOM node for the enhanced UI.
-         *
-         * Created during {@link init} via {@link Libs.mountNode}, inserted into the DOM during {@link mount},
-         * and removed during {@link destroy}.
-         */
-        this.node = null;
-        /**
-         * Parsed configuration (bound from the `<select>` element via binder map).
-         *
-         * Provides feature flags (multiple/disabled/readonly/visible/virtualScroll/ajax/autoclose…),
-         * a11y ids (e.g. `SEID_LIST`, `SEID_HOLDER`) and user callbacks under `options.on`.
-         *
-         * @internal
-         */
-        this.options = null;
-        /**
-         * Manager that owns model resources and bridges the Adapter ↔ RecyclerView pipeline.
-         *
-         * The configured adapter is {@link MixedAdapter}. The recyclerview implementation is chosen
-         * based on `options.virtualScroll` (standard {@link RecyclerView} vs {@link VirtualRecyclerView}).
-         *
-         * @internal
-         */
-        this.optionModelManager = null;
         /**
          * Whether the popup/list UI is currently open.
          *
@@ -9066,20 +8886,10 @@ class SelectBox extends Lifecycle {
          * @internal
          */
         this.hasDeInitialized = false;
-        /**
-         * Selective context (global helper / registry).
-         *
-         * Used to locate the instance wrapper via `Selective.find(...)` and to close other open instances.
-         */
-        this.Selective = null;
         /**
          * Registered plugins for this SelectBox instance.
          */
         this.plugins = [];
-        /**
-         * Cached plugin context for this SelectBox instance.
-         */
-        this.pluginContext = null;
         if (select && Selective)
             this.initialize(select, Selective);
     }
@@ -9204,7 +9014,9 @@ class SelectBox extends Lifecycle {
                             classList: "seui-view",
                             tabIndex: 0,
                             onkeydown: (e) => {
-                                if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown") {
+                                if (e.key === "Enter" ||
+                                    e.key === " " ||
+                                    e.key === "ArrowDown") {
                                     e.preventDefault();
                                     this.getAction()?.open();
                                 }
@@ -9310,6 +9122,7 @@ class SelectBox extends Lifecycle {
             e.preventDefault();
         });
         Refresher.resizeBox(select, container.tags.ViewPanel);
+        Refresher.resizeBox(select, this.node, true);
         select.classList.add("init");
         // initial mask
         const action = this.getAction();
@@ -9596,7 +9409,11 @@ class SelectBox extends Lifecycle {
             get value() {
                 const item_list = this.valueArray;
                 const valLength = item_list.length;
-                return valLength > 1 ? item_list : valLength === 0 ? "" : item_list[0];
+                return valLength > 1
+                    ? item_list
+                    : valLength === 0
+                        ? ""
+                        : item_list[0];
             },
             get valueArray() {
                 const item_list = [];
@@ -9621,7 +9438,7 @@ class SelectBox extends Lifecycle {
             get mask() {
                 const item_list = [];
                 superThis.getModelOption(true).forEach((m) => {
-                    item_list.push(m.text);
+                    item_list.push(m.mask);
                 });
                 return item_list;
             },
@@ -9631,7 +9448,11 @@ class SelectBox extends Lifecycle {
                     item_list.push(m.text);
                 });
                 const valLength = item_list.length;
-                return valLength > 1 ? item_list : valLength === 0 ? "" : item_list[0];
+                return valLength > 1
+                    ? item_list
+                    : valLength === 0
+                        ? ""
+                        : item_list[0];
             },
             get isOpen() {
                 return superThis.isOpen;
@@ -9656,7 +9477,8 @@ class SelectBox extends Lifecycle {
             },
             selectAll(_evtToken, trigger = true) {
                 if (bindedOptions.multiple && bindedOptions.maxSelected > 0) {
-                    if (superThis.getModelOption().length > bindedOptions.maxSelected)
+                    if (superThis.getModelOption().length >
+                        bindedOptions.maxSelected)
                         return;
                 }
                 if (this.disabled || this.readonly || !bindedOptions.multiple)
@@ -9688,7 +9510,7 @@ class SelectBox extends Lifecycle {
             },
             deSelectByDataset(_evtToken, dataset, trigger = true) {
                 if (dataset) {
-                    superThis.getModelOption().forEach(optionModel => {
+                    superThis.getModelOption().forEach((optionModel) => {
                         if (optionModel.dataset) {
                             for (let searchKey in dataset) {
                                 let value = dataset[searchKey];
@@ -9702,12 +9524,14 @@ class SelectBox extends Lifecycle {
                     this.change(false, trigger);
                 }
             },
-            setValue(_evtToken = null, value, trigger = true, force = false) {
+            setValue(_evtToken, value, trigger = true, force = false) {
                 if (!Array.isArray(value))
                     value = [value];
                 value = value.filter((v) => v !== "" && v != null);
                 if (value.length === 0) {
-                    superThis.getModelOption().forEach((m) => (m.selectedNonTrigger = false));
+                    superThis
+                        .getModelOption()
+                        .forEach((m) => (m.selectedNonTrigger = false));
                     this.change(false, trigger);
                     return;
                 }
@@ -9721,17 +9545,19 @@ class SelectBox extends Lifecycle {
                     return;
                 // AJAX: load missing values
                 if (container.searchController?.isAjax?.()) {
+                    container.searchController.resetPagination();
+                    superThis.hasLoadedOnce = false;
                     const { missing } = container.searchController.checkMissingValues(value);
                     if (missing.length > 0) {
                         (async () => {
                             if (bindedOptions.loadingfield)
                                 container.popup?.showLoading?.();
                             try {
-                                container.searchController.resetPagination();
                                 const result = await container.searchController.loadByValues(missing);
                                 if (result.success && result.items.length > 0) {
                                     result.items.forEach((it) => {
-                                        if (missing.includes(it.value) || missing.includes(it.text))
+                                        if (missing.includes(it.value) ||
+                                            missing.includes(it.text))
                                             it.selected = true;
                                     });
                                     container.searchController.applyAjaxResult?.(result.items, false, false);
@@ -9742,6 +9568,10 @@ class SelectBox extends Lifecycle {
                                 }
                                 else if (missing.length > 0) {
                                     console.warn(`Could not load ${missing.length} values:`, missing);
+                                    setTimeout(() => {
+                                        container.searchController.resetPagination();
+                                        this.change(false, trigger);
+                                    }, 200);
                                 }
                             }
                             catch (error) {
@@ -9770,7 +9600,8 @@ class SelectBox extends Lifecycle {
                 this.change(false, trigger);
             },
             load() {
-                if ((!superThis.hasLoadedOnce || superThis.isBeforeSearch) && bindedOptions?.ajax) {
+                if ((!superThis.hasLoadedOnce || superThis.isBeforeSearch) &&
+                    bindedOptions?.ajax) {
                     container.searchController.resetPagination();
                     container.popup.showLoading();
                     superThis.hasLoadedOnce = true;
@@ -9816,7 +9647,13 @@ class SelectBox extends Lifecycle {
                     adapter.resetHighlight();
                 }
                 this.load();
-                container.popup.open(null, !container.popup.loadingState.isVisible);
+                container.popup.open(() => {
+                    setTimeout(() => {
+                        if (selectedOption) {
+                            adapter.setHighlight(selectedOption, bindedOptions.autoscroll);
+                        }
+                    }, 100);
+                }, !container.popup.loadingState.isVisible);
                 container.searchbox.show();
                 const ViewPanel = container.tags.ViewPanel;
                 ViewPanel.setAttribute("aria-expanded", "true");
@@ -9857,9 +9694,10 @@ class SelectBox extends Lifecycle {
                 else
                     this.open();
             },
-            change(_evtToken = null, canTrigger = true) {
+            change(_evtToken, canTrigger = true) {
                 if (canTrigger) {
-                    if (bindedOptions.multiple && bindedOptions.maxSelected > 0) {
+                    if (bindedOptions.multiple &&
+                        bindedOptions.maxSelected > 0) {
                         if (this.valueArray.length > bindedOptions.maxSelected) {
                             this.setValue(null, this.oldValue, false, true);
                         }
@@ -9894,7 +9732,8 @@ class SelectBox extends Lifecycle {
             },
             refreshMask() {
                 let mask = bindedOptions.placeholder;
-                if (!bindedOptions.multiple && superThis.getModelOption().length > 0) {
+                if (!bindedOptions.multiple &&
+                    superThis.getModelOption().length > 0) {
                     mask = this.mask[0];
                 }
                 mask ?? (mask = bindedOptions.placeholder);
@@ -9926,7 +9765,9 @@ class SelectBox extends Lifecycle {
                             .search("")
                             .then(() => {
                             container.popup?.triggerResize?.();
-                            resove(getInstance());
+                            setTimeout(() => {
+                                resove(getInstance());
+                            }, 60);
                         })
                             .catch((err) => {
                             console.error("Initial ajax load error:", err);
@@ -9976,7 +9817,8 @@ class SelectBox extends Lifecycle {
             set(value) {
                 superThis[privateProp] = !!value;
                 if (superThis.container?.targetElement?.dataset) {
-                    superThis.container.targetElement.dataset[prop] = String(!!value);
+                    superThis.container.targetElement.dataset[prop] =
+                        String(!!value);
                 }
             },
             enumerable: true,
@@ -10004,7 +9846,7 @@ class SelectBox extends Lifecycle {
      * @returns A flat array of option models (possibly filtered).
      * @internal
      */
-    getModelOption(isSelected = null) {
+    getModelOption(isSelected) {
         if (!this.optionModelManager)
             return [];
         const { modelList } = this.optionModelManager.getResources();
@@ -10084,14 +9926,6 @@ class ElementAdditionObserver {
          * @internal
          */
         this.isActive = false;
-        /**
-         * Underlying DOM {@link MutationObserver} instance.
-         *
-         * `null` when disconnected.
-         *
-         * @internal
-         */
-        this.observer = null;
         /**
          * Registered detection callbacks.
          *
@@ -10685,7 +10519,7 @@ class Selective extends Lifecycle {
         if (wasObserving)
             this.EAObserver?.disconnect();
         bindMap.self?.deInit?.();
-        const wrapper = (bindMap.container?.element) ?? selectElement.parentElement;
+        const wrapper = bindMap.container?.element ?? selectElement.parentElement;
         selectElement.style.display = "";
         selectElement.style.visibility = "";
         selectElement.disabled = false;
@@ -10905,7 +10739,7 @@ const SECLASS = new Selective();
  *
  * Declared as `const` literal type to enable strict typing and easy tree-shaking.
  */
-const version = "1.4.0";
+const version = "1.4.2";
 /**
  * Library name identifier.
  *
@@ -10951,7 +10785,7 @@ function find(query) {
  * // Destroy all instances
  * destroy();
  */
-function destroy(query = null) {
+function destroy(query) {
     SECLASS.destroy(query);
 }
 /**