selective-ui 1.2.3 → 1.2.4

package/dist/selective-ui.esm.js

@@ -1,4 +1,4 @@
-/*! Selective UI v1.2.3 | MIT License */
+/*! Selective UI v1.2.4 | MIT License */
 /**
  * @class
  */
@@ -38,7 +38,7 @@ class iStorage {
             textAccessoryDeselect: "Deselect: ",
             animationtime: 200, // millisecond
             delaysearchtime: 200, // millisecond
-            allowHtml: true,
+            allowHtml: false,
             maxSelected: 0,
             labelHalign: "left",
             labelValign: "center",
@@ -830,112 +830,425 @@ class Refresher {
 }
 
 /**
- * @class
+ * Enumerates the finite lifecycle states used across core classes (e.g., View/Model).
+ *
+ * State flow (happy path):
+ * NEW → INITIALIZED → MOUNTED → UPDATED → DESTROYED
+ *
+ * Notes:
+ * - `UPDATED` may be emitted multiple times after mount, depending on implementation.
+ * - `DESTROYED` is terminal; no further transitions should occur.
+ */
+var LifecycleState;
+(function (LifecycleState) {
+    /** The instance has been created but not initialized. */
+    LifecycleState["NEW"] = "new";
+    /** Initialization logic has completed; ready to be mounted. */
+    LifecycleState["INITIALIZED"] = "initialized";
+    /** The instance is mounted/attached to its environment (e.g., DOM). */
+    LifecycleState["MOUNTED"] = "mounted";
+    /**
+     * The instance has been updated at least once after being mounted.
+     * Further updates typically keep the state at UPDATED.
+     */
+    LifecycleState["UPDATED"] = "updated";
+    /** Teardown has run; resources/hooks have been released. */
+    LifecycleState["DESTROYED"] = "destroyed";
+})(LifecycleState || (LifecycleState = {}));
+
+/**
+ * Lightweight lifecycle manager that provides:
+ * - A finite-state lifecycle machine (`NEW` → `INITIALIZED` → `MOUNTED` → `UPDATED` → `DESTROYED`)
+ * - A simple hooks system to subscribe to lifecycle events (`onInit`, `onMount`, `onUpdate`, `onDestroy`)
+ *
+ * Classes in the core (e.g., Model/View) can extend this to standardize initialization,
+ * mounting, updates, and teardown. Hooks are stored as in-memory callbacks and cleared on destroy.
  */
-class PlaceHolder {
+class Lifecycle {
+    /**
+     * Constructs the lifecycle manager and pre-registers hook containers.
+     * No hooks are executed during construction.
+     */
+    constructor() {
+        /** Current lifecycle state */
+        this.state = LifecycleState.NEW;
+        /**
+         * Registered lifecycle hooks.
+         *
+         * Uses a Set per hook to:
+         * - Avoid duplicate registrations
+         * - Preserve insertion order for deterministic execution
+         */
+        this.hooks = new Map();
+        this.hooks.set("onInit", new Set());
+        this.hooks.set("onMount", new Set());
+        this.hooks.set("onUpdate", new Set());
+        this.hooks.set("onDestroy", new Set());
+    }
+    /**
+     * Subscribes a callback to a lifecycle hook.
+     *
+     * @param hook - The lifecycle hook name to listen to
+     * @param fn - The callback to execute when the hook is emitted
+     * @returns `this` for chaining
+     */
+    on(hook, fn) {
+        this.hooks.get(hook).add(fn);
+        return this;
+    }
+    /**
+     * Unsubscribes a previously registered callback from a lifecycle hook.
+     *
+     * @param hook - The lifecycle hook name
+     * @param fn - The callback to remove
+     * @returns `this` for chaining
+     */
+    off(hook, fn) {
+        this.hooks.get(hook).delete(fn);
+        return this;
+    }
+    /**
+     * Emits a lifecycle hook, executing all registered callbacks
+     * in the order they were added.
+     *
+     * @param hook - The lifecycle hook to emit
+     * @internal Prefer using the public lifecycle methods (`init/mount/update/destroy`)
+     *           which call `emit` at the correct times.
+     */
+    emit(hook, prevState) {
+        const ctx = {
+            state: this.state,
+            prevState,
+        };
+        for (const fn of this.hooks.get(hook)) {
+            try {
+                fn(ctx);
+            }
+            catch (err) {
+                this.handleHookError(err, hook);
+            }
+        }
+    }
+    handleHookError(error, hook) {
+        console.error(`[Lifecycle:${hook}]`, error);
+    }
+    /**
+     * Transitions from `NEW` → `INITIALIZED` and emits `onInit`.
+     *
+     * Safe to call multiple times; subsequent calls are no-ops unless current state is `NEW`.
+     */
+    init() {
+        if (this.state !== LifecycleState.NEW)
+            return;
+        const prev = this.state;
+        this.state = LifecycleState.INITIALIZED;
+        this.emit("onInit", prev);
+    }
+    /**
+     * Transitions from `INITIALIZED` → `MOUNTED` and emits `onMount`.
+     *
+     * No-ops if current state is not `INITIALIZED` (guards against invalid order).
+     */
+    mount() {
+        if (this.state !== LifecycleState.INITIALIZED)
+            return;
+        const prev = this.state;
+        this.state = LifecycleState.MOUNTED;
+        this.emit("onMount", prev);
+    }
     /**
-     * Represents a placeholder component for the Select UI, allowing dynamic updates to placeholder text.
-     * Supports HTML content based on configuration and provides methods to get or set the placeholder value.
+     * Transitions from `MOUNTED` → `UPDATED` and emits `onUpdate`.
+     *
+     * No-ops if not currently `MOUNTED`. Subsequent `update()` calls will keep the state
+     * at `UPDATED` while still emitting `onUpdate`.
+     */
+    update() {
+        if (this.state !== LifecycleState.MOUNTED &&
+            this.state !== LifecycleState.UPDATED) {
+            return;
+        }
+        const prev = this.state;
+        this.state = LifecycleState.UPDATED;
+        this.emit("onUpdate", prev);
+    }
+    /**
+     * Transitions to `DESTROYED` and emits `onDestroy`, then clears all hooks.
+     *
+     * Idempotent: calling `destroy()` multiple times after destruction has no effect.
+     */
+    destroy() {
+        if (this.state === LifecycleState.DESTROYED)
+            return;
+        const prev = this.state;
+        this.state = LifecycleState.DESTROYED;
+        this.emit("onDestroy", prev);
+        this.clearHooks();
+    }
+    /**
+     * Returns the current lifecycle state.
+     */
+    getState() {
+        return this.state;
+    }
+    /**
+     * Checks if the lifecycle is in the specified state.
+     *
+     * @param state - The state to compare against
+     * @returns True if the current state matches; otherwise false
+     */
+    is(state) {
+        return this.state === state;
+    }
+    /**
+     * Clears all registered lifecycle hooks.
+     *
+     * Called automatically during `destroy()`.
+     */
+    clearHooks() {
+        for (const set of this.hooks.values()) {
+            set.clear();
+        }
+    }
+}
+
+/**
+ * UI component representing a placeholder for the Select UI.
+ *
+ * The placeholder displays contextual guidance when no value is selected.
+ * It supports dynamic updates and optional HTML content, depending on configuration.
+ *
+ * The component manages a single DOM node and participates
+ * in the standard `Lifecycle`.
+ *
+ * @extends Lifecycle
+ */
+class PlaceHolder extends Lifecycle {
+    /**
+     * Creates a new PlaceHolder instance.
+     *
+     * If options are provided, the component is initialized immediately.
+     *
+     * @param options - Configuration object containing placeholder text
+     *                  and HTML rendering settings.
      */
     constructor(options) {
+        super();
+        /**
+         * Root DOM element of the placeholder component.
+         * Created during initialization and removed on destroy.
+         */
         this.node = null;
+        /**
+         * Configuration options containing placeholder text
+         * and rendering preferences (e.g., allowHtml).
+         */
         this.options = null;
         if (options)
-            this.init(options);
+            this.initialize(options);
     }
     /**
-     * Initializes the placeholder element with provided options and renders its initial content.
+     * Initializes the placeholder component.
      *
-     * @param {object} options - Configuration object containing placeholder text and HTML allowance.
+     * Creates the DOM node, applies base styling,
+     * renders the initial placeholder content,
+     * stores configuration options, and starts the lifecycle.
+     *
+     * @param options - Configuration object containing placeholder settings.
      */
-    init(options) {
+    initialize(options) {
         this.node = Libs.nodeCreator({
             node: "div",
             classList: "selective-ui-placeholder",
             innerHTML: options.placeholder,
         });
         this.options = options;
+        this.init();
     }
     /**
-     * Retrieves the current placeholder text from the configuration.
+     * Returns the current placeholder text from the configuration.
      *
-     * @returns {string} - The current placeholder text.
+     * @returns The current placeholder value, or an empty string if not set.
      */
     get() {
         return this.options?.placeholder ?? "";
     }
     /**
-     * Updates the placeholder text and optionally saves it to the configuration.
-     * Applies HTML sanitization based on the allowHtml setting.
+     * Updates the placeholder content.
+     *
+     * The value can optionally be persisted back into the configuration.
+     * HTML rendering is controlled by the `allowHtml` option:
+     * - When enabled, translated HTML is rendered
+     * - When disabled, HTML tags are stripped for safety
      *
-     * @param {string} value - The new placeholder text.
-     * @param {boolean} [isSave=true] - Whether to persist the new value in the configuration.
+     * @param value - The new placeholder content.
+     * @param isSave - Whether to persist the value in the configuration.
+     *                 Defaults to `true`.
      */
     set(value, isSave = true) {
         if (!this.node || !this.options)
             return;
-        if (isSave)
+        if (isSave) {
             this.options.placeholder = value;
+        }
         const translated = Libs.tagTranslate(value);
-        this.node.innerHTML = this.options.allowHtml ? translated : Libs.stripHtml(translated);
+        this.node.innerHTML = this.options.allowHtml
+            ? translated
+            : Libs.stripHtml(translated);
+    }
+    /**
+     * Destroys the placeholder component.
+     *
+     * Removes the DOM node, clears stored options,
+     * and terminates the lifecycle.
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.node?.remove();
+        this.node = null;
+        this.options = null;
+        super.destroy();
     }
 }
 
 /**
- * @class
+ * Base directive class representing a lightweight UI control.
+ *
+ * A Directive is a small interactive UI element that:
+ * - Owns a single root HTMLElement
+ * - Participates in the standard lifecycle (`init → mount → destroy`)
+ * - Encapsulates behavior rather than complex rendering logic
+ *
+ * This particular implementation acts as a toggle control
+ * (e.g., to open/close a dropdown).
+ *
+ * @extends Lifecycle
  */
-class Directive {
+class Directive extends Lifecycle {
+    /**
+     * Creates a new Directive instance and immediately initializes it.
+     *
+     * The lifecycle is automatically started:
+     * constructor → init → mount
+     */
     constructor() {
-        this.node = this.init();
+        super();
+        this.init();
     }
     /**
-     * Represents a directive button element used to toggle dropdown state.
-     * Initializes a clickable node with appropriate ARIA attributes for accessibility.
+     * Initializes the directive's DOM structure.
+     *
+     * Creates a clickable element that behaves like a button
+     * and applies appropriate ARIA attributes for accessibility.
+     *
+     * Automatically transitions the lifecycle from:
+     * NEW → INITIALIZED → MOUNTED
      */
     init() {
-        // Libs.nodeCreator returns Element, but this node is always an HTMLElement in practice.
-        return Libs.nodeCreator({
+        // Libs.nodeCreator returns Element, but this node
+        // is guaranteed to be an HTMLElement in this context.
+        this.node = Libs.nodeCreator({
             node: "div",
             classList: "selective-ui-directive",
             role: "button",
             ariaLabel: "Toggle dropdown",
         });
+        super.init();
+        this.mount();
     }
     /**
-     * Sets the dropdown state by toggling the "drop-down" CSS class on the directive node.
+     * Updates the visual dropdown state of the directive.
+     *
+     * Toggles the `drop-down` CSS class on the root node,
+     * allowing presentation logic to be handled purely via styles.
      *
-     * @param {boolean} value - If true, adds the "drop-down" class; otherwise removes it.
+     * @param value - True to indicate dropdown is open; false otherwise.
      */
     setDropdown(value) {
         this.node.classList.toggle("drop-down", !!value);
     }
+    /**
+     * Destroys the directive and cleans up DOM resources.
+     *
+     * Removes the root node from the DOM and ends the lifecycle.
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.node.remove();
+        this.node = null;
+        super.destroy();
+    }
 }
 
 /**
- * @class
+ * UI control that exposes "Select All" / "Deselect All" actions
+ * for multiple-selection lists.
+ *
+ * Responsibilities:
+ * - Renders two action controls (links/buttons)
+ * - Shows/hides itself based on configuration flags
+ * - Allows registration of callbacks for both actions
+ * - Participates in the standard `Lifecycle`
+ *
+ * Visibility rule:
+ * - Visible only when `options.multiple` and `options.selectall` are truthy.
+ *
+ * @extends Lifecycle
  */
-class OptionHandle {
+class OptionHandle extends Lifecycle {
     /**
-     * Represents an option handle component that provides "Select All" and "Deselect All" actions
-     * for multiple-selection lists. Includes methods to show/hide the handle, refresh its visibility,
-     * and register callbacks for select/deselect events.
+     * Creates a new OptionHandle control.
+     *
+     * If `options` are provided, the component is initialized immediately and
+     * enters the lifecycle (init). Otherwise, call a custom initializer later
+     * to set it up.
+     *
+     * @param options - Configuration with texts and feature flags.
      */
     constructor(options = null) {
+        super();
+        /**
+         * Internal reference to the mounted node structure returned by `Libs.mountNode`.
+         * Used to access typed tags if needed. Null before initialization.
+         */
         this.nodeMounted = null;
+        /**
+         * Root DOM element of the option handle component.
+         * Created during initialization and removed on destroy.
+         */
         this.node = null;
+        /**
+         * Configuration options controlling labels and feature flags.
+         * (e.g., textSelectAll, textDeselectAll, multiple, selectall)
+         */
         this.options = null;
+        /**
+         * Registered callbacks executed when "Select All" is activated.
+         */
         this.actionOnSelectAll = [];
+        /**
+         * Registered callbacks executed when "Deselect All" is activated.
+         */
         this.actionOnDeSelectAll = [];
         if (options)
-            this.init(options);
+            this.initialize(options);
     }
     /**
-     * Initializes the option handle UI with "Select All" and "Deselect All" buttons,
-     * wiring their click events to trigger registered callbacks.
+     * Initializes the option handle UI.
+     *
+     * Builds the DOM:
+     * - Root: `.selective-ui-option-handle.hide`
+     * - Children: "Select All" and "Deselect All" controls
      *
-     * @param {object} options - Configuration object containing text labels and feature flags.
+     * Wires their click handlers to invoke registered callbacks
+     * via the `iEvents.callFunctions` helper.
+     *
+     * @param options - Configuration providing labels and feature flags.
      */
-    init(options) {
+    initialize(options) {
         this.nodeMounted = Libs.mountNode({
             OptionHandle: {
                 tag: { node: "div", classList: ["selective-ui-option-handle", "hide"] },
@@ -965,11 +1278,17 @@ class OptionHandle {
         });
         this.node = this.nodeMounted.view;
         this.options = options;
+        this.init();
     }
     /**
-     * Determines whether the option handle should be available based on configuration.
+     * Returns whether the handle should be available (and thus visible)
+     * based on current configuration flags.
+     *
+     * Availability requires:
+     * - `multiple` is truthy
+     * - `selectall` is truthy
      *
-     * @returns {boolean} - True if multiple selection and select-all features are enabled.
+     * @returns True if both features are enabled; otherwise false.
      */
     available() {
         if (!this.options)
@@ -977,19 +1296,28 @@ class OptionHandle {
         return Libs.string2Boolean(this.options.multiple) && Libs.string2Boolean(this.options.selectall);
     }
     /**
-     * Refreshes the visibility of the option handle based on availability.
-     * Shows the handle if available; hides it otherwise.
+     * Refreshes the visibility based on `available()` and emits the update lifecycle.
+     *
+     * - Shows the handle when available
+     * - Hides it otherwise
+     *
+     * Note: `super.update()` transitions lifecycle to `UPDATED` (idempotent after first call).
      */
-    refresh() {
-        if (!this.node)
-            return;
-        if (this.available())
-            this.show();
-        else
-            this.hide();
+    update() {
+        if (this.node) {
+            if (this.available()) {
+                this.show();
+            }
+            else {
+                this.hide();
+            }
+        }
+        super.update();
     }
     /**
-     * Makes the option handle visible by removing the "hide" class.
+     * Makes the option handle visible.
+     *
+     * Removes the `hide` class from the root node.
      */
     show() {
         if (!this.node)
@@ -997,7 +1325,9 @@ class OptionHandle {
         this.node.classList.remove("hide");
     }
     /**
-     * Hides the option handle by adding the "hide" class.
+     * Hides the option handle.
+     *
+     * Adds the `hide` class to the root node.
      */
     hide() {
         if (!this.node)
@@ -1005,45 +1335,94 @@ class OptionHandle {
         this.node.classList.add("hide");
     }
     /**
-     * Registers a callback to be executed when "Select All" is clicked.
+     * Registers a callback for the "Select All" action.
+     *
+     * The callback will be invoked with the arguments provided
+     * by the action dispatcher (if any).
      *
-     * @param {Function|null} action - The function to call on select-all action.
+     * @param action - Function to execute when "Select All" is triggered.
      */
-    OnSelectAll(action = null) {
-        if (typeof action === "function")
+    onSelectAll(action = null) {
+        if (typeof action === "function") {
             this.actionOnSelectAll.push(action);
+        }
     }
     /**
-     * Registers a callback to be executed when "Deselect All" is clicked.
+     * Registers a callback for the "Deselect All" action.
+     *
+     * The callback will be invoked with the arguments provided
+     * by the action dispatcher (if any).
      *
-     * @param {Function|null} action - The function to call on deselect-all action.
+     * @param action - Function to execute when "Deselect All" is triggered.
      */
-    OnDeSelectAll(action = null) {
-        if (typeof action === "function")
+    onDeSelectAll(action = null) {
+        if (typeof action === "function") {
             this.actionOnDeSelectAll.push(action);
+        }
+    }
+    /**
+     * Destroys the option handle component.
+     *
+     * Removes the DOM node, clears stored options,
+     * and terminates the lifecycle.
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.node.remove();
+        this.options = null;
+        this.actionOnSelectAll = null;
+        this.actionOnDeSelectAll = null;
+        this.node = null;
+        super.destroy();
     }
 }
 
 /**
- * @class
+ * UI component that represents an empty state.
+ *
+ * The empty state is used to display contextual feedback when:
+ * - No data is available
+ * - A search yields no matching results
+ *
+ * It manages a single DOM node and participates in the standard lifecycle.
+ *
+ * @extends Lifecycle
  */
-class EmptyState {
+class EmptyState extends Lifecycle {
     /**
-     * Represents an empty state component that displays a message when no data or search results are available.
-     * Provides methods to show/hide the state and check its visibility.
+     * Creates a new EmptyState instance.
+     *
+     * If options are provided, the component is initialized immediately.
+     *
+     * @param options - Configuration containing messages for
+     *                  "no data" and "not found" states.
      */
     constructor(options = null) {
+        super();
+        /**
+         * Root DOM element of the empty state component.
+         * Created during initialization and removed on destroy.
+         */
         this.node = null;
+        /**
+         * Configuration options providing display text
+         * for different empty state scenarios.
+         */
         this.options = null;
         if (options)
-            this.init(options);
+            this.initialize(options);
     }
     /**
-     * Initializes the empty state element with ARIA attributes for accessibility and stores configuration options.
+     * Initializes the empty state component.
+     *
+     * Creates the root DOM element, applies accessibility attributes,
+     * stores configuration options, and starts the lifecycle.
      *
-     * @param {object} options - Configuration object containing text for "no data" and "not found" states.
+     * @param options - Configuration object containing empty state messages.
      */
-    init(options) {
+    initialize(options) {
         this.options = options;
         this.node = Libs.nodeCreator({
             node: "div",
@@ -1051,22 +1430,32 @@ class EmptyState {
             role: "status",
             ariaLive: "polite",
         });
+        this.init();
     }
     /**
-     * Displays the empty state message based on the provided type.
+     * Displays the empty state message.
      *
-     * @param {"notfound" | "nodata"} [type="nodata"] - Determines which message to show:
-     *        "notfound" for search results not found, "nodata" for no available data.
+     * The message content depends on the provided type:
+     * - `"nodata"`: no data available
+     * - `"notfound"`: no matching search results
+     *
+     * @param type - Type of empty state to display.
+     *               Defaults to `"nodata"`.
      */
     show(type = "nodata") {
         if (!this.node || !this.options)
             return;
-        const text = type === "notfound" ? this.options.textNotFound : this.options.textNoData;
+        const text = type === "notfound"
+            ? this.options.textNotFound
+            : this.options.textNoData;
         this.node.textContent = text;
         this.node.classList.remove("hide");
     }
     /**
-     * Hides the empty state element by adding the "hide" class.
+     * Hides the empty state component.
+     *
+     * This does not remove the element from the DOM;
+     * it only updates its visibility via CSS.
      */
     hide() {
         if (!this.node)
@@ -1076,33 +1465,71 @@ class EmptyState {
     /**
      * Indicates whether the empty state is currently visible.
      *
-     * @returns {boolean} - True if visible, false otherwise.
+     * @returns True if the empty state is shown; otherwise false.
      */
     get isVisible() {
         return !!this.node && !this.node.classList.contains("hide");
     }
+    /**
+     * Destroys the empty state component.
+     *
+     * Removes the DOM node, clears stored options,
+     * and terminates the lifecycle.
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.options = null;
+        this.node?.remove();
+        this.node = null;
+        super.destroy();
+    }
 }
 
 /**
- * @class
+ * UI component representing a loading state.
+ *
+ * The loading state is displayed while data is being fetched,
+ * processed, or updated asynchronously.
+ *
+ * It manages a single DOM element and participates in the
+ * standard lifecycle provided by `Lifecycle`.
+ *
+ * @extends Lifecycle
  */
-class LoadingState {
+class LoadingState extends Lifecycle {
     /**
-     * Represents a loading state component that displays a loading message during data fetch or processing.
-     * Provides methods to show/hide the state and check its visibility.
+     * Creates a new LoadingState instance.
+     *
+     * If options are provided, the component is initialized immediately.
+     *
+     * @param options - Configuration object containing the loading message text.
      */
     constructor(options = null) {
+        super();
+        /**
+         * Root DOM element of the loading state component.
+         * Created during initialization and removed on destroy.
+         */
         this.node = null;
+        /**
+         * Configuration options containing the loading message text.
+         */
         this.options = null;
         if (options)
-            this.init(options);
+            this.initialize(options);
     }
     /**
-     * Initializes the loading state element with ARIA attributes for accessibility and stores configuration options.
+     * Initializes the loading state component.
+     *
+     * Creates the root DOM element, sets the initial loading text,
+     * applies accessibility attributes, stores configuration options,
+     * and starts the lifecycle.
      *
-     * @param {object} options - Configuration object containing text for the loading message.
+     * @param options - Configuration object containing loading text.
      */
-    init(options) {
+    initialize(options) {
         this.options = options;
         this.node = Libs.nodeCreator({
             node: "div",
@@ -1111,11 +1538,16 @@ class LoadingState {
             role: "status",
             ariaLive: "polite",
         });
+        this.init();
     }
     /**
-     * Displays the loading state message and adjusts its size based on whether items are present.
+     * Displays the loading state.
      *
-     * @param {boolean} hasItems - If true, applies a "small" style for compact display.
+     * When items are already present, the loading state can be shown
+     * in a compact form by applying a reduced ("small") style.
+     *
+     * @param hasItems - True if existing items are present,
+     *                   enabling a compact loading indicator.
      */
     show(hasItems) {
         if (!this.node || !this.options)
@@ -1125,7 +1557,10 @@ class LoadingState {
         this.node.classList.remove("hide");
     }
     /**
-     * Hides the loading state element by adding the "hide" class.
+     * Hides the loading state.
+     *
+     * This only toggles visibility via CSS and does not
+     * remove the element from the DOM.
      */
     hide() {
         if (!this.node)
@@ -1135,11 +1570,26 @@ class LoadingState {
     /**
      * Indicates whether the loading state is currently visible.
      *
-     * @returns {boolean} - True if visible, false otherwise.
+     * @returns True if the loading indicator is shown; otherwise false.
      */
     get isVisible() {
         return !!this.node && !this.node.classList.contains("hide");
     }
+    /**
+     * Destroys the loading state component.
+     *
+     * Removes the DOM node, clears stored options,
+     * and terminates the lifecycle.
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.options = null;
+        this.node?.remove();
+        this.node = null;
+        super.destroy();
+    }
 }
 
 /**
@@ -1268,50 +1718,90 @@ class ResizeObserverService {
 }
 
 /**
- * @class
+ * Popup panel that renders and manages the dropdown surface.
+ *
+ * Responsibilities:
+ * - Build and attach the dropdown DOM structure
+ * - Integrate state components (OptionHandle, LoadingState, EmptyState)
+ * - Bind to ModelManager resources (adapter + recycler view)
+ * - Handle virtual scrolling and infinite scroll
+ * - Compute placement (top/bottom) and animate open/close/resize via Effector
+ * - Keep "empty/not found" states in sync with adapter visibility stats
+ *
+ * Lifecycle:
+ * - Created via constructor → `initialize()` (when args provided) → `init()` → `mount()`
+ * - `open()` attaches and animates the panel
+ * - `close()` collapses the panel
+ * - `destroy()` fully tears down all resources
+ *
+ * @extends Lifecycle
  */
-class Popup {
+class Popup extends Lifecycle {
     /**
-     * Represents a popup component that manages rendering and interaction for a dropdown panel.
-     * Stores a reference to the ModelManager for handling option models and adapter logic.
+     * Creates a Popup instance that manages the dropdown panel for a Select-like UI.
+     *
+     * If `select` and `options` are provided, the popup is initialized immediately.
      *
-     * @param {HTMLSelectElement|null} [select=null] - The source select element to bind.
-     * @param {object|null} [options=null] - Configuration options for the popup.
-     * @param {ModelManager|null} [modelManager=null] - The model manager instance for data handling.
+     * @param select - Source `<select>` element this popup is bound to.
+     * @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) {
+        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) */
             estimateItemHeight: 36,
+            /** Number of extra items to render above/below the viewport */
             overscan: 8,
+            /** Whether the list contains items with dynamic (non-uniform) heights */
             dynamicHeights: true
         };
         this.modelManager = modelManager;
         if (select && options) {
-            this.init(select, options);
+            this.initialize(select, options);
         }
     }
     /**
-     * Initializes the popup UI: creates DOM structure, wires OptionHandle, LoadingState, and EmptyState,
-     * binds ModelManager resources (adapter/recyclerView), and sets up empty-state logic.
+     * Initializes the popup UI:
+     * - Creates the container and child components (OptionHandle, LoadingState, EmptyState)
+     * - Binds to ModelManager resources (adapter/recyclerView)
+     * - Enables empty-state synchronization with adapter
+     * - Applies virtual scroll options (when enabled)
      *
-     * @param {HTMLSelectElement} select - The source select element to bind.
-     * @param {object} options - Configuration for panel, IDs, multiple mode, and texts.
+     * @param select - The source select element to bind.
+     * @param options - Panel configuration (dimensions, IDs, labels, flags).
+     * @throws Error if a ModelManager is not provided.
      */
-    init(select, options) {
+    initialize(select, options) {
         if (!this.modelManager)
             throw new Error("Popup requires a ModelManager instance.");
         this.optionHandle = new OptionHandle(options);
@@ -1343,6 +1833,7 @@ class Popup {
         this.optionsContainer = nodeMounted.tags.OptionsContainer;
         this.parent = Libs.getBinderMap(select);
         this.options = options;
+        this.init();
         const recyclerViewOpt = options.virtualScroll
             ? {
                 scrollEl: this.node,
@@ -1351,22 +1842,28 @@ class Popup {
                 dynamicHeights: this.virtualScrollConfig.dynamicHeights
             }
             : {};
-        // Load ModelManager resources into container
+        // Load ModelManager resources into the list container
         this.modelManager.load(this.optionsContainer, { isMultiple: options.multiple }, recyclerViewOpt);
         const MMResources = this.modelManager.getResources();
         this.optionAdapter = MMResources.adapter;
         this.recyclerView = MMResources.recyclerView;
-        this.optionHandle.OnSelectAll(() => {
+        this.optionHandle.onSelectAll(() => {
             MMResources.adapter.checkAll(true);
         });
-        this.optionHandle.OnDeSelectAll(() => {
+        this.optionHandle.onDeSelectAll(() => {
             MMResources.adapter.checkAll(false);
         });
         this.setupEmptyStateLogic();
+        this.mount();
     }
     /**
-     * Shows the loading state and temporarily skips model events.
-     * Adjusts size based on current visibility stats and triggers a resize.
+     * Shows the loading state and temporarily suspends adapter/model events.
+     *
+     * Behavior:
+     * - Cancels any pending hide-timeout
+     * - Instructs `ModelManager` to skip events
+     * - Shows loading indicator (compact mode if there are visible items)
+     * - Triggers a resize to accommodate layout changes
      */
     async showLoading() {
         if (!this.options || !this.loadingState || !this.optionHandle || !this.optionAdapter || !this.modelManager)
@@ -1376,15 +1873,15 @@ class Popup {
         this.modelManager.skipEvent(true);
         if (Libs.string2Boolean(this.options.loadingfield) === false)
             return;
-        // this.updateEmptyState({isEmpty: false, hasVisible: true});
         this.emptyState.hide();
         this.loadingState.show(this.optionAdapter.getVisibilityStats().hasVisible);
-        // this.optionHandle.hide();
         this.triggerResize();
     }
     /**
-     * Hides the loading state after a short delay, restores event handling,
-     * updates empty state based on adapter visibility stats, and triggers a resize.
+     * Hides the loading state (after a configured delay), resumes events, syncs empty state,
+     * and triggers a resize.
+     *
+     * Debounce: Uses `animationtime` as a short delay before hiding the loading indicator.
      */
     async hideLoading() {
         if (!this.options || !this.loadingState || !this.optionAdapter || !this.modelManager)
@@ -1400,8 +1897,10 @@ class Popup {
         }, this.options.animationtime);
     }
     /**
-     * Subscribes to adapter visibility and item changes to keep the empty state in sync.
-     * Triggers resize when items change to reflect layout updates.
+     * Subscribes to adapter events to keep the empty state synchronized.
+     *
+     * - `onVisibilityChanged`: updates empty/not-found visibility
+     * - `onPropChanged('items')`: updates visibility after items are mutated
      */
     setupEmptyStateLogic() {
         if (!this.optionAdapter)
@@ -1416,10 +1915,14 @@ class Popup {
         });
     }
     /**
-     * Updates the empty state and option container visibility based on aggregated stats.
-     * Shows "no data" when empty, "not found" when no visible items, otherwise shows options and handle.
+     * Updates the empty/not-found state and the options container visibility.
+     *
+     * Rules:
+     * - `isEmpty` → show "No data", hide options & handle
+     * - `!hasVisible` → show "Not found", hide options & handle
+     * - otherwise → show options, hide empty state, refresh handle
      *
-     * @param {VisibilityStats|undefined} stats - Visibility stats; computed if omitted.
+     * @param stats - Optionally provide precomputed visibility stats.
      */
     updateEmptyState(stats) {
         if (!this.optionAdapter || !this.emptyState || !this.optionHandle || !this.optionsContainer)
@@ -1438,30 +1941,44 @@ class Popup {
         else {
             this.emptyState.hide();
             this.optionsContainer.classList.remove("hide");
-            this.optionHandle.refresh();
+            this.optionHandle.update();
         }
     }
     /**
-     * Registers a callback for adapter property pre-change notifications.
+     * Subscribes to adapter property pre-change notifications.
+     *
+     * @param propName - Adapter property name to observe.
+     * @param callback - Handler invoked before the property changes.
      */
     onAdapterPropChanging(propName, callback) {
         this.optionAdapter?.onPropChanging(propName, callback);
     }
     /**
-     * Registers a callback for adapter property post-change notifications.
+     * Subscribes to adapter property post-change notifications.
+     *
+     * @param propName - Adapter property name to observe.
+     * @param callback - Handler invoked after the property changes.
      */
     onAdapterPropChanged(propName, callback) {
         this.optionAdapter?.onPropChanged(propName, callback);
     }
     /**
-     * Injects an effector service used to perform side effects (e.g., animations or external actions).
+     * Injects an effector service used for size measurement and animations.
+     *
+     * @param effectorSvc - Effector instance to bind to the popup element.
      */
     setupEffector(effectorSvc) {
         this.effSvc = effectorSvc;
     }
     /**
-     * Opens the popup: creates and attaches DOM if needed, initializes observers and effector,
-     * computes position and dimensions, and runs expand animation. Invokes callback on completion.
+     * Opens (expands) the popup:
+     * - On first open: appends to `document.body`, sets up resize observer, and blocks outside mousedown
+     * - Synchronizes the OptionHandle visibility and (optionally) the empty state
+     * - Computes placement from the parent anchor and runs the expand animation
+     * - Resumes recycler view after the animation completes
+     *
+     * @param callback - Optional callback invoked when the opening animation completes.
+     * @param isShowEmptyState - If true, evaluates and applies empty/not-found state before animation.
      */
     open(callback = null, isShowEmptyState) {
         if (!this.node || !this.options || !this.optionHandle || !this.parent || !this.effSvc)
@@ -1471,12 +1988,13 @@ class Popup {
             this.isCreated = true;
             this.resizeObser = new ResizeObserverService();
             this.effSvc.setElement(this.node);
+            // Prevent the popup from closing when clicking inside
             this.node.addEventListener("mousedown", (e) => {
                 e.stopPropagation();
                 e.preventDefault();
             });
         }
-        this.optionHandle.refresh();
+        this.optionHandle.update();
         if (isShowEmptyState) {
             this.updateEmptyState();
         }
@@ -1507,8 +2025,14 @@ class Popup {
         });
     }
     /**
-     * Closes the popup: disconnects the resize observer and runs collapse animation.
-     * Safely no-ops if the popup has not been created.
+     * Closes (collapses) the popup:
+     * - Suspends the recycler view
+     * - Disconnects the resize observer
+     * - Runs the collapse animation
+     *
+     * Safely no-ops when the popup has not been created.
+     *
+     * @param callback - Optional callback invoked when the closing animation completes.
      */
     close(callback = null) {
         if (!this.isCreated || !this.options || !this.resizeObser || !this.effSvc)
@@ -1522,19 +2046,20 @@ class Popup {
         });
     }
     /**
-     * Programmatically triggers a resize recalculation if the popup is created,
-     * causing the layout to update based on the current parent dimensions.
+     * Programmatically triggers a resize recalculation (if created),
+     * causing the popup to recompute placement and dimensions.
      */
     triggerResize() {
         if (this.isCreated)
             this.resizeObser?.trigger();
     }
     /**
-     * Enables infinite scroll by listening to container scroll events and loading more data
-     * when nearing the bottom, respecting pagination state (enabled/loading/hasMore).
+     * Enables infinite scrolling:
+     * - Listens to scroll events on the popup container
+     * - When within 100px of the bottom, attempts to load more items (if enabled and not already loading)
      *
-     * @param searchController - Provides pagination state and a method to load more items.
-     * @param _options - Optional SelectiveOptions (reserved for future behavior tuning).
+     * @param searchController - Provides pagination state and a `loadMore()` method.
+     * @param _options - Optional SelectiveOptions (reserved for future tuning).
      */
     setupInfiniteScroll(searchController, _options) {
         if (!this.node)
@@ -1547,6 +2072,7 @@ class Popup {
             const scrollTop = container.scrollTop;
             const scrollHeight = container.scrollHeight;
             const clientHeight = container.clientHeight;
+            // Near-bottom threshold: 100px
             if (scrollHeight - scrollTop - clientHeight < 100) {
                 if (!state.isLoading && state.hasMore) {
                     const result = await searchController.loadMore();
@@ -1560,18 +2086,24 @@ class Popup {
         this.node.addEventListener("scroll", this.scrollListener);
     }
     /**
-     * Completely tear down the popup instance and release all resources.
+     * Completely tears down the popup and releases all resources.
      *
-     * Responsibilities:
-     *  - Clear any pending timeouts and cancel animations/effects.
-     *  - Remove event listeners (scroll, mousedown) and disconnect ResizeObserver.
-     *  - Unmount and remove the DOM node; sever references to Effector/ModelManager.
-     *  - Dispose adapter/recycler and child components (OptionHandle, EmptyState, LoadingState).
-     *  - Reset flags and null out references to avoid memory leaks.
+     * Operations:
+     * - Clear pending timeouts
+     * - Remove event listeners (scroll, mousedown)
+     * - Disconnect resize observer
+     * - Unbind effector from the element
+     * - Remove DOM node (replace-with-clone fallback)
+     * - Reset ModelManager event skipping
+     * - Clear recycler view, adapter, and child components
+     * - Null out references to avoid leaks and mark as not created
      *
-     * Safe to call multiple times; all operations are guarded via optional chaining.
+     * Idempotent: safe to call multiple times.
      */
-    detroy() {
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
         if (this.hideLoadHandle) {
             clearTimeout(this.hideLoadHandle);
             this.hideLoadHandle = null;
@@ -1580,6 +2112,10 @@ class Popup {
             this.node.removeEventListener("scroll", this.scrollListener);
             this.scrollListener = null;
         }
+        this.emptyState.destroy();
+        this.loadingState.destroy();
+        this.optionHandle.destroy();
+        this.recyclerView.destroy();
         try {
             this.resizeObser?.disconnect();
         }
@@ -1607,6 +2143,7 @@ class Popup {
             this.recyclerView?.clear?.();
             this.recyclerView = null;
             this.optionAdapter = null;
+            // Original behavior kept intentionally.
             this.node.remove();
         }
         catch (_) { }
@@ -1617,10 +2154,11 @@ class Popup {
         this.parent = null;
         this.options = null;
         this.isCreated = false;
+        super.destroy();
     }
     /**
-     * Computes the parent panel's location and box metrics, including size, position,
-     * padding, and border, accounting for iOS visual viewport offsets.
+     * Computes the parent panel's location and box metrics
+     * (size, position, padding, border). Accounts for iOS visual viewport offsets.
      */
     getParentLocation() {
         const viewPanel = this.parent.container.tags.ViewPanel;
@@ -1646,8 +2184,12 @@ class Popup {
         };
     }
     /**
-     * Determines popup placement (top/bottom) and height constraints based on available viewport space,
-     * content size, and configured min/max heights; returns final position, top, and heights.
+     * Determines popup placement (top/bottom) and height constraints based on:
+     * - Available viewport space above/below the anchor
+     * - Content size from effector's hidden measurement
+     * - Configured min/max heights
+     *
+     * Returns the final placement, top offset, and computed heights.
      */
     calculatePosition(location) {
         const vv = window.visualViewport;
@@ -1691,7 +2233,7 @@ class Popup {
         return { position, top, maxHeight, realHeight, contentHeight };
     }
     /**
-     * Handles parent resize events by recalculating placement and dimensions,
+     * Handles parent resize by recalculating placement and dimensions,
      * then animates the popup to the new size and position.
      */
     handleResize(location) {
@@ -1711,33 +2253,66 @@ class Popup {
     }
 }
 
-class SearchBox {
+/**
+ * Searchable input component for the Select UI.
+ *
+ * Responsibilities:
+ * - Render a search input field with proper ARIA attributes
+ * - Dispatch typed events for search, navigation, Enter, and Escape
+ * - Support showing/hiding and dynamic placeholder updates
+ *
+ * Lifecycle:
+ * - Constructed with optional options → initialized → `init()`
+ * - Consumers wire callbacks (`onSearch`, `onNavigate`, `onEnter`, `onEsc`)
+ *
+ * @extends Lifecycle
+ */
+class SearchBox extends Lifecycle {
     /**
      * Creates a searchable input box component with optional configuration
      * and initializes it if options are provided.
      *
-     * @param {object|null} [options=null] - Configuration (e.g., placeholder, accessibility IDs).
+     * @param options - Configuration (e.g., placeholder, accessibility IDs).
      */
     constructor(options = null) {
+        super();
+        /** Internal reference to the mounted node structure with typed tags. */
         this.nodeMounted = null;
+        /** Root container element for the search box component. */
         this.node = null;
+        /** Reference to the input element (`type="search"`). */
         this.SearchInput = null;
+        /** Callback fired on input changes (when not a control key event). */
         this.onSearch = null;
+        /** Current configuration options (placeholder, IDs, searchable flag, etc.). */
         this.options = null;
+        /** Callback to handle list navigation: +1 for next, -1 for previous. */
         this.onNavigate = null;
+        /** Callback fired on Enter. Typically used to confirm a selection. */
         this.onEnter = null;
+        /** Callback fired on Escape. Typically used to dismiss a popup. */
         this.onEsc = null;
         this.options = options;
         if (options)
-            this.init(options);
+            this.initialize(options);
     }
     /**
      * Initializes the search box DOM, sets ARIA attributes, and wires keyboard/mouse/input events.
-     * Supports navigation (ArrowUp/ArrowDown/Tab), Enter, and Escape through callbacks.
      *
-     * @param {object} options - Configuration including placeholder and SEID_LIST for aria-controls.
+     * Accessibility:
+     * - `role="searchbox"`
+     * - `aria-controls` references the listbox container by ID
+     * - `aria-autocomplete="list"` indicates list-based suggestions/results
+     *
+     * Keyboard support:
+     * - ArrowDown / Tab → navigate forward
+     * - ArrowUp → navigate backward
+     * - Enter → confirm action
+     * - Escape → cancel/close action
+     *
+     * @param options - Configuration including placeholder and `SEID_LIST` for `aria-controls`.
      */
-    init(options) {
+    initialize(options) {
         this.nodeMounted = Libs.mountNode({
             SearchBox: {
                 tag: { node: "div", classList: ["selective-ui-searchbox", "hide"] },
@@ -1761,12 +2336,14 @@ class SearchBox {
         this.SearchInput = this.nodeMounted.tags.SearchInput;
         let isControlKey = false;
         const inputEl = this.nodeMounted.tags.SearchInput;
+        // Prevent parent listeners from intercepting mouse interactions.
         inputEl.addEventListener("mousedown", (e) => {
             e.stopPropagation();
         });
         inputEl.addEventListener("mouseup", (e) => {
             e.stopPropagation();
         });
+        // Keyboard handling: navigation, submit, and cancel.
         inputEl.addEventListener("keydown", (e) => {
             isControlKey = false;
             if (e.key === "ArrowDown" || e.key === "Tab") {
@@ -1793,16 +2370,19 @@ class SearchBox {
                 isControlKey = true;
                 this.onEsc?.();
             }
+            // Ensure events don't bubble to container-level listeners.
             e.stopPropagation();
         });
+        // Text input changes (ignore control-key initiated sequences).
         inputEl.addEventListener("input", () => {
             if (isControlKey)
                 return;
             this.onSearch?.(inputEl.value, true);
         });
+        this.init();
     }
     /**
-     * Shows the search box, toggles read-only based on `options.searchable`,
+     * Shows the search box, toggles `readOnly` based on `options.searchable`,
      * and focuses the input when searchable.
      */
     show() {
@@ -1817,7 +2397,7 @@ class SearchBox {
         }
     }
     /**
-     * Hides the search box by adding the "hide" class.
+     * Hides the search box by adding the `hide` class.
      */
     hide() {
         if (!this.node)
@@ -1825,9 +2405,9 @@ class SearchBox {
         this.node.classList.add("hide");
     }
     /**
-     * Clears the current search value and optionally triggers the onSearch callback.
+     * Clears the current search value and optionally triggers the `onSearch` callback.
      *
-     * @param {boolean} [isTrigger=true] - Whether to invoke onSearch with an empty string.
+     * @param isTrigger - Whether to invoke `onSearch` with an empty string. Defaults to `true`.
      */
     clear(isTrigger = true) {
         if (!this.nodeMounted)
@@ -1838,7 +2418,7 @@ class SearchBox {
     /**
      * Updates the input's placeholder text, stripping any HTML for safety.
      *
-     * @param {string} value - The new placeholder text.
+     * @param value - The new placeholder text.
      */
     setPlaceHolder(value) {
         if (!this.SearchInput)
@@ -1846,15 +2426,37 @@ class SearchBox {
         this.SearchInput.placeholder = Libs.stripHtml(value);
     }
     /**
-     * Sets the active descendant for ARIA to indicate which option is currently highlighted.
+     * Sets the active descendant for ARIA to indicate the currently highlighted option.
      *
-     * @param {string} id - The DOM id of the active option element.
+     * @param id - The DOM id of the active option element.
      */
     setActiveDescendant(id) {
         if (!this.SearchInput)
             return;
         this.SearchInput.setAttribute("aria-activedescendant", id);
     }
+    /**
+     * Destroys the search box and releases resources.
+     *
+     * - Removes the root DOM node
+     * - Clears references to DOM and callbacks
+     * - Ends the lifecycle
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.node?.remove();
+        this.nodeMounted = null;
+        this.node = null;
+        this.SearchInput = null;
+        this.onSearch = null;
+        this.options = null;
+        this.onNavigate = null;
+        this.onEnter = null;
+        this.onEsc = null;
+        super.destroy();
+    }
 }
 
 /**
@@ -2160,66 +2762,85 @@ class EffectorImpl {
 }
 
 /**
- * @template TTarget
- * @template TTags
- * @template TView
+ * Base Model class that connects a target DOM element with its corresponding View.
+ * Handles lifecycle, state, and synchronization between model, view, and DOM.
+ *
+ * @template TTarget - The HTML element this model is bound to
+ * @template TTags - A map of named HTML elements used by the view
+ * @template TView - The view implementation associated with this model
+ * @template TOptions - Configuration options for the model
+ *
  * @implements {ModelContract<TTarget, TView>}
  */
-class Model {
+class Model extends Lifecycle {
     /**
-     * Returns the current value from the underlying target element's "value" attribute.
-     * For single-select, this is typically a string; for multi-select, may be an array depending on usage.
+     * Returns the current value of the bound target element.
+     *
+     * - For single-value elements, this is usually a string
+     * - For multi-value elements, this may be an array depending on usage
      */
     get value() {
         return this.targetElement?.getAttribute("value") ?? null;
     }
     /**
-     * Constructs a Model instance with configuration options and optional bindings to a target element and view.
-     * Stores references for later updates and rendering.
+     * Creates a new Model instance.
      *
-     * @param {TOptions} options - Configuration options for the model.
-     * @param {TTarget|null} [targetElement=null] - The underlying element (e.g., <option> or group node).
-     * @param {TView|null} [view=null] - The associated view responsible for rendering the model.
+     * Initializes the model with configuration options and optionally binds
+     * it to a target DOM element and a view.
+     *
+     * @param options - Configuration options for the model
+     * @param targetElement - Optional DOM element to bind to this model
+     * @param view - Optional view responsible for rendering the model
      */
     constructor(options, targetElement = null, view = null) {
+        super();
+        /** The underlying DOM element associated with this model */
         this.targetElement = null;
+        /** View instance responsible for rendering this model */
         this.view = null;
+        /** Position index of the model (used for ordering or tracking) */
         this.position = -1;
+        /** Indicates whether the model has been initialized */
         this.isInit = false;
+        /** Indicates whether the model has been destroyed/removed */
         this.isRemoved = false;
         this.options = options;
         this.targetElement = targetElement;
         this.view = view;
+        this.init();
     }
     /**
-     * Updates the bound target element reference and invokes the change hook.
+     * Updates the bound target element and triggers the update lifecycle.
      *
-     * @param {TTarget|null} targetElement - The new target element to bind to the model.
+     * @param targetElement - The new DOM element to associate with this model
      */
-    update(targetElement) {
+    updateTarget(targetElement) {
         this.targetElement = targetElement;
-        this.onTargetChanged();
+        this.update();
     }
     /**
-     * Cleans up references and invokes the removal hook when the model is no longer needed.
+     * Hook executed when the model is updated.
+     * Intended to be overridden by subclasses.
      */
-    remove() {
+    onUpdate() { }
+    /**
+     * Destroys the model and releases all references.
+     *
+     * - Unbinds the target element
+     * - Removes the associated view from the DOM
+     * - Marks the model as removed
+     * - Triggers lifecycle cleanup
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
         this.targetElement = null;
-        this.view?.getView()?.remove?.();
+        this.view?.destroy();
         this.view = null;
         this.isRemoved = true;
-        this.onRemove();
+        super.destroy();
     }
-    /**
-     * Hook invoked whenever the target element changes.
-     * Override in subclasses to react to attribute/content updates (e.g., text, disabled state).
-     */
-    onTargetChanged() { }
-    /**
-     * Hook invoked whenever the target element is removed.
-     * Override in subclasses to react to removal of the element.
-     */
-    onRemove() { }
 }
 
 /**
@@ -2239,10 +2860,14 @@ class GroupModel extends Model {
         this.items = [];
         this.collapsed = false;
         this.privOnCollapsedChanged = [];
-        if (targetElement) {
-            this.label = targetElement.label;
-            this.collapsed = Libs.string2Boolean(targetElement.dataset?.collapsed);
+    }
+    init() {
+        if (this.targetElement) {
+            this.label = this.targetElement.label;
+            this.collapsed = Libs.string2Boolean(this.targetElement.dataset?.collapsed);
         }
+        super.init();
+        this.mount();
     }
     /**
      * Returns the array of values from all option items within the group.
@@ -2281,19 +2906,31 @@ class GroupModel extends Model {
      *
      * @param {HTMLOptGroupElement} targetElement - The updated <optgroup> element.
      */
-    update(targetElement) {
+    updateTarget(targetElement) {
         this.label = targetElement.label;
         this.view?.updateLabel(this.label);
+        this.update();
     }
     /**
      * Hook invoked when the target element reference changes.
      * Updates the view's label and collapsed state to keep UI in sync.
      */
-    onTargetChanged() {
+    update() {
         if (this.view) {
             this.view.updateLabel(this.label);
             this.view.setCollapsed(this.collapsed);
         }
+        super.update();
+    }
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.items.forEach(item => {
+            item.destroy();
+        });
+        this.items = [];
+        super.destroy();
     }
     /**
      * Registers a callback to be invoked when the group's collapsed state changes.
@@ -2361,9 +2998,11 @@ class OptionModel extends Model {
         this._visible = true;
         this._highlighted = false;
         this.group = null;
-        (async () => {
-            this.textToFind = Libs.string2normalize(this.textContent.toLowerCase());
-        })();
+    }
+    init() {
+        this.textToFind = Libs.string2normalize(this.textContent.toLowerCase());
+        super.init();
+        this.mount();
     }
     /**
      * Returns the image source from dataset (imgsrc or image), or an empty string if absent.
@@ -2536,10 +3175,12 @@ class OptionModel extends Model {
      * Updates label content (HTML or text), image src/alt if present,
      * and synchronizes initial selected state to the view.
      */
-    onTargetChanged() {
+    update() {
         this.textToFind = Libs.string2normalize(this.textContent.toLowerCase());
-        if (!this.view)
+        if (!this.view) {
+            super.update();
             return;
+        }
         const labelContent = this.view.view.tags.LabelContent;
         if (labelContent) {
             if (this.options.allowHtml) {
@@ -2556,6 +3197,18 @@ class OptionModel extends Model {
         }
         if (this.targetElement)
             this.selectedNonTrigger = this.targetElement.selected;
+        super.update();
+    }
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.privOnSelected = [];
+        this.privOnInternalSelected = [];
+        this.privOnVisibilityChanged = [];
+        this.group = null;
+        this.textToFind = null;
+        super.destroy();
     }
 }
 
@@ -2735,7 +3388,7 @@ class ModelManager {
                     // Label is used as key; keep original behavior.
                     const hasLabelChange = existingGroup.label !== dataVset.label;
                     if (hasLabelChange) {
-                        existingGroup.update(dataVset);
+                        existingGroup.updateTarget(dataVset);
                     }
                     existingGroup.position = position;
                     existingGroup.items = [];
@@ -2755,7 +3408,7 @@ class ModelManager {
                 const key = `${dataVset.value}::${dataVset.text}`;
                 const existingOption = oldOptionMap.get(key);
                 if (existingOption) {
-                    existingOption.update(dataVset);
+                    existingOption.updateTarget(dataVset);
                     existingOption.position = position;
                     const parentGroup = dataVset["__parentGroup"];
                     if (parentGroup && currentGroup) {
@@ -2790,11 +3443,11 @@ class ModelManager {
         this.oldPosition = position;
         oldGroupMap.forEach((removedGroup) => {
             isUpdate = false;
-            removedGroup.remove();
+            removedGroup.destroy();
         });
         oldOptionMap.forEach((removedOption) => {
             isUpdate = false;
-            removedOption.remove();
+            removedOption.destroy();
         });
         this.privModelList = newModels;
         if (this.privAdapterHandle) {
@@ -2857,34 +3510,45 @@ class ModelManager {
 }
 
 /**
- * @template TItem
- * @template TAdapter
+ * RecyclerView renders models provided by an Adapter into a container element.
+ *
+ * Responsibilities:
+ * - Maintain a root container (`viewElement`) where item views are rendered
+ * - Attach an Adapter and wire item-change lifecycle:
+ *   - `onPropChanging('items')` → clear container before items change
+ *   - `onPropChanged('items')` → re-render after items change
+ * - Expose rendering utilities: `render()`, `clear()`, `refresh()`
+ * - Participate in the standard lifecycle (`init` → `mount` → `update` → `destroy`)
+ *
+ * @template TItem - The model type handled by the adapter.
+ * @template TAdapter - The adapter type that manages items and updates the view.
+ *
  * @implements {RecyclerViewContract<TAdapter>}
  */
-class RecyclerView {
+class RecyclerView extends Lifecycle {
     /**
      * Constructs a RecyclerView with an optional container element that will host rendered item views.
      *
      * @param {HTMLDivElement|null} [viewElement=null] - The root element where the adapter will render items.
      */
     constructor(viewElement = null) {
+        super();
+        /** Root container that hosts rendered item views. */
         this.viewElement = null;
+        /** The adapter that manages models and updates the RecyclerView on changes. */
         this.adapter = null;
         this.viewElement = viewElement;
-    }
-    /**
-     * Sets or updates the container element used to render the adapter's item views.
-     *
-     * @param {HTMLDivElement} viewElement - The root element for rendering.
-     */
-    setView(viewElement) {
-        this.viewElement = viewElement;
+        this.init();
     }
     /**
      * Attaches an adapter to the RecyclerView and wires item-change lifecycle:
-     * - onPropChanging("items"): clears the container before items change,
-     * - onPropChanged("items"): re-renders after items change,
-     * then performs an initial render.
+     * - `onPropChanging('items')`: clears the container before items change
+     * - `onPropChanged('items')`: re-renders after items change
+     *
+     * Then performs:
+     * - `adapter.mount()` to initialize the adapter
+     * - `this.mount()` to mark the RecyclerView as mounted
+     * - An initial `render()` to sync the UI
      *
      * @param {TAdapter} adapter - The adapter managing models and their views.
      */
@@ -2896,11 +3560,13 @@ class RecyclerView {
         adapter.onPropChanged("items", () => {
             this.render();
         });
+        adapter.mount();
+        this.mount();
         this.render();
     }
     /**
      * Removes all child nodes from the rendering container, if present.
-     * Used prior to re-rendering or when items are changing.
+     * Typically used right before re-rendering or when items are about to change.
      */
     clear() {
         if (!this.viewElement)
@@ -2910,77 +3576,155 @@ class RecyclerView {
     /**
      * Renders the current adapter contents into the container.
      * No-ops if either the adapter or the container is not set.
+     * Emits the `update` lifecycle after delegating rendering to the adapter.
      */
     render() {
         if (!this.adapter || !this.viewElement)
             return;
         this.adapter.updateRecyclerView(this.viewElement);
+        this.update();
     }
     /**
      * Forces a re-render of the current adapter state into the container.
      * Useful when visual updates are required without changing the data.
      *
-     * @param isUpdate - Indicates if this refresh is due to an update operation.
+     * @param {boolean} isUpdate - Indicates if this refresh originates from an update operation.
+     *                             (Reserved for future use; no impact on logic.)
      */
     refresh(isUpdate) {
         this.render();
     }
+    /**
+     * Destroys the RecyclerView, detaching from its adapter and container.
+     *
+     * - Delegates teardown to the adapter
+     * - Clears strong references (adapter, viewElement)
+     * - Ends the lifecycle
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.adapter?.destroy?.();
+        this.viewElement = null;
+        this.adapter = null;
+        super.destroy();
+    }
 }
 
 /**
- * @class
+ * Accessory box that displays “selected chips” for multi-select mode.
+ *
+ * Responsibilities:
+ * - Create and position a lightweight container near the Select UI mask
+ * - Render current selections as removable “accessory items” (chips)
+ * - Dispatch selection changes back to the ModelManager
+ * - Show/hide based on configuration and current selection count
+ *
+ * Lifecycle:
+ * - Constructed with optional options → `initialize()` → `init()`
+ * - `setRoot()` binds to the Select UI mask and calls `mount()`
+ * - `setModelData()` re-renders chips and calls `update()`
+ * - `destroy()` removes the DOM node and clears references
+ *
+ * @extends Lifecycle
  */
-class AccessoryBox {
+class AccessoryBox extends Lifecycle {
     /**
-     * Initializes the accessory box with optional configuration and immediately calls init() if provided.
+     * Creates an AccessoryBox and (optionally) initializes it with configuration.
      *
-     * @param {object|null} options - Configuration options for the accessory box (e.g., layout and behavior).
+     * @param options - Configuration options (e.g., placement via `accessoryStyle`,
+     *                  visibility via `accessoryVisible`, texts, etc.).
      */
     constructor(options = null) {
+        super();
+        /** Internal reference to the mounted node structure. */
         this.nodeMounted = null;
+        /** Root DOM element of the accessory box (hidden by default). */
         this.node = null;
+        /** Configuration (texts, behavior, placement style). */
         this.options = null;
+        /** The overlay/mask element belonging to the main Select UI. */
         this.selectUIMask = null;
+        /** Parent element hosting both the Select UI mask and the accessory box. */
         this.parentMask = null;
+        /** ModelManager used to trigger selection state changes. */
         this.modelManager = null;
+        /** Current list of selected option models rendered as “chips”. */
         this.modelDatas = [];
         if (options)
-            this.init(options);
+            this.initialize(options);
     }
     /**
-     * Creates the accessory box DOM node and stores the provided options.
-     * The node is initially hidden and stops mouseup events from bubbling.
+     * Stores options and starts the lifecycle.
      *
-     * @param {SelectiveOptions} options - Configuration object for the accessory box.
+     * Does not attach the node yet; the DOM structure is created in `init()`.
+     *
+     * @param options - Configuration object for the accessory box.
+     */
+    initialize(options) {
+        this.options = options;
+        this.init(); // Trigger lifecycle initialization
+    }
+    /**
+     * Initializes the accessory box DOM structure.
+     *
+     * - Creates the root node (hidden by default)
+     * - Stops mouseup events from propagating to parent containers
+     * - Completes the lifecycle initialization
      */
-    init(options) {
+    init() {
+        if (this.state !== LifecycleState.NEW)
+            return;
         this.nodeMounted = Libs.mountNode({
             AccessoryBox: {
                 tag: {
                     node: "div",
                     classList: ["selective-ui-accessorybox", "hide"],
                     onmouseup: (evt) => {
+                        // Prevent outside listeners from reacting to chip clicks
                         evt.stopPropagation();
                     },
                 },
             },
         });
         this.node = this.nodeMounted.view;
-        this.options = options;
+        super.init(); // Mark as INITIALIZED
     }
     /**
-     * Sets the root references for the accessory box (mask elements) and refreshes its location in the DOM.
+     * Binds to the Select UI mask and positions the accessory box relative to it.
+     *
+     * You should call this after the Select UI mask is available. This method
+     * will insert the accessory box either before or after the mask based on
+     * `options.accessoryStyle` and then call `mount()`.
      *
-     * @param {HTMLDivElement} selectUIMask - The overlay/mask element of the main Select UI.
+     * @param selectUIMask - The overlay/mask element of the main Select UI.
      */
     setRoot(selectUIMask) {
         this.selectUIMask = selectUIMask;
         this.parentMask = selectUIMask.parentElement;
         this.refreshLocation();
+        this.mount();
+    }
+    /**
+     * Lifecycle mount override (no-op guard).
+     *
+     * Ensures mount is only applied once the component has been initialized.
+     */
+    mount() {
+        if (!this.is(LifecycleState.INITIALIZED)) {
+            return;
+        }
+        super.mount();
     }
     /**
-     * Inserts the accessory box before or after the Select UI mask depending on the configured accessoryStyle.
-     * Keeps the accessory box aligned relative to the parent mask.
+     * Positions the accessory box relative to the Select UI mask.
+     *
+     * Placement rules:
+     * - `accessoryStyle === "top"` → insert before the mask
+     * - otherwise → insert after the mask
+     *
+     * Also keeps the accessory box aligned under the same parent container.
      */
     refreshLocation() {
         if (!this.parentMask ||
@@ -2994,18 +3738,30 @@ class AccessoryBox {
         this.parentMask.insertBefore(this.node, ref);
     }
     /**
-     * Assigns a ModelManager instance used to trigger and manage selection state changes.
+     * Assigns the `ModelManager` instance used to trigger selection changes.
      *
-     * @param {ModelManager} modelManager - The model manager controlling option state.
+     * @param modelManager - The model manager controlling option state.
      */
     setModelManager(modelManager) {
         this.modelManager = modelManager;
     }
     /**
-     * Renders accessory items for the currently selected options in multiple-select mode.
-     * Shows the accessory box when there are items; otherwise hides it. Triggers a window resize event.
+     * Renders accessory items (“chips”) for the provided selected options.
+     *
+     * Behavior:
+     * - Clears the current container
+     * - For multi-select mode with non-empty data, mounts each chip:
+     *   - A “button” (span with role="button") to deselect the option
+     *   - A content span showing the option’s text (HTML is preserved as provided)
+     * - When the button is clicked:
+     *   - Calls `modelManager.triggerChanging("select")`
+     *   - Sets `modelData.selected = false`
+     *
+     * Finally:
+     * - Updates visibility based on config and chip count
+     * - Emits lifecycle `update()` and a window `"resize"` event
      *
-     * @param {OptionModel[]} modelDatas - List of option models to render as accessory items.
+     * @param modelDatas - List of option models representing current selections.
      */
     setModelData(modelDatas) {
         if (!this.node || !this.options)
@@ -3048,38 +3804,107 @@ class AccessoryBox {
         }
         this.modelDatas = modelDatas;
         this.refreshDisplay();
+        this.update(); // lifecycle UPDATE
         iEvents.trigger(window, "resize");
     }
+    /**
+     * Lifecycle update override (no-op guard).
+     *
+     * Ensures update is only emitted after the component is mounted.
+     */
+    update() {
+        if (this.state !== LifecycleState.MOUNTED)
+            return;
+        super.update();
+    }
+    /**
+     * Applies visibility rules based on configuration and chip count.
+     *
+     * Visible when:
+     * - `accessoryVisible` is truthy
+     * - There is at least one selected item
+     * - The Select is in multiple mode
+     */
     refreshDisplay() {
-        if (this.options?.accessoryVisible && this.modelDatas.length > 0 && this.options.multiple) {
+        if (this.options?.accessoryVisible &&
+            this.modelDatas.length > 0 &&
+            this.options.multiple) {
             this.show();
         }
         else {
             this.hide();
         }
     }
+    /** Shows the accessory box. */
     show() {
-        this.node.classList.remove("hide");
+        this.node?.classList.remove("hide");
     }
+    /** Hides the accessory box. */
     hide() {
-        this.node.classList.add("hide");
+        this.node?.classList.add("hide");
+    }
+    /**
+     * Destroys the accessory box and releases resources.
+     *
+     * - Removes the root DOM node
+     * - Clears references to mounted structures, options, masks, and ModelManager
+     * - Resets internal model data
+     * - Ends the lifecycle
+     */
+    destroy() {
+        if (this.state === LifecycleState.DESTROYED)
+            return;
+        // Clean up DOM
+        this.node?.remove();
+        // Clear references
+        this.nodeMounted = null;
+        this.node = null;
+        this.options = null;
+        this.selectUIMask = null;
+        this.parentMask = null;
+        this.modelManager = null;
+        this.modelDatas = [];
+        super.destroy();
     }
 }
 
-class SearchController {
+/**
+ * Controller responsible for orchestrating search behavior across the Select UI.
+ *
+ * Responsibilities:
+ * - Manage local (in-memory) filtering and remote (AJAX) searching
+ * - Normalize heterogeneous server responses into a common structure
+ * - Maintain pagination state (page, totals, loading, hasMore)
+ * - Apply remote results back to the underlying <select> element
+ * - Coordinate UI updates via Popup (loading indicator, resize, empty/not-found states)
+ *
+ * Lifecycle:
+ * - Constructed with references to the native <select>, ModelManager, and SelectBox
+ * - `init()` runs immediately via `initialize()`
+ * - Methods `search()`, `loadMore()`, `clear()` are invoked by higher-level components
+ *
+ * @extends Lifecycle
+ */
+class SearchController extends Lifecycle {
     /**
      * Initializes the SearchController with a source <select> element and a ModelManager
      * to manage option models and search results.
      *
-     * @param {HTMLSelectElement} selectElement - The native select element that provides context and data source.
-     * @param {ModelManager<MixedItem, any>} modelManager - Manager responsible for models and rendering updates.
-     * @param {SelectBox} selectBox - SelectBox handle.
+     * @param selectElement - The native select element that provides context and data source.
+     * @param modelManager - Manager responsible for models and rendering updates.
+     * @param selectBox - SelectBox handle.
      */
     constructor(selectElement, modelManager, selectBox) {
+        super();
+        /** Current AJAX configuration; when absent, local search is used. */
         this.ajaxConfig = null;
+        /** Used to cancel in-flight AJAX requests when a new search starts. */
         this.abortController = null;
+        /** Popup instance to reflect UI states (loading, empty/not-found), and sizing. */
         this.popup = null;
+        /** SelectBox handle (used by custom data builders). */
         this.selectBox = null;
+        /** Current pagination and loading state for remote searches. */
         this.paginationState = {
             currentPage: 0,
             totalPages: 1,
@@ -3088,22 +3913,39 @@ class SearchController {
             currentKeyword: "",
             isPaginationEnabled: false,
         };
+        this.initialize(selectElement, modelManager, selectBox);
+    }
+    /**
+     * Internal initializer that captures dependencies and starts the lifecycle.
+     *
+     * @param selectElement - The native select element that provides context and data source.
+     * @param modelManager - Manager responsible for models and rendering updates.
+     * @param selectBox - SelectBox handle.
+     */
+    initialize(selectElement, modelManager, selectBox) {
         this.select = selectElement;
         this.modelManager = modelManager;
         this.selectBox = selectBox;
+        this.init();
     }
     /**
      * Indicates whether AJAX-based search is configured.
      *
-     * @returns {boolean} - True if AJAX config is present; false otherwise.
+     * @returns True if AJAX config is present; false otherwise.
      */
     isAjax() {
         return !!this.ajaxConfig;
     }
     /**
-     * Load specific options by their values from server
-     * @param {string|string[]} values - Values to load
-     * @returns {Promise<{success: boolean, items: Array, message?: string}>}
+     * Loads specific options by their values from the server.
+     *
+     * Behavior:
+     * - Uses `ajaxConfig.dataByValues` if provided; otherwise builds a default payload.
+     * - Supports GET/POST according to `ajaxConfig.method` (defaults to GET).
+     * - Normalizes the response via `parseResponse()` and returns normalized items.
+     *
+     * @param values - Value or list of values to load.
+     * @returns Promise resolving with `{ success, items, message? }`.
      */
     async loadByValues(values) {
         if (!this.ajaxConfig) {
@@ -3122,7 +3964,9 @@ class SearchController {
                 payload = {
                     values: valuesArray.join(","),
                     load_by_values: "1",
-                    ...(typeof cfg.data === "function" ? cfg.data.bind(this.selectBox.Selective.find(this.selectBox.container.targetElement))("", 0) : cfg.data ?? {}),
+                    ...(typeof cfg.data === "function"
+                        ? cfg.data.bind(this.selectBox.Selective.find(this.selectBox.container.targetElement))("", 0)
+                        : cfg.data ?? {}),
                 };
             }
             let response;
@@ -3143,6 +3987,7 @@ class SearchController {
                 throw new Error(`HTTP error! status: ${response.status}`);
             const data = await response.json();
             const result = this.parseResponse(data);
+            this.update();
             return { success: true, items: result.items };
         }
         catch (error) {
@@ -3151,9 +3996,10 @@ class SearchController {
         }
     }
     /**
-     * Check if values exist in current options
-     * @param {string[]} values - Values to check
-     * @returns {{existing: string[], missing: string[]}}
+     * Checks whether the provided values already exist in the current <select> options.
+     *
+     * @param values - Values to check for presence.
+     * @returns Partitioned result: `{ existing, missing }`.
      */
     checkMissingValues(values) {
         const allOptions = Array.from(this.select.options);
@@ -3165,7 +4011,7 @@ class SearchController {
     /**
      * Configures AJAX settings used for remote searching and pagination.
      *
-     * @param {object} config - AJAX configuration object (e.g., endpoint, headers, query params).
+     * @param config - AJAX configuration (endpoint, method, data builders, etc.).
      */
     setAjax(config) {
         this.ajaxConfig = config;
@@ -3173,13 +4019,15 @@ class SearchController {
     /**
      * Attaches a Popup instance to allow UI updates during search (e.g., loading, resize).
      *
-     * @param {Popup} popupInstance - The popup used to display search results and loading state.
+     * @param popupInstance - The popup used to display search results and loading state.
      */
     setPopup(popupInstance) {
         this.popup = popupInstance;
     }
     /**
      * Returns a shallow copy of the current pagination state used for search/infinite scroll.
+     *
+     * @returns Pagination state snapshot.
      */
     getPaginationState() {
         return { ...this.paginationState };
@@ -3200,6 +4048,8 @@ class SearchController {
     }
     /**
      * Clears the current keyword and makes all options visible (local reset).
+     *
+     * No network requests are made; operates on the current model set.
      */
     clear() {
         this.paginationState.currentKeyword = "";
@@ -3217,14 +4067,20 @@ class SearchController {
     }
     /**
      * Performs a search with either AJAX or local filtering depending on configuration.
+     *
+     * @param keyword - The search term to apply.
+     * @param append - For AJAX mode: whether to append results (next page). Defaults to false.
+     * @returns An implementation-specific result object.
      */
     async search(keyword, append = false) {
         if (this.ajaxConfig)
-            return this._ajaxSearch(keyword, append);
-        return this._localSearch(keyword);
+            return this.ajaxSearch(keyword, append);
+        return this.localSearch(keyword);
     }
     /**
      * Loads the next page for AJAX pagination if enabled and not already loading.
+     *
+     * @returns Result of the paginated AJAX request, or an error when not applicable.
      */
     async loadMore() {
         if (!this.ajaxConfig)
@@ -3236,13 +4092,16 @@ class SearchController {
         if (!this.paginationState.hasMore)
             return { success: false, message: "No more data" };
         this.paginationState.currentPage++;
-        return this._ajaxSearch(this.paginationState.currentKeyword, true);
+        return this.ajaxSearch(this.paginationState.currentKeyword, true);
     }
     /**
      * Executes a local (in-memory) search by normalizing the keyword (lowercase, non-accent)
-     * and toggling each option's visibility based on text match. Returns summary flags.
+     * and toggling each option's visibility based on text match.
+     *
+     * @param keyword - Keyword to filter against local options.
+     * @returns Summary flags: `{ success, hasResults, isEmpty }`.
      */
-    async _localSearch(keyword) {
+    async localSearch(keyword) {
         if (this.compareSearchTrigger(keyword))
             this.paginationState.currentKeyword = keyword;
         const lower = String(keyword ?? "").toLowerCase();
@@ -3262,6 +4121,7 @@ class SearchController {
             if (isVisible)
                 hasVisibleItems = true;
         });
+        this.update();
         return {
             success: true,
             hasResults: hasVisibleItems,
@@ -3271,14 +4131,28 @@ class SearchController {
     /**
      * Checks whether the provided keyword differs from the current one,
      * to determine if a new search should be triggered.
+     *
+     * @param keyword - The keyword to compare with the current search term.
+     * @returns True if a new search should be triggered; otherwise false.
      */
     compareSearchTrigger(keyword) {
         return keyword !== this.paginationState.currentKeyword;
     }
     /**
      * Executes an AJAX-based search with optional appending.
+     *
+     * Behavior:
+     * - Aborts any in-flight request before starting a new search
+     * - Shows loading in the popup (if available)
+     * - Supports GET/POST with data built from config or function
+     * - Applies normalized results to the <select>, respecting `keepSelected`
+     * - Updates pagination state when server response includes pagination info
+     *
+     * @param keyword - Search keyword.
+     * @param append - Whether to append results (true = next page); defaults to false.
+     * @returns An implementation-specific result object with success and pagination flags.
      */
-    async _ajaxSearch(keyword, append = false) {
+    async ajaxSearch(keyword, append = false) {
         const cfg = this.ajaxConfig;
         if (this.compareSearchTrigger(keyword)) {
             this.resetPagination();
@@ -3332,6 +4206,7 @@ class SearchController {
             this.applyAjaxResult(result.items, !!cfg.keepSelected, append);
             this.paginationState.isLoading = false;
             this.popup?.hideLoading();
+            this.update();
             return {
                 success: true,
                 hasResults: result.items.length > 0,
@@ -3352,7 +4227,20 @@ class SearchController {
         }
     }
     /**
-     * Parses various server response shapes into a normalized structure for options and groups.
+     * Normalizes various server response shapes into a standard structure for options and groups.
+     *
+     * Supported shapes (examples):
+     * - `{ object: [...], page?, totalPages?, hasMore? }`
+     * - `{ data: [...], page?, totalPages?, hasMore? }`
+     * - `{ items: [...], pagination: { page, totalPages, hasMore } }`
+     * - `[...]` (array of items)
+     *
+     * Each item can represent either:
+     * - An option: `{ type: "option", value, text, selected?, data? }`
+     * - A group: `{ type: "optgroup", label, data?, options: [...] }`
+     *
+     * @param data - Server response (any shape).
+     * @returns `{ items, hasPagination, page, totalPages, hasMore }`
      */
     parseResponse(data) {
         let items = [];
@@ -3419,6 +4307,15 @@ class SearchController {
     }
     /**
      * Applies normalized AJAX results to the underlying <select> element.
+     *
+     * Behavior:
+     * - Optionally preserves existing selections (`keepSelected`)
+     * - Clears existing children unless `append` is true
+     * - Supports adding either normalized items or raw HTMLOption/HTMLOptGroup elements
+     *
+     * @param items - Normalized items (or raw HTMLOption/HTMLOptGroup).
+     * @param keepSelected - Preserve previously selected options.
+     * @param append - Append to existing options instead of replacing.
      */
     applyAjaxResult(items, keepSelected, append = false) {
         const select = this.select;
@@ -3428,7 +4325,7 @@ class SearchController {
         if (!append)
             select.innerHTML = "";
         items.forEach((item) => {
-            // Skip empty item
+            // Skip empty item (defensive guard)
             if ((item["type"] === "option" || !item["type"]) && item["value"] === "" && item["text"] === "")
                 return;
             if (item instanceof HTMLOptionElement || item instanceof HTMLOptGroupElement) {
@@ -3477,6 +4374,25 @@ class SearchController {
             }
         });
     }
+    /**
+     * Destroys the controller and clears references.
+     *
+     * Notes:
+     * - In-flight requests are not aborted here; consumers should abort if needed before destroy.
+     * - The linked Popup/ModelManager exist outside this controller and are not destroyed here.
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.select = null;
+        this.modelManager = null;
+        this.ajaxConfig = null;
+        this.abortController = null;
+        this.popup = null;
+        this.selectBox = null;
+        super.destroy();
+    }
 }
 
 /**
@@ -3640,36 +4556,54 @@ class DatasetObserver {
 }
 
 /**
- * @template TItem
- * @template TViewer
+ * Base adapter that manages a list of model items and their corresponding views.
+ *
+ * Responsibilities:
+ * - Hold and manage an item list (`items`)
+ * - Create/bind item views (via `viewHolder()` and `onViewHolder()`)
+ * - Expose a property-change event pipeline (`onPropChanging` / `onPropChanged`)
+ * - Cooperate with a RecyclerView through `updateRecyclerView(parent)`
+ * - Participate in the standard lifecycle (`init` → `mount` → `update` → `destroy`)
+ *
+ * Notes:
+ * - Items are expected to embed a `view` reference and an `isInit` flag to track first render.
+ * - Subclasses should override `viewHolder()` to return a concrete `TViewer`.
+ *
+ * @template TItem - Model type the adapter operates on. Must contain `{ view: TViewer | null; isInit: boolean }`.
+ * @template TViewer - View type associated with each item (must implement `ViewContract`).
+ *
  * @implements {AdapterContract<TItem>}
  */
-class Adapter {
+class Adapter extends Lifecycle {
     /**
-     * Initializes the adapter with an optional array of items and invokes onInit()
-     * to perform any subclass-specific setup. Accepts a generic list of models.
+     * Initializes the adapter with an optional array of items and starts its lifecycle.
+     * Subclasses may override the lifecycle hooks (e.g., `onInit`) for custom setup.
      *
      * @param {TItem[]} [items=[]] - Initial items to be managed by the adapter.
      */
     constructor(items = []) {
+        super();
+        /** Current list of items managed by the adapter. */
         this.items = [];
+        /** Unique key for this adapter instance (used to namespace callback pipelines). */
         this.adapterKey = Libs.randomString(12);
+        /** When true, suppresses certain event emissions (reserved for external coordination). */
         this.isSkipEvent = false;
         this.items = items;
-        this.onInit();
+        this.init();
     }
     /**
-     * Lifecycle hook called once after construction. Override in subclasses to
-     * perform setup tasks (e.g., event wiring, cache building).
-     */
-    onInit() { }
-    /**
-     * Binds an item model to its viewer at a given position. If the item has not
-     * been initialized yet, renders the viewer; otherwise triggers an update.
+     * Binds an item model to its viewer at a given position.
+     *
+     * Behavior:
+     * - If the item has been initialized (`isInit = true`), calls `viewer.update()`
+     * - Otherwise, calls `viewer.mount()` to perform the initial render
+     *
+     * Subclasses may override to customize bind logic (animations, diffing, etc.).
      *
      * @param {TItem} item - The model instance to bind to the view.
-     * @param {TViewer|null} viewer - The view instance responsible for rendering the model.
-     * @param {number} position - The index of the item within the adapter.
+     * @param {TViewer|null} viewer - The view responsible for rendering the model.
+     * @param {number} position - Index of the item within the adapter.
      */
     onViewHolder(item, viewer, position) {
         const v = viewer;
@@ -3677,56 +4611,68 @@ class Adapter {
             v?.update?.();
         }
         else {
-            v?.render?.();
+            v?.mount?.();
         }
     }
     /**
-     * Registers a pre-change (debounced) callback for a property change pipeline.
-     * The callback is scheduled with a minimal delay to batch rapid updates.
+     * Registers a **pre-change** callback for a property pipeline (e.g., `"items"`).
      *
-     * @param {string} propName - The property name to observe (e.g., "items").
+     * Execution semantics:
+     * - Scheduled with minimal debounce (0ms) by the global callback scheduler
+     * - Runs **before** the property value is updated
+     * - Can be used to clear UI or allocate resources
+     *
+     * @param {string} propName - Property name to observe (e.g., `"items"`).
      * @param {Function} callback - Function to execute before the property changes.
      */
     onPropChanging(propName, callback) {
         Libs.callbackScheduler.on(`${propName}ing_${this.adapterKey}`, callback, { debounce: 0 });
     }
     /**
-     * Registers a post-change callback for a property change pipeline.
-     * The callback is executed after the property is updated.
+     * Registers a **post-change** callback for a property pipeline (e.g., `"items"`).
+     *
+     * Execution semantics:
+     * - Scheduled with minimal debounce (0ms) by the global callback scheduler
+     * - Runs **after** the property value is updated
+     * - Can be used to re-render or refresh UI
      *
-     * @param {string} propName - The property name to observe (e.g., "items").
+     * @param {string} propName - Property name to observe (e.g., `"items"`).
      * @param {Function} callback - Function to execute after the property changes.
      */
     onPropChanged(propName, callback) {
         Libs.callbackScheduler.on(`${propName}_${this.adapterKey}`, callback, { debounce: 0 });
     }
     /**
-     * Triggers the post-change pipeline for a given property, passing optional parameters
-     * to registered callbacks. Use this after mutating adapter state.
+     * Triggers the **post-change** pipeline for a given property.
+     * Use this **after** mutating the adapter state.
      *
-     * @param {string} propName - The property name to emit (e.g., "items").
+     * @param {string} propName - Property name to emit (e.g., `"items"`).
      * @param {...any} params - Parameters forwarded to the callbacks.
+     * @returns {Promise<void>} - Resolves when all callbacks complete.
      */
     changeProp(propName, ...params) {
         return Libs.callbackScheduler.run(`${propName}_${this.adapterKey}`, ...params);
     }
     /**
-     * Triggers the pre-change pipeline for a given property, passing optional parameters
-     * to registered callbacks. Use this before mutating adapter state.
+     * Triggers the **pre-change** pipeline for a given property.
+     * Use this **before** mutating the adapter state.
      *
-     * @param {string} propName - The property name to emit (e.g., "items").
+     * @param {string} propName - Property name to emit (e.g., `"items"`).
      * @param {...any} params - Parameters forwarded to the callbacks.
+     * @returns {Promise<void>} - Resolves when all callbacks complete.
      */
     changingProp(propName, ...params) {
         return Libs.callbackScheduler.run(`${propName}ing_${this.adapterKey}`, ...params);
     }
     /**
-     * Creates and returns a viewer instance for the given item within the specified parent container.
-     * Override in subclasses to return a concrete view implementation tailored to TItem.
+     * Factory method that creates a viewer instance for the given item,
+     * attached to the specified parent container.
      *
-     * @param {HTMLElement} parent - The container element that will host the viewer.
-     * @param {TItem} item - The model instance for which the viewer is created.
-     * @returns {TViewer|null} - The created viewer instance; null by default.
+     * Subclasses **must** override this to return a concrete viewer.
+     *
+     * @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.
      */
     viewHolder(parent, item) {
         return null;
@@ -3740,8 +4686,16 @@ class Adapter {
         return this.items.length;
     }
     /**
-     * Replaces the adapter's items with a new collection, emitting pre-change and post-change
-     * notifications to observers. Does not render; call updateRecyclerView() to apply to the DOM.
+     * Replaces the adapter's items with a new collection.
+     *
+     * Event flow:
+     * 1) Emit `changingProp('items')` (pre-change)
+     * 2) Assign the new items array
+     * 3) Emit `changeProp('items')` (post-change)
+     * 4) Emit lifecycle `update()`
+     *
+     * Note: This does **not** directly render to the DOM.
+     * Call `updateRecyclerView()` (typically via RecyclerView) to apply.
      *
      * @param {TItem[]} items - The new list of items to set.
      */
@@ -3749,10 +4703,10 @@ class Adapter {
         await this.changingProp("items", items);
         this.items = items;
         await this.changeProp("items", items);
+        this.update();
     }
     /**
-     * Synchronizes adapter items from an external source by delegating to setItems().
-     * Useful for keeping adapter state aligned with another data store.
+     * Synchronizes adapter items from an external source by delegating to `setItems()`.
      *
      * @param {TItem[]} items - The source list of items to synchronize.
      */
@@ -3760,10 +4714,16 @@ class Adapter {
         await this.setItems(items);
     }
     /**
-     * Iterates through all items and ensures each has a viewer. For new items, calls viewHolder()
-     * to create the viewer, then binds via onViewHolder() and marks the item as initialized.
+     * Ensures each item has a viewer, then binds it through `onViewHolder()`.
+     *
+     * Flow:
+     * - Iterate items in order
+     * - If an item is not initialized:
+     *   - Create a viewer via `viewHolder(parent, item)` and assign to `item.view`
+     * - Call `onViewHolder(item, viewer, index)` to mount/update accordingly
+     * - Mark item as initialized (`isInit = true`)
      *
-     * @param {HTMLElement} parent - The container element in which item viewers are rendered.
+     * @param {HTMLElement} parent - The container in which item viewers are rendered.
      */
     updateRecyclerView(parent) {
         for (let index = 0; index < this.itemCount(); index++) {
@@ -3778,65 +4738,127 @@ class Adapter {
         }
     }
     /**
-     * Updates adapter data without performing any default actions.
-     * Override in subclasses to implement custom data refresh logic.
+     * Hook for updating adapter data without performing default actions.
+     * Subclasses can override to implement custom refresh logic.
      *
-     * @param {TItem[]} items - The incoming data to apply to the adapter.
+     * @param {TItem[]} items - Incoming data to apply to the adapter.
      */
     updateData(items) {
     }
+    /**
+     * Destroys the adapter and releases references.
+     *
+     * - Clears the RecyclerView reference (if any)
+     * - Empties the item array
+     * - (Subclasses may override to destroy item views if needed)
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.recyclerView = null;
+        this.items.forEach(item => {
+            item?.destroy?.();
+        });
+        this.items = [];
+    }
 }
 
 /**
- * @template TTags
+ * Base View class that anchors a mounted DOM structure into a parent container.
+ *
+ * Responsibilities:
+ * - Hold a reference to the parent container (`parent`)
+ * - Store the mounted structure (`view`) returned by a mounting helper
+ * - Provide a safe getter for the root element (`getView()`)
+ * - Participate in the standard lifecycle (`init` → `mount` → `update` → `destroy`)
+ *
+ * Typical usage:
+ * - Subclasses set `this.view` inside `onMount()` using a mounting utility
+ * - Then call `this.parent!.appendChild(this.view.view)`
+ *
+ * @template TTags - A map of tag names to their corresponding HTMLElement instances.
  * @implements {ViewContract<TTags>}
  */
-class View {
+class View extends Lifecycle {
     /**
-     * Initializes the view with a parent container element that will host its rendered content.
+     * Creates a View bound to the specified parent container.
+     *
+     * Note: Subclasses should assign `this.view` during `onMount()` before
+     * attempting to access `getView()` or manipulate the root element.
      *
-     * @param {HTMLElement} parent - The parent element into which this view will render.
+     * @param parent - The parent element into which this view will render.
      */
     constructor(parent) {
+        super();
+        /** The parent DOM element into which this view is rendered. */
         this.parent = null;
+        /**
+         * Mounted result containing:
+         * - `view`: the root element of this view
+         * - `tags`: a strongly-typed map of child elements
+         */
         this.view = null;
         this.parent = parent;
+        this.init();
     }
-    /**
-     * Renders the view into the parent container.
-     * Override in subclasses to create DOM structure and mount tags.
-     */
-    render() { }
-    /**
-     * Updates the view to reflect model or state changes.
-     * Override in subclasses to patch DOM nodes without full re-render.
-     */
-    update() { }
     /**
      * Returns the root HTMLElement of the mounted view.
      *
-     * @returns {HTMLElement} - The root view element.
+     * @returns The root element produced by the mounting helper.
+     * @throws {Error} If the view has not been mounted or `this.view` is not set.
      */
     getView() {
-        if (!this.view?.view)
+        if (!this.view?.view) {
             throw new Error("View is not mounted. Did you forget to set this.view?");
+        }
         return this.view.view;
     }
+    /**
+     * Destroys the view and releases DOM references.
+     *
+     * - Removes the root element from the DOM (if present)
+     * - Clears references to `parent` and `view`
+     * - Ends the lifecycle via `super.destroy()`
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.getView()?.remove?.();
+        this.parent = null;
+        this.view = null;
+        super.destroy();
+    }
 }
 
 /**
- * @extends {View<GroupViewTags>}
+ * View implementation responsible for rendering and managing
+ * a grouped collection of selectable items.
+ *
+ * The group consists of:
+ * - A header element (label)
+ * - A container holding child item views
+ *
+ * @extends View<GroupViewTags>
  */
 class GroupView extends View {
     constructor() {
         super(...arguments);
+        /**
+         * Strongly-typed reference to the mounted group view structure.
+         * Will be null until the view has been mounted.
+         */
         this.view = null;
     }
     /**
-     * Renders the group view structure (header + items container), sets ARIA attributes,
-     * and appends the root element to the parent container.
+     * Mounts the group view into the DOM.
+     *
+     * Creates the group container, header, and items wrapper,
+     * applies required ARIA attributes, and appends the root
+     * element to the parent container.
      */
-    render() {
+    mount() {
         const group_id = Libs.randomString(7);
         this.view = Libs.mountView({
             GroupView: {
@@ -3866,53 +4888,68 @@ class GroupView extends View {
                 },
             },
         });
-        // Parent is guaranteed by base constructor.
+        // Parent is guaranteed to exist by the base View constructor.
         this.parent.appendChild(this.view.view);
+        super.mount();
     }
     /**
-     * Performs a lightweight refresh of the view (currently updates the header label).
+     * Called when the view needs to be updated.
+     *
+     * Currently performs a lightweight refresh by updating
+     * the group header label.
      */
     update() {
         this.updateLabel();
+        super.update();
     }
     /**
-     * Updates the group header text content if a label is provided.
+     * Updates the text content of the group header.
      *
-     * @param {string|null} [label=null] - The new label to display; if null, keeps current.
+     * @param label - The new label to display.
+     *                If null, the existing label is preserved.
      */
     updateLabel(label = null) {
         if (!this.view)
             return;
         const headerEl = this.view.tags.GroupHeader;
-        if (label !== null)
+        if (label !== null) {
             headerEl.textContent = label;
+        }
     }
     /**
-     * Returns the container element that holds all option/item views in this group.
+     * Returns the container element that holds all item/option views
+     * belonging to this group.
      *
-     * @returns {HTMLDivElement} - The items container element.
+     * @returns The HTMLDivElement used as the items container.
+     * @throws {Error} If the view has not been mounted yet.
      */
     getItemsContainer() {
-        if (!this.view)
-            throw new Error("GroupView is not rendered.");
+        if (!this.view) {
+            throw new Error("GroupView has not been rendered.");
+        }
         return this.view.tags.GroupItems;
     }
     /**
-     * Toggles the group's visibility based on whether any child item is visible.
-     * Hides the entire group when all children are hidden.
+     * Updates the visibility of the group based on its children.
+     *
+     * If all child items are hidden, the entire group
+     * will be hidden as well.
      */
     updateVisibility() {
         if (!this.view)
             return;
         const items = this.view.tags.GroupItems;
-        const visibleItems = Array.from(items.children).filter((child) => !child.classList.contains("hide"));
-        const isVisible = visibleItems.length > 0;
-        this.view.view.classList.toggle("hide", !isVisible);
+        const visibleItems = Array.from(items.children).filter(child => !child.classList.contains("hide"));
+        this.view.view.classList.toggle("hide", visibleItems.length === 0);
     }
     /**
-     * Sets the collapsed state on the group and updates ARIA attributes accordingly.
+     * Sets the collapsed/expanded state of the group.
      *
-     * @param {boolean} collapsed - True to collapse; false to expand.
+     * This updates both:
+     * - Visual state (CSS classes)
+     * - Accessibility state (ARIA attributes)
+     *
+     * @param collapsed - True to collapse the group, false to expand it.
      */
     setCollapsed(collapsed) {
         if (!this.view)
@@ -3923,30 +4960,62 @@ class GroupView extends View {
 }
 
 /**
- * @extends {View<OptionViewTags>}
+ * View implementation for a single selectable option.
+ *
+ * An option may consist of:
+ * - An input element (radio or checkbox)
+ * - An optional image
+ * - A label container
+ *
+ * This view supports reactive configuration changes via a Proxy,
+ * allowing partial DOM updates without fully re-rendering the view.
+ *
+ * @extends View<OptionViewTags>
  */
 class OptionView extends View {
     /**
-     * Initializes the OptionView with a parent container and sets up the reactive config proxy.
-     * The proxy enables partial DOM updates when config properties change after initial render.
+     * Creates a new OptionView bound to the given parent element.
      *
-     * @param {HTMLElement} parent - The parent element into which this view will be mounted.
+     * Initializes the internal configuration and sets up
+     * a reactive Proxy to track and apply configuration changes.
+     *
+     * @param parent - The container element that will host this option view.
      */
     constructor(parent) {
         super(parent);
+        /**
+         * Reference to the mounted option view.
+         * Set during `onMount`; null before render.
+         */
         this.view = null;
+        /**
+         * Internal configuration state used as the Proxy target.
+         * Should not be mutated directly.
+         */
         this.config = null;
+        /**
+         * Proxy wrapper around `config`.
+         * Assigning properties on this object triggers incremental
+         * DOM updates once the view has been rendered.
+         */
         this.configProxy = null;
+        /**
+         * Indicates whether the initial render has been completed.
+         * Partial DOM updates are skipped until this becomes true.
+         */
         this.isRendered = false;
-        this.setupConfigProxy();
+        this.initialize();
     }
     /**
-     * Creates the internal configuration object and wraps it with a Proxy.
-     * The proxy intercepts property assignments and, if the view is rendered,
-     * applies only the necessary DOM changes for the updated property.
-     * No DOM mutations occur before the first render.
+     * Initializes the default configuration object and wraps it in a Proxy.
+     *
+     * The Proxy intercepts property assignments and:
+     * - Updates internal state
+     * - Applies targeted DOM changes when the view is already rendered
+     *
+     * No DOM mutations occur before the initial render.
      */
-    setupConfigProxy() {
+    initialize() {
         const self = this;
         this.config = {
             isMultiple: false,
@@ -3973,54 +5042,59 @@ class OptionView extends View {
                 return true;
             },
         });
+        this.init();
     }
     /**
-     * Indicates whether the option supports multiple selection (checkbox) instead of single (radio).
+     * Indicates whether the option supports multiple selection.
      *
-     * @returns {boolean} True if multiple selection is enabled; otherwise false.
+     * - `false`: single selection (radio)
+     * - `true`: multiple selection (checkbox)
      */
     get isMultiple() {
         return this.config.isMultiple;
     }
     /**
      * Enables or disables multiple selection mode.
-     * When rendered, toggles the root CSS class and switches the input type between 'checkbox' and 'radio'.
      *
-     * @param {boolean} value - True to enable multiple selection; false for single selection.
+     * When rendered:
+     * - Toggles the `multiple` CSS class on the root element
+     * - Switches the input type between `radio` and `checkbox`
      */
     set isMultiple(value) {
         this.configProxy.isMultiple = !!value;
     }
     /**
-     * Indicates whether the option includes an image block alongside the label.
-     *
-     * @returns {boolean} True if an image is displayed; otherwise false.
+     * Indicates whether the option displays an image next to the label.
      */
     get hasImage() {
         return this.config.hasImage;
     }
     /**
-     * Shows or hides the image block for the option.
-     * When rendered, toggles related CSS classes and creates/removes the image element accordingly.
+     * Shows or hides the image block.
      *
-     * @param {boolean} value - True to show the image; false to hide it.
+     * When rendered:
+     * - Toggles related CSS classes
+     * - Creates or removes the `<img>` element dynamically
      */
     set hasImage(value) {
         this.configProxy.hasImage = !!value;
     }
     /**
-     * Provides reactive access to the entire option configuration via a Proxy.
-     * Mutating properties on this object will trigger partial DOM updates when rendered.
+     * Provides reactive access to the full option configuration.
      *
-     * @returns {object} The proxied configuration object.
+     * Mutating properties on this object triggers incremental
+     * DOM updates when the view has already been rendered.
      */
     get optionConfig() {
         return this.configProxy;
     }
     /**
-     * Applies a set of configuration changes in batch.
-     * Only properties that differ from the current config are updated.
-     * When rendered, each changed property triggers a targeted DOM update via the proxy.
+     * Applies a batch of configuration changes.
+     *
+     * Only properties whose values differ from the current state
+     * are assigned to the Proxy and processed.
+     *
+     * @param config - Partial configuration patch
      */
     set optionConfig(config) {
         if (!config || !this.configProxy || !this.config)
@@ -4038,24 +5112,25 @@ class OptionView extends View {
             changes.labelValign = config.labelValign;
         if (config.labelHalign !== undefined && config.labelHalign !== this.config.labelHalign)
             changes.labelHalign = config.labelHalign;
-        if (Object.keys(changes).length > 0)
+        if (Object.keys(changes).length > 0) {
             Object.assign(this.configProxy, changes);
+        }
     }
     /**
-     * Renders the option view into the parent element.
-     * Builds the DOM structure (input, optional image, label) based on current config,
-     * assigns classes and ARIA attributes, mounts via Libs.mountView, and marks as rendered
-     * to allow future incremental updates through the config proxy.
+     * Performs the initial render of the option view.
+     *
+     * Builds the DOM structure based on the current configuration,
+     * assigns CSS classes and ARIA attributes, mounts the view via
+     * `Libs.mountView`, and enables reactive updates afterward.
      */
-    render() {
+    mount() {
         const viewClass = ["selective-ui-option-view"];
         const opt_id = Libs.randomString(7);
         const inputID = `option_${opt_id}`;
         if (this.config.isMultiple)
             viewClass.push("multiple");
         if (this.config.hasImage) {
-            viewClass.push("has-image");
-            viewClass.push(`image-${this.config.imagePosition}`);
+            viewClass.push("has-image", `image-${this.config.imagePosition}`);
         }
         const childStructure = {
             OptionInput: {
@@ -4108,10 +5183,14 @@ class OptionView extends View {
         });
         this.parent.appendChild(this.view.view);
         this.isRendered = true;
+        super.mount();
     }
     /**
-     * Applies a targeted DOM update for a single configuration property change.
-     * Safely updates classes, attributes, styles, and child elements without re-rendering the whole view.
+     * Applies a targeted DOM update for a single configuration change.
+     *
+     * Updates only the affected parts of the view
+     * (classes, attributes, styles, or child nodes)
+     * without triggering a full re-render.
      */
     applyPartialChange(prop, newValue, oldValue) {
         const v = this.view;
@@ -4137,18 +5216,20 @@ class OptionView extends View {
                     this.createImage();
                 }
                 else {
-                    root.className = root.className.replace(/image-(top|right|bottom|left)/g, "").trim();
+                    root.className = root.className
+                        .replace(/image-(top|right|bottom|left)/g, "")
+                        .trim();
                     const img = v.tags?.OptionImage;
-                    if (img) {
-                        img.remove();
-                        v.tags.OptionImage = null;
-                    }
+                    img?.remove();
+                    v.tags.OptionImage = null;
                 }
                 break;
             }
             case "imagePosition": {
                 if (this.config.hasImage) {
-                    root.className = root.className.replace(/image-(top|right|bottom|left)/g, "").trim();
+                    root.className = root.className
+                        .replace(/image-(top|right|bottom|left)/g, "")
+                        .trim();
                     root.classList.add(`image-${String(newValue)}`);
                 }
                 break;
@@ -4161,35 +5242,33 @@ class OptionView extends View {
                     const styleProp = prop === "imageWidth" ? "width" :
                         prop === "imageHeight" ? "height" :
                             "borderRadius";
-                    const val = String(newValue);
-                    if (img.style[styleProp] !== val)
-                        img.style[styleProp] = val;
+                    img.style[styleProp] = String(newValue);
                 }
                 break;
             }
             case "labelValign":
             case "labelHalign": {
                 if (label) {
-                    const newClass = `align-vertical-${this.config.labelValign} align-horizontal-${this.config.labelHalign}`;
-                    if (label.className !== newClass)
-                        label.className = newClass;
+                    label.className =
+                        `align-vertical-${this.config.labelValign} ` +
+                            `align-horizontal-${this.config.labelHalign}`;
                 }
                 break;
             }
         }
     }
     /**
-     * Creates the <img> element for the option on demand and inserts it into the DOM.
-     * Skips creation if the view or root is missing, or if an image already exists.
-     * The image receives configured styles (width, height, borderRadius) and is placed
-     * before the label if present; otherwise appended to the root. Updates `v.tags.OptionImage`.
+     * Creates and inserts the `<img>` element for the option on demand.
+     *
+     * The image is styled using the current configuration and is inserted
+     * before the label when possible. If an image already exists, no action
+     * is taken.
      */
     createImage() {
         const v = this.view;
         if (!v || !v.view)
             return;
-        const existing = v.tags?.OptionImage;
-        if (existing)
+        if (v.tags?.OptionImage)
             return;
         const root = v.view;
         const label = v.tags?.OptionLabel;
@@ -4198,27 +5277,64 @@ class OptionView extends View {
         image.style.width = this.config.imageWidth;
         image.style.height = this.config.imageHeight;
         image.style.borderRadius = this.config.imageBorderRadius;
-        if (label && label.parentElement)
+        if (label?.parentElement) {
             root.insertBefore(image, label);
-        else
+        }
+        else {
             root.appendChild(image);
+        }
         v.tags.OptionImage = image;
     }
 }
 
 /**
- * @extends {Adapter<GroupModel|OptionModel>}
+ * Adapter that can render a heterogeneous list composed of groups and options.
+ *
+ * Responsibilities:
+ * - Build and maintain a flat list of options for navigation and visibility stats
+ * - Create proper views based on item type (GroupView / OptionView)
+ * - Bind view logic (events, image/label rendering, collapsed/expanded state)
+ * - Track selection for both single and multiple-select modes
+ * - Emit visibility-change statistics to subscribed listeners
+ *
+ * Lifecycle / Events:
+ * - On `init()`: schedule a debounced visibility aggregation dispatcher
+ * - On item changes: rebuild the flat structure and notify observers
+ * - Delegates selection updates via the underlying `OptionModel` event hooks
+ *
+ * @extends Adapter
  */
 class MixedAdapter extends Adapter {
+    /**
+     * Creates a MixedAdapter with an optional initial list of items.
+     * Builds an initial flat structure for fast navigation and stats.
+     *
+     * @param items - Initial items (groups and/or options).
+     */
     constructor(items = []) {
         super(items);
+        /** Whether the adapter operates in multi-selection mode. */
         this.isMultiple = false;
+        /** Registered listeners for aggregated visibility statistics. */
         this.visibilityChangedCallbacks = [];
+        /** Index (in the flat list) of the currently highlighted option. */
         this.currentHighlightIndex = -1;
+        /** Cached pointer to the single selected item in single-select mode. */
         this.selectedItemSingle = null;
+        /** Top-level group models (if any). */
         this.groups = [];
+        /** Flat list of all option models (including those inside groups). */
         this.flatOptions = [];
         this.buildFlatStructure();
+    }
+    /**
+     * Initializes internal scheduling for visibility-change notifications,
+     * then calls the base lifecycle and mounts immediately.
+     *
+     * - Debounced `sche_vis_${adapterKey}` computes visibility aggregates
+     *   and invokes all registered `visibilityChangedCallbacks`.
+     */
+    init() {
         Libs.callbackScheduler.on(`sche_vis_${this.adapterKey}`, () => {
             const visibleCount = this.flatOptions.filter((item) => item.visible).length;
             const totalCount = this.flatOptions.length;
@@ -4230,11 +5346,18 @@ class MixedAdapter extends Adapter {
                     isEmpty: totalCount === 0,
                 });
             });
+            // Proxy hook; allows other listeners to chain after visibility aggregation.
             Libs.callbackScheduler.run(`sche_vis_proxy_${this.adapterKey}`);
         }, { debounce: 10 });
+        super.init();
+        this.mount();
     }
     /**
-     * Build flat list of all options for navigation
+     * Builds / rebuilds a flat list of options and captures group references.
+     *
+     * The flat list is used for:
+     * - navigation across visible options
+     * - computing visibility statistics quickly
      */
     buildFlatStructure() {
         this.flatOptions = [];
@@ -4250,11 +5373,11 @@ class MixedAdapter extends Adapter {
         });
     }
     /**
-     * Creates and returns the appropriate view instance for the given item type.
+     * Factory method returning the appropriate view implementation per item type.
      *
-     * @param {HTMLElement} parent - The parent container element where the view will be attached.
-     * @param {GroupModel|OptionModel} item - The data model representing either a group or an option.
-     * @returns {GroupView|OptionView} - A new view instance corresponding to the item type.
+     * @param parent - The container element where the view will be mounted.
+     * @param item - The item to render (group or option).
+     * @returns A new GroupView/OptionView instance based on the item type.
      */
     viewHolder(parent, item) {
         if (item instanceof GroupModel)
@@ -4262,12 +5385,12 @@ class MixedAdapter extends Adapter {
         return new OptionView(parent);
     }
     /**
-     * Binds a data model (GroupModel or OptionModel) to its corresponding view
-     * and delegates rendering logic based on the type of item.
+     * Binds a data model (group or option) to its view and delegates rendering
+     * to specialized handlers.
      *
-     * @param {GroupModel|OptionModel} item - The data model representing either a group or an option.
-     * @param {GroupView|OptionView|null} viewer - The view instance that displays the item in the UI.
-     * @param {number} position - The position (index) of the item within its parent list.
+     * @param item - GroupModel or OptionModel.
+     * @param viewer - The view instance that will render the model.
+     * @param position - Position of the item in the top-level list.
      */
     onViewHolder(item, viewer, position) {
         item.position = position;
@@ -4280,12 +5403,15 @@ class MixedAdapter extends Adapter {
         item.isInit = true;
     }
     /**
-     * Handles binding and rendering logic for a group view, including header behavior,
-     * collapse/expand state, and initialization of option items.
+     * Handles binding/rendering for a group:
+     * - Sets header text and click-to-toggle behavior
+     * - Observes collapsed state to hide/show child options
+     * - Ensures each child option is rendered and bound
+     * - Syncs collapsed state and visibility
      *
-     * @param {GroupModel} groupModel - The data model representing the group and its items.
-     * @param {GroupView} groupView - The view instance that renders the group in the UI.
-     * @param {number} position - The position (index) of the group within a list.
+     * @param groupModel - Group data model.
+     * @param groupView - Group view instance.
+     * @param position - Group index.
      */
     handleGroupView(groupModel, groupView, position) {
         super.onViewHolder(groupModel, groupView, position);
@@ -4319,12 +5445,15 @@ class MixedAdapter extends Adapter {
         groupView.updateVisibility();
     }
     /**
-     * Handles binding and rendering logic for an option item, including image setup,
-     * label rendering, event wiring, and selection state synchronization.
+     * Handles binding/rendering for an option:
+     * - Applies adapter-wide and model-specific visual configuration (image, label alignment, etc.)
+     * - Wires click/hover listeners for selection and highlighting
+     * - Syncs selection state (single vs multiple)
+     * - Updates image source/alt and label HTML
      *
-     * @param {OptionModel} optionModel - The data model representing a single option.
-     * @param {OptionView} optionViewer - The view instance that renders the option in the UI.
-     * @param {number} position - The index of this option within its group's item list.
+     * @param optionModel - Option data model.
+     * @param optionViewer - Option view instance.
+     * @param position - Option index within its group list.
      */
     handleOptionView(optionModel, optionViewer, position) {
         optionViewer.isMultiple = this.isMultiple;
@@ -4393,54 +5522,77 @@ class MixedAdapter extends Adapter {
         }
     }
     /**
-     * Updates the list of items in the component and rebuilds its internal flat structure.
+     * Replaces items and rebuilds the internal flat structure.
+     * Emits the standard pre/post change notifications and updates lifecycle.
      *
-     * @param {Array<GroupModel|OptionModel>} items - The new collection of items to be displayed.
+     * @param items - New mixed item collection (groups/options).
      */
     async setItems(items) {
         await this.changingProp("items", items);
         this.items = items;
         this.buildFlatStructure();
         await this.changeProp("items", items);
+        this.update();
     }
     /**
-     * Synchronizes the component's items from an external source by delegating to setItems().
+     * Synchronizes items from an external source by delegating to `setItems()`.
      *
-     * @param {Array<GroupModel|OptionModel>} items - The new collection of items to sync.
+     * @param items - New mixed item collection (groups/options).
      */
     async syncFromSource(items) {
         await this.setItems(items);
     }
     /**
-     * Updates the component's data items and rebuilds the internal flat structure
-     * without triggering change notifications.
+     * Updates items and rebuilds the flat structure **without** firing change notifications.
      *
-     * @param {Array<GroupModel|OptionModel>} items - The new collection of items to update.
+     * @param items - New mixed item collection (groups/options).
      */
     updateData(items) {
         this.items = items;
         this.buildFlatStructure();
+        this.update();
+    }
+    /**
+     * Destroys the adapter and cleans up:
+     * - Clears visibility scheduler
+     * - Destroys all groups (cascades to their items/views)
+     * - Resets cached state and arrays
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        Libs.callbackScheduler.clear(`sche_vis_${this.adapterKey}`);
+        this.groups.forEach(group => {
+            group.destroy();
+        });
+        this.visibilityChangedCallbacks = [];
+        this.currentHighlightIndex = -1;
+        this.selectedItemSingle = null;
+        this.groups = [];
+        this.flatOptions = [];
+        super.destroy();
     }
     /**
-     * Returns all option items that are currently selected.
+     * Returns all currently selected option items.
      *
-     * @returns {OptionModel[]} - An array of selected option items from the flat list.
+     * @returns Array of selected options from the flat list.
      */
     getSelectedItems() {
         return this.flatOptions.filter((item) => item.selected);
     }
     /**
-     * Returns the first selected option item, if any.
+     * Returns the first selected option (if any).
      *
-     * @returns {OptionModel|undefined} - The first selected option or undefined if none are selected.
+     * @returns The first selected option; `undefined` if none.
      */
     getSelectedItem() {
         return this.flatOptions.find((item) => item.selected);
     }
     /**
-     * Checks or unchecks all options when in multiple selection mode.
+     * Checks/unchecks all options when in multiple selection mode.
      *
-     * @param {boolean} isChecked - If true, select all; if false, deselect all.
+     * @param isChecked - `true` to select all; `false` to deselect all.
      */
     checkAll(isChecked) {
         if (!this.isMultiple)
@@ -4452,21 +5604,21 @@ class MixedAdapter extends Adapter {
     /**
      * Subscribes a callback to visibility changes across options.
      *
-     * @param {(stats: {visibleCount:number,totalCount:number,hasVisible:boolean,isEmpty:boolean}) => void} callback
-     * - Function to invoke when visibility stats change.
+     * @param callback - Invoked with aggregated visibility stats.
      */
     onVisibilityChanged(callback) {
         this.visibilityChangedCallbacks.push(callback);
     }
     /**
-     * Notifies all registered visibility-change callbacks with up-to-date statistics.
-     * Computes visible and total counts, then emits aggregated state.
+     * Schedules a visibility statistics recomputation and notifies subscribers.
      */
     notifyVisibilityChanged() {
         Libs.callbackScheduler.run(`sche_vis_${this.adapterKey}`);
     }
     /**
      * Computes and returns current visibility statistics for options.
+     *
+     * @returns Aggregated stats: `{ visibleCount, totalCount, hasVisible, isEmpty }`.
      */
     getVisibilityStats() {
         const visibleCount = this.flatOptions.filter((item) => item.visible).length;
@@ -4479,16 +5631,16 @@ class MixedAdapter extends Adapter {
         };
     }
     /**
-     * Resets the highlight to the first visible option (index 0).
+     * Resets the highlight to the first visible option.
      */
     resetHighlight() {
         this.setHighlight(0);
     }
     /**
-     * Moves the highlight forward/backward among visible options and optionally scrolls into view.
+     * Moves the highlight among visible options and optionally scrolls into view.
      *
-     * @param {number} direction - Increment (+1) or decrement (-1) of the current visible index.
-     * @param {boolean} [isScrollToView=true] - Whether to scroll the highlighted item into view.
+     * @param direction - +1 to move forward; -1 to move backward.
+     * @param isScrollToView - Whether to scroll the highlighted item into view. Defaults to `true`.
      */
     navigate(direction, isScrollToView = true) {
         const visibleOptions = this.flatOptions.filter((opt) => opt.visible);
@@ -4507,8 +5659,8 @@ class MixedAdapter extends Adapter {
         this.setHighlight(flatIndex, isScrollToView);
     }
     /**
-     * Triggers a click on the currently highlighted and visible option to select it.
-     * No-op if nothing is highlighted or the highlighted item is not visible.
+     * Triggers a click on the currently highlighted, visible option.
+     * No-ops if nothing is highlighted or the item is hidden.
      */
     selectHighlighted() {
         if (this.currentHighlightIndex > -1 && this.flatOptions[this.currentHighlightIndex]) {
@@ -4521,11 +5673,11 @@ class MixedAdapter extends Adapter {
         }
     }
     /**
-     * Highlights a target option by flat index or model instance, skipping invisible items,
-     * and optionally scrolls the highlighted element into view.
+     * Highlights a target option (by flat index or model reference),
+     * skipping invisible items and optionally scrolling into view.
      *
-     * @param {number|OptionModel} target - Flat index or the specific OptionModel to highlight.
-     * @param {boolean} [isScrollToView=true] - Whether to scroll the highlighted item into view.
+     * @param target - Flat index or OptionModel instance to highlight.
+     * @param isScrollToView - Whether to scroll the highlighted item into view. Defaults to `true`.
      */
     setHighlight(target, isScrollToView = true) {
         let index = 0;
@@ -4554,6 +5706,7 @@ class MixedAdapter extends Adapter {
                     el.scrollIntoView({ block: 'center', behavior: 'smooth' });
                 }
                 else {
+                    // If virtualized, ensure the item is rendered before trying to scroll.
                     this.recyclerView?.ensureRendered?.(i, { scrollIntoView: true });
                 }
             }
@@ -4562,66 +5715,134 @@ class MixedAdapter extends Adapter {
         }
     }
     /**
-     * Hook invoked whenever the highlight changes.
+     * Hook invoked whenever the highlighted item changes.
      * Override to handle UI side effects (e.g., ARIA announcement, focus sync).
+     *
+     * @param index - Flat index of the newly highlighted item.
+     * @param id - Optional DOM id of the highlighted view element.
      */
     onHighlightChange(index, id) { }
     /**
-     * Hook invoked when a group's collapsed state changes.
-     * Override to handle side effects like analytics or layout adjustments.
+     * Hook invoked whenever a group's collapsed state changes.
+     * Override to handle side effects (e.g., analytics, layout adjustments).
+     *
+     * @param model - The group whose collapsed state changed.
+     * @param collapsed - New collapsed state.
      */
     onCollapsedChange(model, collapsed) { }
 }
 
 /**
- * Fenwick tree (Binary Indexed Tree) for efficient prefix sum queries.
- * Supports O(log n) update and query operations for cumulative item heights.
- * Uses 1-based indexing internally for BIT operations.
+ * Fenwick tree (Binary Indexed Tree) for efficient prefix-sum queries.
+ *
+ * - Internally uses **1-based indexing** for all BIT operations.
+ * - Supports **O(log n)** updates and prefix/range queries.
+ * - Useful for cumulative height calculations in virtualized lists.
+ *
+ * @extends Lifecycle
  */
-class Fenwick {
-    constructor(n = 0) {
+class Fenwick extends Lifecycle {
+    /**
+     * Creates a Fenwick tree and initializes it with the provided size (optional).
+     *
+     * @param stackNum - Initial number of elements (all values start at 0). Defaults to 0.
+     */
+    constructor(stackNum = 0) {
+        super();
+        /** Internal BIT array. Index 0 is unused; valid range: [1..stackNum]. */
         this.bit = [];
-        this.n = 0;
-        this.reset(n);
+        /** Number of elements managed by the tree (logical size). */
+        this.stackNum = 0;
+        this.initialize(stackNum);
+    }
+    /**
+     * Initializes lifecycle and resets the tree to the given size.
+     *
+     * @param stackNum - Number of elements to allocate (values cleared to 0).
+     */
+    initialize(stackNum) {
+        this.init();
+        this.reset(stackNum);
     }
-    /** Resets tree to new size, clearing all values. */
-    reset(n) {
-        this.n = n;
-        this.bit = new Array(n + 1).fill(0);
+    /**
+     * Resets the tree to a new size and clears all values to 0.
+     *
+     * @param stackNum - New number of elements (valid 1-based indexes: 1..stackNum).
+     */
+    reset(stackNum) {
+        this.stackNum = stackNum;
+        this.bit = new Array(stackNum + 1).fill(0);
     }
-    /** Adds delta to element at 1-based index i. */
+    /**
+     * Adds `delta` to the element at **1-based** index `i`.
+     *
+     * Complexity: **O(log n)**
+     *
+     * @param i - 1-based index of the element to update (1..stackNum).
+     * @param delta - Value to add (can be negative).
+     */
     add(i, delta) {
-        for (let x = i; x <= this.n; x += x & -x)
+        for (let x = i; x <= this.stackNum; x += x & -x)
             this.bit[x] += delta;
     }
-    /** Returns prefix sum for range [1..i]. */
+    /**
+     * Returns the prefix sum for the range **[1..i]** (inclusive).
+     *
+     * Complexity: **O(log n)**
+     *
+     * @param i - 1-based index up to which the sum is calculated.
+     * @returns The cumulative sum from 1 to i.
+     */
     sum(i) {
         let s = 0;
         for (let x = i; x > 0; x -= x & -x)
             s += this.bit[x];
         return s;
     }
-    /** Returns sum in range [l..r] (1-based, inclusive). */
+    /**
+     * Returns the sum in the range **[l..r]** (1-based, inclusive).
+     *
+     * Complexity: **O(log n)**
+     *
+     * @param l - Left index (inclusive).
+     * @param r - Right index (inclusive).
+     * @returns The sum in [l..r], or 0 if r < l.
+     */
     rangeSum(l, r) {
         return r < l ? 0 : this.sum(r) - this.sum(l - 1);
     }
-    /** Builds tree from 0-based array in O(n log n). */
+    /**
+     * Builds the tree from a **0-based** array in **O(n log n)**.
+     *
+     * Each element `arr[i]` is added to index `i + 1`.
+     *
+     * @param arr - Source values (0-based).
+     */
     buildFrom(arr) {
         this.reset(arr.length);
         arr.forEach((val, i) => this.add(i + 1, val));
     }
     /**
-     * Binary search to find largest index where prefix sum <= target.
-     * Returns count of items that fit within target height.
+     * Finds the largest index `idx` such that `prefixSum(idx) <= target`.
+     *
+     * This is a classic Fenwick-tree lower-bound over prefix sums.
+     * It effectively returns the **count of items** that fit within the target
+     * cumulative value (e.g., number of items whose total height <= target).
+     *
+     * Complexity: **O(log n)**
+     *
+     * @param target - Target prefix sum.
+     * @returns The largest index satisfying the condition (in range 0..stackNum).
+     *          Returns 0 if the first element already exceeds `target`.
      */
     lowerBoundPrefix(target) {
         let idx = 0, bitMask = 1;
-        while (bitMask << 1 <= this.n)
+        while (bitMask << 1 <= this.stackNum)
             bitMask <<= 1;
         let cur = 0;
         for (let step = bitMask; step !== 0; step >>= 1) {
             const next = idx + step;
-            if (next <= this.n && cur + this.bit[next] <= target) {
+            if (next <= this.stackNum && cur + this.bit[next] <= target) {
                 idx = next;
                 cur += this.bit[next];
             }
@@ -4630,19 +5851,38 @@ class Fenwick {
     }
 }
 /**
- * Virtual RecyclerView with efficient windowing and dynamic height support.
+ * Virtual RecyclerView with efficient windowing and dynamic-height support.
  *
- * Only renders items visible in viewport plus overscan buffer, using padding
- * elements to simulate scroll height. Supports variable item heights with
- * adaptive estimation and maintains scroll position during height changes.
+ * Only renders items visible in the viewport plus an overscan buffer, using
+ * top/bottom padding elements to simulate full scroll height. Supports variable
+ * item heights with **adaptive estimation** and maintains scroll position during
+ * height changes using an **anchor item** technique.
  *
- * @template TItem - Model type for list items
- * @template TAdapter - Adapter managing item views
+ * Key features:
+ * - Virtual windowing with configurable `overscan`
+ * - Dynamic heights with `ResizeObserver`-based measurement
+ * - Adaptive height estimation (average of measured items)
+ * - Efficient prefix sums via Fenwick tree (1-based) for O(log n) math
+ * - Stable scroll position during re-measure via anchor correction
+ *
+ * @template TItem - Model type for list items.
+ * @template TAdapter - Adapter managing item views.
+ *
+ * @extends RecyclerView
  */
 class VirtualRecyclerView extends RecyclerView {
-    /** Creates virtual recycler view with optional root element. */
+    /** Creates a virtual recycler view with an optional root element. */
     constructor(viewElement = null) {
         super(viewElement);
+        /**
+         * Virtualization settings.
+         *
+         * - `scrollEl`           : External scroll container (if omitted, inferred from DOM)
+         * - `estimateItemHeight` : Initial/fallback item height in pixels
+         * - `overscan`           : Extra viewport height (in item multiples) rendered above/below
+         * - `dynamicHeights`     : Enable measuring items with ResizeObserver
+         * - `adaptiveEstimate`   : Use average of measured items as the running estimate
+         */
         this.opts = {
             scrollEl: undefined,
             estimateItemHeight: 36,
@@ -4650,31 +5890,54 @@ class VirtualRecyclerView extends RecyclerView {
             dynamicHeights: true,
             adaptiveEstimate: true,
         };
+        /** Cache of measured heights per item index (undefined when not measured). */
         this.heightCache = [];
+        /** Fenwick tree storing current height values (0 for invisible items). */
         this.fenwick = new Fenwick(0);
+        /** Map of currently created (mounted) DOM elements keyed by item index. */
         this.created = new Map();
+        /** Whether an initial height probe has been performed. */
         this.firstMeasured = false;
+        /** Current window bounds (inclusive) in flat item-space. */
         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. */
         this.updating = false;
         this.suppressResize = false;
         this.lastRenderCount = 0;
         this.suspended = false;
         this.resumeResizeAfter = false;
+        /** Small cache for sticky header height (16ms TTL). */
         this.stickyCacheTick = 0;
         this.stickyCacheVal = 0;
+        /** Stats for adaptive estimator. */
         this.measuredSum = 0;
         this.measuredCount = 0;
     }
-    /** Updates virtualization settings (overscan, heights, etc). */
+    /**
+     * Updates virtualization settings (overscan, estimates, dynamic heights, etc.).
+     *
+     * @param opts - Partial configuration to merge with current options.
+     */
     configure(opts) {
         this.opts = { ...this.opts, ...opts };
     }
     /**
-     * Binds adapter and initializes virtualization scaffold.
-     * Removes previous adapter if exists, sets up scroll listeners and DOM structure.
+     * Binds an adapter and initializes the virtualization scaffold.
+     *
+     * Flow:
+     * 1) Dispose previous adapter/listeners if any
+     * 2) Call `super.setAdapter(adapter)` to wire lifecycle
+     * 3) Build the pad elements (top, host, bottom)
+     * 4) Resolve `scrollEl` (from config or DOM)
+     * 5) Attach scroll listener, refresh and attach resize observer
+     * 6) Subscribe to adapter visibility changes to force a refresh
+     *
+     * @param adapter - The adapter managing models and item views.
      */
     setAdapter(adapter) {
         if (this.adapter)
@@ -4720,7 +5983,7 @@ class VirtualRecyclerView extends RecyclerView {
     }
     /**
      * Resumes scroll/resize processing after suspension.
-     * Re-attaches listeners and schedules window update.
+     * Re-attaches listeners and schedules a window update.
      */
     resume() {
         this.suspended = false;
@@ -4734,10 +5997,10 @@ class VirtualRecyclerView extends RecyclerView {
         this.scheduleUpdateWindow();
     }
     /**
-     * Rebuilds internal state and schedules render update.
-     * Probes initial item height on first run, rebuilds Fenwick tree.
+     * Rebuilds internal state and schedules a render update.
+     * Probes initial item height on first run and rebuilds the Fenwick tree.
      *
-     * @param isUpdate - True if called from data update, false on initial setup
+     * @param isUpdate - True if called from a data update; false on initial setup.
      */
     refresh(isUpdate) {
         if (!this.adapter || !this.viewElement)
@@ -4748,6 +6011,7 @@ class VirtualRecyclerView extends RecyclerView {
         this.lastRenderCount = count;
         if (count === 0) {
             this.resetState();
+            this.update();
             return;
         }
         this.heightCache.length = count;
@@ -4757,10 +6021,13 @@ class VirtualRecyclerView extends RecyclerView {
         }
         this.rebuildFenwick(count);
         this.scheduleUpdateWindow();
+        this.update();
     }
     /**
-     * Ensures item at index is rendered and optionally scrolls into view.
-     * Useful for programmatic navigation to specific items.
+     * Ensures the item at `index` is rendered and optionally scrolls it into view.
+     *
+     * @param index - Item index to ensure visible/mounted.
+     * @param opt - Optional behavior: `{ scrollIntoView?: boolean }`.
      */
     ensureRendered(index, opt) {
         this.mountRange(index, index);
@@ -4768,8 +6035,10 @@ class VirtualRecyclerView extends RecyclerView {
             this.scrollToIndex(index);
     }
     /**
-     * Scrolls container to make item at index visible.
+     * Scrolls the container to make the item at `index` visible.
      * Calculates target scroll position accounting for container offset.
+     *
+     * @param index - Item index to bring into view.
      */
     scrollToIndex(index) {
         const count = this.adapter?.itemCount?.() ?? 0;
@@ -4782,8 +6051,8 @@ class VirtualRecyclerView extends RecyclerView {
         this.scrollEl.scrollTop = Math.min(Math.max(0, target), maxScroll);
     }
     /**
-     * Cleans up all resources: listeners, observers, DOM elements.
-     * Call before removing component to prevent memory leaks.
+     * Cleans up all resources: listeners, observers, and DOM elements.
+     * Call before removing the component to prevent memory leaks.
      */
     dispose() {
         this.cancelFrames();
@@ -4795,9 +6064,31 @@ class VirtualRecyclerView extends RecyclerView {
         this.created.clear();
     }
     /**
-     * Hard reset after visibility changes (e.g., search/filter cleared).
-     * Rebuilds all height structures and remounts visible window.
-     * Essential for fixing padding calculations after bulk visibility changes.
+     * Destroys the virtual recycler view and releases resources.
+     *
+     * - Resets internal state and disposes observers/listeners
+     * - Removes scaffold elements (PadTop, ItemsHost, PadBottom)
+     * - Ends the lifecycle
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        this.resetState();
+        this.dispose();
+        this.PadTop.remove();
+        this.ItemsHost.remove();
+        this.PadBottom.remove();
+        this.PadTop = null;
+        this.ItemsHost = null;
+        this.PadBottom = null;
+        super.destroy();
+    }
+    /**
+     * Hard reset after large visibility changes (e.g., search/filter cleared).
+     *
+     * Rebuilds all height structures and remounts the visible window.
+     * Essential for fixing padding calculations after bulk visibility updates.
      */
     refreshItem() {
         if (!this.adapter)
@@ -4825,7 +6116,7 @@ class VirtualRecyclerView extends RecyclerView {
             this.measureRaf = null;
         }
     }
-    /** Resets all internal state: DOM, caches, measurements. */
+    /** Resets all internal state: DOM, caches, and measurements. */
     resetState() {
         this.created.forEach(el => el.remove());
         this.created.clear();
@@ -4838,8 +6129,8 @@ class VirtualRecyclerView extends RecyclerView {
         this.measuredCount = 0;
     }
     /**
-     * Measures first item to set initial height estimate.
-     * Removes probe element if dynamic heights disabled.
+     * Measures the first item to set an initial height estimate.
+     * If dynamic heights are disabled, removes the probe element afterward.
      */
     probeInitialHeight() {
         const probe = 0;
@@ -4861,16 +6152,16 @@ class VirtualRecyclerView extends RecyclerView {
         }
     }
     /**
-     * Checks if item is visible (not filtered/hidden).
-     * Defaults to visible if property undefined.
+     * Whether item at `index` is visible (not filtered/hidden).
+     * Defaults to visible when the property is undefined.
      */
     isIndexVisible(index) {
         const item = this.adapter?.items?.[index];
         return item?.visible ?? true;
     }
     /**
-     * Finds next visible item index starting from given index.
-     * Returns -1 if no visible items found.
+     * Finds the next visible item index starting from `index`.
+     * Returns -1 if no visible items are found.
      */
     nextVisibleFrom(index, count) {
         for (let i = Math.max(0, index); i < count; i++) {
@@ -4881,7 +6172,7 @@ class VirtualRecyclerView extends RecyclerView {
     }
     /**
      * Recalculates total measured height and count from cache.
-     * Only counts visible items for adaptive estimation.
+     * Only counts **visible** items for adaptive estimation.
      */
     recomputeMeasuredStats(count) {
         this.measuredSum = 0;
@@ -4896,15 +6187,15 @@ class VirtualRecyclerView extends RecyclerView {
             }
         }
     }
-    /** Returns view container's top offset relative to scroll container. */
+    /** Returns view container's top offset relative to the scroll container. */
     containerTopInScroll() {
         const a = this.viewElement.getBoundingClientRect();
         const b = this.scrollEl.getBoundingClientRect();
         return Math.max(0, a.top - b.top + this.scrollEl.scrollTop);
     }
     /**
-     * Returns sticky header height with 16ms cache to avoid DOM thrashing.
-     * Used to adjust viewport calculations.
+     * Returns sticky header height with ~16ms cache to avoid layout thrashing.
+     * Used to adjust effective viewport height.
      */
     stickyTopHeight() {
         const now = performance.now();
@@ -4915,7 +6206,7 @@ class VirtualRecyclerView extends RecyclerView {
         this.stickyCacheTick = now;
         return this.stickyCacheVal;
     }
-    /** Schedules window update on next frame if not already scheduled. */
+    /** Schedules a window update on the next frame if not already scheduled. */
     scheduleUpdateWindow() {
         if (this.rafId != null || this.suspended)
             return;
@@ -4925,8 +6216,10 @@ class VirtualRecyclerView extends RecyclerView {
         });
     }
     /**
-     * Measures element's total height including margins.
-     * Used for accurate item height tracking.
+     * Measures an element's total height including vertical margins.
+     *
+     * @param el - Element to measure.
+     * @returns Total outer height in pixels.
      */
     measureOuterHeight(el) {
         const rect = el.getBoundingClientRect();
@@ -4937,7 +6230,7 @@ class VirtualRecyclerView extends RecyclerView {
     }
     /**
      * Returns height estimate for unmeasured items.
-     * Uses adaptive average if enabled, otherwise fixed estimate.
+     * Uses adaptive average if enabled, otherwise the fixed estimate.
      */
     getEstimate() {
         if (this.opts.adaptiveEstimate && this.measuredCount > 0) {
@@ -4946,8 +6239,10 @@ class VirtualRecyclerView extends RecyclerView {
         return this.opts.estimateItemHeight;
     }
     /**
-     * Rebuilds Fenwick tree with current heights and estimates.
-     * Invisible items get 0 height, others use cached or estimated height.
+     * Rebuilds the Fenwick tree with current heights and estimates.
+     * Invisible items receive height 0; others use cached or estimated height.
+     *
+     * @param count - Total number of items.
      */
     rebuildFenwick(count) {
         const est = this.getEstimate();
@@ -4955,10 +6250,12 @@ class VirtualRecyclerView extends RecyclerView {
         this.fenwick.buildFrom(arr);
     }
     /**
-     * Updates cached height at index and applies delta to Fenwick tree.
-     * Updates running average for adaptive estimation.
+     * Updates cached height at `index` and applies delta to the Fenwick tree.
+     * Also updates running average for the adaptive estimator.
      *
-     * @returns True if height changed beyond epsilon threshold
+     * @param index - Item index to update.
+     * @param newH - Newly measured outer height (px).
+     * @returns True if the height changed beyond the epsilon threshold.
      */
     updateHeightAt(index, newH) {
         if (!this.isIndexVisible(index))
@@ -4980,8 +6277,11 @@ class VirtualRecyclerView extends RecyclerView {
         return true;
     }
     /**
-     * Finds first visible item at or after scroll offset.
-     * Uses Fenwick binary search then adjusts for visibility.
+     * Finds the first visible item at or after a scroll-relative offset.
+     * Uses Fenwick lower-bound then adjusts forward to the next visible item.
+     *
+     * @param stRel - ScrollTop relative to the view container (px).
+     * @param count - Total item count.
      */
     findFirstVisibleIndex(stRel, count) {
         const k = this.fenwick.lowerBoundPrefix(Math.max(0, stRel));
@@ -4990,8 +6290,11 @@ class VirtualRecyclerView extends RecyclerView {
         return v === -1 ? Math.max(0, raw) : v;
     }
     /**
-     * Inserts element into DOM maintaining index order.
-     * Tries adjacent siblings first, then scans for insertion point.
+     * Inserts an element into the host maintaining increasing index order.
+     * Tries adjacent siblings first, then scans for the insertion point.
+     *
+     * @param index - Item index.
+     * @param el - Element to insert.
      */
     insertIntoHostByIndex(index, el) {
         el.setAttribute(VirtualRecyclerView.ATTR_INDEX, String(index));
@@ -5016,8 +6319,11 @@ class VirtualRecyclerView extends RecyclerView {
         this.ItemsHost.appendChild(el);
     }
     /**
-     * Ensures element is in correct DOM position for its index.
-     * Reinserts if siblings indicate wrong position.
+     * Ensures the element is in the correct DOM position for its index.
+     * Reinserts when adjacent siblings indicate an out-of-order position.
+     *
+     * @param index - Item index.
+     * @param el - Element to validate/reinsert.
      */
     ensureDomOrder(index, el) {
         if (el.parentElement !== this.ItemsHost) {
@@ -5035,8 +6341,8 @@ class VirtualRecyclerView extends RecyclerView {
         }
     }
     /**
-     * Attaches ResizeObserver to measure items when they resize.
-     * Singleton pattern - only creates once per instance.
+     * Attaches a ResizeObserver to measure items when they resize.
+     * Singleton pattern — only creates once per instance.
      */
     attachResizeObserverOnce() {
         if (this.resizeObs)
@@ -5052,8 +6358,8 @@ class VirtualRecyclerView extends RecyclerView {
         this.resizeObs.observe(this.ItemsHost);
     }
     /**
-     * Measures all currently rendered items and updates height cache.
-     * Triggers window update if any heights changed.
+     * Measures all currently rendered items and updates the height cache.
+     * Triggers a window update when any heights changed.
      */
     measureVisibleAndUpdate() {
         if (!this.adapter)
@@ -5079,20 +6385,21 @@ class VirtualRecyclerView extends RecyclerView {
             this.scheduleUpdateWindow();
         }
     }
-    /** Scroll event handler - schedules render update. */
+    /** Scroll event handler — schedules a render update. */
     onScroll() {
         this.scheduleUpdateWindow();
     }
     /**
-     * Core rendering logic - calculates and updates visible window.
+     * Core rendering logic — calculates and updates the visible window.
      *
-     * 1. Calculates viewport bounds accounting for scroll and sticky headers
-     * 2. Uses anchor item to prevent scroll jumping during height changes
-     * 3. Determines start/end indices with overscan buffer
-     * 4. Mounts/unmounts items as needed
-     * 5. Measures visible items if dynamic heights enabled
-     * 6. Updates padding elements to maintain total scroll height
-     * 7. Adjusts scroll position to maintain anchor item position
+     * Steps:
+     * 1) Calculate viewport bounds (account for sticky headers)
+     * 2) Use an anchor item to prevent scroll jumping on height changes
+     * 3) Determine start/end indices with overscan buffer
+     * 4) Mount/unmount items as needed
+     * 5) Measure visible items (if dynamic heights enabled)
+     * 6) Update pad heights (top/bottom) to maintain total scroll span
+     * 7) Adjust scroll position to keep the anchor item stable
      */
     updateWindowInternal() {
         if (this.updating || this.suspended)
@@ -5104,6 +6411,7 @@ class VirtualRecyclerView extends RecyclerView {
             const count = this.adapter.itemCount();
             if (count <= 0)
                 return;
+            // Handle item count changes (e.g., add/remove)
             if (this.lastRenderCount !== count) {
                 this.lastRenderCount = count;
                 this.heightCache.length = count;
@@ -5145,6 +6453,7 @@ class VirtualRecyclerView extends RecyclerView {
             finally {
                 this.suppressResize = false;
             }
+            // Keep anchor item stable to prevent scroll jump
             const anchorTopNew = this.offsetTopOf(anchorIndex);
             const targetScroll = this.containerTopInScroll() + anchorTopNew - anchorDelta;
             const maxScroll = Math.max(0, this.scrollEl.scrollHeight - this.scrollEl.clientHeight);
@@ -5159,14 +6468,16 @@ class VirtualRecyclerView extends RecyclerView {
             this.updating = false;
         }
     }
-    /** Mounts all items in inclusive range [start..end]. */
+    /** Mounts all items in the inclusive range `[start..end]`. */
     mountRange(start, end) {
         for (let i = start; i <= end; i++)
             this.mountIndexOnce(i);
     }
     /**
-     * Mounts single item, reusing existing element if available.
-     * Creates view holder on first mount, rebinds on subsequent renders.
+     * Mounts a single item, reusing an existing element if available.
+     * Creates the view holder on first mount, or rebinds on subsequent renders.
+     *
+     * @param index - Item index to mount/rebind.
      */
     mountIndexOnce(index) {
         if (!this.isIndexVisible(index)) {
@@ -5206,7 +6517,9 @@ class VirtualRecyclerView extends RecyclerView {
             this.created.set(index, el);
         }
     }
-    /** Removes all mounted items outside [start..end] range. */
+    /**
+     * Removes all mounted items outside the inclusive range `[start..end]`.
+     */
     unmountOutside(start, end) {
         this.created.forEach((el, idx) => {
             if (idx < start || idx > end) {
@@ -5216,7 +6529,9 @@ class VirtualRecyclerView extends RecyclerView {
             }
         });
     }
-    /** Removes all items marked as invisible from DOM. */
+    /**
+     * Removes all items currently marked as invisible from the DOM.
+     */
     cleanupInvisibleItems() {
         this.created.forEach((el, idx) => {
             if (!this.isIndexVisible(idx)) {
@@ -5226,26 +6541,44 @@ class VirtualRecyclerView extends RecyclerView {
             }
         });
     }
-    /** Returns cumulative height from start to top of item at index. */
+    /**
+     * Returns cumulative height from the start to the **top** of item at `index`.
+     *
+     * Internally uses Fenwick sum on the **inclusive** range [1..index],
+     * which corresponds to offset-top in 0-based item space.
+     *
+     * @param index - Item index (0-based).
+     */
     offsetTopOf(index) {
         return this.fenwick.sum(index);
     }
-    /** Returns total height of items in range [start..end]. */
+    /**
+     * Returns the total height of items in inclusive range `[start..end]`.
+     *
+     * @param start - Start index (0-based).
+     * @param end - End index (0-based).
+     */
     windowHeight(start, end) {
         return this.fenwick.rangeSum(start + 1, end + 1);
     }
-    /** Returns total scrollable height for all items. */
+    /**
+     * Returns the total scrollable height for all items.
+     *
+     * @param count - Total item count.
+     */
     totalHeight(count) {
         return this.fenwick.sum(count);
     }
 }
+/** Epsilon threshold for height-change significance. */
 VirtualRecyclerView.EPS = 0.5;
+/** Attribute stored on each element indicating its item index. */
 VirtualRecyclerView.ATTR_INDEX = "data-vindex";
 
 /**
  * @class
  */
-class SelectBox {
+class SelectBox extends Lifecycle {
     /**
      * Initializes a SelectBox instance and, if a source <select> and Selective context are provided,
      * immediately calls init() to set up the enhanced UI and behavior.
@@ -5254,6 +6587,7 @@ class SelectBox {
      * @param {any|null} [Selective=null] - The Selective framework/context used for configuration and services.
      */
     constructor(select = null, Selective = null) {
+        super();
         this.container = {};
         this.oldValue = null;
         this.node = null;
@@ -5264,8 +6598,8 @@ class SelectBox {
         this.isBeforeSearch = false;
         /** Selective context (global helper) */
         this.Selective = null;
-        if (select)
-            this.init(select, Selective);
+        if (select && Selective)
+            this.initialize(select, Selective);
     }
     /**
      * Gets or sets the disabled state of the SelectBox.
@@ -5309,14 +6643,24 @@ class SelectBox {
         this.node.classList.toggle("invisible", !value);
     }
     /**
-     * Initializes the SelectBox UI and behavior by wiring core components.
-     *
-     * @param {HTMLSelectElement} select - The native <select> element to enhance.
-     * @param {any} Selective - The Selective framework/context for services and configuration.
+     * Wrapper method to initialize with select element
      */
-    init(select, Selective) {
+    initialize(select, Selective) {
         const bindedMap = Libs.getBinderMap(select);
-        const options = bindedMap.options;
+        this.options = bindedMap.options;
+        this.Selective = Selective;
+        this.init(select);
+    }
+    /**
+     * Override lifecycle init - Creates all components and DOM structure
+     */
+    init(select) {
+        if (this.state !== LifecycleState.NEW)
+            return;
+        if (!select || !this.options)
+            return;
+        const options = this.options;
+        // Create all components
         const placeholder = new PlaceHolder(options);
         const directive = new Directive();
         const searchbox = new SearchBox(options);
@@ -5326,11 +6670,9 @@ class SelectBox {
         const searchController = new SearchController(select, optionModelManager, this);
         const selectObserver = new SelectObserver(select);
         const datasetObserver = new DatasetObserver(select);
-        this.Selective = Selective;
-        this.options = options;
         // ensure placeholder has id for aria-labelledby usage
         if (placeholder.node)
-            placeholder.node.id = String((options).SEID_HOLDER ?? "");
+            placeholder.node.id = String(options.SEID_HOLDER ?? "");
         const container = Libs.mountNode({
             Container: {
                 tag: { node: "div", classList: "selective-ui-MAIN" },
@@ -5358,17 +6700,16 @@ class SelectBox {
         }, null);
         this.container = container;
         this.node = container.view;
-        // Mount into DOM: wrapper before select, then move select inside
-        select.parentNode?.insertBefore(this.node, select);
-        this.node.insertBefore(select, container.tags.ViewPanel);
-        accessoryBox.setRoot(container.tags.ViewPanel);
-        accessoryBox.setModelManager(optionModelManager);
-        container.tags.ViewPanel.addEventListener("mousedown", (e) => {
-            e.stopPropagation();
-            e.preventDefault();
-        });
-        Refresher.resizeBox(select, container.tags.ViewPanel);
-        select.classList.add("init");
+        // Store references on container
+        container.searchController = searchController;
+        container.placeholder = placeholder;
+        container.directive = directive;
+        container.searchbox = searchbox;
+        container.effector = effector;
+        container.targetElement = select;
+        container.accessorybox = accessoryBox;
+        container.selectObserver = selectObserver;
+        container.datasetObserver = datasetObserver;
         // ModelManager setup
         optionModelManager.setupAdapter(MixedAdapter);
         if (options.virtualScroll) {
@@ -5382,16 +6723,6 @@ class SelectBox {
             container.popup?.triggerResize?.();
         };
         this.optionModelManager = optionModelManager;
-        // Store references on container
-        container.searchController = searchController;
-        container.placeholder = placeholder;
-        container.directive = directive;
-        container.searchbox = searchbox;
-        container.effector = effector;
-        container.targetElement = select;
-        container.accessorybox = accessoryBox;
-        container.selectObserver = selectObserver;
-        container.datasetObserver = datasetObserver;
         // Popup
         container.popup = new Popup(select, options, optionModelManager);
         container.popup.setupEffector(effector);
@@ -5405,30 +6736,54 @@ class SelectBox {
         container.popup.onAdapterPropChanging("select", () => {
             this.oldValue = this.getAction()?.value ?? "";
         });
+        accessoryBox.setRoot(container.tags.ViewPanel);
+        accessoryBox.setModelManager(optionModelManager);
+        this.setupEventHandlers(select, container, options, searchController, searchbox);
+        this.setupObservers(selectObserver, datasetObserver, select, optionModelManager);
+        // Initial states
+        this.isDisabled = Libs.string2Boolean(options.disabled);
+        this.isReadOnly = Libs.string2Boolean(options.readonly);
+        // Call parent lifecycle init
+        super.init();
+    }
+    /**
+     * Override lifecycle mount - Mounts component into DOM
+     */
+    mount() {
+        if (this.state !== LifecycleState.INITIALIZED)
+            return;
+        if (!this.node || !this.container.targetElement)
+            return;
+        const select = this.container.targetElement;
+        const container = this.container;
+        // Mount into DOM: wrapper before select, then move select inside
+        select.parentNode?.insertBefore(this.node, select);
+        this.node.insertBefore(select, container.tags.ViewPanel);
+        container.tags.ViewPanel.addEventListener("mousedown", (e) => {
+            e.stopPropagation();
+            e.preventDefault();
+        });
+        Refresher.resizeBox(select, container.tags.ViewPanel);
+        select.classList.add("init");
         // initial mask
         this.getAction()?.change(null, false);
-        // Observers
-        selectObserver.connect();
-        selectObserver.onChanged = (sel) => {
-            optionModelManager.update(Libs.parseSelectToArray(sel));
-            this.getAction()?.refreshMask();
-        };
-        datasetObserver.connect();
-        datasetObserver.onChanged = (dataset) => {
-            if (Libs.string2Boolean(dataset.disabled) !== this.isDisabled) {
-                this.isDisabled = Libs.string2Boolean(dataset.disabled);
-            }
-            if (Libs.string2Boolean(dataset.readonly) !== this.isReadOnly) {
-                this.isReadOnly = Libs.string2Boolean(dataset.readonly);
-            }
-            if (Libs.string2Boolean(dataset.visible) !== this.isVisible) {
-                this.isVisible = Libs.string2Boolean(dataset.visible ?? "1");
-            }
-        };
-        // AJAX setup (if provided)
-        if (options.ajax) {
-            searchController.setAjax(options.ajax);
-        }
+        // Call parent lifecycle mount
+        super.mount();
+    }
+    /**
+     * Override lifecycle update - Called when data/state changes
+     */
+    update() {
+        if (this.state !== LifecycleState.MOUNTED)
+            return;
+        // Trigger any update logic here
+        this.container.popup?.triggerResize?.();
+        super.update();
+    }
+    /**
+     * Setup event handlers (extracted from init for clarity)
+     */
+    setupEventHandlers(select, container, options, searchController, searchbox) {
         const optionAdapter = container.popup.optionAdapter;
         let hightlightTimer = null;
         const searchHandle = (keyword, isTrigger) => {
@@ -5494,9 +6849,32 @@ class SelectBox {
         optionAdapter.onCollapsedChange = () => {
             container.popup?.triggerResize?.();
         };
-        // Initial states
-        this.isDisabled = Libs.string2Boolean(options.disabled);
-        this.isReadOnly = Libs.string2Boolean(options.readonly);
+        // AJAX setup (if provided)
+        if (options.ajax) {
+            searchController.setAjax(options.ajax);
+        }
+    }
+    /**
+     * Setup observers (extracted from init for clarity)
+     */
+    setupObservers(selectObserver, datasetObserver, select, optionModelManager) {
+        selectObserver.connect();
+        selectObserver.onChanged = (sel) => {
+            optionModelManager.update(Libs.parseSelectToArray(sel));
+            this.getAction()?.refreshMask();
+        };
+        datasetObserver.connect();
+        datasetObserver.onChanged = (dataset) => {
+            if (Libs.string2Boolean(dataset.disabled) !== this.isDisabled) {
+                this.isDisabled = Libs.string2Boolean(dataset.disabled);
+            }
+            if (Libs.string2Boolean(dataset.readonly) !== this.isReadOnly) {
+                this.isReadOnly = Libs.string2Boolean(dataset.readonly);
+            }
+            if (Libs.string2Boolean(dataset.visible) !== this.isVisible) {
+                this.isVisible = Libs.string2Boolean(dataset.visible ?? "1");
+            }
+        };
     }
     /**
      * Disconnects observers associated with the SelectBox instance.
@@ -5509,6 +6887,38 @@ class SelectBox {
         if (datasetObserver?.disconnect)
             datasetObserver.disconnect();
     }
+    /**
+     * Override lifecycle destroy - Complete cleanup
+     */
+    destroy() {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        // Disconnect observers
+        this.deInit();
+        // Destroy child components
+        const container = this.container;
+        container.searchController.destroy();
+        container.directive.destroy();
+        container.popup.destroy();
+        container.accessorybox.destroy();
+        container.placeholder.destroy();
+        container.searchbox.destroy();
+        // Remove from DOM
+        this.node?.remove();
+        // Clear all references
+        this.container = {};
+        this.node = null;
+        this.options = null;
+        this.optionModelManager = null;
+        this.Selective = null;
+        this.oldValue = null;
+        this.isOpen = false;
+        this.hasLoadedOnce = false;
+        this.isBeforeSearch = false;
+        // Call parent lifecycle destroy
+        super.destroy();
+    }
     /**
      * Returns an action API for controlling the SelectBox instance.
      */
@@ -5587,7 +6997,7 @@ class SelectBox {
             },
             valueDataset(_evtToken, strDataset = null, isArray = false) {
                 var item_list = [];
-                superThis.getModelOption(true).forEach(m => {
+                superThis.getModelOption(true).forEach((m) => {
                     item_list.push(strDataset ? m.dataset[strDataset] : m.dataset);
                 });
                 if (!isArray) {
@@ -5801,6 +7211,10 @@ class SelectBox {
                     if (superThis.options?.autoclose)
                         this.close();
                 }
+                // Trigger update lifecycle
+                if (superThis.is(LifecycleState.MOUNTED)) {
+                    superThis.update();
+                }
             },
             refreshMask() {
                 let mask = bindedOptions.placeholder;
@@ -5841,7 +7255,7 @@ class SelectBox {
                         });
                     }
                 });
-            }
+            },
         };
         // mirror properties: disabled / readonly / visible
         this.createSymProp(resp, "disabled", "isDisabled");
@@ -5890,9 +7304,6 @@ class SelectBox {
         }
         return flatOptions;
     }
-    detroy() {
-        this.container.popup.detroy();
-    }
 }
 
 /**
@@ -5919,12 +7330,12 @@ class ElementAdditionObserver {
         this.actions = [];
     }
     /**
-     * Starts observing the document for additions of elements matching the given tag.
+     * connect observing the document for additions of elements matching the given tag.
      * Detects both direct additions and nested matches within added subtrees.
      *
      * @param {string} tag - The tag name to watch for (e.g., "select", "div").
      */
-    start(tag) {
+    connect(tag) {
         if (this.isActive)
             return;
         this.isActive = true;
@@ -5953,7 +7364,7 @@ class ElementAdditionObserver {
      * Stops observing for element additions and releases internal resources.
      * No-ops if the observer is not active.
      */
-    stop() {
+    disconnect() {
         if (!this.isActive)
             return;
         this.isActive = false;
@@ -5970,9 +7381,21 @@ class ElementAdditionObserver {
     }
 }
 
-class Selective {
+class Selective extends Lifecycle {
     constructor() {
+        super();
+        this.bindedQueries = new Map();
+        this.init();
+    }
+    /**
+     * Override lifecycle init - Initialize Selective system
+     */
+    init() {
+        if (!this.is(LifecycleState.NEW))
+            return;
+        // Initialize core properties
         this.bindedQueries = new Map();
+        super.init();
     }
     /**
      * Binds Selective UI to all <select> elements matching the query.
@@ -5983,6 +7406,10 @@ class Selective {
      * @param {object} options - Configuration overrides merged with defaults.
      */
     bind(query, options) {
+        // Auto-init if not initialized
+        if (this.is(LifecycleState.NEW)) {
+            this.init();
+        }
         const merged = Libs.mergeConfig(Libs.getDefaultConfig(), options);
         // Ensure hooks exist
         merged.on = merged.on ?? {};
@@ -5990,16 +7417,18 @@ class Selective {
         this.bindedQueries.set(query, merged);
         const doneToken = Libs.randomString();
         Libs.callbackScheduler.on(doneToken, () => {
-            iEvents.callEvent([this.find(query)], ...(merged.on.load));
+            iEvents.callEvent([this.find(query)], ...merged.on.load);
             Libs.callbackScheduler.clear(doneToken);
             merged.on.load = [];
         });
         const selectElements = Libs.getElements(query);
+        let hasAnyBound = false;
         selectElements.forEach((item) => {
             (async () => {
                 if (item.tagName === "SELECT") {
                     Libs.removeUnbinderMap(item);
                     if (this.applySelectBox(item, merged)) {
+                        hasAnyBound = true;
                         Libs.callbackScheduler.run(doneToken);
                     }
                 }
@@ -6008,6 +7437,30 @@ class Selective {
         if (!Libs.getBindedCommand().includes(query)) {
             Libs.getBindedCommand().push(query);
         }
+        // Mount if first bind and has elements
+        if (this.is(LifecycleState.INITIALIZED) && hasAnyBound) {
+            this.mount();
+        }
+        // Trigger update if already mounted
+        if (this.is(LifecycleState.MOUNTED)) {
+            this.update();
+        }
+    }
+    /**
+     * Override lifecycle mount - System is ready and has bound elements
+     */
+    mount() {
+        if (this.state !== LifecycleState.INITIALIZED)
+            return;
+        super.mount();
+    }
+    /**
+     * Override lifecycle update - Called when bindings change
+     */
+    update() {
+        if (this.state !== LifecycleState.MOUNTED)
+            return;
+        super.update();
     }
     /**
      * Finds the first bound SelectBox actions for a given query (or all bound queries if "*").
@@ -6052,20 +7505,26 @@ class Selective {
      * Selective bindings automatically when they match previously bound queries.
      */
     Observer() {
-        this.EAObserver = new ElementAdditionObserver();
-        this.EAObserver.onDetect((selectElement) => {
-            this.bindedQueries.forEach((options, query) => {
-                try {
-                    if (selectElement.matches(query)) {
-                        this.applySelectBox(selectElement, options);
+        if (!this.EAObserver) {
+            this.EAObserver = new ElementAdditionObserver();
+            this.EAObserver.onDetect((selectElement) => {
+                this.bindedQueries.forEach((options, query) => {
+                    try {
+                        if (selectElement.matches(query)) {
+                            this.applySelectBox(selectElement, options);
+                            // Trigger update when new element is bound
+                            if (this.is(LifecycleState.MOUNTED)) {
+                                this.update();
+                            }
+                        }
                     }
-                }
-                catch (error) {
-                    console.warn(`Invalid selector: ${query}`, error);
-                }
+                    catch (error) {
+                        console.warn(`Invalid selector: ${query}`, error);
+                    }
+                });
             });
-        });
-        this.EAObserver.start("select");
+        }
+        this.EAObserver.connect("select");
     }
     /**
      * Destroys Selective instances. Supports:
@@ -6085,17 +7544,26 @@ class Selective {
         else if (target instanceof HTMLSelectElement) {
             this.destroyElement(target);
         }
+        // Trigger update after partial destroy
+        if (target !== null && this.is(LifecycleState.MOUNTED)) {
+            this.update();
+        }
     }
     /**
      * Destroys all bound Selective instances and clears bindings/state.
      * Stops the ElementAdditionObserver.
+     * Calls lifecycle destroy.
      */
     destroyAll() {
+        if (this.state === LifecycleState.DESTROYED)
+            return;
         const bindedCommands = Libs.getBindedCommand();
         bindedCommands.forEach((query) => this.destroyByQuery(query));
         this.bindedQueries.clear();
         Libs.getBindedCommand().length = 0;
-        this.EAObserver?.stop();
+        this.EAObserver?.disconnect();
+        // Call parent lifecycle destroy
+        super.destroy();
     }
     /**
      * Destroys Selective instances bound to the specified query and removes
@@ -6125,17 +7593,17 @@ class Selective {
         const bindMap = Libs.getBinderMap(selectElement);
         if (!bindMap)
             return;
-        const popup = bindMap.container?.popup;
-        popup?.detroy();
+        const selfBox = bindMap.self;
         Libs.setUnbinderMap(selectElement, bindMap);
         const wasObserving = !!this.EAObserver;
         if (wasObserving)
-            this.EAObserver?.stop();
+            this.EAObserver?.disconnect();
         try {
             bindMap.self?.deInit?.();
         }
         catch (_) { }
-        const wrapper = bindMap.container?.element ?? selectElement.parentElement;
+        const wrapper = bindMap.container?.element ??
+            selectElement.parentElement;
         selectElement.style.display = "";
         selectElement.style.visibility = "";
         selectElement.disabled = false;
@@ -6144,12 +7612,13 @@ class Selective {
             wrapper.parentNode.replaceChild(selectElement, wrapper);
         }
         else {
-            document.body.appendChild(selectElement);
+            selectElement.appendChild(selectElement);
         }
         Libs.removeBinderMap(selectElement);
         if (wasObserving && this.bindedQueries.size > 0) {
-            this.EAObserver?.start("select");
+            this.EAObserver?.connect("select");
         }
+        selfBox?.destroy?.();
     }
     /**
      * Rebinds a query by destroying existing instances and binding anew
@@ -6161,6 +7630,10 @@ class Selective {
     rebind(query, options) {
         this.destroyByQuery(query);
         this.bind(query, options);
+        // Trigger update after rebind
+        if (this.is(LifecycleState.MOUNTED)) {
+            this.update();
+        }
     }
     /**
      * Applies SelectBox enhancement to a single <select> element:
@@ -6172,7 +7645,8 @@ class Selective {
      * @returns {boolean} - False if already bound; true if successfully applied.
      */
     applySelectBox(selectElement, options) {
-        if (Libs.getBinderMap(selectElement) || Libs.getUnbinderMap(selectElement)) {
+        if (Libs.getBinderMap(selectElement) ||
+            Libs.getUnbinderMap(selectElement)) {
             return false;
         }
         const SEID = Libs.randomString(8);
@@ -6182,13 +7656,20 @@ class Selective {
         options_cfg.SEID_HOLDER = `seui-${SEID}-placeholder`;
         const bindMap = { options: options_cfg };
         Libs.setBinderMap(selectElement, bindMap);
+        // Create SelectBox with lifecycle
         const selectBox = new SelectBox(selectElement, this);
+        selectBox.on("onMount", () => {
+            if (selectBox.container.view) {
+                selectBox.container.view.addEventListener("mouseup", () => {
+                    bindMap.action?.toggle?.();
+                });
+            }
+        });
+        // Mount the SelectBox
+        selectBox.mount();
         bindMap.container = selectBox.container;
         bindMap.action = selectBox.getAction();
         bindMap.self = selectBox;
-        selectBox.container.view.addEventListener("mouseup", () => {
-            bindMap.action?.toggle?.();
-        });
         return true;
     }
     /**
@@ -6205,7 +7686,8 @@ class Selective {
     getProperties(actionName, action) {
         const descriptor = Object.getOwnPropertyDescriptor(action, actionName);
         let type = "variable";
-        if (descriptor?.get || (descriptor?.set && typeof action[actionName] !== "function")) {
+        if (descriptor?.get ||
+            (descriptor?.set && typeof action[actionName] !== "function")) {
             type = "get-set";
         }
         else if (typeof action[actionName] === "function") {
@@ -6284,7 +7766,7 @@ const SECLASS = new Selective();
  *
  * Declared as `const` literal type to enable strict typing and easy tree-shaking.
  */
-const version = "1.2.3";
+const version = "1.2.4";
 /**
  * Library name identifier.
  *