selective-ui 1.2.6 → 1.3.0

package/README.md

@@ -5,12 +5,5 @@ Advanced Custom Select Component - Pure JavaScript, Zero Dependencies
 
 Full docs with examples: http://selective-ui.maisoft.io.vn/
 
-## Usage
-
-```ts
-registerPlugin(MyPlugin);
-bind(".my-select");
-```
-
 # License
 This is commercial software. See [LICENSE](https://github.com/maihcx/selective-ui/blob/main/LICENSE) for more info.

package/dist/selective-ui.esm.js

@@ -1,4 +1,4 @@
-/*! Selective UI v1.2.6 | MIT License */
+/*! Selective UI v1.3.0 | MIT License */
 /**
  * @class
  */
@@ -27,6 +27,7 @@ class iStorage {
             autofocus: true,
             searchable: true,
             loadingfield: true,
+            preload: false,
             visible: true,
             skipError: false,
             customDelimiter: ",",
@@ -36,8 +37,8 @@ class iStorage {
             textSelectAll: "Select all",
             textDeselectAll: "Deselect all",
             textAccessoryDeselect: "Deselect: ",
-            animationtime: 200, // millisecond
-            delaysearchtime: 200, // millisecond
+            animationtime: 200, // milliseconds
+            delaysearchtime: 200, // milliseconds
             allowHtml: false,
             maxSelected: 0,
             labelHalign: "left",
@@ -655,8 +656,7 @@ class Libs {
         tmp.innerHTML = s;
         tmp.querySelectorAll("script, style, iframe, object, embed, link").forEach((n) => n.remove());
         tmp.querySelectorAll("*").forEach((n) => {
-            for (const k in n.attributes) {
-                const a = n.attributes[k];
+            for (const a of Array.from(n.attributes)) {
                 const name = a.name ?? "";
                 const value = a.value ?? "";
                 if (/^on/i.test(name)) {
@@ -697,26 +697,34 @@ class Libs {
         return s.replace(/đ/g, "d").replace(/Đ/g, "d");
     }
     /**
-     * Parse select element to array (including optgroups)
-     * @param {HTMLSelectElement} selectElement
-     * @returns {Array<HTMLOptGroupElement|HTMLOptionElement>}
+     * Flattens a `<select>` element into an ordered array that includes optgroups
+     * and their child options.
+     *
+     * Notes:
+     * - Keeps original DOM order.
+     * - Adds a non-standard `__parentGroup` pointer on options inside optgroups.
+     *
+     * @param {HTMLSelectElement} selectElement - The source select element.
+     * @returns {Array<HTMLOptGroupElement | HTMLOptionElement>} Flattened node list.
      */
     static parseSelectToArray(selectElement) {
         const result = [];
-        const children = Array.from(selectElement.children);
-        children.forEach((child) => {
+        const children = selectElement.children;
+        for (let childIndex = 0; childIndex < children.length; childIndex++) {
+            const child = children[childIndex];
             if (child.tagName === "OPTGROUP") {
                 const group = child;
                 result.push(group);
-                Array.from(group.children).forEach((option) => {
+                for (let optionIndex = 0; optionIndex < group.children.length; optionIndex++) {
+                    const option = group.children[optionIndex];
                     option["__parentGroup"] = group;
                     result.push(option);
-                });
+                }
             }
             else if (child.tagName === "OPTION") {
                 result.push(child);
             }
-        });
+        }
         return result;
     }
     /**
@@ -2398,7 +2406,7 @@ class Popup extends Lifecycle {
             }
             : {};
         // Load ModelManager resources into the list container
-        this.modelManager.load(this.optionsContainer, { isMultiple: options.multiple }, recyclerViewOpt);
+        this.modelManager.load(this.optionsContainer, { isMultiple: options.multiple, options: options }, recyclerViewOpt);
         const MMResources = this.modelManager.getResources();
         this.optionAdapter = MMResources.adapter;
         this.recyclerView = MMResources.recyclerView;
@@ -2525,36 +2533,60 @@ class Popup extends Lifecycle {
     setupEffector(effectorSvc) {
         this.effSvc = effectorSvc;
     }
+    /**
+     * Loads and initializes the popup (one-time setup):
+     * - Appends the popup node to `document.body`
+     * - Initializes the resize observer service
+     * - Binds the effect service to the popup element
+     * - Blocks mousedown events inside the popup to prevent auto-close
+     *
+     * Safely no-ops when the popup has already been created
+     * or required dependencies are missing.
+     */
+    load() {
+        if (!this.node || !this.parent || !this.effSvc)
+            return;
+        if (this.isCreated)
+            return;
+        document.body.appendChild(this.node);
+        this.isCreated = true;
+        this.resizeObser = new ResizeObserverService();
+        this.effSvc.setElement(this.node);
+        this.node.addEventListener("mousedown", (e) => {
+            e.stopPropagation();
+            e.preventDefault();
+        });
+    }
     /**
      * 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
+     * - Ensures the popup is loaded and initialized
+     * - Synchronizes option handle visibility
+     * - Optionally evaluates and applies the empty/not-found state
+     * - Computes placement relative to the parent anchor
+     * - Runs the expand animation
+     * - Connects the resize observer after animation completes
+     * - Resumes the recycler view
+     *
+     * Safely no-ops when required dependencies are missing.
      *
      * @param callback - Optional callback invoked when the opening animation completes.
-     * @param isShowEmptyState - If true, evaluates and applies empty/not-found state before animation.
+     * @param isShowEmptyState - If true, applies the empty/not-found state before animation.
      */
     open(callback = null, isShowEmptyState) {
         if (!this.node || !this.options || !this.optionHandle || !this.parent || !this.effSvc)
             return;
-        if (!this.isCreated) {
-            document.body.appendChild(this.node);
-            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();
-            });
-        }
+        // Ensure one-time initialization
+        this.load();
+        // Sync option visibility state
         this.optionHandle.update();
+        // Apply empty state if requested
         if (isShowEmptyState) {
             this.updateEmptyState();
         }
+        // Compute placement based on parent anchor
         const location = this.getParentLocation();
         const { position, top, maxHeight, realHeight } = this.calculatePosition(location);
+        // Run expand animation
         this.effSvc.expand({
             duration: this.options.animationtime,
             display: "flex",
@@ -2567,13 +2599,14 @@ class Popup extends Lifecycle {
             onComplete: () => {
                 if (!this.resizeObser || !this.parent)
                     return;
+                // Recompute position on parent resize to keep behavior consistent
                 this.resizeObser.onChanged = (_metrics) => {
-                    // Recompute from parent each time to keep behavior identical.
                     const loc = this.getParentLocation();
                     this.handleResize(loc);
                 };
                 this.resizeObser.connect(this.parent.container.tags.ViewPanel);
                 callback?.();
+                // Resume recycler view rendering after animation
                 const rv = this.recyclerView;
                 rv?.resume?.();
             },
@@ -3782,6 +3815,7 @@ class GroupModel extends Model {
          */
         this.privOnCollapsedChanged = [];
         this.label = this.targetElement.label;
+        this.collapsed = Libs.string2Boolean(this.targetElement.dataset?.collapsed);
     }
     /**
      * Initializes group state from the backing `<optgroup>` (if present) and mounts the model.
@@ -3798,7 +3832,6 @@ class GroupModel extends Model {
      * @override
      */
     init() {
-        this.collapsed = Libs.string2Boolean(this.targetElement.dataset?.collapsed);
         super.init();
         this.mount();
     }
@@ -5518,7 +5551,8 @@ class SearchController extends Lifecycle {
             .join(",");
         let payload;
         if (typeof cfg.data === "function") {
-            payload = cfg.data.bind(this.selectBox.Selective.find(this.selectBox.container.targetElement))(keyword, page);
+            const selectiveInstance = this.selectBox?.Selective?.find(this.selectBox?.container?.targetElement);
+            payload = cfg.data.call(selectiveInstance, keyword, page);
             if (payload && typeof payload.selectedValue === "undefined")
                 payload.selectedValue = selectedValues;
         }
@@ -6463,8 +6497,18 @@ class View extends Lifecycle {
  * @see {@link View}
  */
 class GroupView extends View {
-    constructor() {
-        super(...arguments);
+    /**
+     * Creates a new GroupView bound to the given parent element.
+     *
+     * Initialization flow:
+     * 1. Calls `super(parent)` (View base constructor).
+     *
+     * @public
+     * @param {HTMLElement} parent - Container element that will host this group view.
+     * @param {SelectiveOptions} options - Optional configuration for this group view.
+     */
+    constructor(parent, options) {
+        super(parent);
         /**
          * Strongly-typed reference to the mounted group view structure.
          *
@@ -6479,6 +6523,16 @@ class GroupView extends View {
          * @public
          */
         this.view = null;
+        /**
+         * Parsed configuration (bound from the `<select>` element via binder map).
+         *
+         * Provides feature flags (multiple/disabled/readonly/visible/virtualScroll/ajax/autoclose…),
+         * a11y ids (e.g. `SEID_LIST`, `SEID_HOLDER`) and user callbacks under `options.on`.
+         *
+         * @internal
+         */
+        this.options = null;
+        this.options = options;
     }
     /**
      * Mounts the group view into the DOM.
@@ -6486,8 +6540,8 @@ class GroupView extends View {
      * Creation flow:
      * 1. Generates unique group ID (7-character random string).
      * 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">`
+     *    - Root: `<div role="group" aria-labelledby="seui-{this.options?.SEID || default}-{id}-header">`
+     *    - Header: `<div role="presentation" id="seui-{this.options?.SEID || default}-{id}-header">`
      *    - Items: `<div role="group">` (nested group for child items)
      * 3. Appends root to {@link parent} container.
      * 4. Transitions `INITIALIZED → MOUNTED` via `super.mount()`.
@@ -6513,8 +6567,8 @@ class GroupView extends View {
                     node: "div",
                     classList: ["seui-group"],
                     role: "group",
-                    ariaLabelledby: `seui-${group_id}-header`,
-                    id: `seui-${group_id}-group`,
+                    ariaLabelledby: `seui-${this.options?.SEID || "default"}-${group_id}-header`,
+                    id: `seui-${this.options?.SEID || "default"}-${group_id}-group`,
                 },
                 child: {
                     GroupHeader: {
@@ -6522,7 +6576,7 @@ class GroupView extends View {
                             node: "div",
                             classList: ["seui-group-header"],
                             role: "presentation",
-                            id: `seui-${group_id}-header`,
+                            id: `seui-${this.options?.SEID || "default"}-${group_id}-header`,
                         },
                     },
                     GroupItems: {
@@ -6731,8 +6785,9 @@ class OptionView extends View {
      *
      * @public
      * @param {HTMLElement} parent - Container element that will host this option view.
+     * @param {SelectiveOptions} options - Optional configuration for this option view.
      */
-    constructor(parent) {
+    constructor(parent, options) {
         super(parent);
         /**
          * Strongly-typed reference to the mounted option view structure.
@@ -6748,6 +6803,15 @@ class OptionView extends View {
          * @public
          */
         this.view = null;
+        /**
+         * Parsed configuration (bound from the `<select>` element via binder map).
+         *
+         * Provides feature flags (multiple/disabled/readonly/visible/virtualScroll/ajax/autoclose…),
+         * a11y ids (e.g. `SEID_LIST`, `SEID_HOLDER`) and user callbacks under `options.on`.
+         *
+         * @internal
+         */
+        this.options = null;
         /**
          * Internal configuration object (Proxy target).
          *
@@ -6789,6 +6853,7 @@ class OptionView extends View {
          * @private
          */
         this.isRendered = false;
+        this.options = options;
         this.initialize();
     }
     /**
@@ -6993,7 +7058,7 @@ class OptionView extends View {
     mount() {
         const viewClass = ["seui-option-view"];
         const opt_id = Libs.randomString(7);
-        const inputID = `option_${opt_id}`;
+        const inputID = `option_${this.options?.SEID ?? "default"}_${opt_id}`;
         if (this.config.isMultiple)
             viewClass.push("multiple");
         if (this.config.hasImage) {
@@ -7039,7 +7104,7 @@ class OptionView extends View {
             OptionView: {
                 tag: {
                     node: "div",
-                    id: `seui-${opt_id}-option`,
+                    id: `seui-${this.options?.SEID ?? "default"}-${opt_id}-option`,
                     classList: viewClass,
                     role: "option",
                     ariaSelected: "false",
@@ -7253,6 +7318,15 @@ class MixedAdapter extends Adapter {
         super(items);
         /** Whether the adapter operates in multi-selection mode. */
         this.isMultiple = false;
+        /**
+         * Parsed configuration (bound from the `<select>` element via binder map).
+         *
+         * Provides feature flags (multiple/disabled/readonly/visible/virtualScroll/ajax/autoclose…),
+         * a11y ids (e.g. `SEID_LIST`, `SEID_HOLDER`) and user callbacks under `options.on`.
+         *
+         * @internal
+         */
+        this.options = null;
         /**
          * Subscribers for aggregated visibility statistics.
          * Fired via a debounced scheduler to avoid repeated recomputation during batch updates.
@@ -7345,8 +7419,8 @@ class MixedAdapter extends Adapter {
      */
     viewHolder(parent, item) {
         if (item instanceof GroupModel)
-            return new GroupView(parent);
-        return new OptionView(parent);
+            return new GroupView(parent, this.options);
+        return new OptionView(parent, this.options);
     }
     /**
      * Binds a model (group or option) to its view and delegates to specialized handlers.
@@ -7414,7 +7488,7 @@ class MixedAdapter extends Adapter {
         groupModel.items.forEach((optionModel, idx) => {
             let optionViewer = optionModel.view;
             if (!optionModel.isInit || !optionViewer) {
-                optionViewer = new OptionView(itemsContainer);
+                optionViewer = new OptionView(itemsContainer, this.options);
             }
             this.handleOptionView(optionModel, optionViewer, idx);
             optionModel.isInit = true;
@@ -9171,16 +9245,17 @@ class SelectBox extends Lifecycle {
         });
         this.optionModelManager = optionModelManager;
         // Popup
-        container.popup = new Popup(select, options, optionModelManager);
-        container.popup.setupEffector(effector);
-        container.popup.setupInfiniteScroll(searchController, options);
-        container.popup.onAdapterPropChanged("selected", () => {
+        const popup = new Popup(select, options, optionModelManager);
+        container.popup = popup;
+        popup.setupEffector(effector);
+        popup.setupInfiniteScroll(searchController, options);
+        popup.onAdapterPropChanged("selected", () => {
             this.getAction()?.change(null, true);
         });
-        container.popup.onAdapterPropChanged("selected_internal", () => {
+        popup.onAdapterPropChanged("selected_internal", () => {
             this.getAction()?.change(null, false);
         });
-        container.popup.onAdapterPropChanging("select", () => {
+        popup.onAdapterPropChanging("select", () => {
             this.oldValue = this.getAction()?.value ?? "";
         });
         accessoryBox.setRoot(container.tags.ViewPanel);
@@ -9237,7 +9312,11 @@ class SelectBox extends Lifecycle {
         Refresher.resizeBox(select, container.tags.ViewPanel);
         select.classList.add("init");
         // initial mask
-        this.getAction()?.change(null, false);
+        const action = this.getAction();
+        action?.change?.(null, false);
+        if (this.options.preload) {
+            action?.load?.();
+        }
         // Call parent lifecycle mount
         super.mount();
     }
@@ -9677,6 +9756,26 @@ class SelectBox extends Lifecycle {
                 }
                 this.change(false, trigger);
             },
+            load() {
+                if ((!superThis.hasLoadedOnce || superThis.isBeforeSearch) && bindedOptions?.ajax) {
+                    container.searchController.resetPagination();
+                    container.popup.showLoading();
+                    superThis.hasLoadedOnce = true;
+                    superThis.isBeforeSearch = false;
+                    setTimeout(() => {
+                        if (!container.popup || !container.searchController)
+                            return;
+                        container.searchController
+                            .search("")
+                            .then(() => container.popup?.triggerResize?.())
+                            .catch((err) => console.error("Initial ajax load error:", err));
+                    }, bindedOptions.animationtime);
+                    container.popup.load();
+                }
+                else {
+                    container.popup.load();
+                }
+            },
             open() {
                 if (superThis.isOpen)
                     return;
@@ -9686,45 +9785,34 @@ class SelectBox extends Lifecycle {
                     if (closeToken.isCancel)
                         return;
                 }
-                if (this.disabled)
+                if (this.disabled) {
                     return;
+                }
                 const beforeShowToken = iEvents.callEvent([getInstance()], ...bindedOptions.on.beforeShow);
-                if (beforeShowToken.isCancel)
+                if (beforeShowToken.isCancel) {
                     return;
+                }
                 superThis.isOpen = true;
                 container.directive.setDropdown(true);
                 const adapter = container.popup.optionAdapter;
                 const selectedOption = adapter.getSelectedItem();
-                if (selectedOption)
+                if (selectedOption) {
                     adapter.setHighlight(selectedOption, false);
-                else
-                    adapter.resetHighlight();
-                if ((!superThis.hasLoadedOnce || superThis.isBeforeSearch) && bindedOptions?.ajax) {
-                    container.searchController.resetPagination();
-                    container.popup.showLoading();
-                    superThis.hasLoadedOnce = true;
-                    superThis.isBeforeSearch = false;
-                    setTimeout(() => {
-                        if (!container.popup || !container.searchController)
-                            return;
-                        container.searchController
-                            .search("")
-                            .then(() => container.popup?.triggerResize?.())
-                            .catch((err) => console.error("Initial ajax load error:", err));
-                    }, bindedOptions.animationtime);
-                    container.popup.open(null, false);
                 }
                 else {
-                    container.popup.open(null, true);
+                    adapter.resetHighlight();
                 }
+                this.load();
+                container.popup.open(null, !container.popup.loadingState.isVisible);
                 container.searchbox.show();
                 const ViewPanel = container.tags.ViewPanel;
                 ViewPanel.setAttribute("aria-expanded", "true");
                 ViewPanel.setAttribute("aria-controls", bindedOptions.SEID_LIST);
                 ViewPanel.setAttribute("aria-haspopup", "listbox");
                 ViewPanel.setAttribute("aria-labelledby", bindedOptions.SEID_HOLDER);
-                if (bindedOptions.multiple)
+                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));
@@ -9998,7 +10086,7 @@ class ElementAdditionObserver {
          *
          * @internal
          */
-        this.actions = [];
+        this.actions = new Set();
     }
     /**
      * Registers a callback invoked whenever a matching element is detected as added to the DOM.
@@ -10010,7 +10098,7 @@ class ElementAdditionObserver {
      * @param action - Function executed with the newly detected element.
      */
     onDetect(action) {
-        this.actions.push(action);
+        this.actions.add(action);
     }
     /**
      * Clears all registered detection callbacks.
@@ -10019,7 +10107,7 @@ class ElementAdditionObserver {
      * to scan mutations but will not invoke any listeners until new callbacks are registered.
      */
     clearDetect() {
-        this.actions = [];
+        this.actions.clear();
     }
     /**
      * Starts observing the document for additions of elements matching the given tag name.
@@ -10093,7 +10181,9 @@ class ElementAdditionObserver {
      * @internal
      */
     handle(element) {
-        this.actions.forEach((action) => action(element));
+        for (const action of this.actions) {
+            action(element);
+        }
     }
 }
 
@@ -10802,7 +10892,7 @@ const SECLASS = new Selective();
  *
  * Declared as `const` literal type to enable strict typing and easy tree-shaking.
  */
-const version = "1.2.6";
+const version = "1.3.0";
 /**
  * Library name identifier.
  *