selective-ui 1.2.5 → 1.2.6

package/dist/selective-ui.esm.js

@@ -1,4 +1,4 @@
-/*! Selective UI v1.2.5 | MIT License */
+/*! Selective UI v1.2.6 | MIT License */
 /**
  * @class
  */
@@ -207,7 +207,7 @@ class CallbackScheduler {
      * @public
      * @param {TimerKey} key - Key whose callbacks will be scheduled.
      * @param {...any[]} params - Parameters passed as a shared payload to all callbacks.
-     * @returns {Promise<void> | void} Promise resolving when all callbacks finish execution.
+     * @returns {Promise<void>} Promise resolving when all callbacks finish execution.
      */
     run(key, ...params) {
         const executes = this.executeStored.get(key);
@@ -326,11 +326,11 @@ class Libs {
         return result;
     }
     /**
-     * Resolves a selector, NodeList, or single Element into an array of elements.
+     * Resolves a selector, NodeList, or single HTMLElement into an array of elements.
      * Returns an empty array if nothing is found.
      *
-     * @param {string|NodeListOf<Element>|Element|HTMLElement|ArrayLike<Element>|null} queryCommon - CSS selector, NodeList, or Element.
-     * @returns {Element[]} - Array of matched elements (empty if none).
+     * @param {string|NodeListOf<HTMLElement>|HTMLElement|HTMLElement|ArrayLike<HTMLElement>|null} queryCommon - CSS selector, NodeList, or HTMLElement.
+     * @returns {HTMLElement[]} - Array of matched elements (empty if none).
      */
     static getElements(queryCommon) {
         if (!queryCommon)
@@ -339,7 +339,7 @@ class Libs {
             const nodeList = document.querySelectorAll(queryCommon);
             return Array.from(nodeList);
         }
-        if (queryCommon instanceof Element) {
+        if (queryCommon instanceof HTMLElement) {
             return [queryCommon];
         }
         // NodeList or array-like
@@ -349,27 +349,27 @@ class Libs {
         return [];
     }
     /**
-     * Creates a new Element based on a NodeSpec and applies attributes, classes, styles, dataset, and events.
+     * Creates a new HTMLElement based on a NodeSpec and applies attributes, classes, styles, dataset, and events.
      *
      * @param {NodeSpec} data - Specification describing the element to create.
-     * @returns {Element} - The created element.
+     * @returns {HTMLElement} - The created element.
      */
     static nodeCreator(data = {}) {
         const nodeName = (data.node ?? "div");
         return this.nodeCloner(document.createElement(nodeName), data, true);
     }
     /**
-     * Clones an element (or converts a Node to Element) and applies NodeSpec options.
+     * Clones an element (or converts a Node to HTMLElement) and applies NodeSpec options.
      * When systemNodeCreate=true, uses the provided node as-is.
      *
-     * @param {Element} node - The element to clone or use.
+     * @param {HTMLElement} node - The element to clone or use.
      * @param {NodeSpec|null} _nodeOption - Options (classList, style, dataset, event, other props).
      * @param {boolean} systemNodeCreate - If true, do not clone; use original node.
-     * @returns {Element} - The processed element.
+     * @returns {HTMLElement} - The processed element.
      */
     static nodeCloner(node = document.documentElement, _nodeOption = null, systemNodeCreate = false) {
         const nodeOption = { ...(_nodeOption ?? {}) };
-        const element_creation = systemNodeCreate ? node : this.nodeToElement(node.cloneNode(true));
+        const element_creation = systemNodeCreate ? node : node.cloneNode(true);
         const classList = nodeOption.classList;
         if (typeof classList === "string") {
             element_creation.classList.add(classList);
@@ -429,40 +429,17 @@ class Libs {
         });
         return element_creation;
     }
-    /**
-     * Ensures the given Node is an Element; throws if not.
-     *
-     * @param {Node} node - The node to validate.
-     * @returns {Element} - The element cast.
-     * @throws {TypeError} - If node is not an Element.
-     */
-    static nodeToElement(node) {
-        if (node instanceof Element)
-            return node;
-        throw new TypeError("Node is not an Element");
-    }
-    /**
-     * Mounts a view from a plain object specification and returns a typed result
-     * containing the root element and a tag map.
-     *
-     * @template TTags
-     * @param {object} rawObj - The specification describing elements and tags.
-     * @returns {MountViewResult<TTags>} - The mounted view and its tag references.
-     */
-    static mountView(rawObj) {
-        return this.mountNode(rawObj);
-    }
     /**
      * Recursively builds DOM nodes from a specification object, appends/prepends them
      * to an optional parent, and returns either a tag map or a full MountViewResult.
      *
      * @template TTags
      * @param {Object<string, any>} rawObj - Node spec (keys -> { tag, child }).
-     * @param {Element|null} [parentE=null] - Parent to attach into; if null, returns root.
+     * @param {HTMLElement|null} [parentE=null] - Parent to attach into; if null, returns root.
      * @param {boolean} [isPrepend=false] - If true, prepend; otherwise append.
      * @param {boolean} [isRecusive=false] - Internal flag for recursion control.
      * @param {TTags|Object} [recursiveTemp={}] - Accumulator for tag references.
-     * @returns {MountViewResult<TTags>|TTags} - Tag map or the final mount result.
+     * @returns {TTags} - Tag map or the final mount result.
      */
     static mountNode(rawObj, parentE = null, isPrepend = false, isRecusive = false, recursiveTemp = {}) {
         let view = null;
@@ -581,7 +558,7 @@ class Libs {
     /**
      * Removes a binder map entry for the given element from the global storage.
      *
-     * @param {HTMLElement} element - Element key to remove from the binder map.
+     * @param {HTMLElement} element - HTMLElement key to remove from the binder map.
      * @returns {boolean} - True if an entry existed and was removed.
      */
     static removeBinderMap(element) {
@@ -590,8 +567,8 @@ class Libs {
     /**
      * Retrieves the binder map entry associated with the given element.
      *
-     * @param {HTMLElement} item - Element key whose binder map is requested.
-     * @returns {BinderMap | null} - The stored binder map value or undefined if absent.
+     * @param {HTMLElement} item - HTMLElement key whose binder map is requested.
+     * @returns {BinderMap | any} - The stored binder map value or undefined if absent.
      */
     static getBinderMap(item) {
         return this.iStorage.bindedMap.get(item);
@@ -599,7 +576,7 @@ class Libs {
     /**
      * Sets or updates the binder map entry for a given element.
      *
-     * @param {HTMLElement} item - Element key to associate with the binder map.
+     * @param {HTMLElement} item - HTMLElement key to associate with the binder map.
      * @param {BinderMap} bindMap - Value to store in the binder map.
      */
     static setBinderMap(item, bindMap) {
@@ -608,7 +585,7 @@ class Libs {
     /**
      * Removes an unbinder map entry for the given element from the global storage.
      *
-     * @param {HTMLElement} element - Element key to remove from the unbinder map.
+     * @param {HTMLElement} element - HTMLElement key to remove from the unbinder map.
      * @returns {boolean} - True if an entry existed and was removed.
      */
     static removeUnbinderMap(element) {
@@ -617,7 +594,7 @@ class Libs {
     /**
      * Retrieves the unbinder map entry associated with the given element.
      *
-     * @param {HTMLElement} item - Element key whose unbinder map is requested.
+     * @param {HTMLElement} item - HTMLElement key whose unbinder map is requested.
      * @returns {unknown} - The stored unbinder map value or undefined if absent.
      */
     static getUnbinderMap(item) {
@@ -626,7 +603,7 @@ class Libs {
     /**
      * Sets or updates the unbinder map entry for a given element.
      *
-     * @param {HTMLElement} item - Element key to associate with the unbinder map.
+     * @param {HTMLElement} item - HTMLElement key to associate with the unbinder map.
      * @param {BinderMap} bindMap - Value to store in the unbinder map.
      */
     static setUnbinderMap(item, bindMap) {
@@ -1274,7 +1251,7 @@ class Lifecycle {
  * getter/setter APIs for the placeholder content.
  *
  * ### Responsibility
- * - Create and own the placeholder DOM element (`.selective-ui-placeholder`).
+ * - Create and own the placeholder DOM element (`.seui-placeholder`).
  * - Render placeholder content from {@link SelectiveOptions.placeholder}.
  * - Support runtime updates via {@link set}, optionally persisting into options.
  * - Participate in the shared {@link Lifecycle} FSM.
@@ -1332,7 +1309,7 @@ class PlaceHolder extends Lifecycle {
      * Builds the placeholder DOM node and starts the lifecycle.
      *
      * Side effects:
-     * - Creates a `div.selective-ui-placeholder` node via {@link Libs.nodeCreator}.
+     * - Creates a `div.seui-placeholder` node via {@link Libs.nodeCreator}.
      * - Writes initial placeholder content into `innerHTML`.
      * - Transitions the lifecycle by calling `init()`.
      *
@@ -1342,7 +1319,7 @@ class PlaceHolder extends Lifecycle {
     initialize(options) {
         this.node = Libs.nodeCreator({
             node: "div",
-            classList: "selective-ui-placeholder",
+            classList: "seui-placeholder",
             innerHTML: options.placeholder,
         });
         this.options = options;
@@ -1463,7 +1440,7 @@ class Directive extends Lifecycle {
         // is guaranteed to be an HTMLElement in this context.
         this.node = Libs.nodeCreator({
             node: "div",
-            classList: "selective-ui-directive",
+            classList: "seui-directive",
             role: "button",
             ariaLabel: "Toggle dropdown",
         });
@@ -1602,9 +1579,9 @@ class OptionHandle extends Lifecycle {
      * Initializes DOM and binds event handlers.
      *
      * DOM structure (conceptually):
-     * - Root: `div.selective-ui-option-handle.hide`
-     * - Child: `a.selective-ui-option-handle-item` ("Select all")
-     * - Child: `a.selective-ui-option-handle-item` ("Deselect all")
+     * - Root: `div.seui-option-handle.hide`
+     * - Child: `a.seui-option-handle-item` ("Select all")
+     * - Child: `a.seui-option-handle-item` ("Deselect all")
      *
      * Click handlers:
      * - "Select all" → dispatches {@link actionOnSelectAll} via {@link iEvents.callFunctions}
@@ -1620,12 +1597,12 @@ class OptionHandle extends Lifecycle {
     initialize(options) {
         this.nodeMounted = Libs.mountNode({
             OptionHandle: {
-                tag: { node: "div", classList: ["selective-ui-option-handle", "hide"] },
+                tag: { node: "div", classList: ["seui-option-handle", "hide"] },
                 child: {
                     SelectAll: {
                         tag: {
                             node: "a",
-                            classList: "selective-ui-option-handle-item",
+                            classList: "seui-option-handle-item",
                             textContent: options.textSelectAll,
                             onclick: () => {
                                 iEvents.callFunctions(this.actionOnSelectAll);
@@ -1635,7 +1612,7 @@ class OptionHandle extends Lifecycle {
                     DeSelectAll: {
                         tag: {
                             node: "a",
-                            classList: "selective-ui-option-handle-item",
+                            classList: "seui-option-handle-item",
                             textContent: options.textDeselectAll,
                             onclick: () => {
                                 iEvents.callFunctions(this.actionOnDeSelectAll);
@@ -1833,7 +1810,7 @@ class EmptyState extends Lifecycle {
      *
      * Side effects:
      * - Creates the root `div` node with `role="status"` and `aria-live="polite"`.
-     * - Applies base CSS classes: `"selective-ui-empty-state"` and `"hide"`.
+     * - Applies base CSS classes: `"seui-empty-state"` and `"hide"`.
      * - Stores the options reference and calls {@link Lifecycle.init}.
      *
      * @param {SelectiveOptions} options - Configuration object containing empty state messages.
@@ -1843,7 +1820,7 @@ class EmptyState extends Lifecycle {
         this.options = options;
         this.node = Libs.nodeCreator({
             node: "div",
-            classList: ["selective-ui-empty-state", "hide"],
+            classList: ["seui-empty-state", "hide"],
             role: "status",
             ariaLive: "polite",
         });
@@ -1976,7 +1953,7 @@ class LoadingState extends Lifecycle {
      * Initializes internal resources for this component.
      *
      * Side effects:
-     * - Creates the root `div` node with base CSS classes: `"selective-ui-loading-state"` and `"hide"`.
+     * - Creates the root `div` node with base CSS classes: `"seui-loading-state"` and `"hide"`.
      * - Sets initial text to `options.textLoading`.
      * - Applies `role="status"` and `aria-live="polite"`.
      * - Stores the options reference and calls {@link Lifecycle.init}.
@@ -1988,7 +1965,7 @@ class LoadingState extends Lifecycle {
         this.options = options;
         this.node = Libs.nodeCreator({
             node: "div",
-            classList: ["selective-ui-loading-state", "hide"],
+            classList: ["seui-loading-state", "hide"],
             textContent: options.textLoading,
             role: "status",
             ariaLive: "polite",
@@ -2249,7 +2226,7 @@ class ResizeObserverService {
      * Not idempotent. Call {@link disconnect} before calling `connect()` again to avoid duplicates.
      */
     connect(element) {
-        if (!(element instanceof Element)) {
+        if (!(element instanceof HTMLElement)) {
             throw new Error("Invalid element");
         }
         this.element = element;
@@ -2389,7 +2366,7 @@ class Popup extends Lifecycle {
             PopupContainer: {
                 tag: {
                     node: "div",
-                    classList: "selective-ui-popup",
+                    classList: "seui-popup",
                     style: { maxHeight: options.panelHeight },
                 },
                 child: {
@@ -2398,7 +2375,7 @@ class Popup extends Lifecycle {
                         tag: {
                             id: options.SEID_LIST,
                             node: "div",
-                            classList: "selective-ui-options-container",
+                            classList: "seui-options-container",
                             role: "listbox",
                         },
                     },
@@ -2682,10 +2659,8 @@ class Popup extends Lifecycle {
         if (this.is(LifecycleState.DESTROYED)) {
             return;
         }
-        if (this.hideLoadHandle) {
-            clearTimeout(this.hideLoadHandle);
-            this.hideLoadHandle = null;
-        }
+        clearTimeout(this.hideLoadHandle);
+        this.hideLoadHandle = null;
         if (this.node && this.scrollListener) {
             this.node.removeEventListener("scroll", this.scrollListener);
             this.scrollListener = null;
@@ -2693,19 +2668,14 @@ class Popup extends Lifecycle {
         this.emptyState.destroy();
         this.loadingState.destroy();
         this.optionHandle.destroy();
-        try {
-            this.resizeObser?.disconnect();
-        }
-        catch (_) { }
-        this.resizeObser = null;
-        try {
-            this.effSvc?.setElement?.(null);
-        }
-        catch (_) { }
-        this.effSvc = null;
+        this.resizeObser?.disconnect?.();
+        this.effSvc?.setElement?.(null);
+        this.modelManager?.skipEvent?.(false);
+        this.recyclerView?.clear?.();
+        this.node?.remove?.();
         if (this.node) {
             try {
-                const clone = this.node.cloneNode(true);
+                const clone = Libs.nodeCloner(this.node);
                 this.node.replaceWith(clone);
                 clone.remove();
             }
@@ -2715,15 +2685,6 @@ class Popup extends Lifecycle {
         }
         this.node = null;
         this.optionsContainer = null;
-        try {
-            this.modelManager?.skipEvent?.(false);
-            this.recyclerView?.clear?.();
-            this.recyclerView = null;
-            this.optionAdapter = null;
-            // Original behavior kept intentionally.
-            this.node.remove();
-        }
-        catch (_) { }
         this.modelManager = null;
         this.optionHandle = null;
         this.emptyState = null;
@@ -2731,6 +2692,10 @@ class Popup extends Lifecycle {
         this.parent = null;
         this.options = null;
         this.isCreated = false;
+        this.effSvc = null;
+        this.resizeObser = null;
+        this.recyclerView = null;
+        this.optionAdapter = null;
         super.destroy();
     }
     /**
@@ -2964,8 +2929,8 @@ class SearchBox extends Lifecycle {
      * Initializes DOM, ARIA attributes, and interaction listeners.
      *
      * DOM structure (conceptually):
-     * - Root: `div.selective-ui-searchbox.hide`
-     * - Child: `input[type="search"].selective-ui-searchbox-input`
+     * - Root: `div.seui-searchbox.hide`
+     * - Child: `input[type="search"].seui-searchbox-input`
      *
      * Accessibility attributes set on the input:
      * - `role="searchbox"`: announces search field semantics
@@ -2995,14 +2960,14 @@ class SearchBox extends Lifecycle {
     initialize(options) {
         this.nodeMounted = Libs.mountNode({
             SearchBox: {
-                tag: { node: "div", classList: ["selective-ui-searchbox", "hide"] },
+                tag: { node: "div", classList: ["seui-searchbox", "hide"] },
                 child: {
                     SearchInput: {
                         tag: {
                             id: Libs.randomString(),
                             node: "input",
                             type: "search",
-                            classList: ["selective-ui-searchbox-input"],
+                            classList: ["seui-searchbox-input"],
                             placeholder: options.placeholder,
                             role: "searchbox",
                             ariaControls: options.SEID_LIST,
@@ -4190,15 +4155,17 @@ class OptionModel extends Model {
     set selectedNonTrigger(value) {
         const input = this.view?.view?.tags?.OptionInput;
         const viewEl = this.view?.getView?.();
-        if (input)
+        if (input) {
             input.checked = value;
+        }
         if (viewEl && this.targetElement) {
             viewEl.classList.toggle("checked", !!value);
             viewEl.setAttribute("aria-selected", value ? "true" : "false");
             this.targetElement.toggleAttribute("selected", !!value);
         }
-        if (this.targetElement)
+        if (this.targetElement) {
             this.targetElement.selected = value;
+        }
         iEvents.callEvent([this, value], ...this.privOnInternalSelected);
     }
     /**
@@ -4322,8 +4289,12 @@ class OptionModel extends Model {
         }
         const imageTag = this.view.view.tags.OptionImage;
         if (imageTag && this.hasImage) {
-            imageTag.src = this.imageSrc;
-            imageTag.alt = this.text;
+            if (imageTag.src != this.imageSrc) {
+                imageTag.src = this.imageSrc;
+            }
+            if (imageTag.alt != this.text) {
+                imageTag.alt = this.text;
+            }
         }
         if (this.targetElement)
             this.selectedNonTrigger = this.targetElement.selected;
@@ -4455,9 +4426,8 @@ class ModelManager extends Lifecycle {
                 this.privModelList.push(currentGroup);
             }
             else if (data.tagName === "OPTION") {
-                const optionEl = data;
-                const optionModel = new OptionModel(this.options, optionEl);
-                const parentGroup = optionEl["__parentGroup"];
+                const optionModel = new OptionModel(this.options, data);
+                const parentGroup = data["__parentGroup"];
                 if (parentGroup && currentGroup && parentGroup === currentGroup.targetElement) {
                     currentGroup.addItem(optionModel);
                     optionModel.group = currentGroup;
@@ -4868,7 +4838,7 @@ class RecyclerView extends Lifecycle {
  *   popup/layout logic to recompute geometry.
  *
  * ### DOM & a11y side effects
- * - Creates a root `<div>` with classes `selective-ui-accessorybox hide`.
+ * - Creates a root `<div>` with classes `seui-accessorybox hide`.
  * - Stops `mouseup` propagation on the root to avoid "outside click" behaviors.
  * - Each chip has:
  *   - a `<span role="button">` with `aria-label`/`title` for screen readers and tooltips,
@@ -4948,7 +4918,7 @@ class AccessoryBox extends Lifecycle {
      * Guarded: runs only when state is `NEW`.
      *
      * Side effects:
-     * - Creates the root node with base classes (`selective-ui-accessorybox`, `hide`).
+     * - Creates the root node with base classes (`seui-accessorybox`, `hide`).
      * - Stops `mouseup` propagation to avoid outside-click handlers reacting to chip interactions.
      *
      * @returns {void}
@@ -4961,7 +4931,7 @@ class AccessoryBox extends Lifecycle {
             AccessoryBox: {
                 tag: {
                     node: "div",
-                    classList: ["selective-ui-accessorybox", "hide"],
+                    classList: ["seui-accessorybox", "hide"],
                     onmouseup: (evt) => {
                         // Prevent outside listeners from reacting to chip clicks
                         evt.stopPropagation();
@@ -5028,7 +4998,7 @@ class AccessoryBox extends Lifecycle {
     /**
      * Assigns the {@link ModelManager} used to run selection pipelines and mutate selection state.
      *
-     * @param {ModelManager<MixedItem, MixedAdapter> | null} modelManager - Model manager controlling option state.
+     * @param {ModelManager<MixedItem, MixedAdapter>} modelManager - Model manager controlling option state.
      * @returns {void}
      */
     setModelManager(modelManager) {
@@ -6515,7 +6485,7 @@ class GroupView extends View {
      *
      * Creation flow:
      * 1. Generates unique group ID (7-character random string).
-     * 2. Creates DOM structure via {@link Libs.mountView}:
+     * 2. Creates DOM structure via {@link Libs.mountNode}:
      *    - Root: `<div role="group" aria-labelledby="seui-{id}-header">`
      *    - Header: `<div role="presentation" id="seui-{id}-header">`
      *    - Items: `<div role="group">` (nested group for child items)
@@ -6537,11 +6507,11 @@ class GroupView extends View {
      */
     mount() {
         const group_id = Libs.randomString(7);
-        this.view = Libs.mountView({
+        this.view = Libs.mountNode({
             GroupView: {
                 tag: {
                     node: "div",
-                    classList: ["selective-ui-group"],
+                    classList: ["seui-group"],
                     role: "group",
                     ariaLabelledby: `seui-${group_id}-header`,
                     id: `seui-${group_id}-group`,
@@ -6550,7 +6520,7 @@ class GroupView extends View {
                     GroupHeader: {
                         tag: {
                             node: "div",
-                            classList: ["selective-ui-group-header"],
+                            classList: ["seui-group-header"],
                             role: "presentation",
                             id: `seui-${group_id}-header`,
                         },
@@ -6558,7 +6528,7 @@ class GroupView extends View {
                     GroupItems: {
                         tag: {
                             node: "div",
-                            classList: ["selective-ui-group-items"],
+                            classList: ["seui-group-items"],
                             role: "group",
                         },
                     },
@@ -7003,7 +6973,7 @@ class OptionView extends View {
      *    - **OptionImage** (conditional): `<img>` with inline styles (width/height/borderRadius).
      *    - **OptionLabel**: `<label htmlFor="{inputID}">` with alignment classes.
      *      - **LabelContent**: `<div>` (content placeholder).
-     * 4. Creates DOM via {@link Libs.mountView}.
+     * 4. Creates DOM via {@link Libs.mountNode}.
      * 5. Appends root to {@link parent}.
      * 6. Sets {@link isRendered} to `true` (enables reactive updates).
      * 7. Transitions `INITIALIZED → MOUNTED` via `super.mount()`.
@@ -7021,7 +6991,7 @@ class OptionView extends View {
      * @override
      */
     mount() {
-        const viewClass = ["selective-ui-option-view"];
+        const viewClass = ["seui-option-view"];
         const opt_id = Libs.randomString(7);
         const inputID = `option_${opt_id}`;
         if (this.config.isMultiple)
@@ -7065,7 +7035,7 @@ class OptionView extends View {
                 },
             },
         };
-        this.view = Libs.mountView({
+        this.view = Libs.mountNode({
             OptionView: {
                 tag: {
                     node: "div",
@@ -8113,15 +8083,15 @@ class VirtualRecyclerView extends RecyclerView {
             return;
         this.viewElement.replaceChildren();
         const nodeMounted = Libs.mountNode({
-            PadTop: { tag: { node: "div", classList: "selective-ui-virtual-pad-top" } },
-            ItemsHost: { tag: { node: "div", classList: "selective-ui-virtual-items" } },
-            PadBottom: { tag: { node: "div", classList: "selective-ui-virtual-pad-bottom" } },
+            PadTop: { tag: { node: "div", classList: "seui-virtual-pad-top" } },
+            ItemsHost: { tag: { node: "div", classList: "seui-virtual-items" } },
+            PadBottom: { tag: { node: "div", classList: "seui-virtual-pad-bottom" } },
         }, this.viewElement);
         this.PadTop = nodeMounted.PadTop;
         this.ItemsHost = nodeMounted.ItemsHost;
         this.PadBottom = nodeMounted.PadBottom;
         this.scrollEl = this.opts.scrollEl
-            ?? this.viewElement.closest(".selective-ui-popup")
+            ?? this.viewElement.closest(".seui-popup")
             ?? this.viewElement.parentElement;
         if (!this.scrollEl)
             throw new Error("VirtualRecyclerView: scrollEl not found");
@@ -8450,7 +8420,7 @@ class VirtualRecyclerView extends RecyclerView {
         const now = performance.now();
         if (now - this.stickyCacheTick < 16)
             return this.stickyCacheVal;
-        const sticky = this.scrollEl.querySelector(".selective-ui-option-handle:not(.hide)");
+        const sticky = this.scrollEl.querySelector(".seui-option-handle:not(.hide)");
         this.stickyCacheVal = sticky?.offsetHeight ?? 0;
         this.stickyCacheTick = now;
         return this.stickyCacheVal;
@@ -9013,12 +8983,29 @@ class SelectBox extends Lifecycle {
          * @internal
          */
         this.isBeforeSearch = false;
+        /**
+         * Tracks whether {@link deInit} has already run.
+         *
+         * This guards teardown work (including plugin lifecycle hooks) from running more than once
+         * when {@link deInit} is called separately before {@link destroy}.
+         *
+         * @internal
+         */
+        this.hasDeInitialized = false;
         /**
          * Selective context (global helper / registry).
          *
          * Used to locate the instance wrapper via `Selective.find(...)` and to close other open instances.
          */
         this.Selective = null;
+        /**
+         * Registered plugins for this SelectBox instance.
+         */
+        this.plugins = [];
+        /**
+         * Cached plugin context for this SelectBox instance.
+         */
+        this.pluginContext = null;
         if (select && Selective)
             this.initialize(select, Selective);
     }
@@ -9135,12 +9122,12 @@ class SelectBox extends Lifecycle {
             placeholder.node.id = String(options.SEID_HOLDER ?? "");
         const container = Libs.mountNode({
             Container: {
-                tag: { node: "div", classList: "selective-ui-MAIN" },
+                tag: { node: "div", classList: "seui-MAIN" },
                 child: {
                     ViewPanel: {
                         tag: {
                             node: "div",
-                            classList: "selective-ui-view",
+                            classList: "seui-view",
                             tabIndex: 0,
                             onkeydown: (e) => {
                                 if (e.key === "Enter" || e.key === " " || e.key === "ArrowDown") {
@@ -9200,6 +9187,20 @@ class SelectBox extends Lifecycle {
         accessoryBox.setModelManager(optionModelManager);
         this.setupEventHandlers(select, container, options, searchController, searchbox);
         this.setupObservers(selectObserver, datasetObserver, select, optionModelManager);
+        this.plugins = this.Selective?.getPlugins?.() ?? [];
+        if (this.plugins.length) {
+            const resources = optionModelManager.getResources();
+            const pluginContext = {
+                selectBox: this,
+                options,
+                adapter: resources.adapter,
+                recycler: resources.recyclerView,
+                viewTags: container.tags,
+                actions: this.getAction(),
+            };
+            this.pluginContext = pluginContext;
+            this.runPluginHook("init", (plugin) => plugin.init?.(pluginContext));
+        }
         // Initial states
         this.isDisabled = Libs.string2Boolean(options.disabled);
         this.isReadOnly = Libs.string2Boolean(options.readonly);
@@ -9397,12 +9398,21 @@ class SelectBox extends Lifecycle {
      * preventing memory leaks and unintended background updates.
      */
     deInit() {
+        if (this.hasDeInitialized) {
+            return;
+        }
         const c = this.container ?? {};
         const { selectObserver, datasetObserver } = c;
+        if (this.plugins.length) {
+            this.runPluginHook("destroy", (plugin) => plugin.destroy?.());
+        }
+        this.plugins = [];
+        this.pluginContext = null;
         if (selectObserver?.disconnect)
             selectObserver.disconnect();
         if (datasetObserver?.disconnect)
             datasetObserver.disconnect();
+        this.hasDeInitialized = true;
     }
     /**
      * Lifecycle: `destroy` (teardown stage).
@@ -9716,6 +9726,9 @@ class SelectBox extends Lifecycle {
                 if (bindedOptions.multiple)
                     ViewPanel.setAttribute("aria-multiselectable", "true");
                 iEvents.callEvent([getInstance()], ...bindedOptions.on.show);
+                if (superThis.pluginContext) {
+                    superThis.runPluginHook("onOpen", (plugin) => plugin.onOpen?.(superThis.pluginContext));
+                }
                 return;
             },
             close() {
@@ -9732,6 +9745,9 @@ class SelectBox extends Lifecycle {
                 container.searchbox.hide();
                 container.tags.ViewPanel.setAttribute("aria-expanded", "false");
                 iEvents.callEvent([getInstance()], ...bindedOptions.on.close);
+                if (superThis.pluginContext) {
+                    superThis.runPluginHook("onClose", (plugin) => plugin.onClose?.(superThis.pluginContext));
+                }
                 return;
             },
             toggle() {
@@ -9770,6 +9786,10 @@ class SelectBox extends Lifecycle {
                 if (superThis.is(LifecycleState.MOUNTED)) {
                     superThis.update();
                 }
+                if (superThis.pluginContext && superThis.optionModelManager) {
+                    const resources = superThis.optionModelManager.getResources();
+                    superThis.runPluginHook("onChange", (plugin) => plugin.onChange?.(this.value, resources.modelList, resources.adapter, superThis.pluginContext));
+                }
             },
             refreshMask() {
                 let mask = bindedOptions.placeholder;
@@ -9902,6 +9922,27 @@ class SelectBox extends Lifecycle {
         }
         return flatOptions;
     }
+    /**
+     * Safely runs a hook across all registered plugins.
+     *
+     * Any plugin failure is isolated to prevent breaking the current flow.
+     *
+     * @param hook - Hook name for logging context.
+     * @param runner - Hook invocation handler.
+     * @internal
+     */
+    runPluginHook(hook, runner) {
+        if (!this.plugins.length)
+            return;
+        this.plugins.forEach((plugin) => {
+            try {
+                runner(plugin);
+            }
+            catch (error) {
+                console.error(`Plugin "${plugin.id}" ${hook} error:`, error);
+            }
+        });
+    }
 }
 
 /**
@@ -10128,6 +10169,15 @@ class Selective extends Lifecycle {
          * @private
          */
         this.bindedQueries = new Map();
+        /**
+         * Registry of Selective plugins keyed by plugin ID.
+         *
+         * - Managed via {@link registerPlugin}, {@link unregisterPlugin}, and {@link getPlugin}.
+         * - Cleared during {@link destroyAll} after invoking plugin teardown hooks.
+         *
+         * @private
+         */
+        this.plugins = new Map();
         this.init();
     }
     /**
@@ -10136,6 +10186,7 @@ class Selective extends Lifecycle {
      * Behavior:
      * - No-op if not in {@link LifecycleState.NEW} (idempotent guard).
      * - Initializes {@link bindedQueries} as empty `Map`.
+     * - Initializes {@link plugins} as empty `Map`.
      * - Transitions `NEW → INITIALIZED` via `super.init()`.
      *
      * Notes:
@@ -10151,6 +10202,7 @@ class Selective extends Lifecycle {
             return;
         // Initialize core properties
         this.bindedQueries = new Map();
+        this.plugins = new Map();
         super.init();
     }
     /**
@@ -10318,6 +10370,14 @@ class Selective extends Lifecycle {
         }
         return response;
     }
+    /**
+     * Returns all registered Selective plugins.
+     *
+     * @returns The list of plugins in registration order.
+     */
+    getPlugins() {
+        return Array.from(this.plugins.values());
+    }
     /**
      * Activates auto-binding for newly added `<select>` elements.
      *
@@ -10389,14 +10449,51 @@ class Selective extends Lifecycle {
             this.update();
         }
     }
+    /**
+     * Registers a plugin for Selective lifecycle integration.
+     *
+     * @public
+     * @param {SelectivePlugin} plugin - Plugin instance to register.
+     * @returns {void}
+     */
+    registerPlugin(plugin) {
+        if (!plugin?.id)
+            return;
+        this.plugins.set(plugin.id, plugin);
+    }
+    /**
+     * Unregisters a plugin by ID.
+     *
+     * @public
+     * @param {string} id - Plugin ID to remove.
+     * @returns {void}
+     */
+    unregisterPlugin(id) {
+        if (!id)
+            return;
+        this.plugins.delete(id);
+    }
+    /**
+     * Retrieves a plugin by ID.
+     *
+     * @public
+     * @param {string} id - Plugin ID to retrieve.
+     * @returns {SelectivePlugin | undefined} Plugin instance if found.
+     */
+    getPlugin(id) {
+        if (!id)
+            return undefined;
+        return this.plugins.get(id);
+    }
     /**
      * Destroys all bound Selective instances and releases global resources.
      *
      * Teardown flow:
      * 1. Iterates all registered queries and calls {@link destroyByQuery}.
      * 2. Clears {@link bindedQueries} and {@link Libs.getBindedCommand}.
-     * 3. Disconnects {@link EAObserver} (stops auto-binding).
-     * 4. Transitions to {@link LifecycleState.DESTROYED} via `super.destroy()`.
+     * 3. Invokes plugin teardown hooks and clears {@link plugins}.
+     * 4. Disconnects {@link EAObserver} (stops auto-binding).
+     * 5. Transitions to {@link LifecycleState.DESTROYED} via `super.destroy()`.
      *
      * Idempotency:
      * - No-op if already {@link LifecycleState.DESTROYED}.
@@ -10411,7 +10508,13 @@ class Selective extends Lifecycle {
         bindedCommands.forEach((query) => this.destroyByQuery(query));
         this.bindedQueries.clear();
         Libs.getBindedCommand().length = 0;
+        this.plugins.forEach((plugin) => {
+            plugin.destroy?.();
+            plugin.onDestroy?.();
+        });
+        this.plugins.clear();
         this.EAObserver?.disconnect();
+        this.plugins.clear();
         // Call parent lifecycle destroy
         super.destroy();
     }
@@ -10478,12 +10581,8 @@ class Selective extends Lifecycle {
         const wasObserving = !!this.EAObserver;
         if (wasObserving)
             this.EAObserver?.disconnect();
-        try {
-            bindMap.self?.deInit?.();
-        }
-        catch (_) { }
-        const wrapper = bindMap.container?.element ??
-            selectElement.parentElement;
+        bindMap.self?.deInit?.();
+        const wrapper = (bindMap.container?.element) ?? selectElement.parentElement;
         selectElement.style.display = "";
         selectElement.style.visibility = "";
         selectElement.disabled = false;
@@ -10703,7 +10802,7 @@ const SECLASS = new Selective();
  *
  * Declared as `const` literal type to enable strict typing and easy tree-shaking.
  */
-const version = "1.2.5";
+const version = "1.2.6";
 /**
  * Library name identifier.
  *
@@ -10782,6 +10881,22 @@ function rebind(query, options = {}) {
 function effector(element) {
     return Effector(element);
 }
+/**
+ * Register a Selective plugin globally.
+ *
+ * @param plugin - Plugin to register.
+ */
+function registerPlugin(plugin) {
+    SECLASS.registerPlugin(plugin);
+}
+/**
+ * Unregister a Selective plugin by id.
+ *
+ * @param id - Plugin id.
+ */
+function unregisterPlugin(id) {
+    SECLASS.unregisterPlugin(id);
+}
 let domInitialized = false;
 function init() {
     if (domInitialized)
@@ -10806,5 +10921,5 @@ if (typeof document !== "undefined") {
     }
 }
 
-export { bind, destroy, effector, find, name, rebind, version };
+export { bind, destroy, effector, find, name, rebind, registerPlugin, unregisterPlugin, version };
 //# sourceMappingURL=selective-ui.esm.js.map