selective-ui 1.4.0 → 1.4.2

package/dist/selective-ui.umd.js

@@ -1,4 +1,4 @@
-/*! Selective UI v1.4.0 | MIT License */
+/*! Selective UI v1.4.2 | MIT License */
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
     typeof define === 'function' && define.amd ? define(['exports'], factory) :
@@ -153,7 +153,7 @@
          *
          * @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}
          */
@@ -241,7 +241,8 @@
                                 await resp;
                             }
                         }
-                        catch { }
+                        catch {
+                        }
                         finally {
                             if (entry.once) {
                                 executes[i] = undefined;
@@ -374,9 +375,11 @@
          * @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);
@@ -448,11 +451,13 @@
          * @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);
@@ -669,7 +674,8 @@
                         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);
                     }
                 }
@@ -699,7 +705,10 @@
         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");
         }
         /**
@@ -741,7 +750,8 @@
          */
         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.
@@ -763,14 +773,16 @@
             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.
@@ -966,8 +978,9 @@
          *
          * @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;
@@ -987,7 +1000,12 @@
                 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 });
+            }
         }
     }
 
@@ -1297,25 +1315,6 @@
          */
         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);
         }
@@ -1540,34 +1539,8 @@
          *
          * @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.
              *
@@ -1655,7 +1628,8 @@
         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.
@@ -1712,7 +1686,7 @@
          *
          * @param action - Callback invoked on activation; ignored when not a function.
          */
-        onSelectAll(action = null) {
+        onSelectAll(action) {
             if (typeof action === "function") {
                 this.actionOnSelectAll.push(action);
             }
@@ -1728,7 +1702,7 @@
          *
          * @param action - Callback invoked on activation; ignored when not a function.
          */
-        onDeSelectAll(action = null) {
+        onDeSelectAll(action) {
             if (typeof action === "function") {
                 this.actionOnDeSelectAll.push(action);
             }
@@ -1796,26 +1770,10 @@
          * 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);
         }
@@ -1941,25 +1899,10 @@
          * 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);
         }
@@ -2117,27 +2060,6 @@
              * 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);
         }
@@ -2183,7 +2105,8 @@
                 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 = {
@@ -2315,36 +2238,10 @@
          * @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) */
@@ -2352,7 +2249,7 @@
                 /** 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) {
@@ -2399,7 +2296,8 @@
                 },
             }, 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();
@@ -2408,7 +2306,7 @@
                     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
@@ -2435,7 +2333,11 @@
          * - 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);
@@ -2453,7 +2355,10 @@
          * 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);
@@ -2494,7 +2399,10 @@
          * @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) {
@@ -2578,8 +2486,12 @@
          * @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();
@@ -2628,8 +2540,11 @@
          *
          * @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?.();
@@ -2788,7 +2703,9 @@
             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);
             }
@@ -2888,78 +2805,8 @@
          *
          * @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);
@@ -3225,17 +3072,7 @@
          *
          * @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.
              *
@@ -3419,7 +3256,9 @@
             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(() => {
@@ -3557,7 +3396,9 @@
                 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");
@@ -3673,25 +3514,11 @@
          * - 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).
@@ -3723,7 +3550,7 @@
          * - 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) {
@@ -3923,7 +3750,7 @@
             if (this.is(LifecycleState.DESTROYED)) {
                 return;
             }
-            this.items.forEach(item => {
+            this.items.forEach((item) => {
                 item.destroy();
             });
             this.items = [];
@@ -4047,10 +3874,10 @@
          * 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).
@@ -4074,11 +3901,6 @@
             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.
@@ -4207,6 +4029,32 @@
             }
             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).
          *
@@ -4220,7 +4068,7 @@
          * @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);
         }
@@ -4233,7 +4081,9 @@
          * @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.
@@ -4414,8 +4264,6 @@
         constructor(options) {
             super();
             this.privModelList = [];
-            this.privAdapterHandle = null;
-            this.privRecyclerViewHandle = null;
             this.options = null;
             this.oldPosition = 0;
             this.options = options;
@@ -4467,7 +4315,9 @@
                 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;
                     }
@@ -4892,44 +4742,10 @@
         /**
          * 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.
@@ -5237,15 +5053,6 @@
          */
         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.
@@ -5309,7 +5116,11 @@
          */
         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)
@@ -5326,7 +5137,7 @@
                         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;
@@ -5336,7 +5147,9 @@
                     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 {
@@ -5373,7 +5186,7 @@
          * 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) {
@@ -5563,7 +5376,12 @@
                     payload.selectedValue = selectedValues;
             }
             else {
-                payload = { search: keyword, page, selectedValue: selectedValues, ...(cfg.data ?? {}) };
+                payload = {
+                    search: keyword,
+                    page,
+                    selectedValue: selectedValues,
+                    ...(cfg.data ?? {}),
+                };
             }
             try {
                 let response;
@@ -5573,13 +5391,17 @@
                     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);
@@ -5653,7 +5475,7 @@
                     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)) {
@@ -5664,23 +5486,39 @@
                 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)
@@ -5722,9 +5560,12 @@
                 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;
                 }
@@ -5746,7 +5587,8 @@
                                     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);
@@ -5763,7 +5605,8 @@
                             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);
@@ -5839,16 +5682,6 @@
          * @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.
              *
@@ -5989,16 +5822,12 @@
          * @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;
                     }
@@ -6147,6 +5976,16 @@
              * 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();
         }
@@ -6188,7 +6027,9 @@
          * @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.
@@ -6204,7 +6045,11 @@
          * @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.
@@ -6239,7 +6084,7 @@
          *
          * @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;
@@ -6345,11 +6190,16 @@
             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();
         }
     }
 
@@ -6401,20 +6251,6 @@
          */
         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();
         }
@@ -6515,29 +6351,6 @@
          */
         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;
         }
         /**
@@ -6631,10 +6444,10 @@
          * - 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;
@@ -6681,7 +6494,7 @@
             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);
         }
         /**
@@ -6795,57 +6608,6 @@
          */
         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.
              *
@@ -7010,24 +6772,30 @@
          * - 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);
@@ -7201,9 +6969,11 @@
                 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;
@@ -7324,15 +7094,6 @@
             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.
@@ -7343,11 +7104,6 @@
              * `-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 = [];
             /**
@@ -7436,7 +7192,7 @@
          * - 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
@@ -7663,7 +7419,7 @@
                 return;
             }
             Libs.callbackScheduler.clear(`sche_vis_${this.adapterKey}`);
-            this.groups.forEach(group => {
+            this.groups.forEach((group) => {
                 group.destroy();
             });
             this.visibilityChangedCallbacks = [];
@@ -7743,7 +7499,7 @@
          * @returns {void}
          */
         resetHighlight() {
-            this.setHighlight(0);
+            this.setHighlight(0, false);
         }
         /**
          * Moves highlight among **visible** options and optionally scrolls the new target into view.
@@ -7786,7 +7542,8 @@
          * @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?.();
@@ -7823,7 +7580,8 @@
             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++) {
@@ -7834,12 +7592,13 @@
                 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);
@@ -8068,9 +7827,9 @@
          *
          * 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>`).
@@ -8106,15 +7865,18 @@
             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;
@@ -8163,20 +7925,29 @@
                 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());
@@ -8215,7 +7986,9 @@
         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();
@@ -8270,9 +8043,19 @@
          * @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.
@@ -8286,15 +8069,25 @@
          * @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.
@@ -8313,7 +8106,7 @@
                 this.scrollEl.removeEventListener("scroll", this.boundOnScroll);
             }
             this.resizeObs?.disconnect();
-            this.created.forEach(el => el.remove());
+            this.created.forEach((el) => el.remove());
             this.created.clear();
         }
         /**
@@ -8361,9 +8154,22 @@
             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;
@@ -8381,7 +8187,30 @@
             }
         }
         /**
-         * 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}.
@@ -8390,7 +8219,7 @@
          * @returns {void}
          */
         resetState() {
-            this.created.forEach(el => el.remove());
+            this.created.forEach((el) => el.remove());
             this.created.clear();
             this.heightCache = [];
             this.fenwick.reset(0);
@@ -8664,8 +8493,12 @@
             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);
@@ -8687,7 +8520,10 @@
             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;
@@ -8728,6 +8564,15 @@
                     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.
@@ -9016,31 +8861,6 @@
              * @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.
              *
@@ -9072,20 +8892,10 @@
              * @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);
         }
@@ -9210,7 +9020,9 @@
                                 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();
                                     }
@@ -9316,6 +9128,7 @@
                 e.preventDefault();
             });
             Refresher.resizeBox(select, container.tags.ViewPanel);
+            Refresher.resizeBox(select, this.node, true);
             select.classList.add("init");
             // initial mask
             const action = this.getAction();
@@ -9602,7 +9415,11 @@
                 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 = [];
@@ -9627,7 +9444,7 @@
                 get mask() {
                     const item_list = [];
                     superThis.getModelOption(true).forEach((m) => {
-                        item_list.push(m.text);
+                        item_list.push(m.mask);
                     });
                     return item_list;
                 },
@@ -9637,7 +9454,11 @@
                         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;
@@ -9662,7 +9483,8 @@
                 },
                 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)
@@ -9694,7 +9516,7 @@
                 },
                 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];
@@ -9708,12 +9530,14 @@
                         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;
                     }
@@ -9727,17 +9551,19 @@
                         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);
@@ -9748,6 +9574,10 @@
                                     }
                                     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) {
@@ -9776,7 +9606,8 @@
                     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;
@@ -9822,7 +9653,13 @@
                         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");
@@ -9863,9 +9700,10 @@
                     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);
                             }
@@ -9900,7 +9738,8 @@
                 },
                 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);
@@ -9932,7 +9771,9 @@
                                 .search("")
                                 .then(() => {
                                 container.popup?.triggerResize?.();
-                                resove(getInstance());
+                                setTimeout(() => {
+                                    resove(getInstance());
+                                }, 60);
                             })
                                 .catch((err) => {
                                 console.error("Initial ajax load error:", err);
@@ -9982,7 +9823,8 @@
                 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,
@@ -10010,7 +9852,7 @@
          * @returns A flat array of option models (possibly filtered).
          * @internal
          */
-        getModelOption(isSelected = null) {
+        getModelOption(isSelected) {
             if (!this.optionModelManager)
                 return [];
             const { modelList } = this.optionModelManager.getResources();
@@ -10090,14 +9932,6 @@
              * @internal
              */
             this.isActive = false;
-            /**
-             * Underlying DOM {@link MutationObserver} instance.
-             *
-             * `null` when disconnected.
-             *
-             * @internal
-             */
-            this.observer = null;
             /**
              * Registered detection callbacks.
              *
@@ -10691,7 +10525,7 @@
             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;
@@ -10908,7 +10742,7 @@
     if (typeof globalThis.GLOBAL_SEUI == "undefined") {
         const SECLASS = new Selective();
         globalThis.GLOBAL_SEUI = {
-            version: "1.4.0",
+            version: "1.4.2",
             name: "SelectiveUI",
             bind: SECLASS.bind.bind(SECLASS),
             find: SECLASS.find.bind(SECLASS),
@@ -10916,7 +10750,7 @@
             effector: Effector.bind(Effector),
             rebind: SECLASS.rebind.bind(SECLASS),
             registerPlugin: SECLASS.registerPlugin.bind(SECLASS),
-            unregisterPlugin: SECLASS.unregisterPlugin.bind(SECLASS)
+            unregisterPlugin: SECLASS.unregisterPlugin.bind(SECLASS),
         };
         let domInitialized = false;
         function init() {
@@ -10941,7 +10775,7 @@
                 init();
             }
         }
-        console.log(`[${"SelectiveUI"}] v${"1.4.0"} loaded successfully`);
+        console.log(`[${"SelectiveUI"}] v${"1.4.2"} loaded successfully`);
     }
     else {
         console.warn(`[${globalThis.GLOBAL_SEUI.name}] Already loaded (v${globalThis.GLOBAL_SEUI.version}). ` +
@@ -10998,7 +10832,7 @@
      * // Destroy all instances
      * destroy();
      */
-    function destroy(query = null) {
+    function destroy(query) {
         globalThis.GLOBAL_SEUI.destroy(query);
     }
     /**