selective-ui 1.0.4 → 1.0.5

package/dist/selective-ui.esm.js

@@ -1,4 +1,4 @@
-/*! Selective UI v1.0.4 | MIT License */
+/*! Selective UI v1.0.5 | MIT License */
 /**
  * @class
  */
@@ -789,6 +789,14 @@ class Refresher {
         
         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;
@@ -1388,58 +1396,206 @@ class OptionView extends View {
     /** @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" } }
@@ -1462,72 +1618,115 @@ class OptionView extends View {
         });
 
         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;
     }
 }
 
@@ -2083,6 +2282,8 @@ class ModelManager {
     /** @type {RecyclerViewContract<TAdapter>} */
     #privRecyclerViewHandle;
 
+    #lastFingerprint = null;
+
     options = null;
     
     /**
@@ -2112,6 +2313,48 @@ class ModelManager {
         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.
@@ -2152,6 +2395,8 @@ class ModelManager {
      * @param {Array<HTMLOptGroupElement|HTMLOptionElement>} modelData - New source elements to rebuild models from.
      */
     replace(modelData) {
+        this.#lastFingerprint = null;
+        
         this.createModelResources(modelData);
 
         if (this.#privAdapterHandle) {
@@ -2196,6 +2441,10 @@ class ModelManager {
      * @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 = [];
         
@@ -2206,20 +2455,29 @@ class ModelManager {
             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;
@@ -2234,11 +2492,21 @@ class ModelManager {
             }
             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);
@@ -2248,7 +2516,7 @@ class ModelManager {
                         newModels.push(existingOption);
                     }
                     
-                    oldOptionMap.delete(dataVset.value);
+                    oldOptionMap.delete(key);
                 } else {
                     const newOption = new OptionModel(this.options, dataVset);
                     newOption.position = position;
@@ -2264,6 +2532,12 @@ class ModelManager {
             }
         });
 
+        if (changesToApply.length > 0) {
+            requestAnimationFrame(() => {
+                changesToApply.forEach(change => change());
+            });
+        }
+
         oldGroupMap.forEach(removedGroup => {
             if (removedGroup.view) {
                 removedGroup.view.getView()?.remove();
@@ -2613,8 +2887,6 @@ class MixedAdapter extends Adapter {
 
         if (!optionModel.isInit) {
             super.onViewHolder(optionModel, optionViewer, position);
-        } else {
-            optionViewer.update();
         }
 
         optionModel.view = optionViewer;
@@ -2622,8 +2894,12 @@ class MixedAdapter extends Adapter {
         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;
+                }
             }
         }
 
@@ -4750,31 +5026,85 @@ class SelectObserver {
 
     #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, {
@@ -4786,16 +5116,19 @@ class SelectObserver {
         });
     }
 
+
     /**
-     * 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);
@@ -6126,7 +6459,7 @@ function markLoaded(name, version, api) {
     console.log(`[${name}] v${version} loaded successfully`);
 }
 
-const version = "1.0.4";
+const version = "1.0.5";
 const name = "SelectiveUI";
 
 const alreadyLoaded = checkDuplicate(name);