selective-ui 1.0.2

package/src/js/models/group-model.js

@@ -0,0 +1,143 @@
+import { Model } from "../core/base/model";
+import { iEvents } from "../utils/ievents";
+import { Libs } from "../utils/libs";
+import { GroupView } from "../views/group-view";
+import { OptionModel } from "./option-model";
+
+/**
+ * @extends {Model<HTMLOptGroupElement, GroupViewTags, GroupView>}
+ */
+export class GroupModel extends Model {
+    label = "";
+    /** @type {OptionModel[]} */
+    items = [];
+    collapsed = false;
+    #privOnCollapsedChanged = [];
+
+    /**
+     * Initializes a group model with options and an optional <optgroup> target.
+     * Reads the label and collapsed state from the target element's attributes/dataset.
+     *
+     * @param {object} options - Configuration for the model.
+     * @param {HTMLOptGroupElement} [targetElement] - The source <optgroup> element.
+     */
+    constructor(options, targetElement) {
+        super(options, targetElement);
+        if (targetElement) {
+            this.label = targetElement.label;
+            this.collapsed = Libs.string2Boolean(targetElement.dataset?.collapsed);
+        }
+    }
+
+    /**
+     * Returns the array of values from all option items within the group.
+     *
+     * @type {String[]}
+     */
+    get value() {
+        return this.items.map(item => item.value);
+    }
+
+    /**
+     * Returns the list of option items currently selected within the group.
+     *
+     * @type {OptionModel[]}
+     */
+    get selectedItems() {
+        return this.items.filter(item => item.selected);
+    }
+
+    /**
+     * Returns the list of option items currently visible within the group.
+     *
+     * @type {OptionModel[]}
+     */
+    get visibleItems() {
+        return this.items.filter(item => item.visible);
+    }
+
+    /**
+     * Indicates whether the group has at least one visible option item.
+     *
+     * @type {boolean}
+     */
+    get hasVisibleItems() {
+        return this.visibleItems.length > 0;
+    }
+
+    /**
+     * Updates the group's label from the new target element and propagates the change to the view.
+     *
+     * @param {HTMLOptGroupElement} targetElement - The updated <optgroup> element.
+     */
+    update(targetElement) {
+        this.label = targetElement.label;
+        if (this.view) {
+            this.view.updateLabel(this.label);
+        }
+    }
+
+    /**
+     * Hook invoked when the target element reference changes.
+     * Updates the view's label and collapsed state to keep UI in sync.
+     */
+    onTargetChanged() {
+        if (this.view) {
+            this.view.updateLabel(this.label);
+            this.view.setCollapsed(this.collapsed);
+        }
+    }
+
+    /**
+     * Registers a callback to be invoked when the group's collapsed state changes.
+     *
+     * @param {(evtToken: any, model: GroupModel, collapsed: boolean) => void} callback - Listener for collapse changes.
+     */
+    onCollapsedChanged(callback) {
+        this.#privOnCollapsedChanged.push(callback);
+    }
+
+    /**
+     * Toggles the group's collapsed state, updates the view, and notifies registered listeners.
+     */
+    toggleCollapse() {
+        this.collapsed = !this.collapsed;
+        if (this.view) {
+            this.view.setCollapsed(this.collapsed);
+        }
+        iEvents.callEvent([this, this.collapsed], ...this.#privOnCollapsedChanged);
+    }
+
+    /**
+     * Adds an option item to this group and sets its back-reference to the group.
+     *
+     * @param {OptionModel} optionModel - The option to add.
+     */
+    addItem(optionModel) {
+        this.items.push(optionModel);
+        optionModel.group = this;
+    }
+
+    /**
+     * Removes an option item from this group and clears its group reference.
+     *
+     * @param {OptionModel} optionModel - The option to remove.
+     */
+    removeItem(optionModel) {
+        const index = this.items.indexOf(optionModel);
+        if (index > -1) {
+            this.items.splice(index, 1);
+            optionModel.group = null;
+        }
+    }
+
+    /**
+     * Updates the group's visibility in the view, typically based on children visibility.
+     * No-ops if the view is not initialized.
+     */
+    updateVisibility() {
+        if (this.view) {
+            this.view.updateVisibility();
+        }
+    }
+}

package/src/js/models/option-model.js

@@ -0,0 +1,237 @@
+import { Model } from "../core/base/model.js";
+import { iEvents } from "../utils/ievents.js";
+import { Libs } from "../utils/libs.js";
+import { OptionView } from "../views/option-view.js";
+
+/**
+ * @extends {Model<HTMLOptionElement, OptionViewTags, OptionView>}
+ */
+export class OptionModel extends Model {
+    #privOnSelected = [];
+    #privOnInternalSelected = [];
+    #privOnVisibilityChanged = [];
+    #visible = true;
+    #highlighted = false;
+
+    /** @type {import('./group-model').GroupModel} */
+    group = null
+    
+    /**
+     * Returns the image source from dataset (imgsrc or image), or an empty string if absent.
+     *
+     * @type {string}
+     */
+    get imageSrc() {
+        return this.dataset?.imgsrc || this.dataset?.image || "";
+    }
+    
+    /**
+     * Indicates whether this option has an associated image source.
+     *
+     * @type {boolean}
+     */
+    get hasImage() {
+        return !!this.imageSrc;
+    }
+    
+    /**
+     * Gets the option's current value from the underlying <option> element.
+     *
+     * @type {string}
+     */
+    get value() {
+        return this.targetElement.value;
+    }
+    
+    /**
+     * Gets whether the option is currently selected (proxied to the <option> element).
+     *
+     * @type {boolean}
+     */
+    get selected() {
+       return this.targetElement.selected;
+    }
+    
+    /**
+     * Sets the selected state and triggers external selection listeners.
+     * Uses selectedNonTrigger internally to update DOM/ARIA without firing external side effects first.
+     *
+     * @type {boolean}
+     */
+    set selected(value) {
+        this.selectedNonTrigger = value;
+        
+        iEvents.callEvent([this, value], ...this.#privOnSelected);
+    }
+    
+    /**
+     * Gets whether the option is currently visible in the UI.
+     *
+     * @type {boolean}
+     */
+    get visible() {
+        return this.#visible;
+    }
+    
+    /**
+     * Sets the visibility state; toggles "hide" class on the view and notifies visibility listeners.
+     *
+     * @type {boolean}
+     */
+    set visible(value) {
+        if (this.#visible === value) return;
+        this.#visible = value;
+        
+        const view = this.view?.getView();
+        if (view) {
+            view.classList.toggle("hide", !value);
+        }
+
+        iEvents.callEvent([this, value], ...this.#privOnVisibilityChanged);
+    }
+    
+    /**
+     * Gets the selected state without triggering external listeners (alias of selected).
+     *
+     * @type {boolean}
+     */
+    get selectedNonTrigger() {
+        return this.selected;
+    }
+    
+    /**
+     * Sets the selected state and updates input checked, CSS classes, ARIA attributes,
+     * and the underlying <option> 'selected' attribute. Notifies internal selection listeners.
+     *
+     * @type {boolean}
+     */
+    set selectedNonTrigger(value) {
+        const tag = this.view?.getTag("OptionInput");
+        const view = this.view?.getView();
+        
+        if (tag) {
+            tag.checked = value;
+        }
+
+        if (view) {
+            view.classList.toggle("checked", !!value);
+            view.setAttribute("aria-selected", value ? "true" : "false");
+            this.targetElement.toggleAttribute("selected", !!value);
+        }
+        
+        this.targetElement.selected = value;
+        iEvents.callEvent([this, value], ...this.#privOnInternalSelected);
+    }
+    
+    /**
+     * Returns the display text for the option, applying tag translation and optional HTML allowance.
+     * If allowHtml=false, returns stripped/sanitized text.
+     *
+     * @type {string}
+     */
+    get text() {
+        const text = Libs.tagTranslate(this.dataset?.mask ?? this.targetElement.text);
+        return this.options.allowHtml ? text : Libs.stripHtml(text);
+    }
+    
+    /**
+     * Returns a plain-text version of the display text (trimmed),
+     * stripping HTML if allowHtml is true, otherwise the raw text.
+     *
+     * @type {string}
+     */
+    get textContent() {
+        return this.options.allowHtml ? Libs.stripHtml(this.text).trim() : this.text.trim();
+    }
+    
+    /**
+     * Returns the dataset object of the underlying <option> element, or an empty object.
+     *
+     * @type {DOMStringMap|Record<string, string>}
+     */
+    get dataset() {
+        return this.targetElement.dataset ?? {};
+    }
+
+    /**
+     * Gets whether the option is currently highlighted (e.g., via keyboard navigation).
+     *
+     * @type {boolean}
+     */
+    get highlighted() {
+        return this.#highlighted;
+    }
+    
+
+    /**
+     * Sets the highlighted state and toggles the "highlight" CSS class on the view.
+     * Always syncs the DOM class even if the state is unchanged.
+     *
+     * @type {boolean}
+     */
+    set highlighted(value) {
+        const val = !!value;
+        const view = this.view?.getView?.();
+
+        if (this.#highlighted !== val) {
+            this.#highlighted = val;
+        }
+
+        if (view) {
+            view.classList.toggle('highlight', val);
+        }
+    }
+
+    
+    /**
+     * Registers a listener invoked when external selection changes (via setter `selected`).
+     *
+     * @param {(evtToken: any, el: OptionModel, selected: boolean) => void} callback - Selection listener.
+     */
+    onSelected(callback) {
+        this.#privOnSelected.push(callback);
+    }
+    
+    /**
+     * Registers a listener invoked when internal selection changes (via setter `selectedNonTrigger`).
+     *
+     * @param {(evtToken: any, el: OptionModel, selected: boolean) => void} callback - Internal selection listener.
+     */
+    onInternalSelected(callback) {
+        this.#privOnInternalSelected.push(callback);
+    }
+    
+    /**
+     * Registers a listener invoked when visibility changes (via setter `visible`).
+     *
+     * @param {(evtToken: any, model: OptionModel, visible: boolean) => void} callback - Visibility listener.
+     */
+    onVisibilityChanged(callback) {
+        this.#privOnVisibilityChanged.push(callback);
+    }
+    
+    /**
+     * Hook called when the target <option> element changes.
+     * Updates label content (HTML or text), image src/alt if present,
+     * and synchronizes initial selected state to the view.
+     */
+    onTargetChanged() {
+        const labelContent = this.view.getTag("LabelContent");
+        if (labelContent) {
+            if (this.options.allowHtml) {
+                labelContent.innerHTML = this.text;
+            }
+            else {
+                labelContent.textContent = this.textContent;
+            }
+        }
+
+        const imageTag = this.view.getTag("OptionImage");
+        if (imageTag && this.hasImage) {
+            imageTag.src = this.imageSrc;
+            imageTag.alt = this.text;
+        }
+        
+        this.selectedNonTrigger = this.targetElement.selected;
+    }
+}

package/src/js/services/dataset-observer.js

@@ -0,0 +1,73 @@
+export class DatasetObserver {
+    /** @type {MutationObserver} */
+    #observer;
+
+    /** @type {HTMLElement} */
+    #element;
+
+    #debounceTimer = null;
+
+    /**
+     * Observes data-* attribute changes on a target element and debounces notifications.
+     * Sets up a MutationObserver to detect dataset mutations and a fallback custom event listener.
+     *
+     * @param {HTMLElement} element - The element whose dataset (data-* attributes) will be observed.
+     */
+    constructor(element) {
+        this.#element = element;
+
+        this.#observer = new MutationObserver((mutations) => {
+            let datasetChanged = false;
+
+            for (const mutation of mutations) {
+                if (
+                    mutation.type === "attributes" &&
+                    mutation.attributeName?.startsWith("data-")
+                ) {
+                    datasetChanged = true;
+                    break;
+                }
+            }
+
+            if (!datasetChanged) return;
+
+            clearTimeout(this.#debounceTimer);
+            this.#debounceTimer = setTimeout(() => {
+                this.onChanged({ ...this.#element.dataset });
+            }, 50);
+        });
+
+        element.addEventListener("dataset:changed", () => {
+            this.onChanged({ ...this.#element.dataset });
+        });
+    }
+
+    /**
+     * Starts observing the element for attribute changes, including old values.
+     * Uses MutationObserver to track updates to data-* attributes.
+     */
+    connect() {
+        this.#observer.observe(this.#element, {
+            attributes: true,
+            attributeOldValue: true
+        });
+    }
+
+    /**
+     * Callback invoked when the element's dataset changes (debounced).
+     * Override in subclasses to handle dataset updates.
+     *
+     * @param {DOMStringMap} dataset - A shallow copy of the element's current dataset.
+     */
+    onChanged(dataset) {
+        // override
+    }
+
+    /**
+     * Stops observing the element and clears any pending debounce timers.
+     */
+    disconnect() {
+        clearTimeout(this.#debounceTimer);
+        this.#observer.disconnect();
+    }
+}

package/src/js/services/ea-observer.js

@@ -0,0 +1,88 @@
+/**
+ * @class
+ */
+export class ElementAdditionObserver {
+    #isActive = false;
+    /** @type {MutationObserver} */
+    #observer = null;
+
+    /** @type {Function[]} */
+    #actions = [];
+
+    /**
+     * Registers a callback to be invoked whenever a matching element is detected being added to the DOM.
+     *
+     * @param {(el: HTMLSelectElement) => void} action - Function executed with the newly added element.
+     */
+    onDetect(action) {
+        this.#actions.push(action);
+    }
+
+    /**
+     * Clears all previously registered detection callbacks.
+     */
+    clearDetect() {
+        this.#actions = [];
+    }
+
+    /**
+     * Starts observing the document for additions of elements matching the given tag.
+     * Detects both direct additions and nested matches within added subtrees.
+     *
+     * @param {string} tag - The tag name to watch for (e.g., "select", "div").
+     */
+    start(tag) {
+        if (this.#isActive) {
+            return;
+        }
+        this.#isActive = true;
+        const upperTag = tag.toUpperCase();
+        const lowerTag = tag.toLowerCase();
+        this.#observer = new MutationObserver((mutations) => {
+            mutations.forEach((mutation) => {
+                mutation.addedNodes.forEach((node) => {
+                    const subnode = /** @type {HTMLElement} */ (node);
+                    if (subnode.nodeType === 1) {
+                        if (subnode.tagName === upperTag) {
+                            this.#handle(subnode);
+                        }
+                        
+                        const selects = subnode.querySelectorAll(lowerTag);
+                        selects.forEach((select) => {
+                            this.#handle(select);
+                        });
+                    }
+                });
+            });
+        });
+
+        this.#observer.observe(document.body, {
+            childList: true,
+            subtree: true
+        });
+    }
+
+    /**
+     * Stops observing for element additions and releases internal resources.
+     * No-ops if the observer is not active.
+     */
+    stop() {
+        if (!this.#isActive) {
+            return;
+        }
+        this.#isActive = false;
+        this.#observer.disconnect();
+        this.#observer = null;
+    }
+
+    /**
+     * Internal handler that invokes all registered detection callbacks for the provided element.
+     *
+     * @param {Element} element - The element that was detected as added to the DOM.
+     */
+    #handle(element) {
+        this.#actions.forEach(action => {
+            action(element);
+        });
+    }
+}