selective-ui 1.0.2

package/src/js/core/base/adapter.js

@@ -0,0 +1,163 @@
+import { Libs } from "../../utils/libs";
+import { Model } from "./model";
+
+/**
+ * @template {ModelContract<any, any>} TItem
+ * @implements {AdapterContract<TItem>}
+ */
+export class Adapter {
+    /** @type {TItem[]} */
+    items = [];
+    adapterKey = Libs.randomString(12);
+
+    isSkipEvent = false;
+
+
+    /**
+     * Initializes the adapter with an optional array of items and invokes onInit()
+     * to perform any subclass-specific setup. Accepts a generic list of models.
+     *
+     * @param {TItem[]} [items=[]] - Initial items to be managed by the adapter.
+     */
+    constructor(items = []) {
+        this.items = items;
+        this.onInit();
+    }
+
+    /**
+     * Lifecycle hook called once after construction. Override in subclasses to
+     * perform setup tasks (e.g., event wiring, cache building).
+     */
+    onInit() {}
+
+    /**
+     * Binds an item model to its viewer at a given position. If the item has not
+     * been initialized yet, renders the viewer; otherwise triggers an update.
+     *
+     * @param {any} item - The model instance to bind to the view.
+     * @param {any} viewer - The view instance responsible for rendering the model.
+     * @param {number} position - The index of the item within the adapter.
+     */
+    onViewHolder(item, viewer, position) {
+        if (!item.isInit) {
+            viewer.render();
+        }
+        else {
+            viewer.update();
+        }
+    }
+
+    /**
+     * Registers a pre-change (debounced) callback for a property change pipeline.
+     * The callback is scheduled with a minimal delay to batch rapid updates.
+     *
+     * @param {string} propName - The property name to observe (e.g., "items").
+     * @param {Function} callback - Function to execute before the property changes.
+     */
+    onPropChanging(propName, callback) {
+        Libs.timerProcess.setExecute(`${propName}ing_${this.adapterKey}`, callback, 1);
+    }
+
+    /**
+     * Registers a post-change callback for a property change pipeline.
+     * The callback is executed after the property is updated.
+     *
+     * @param {string} propName - The property name to observe (e.g., "items").
+     * @param {Function} callback - Function to execute after the property changes.
+     */
+    onPropChanged(propName, callback) {
+        Libs.timerProcess.setExecute(`${propName}_${this.adapterKey}`, callback);
+    }
+
+    /**
+     * Triggers the post-change pipeline for a given property, passing optional parameters
+     * to registered callbacks. Use this after mutating adapter state.
+     *
+     * @param {string} propName - The property name to emit (e.g., "items").
+     * @param {...any} params - Parameters forwarded to the callbacks.
+     */
+    changeProp(propName, ...params) {
+        Libs.timerProcess.run(`${propName}_${this.adapterKey}`, ...params);
+    }
+
+    /**
+     * Triggers the pre-change pipeline for a given property, passing optional parameters
+     * to registered callbacks. Use this before mutating adapter state.
+     *
+     * @param {string} propName - The property name to emit (e.g., "items").
+     * @param {...any} params - Parameters forwarded to the callbacks.
+     */
+    changingProp(propName, ...params) {
+        Libs.timerProcess.run(`${propName}ing_${this.adapterKey}`, ...params);
+    }
+
+
+    /**
+     * Creates and returns a viewer instance for the given item within the specified parent container.
+     * Override in subclasses to return a concrete view implementation tailored to TItem.
+     *
+     * @param {HTMLElement} parent - The container element that will host the viewer.
+     * @param {TItem} item - The model instance for which the viewer is created.
+     * @returns {any} - The created viewer instance; null by default.
+     */
+    viewHolder(parent, item) {
+        return null;
+    }
+
+    /**
+     * Returns the total number of items currently managed by the adapter.
+     *
+     * @returns {number} - The item count.
+     */
+    itemCount() {
+        return this.items.length;
+    }
+
+    /**
+     * Replaces the adapter's items with a new collection, emitting pre-change and post-change
+     * notifications to observers. Does not render; call updateRecyclerView() to apply to the DOM.
+     *
+     * @param {TItem[]} items - The new list of items to set.
+     */
+    setItems(items) {
+        this.changingProp("items", items);
+        this.items = items;
+        this.changeProp("items", items);
+    }
+
+    /**
+     * Synchronizes adapter items from an external source by delegating to setItems().
+     * Useful for keeping adapter state aligned with another data store.
+     *
+     * @param {TItem[]} items - The source list of items to synchronize.
+     */
+    syncFromSource(items) {
+        this.setItems(items);
+    }
+
+    /**
+     * Iterates through all items and ensures each has a viewer. For new items, calls viewHolder()
+     * to create the viewer, then binds via onViewHolder() and marks the item as initialized.
+     *
+     * @param {HTMLElement|null} parent - The container element in which item viewers are rendered.
+     */
+    updateRecyclerView(parent) {
+        for (let index = 0; index < this.itemCount(); index++) {
+            let viewer = this.items[index].view;
+            if (!this.items[index].isInit) {
+                viewer = this.viewHolder(parent, this.items[index]);
+            }
+            this.onViewHolder(this.items[index], viewer, index);
+
+            this.items[index].isInit = true;
+        }
+    }
+
+    /**
+     * Updates adapter data without performing any default actions.
+     * Override in subclasses to implement custom data refresh logic.
+     *
+     * @param {TItem[]} items - The incoming data to apply to the adapter.
+     */
+    updateData(items) { }
+}

package/src/js/core/base/model.js

@@ -0,0 +1,59 @@
+/**
+ * @template TTarget
+ * @template {Record<string, Element>} TTags
+ * @template {ViewContract<TTags>} TView
+ * @implements {ModelContract<TTarget, TView>}
+ */
+export class Model {
+    /** @type {TTarget | null} */
+    targetElement = null;
+
+    options = null;
+
+    /** @type {TView | null} */
+    view = null;
+
+    position = -1;
+
+    isInit = false;
+
+    /**
+     * Returns the current value from the underlying target element's "value" attribute.
+     * For single-select, this is typically a string; for multi-select, may be an array depending on usage.
+     *
+     * @type {String|String[]}
+     */
+    get value() {
+        return /** @type {HTMLElement} */ (this.targetElement).getAttribute("value");
+    }
+
+    /**
+     * Constructs a Model instance with configuration options and optional bindings to a target element and view.
+     * Stores references for later updates and rendering.
+     *
+     * @param {object} options - Configuration options for the model.
+     * @param {TTarget|null} [targetElement=null] - The underlying element (e.g., <option> or group node).
+     * @param {TView|null} [view=null] - The associated view responsible for rendering the model.
+     */
+    constructor(options, targetElement = null, view = null) {
+        this.options = options;
+        this.targetElement = targetElement;
+        this.view = view;
+    }
+
+    /**
+     * Updates the bound target element reference and invokes the change hook.
+     *
+     * @param {TTarget|null} targetElement - The new target element to bind to the model.
+     */
+    update(targetElement) {
+        this.targetElement = targetElement;
+        this.onTargetChanged();
+    }
+
+    /**
+     * Hook invoked whenever the target element changes.
+     * Override in subclasses to react to attribute/content updates (e.g., text, disabled state).
+     */
+    onTargetChanged() { }
+}

package/src/js/core/base/recyclerview.js

@@ -0,0 +1,83 @@
+/**
+ * @template {ModelContract<any, any>} TItem
+ * @template {AdapterContract<TItem>} TAdapter
+ * @implements {RecyclerViewContract<TAdapter>}
+ */
+export class RecyclerView {
+    /**
+     * @type {HTMLDivElement}
+     */
+    viewElement = null;
+
+    /**
+     * @type {TAdapter}
+     */
+    adapter = null;
+
+    /**
+     * Constructs a RecyclerView with an optional container element that will host rendered item views.
+     *
+     * @param {HTMLDivElement|null} [viewElement=null] - The root element where the adapter will render items.
+     */
+    constructor(viewElement = null) {
+        this.viewElement = viewElement;
+    }
+    
+    /**
+     * Sets or updates the container element used to render the adapter's item views.
+     *
+     * @param {HTMLDivElement} viewElement - The root element for rendering.
+     */
+    setView(viewElement) {
+        this.viewElement = viewElement;
+    }
+    
+    /**
+     * Attaches an adapter to the RecyclerView and wires item-change lifecycle:
+     * - onPropChanging("items"): clears the container before items change,
+     * - onPropChanged("items"): re-renders after items change,
+     * then performs an initial render.
+     *
+     * @param {TAdapter} adapter - The adapter managing models and their views.
+     */
+    setAdapter(adapter) {
+        this.adapter = adapter;
+
+        adapter.onPropChanging("items", () => {
+            this.clear();
+        });
+
+        adapter.onPropChanged("items", () => {
+            this.render();
+        });
+
+        this.render();
+    }
+
+    /**
+     * Removes all child nodes from the rendering container, if present.
+     * Used prior to re-rendering or when items are changing.
+     */
+    clear() {
+        if (!this.viewElement) return;
+        this.viewElement.replaceChildren();
+    }
+
+    /**
+     * Renders the current adapter contents into the container.
+     * No-ops if either the adapter or the container is not set.
+     */
+    render() {
+        if (!this.adapter || !this.viewElement) return;
+
+        this.adapter.updateRecyclerView(this.viewElement);
+    }
+
+    /**
+     * Forces a re-render of the current adapter state into the container.
+     * Useful when visual updates are required without changing the data.
+     */
+    refresh() {
+        this.render();
+    }
+}

package/src/js/core/base/view.js

@@ -0,0 +1,62 @@
+
+/**
+ * @template {Record<string, Element>} TTags
+ * @implements {ViewContract<TTags>}
+ */
+export class View {
+    /** @type {Element|null} */
+    parent = null;
+
+    /**
+     * Initializes the view with a parent container element that will host its rendered content.
+     *
+     * @param {Element} parent - The parent element into which this view will render.
+     */
+    constructor(parent) {
+        this.parent = parent;
+    }
+
+    /**
+     * Renders the view into the parent container.
+     * Override in subclasses to create DOM structure and mount tags.
+     */
+    render() {}
+    
+    /**
+     * Updates the view to reflect model or state changes.
+     * Override in subclasses to patch DOM nodes without full re-render.
+     */
+    update() {}
+
+    /** @type {MountViewResult<TTags>} */
+    view = null;
+
+    /**
+     * Returns the root HTMLElement of the mounted view.
+     *
+     * @returns {HTMLElement} - The root view element.
+     */
+    getView() {
+        return this.view.view;
+    }
+
+    /**
+     * Retrieves a single tagged element from the mounted view.
+     *
+     * @template {keyof TTags} K
+     * @param {K} tag - The tag key corresponding to the desired element.
+     * @returns {TTags[K]} - The element associated with the provided tag key.
+     */
+    getTag(tag) {
+        return this.view.tags[tag];
+    }
+
+    /**
+     * Retrieves the full tag map for the mounted view.
+     *
+     * @returns {TTags} - An object map of all tagged elements.
+     */
+    getTags() {
+        return this.view.tags;
+    }
+}

package/src/js/core/model-manager.js

@@ -0,0 +1,286 @@
+import { GroupModel } from "../models/group-model";
+import { OptionModel } from "../models/option-model";
+import { Adapter } from "./base/adapter";
+
+/**
+ * @template {ModelContract<any, any>} TModel
+ * @template {Adapter} TAdapter
+ */
+export class ModelManager {
+    /** @type {Array<GroupModel|OptionModel>} */
+    #privModelList = [];
+
+    /** @type {new (...args: any[]) => TAdapter} */
+    #privAdapter;
+
+    /** @type {TAdapter} */
+    #privAdapterHandle;
+
+    /** @type {new (...args: any[]) => RecyclerViewContract<TAdapter>} */
+    #privRecyclerView;
+
+    /** @type {RecyclerViewContract<TAdapter>} */
+    #privRecyclerViewHandle;
+
+    options = null;
+    
+    /**
+     * Constructs a ModelManager with configuration options used by created models and components.
+     *
+     * @param {object} options - Configuration object passed to GroupModel/OptionModel and view infrastructure.
+     */
+    constructor(options) {
+        this.options = options;
+    }
+
+    /**
+     * Registers the adapter class to be used for rendering and managing models.
+     *
+     * @param {new (...args: any[]) => TAdapter} adapter - The adapter constructor (class) to instantiate.
+     */
+    setupAdapter(adapter) {
+        this.#privAdapter = adapter;
+    }
+
+    /**
+     * Registers the RecyclerView class responsible for hosting and updating item views.
+     *
+     * @param {new (...args: any[]) => RecyclerViewContract<TAdapter>} recyclerView - The recycler view constructor.
+     */
+    setupRecyclerView(recyclerView) {
+        this.#privRecyclerView = recyclerView;
+    }
+
+    /**
+     * Builds model instances (GroupModel/OptionModel) from raw <optgroup>/<option> elements.
+     * Preserves grouping relationships and returns the structured list.
+     *
+     * @param {Array<HTMLOptGroupElement|HTMLOptionElement>} modelData - Parsed DOM elements from the source <select>.
+     * @returns {Array<GroupModel|OptionModel>} - The ordered list of group and option models.
+     */
+    createModelResources(modelData) {
+        this.#privModelList = [];
+        let currentGroup = null;
+        
+        modelData.forEach(data => {
+            if (data.tagName === "OPTGROUP") {
+                currentGroup = new GroupModel(this.options, data);
+                this.#privModelList.push(currentGroup);
+            } 
+            else if (data.tagName === "OPTION") {
+                const optionModel = new OptionModel(this.options, /** @type {HTMLOptionElement} */ (data));
+                
+                if (data["__parentGroup"] && currentGroup && 
+                    data["__parentGroup"] === currentGroup.targetElement) {
+                    currentGroup.addItem(optionModel);
+                    optionModel.group = currentGroup;
+                } else {
+                    this.#privModelList.push(optionModel);
+                    currentGroup = null;
+                }
+            }
+        });
+
+        return this.#privModelList;
+    }
+
+    /**
+     * Replaces the current model list with new data and syncs it into the adapter,
+     * then refreshes the view to reflect changes.
+     *
+     * @param {Array<HTMLOptGroupElement|HTMLOptionElement>} modelData - New source elements to rebuild models from.
+     */
+    replace(modelData) {
+        this.createModelResources(modelData);
+
+        if (this.#privAdapterHandle) {
+            this.#privAdapterHandle.syncFromSource(this.#privModelList);
+        }
+
+        this.refresh();
+    }
+
+    /**
+     * Requests a view refresh if an adapter has been initialized,
+     * typically used after external updates to model data.
+     */
+    notify() {
+        if (!this.#privAdapterHandle) return;
+        
+        this.refresh();
+    }
+
+    /**
+     * Initializes adapter and recycler view instances, attaches them to a container element,
+     * and applies optional configuration overrides for adapter and recyclerView.
+     *
+     * @param {HTMLElement} viewElement - The container element where items will be rendered.
+     * @param {object} [adapterOpt={}] - Optional properties to merge into the adapter instance.
+     * @param {object} [recyclerViewOpt={}] - Optional properties to merge into the recycler view instance.
+     */
+    load(viewElement, adapterOpt = {}, recyclerViewOpt = {}) {
+        this.#privAdapterHandle = new this.#privAdapter(this.#privModelList);
+        Object.assign(this.#privAdapterHandle, adapterOpt);
+
+        this.#privRecyclerViewHandle = new this.#privRecyclerView(viewElement);
+        this.#privRecyclerViewHandle.setAdapter(this.#privAdapterHandle);
+        Object.assign(this.#privRecyclerViewHandle, recyclerViewOpt);
+    }
+
+    /**
+     * Diffs existing models against new <optgroup>/<option> data to update in place:
+     * reuses existing models when possible, updates positions and group membership,
+     * removes stale views, and notifies adapter and listeners about updates.
+     *
+     * @param {Array<HTMLOptGroupElement|HTMLOptionElement>} modelData - Fresh DOM elements reflecting the latest state.
+     */
+    update(modelData) {
+        const oldModels = this.#privModelList;
+        const newModels = [];
+        
+        const oldGroupMap = new Map();
+        const oldOptionMap = new Map();
+        
+        oldModels.forEach(model => {
+            if (model instanceof GroupModel) {
+                oldGroupMap.set(model.label, model);
+            } else if (model instanceof OptionModel) {
+                oldOptionMap.set(model.value, model);
+            }
+        });
+
+        let currentGroup = null;
+        let position = 0;
+
+        modelData.forEach((data, index) => {
+            if (data.tagName === "OPTGROUP") {
+                let dataVset = /** @type {HTMLOptGroupElement} */ (data);
+                const existingGroup = oldGroupMap.get(dataVset.label);
+                
+                if (existingGroup) {
+                    existingGroup.update(dataVset);
+                    existingGroup.position = position;
+                    existingGroup.items = [];
+                    currentGroup = existingGroup;
+                    newModels.push(existingGroup);
+                    oldGroupMap.delete(dataVset.label);
+                } else {
+                    currentGroup = new GroupModel(this.options, dataVset);
+                    currentGroup.position = position;
+                    newModels.push(currentGroup);
+                }
+                position++;
+            }
+            else if (data.tagName === "OPTION") {
+                let dataVset = /** @type {HTMLOptionElement} */ (data);
+                const existingOption = oldOptionMap.get(dataVset.value);
+                
+                if (existingOption) {
+                    existingOption.update(dataVset);
+                    existingOption.position = position;
+                    
+                    if (dataVset["__parentGroup"] && currentGroup) {
+                        currentGroup.addItem(existingOption);
+                        existingOption.group = currentGroup;
+                    } else {
+                        existingOption.group = null;
+                        newModels.push(existingOption);
+                    }
+                    
+                    oldOptionMap.delete(dataVset.value);
+                } else {
+                    const newOption = new OptionModel(this.options, dataVset);
+                    newOption.position = position;
+                    
+                    if (dataVset["__parentGroup"] && currentGroup) {
+                        currentGroup.addItem(newOption);
+                        newOption.group = currentGroup;
+                    } else {
+                        newModels.push(newOption);
+                    }
+                }
+                position++;
+            }
+        });
+
+        oldGroupMap.forEach(removedGroup => {
+            if (removedGroup.view) {
+                removedGroup.view.getView()?.remove();
+            }
+        });
+        
+        oldOptionMap.forEach(removedOption => {
+            if (removedOption.view) {
+                removedOption.view.getView()?.remove();
+            }
+        });
+
+        this.#privModelList = newModels;
+        
+        if (this.#privAdapterHandle) {
+            this.#privAdapterHandle.updateData(this.#privModelList);
+        }
+
+        this.onUpdated();
+        this.refresh();
+    }
+
+    /**
+     * Hook invoked after the manager completes an update or refresh cycle.
+     * Override to run side effects (e.g., layout adjustments or analytics).
+     */
+    onUpdated() { }
+
+    /**
+     * Instructs the adapter to temporarily skip event handling (e.g., during batch updates).
+     *
+     * @param {boolean} value - True to skip events; false to restore normal behavior.
+     */
+    skipEvent(value) {
+        this.#privAdapterHandle.isSkipEvent = value;
+    }
+
+    /**
+     * Re-renders the recycler view if present and invokes the post-refresh hook.
+     * No-op if the recycler view is not initialized.
+     */
+    refresh() {
+        if (!this.#privRecyclerViewHandle) return;
+        this.#privRecyclerViewHandle.refresh();
+        this.onUpdated();
+    }
+
+    /**
+     * Returns handles to the current resources, including the model list,
+     * adapter instance, and recycler view instance.
+     *
+     * @returns {{modelList: (GroupModel|OptionModel)[], adapter: TAdapter, recyclerView: RecyclerViewContract<TAdapter>}}
+     */
+    getResources() {
+        return {
+            modelList: this.#privModelList,
+            adapter: this.#privAdapterHandle,
+            recyclerView: this.#privRecyclerViewHandle
+        };
+    }
+
+    /**
+     * Triggers the adapter's pre-change pipeline for a named event,
+     * enabling observers to react before a change is applied.
+     *
+     * @param {string} event_name - The event or property name (e.g., "items", "select").
+     */
+    triggerChanging(event_name) {
+        this.#privAdapterHandle.changingProp(event_name);
+    }
+
+    /**
+     * Triggers the adapter's post-change pipeline for a named event,
+     * notifying observers after a change has been applied.
+     *
+     * @param {string} event_name - The event or property name (e.g., "items", "select").
+     */
+    triggerChanged(event_name) {
+        this.#privAdapterHandle.changeProp(event_name);
+    }
+}