selective-ui 1.2.5 → 1.2.6

package/dist/selective-ui.umd.js

@@ -1,4 +1,4 @@
-/*! Selective UI v1.2.5 | MIT License */
+/*! Selective UI v1.2.6 | MIT License */
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
     typeof define === 'function' && define.amd ? define(['exports'], factory) :
@@ -213,7 +213,7 @@
          * @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);
@@ -332,11 +332,11 @@
             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)
@@ -345,7 +345,7 @@
                 const nodeList = document.querySelectorAll(queryCommon);
                 return Array.from(nodeList);
             }
-            if (queryCommon instanceof Element) {
+            if (queryCommon instanceof HTMLElement) {
                 return [queryCommon];
             }
             // NodeList or array-like
@@ -355,27 +355,27 @@
             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);
@@ -435,40 +435,17 @@
             });
             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;
@@ -587,7 +564,7 @@
         /**
          * 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) {
@@ -596,8 +573,8 @@
         /**
          * 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);
@@ -605,7 +582,7 @@
         /**
          * 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) {
@@ -614,7 +591,7 @@
         /**
          * 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) {
@@ -623,7 +600,7 @@
         /**
          * 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) {
@@ -632,7 +609,7 @@
         /**
          * 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) {
@@ -1280,7 +1257,7 @@
      * 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.
@@ -1338,7 +1315,7 @@
          * 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()`.
          *
@@ -1348,7 +1325,7 @@
         initialize(options) {
             this.node = Libs.nodeCreator({
                 node: "div",
-                classList: "selective-ui-placeholder",
+                classList: "seui-placeholder",
                 innerHTML: options.placeholder,
             });
             this.options = options;
@@ -1469,7 +1446,7 @@
             // 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",
             });
@@ -1608,9 +1585,9 @@
          * 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}
@@ -1626,12 +1603,12 @@
         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);
@@ -1641,7 +1618,7 @@
                         DeSelectAll: {
                             tag: {
                                 node: "a",
-                                classList: "selective-ui-option-handle-item",
+                                classList: "seui-option-handle-item",
                                 textContent: options.textDeselectAll,
                                 onclick: () => {
                                     iEvents.callFunctions(this.actionOnDeSelectAll);
@@ -1839,7 +1816,7 @@
          *
          * 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.
@@ -1849,7 +1826,7 @@
             this.options = options;
             this.node = Libs.nodeCreator({
                 node: "div",
-                classList: ["selective-ui-empty-state", "hide"],
+                classList: ["seui-empty-state", "hide"],
                 role: "status",
                 ariaLive: "polite",
             });
@@ -1982,7 +1959,7 @@
          * 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}.
@@ -1994,7 +1971,7 @@
             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",
@@ -2255,7 +2232,7 @@
          * 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;
@@ -2395,7 +2372,7 @@
                 PopupContainer: {
                     tag: {
                         node: "div",
-                        classList: "selective-ui-popup",
+                        classList: "seui-popup",
                         style: { maxHeight: options.panelHeight },
                     },
                     child: {
@@ -2404,7 +2381,7 @@
                             tag: {
                                 id: options.SEID_LIST,
                                 node: "div",
-                                classList: "selective-ui-options-container",
+                                classList: "seui-options-container",
                                 role: "listbox",
                             },
                         },
@@ -2688,10 +2665,8 @@
             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;
@@ -2699,19 +2674,14 @@
             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();
                 }
@@ -2721,15 +2691,6 @@
             }
             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;
@@ -2737,6 +2698,10 @@
             this.parent = null;
             this.options = null;
             this.isCreated = false;
+            this.effSvc = null;
+            this.resizeObser = null;
+            this.recyclerView = null;
+            this.optionAdapter = null;
             super.destroy();
         }
         /**
@@ -2970,8 +2935,8 @@
          * 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
@@ -3001,14 +2966,14 @@
         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,
@@ -4196,15 +4161,17 @@
         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);
         }
         /**
@@ -4328,8 +4295,12 @@
             }
             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;
@@ -4461,9 +4432,8 @@
                     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;
@@ -4874,7 +4844,7 @@
      *   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,
@@ -4954,7 +4924,7 @@
          * 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}
@@ -4967,7 +4937,7 @@
                 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();
@@ -5034,7 +5004,7 @@
         /**
          * 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) {
@@ -6521,7 +6491,7 @@
          *
          * 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)
@@ -6543,11 +6513,11 @@
          */
         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`,
@@ -6556,7 +6526,7 @@
                         GroupHeader: {
                             tag: {
                                 node: "div",
-                                classList: ["selective-ui-group-header"],
+                                classList: ["seui-group-header"],
                                 role: "presentation",
                                 id: `seui-${group_id}-header`,
                             },
@@ -6564,7 +6534,7 @@
                         GroupItems: {
                             tag: {
                                 node: "div",
-                                classList: ["selective-ui-group-items"],
+                                classList: ["seui-group-items"],
                                 role: "group",
                             },
                         },
@@ -7009,7 +6979,7 @@
          *    - **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()`.
@@ -7027,7 +6997,7 @@
          * @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)
@@ -7071,7 +7041,7 @@
                     },
                 },
             };
-            this.view = Libs.mountView({
+            this.view = Libs.mountNode({
                 OptionView: {
                     tag: {
                         node: "div",
@@ -8119,15 +8089,15 @@
                 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");
@@ -8456,7 +8426,7 @@
             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;
@@ -9019,12 +8989,29 @@
              * @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);
         }
@@ -9141,12 +9128,12 @@
                 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") {
@@ -9206,6 +9193,20 @@
             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);
@@ -9403,12 +9404,21 @@
          * 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).
@@ -9722,6 +9732,9 @@
                     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() {
@@ -9738,6 +9751,9 @@
                     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() {
@@ -9776,6 +9792,10 @@
                     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;
@@ -9908,6 +9928,27 @@
             }
             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);
+                }
+            });
+        }
     }
 
     /**
@@ -10134,6 +10175,15 @@
              * @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();
         }
         /**
@@ -10142,6 +10192,7 @@
          * 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:
@@ -10157,6 +10208,7 @@
                 return;
             // Initialize core properties
             this.bindedQueries = new Map();
+            this.plugins = new Map();
             super.init();
         }
         /**
@@ -10324,6 +10376,14 @@
             }
             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.
          *
@@ -10395,14 +10455,51 @@
                 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}.
@@ -10417,7 +10514,13 @@
             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();
         }
@@ -10484,12 +10587,8 @@
             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;
@@ -10706,13 +10805,15 @@
     if (typeof globalThis.GLOBAL_SEUI == "undefined") {
         const SECLASS = new Selective();
         globalThis.GLOBAL_SEUI = {
-            version: "1.2.5",
+            version: "1.2.6",
             name: "SelectiveUI",
             bind: SECLASS.bind.bind(SECLASS),
             find: SECLASS.find.bind(SECLASS),
             destroy: SECLASS.destroy.bind(SECLASS),
             effector: Effector.bind(Effector),
-            rebind: SECLASS.rebind.bind(SECLASS)
+            rebind: SECLASS.rebind.bind(SECLASS),
+            registerPlugin: SECLASS.registerPlugin.bind(SECLASS),
+            unregisterPlugin: SECLASS.unregisterPlugin.bind(SECLASS)
         };
         let domInitialized = false;
         function init() {
@@ -10737,7 +10838,7 @@
                 init();
             }
         }
-        console.log(`[${"SelectiveUI"}] v${"1.2.5"} loaded successfully`);
+        console.log(`[${"SelectiveUI"}] v${"1.2.6"} loaded successfully`);
     }
     else {
         console.warn(`[${globalThis.GLOBAL_SEUI.name}] Already loaded (v${globalThis.GLOBAL_SEUI.version}). ` +
@@ -10827,6 +10928,22 @@
     function effector(element) {
         return globalThis.GLOBAL_SEUI.effector(element);
     }
+    /**
+     * Register a Selective plugin implementation.
+     *
+     * @param plugin - Plugin instance to register.
+     */
+    function registerPlugin(plugin) {
+        globalThis.GLOBAL_SEUI.registerPlugin(plugin);
+    }
+    /**
+     * Unregister a Selective plugin implementation by id.
+     *
+     * @param id - Plugin id to remove.
+     */
+    function unregisterPlugin(id) {
+        globalThis.GLOBAL_SEUI.unregisterPlugin(id);
+    }
 
     exports.bind = bind;
     exports.destroy = destroy;
@@ -10834,6 +10951,8 @@
     exports.find = find;
     exports.name = name;
     exports.rebind = rebind;
+    exports.registerPlugin = registerPlugin;
+    exports.unregisterPlugin = unregisterPlugin;
     exports.version = version;
 
 }));