selective-ui 1.2.5 → 1.2.6

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

@@ -229,7 +229,9 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
         const input = this.view?.view?.tags?.OptionInput;
         const viewEl = this.view?.getView?.();
 
-        if (input) (input as HTMLInputElement).checked = value;
+        if (input) {
+            input.checked = value;
+        }
 
         if (viewEl && this.targetElement) {
             viewEl.classList.toggle("checked", !!value);
@@ -237,7 +239,9 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
             this.targetElement.toggleAttribute("selected", !!value);
         }
 
-        if (this.targetElement) this.targetElement.selected = value;
+        if (this.targetElement) {
+            this.targetElement.selected = value;
+        }
 
         iEvents.callEvent<[OptionModel, boolean]>([this, value], ...this.privOnInternalSelected);
     }
@@ -284,7 +288,7 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
      * @returns {DOMStringMap}
      */
     public get dataset(): DOMStringMap {
-        return this.targetElement?.dataset ?? ({} as DOMStringMap);
+        return this.targetElement?.dataset ?? {};
     }
 
     /**
@@ -377,8 +381,12 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
 
         const imageTag = this.view.view.tags.OptionImage;
         if (imageTag && this.hasImage) {
-            (imageTag as HTMLImageElement).src = this.imageSrc;
-            (imageTag as HTMLImageElement).alt = this.text;
+            if (imageTag.src != this.imageSrc) {
+                imageTag.src = this.imageSrc;
+            }
+            if (imageTag.alt != this.text) {
+                imageTag.alt = this.text;
+            }
         }
 
         if (this.targetElement) this.selectedNonTrigger = this.targetElement.selected;

package/src/ts/services/refresher.ts

@@ -1,3 +1,4 @@
+import { BinderMap } from "../types/utils/istorage.type";
 import { Libs } from "../utils/libs";
 
 /**
@@ -37,7 +38,7 @@ export class Refresher {
      * @param view - View panel element whose inline styles will be updated.
      */
     public static resizeBox(select: HTMLSelectElement, view: HTMLElement): void {
-        const bindedMap = Libs.getBinderMap(select);
+        const bindedMap = Libs.getBinderMap<BinderMap>(select);
         if (!bindedMap?.options) return;
 
         const options = bindedMap.options;

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

@@ -63,7 +63,7 @@ export class ResizeObserverService {
      * @remarks
      * Set by {@link connect} and cleared by {@link disconnect}.
      */
-    public element: Element | null = null;
+    public element: HTMLElement | null = null;
 
     /**
      * Underlying `ResizeObserver` instance.
@@ -132,7 +132,7 @@ export class ResizeObserverService {
      * This method is the single funnel for all observation signals (internal + external).
      */
     private updateChanged(): void {
-        const el = this.element as HTMLElement | null;
+        const el = this.element;
 
         if (!el || typeof el.getBoundingClientRect !== "function") {
             const defaultMetrics: ElementMetrics = {
@@ -213,8 +213,8 @@ export class ResizeObserverService {
      * @remarks
      * Not idempotent. Call {@link disconnect} before calling `connect()` again to avoid duplicates.
      */
-    public connect(element: Element): void {
-        if (!(element instanceof Element)) {
+    public connect(element: HTMLElement): void {
+        if (!(element instanceof HTMLElement)) {
             throw new Error("Invalid element");
         }
 

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

@@ -3,7 +3,7 @@ import { Lifecycle } from "src/ts/core/base/lifecycle";
 import { MountViewResult } from "../../utils/libs.type";
 
 /**
- * Contract definition for a UI View created via `mountView` or `mountNode`.
+ * Contract definition for a UI View created via `mountNode`.
  *
  * A View encapsulates:
  * - The mounted DOM structure
@@ -32,7 +32,7 @@ export interface ViewContract<TTags extends Record<string, HTMLElement>> extends
     parent: HTMLElement | null;
 
     /**
-     * Internal representation of the mounted view returned by `mountView` or `mountNode`.
+     * Internal representation of the mounted view returned by `mountNode`.
      *
      * Contains:
      * - The root element of the view
@@ -46,7 +46,7 @@ export interface ViewContract<TTags extends Record<string, HTMLElement>> extends
      * Returns the root HTMLElement of the mounted view.
      *
      * This is typically the top-level container element
-     * created by `mountView` / `mountNode`.
+     * created by `mountNode`.
      *
      * @returns The root HTMLElement of the view.
      * @throws {Error} If the view has not been mounted or initialized.

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

@@ -42,7 +42,7 @@ export type VirtualOptions = {
 
 /**
  * Tag map for the virtual recycler view DOM structure.
- * These nodes are typically produced by `mountView`/`mountNode` and used to
+ * These nodes are typically produced by `mountNode` and used to
  * manipulate padding and host the rendered item elements.
  */
 export type VirtualRecyclerViewTags = {

package/src/ts/types/plugins/plugin.type.ts

@@ -0,0 +1,46 @@
+import { SelectBox } from "../../components/selectbox";
+import { SelectBoxAction, SelectBoxTags } from "../components/searchbox.type";
+import { AdapterContract } from "../core/base/adapter.type";
+import { RecyclerViewContract } from "../core/base/recyclerview.type";
+import { SelectiveOptions } from "../utils/selective.type";
+
+/**
+ * Runtime context passed to plugin hooks.
+ */
+export interface PluginContext<TTags extends Record<string, HTMLElement>> {
+    selectBox: SelectBox;
+    options: SelectiveOptions;
+    adapter: AdapterContract<any> | null;
+    recycler: RecyclerViewContract<AdapterContract<any>> | null;
+    viewTags: TTags & { id: string };
+    actions: SelectBoxAction;
+}
+
+/**
+ * Plugin contract for extending Selective lifecycle behavior.
+ */
+export interface SelectivePlugin {
+    /** Unique plugin identifier. */
+    id: string;
+
+    /** Initialization hook invoked during plugin setup. */
+    init?(context?: PluginContext<SelectBoxTags>): void;
+
+    /** Teardown hook invoked when plugin is destroyed. */
+    destroy?(context?: PluginContext<SelectBoxTags>): void;
+
+    /** Alias for destroy hook, invoked during global teardown. */
+    onDestroy?(context?: PluginContext<SelectBoxTags>): void;
+
+    /** Hook invoked when a SelectBox is bound. */
+    onBind?(context?: PluginContext<SelectBoxTags>): void;
+
+    /** Hook invoked when a SelectBox is opened. */
+    onOpen?(context?: PluginContext<SelectBoxTags>): void;
+
+    /** Hook invoked when a SelectBox is closed. */
+    onClose?(context?: PluginContext<SelectBoxTags>): void;
+
+    /** Hook invoked when selection changes. */
+    onChange?(context?: PluginContext<SelectBoxTags>, ...args: unknown[]): void;
+}

package/src/ts/types/utils/istorage.type.ts

@@ -70,11 +70,15 @@ export interface DefaultConfig {
  * Represents a binding map for component initialization.
  * Includes options, container reference, and lifecycle actions.
  */
-export type BinderMap = {
+export type BinderMap<
+    TContainer extends any = any, 
+    TAction extends Record<string, any> = Record<string, any>, 
+    TSelf extends { deInit?: () => void } & Record<string, any> = { deInit?: () => void } & Record<string, any>
+> = {
     options: SelectiveOptions;       // Component options
-    container?: any;                 // Reference to the container element
-    action?: Record<string, any>;    // Action handlers or methods
-    self?: { deInit?: () => void } & Record<string, any>; // Self-reference with optional cleanup
+    container?: TContainer;                 // Reference to the container element
+    action?: TAction;    // Action handlers or methods
+    self?: TSelf; // Self-reference with optional cleanup
 };
 
 /**

package/src/ts/types/utils/libs.type.ts

@@ -20,11 +20,11 @@ export type NodeSpec = {
 
 /**
  * Generic mount result shape used across views.
- * Returned by mountView/mountNode utilities.
+ * Returned by mountNode utilities.
  *
  * @template TTags - A map of tag names to their corresponding HTMLElement instances.
  */
-export type MountViewResult<TTags extends Record<string, HTMLElement>> = {
+export type MountViewResult<TTags extends Record<string, HTMLElement> = Record<string, HTMLElement>> = {
     view: HTMLElement | null;                   // Root element of the mounted view
     tags: TTags & { id: string };               // Tag map with an additional unique ID
 };

package/src/ts/types/utils/selective.type.ts

@@ -1,5 +1,6 @@
 import { EffectorInterface } from "../services/effector.type";
 import { DefaultConfig } from "./istorage.type";
+import type { SelectivePlugin } from "../plugins/plugin.type";
 
 /**
  * Represents configuration options for the Selective component.
@@ -56,6 +57,18 @@ export interface SelectiveUIGlobal {
      */
     effector(element: string | HTMLElement): EffectorInterface;
 
+    /**
+     * Register a Selective plugin implementation.
+     * @param plugin - Plugin instance to register.
+     */
+    registerPlugin(plugin: SelectivePlugin): void;
+
+    /**
+     * Unregister a Selective plugin implementation by id.
+     * @param id - Plugin id to remove.
+     */
+    unregisterPlugin(id: string): void;
+
     /**
      * Current version of the library.
      */
@@ -65,4 +78,4 @@ export interface SelectiveUIGlobal {
      * Current version of the library.
      */
     name: string;
-}
+}

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

@@ -150,12 +150,12 @@ export class CallbackScheduler {
      * @public
      * @param {TimerKey} key - Key whose callbacks will be scheduled.
      * @param {...any[]} params - Parameters passed as a shared payload to all callbacks.
-     * @returns {Promise<void> | void} Promise resolving when all callbacks finish execution.
+     * @returns {Promise<void>} Promise resolving when all callbacks finish execution.
      */
-    public run(key: TimerKey, ...params: any[]): Promise<void> | void {
+    public run<T extends Promise<void>>(key: TimerKey, ...params: any[]): T {
         const executes = this.executeStored.get(key);
         if (!executes || executes.length === 0) {
-            return Promise.resolve();
+            return Promise.resolve() as T;
         }
 
         if (!this.timerRunner.has(key)) {
@@ -201,7 +201,7 @@ export class CallbackScheduler {
             tasks.push(task);
         }
 
-        return Promise.all(tasks).then(() => void 0);
+        return Promise.all(tasks).then(() => void 0) as T;
     }
 
     /**

package/src/ts/utils/libs.ts

@@ -61,65 +61,65 @@ export class Libs {
     }
 
     /**
-     * Resolves a selector, NodeList, or single Element into an array of elements.
+     * Resolves a selector, NodeList, or single HTMLElement into an array of elements.
      * Returns an empty array if nothing is found.
      *
-     * @param {string|NodeListOf<Element>|Element|HTMLElement|ArrayLike<Element>|null} queryCommon - CSS selector, NodeList, or Element.
-     * @returns {Element[]} - Array of matched elements (empty if none).
+     * @param {string|NodeListOf<HTMLElement>|HTMLElement|HTMLElement|ArrayLike<HTMLElement>|null} queryCommon - CSS selector, NodeList, or HTMLElement.
+     * @returns {HTMLElement[]} - Array of matched elements (empty if none).
      */
-    public static getElements(
+    public static getElements<T extends HTMLElement[]>(
         queryCommon:
             | string
-            | NodeListOf<Element>
+            | NodeListOf<HTMLElement>
             | Element
             | HTMLElement
-            | ArrayLike<Element>
+            | ArrayLike<HTMLElement>
             | null
             | undefined
-    ): Element[] {
-        if (!queryCommon) return [];
+    ): T {
+        if (!queryCommon) return [] as T;
 
         if (typeof queryCommon === "string") {
-            const nodeList = document.querySelectorAll(queryCommon);
-            return Array.from(nodeList);
+            const nodeList = document.querySelectorAll<HTMLElement>(queryCommon);
+            return Array.from(nodeList) as T;
         }
 
-        if (queryCommon instanceof Element) {
-            return [queryCommon];
+        if (queryCommon instanceof HTMLElement) {
+            return [queryCommon] as T;
         }
 
         // NodeList or array-like
         if (queryCommon instanceof NodeList || Array.isArray(queryCommon)) {
-            return Array.from(queryCommon);
+            return Array.from(queryCommon) as T;
         }
 
-        return [];
+        return [] as T;
     }
 
     /**
-     * Creates a new Element based on a NodeSpec and applies attributes, classes, styles, dataset, and events.
+     * Creates a new HTMLElement based on a NodeSpec and applies attributes, classes, styles, dataset, and events.
      *
      * @param {NodeSpec} data - Specification describing the element to create.
-     * @returns {Element} - The created element.
+     * @returns {HTMLElement} - The created element.
      */
-    public static nodeCreator(data: Partial<NodeSpec> = {}): Element {
+    public static nodeCreator<T extends HTMLElement>(data: Partial<NodeSpec> = {}): T {
         const nodeName = (data.node ?? "div") as string;
-        return this.nodeCloner(document.createElement(nodeName), data as NodeSpec, true);
+        return this.nodeCloner<T>(document.createElement(nodeName), data as NodeSpec, true);
     }
 
     /**
-     * Clones an element (or converts a Node to Element) and applies NodeSpec options.
+     * Clones an element (or converts a Node to HTMLElement) and applies NodeSpec options.
      * When systemNodeCreate=true, uses the provided node as-is.
      *
-     * @param {Element} node - The element to clone or use.
+     * @param {HTMLElement} node - The element to clone or use.
      * @param {NodeSpec|null} _nodeOption - Options (classList, style, dataset, event, other props).
      * @param {boolean} systemNodeCreate - If true, do not clone; use original node.
-     * @returns {Element} - The processed element.
+     * @returns {HTMLElement} - The processed element.
      */
-    public static nodeCloner(node: Element = document.documentElement, _nodeOption: NodeSpec | null = null, systemNodeCreate = false): Element {
+    public static nodeCloner<T extends HTMLElement>(node: HTMLElement = document.documentElement, _nodeOption: NodeSpec | null = null, systemNodeCreate = false): T {
         const nodeOption: Record<string, unknown> = { ...(_nodeOption ?? {}) };
 
-        const element_creation: Element = systemNodeCreate ? node : this.nodeToElement(node.cloneNode(true));
+        const element_creation: T = systemNodeCreate ? node as T : node.cloneNode(true) as T;
 
         const classList = nodeOption.classList;
         if (typeof classList === "string") {
@@ -184,55 +184,31 @@ export class Libs {
         return element_creation;
     }
 
-    /**
-     * Ensures the given Node is an Element; throws if not.
-     *
-     * @param {Node} node - The node to validate.
-     * @returns {Element} - The element cast.
-     * @throws {TypeError} - If node is not an Element.
-     */
-    public static nodeToElement(node: Node): Element {
-        if (node instanceof Element) return node;
-        throw new TypeError("Node is not an Element");
-    }
-
-    /**
-     * Mounts a view from a plain object specification and returns a typed result
-     * containing the root element and a tag map.
-     *
-     * @template TTags
-     * @param {object} rawObj - The specification describing elements and tags.
-     * @returns {MountViewResult<TTags>} - The mounted view and its tag references.
-     */
-    public static mountView<TTags extends Record<string, any>>(rawObj: Record<string, any>): MountViewResult<TTags> {
-        return this.mountNode<TTags>(rawObj) as MountViewResult<TTags>;
-    }
-
     /**
      * Recursively builds DOM nodes from a specification object, appends/prepends them
      * to an optional parent, and returns either a tag map or a full MountViewResult.
      *
      * @template TTags
      * @param {Object<string, any>} rawObj - Node spec (keys -> { tag, child }).
-     * @param {Element|null} [parentE=null] - Parent to attach into; if null, returns root.
+     * @param {HTMLElement|null} [parentE=null] - Parent to attach into; if null, returns root.
      * @param {boolean} [isPrepend=false] - If true, prepend; otherwise append.
      * @param {boolean} [isRecusive=false] - Internal flag for recursion control.
      * @param {TTags|Object} [recursiveTemp={}] - Accumulator for tag references.
-     * @returns {MountViewResult<TTags>|TTags} - Tag map or the final mount result.
+     * @returns {TTags} - Tag map or the final mount result.
      */
     public static mountNode<TTags extends Record<string, any>>(
         rawObj: Record<string, any>,
-        parentE: Element | null = null,
+        parentE: HTMLElement | null = null,
         isPrepend = false,
         isRecusive = false,
         recursiveTemp: any = {}
-    ): MountViewResult<TTags> | TTags {
-        let view: Element | null = null;
+    ): TTags {
+        let view: HTMLElement | null = null;
 
         for (const key in rawObj) {
             const singleObj = rawObj[key];
-            const tag: Element =
-                singleObj?.tag?.tagName ? (singleObj.tag as Element) : (this.nodeCreator(singleObj.tag) as Element);
+            const tag: HTMLElement =
+                singleObj?.tag?.tagName ? (singleObj.tag as HTMLElement) : (this.nodeCreator(singleObj.tag) as HTMLElement);
 
             recursiveTemp[key] = tag;
 
@@ -349,7 +325,7 @@ export class Libs {
     /**
      * Removes a binder map entry for the given element from the global storage.
      *
-     * @param {HTMLElement} element - Element key to remove from the binder map.
+     * @param {HTMLElement} element - HTMLElement key to remove from the binder map.
      * @returns {boolean} - True if an entry existed and was removed.
      */
     public static removeBinderMap(element: HTMLElement): boolean {
@@ -359,17 +335,17 @@ export class Libs {
     /**
      * Retrieves the binder map entry associated with the given element.
      *
-     * @param {HTMLElement} item - Element key whose binder map is requested.
-     * @returns {BinderMap | null} - The stored binder map value or undefined if absent.
+     * @param {HTMLElement} item - HTMLElement key whose binder map is requested.
+     * @returns {BinderMap | any} - The stored binder map value or undefined if absent.
      */
-    public static getBinderMap(item: HTMLElement): BinderMap | null {
-        return this.iStorage.bindedMap.get(item);
+    public static getBinderMap<T extends BinderMap | any>(item: HTMLElement): T {
+        return this.iStorage.bindedMap.get(item) as T;
     }
 
     /**
      * Sets or updates the binder map entry for a given element.
      *
-     * @param {HTMLElement} item - Element key to associate with the binder map.
+     * @param {HTMLElement} item - HTMLElement key to associate with the binder map.
      * @param {BinderMap} bindMap - Value to store in the binder map.
      */
     public static setBinderMap(item: HTMLElement, bindMap: BinderMap): void {
@@ -379,7 +355,7 @@ export class Libs {
     /**
      * Removes an unbinder map entry for the given element from the global storage.
      *
-     * @param {HTMLElement} element - Element key to remove from the unbinder map.
+     * @param {HTMLElement} element - HTMLElement key to remove from the unbinder map.
      * @returns {boolean} - True if an entry existed and was removed.
      */
     public static removeUnbinderMap(element: HTMLElement): boolean {
@@ -389,7 +365,7 @@ export class Libs {
     /**
      * Retrieves the unbinder map entry associated with the given element.
      *
-     * @param {HTMLElement} item - Element key whose unbinder map is requested.
+     * @param {HTMLElement} item - HTMLElement key whose unbinder map is requested.
      * @returns {unknown} - The stored unbinder map value or undefined if absent.
      */
     public static getUnbinderMap(item: HTMLElement): unknown {
@@ -399,7 +375,7 @@ export class Libs {
     /**
      * Sets or updates the unbinder map entry for a given element.
      *
-     * @param {HTMLElement} item - Element key to associate with the unbinder map.
+     * @param {HTMLElement} item - HTMLElement key to associate with the unbinder map.
      * @param {BinderMap} bindMap - Value to store in the unbinder map.
      */
     public static setUnbinderMap(item: HTMLElement, bindMap: BinderMap): void {
@@ -440,7 +416,7 @@ export class Libs {
             .replace(/\`\>/g, ">")
             .trim();
 
-        const doc = globalThis?.document as Document | undefined;
+        const doc = globalThis?.document;
 
         if (!doc || typeof doc.createElement !== "function") {
             s = s
@@ -560,7 +536,7 @@ export class Libs {
         if (v.endsWith("rem")) return fs * parseFloat(v) + "px";
 
         // fallback: DOM measure
-        const el = this.nodeCreator({ node: "div", style: { height: v, opacity: "0" } }) as HTMLElement;
+        const el = this.nodeCreator({ node: "div", style: { height: v, opacity: "0" } });
         document.body.appendChild(el);
         const px = el.offsetHeight + "px";
         el.remove();