selective-ui 1.2.2 → 1.2.4

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

@@ -16,7 +16,7 @@ export class SelectObserver {
 
     /**
      * Initializes the SelectObserver for a given <select> element.
-     * Captures the initial snapshot, sets up a MutationObserver, and listens for custom "options:changed" events.
+     * Captures the initial snapshot, sets up a MutationObserver.
      * Changes are debounced to prevent excessive calls.
      *
      * @param {HTMLSelectElement} select - The <select> element to observe.
@@ -31,13 +31,6 @@ export class SelectObserver {
                 this.handleChange();
             }, this._DEBOUNCE_DELAY);
         });
-
-        select.addEventListener("options:changed", () => {
-            if (this.debounceTimer) clearTimeout(this.debounceTimer);
-            this.debounceTimer = setTimeout(() => {
-                this.handleChange();
-            }, this._DEBOUNCE_DELAY);
-        });
     }
 
     /**

package/src/ts/types/components/searchbox.type.ts

@@ -2,7 +2,7 @@ import { PlaceHolder } from "src/ts/components/placeholder";
 import { MountViewResult } from "../utils/libs.type";
 import { Directive } from "src/ts/components/directive";
 import { SearchBox } from "src/ts/components/searchbox";
-import { Popup } from "src/ts/components/popup";
+import { Popup } from "src/ts/components/popup/popup";
 import { EffectorInterface } from "../services/effector.type";
 import { AccessoryBox } from "src/ts/components/accessorybox";
 import { SearchController } from "src/ts/core/search-controller";

package/src/ts/types/core/base/adapter.type.ts

@@ -1,3 +1,4 @@
+import { Lifecycle } from "src/ts/core/base/lifecycle";
 import type { ModelContract } from "./model.type";
 
 /**
@@ -5,7 +6,7 @@ import type { ModelContract } from "./model.type";
  *
  * @template TItem - A model type that implements ModelContract.
  */
-export interface AdapterContract<TItem extends ModelContract<any, any>> {
+export interface AdapterContract<TItem extends ModelContract<any, any>> extends Lifecycle {
     /**
      * List of items managed by the adapter.
      * These items are rendered or updated in the associated container.

package/src/ts/types/core/base/lifecycle.type.ts

@@ -0,0 +1,62 @@
+
+/**
+ * Enumerates the finite lifecycle states used across core classes (e.g., View/Model).
+ *
+ * State flow (happy path):
+ * NEW → INITIALIZED → MOUNTED → UPDATED → DESTROYED
+ *
+ * Notes:
+ * - `UPDATED` may be emitted multiple times after mount, depending on implementation.
+ * - `DESTROYED` is terminal; no further transitions should occur.
+ */
+export enum LifecycleState {
+    /** The instance has been created but not initialized. */
+    NEW = "new",
+
+    /** Initialization logic has completed; ready to be mounted. */
+    INITIALIZED = "initialized",
+
+    /** The instance is mounted/attached to its environment (e.g., DOM). */
+    MOUNTED = "mounted",
+
+    /**
+     * The instance has been updated at least once after being mounted.
+     * Further updates typically keep the state at UPDATED.
+     */
+    UPDATED = "updated",
+
+    /** Teardown has run; resources/hooks have been released. */
+    DESTROYED = "destroyed",
+}
+
+/**
+ * Optional callbacks for lifecycle events.
+ *
+ * Implementers can subscribe to these hooks either by:
+ * - passing these functions to a contract that consumes `LifecycleHooks`, or
+ * - using the `Lifecycle.on(hook, fn)` API at runtime.
+ *
+ * Each callback is executed without arguments and should be side-effect free
+ * except for logic relevant to the lifecycle step.
+ */
+export interface LifecycleHooks {
+    /** Invoked when transitioning from `NEW` → `INITIALIZED`. */
+    onInit?(): void;
+
+    /** Invoked when transitioning from `INITIALIZED` → `MOUNTED`. */
+    onMount?(): void;
+
+    /**
+     * Invoked when transitioning to `UPDATED`.
+     * May be emitted multiple times after the instance is mounted.
+     */
+    onUpdate?(): void;
+
+    /** Invoked when transitioning to `DESTROYED`. Should be idempotent. */
+    onDestroy?(): void;
+}
+
+export type LifecycleHookContext = {
+    state: LifecycleState;
+    prevState: LifecycleState;
+};

package/src/ts/types/core/base/model.type.ts

@@ -1,10 +1,12 @@
+import { Lifecycle } from "src/ts/core/base/lifecycle";
+
 /**
  * Generic model contract for binding a target element and an optional view.
  *
  * @template TTarget - The type of the target element (e.g., DOM element, data object).
  * @template TView - The type of the view associated with the target (e.g., UI component).
  */
-export interface ModelContract<TTarget, TView> {
+export interface ModelContract<TTarget, TView> extends Lifecycle {
     /**
      * The target element that this model is bound to.
      * Can be null if not yet initialized.

package/src/ts/types/core/base/recyclerview.type.ts

@@ -1,3 +1,4 @@
+import { Lifecycle } from "src/ts/core/base/lifecycle";
 import { AdapterContract } from "./adapter.type";
 
 /**
@@ -5,7 +6,7 @@ import { AdapterContract } from "./adapter.type";
  *
  * @template TAdapter - A concrete adapter type that implements AdapterContract.
  */
-export interface RecyclerViewContract<TAdapter extends AdapterContract<any>> {
+export interface RecyclerViewContract<TAdapter extends AdapterContract<any>> extends Lifecycle {
     /**
      * The container element that hosts all item views.
      * Can be null until `setView` is called.
@@ -18,13 +19,6 @@ export interface RecyclerViewContract<TAdapter extends AdapterContract<any>> {
      */
     adapter: TAdapter | null;
 
-    /**
-     * Set or replace the container element used for rendering.
-     *
-     * @param viewElement - The root container element for the recycler view.
-     */
-    setView(viewElement: HTMLElement): void;
-
     /**
      * Attach an adapter and refresh the view accordingly.
      * Implementations typically call `render()` or reconcile the DOM.

package/src/ts/types/core/base/view.type.ts

@@ -1,43 +1,55 @@
+
+import { Lifecycle } from "src/ts/core/base/lifecycle";
 import { MountViewResult } from "../../utils/libs.type";
 
 /**
- * Contract for a UI view created via `mountView`/`mountNode`.
- * Encapsulates the mounted view, its parent, and helper accessors.
+ * Contract definition for a UI View created via `mountView` or `mountNode`.
+ *
+ * A View encapsulates:
+ * - The mounted DOM structure
+ * - The root element
+ * - A strongly-typed map of named child elements
+ * - Lifecycle management hooks
  *
  * @template TTags - A map of tag names to their corresponding HTMLElement instances.
- *                   Example: `{ Root: HTMLDivElement, Button: HTMLButtonElement }`
+ * Example:
+ * ```ts
+ * {
+ *   Root: HTMLDivElement;
+ *   Button: HTMLButtonElement;
+ * }
+ * ```
  */
-export interface ViewContract<TTags extends Record<string, HTMLElement>> {
+export interface ViewContract<TTags extends Record<string, HTMLElement>> extends Lifecycle {
+
     /**
-     * The parent container into which the view is mounted.
-     * Can be null before the view is attached.
+     * The parent DOM element into which the view is mounted.
+     *
+     * This value is:
+     * - `null` before the view is mounted
+     * - Set once the view is attached to the DOM
      */
     parent: HTMLElement | null;
 
     /**
-     * The result returned by mountView/mountNode, including the root element
-     * and the tag map used to retrieve specific nodes.
-     * Can be null if the view has not been mounted yet.
+     * Internal representation of the mounted view returned by `mountView` or `mountNode`.
+     *
+     * Contains:
+     * - The root element of the view
+     * - A strongly-typed tag map for querying child elements
+     *
+     * Will be `null` if the view has not been mounted yet.
      */
     view: MountViewResult<TTags> | null;
 
     /**
-     * Render or re-render the view.
-     * Implementations typically (re)build DOM, bind events, and update state.
-     */
-    render(): void;
-
-    /**
-     * Update the view.
-     * Implementations typically refresh displayed data without a full re-render.
-     */
-    update(): void;
-
-    /**
-     * Get the root HTMLElement for the mounted view.
+     * Returns the root HTMLElement of the mounted view.
+     *
+     * This is typically the top-level container element
+     * created by `mountView` / `mountNode`.
      *
-     * @returns The root element produced by mountView/mountNode.
-     * @throws If the view is not initialized.
+     * @returns The root HTMLElement of the view.
+     * @throws {Error} If the view has not been mounted or initialized.
      */
     getView(): HTMLElement;
 }

package/src/ts/utils/callback-scheduler.ts

@@ -84,12 +84,18 @@ export class CallbackScheduler {
      * - If an entry has `once = true`, it is removed after execution by setting its slot to `undefined`.
      *   (The list is not spliced to preserve indices.)
      */
-    public run(key: TimerKey, ...params: any[]): void {
+    public run(key: TimerKey, ...params: any[]): Promise<void> | void {
         const executes = this.executeStored.get(key);
-        if (!executes) return;
+        if (!executes || executes.length === 0) {
+            return Promise.resolve();
+        }
+
+        if (!this.timerRunner.has(key)) {
+            this.timerRunner.set(key, new Map());
+        }
 
-        if (!this.timerRunner.has(key)) this.timerRunner.set(key, new Map());
         const runner = this.timerRunner.get(key)!;
+        const tasks: Promise<void>[] = [];
 
         for (let i = 0; i < executes.length; i++) {
             const entry = executes[i];
@@ -98,22 +104,36 @@ export class CallbackScheduler {
             const prev = runner.get(i);
             if (prev) clearTimeout(prev);
 
-            const timer = setTimeout(() => {
-                entry.callback(params.length > 0 ? params : null);
-
-                if (entry.once) {
-                    // Preserve index stability by leaving an empty slot.
-                    executes[i] = undefined;
-
-                    // Cleanup the timer handle for this index.
-                    const current = runner.get(i);
-                    if (current) clearTimeout(current);
-                    runner.delete(i);
-                }
-            }, entry.timeout);
-
-            runner.set(i, timer);
+            const task = new Promise<void>((resolve) => {
+                const timer = setTimeout(async () => {
+                    try {
+                        const resp = entry.callback(
+                            params.length > 0 ? params : null
+                        ) as any;
+
+                        if (resp instanceof Promise) {
+                            await resp;
+                        }
+                    } catch {} finally {
+                        if (entry.once) {
+                            executes[i] = undefined;
+
+                            const current = runner.get(i);
+                            if (current) clearTimeout(current);
+                            runner.delete(i);
+                        }
+
+                        resolve();
+                    }
+                }, entry.timeout);
+
+                runner.set(i, timer);
+            });
+
+            tasks.push(task);
         }
+
+        return Promise.all(tasks).then(() => void 0);
     }
 
     /**

package/src/ts/utils/istorage.ts

@@ -38,7 +38,7 @@ export class iStorage {
         textAccessoryDeselect: "Deselect: ",
         animationtime: 200, // millisecond
         delaysearchtime: 200, // millisecond
-        allowHtml: true,
+        allowHtml: false,
         maxSelected: 0,
         labelHalign: "left",
         labelValign: "center",

package/src/ts/utils/selective.ts

@@ -4,13 +4,31 @@ import { SelectBox } from "../components/selectbox";
 import { ElementAdditionObserver } from "../services/ea-observer";
 import { SelectiveActionApi, SelectiveOptions } from "../types/utils/selective.type";
 import { BinderMap, PropertiesType } from "../types/utils/istorage.type";
-import { Popup } from "../components/popup";
+import { Lifecycle } from "../core/base/lifecycle";
+import { LifecycleState } from "../types/core/base/lifecycle.type";
 
-export class Selective {
+export class Selective extends Lifecycle {
     private EAObserver: ElementAdditionObserver;
 
     private bindedQueries: Map<string, SelectiveOptions> = new Map();
 
+    constructor() {
+        super();
+        this.init();
+    }
+
+    /**
+     * Override lifecycle init - Initialize Selective system
+     */
+    public init(): void {
+        if (!this.is(LifecycleState.NEW)) return;
+
+        // Initialize core properties
+        this.bindedQueries = new Map();
+
+        super.init();
+    }
+
     /**
      * Binds Selective UI to all <select> elements matching the query.
      * Merges provided options with defaults, schedules `on.load` callbacks,
@@ -20,27 +38,40 @@ export class Selective {
      * @param {object} options - Configuration overrides merged with defaults.
      */
     public bind(query: string, options: SelectiveOptions): void {
-        const merged = Libs.mergeConfig(Libs.getDefaultConfig(), options) as SelectiveOptions;
+        // Auto-init if not initialized
+        if (this.is(LifecycleState.NEW)) {
+            this.init();
+        }
+
+        const merged = Libs.mergeConfig(
+            Libs.getDefaultConfig(),
+            options,
+        ) as SelectiveOptions;
 
         // Ensure hooks exist
         merged.on = merged.on ?? {};
-        merged.on.load = (merged.on.load ?? []) as Array<(...args: any[]) => void>;
+        merged.on.load = (merged.on.load ?? []) as Array<
+            (...args: any[]) => void
+        >;
 
         this.bindedQueries.set(query, merged);
 
         const doneToken = Libs.randomString();
         Libs.callbackScheduler.on(doneToken, () => {
-            iEvents.callEvent([this.find(query)], ...(merged.on!.load));
+            iEvents.callEvent([this.find(query)], ...merged.on!.load);
             Libs.callbackScheduler.clear(doneToken);
             merged.on!.load = [];
         });
 
         const selectElements = Libs.getElements(query) as HTMLSelectElement[];
+        let hasAnyBound = false;
+
         selectElements.forEach((item) => {
             (async () => {
                 if (item.tagName === "SELECT") {
                     Libs.removeUnbinderMap(item);
                     if (this.applySelectBox(item, merged)) {
+                        hasAnyBound = true;
                         Libs.callbackScheduler.run(doneToken);
                     }
                 }
@@ -50,6 +81,34 @@ export class Selective {
         if (!Libs.getBindedCommand().includes(query)) {
             Libs.getBindedCommand().push(query);
         }
+
+        // Mount if first bind and has elements
+        if (this.is(LifecycleState.INITIALIZED) && hasAnyBound) {
+            this.mount();
+        }
+
+        // Trigger update if already mounted
+        if (this.is(LifecycleState.MOUNTED)) {
+            this.update();
+        }
+    }
+
+    /**
+     * Override lifecycle mount - System is ready and has bound elements
+     */
+    public mount(): void {
+        if (this.state !== LifecycleState.INITIALIZED) return;
+
+        super.mount();
+    }
+
+    /**
+     * Override lifecycle update - Called when bindings change
+     */
+    public update(): void {
+        if (this.state !== LifecycleState.MOUNTED) return;
+
+        super.update();
     }
 
     /**
@@ -101,19 +160,27 @@ export class Selective {
      * Selective bindings automatically when they match previously bound queries.
      */
     public Observer(): void {
-        this.EAObserver = new ElementAdditionObserver();
-        this.EAObserver.onDetect((selectElement: HTMLSelectElement) => {
-            this.bindedQueries.forEach((options, query) => {
-                try {
-                    if (selectElement.matches(query)) {
-                        this.applySelectBox(selectElement, options);
+        if (!this.EAObserver) {
+            this.EAObserver = new ElementAdditionObserver();
+            this.EAObserver.onDetect((selectElement: HTMLSelectElement) => {
+                this.bindedQueries.forEach((options, query) => {
+                    try {
+                        if (selectElement.matches(query)) {
+                            this.applySelectBox(selectElement, options);
+
+                            // Trigger update when new element is bound
+                            if (this.is(LifecycleState.MOUNTED)) {
+                                this.update();
+                            }
+                        }
+                    } catch (error) {
+                        console.warn(`Invalid selector: ${query}`, error);
                     }
-                } catch (error) {
-                    console.warn(`Invalid selector: ${query}`, error);
-                }
+                });
             });
-        });
-        this.EAObserver.start("select");
+        }
+
+        this.EAObserver.connect("select");
     }
 
     /**
@@ -132,19 +199,30 @@ export class Selective {
         } else if (target instanceof HTMLSelectElement) {
             this.destroyElement(target);
         }
+
+        // Trigger update after partial destroy
+        if (target !== null && this.is(LifecycleState.MOUNTED)) {
+            this.update();
+        }
     }
 
     /**
      * Destroys all bound Selective instances and clears bindings/state.
      * Stops the ElementAdditionObserver.
+     * Calls lifecycle destroy.
      */
     private destroyAll(): void {
+        if (this.state === LifecycleState.DESTROYED) return;
+
         const bindedCommands = Libs.getBindedCommand();
         bindedCommands.forEach((query: string) => this.destroyByQuery(query));
 
         this.bindedQueries.clear();
         Libs.getBindedCommand().length = 0;
-        this.EAObserver?.stop();
+        this.EAObserver?.disconnect();
+
+        // Call parent lifecycle destroy
+        super.destroy();
     }
 
     /**
@@ -176,20 +254,20 @@ export class Selective {
         const bindMap = Libs.getBinderMap(selectElement) as BinderMap | null;
         if (!bindMap) return;
 
-        const popup = bindMap.container?.popup as Popup | null;
-        popup?.detroy();
+        const selfBox = bindMap.self as SelectBox | null;
 
         Libs.setUnbinderMap(selectElement, bindMap);
 
         const wasObserving = !!this.EAObserver;
-        if (wasObserving) this.EAObserver?.stop();
+        if (wasObserving) this.EAObserver?.disconnect();
 
         try {
             bindMap.self?.deInit?.();
-        } catch (_) { }
+        } catch (_) {}
 
         const wrapper: HTMLElement | null =
-            (bindMap.container?.element as HTMLElement | undefined) ?? selectElement.parentElement;
+            (bindMap.container?.element as HTMLElement | undefined) ??
+            selectElement.parentElement;
 
         selectElement.style.display = "";
         selectElement.style.visibility = "";
@@ -199,14 +277,16 @@ export class Selective {
         if (wrapper && wrapper.parentNode) {
             wrapper.parentNode.replaceChild(selectElement, wrapper);
         } else {
-            document.body.appendChild(selectElement);
+            selectElement.appendChild(selectElement);
         }
 
         Libs.removeBinderMap(selectElement);
 
         if (wasObserving && this.bindedQueries.size > 0) {
-            this.EAObserver?.start("select");
+            this.EAObserver?.connect("select");
         }
+
+        selfBox?.destroy?.();
     }
 
     /**
@@ -219,6 +299,11 @@ export class Selective {
     public rebind(query: string, options: SelectiveOptions): void {
         this.destroyByQuery(query);
         this.bind(query, options);
+
+        // Trigger update after rebind
+        if (this.is(LifecycleState.MOUNTED)) {
+            this.update();
+        }
     }
 
     /**
@@ -230,13 +315,22 @@ export class Selective {
      * @param {object} options - Configuration used for this instance.
      * @returns {boolean} - False if already bound; true if successfully applied.
      */
-    private applySelectBox(selectElement: HTMLSelectElement, options: SelectiveOptions): boolean {
-        if (Libs.getBinderMap(selectElement) || Libs.getUnbinderMap(selectElement)) {
+    private applySelectBox(
+        selectElement: HTMLSelectElement,
+        options: SelectiveOptions,
+    ): boolean {
+        if (
+            Libs.getBinderMap(selectElement) ||
+            Libs.getUnbinderMap(selectElement)
+        ) {
             return false;
         }
 
         const SEID = Libs.randomString(8);
-        const options_cfg = Libs.buildConfig(selectElement, options) as SelectiveOptions;
+        const options_cfg = Libs.buildConfig(
+            selectElement,
+            options,
+        ) as SelectiveOptions;
 
         options_cfg.SEID = SEID;
         options_cfg.SEID_LIST = `seui-${SEID}-optionlist`;
@@ -245,15 +339,24 @@ export class Selective {
         const bindMap: BinderMap = { options: options_cfg };
         Libs.setBinderMap(selectElement, bindMap);
 
+        // Create SelectBox with lifecycle
         const selectBox = new SelectBox(selectElement, this);
+
+        selectBox.on("onMount", () => {
+            if (selectBox.container.view) {
+                selectBox.container.view.addEventListener("mouseup", () => {
+                    bindMap.action?.toggle?.();
+                });
+            }
+        });
+
+        // Mount the SelectBox
+        selectBox.mount();
+
         bindMap.container = selectBox.container;
         bindMap.action = selectBox.getAction();
         bindMap.self = selectBox;
 
-        selectBox.container.view.addEventListener("mouseup", () => {
-            bindMap.action?.toggle?.();
-        });
-
         return true;
     }
 
@@ -268,11 +371,17 @@ export class Selective {
      * @param {*} action - The object containing the property.
      * @returns {PropertiesType} - The derived property type and name.
      */
-    private getProperties(actionName: string, action: Record<string, any>): PropertiesType {
+    private getProperties(
+        actionName: string,
+        action: Record<string, any>,
+    ): PropertiesType {
         const descriptor = Object.getOwnPropertyDescriptor(action, actionName);
         let type: PropertiesType["type"] = "variable";
 
-        if (descriptor?.get || (descriptor?.set && typeof action[actionName] !== "function")) {
+        if (
+            descriptor?.get ||
+            (descriptor?.set && typeof action[actionName] !== "function")
+        ) {
             type = "get-set";
         } else if (typeof action[actionName] === "function") {
             type = "func";
@@ -289,7 +398,11 @@ export class Selective {
      * @param {string} name - The property name to expose.
      * @param {HTMLElement[]} els - The list of bound elements to proxy.
      */
-    private buildGetSetAction(object: Record<string, any>, name: string, els: HTMLElement[]): void {
+    private buildGetSetAction(
+        object: Record<string, any>,
+        name: string,
+        els: HTMLElement[],
+    ): void {
         Object.defineProperty(object, name, {
             get() {
                 const binded = Libs.getBinderMap(els[0]) as BinderMap;
@@ -315,7 +428,11 @@ export class Selective {
      * @param {string} name - The function name to expose.
      * @param {HTMLElement[]} els - The list of bound elements to invoke against.
      */
-    private buildFuntionAction(object: Record<string, any>, name: string, els: HTMLElement[]): void {
+    private buildFuntionAction(
+        object: Record<string, any>,
+        name: string,
+        els: HTMLElement[],
+    ): void {
         object[name] = (...params: any[]) => {
             let resp = null;
             for (let index = 0; index < els.length; index++) {
@@ -331,4 +448,4 @@ export class Selective {
             return resp ?? object;
         };
     }
-}
+}