selective-ui 1.0.2

package/src/js/services/effector.js

@@ -0,0 +1,404 @@
+/**
+ * @returns {EffectorInterface}
+ */
+export function Effector(query) {
+    return new class {
+        /**
+         * @type {HTMLElement}
+         */
+        element;
+        #timeOut = null;
+        #resizeTimeout = null;
+        #isAnimating = false;
+        
+        /**
+         * Provides an effector utility that controls animations and resizing for a target element.
+         * Supports setting the element by selector or node, canceling in-flight animations/timers,
+         * and exposes methods (expand, collapse, resize) via the returned object instance.
+         *
+         * @param {string|HTMLElement} [query] - A CSS selector or the target element to control.
+         */
+        constructor(query = null) {
+            if (query) {
+                this.setElement(query);
+            }
+        }
+
+        /**
+         * Sets the target element to be controlled by the effector.
+         * Accepts either a CSS selector or a direct HTMLElement reference.
+         *
+         * @param {string|HTMLElement} query - The element or selector to bind.
+         */
+        setElement(query) {
+            if (typeof query === "string") {
+                this.element = document.querySelector(query);
+            } else {
+                this.element = query;
+            }
+        }
+
+        /**
+         * Cancels any pending timeouts or resize triggers and resets the animation state.
+         * Use this to stop ongoing expand/collapse/resize animations immediately.
+         *
+         * @returns {this} - The effector instance for chaining.
+         */
+        cancel() {
+            if (this.#timeOut) {
+                clearTimeout(this.#timeOut);
+                this.#timeOut = null;
+            }
+            if (this.#resizeTimeout) {
+                clearTimeout(this.#resizeTimeout);
+                this.#resizeTimeout = null;
+            }
+            this.#isAnimating = false;
+            return this;
+        }
+
+        /**
+         * Get hidden dimensions
+         * @param {string} display 
+         * @returns {{width: number, height: number, scrollHeight: number}}
+         */
+        getHiddenDimensions(display = "flex") {
+            const originalStyles = {
+                display: this.element.style.display,
+                visibility: this.element.style.visibility,
+                position: this.element.style.position,
+                height: this.element.style.height,
+                width: this.element.style.width,
+            };
+
+            Object.assign(this.element.style, {
+                display: display,
+                visibility: "hidden",
+                position: "fixed",
+                height: "fit-content",
+                width: "fit-content"
+            });
+
+            const getComputedStyle = window.getComputedStyle(this.element);
+            const borderTopWidth = parseFloat(getComputedStyle.borderTopWidth);
+            const borderBottomWidth = parseFloat(getComputedStyle.borderBottomWidth);
+
+            const scrollHeight = this.element.scrollHeight + borderTopWidth + borderBottomWidth;
+
+            const rect = this.element.getBoundingClientRect();
+            
+            const dimensions = {
+                width: rect.width,
+                height: rect.height + borderTopWidth + borderBottomWidth,
+                scrollHeight: scrollHeight
+            };
+
+            Object.assign(this.element.style, originalStyles);
+
+            return dimensions;
+        }
+
+        /**
+         * Expand animation (open popup)
+         * @param {Object} config
+         * @param {number} config.duration - Animation duration in ms
+         * @param {string} config.display - Display type
+         * @param {number} config.width - Target width
+         * @param {number} config.left - Left position
+         * @param {number} config.top - Top position
+         * @param {number} config.maxHeight - Max height
+         * @param {number} config.realHeight - Real height
+         * @param {string} config.position - Position type (top/bottom)
+         * @param {Function} config.onComplete - Callback when complete
+         * @returns {this}
+         */
+        expand(config) {
+            this.cancel();
+            this.#isAnimating = true;
+
+            const {
+                duration = 200,
+                display = "flex",
+                width,
+                left,
+                top,
+                maxHeight,
+                realHeight,
+                position = "bottom",
+                onComplete
+            } = config;
+
+            const initialTop = position === "bottom" 
+                ? top 
+                : top + realHeight;
+
+            Object.assign(this.element.style, {
+                display: display,
+                width: `${width}px`,
+                left: `${left}px`,
+                top: `${initialTop}px`,
+                maxHeight: `${maxHeight}px`,
+                height: "0px",
+                opacity: "0",
+                overflow: "hidden",
+                transition: "none"
+            });
+
+            this.element.classList.toggle("position-top", position === "top");
+            this.element.classList.toggle("position-bottom", position === "bottom");
+
+            requestAnimationFrame(() => {
+                const isScrollable = realHeight >= maxHeight;
+                
+                Object.assign(this.element.style, {
+                    transition: `top ${duration}ms, height ${duration}ms, opacity ${duration}ms`,
+                    top: `${top}px`,
+                    height: `${realHeight}px`,
+                    opacity: "1",
+                    overflow: isScrollable ? "auto" : "hidden"
+                });
+
+                this.#timeOut = setTimeout(() => {
+                    this.element.style.transition = "none";
+                    this.#isAnimating = false;
+                    onComplete && onComplete();
+                }, duration);
+            });
+
+            return this;
+        }
+
+        /**
+         * Collapse animation (close popup)
+         * @param {Object} config
+         * @param {number} config.duration - Animation duration in ms
+         * @param {Function} config.onComplete - Callback when complete
+         * @returns {this}
+         */
+        collapse(config) {
+            this.cancel();
+            this.#isAnimating = true;
+
+            const {
+                duration = 200,
+                onComplete
+            } = config;
+
+            const currentHeight = this.element.offsetHeight;
+            const currentTop = this.element.offsetTop;
+            const position = this.element.classList.contains("position-top") ? "top" : "bottom";
+            const isScrollable = (this.element.scrollHeight - this.element.offsetHeight) > 0;
+
+            const finalTop = position === "top" 
+                ? currentTop + currentHeight
+                : currentTop;
+
+            requestAnimationFrame(() => {
+                Object.assign(this.element.style, {
+                    transition: `height ${duration}ms, top ${duration}ms, opacity ${duration}ms`,
+                    height: "0px",
+                    top: `${finalTop}px`,
+                    opacity: "0",
+                    overflow: isScrollable ? "auto" : "hidden"
+                });
+
+                this.#timeOut = setTimeout(() => {
+                    Object.assign(this.element.style, {
+                        display: "none",
+                        transition: "none"
+                    });
+                    this.#isAnimating = false;
+                    onComplete && onComplete();
+                }, duration);
+            });
+
+            return this;
+        }
+
+        /**
+         * show Swipe animation (close element)
+         * @param {Object} config
+         * @param {number} config.duration - Animation duration in ms
+         * @param {String} config.display - Display for element
+         * @param {Function} config.onComplete - Callback when complete
+         * @returns {this}
+         */
+        showSwipeWidth(config) {
+            this.cancel();
+            this.#isAnimating = true;
+
+            const {
+                duration = 200,
+                display = "block",
+                onComplete
+            } = config;
+
+            Object.assign(this.element.style, {
+                transition: "none",
+                display: display,
+                width: "fit-content"
+            });
+
+            const maxWidth = this.getHiddenDimensions(display).width;
+            
+            Object.assign(this.element.style, {
+                width: "0px"
+            });
+
+            requestAnimationFrame(() => {
+                Object.assign(this.element.style, {
+                    transition: `width ${duration}ms`,
+                    width: `${maxWidth}px`,
+                    overflow: "hidden"
+                });
+            });
+
+            this.#timeOut = setTimeout(() => {
+                Object.assign(this.element.style, {
+                    width: null,
+                    overflow: null,
+                    transition: null
+                });
+                this.#isAnimating = false;
+                onComplete && onComplete();
+            }, duration);
+
+            return this;
+        }
+
+        /**
+         * hide Swipe animation (close element)
+         * @param {Object} config
+         * @param {number} config.duration - Animation duration in ms
+         * @param {Function} config.onComplete - Callback when complete
+         * @returns {this}
+         */
+        hideSwipeWidth(config) {
+            this.cancel();
+            this.#isAnimating = true;
+
+            const {
+                duration = 200,
+                onComplete
+            } = config;
+
+            const maxWidth = this.getHiddenDimensions().width;
+
+            Object.assign(this.element.style, {
+                transition: "none",
+                width: `${maxWidth}px`
+            });
+
+            requestAnimationFrame(() => {
+                Object.assign(this.element.style, {
+                    transition: `width ${duration}ms`,
+                    width: `0px`,
+                    overflow: "hidden"
+                });
+            });
+
+            this.#timeOut = setTimeout(() => {
+                Object.assign(this.element.style, {
+                    width: null,
+                    overflow: null,
+                    transition: null,
+                    display: null
+                });
+                this.#isAnimating = false;
+                onComplete && onComplete();
+            }, duration);
+
+            return this;
+        }
+
+        /**
+         * Resize animation (when content changes)
+         * @param {Object} config
+         * @param {number} config.duration - Animation duration in ms
+         * @param {number} config.width - Target width
+         * @param {number} config.left - Left position
+         * @param {number} config.top - Top position
+         * @param {number} config.maxHeight - Max height
+         * @param {number} config.realHeight - Real height
+         * @param {string} config.position - Position type (top/bottom)
+         * @param {boolean} config.animate - Whether to animate
+         * @param {Function} config.onComplete - Callback when complete
+         * @returns {this}
+         */
+        resize(config) {
+            if (this.#resizeTimeout) {
+                clearTimeout(this.#resizeTimeout);
+            }
+
+            const {
+                duration = 200,
+                width,
+                left,
+                top,
+                maxHeight,
+                realHeight,
+                position = "bottom",
+                animate = true,
+                onComplete
+            } = config;
+
+            const currentPosition = this.element.classList.contains("position-top") ? "top" : "bottom";
+            const isPositionChanged = currentPosition !== position;
+            const isScrollable = this.element.scrollHeight > maxHeight;
+
+            this.element.classList.toggle("position-top", position === "top");
+            this.element.classList.toggle("position-bottom", position === "bottom");
+            
+            if (isPositionChanged) {
+                this.element.style.transition = `top ${duration}ms ease-out, height ${duration}ms ease-out, max-height ${duration}ms ease-out;`;
+            }
+
+            requestAnimationFrame(() => {
+                const curTop = this.element.offsetTop;
+                const styles = {
+                    width: `${width}px`,
+                    left: `${left}px`,
+                    top: `${top}px`,
+                    maxHeight: `${maxHeight}px`,
+                    height: `${realHeight}px`,
+                    overflowY: isScrollable ? "auto" : "hidden"
+                };
+
+                if (animate && (isPositionChanged || Math.abs(this.element.offsetHeight - realHeight) > 5) ) {
+                    styles.transition = `height ${duration}ms, top ${duration}ms`;
+                } else {
+                    this.#resizeTimeout = setTimeout(() => {
+                        this.element.style.transition = "none";
+                    }, duration);
+                }
+
+                Object.assign(this.element.style, styles);
+
+                if (animate && (isPositionChanged || Math.abs(this.element.offsetHeight - realHeight) > 1)) {
+                    this.#resizeTimeout = setTimeout(() => {
+                        this.element.style.transition = "none";
+                        if (isPositionChanged) {
+                            delete this.element.style.transition;
+                        }
+                        onComplete && onComplete();
+                    }, duration);
+                } else {
+                    if (isPositionChanged) {
+                        delete this.element.style.transition;
+                    }
+                    onComplete && onComplete();
+                }
+            });
+
+            return this;
+        }
+
+        /**
+         * Check if currently animating
+         * @returns {boolean}
+         */
+        get isAnimating() {
+            return this.#isAnimating;
+        }
+    }(query);
+}

package/src/js/services/refresher.js

@@ -0,0 +1,40 @@
+import {Libs} from "../utils/libs.js";
+
+/**
+ * @class
+ */
+export class Refresher {
+    /**
+     * Provides a utility to resize the Select UI view panel based on the bound <select> element
+     * and configuration options. Applies explicit width/height if configured; otherwise uses the
+     * select's current offset size. Ensures minimum width/height constraints are respected.
+     *
+     * @param {HTMLSelectElement} select - The native select element used to derive dimensions.
+     * @param {HTMLElement} view - The view panel element whose styles will be updated.
+     */
+    static resizeBox(select, view) {
+        const 
+            bindedMap = Libs.getBinderMap(select),
+            options = bindedMap.options
+        ;
+        
+        const 
+            minWidth = options.minWidth,
+            minHeight = options.minHeight,
+            cfgWidth = parseInt(options.width, 10),
+            cfgHeight = parseInt(options.height, 10)
+        ;
+        
+        let width = `${select.offsetWidth}px`,
+            height = `${select.offsetHeight}px`;
+        
+        if (cfgWidth > 0) {
+            width = options.width;
+        }
+        if (cfgHeight > 0) {
+            height = options.height;
+        }
+
+        Libs.setStyle(view, {width, height, minWidth, minHeight});
+    }
+}

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

@@ -0,0 +1,152 @@
+
+/**
+ * @class
+ */
+export class ResizeObserverService {
+    isInit = false;
+    element = null;
+    /** @type {ResizeObserver} */
+    #resizeObserver = null;
+    #mutationObserver = null;
+    #boundUpdateChanged;
+    
+    /**
+     * Initializes the service and binds the internal update handler to `this`.
+     * Sets the service to an initialized state.
+     */
+    constructor() {
+        this.isInit = true
+        this.#boundUpdateChanged = this.#updateChanged.bind(this);
+    }
+
+    /**
+     * Callback invoked when the observed element's metrics change.
+     * Override to react to size/position/style updates.
+     *
+     * @param {ElementMetrics} metrics - Calculated box metrics (size, position, padding, border, margin).
+     */
+    onChanged(metrics) {}
+
+    /**
+     * Computes the current metrics of the bound element (bounding rect + computed styles)
+     * and forwards them to `onChanged(metrics)`.
+     *
+     * @returns {void}
+     */
+    #updateChanged() {
+        // Guard: nếu element chưa sẵn sàng hoặc không đo được, trả về metrics mặc định
+        const el = this.element;
+        if (!el || typeof el.getBoundingClientRect !== 'function') {
+            /** @type {ElementMetrics} */
+            const defaultMetrics = {
+                width: 0,
+                height: 0,
+                top: 0,
+                left: 0,
+                padding: { top: 0, right: 0, bottom: 0, left: 0 },
+                border:  { top: 0, right: 0, bottom: 0, left: 0 },
+                margin:  { top: 0, right: 0, bottom: 0, left: 0 },
+            };
+            this.onChanged(defaultMetrics);
+            return;
+        }
+
+        const rect = el.getBoundingClientRect();
+        const style = (typeof window?.getComputedStyle === 'function')
+            ? window.getComputedStyle(el)
+            : null;
+
+        /** @type {ElementMetrics} */
+        const metrics = {
+            width: rect?.width ?? 0,
+            height: rect?.height ?? 0,
+            top: rect?.top ?? 0,
+            left: rect?.left ?? 0,
+
+            padding: {
+                top: parseFloat(style?.paddingTop ?? '0'),
+                right: parseFloat(style?.paddingRight ?? '0'),
+                bottom: parseFloat(style?.paddingBottom ?? '0'),
+                left: parseFloat(style?.paddingLeft ?? '0'),
+            },
+
+            border: {
+                top: parseFloat(style?.borderTopWidth ?? '0'),
+                right: parseFloat(style?.borderRightWidth ?? '0'),
+                bottom: parseFloat(style?.borderBottomWidth ?? '0'),
+                left: parseFloat(style?.borderLeftWidth ?? '0'),
+            },
+
+            margin: {
+                top: parseFloat(style?.marginTop ?? '0'),
+                right: parseFloat(style?.marginRight ?? '0'),
+                bottom: parseFloat(style?.marginBottom ?? '0'),
+                left: parseFloat(style?.marginLeft ?? '0'),
+            }
+        };
+        
+        this.onChanged(metrics);
+    }
+    
+    /**
+     * Manually triggers a metrics computation and notification via `onChanged`.
+     */
+    trigger() {
+        this.#updateChanged();
+    }
+    
+    /**
+     * Starts observing the provided element for resize and style/class mutations,
+     * and listens to window/visualViewport scroll/resize to detect layout changes.
+     *
+     * @param {Element} element - The element to observe; must be a valid DOM Element.
+     * @throws {Error} If `element` is not an instance of Element.
+     */
+    connect(element) {
+        if (!(element instanceof Element)) {
+            throw new Error("Element không hợp lệ");
+        }
+
+        this.element = element;
+
+        this.#resizeObserver = new ResizeObserver(this.#boundUpdateChanged);
+        this.#resizeObserver.observe(element);
+
+        this.#mutationObserver = new MutationObserver(this.#boundUpdateChanged);
+        this.#mutationObserver.observe(element, {
+            attributes: true,
+            attributeFilter: ["style", "class"]
+        });
+
+        window.addEventListener("scroll", this.#boundUpdateChanged, true);
+        window.addEventListener("resize", this.#boundUpdateChanged);
+
+        if (window.visualViewport) {
+            window.visualViewport.addEventListener("resize", this.#boundUpdateChanged);
+            window.visualViewport.addEventListener("scroll", this.#boundUpdateChanged);
+        }
+    }
+    
+    /**
+     * Stops all observations and event listeners, resets the change handler,
+     * and releases internal observer resources.
+     */
+    disconnect() {
+        // Optional chaining để an toàn với mocks trong môi trường test
+        this.#resizeObserver?.disconnect?.();
+        this.#mutationObserver?.disconnect?.();
+
+        this.onChanged = (metrics) => {};
+        window.removeEventListener("scroll", this.#boundUpdateChanged, true);
+        window.removeEventListener("resize", this.#boundUpdateChanged);
+
+        if (window.visualViewport) {
+            window.visualViewport.removeEventListener("resize", this.#boundUpdateChanged);
+            window.visualViewport.removeEventListener("scroll", this.#boundUpdateChanged);
+        }
+
+        this.#resizeObserver = null;
+        this.#mutationObserver = null;
+        this.element = null;
+    }
+}

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

@@ -0,0 +1,61 @@
+export class SelectObserver {
+    /** @type {MutationObserver} */
+    #observer;
+
+    /** @type {HTMLSelectElement} */
+    #select;
+
+    #debounceTimer = null;
+
+    /**
+     * 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.
+     *
+     * @param {HTMLSelectElement} select - The <select> element to monitor.
+     */
+    constructor(select) {
+        this.#observer = new MutationObserver(() => {
+            clearTimeout(this.#debounceTimer);
+            this.#debounceTimer = setTimeout(() => {
+                this.onChanged(select);
+            }, 50);
+        });
+
+        this.#select = select;
+
+        select.addEventListener("options:changed", () => {
+            this.onChanged(select);
+        });
+    }
+
+    /**
+     * Starts observing the select element for child list mutations and attribute changes.
+     * Uses a MutationObserver with a debounce to batch rapid updates.
+     */
+    connect() {
+        this.#observer.observe(this.#select, {
+            childList: true,
+            subtree: false,
+
+            attributes: true,
+            attributeFilter: ["selected", "value", "disabled"]
+        });
+    }
+
+    /**
+     * Hook invoked when the select's options or attributes change.
+     * Override to handle updates; receives the current HTMLCollection of options.
+     *
+     * @param {HTMLSelectElement} options - The Select element.
+     */
+    onChanged(options) { }
+
+    /**
+     * Stops observing the select element and clears any pending debounce timers.
+     */
+    disconnect() {
+        clearTimeout(this.#debounceTimer);
+        this.#observer.disconnect();
+    }
+}

package/src/js/types/adapter.type.js

@@ -0,0 +1,33 @@
+
+/**
+ * @template {ModelContract<any, any>} TItem
+ * @typedef {Object} AdapterContract
+ *
+ * @property {TItem[]} items - List of items managed by the adapter.
+ * @property {string} adapterKey - Unique key identifier for the adapter.
+ *
+ * @property {(items: TItem[]) => void} setItems - Replace or update the list of items.
+ * @property {(items: TItem[]) => void} syncFromSource - Synchronize items from an external source.
+ * @property {() => number} itemCount - Get the number of items.
+ *
+ * @property {(parent: HTMLElement, item: TItem) => any} viewHolder
+ *           - Create a viewer for the given item inside the parent container.
+ *
+ * @property {(item: TItem, viewer: any, position: number) => void} onViewHolder
+ *           - Bind an item to its viewer at the specified position (render if not initialized, otherwise update).
+ *
+ * @property {(propName: string, callback: Function) => void} onPropChanging
+ *           - Register a pre-change callback for a property.
+ * @property {(propName: string, callback: Function) => void} onPropChanged
+ *           - Register a post-change callback for a property.
+ * @property {(propName: string, ...params: any[]) => void} changeProp
+ *           - Trigger the post-change pipeline for a property.
+ * @property {(propName: string, ...params: any[]) => void} changingProp
+ *           - Trigger the pre-change pipeline for a property.
+ *
+ * @property {(parent: HTMLElement) => void} updateRecyclerView
+ *           - Ensure all items have viewers and bind them into the recycler container.
+ *
+ * @property {(items: TItem[]) => void} updateData
+ *           - Update adapter data (override in subclasses for custom behavior).
+ */