selective-ui 1.0.4 → 1.0.5

package/dist/selective-ui.umd.js

@@ -1,4 +1,4 @@
-/*! Selective UI v1.0.4 | MIT License */
+/*! Selective UI v1.0.5 | MIT License */
 (function (global, factory) {
     typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
     typeof define === 'function' && define.amd ? define(['exports'], factory) :
@@ -795,6 +795,14 @@
             
             let width = `${select.offsetWidth}px`,
                 height = `${select.offsetHeight}px`;
+                
+            const getCStyle = getComputedStyle(select);
+            if (width == "0px" && getCStyle.width != "auto") {
+                width = getCStyle.width;
+            }
+            if (height == "0px" && getCStyle.height != "auto") {
+                height = getCStyle.height;
+            }
             
             if (cfgWidth > 0) {
                 width = options.width;
@@ -1394,58 +1402,206 @@
         /** @type {OptionViewResult} */
         view;
 
-        isMultiple = false;
-        hasImage = false;
-        optionConfig = null;
+        #config = null;
+        #configProxy = null;
+        #isRendered = false;
+
+        /**
+         * Initializes the OptionView with a parent container and sets up the reactive config proxy.
+         * The proxy enables partial DOM updates when config properties change after initial render.
+         *
+         * @param {HTMLElement} parent - The parent element into which this view will be mounted.
+         */
+        constructor(parent) {
+            super(parent);
+            this.#setupConfigProxy();
+        }
+
+        /**
+         * Creates the internal configuration object and wraps it with a Proxy.
+         * The proxy intercepts property assignments and, if the view is rendered,
+         * applies only the necessary DOM changes for the updated property.
+         * No DOM mutations occur before the first render.
+         */
+        #setupConfigProxy() {
+            const self = this;
+            
+            this.#config = {
+                isMultiple: false,
+                hasImage: false,
+                imagePosition: 'right',
+                imageWidth: '60px',
+                imageHeight: '60px',
+                imageBorderRadius: '4px',
+                labelValign: 'center',
+                labelHalign: 'left'
+            };
+
+            this.#configProxy = new Proxy(this.#config, {
+                set(target, prop, value) {
+                    const oldValue = target[prop];
+                    
+                    if (oldValue !== value) {
+                        target[prop] = value;
+                        
+                        if (self.#isRendered) {
+                            self.#applyPartialChange(prop, value, oldValue);
+                        }
+                    }
+                    return true;
+                }
+            });
+        }
+
+        /**
+         * Indicates whether the option supports multiple selection (checkbox) instead of single (radio).
+         *
+         * @returns {boolean} True if multiple selection is enabled; otherwise false.
+         */
+        get isMultiple() {
+            return this.#config.isMultiple;
+        }
+
+        
+        /**
+         * Enables or disables multiple selection mode.
+         * When rendered, toggles the root CSS class and switches the input type between 'checkbox' and 'radio'.
+         *
+         * @param {boolean} value - True to enable multiple selection; false for single selection.
+         */
+        set isMultiple(value) {
+            this.#configProxy.isMultiple = !!value;
+        }
+
+        /**
+         * Indicates whether the option includes an image block alongside the label.
+         *
+         * @returns {boolean} True if an image is displayed; otherwise false.
+         */
+        get hasImage() {
+            return this.#config.hasImage;
+        }
+
+        
+        /**
+         * Shows or hides the image block for the option.
+         * When rendered, toggles related CSS classes and creates/removes the image element accordingly.
+         *
+         * @param {boolean} value - True to show the image; false to hide it.
+         */
+        set hasImage(value) {
+            this.#configProxy.hasImage = !!value;
+        }
+
+        /**
+         * Provides reactive access to the entire option configuration via a Proxy.
+         * Mutating properties on this object will trigger partial DOM updates when rendered.
+         *
+         * @returns {object} The proxied configuration object.
+         */
+        get optionConfig() {
+            return this.#configProxy;
+        }
+
+        
+        /**
+         * Applies a set of configuration changes in batch.
+         * Only properties that differ from the current config are updated.
+         * When rendered, each changed property triggers a targeted DOM update via the proxy.
+         *
+         * @param {object} config - Partial configuration object.
+         * @param {string} [config.imageWidth] - CSS width of the image (e.g., '60px').
+         * @param {string} [config.imageHeight] - CSS height of the image (e.g., '60px').
+         * @param {string} [config.imageBorderRadius] - CSS border-radius for the image (e.g., '4px').
+         * @param {'top'|'right'|'bottom'|'left'} [config.imagePosition] - Position of the image relative to the label.
+         * @param {'top'|'center'|'bottom'} [config.labelValign] - Vertical alignment of the label.
+         * @param {'left'|'center'|'right'} [config.labelHalign] - Horizontal alignment of the label.
+         */
+        set optionConfig(config) {
+            if (!config) return;
+            
+            const changes = {};
+            let hasChanges = false;
+
+            if (config.imageWidth !== undefined && config.imageWidth !== this.#config.imageWidth) {
+                changes.imageWidth = config.imageWidth;
+                hasChanges = true;
+            }
+            if (config.imageHeight !== undefined && config.imageHeight !== this.#config.imageHeight) {
+                changes.imageHeight = config.imageHeight;
+                hasChanges = true;
+            }
+            if (config.imageBorderRadius !== undefined && config.imageBorderRadius !== this.#config.imageBorderRadius) {
+                changes.imageBorderRadius = config.imageBorderRadius;
+                hasChanges = true;
+            }
+            if (config.imagePosition !== undefined && config.imagePosition !== this.#config.imagePosition) {
+                changes.imagePosition = config.imagePosition;
+                hasChanges = true;
+            }
+            if (config.labelValign !== undefined && config.labelValign !== this.#config.labelValign) {
+                changes.labelValign = config.labelValign;
+                hasChanges = true;
+            }
+            if (config.labelHalign !== undefined && config.labelHalign !== this.#config.labelHalign) {
+                changes.labelHalign = config.labelHalign;
+                hasChanges = true;
+            }
+
+            if (hasChanges) {
+                Object.assign(this.#configProxy, changes);
+            }
+        }
 
         /**
-         * Renders the option view DOM structure (input, optional image, label),
-         * sets ARIA attributes/IDs, mounts into parent, and applies initial config.
+         * Renders the option view into the parent element.
+         * Builds the DOM structure (input, optional image, label) based on current config,
+         * assigns classes and ARIA attributes, mounts via Libs.mountView, and marks as rendered
+         * to allow future incremental updates through the config proxy.
          */
         render() {
             const viewClass = ["selective-ui-option-view"];
             const opt_id = Libs.randomString(7);
             const inputID = `option_${opt_id}`;
 
-            if (this.isMultiple) {
+            if (this.#config.isMultiple) {
                 viewClass.push("multiple");
             }
-
-            if (this.hasImage) {
+            if (this.#config.hasImage) {
                 viewClass.push("has-image");
-                viewClass.push(`image-${this.optionConfig?.imagePosition}`);
+                viewClass.push(`image-${this.#config.imagePosition}`);
             }
 
             const childStructure = {
                 OptionInput: {
                     tag: {
                         node: "input",
-                        type: this.isMultiple ? "checkbox" : "radio",
+                        type: this.#config.isMultiple ? "checkbox" : "radio",
                         classList: "allow-choice",
                         id: inputID
                     }
                 },
-                ...(this.hasImage && {
+                ...(this.#config.hasImage && {
                     OptionImage: {
-                    tag: {
-                        node: "img",
-                        classList: "option-image",
-                        style: {
-                            width: this.optionConfig?.imageWidth || "60px",
-                            height: this.optionConfig?.imageHeight || "60px",
-                            borderRadius: this.optionConfig?.imageBorderRadius || "4px"
+                        tag: {
+                            node: "img",
+                            classList: "option-image",
+                            style: {
+                                width: this.#config.imageWidth,
+                                height: this.#config.imageHeight,
+                                borderRadius: this.#config.imageBorderRadius
+                            }
                         }
                     }
-                    }
                 }),
                 OptionLabel: {
                     tag: {
-                    node: "label",
-                    htmlFor: inputID,
-                    classList: [
-                        `align-vertical-${this.optionConfig?.labelValign}`,
-                        `align-horizontal-${this.optionConfig?.labelHalign}`
-                    ]
+                        node: "label",
+                        htmlFor: inputID,
+                        classList: [
+                            `align-vertical-${this.#config.labelValign}`,
+                            `align-horizontal-${this.#config.labelHalign}`
+                        ]
                     },
                     child: {
                         LabelContent: { tag: { node: "div" } }
@@ -1468,72 +1624,115 @@
             });
 
             this.parent.appendChild(this.view.view);
-
-            this.applyConfigToDOM();
-        }
-
-        /**
-         * Refreshes the option view by reapplying configuration (classes, alignments, image styles).
-         */
-        update() {
-            this.applyConfigToDOM();
+            this.#isRendered = true;
         }
 
         /**
-         * Applies current configuration to the DOM in a minimal, fast way:
-         * - Set root/label classes in a single assignment (less DOM churn),
-         * - Ensure input type matches selection mode,
-         * - Create/remove image element only when needed, update its styles.
+         * Applies a targeted DOM update for a single configuration property change.
+         * Safely updates classes, attributes, styles, and child elements without re-rendering the whole view.
+         *
+         * @param {string | symbol} prop - The name of the changed configuration property.
+         * @param {any} newValue - The new value assigned to the property.
+         * @param {any} oldValue - The previous value of the property.
          */
-        applyConfigToDOM() {
+        #applyPartialChange(prop, newValue, oldValue) {
             const v = this.view;
             if (!v || !v.view) return;
 
-            const root  = v.view;
+            const root = v.view;
             const input = v.tags?.OptionInput;
             const label = v.tags?.OptionLabel;
-            const isMultiple   = !!this.isMultiple;
-            const hasImage     = !!this.hasImage;
-            const imagePos     = this.optionConfig?.imagePosition || 'right';
-            const imageWidth   = this.optionConfig?.imageWidth      || '60px';
-            const imageHeight  = this.optionConfig?.imageHeight     || '60px';
-            const imageRadius  = this.optionConfig?.imageBorderRadius || '4px';
-            const vAlign       = this.optionConfig?.labelValign     || 'center';
-            const hAlign       = this.optionConfig?.labelHalign     || 'left';
 
-            const rootClasses = ['selective-ui-option-view'];
-            if (isMultiple) rootClasses.push('multiple');
-            if (hasImage) {
-                rootClasses.push('has-image', `image-${imagePos}`);
-            }
-            root.className = rootClasses.join(' ');
+            switch(prop) {
+                case 'isMultiple':
+                    root.classList.toggle('multiple', newValue);
+                    
+                    if (input && input.type !== (newValue ? 'checkbox' : 'radio')) {
+                        input.type = newValue ? 'checkbox' : 'radio';
+                    }
+                    break;
 
-            if (input) {
-                const desiredType = isMultiple ? 'checkbox' : 'radio';
-                if (input.type !== desiredType) input.type = desiredType;
-            }
+                case 'hasImage':
+                    root.classList.toggle('has-image', newValue);
+                    
+                    if (newValue) {
+                        root.classList.add(`image-${this.#config.imagePosition}`);
+                        this.#createImage();
+                    } else {
+                        root.className = root.className.replace(/image-(top|right|bottom|left)/g, '').trim();
+                        const image = v.tags?.OptionImage;
+                        if (image) {
+                            image.remove();
+                            v.tags.OptionImage = null;
+                        }
+                    }
+                    break;
 
-            if (label) {
-                label.className = `align-vertical-${vAlign} align-horizontal-${hAlign}`;
+                case 'imagePosition':
+                    if (this.#config.hasImage) {
+                        root.className = root.className.replace(/image-(top|right|bottom|left)/g, '').trim();
+                        root.classList.add(`image-${newValue}`);
+                    }
+                    break;
+
+                case 'imageWidth':
+                case 'imageHeight':
+                case 'imageBorderRadius':
+                    const image = v.tags?.OptionImage;
+                    if (image) {
+                        const styleProp = {
+                            'imageWidth': 'width',
+                            'imageHeight': 'height',
+                            'imageBorderRadius': 'borderRadius'
+                        }[prop];
+                        
+                        if (image.style[styleProp] !== newValue) {
+                            image.style[styleProp] = newValue;
+                        }
+                    }
+                    break;
+
+                case 'labelValign':
+                case 'labelHalign':
+                    if (label) {
+                        const newClass = `align-vertical-${this.#config.labelValign} align-horizontal-${this.#config.labelHalign}`;
+                        if (label.className !== newClass) {
+                            label.className = newClass;
+                        }
+                    }
+                    break;
             }
+        }
+
+        /**
+         * Creates the <img> element for the option on demand and inserts it into the DOM.
+         * Skips creation if the view or root is missing, or if an image already exists.
+         * The image receives configured styles (width, height, borderRadius) and is placed
+         * before the label if present; otherwise appended to the root. Updates `v.tags.OptionImage`.
+         */
+        #createImage() {
+            const v = this.view;
+            if (!v || !v.view) return;
 
             let image = v.tags?.OptionImage;
-            if (hasImage) {
-                if (!image) {
-                    image = document.createElement('img');
-                    image.className = 'option-image';
-                    if (label && label.parentElement) root.insertBefore(image, label);
-                    else root.appendChild(image);
-                    v.tags.OptionImage = image;
-                }
-                const style = image.style;
-                style.width        = imageWidth;
-                style.height       = imageHeight;
-                style.borderRadius = imageRadius;
-            } else if (image) {
-                image.remove();
-                v.tags.OptionImage = null;
+            if (image) return;
+
+            const root = v.view;
+            const label = v.tags?.OptionLabel;
+            
+            image = document.createElement('img');
+            image.className = 'option-image';
+            image.style.width = this.#config.imageWidth;
+            image.style.height = this.#config.imageHeight;
+            image.style.borderRadius = this.#config.imageBorderRadius;
+            
+            if (label && label.parentElement) {
+                root.insertBefore(image, label);
+            } else {
+                root.appendChild(image);
             }
+            
+            v.tags.OptionImage = image;
         }
     }
 
@@ -2089,6 +2288,8 @@
         /** @type {RecyclerViewContract<TAdapter>} */
         #privRecyclerViewHandle;
 
+        #lastFingerprint = null;
+
         options = null;
         
         /**
@@ -2118,6 +2319,48 @@
             this.#privRecyclerView = recyclerView;
         }
 
+        /**
+         * Checks whether the provided model data differs from the last recorded fingerprint.
+         * Computes a new fingerprint and compares it to the previous one; if different,
+         * updates the stored fingerprint and returns true, otherwise returns false.
+         *
+         * @param {Array<HTMLOptionElement|HTMLOptGroupElement>} modelData - The current model data (options/optgroups).
+         * @returns {boolean} True if there are real changes; false otherwise.
+         */
+        hasRealChanges(modelData) {
+            const newFingerprint = this.#createFingerprint(modelData);
+            const hasChanges = newFingerprint !== this.#lastFingerprint;
+            
+            if (hasChanges) {
+                this.#lastFingerprint = newFingerprint;
+            }
+            
+            return hasChanges;
+        }
+
+        /**
+         * Produces a stable string fingerprint for the given model data.
+         * For <optgroup>, includes the label and a pipe-joined hash of its child options
+         * (value:text:selected). For plain <option>, includes its value, text, and selected state.
+         * The entire list is joined by '||' to form the final fingerprint.
+         *
+         * @param {Array<HTMLOptionElement|HTMLOptGroupElement>} modelData - The current model data to fingerprint.
+         * @returns {string} A deterministic fingerprint representing the structure and selection state.
+         */
+        #createFingerprint(modelData) {
+            return modelData.map(item => {
+                if (item.tagName === "OPTGROUP") {
+                    const optionsHash = Array.from(item.children)
+                        .map((/** @type {HTMLOptionElement} */ opt) => `${opt.value}:${opt.text}:${opt.selected}`)
+                        .join('|');
+                    return `G:${item.label}:${optionsHash}`;
+                } else {
+                    const oItem = /** @type {HTMLOptionElement} */ (item);
+                    return `O:${oItem.value}:${oItem.text}:${oItem.selected}`;
+                }
+            }).join('||');
+        }
+
         /**
          * Builds model instances (GroupModel/OptionModel) from raw <optgroup>/<option> elements.
          * Preserves grouping relationships and returns the structured list.
@@ -2158,6 +2401,8 @@
          * @param {Array<HTMLOptGroupElement|HTMLOptionElement>} modelData - New source elements to rebuild models from.
          */
         replace(modelData) {
+            this.#lastFingerprint = null;
+            
             this.createModelResources(modelData);
 
             if (this.#privAdapterHandle) {
@@ -2202,6 +2447,10 @@
          * @param {Array<HTMLOptGroupElement|HTMLOptionElement>} modelData - Fresh DOM elements reflecting the latest state.
          */
         update(modelData) {
+            if (!this.hasRealChanges(modelData)) {
+                return;
+            }
+
             const oldModels = this.#privModelList;
             const newModels = [];
             
@@ -2212,20 +2461,29 @@
                 if (model instanceof GroupModel) {
                     oldGroupMap.set(model.label, model);
                 } else if (model instanceof OptionModel) {
-                    oldOptionMap.set(model.value, model);
+                    const key = `${model.value}::${model.textContent}`;
+                    oldOptionMap.set(key, model);
                 }
             });
 
             let currentGroup = null;
             let position = 0;
+            const changesToApply = [];
 
             modelData.forEach((data, index) => {
                 if (data.tagName === "OPTGROUP") {
                     let dataVset = /** @type {HTMLOptGroupElement} */ (data);
-                    const existingGroup = oldGroupMap.get(dataVset.label);
+                    const existingGroup = /** @type {GroupModel} */ (oldGroupMap.get(dataVset.label));
                     
                     if (existingGroup) {
-                        existingGroup.update(dataVset);
+                        const hasLabelChange = existingGroup.label !== dataVset.label;
+                        
+                        if (hasLabelChange) {
+                            changesToApply.push(() => {
+                                existingGroup.update(dataVset);
+                            });
+                        }
+                        
                         existingGroup.position = position;
                         existingGroup.items = [];
                         currentGroup = existingGroup;
@@ -2240,11 +2498,21 @@
                 }
                 else if (data.tagName === "OPTION") {
                     let dataVset = /** @type {HTMLOptionElement} */ (data);
-                    const existingOption = oldOptionMap.get(dataVset.value);
+                    const key = `${dataVset.value}::${dataVset.text}`;
+                    const existingOption = /** @type {OptionModel} */ (oldOptionMap.get(key));
                     
                     if (existingOption) {
-                        existingOption.update(dataVset);
-                        existingOption.position = position;
+                        const hasSelectedChange = existingOption.selected !== dataVset.selected;
+                        const hasPositionChange = existingOption.position !== position;
+                        
+                        if (hasSelectedChange || hasPositionChange) {
+                            changesToApply.push(() => {
+                                existingOption.update(dataVset);
+                                existingOption.position = position;
+                            });
+                        } else {
+                            existingOption.position = position;
+                        }
                         
                         if (dataVset["__parentGroup"] && currentGroup) {
                             currentGroup.addItem(existingOption);
@@ -2254,7 +2522,7 @@
                             newModels.push(existingOption);
                         }
                         
-                        oldOptionMap.delete(dataVset.value);
+                        oldOptionMap.delete(key);
                     } else {
                         const newOption = new OptionModel(this.options, dataVset);
                         newOption.position = position;
@@ -2270,6 +2538,12 @@
                 }
             });
 
+            if (changesToApply.length > 0) {
+                requestAnimationFrame(() => {
+                    changesToApply.forEach(change => change());
+                });
+            }
+
             oldGroupMap.forEach(removedGroup => {
                 if (removedGroup.view) {
                     removedGroup.view.getView()?.remove();
@@ -2619,8 +2893,6 @@
 
             if (!optionModel.isInit) {
                 super.onViewHolder(optionModel, optionViewer, position);
-            } else {
-                optionViewer.update();
             }
 
             optionModel.view = optionViewer;
@@ -2628,8 +2900,12 @@
             if (optionModel.hasImage) {
                 const imageTag = optionViewer.getTag("OptionImage");
                 if (imageTag) {
-                    imageTag.src = optionModel.imageSrc;
-                    imageTag.alt = optionModel.text;
+                    if (imageTag.src != optionModel.imageSrc) {
+                        imageTag.src = optionModel.imageSrc;
+                    }
+                    if (imageTag.alt != optionModel.text) {
+                        imageTag.alt = optionModel.text;
+                    }
                 }
             }
 
@@ -4756,31 +5032,85 @@
 
         #debounceTimer = null;
 
+        #lastSnapshot = null;
+
+        #DEBOUNCE_DELAY = 50;
+
+        
         /**
-         * Observes a <select> element for option list and attribute changes, with debouncing.
-         * Detects modifications to children (options added/removed) and relevant attributes
-         * ("selected", "value", "disabled"). Emits updates via the overridable onChanged() hook.
+         * Initializes the SelectObserver for a given <select> element.
+         * Captures the initial snapshot, sets up a MutationObserver, and listens for custom "options:changed" events.
+         * Changes are debounced to prevent excessive calls.
          *
-         * @param {HTMLSelectElement} select - The <select> element to monitor.
+         * @param {HTMLSelectElement} select - The <select> element to observe.
          */
         constructor(select) {
+            this.#select = select;
+            this.#lastSnapshot = this.#createSnapshot();
+
             this.#observer = new MutationObserver(() => {
                 clearTimeout(this.#debounceTimer);
                 this.#debounceTimer = setTimeout(() => {
-                    this.onChanged(select);
-                }, 50);
+                    this.#handleChange();
+                }, this.#DEBOUNCE_DELAY);
             });
 
-            this.#select = select;
-
             select.addEventListener("options:changed", () => {
-                this.onChanged(select);
+                clearTimeout(this.#debounceTimer);
+                this.#debounceTimer = setTimeout(() => {
+                    this.#handleChange();
+                }, this.#DEBOUNCE_DELAY);
             });
         }
 
         /**
-         * Starts observing the select element for child list mutations and attribute changes.
-         * Uses a MutationObserver with a debounce to batch rapid updates.
+         * Creates a snapshot of the current state of the <select> element's options.
+         * The snapshot includes option count, values, texts, and selected states for comparison.
+         *
+         * @returns {{length:number, values:string, texts:string, selected:string}} A snapshot of the options state.
+         */
+        #createSnapshot() {
+            const options = Array.from(this.#select.options);
+            return {
+                length: options.length,
+                values: options.map(opt => opt.value).join(','),
+                texts: options.map(opt => opt.text).join(','),
+                selected: options.map(opt => opt.selected).join(',')
+            };
+        }
+
+        /**
+         * Determines if there has been a real change in the <select> element's options or attributes.
+         * Compares the new snapshot with the previous one and updates the stored snapshot if different.
+         *
+         * @returns {boolean} True if a real change occurred, otherwise false.
+         */
+        #hasRealChange() {
+            const newSnapshot = this.#createSnapshot();
+            const changed = JSON.stringify(newSnapshot) !== JSON.stringify(this.#lastSnapshot);
+            
+            if (changed) {
+                this.#lastSnapshot = newSnapshot;
+            }
+            
+            return changed;
+        }
+
+        /**
+         * Handles detected changes after debouncing.
+         * If a real change is found, invokes the onChanged() hook with the current <select> element.
+         */
+        #handleChange() {
+            if (!this.#hasRealChange()) {
+                return;
+            }
+
+            this.onChanged(this.#select);
+        }
+
+        /**
+         * Starts observing the <select> element for child list mutations and attribute changes.
+         * Uses MutationObserver with a debounce mechanism to batch rapid updates.
          */
         connect() {
             this.#observer.observe(this.#select, {
@@ -4792,16 +5122,19 @@
             });
         }
 
+
         /**
-         * Hook invoked when the select's options or attributes change.
-         * Override to handle updates; receives the current HTMLCollection of options.
+         * Hook called when the <select> element's options or attributes change.
+         * Override this method to implement custom update handling logic.
          *
-         * @param {HTMLSelectElement} options - The Select element.
+         * @param {HTMLSelectElement} options - The current <select> element.
          */
         onChanged(options) { }
 
+
         /**
-         * Stops observing the select element and clears any pending debounce timers.
+         * Stops observing the <select> element and clears any pending debounce timers.
+         * Ensures no further change handling occurs after disconnecting.
          */
         disconnect() {
             clearTimeout(this.#debounceTimer);
@@ -6132,7 +6465,7 @@
         console.log(`[${name}] v${version} loaded successfully`);
     }
 
-    const version = "1.0.4";
+    const version = "1.0.5";
     const name = "SelectiveUI";
 
     const alreadyLoaded = checkDuplicate(name);