selective-ui 1.3.1 → 1.4.1

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

@@ -14,8 +14,8 @@ import { OptionModel } from "src/ts/models/option-model";
  * Represents the DOM elements used in the SearchBox component.
  */
 export type SearchBoxTags = {
-    SearchBox: HTMLDivElement;      // Container for the search box
-    SearchInput: HTMLInputElement;  // Input field for search queries
+    SearchBox: HTMLDivElement; // Container for the search box
+    SearchInput: HTMLInputElement; // Input field for search queries
 };
 
 /**
@@ -35,7 +35,7 @@ export type NavigateHandler = (direction: 1 | -1) => void;
  * Represents the DOM elements used in the SelectBox component.
  */
 export type SelectBoxTags = {
-    ViewPanel: HTMLDivElement;  // Panel that displays selectable options
+    ViewPanel: HTMLDivElement; // Panel that displays selectable options
 };
 
 /**
@@ -43,46 +43,46 @@ export type SelectBoxTags = {
  * Combines mounted view result with additional services and components.
  */
 export type ContainerRuntime = MountViewResult<SelectBoxTags> & {
-    placeholder: PlaceHolder;           // Placeholder manager
-    directive: Directive;               // Directive handler for dynamic behavior
-    searchbox: SearchBox;               // Search box component
-    popup: Popup;                       // Popup component for dropdown
-    effector: EffectorInterface;        // Effector for state management
-    targetElement: HTMLSelectElement;   // Original select element
-    accessorybox: AccessoryBox;         // Accessory box for extra UI elements
+    placeholder: PlaceHolder; // Placeholder manager
+    directive: Directive; // Directive handler for dynamic behavior
+    searchbox: SearchBox; // Search box component
+    popup: Popup; // Popup component for dropdown
+    effector: EffectorInterface; // Effector for state management
+    targetElement: HTMLSelectElement; // Original select element
+    accessorybox: AccessoryBox; // Accessory box for extra UI elements
     searchController: SearchController; // Controller for search logic
-    selectObserver: SelectObserver;     // Observer for selection changes
-    datasetObserver: DatasetObserver;   // Observer for dataset updates
+    selectObserver: SelectObserver; // Observer for selection changes
+    datasetObserver: DatasetObserver; // Observer for dataset updates
 };
 
 /**
  * Interface defining actions and properties for the SelectBox component.
  */
 export interface SelectBoxAction {
-    targetElement: HTMLSelectElement;     // Target Select element
+    targetElement: HTMLSelectElement; // Target Select element
 
-    placeholder: string;           // Placeholder text
-    oldValue: unknown;             // Previous value before change
+    placeholder: string; // Placeholder text
+    oldValue: unknown; // Previous value before change
 
-    value: string | string[];      // Current selected value(s)
-    valueArray: string[];          // Selected values as an array
-    valueString: string;           // Selected values as a single string
+    value: string | string[]; // Current selected value(s)
+    valueArray: string[]; // Selected values as an array
+    valueString: string; // Selected values as a single string
 
-    valueOptions: OptionModel[];   // Selected option models
-    mask: string[];                // Masked values for filtering
-    valueText: string | string[];  // Display text for selected values
+    valueOptions: OptionModel[]; // Selected option models
+    mask: string[]; // Masked values for filtering
+    valueText: string | string[]; // Display text for selected values
 
-    isOpen: boolean;               // Indicates if the dropdown is open
+    isOpen: boolean; // Indicates if the dropdown is open
 
-    disabled: boolean;             // Indicates if the component is disabled
-    readonly: boolean;             // Indicates if the component is read-only
-    visible: boolean;              // Indicates if the component is visible
+    disabled: boolean; // Indicates if the component is disabled
+    readonly: boolean; // Indicates if the component is read-only
+    visible: boolean; // Indicates if the component is visible
 
     /**
      * Get parent of self
      * @param evtToken - Optional event token for tracking.
      */
-    getParent(evtToken?: unknown): HTMLElement
+    getParent(evtToken?: unknown): HTMLElement;
 
     /**
      * Get dataset from selected options
@@ -90,7 +90,11 @@ export interface SelectBoxAction {
      * @param strDataset - Property to find
      * @param isArray - Keep array or return once
      */
-    valueDataset(evtToken?: unknown, strDataset?: string, isArray?: boolean): any[] | string
+    valueDataset(
+        evtToken?: unknown,
+        strDataset?: string,
+        isArray?: boolean,
+    ): any[] | string;
 
     /**
      * Select all available options.
@@ -113,7 +117,12 @@ export interface SelectBoxAction {
      * @param trigger - Whether to trigger change events.
      * @param force - Whether to force the update.
      */
-    setValue(evtToken: unknown | null, value: unknown, trigger?: boolean, force?: boolean): void;
+    setValue(
+        evtToken?: unknown,
+        value?: unknown,
+        trigger?: boolean,
+        force?: boolean,
+    ): void;
 
     /**
      * Load options for the SelectBox, typically from an AJAX source.
@@ -156,7 +165,11 @@ export interface SelectBoxAction {
      * @param evtName - Name of the event.
      * @param handle - Callback function for the event.
      */
-    on(evtToken: unknown, evtName: string, handle: (...args: any[]) => any): void;
+    on(
+        evtToken: unknown,
+        evtName: string,
+        handle: (...args: any[]) => any,
+    ): void;
 
     /**
      * Perform an AJAX request.
@@ -170,4 +183,4 @@ export interface SelectBoxAction {
      * @param evtToken - Event token for tracking.
      */
     loadAjax(evtToken: unknown, obj: unknown): void;
-}
+}

package/src/ts/types/components/state.box.type.ts

@@ -3,4 +3,4 @@
  * - "notfound": No matching results found.
  * - "nodata": No data available to display.
  */
-export type EmptyStateType = "notfound" | "nodata";
+export type EmptyStateType = "notfound" | "nodata";

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

@@ -6,7 +6,9 @@ import type { ModelContract } from "./model.type";
  *
  * @template TItem - A model type that implements ModelContract.
  */
-export interface AdapterContract<TItem extends ModelContract<any, any>> extends Lifecycle {
+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.
@@ -64,7 +66,7 @@ export interface AdapterContract<TItem extends ModelContract<any, any>> extends
      * @param item - The item for which the viewer is being created.
      * @returns An adapter-specific viewer instance.
      */
-    viewHolder(parent: HTMLElement, item: TItem): unknown;
+    viewHolder?(parent: HTMLElement, item: TItem): unknown;
 
     /**
      * Bind an item to its viewer at a given position.
@@ -83,7 +85,10 @@ export interface AdapterContract<TItem extends ModelContract<any, any>> extends
      * @param propName - The name of the property being changed.
      * @param callback - The handler invoked with change context/args.
      */
-    onPropChanging(propName: string, callback: (...args: unknown[]) => void): void;
+    onPropChanging(
+        propName: string,
+        callback: (...args: unknown[]) => void,
+    ): void;
 
     /**
      * Register a post-change callback for a given property.
@@ -92,7 +97,10 @@ export interface AdapterContract<TItem extends ModelContract<any, any>> extends
      * @param propName - The name of the property that changed.
      * @param callback - The handler invoked with change context/args.
      */
-    onPropChanged(propName: string, callback: (...args: unknown[]) => void): void;
+    onPropChanged(
+        propName: string,
+        callback: (...args: unknown[]) => void,
+    ): void;
 
     /**
      * Trigger the post-change pipeline for a property.
@@ -127,4 +135,4 @@ export interface AdapterContract<TItem extends ModelContract<any, any>> extends
      * @param items - The incoming items to process/update.
      */
     updateData(items: TItem[]): void;
-}
+}

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

@@ -1,4 +1,3 @@
-
 /**
  * Enumerates the finite lifecycle states used across core classes (e.g., View/Model).
  *
@@ -59,4 +58,4 @@ export interface LifecycleHooks {
 export type LifecycleHookContext = {
     state: LifecycleState;
     prevState: LifecycleState;
-};
+};

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

@@ -11,13 +11,13 @@ export interface ModelContract<TTarget, TView> extends Lifecycle {
      * The target element that this model is bound to.
      * Can be null if not yet initialized.
      */
-    targetElement: TTarget | null;
+    targetElement?: TTarget;
 
     /**
      * The view associated with the target element.
      * Can be null if the view is not yet created.
      */
-    view: TView | null;
+    view?: TView;
 
     /**
      * The value represented by this model.
@@ -39,4 +39,4 @@ export interface ModelContract<TTarget, TView> extends Lifecycle {
      * Indicates whether the model has been vissibly.
      */
     visible?: boolean;
-}
+}

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

@@ -6,18 +6,20 @@ import { AdapterContract } from "./adapter.type";
  *
  * @template TAdapter - A concrete adapter type that implements AdapterContract.
  */
-export interface RecyclerViewContract<TAdapter extends AdapterContract<any>> extends Lifecycle {
+export interface RecyclerViewContract<
+    TAdapter extends AdapterContract<any>,
+> extends Lifecycle {
     /**
      * The container element that hosts all item views.
      * Can be null until `setView` is called.
      */
-    viewElement: HTMLElement | null;
+    viewElement?: HTMLElement;
 
     /**
      * The adapter instance responsible for providing and binding item views.
      * Can be null until `setAdapter` is called.
      */
-    adapter: TAdapter | null;
+    adapter?: TAdapter;
 
     /**
      * Attach an adapter and refresh the view accordingly.
@@ -42,8 +44,8 @@ export interface RecyclerViewContract<TAdapter extends AdapterContract<any>> ext
     /**
      * Refresh the rendered views to reflect current adapter data/state.
      * May perform diffing, partial updates, or full re-binding.
-     * 
+     *
      * @param isUpdate - Indicates if this refresh is due to an update operation.
      */
     refresh(isUpdate: boolean): void;
-}
+}

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

@@ -1,4 +1,3 @@
-
 import { Lifecycle } from "src/ts/core/base/lifecycle";
 import { MountViewResult } from "../../utils/libs.type";
 
@@ -20,8 +19,9 @@ import { MountViewResult } from "../../utils/libs.type";
  * }
  * ```
  */
-export interface ViewContract<TTags extends Record<string, HTMLElement>> extends Lifecycle {
-
+export interface ViewContract<
+    TTags extends Record<string, HTMLElement>,
+> extends Lifecycle {
     /**
      * The parent DOM element into which the view is mounted.
      *
@@ -29,7 +29,7 @@ export interface ViewContract<TTags extends Record<string, HTMLElement>> extends
      * - `null` before the view is mounted
      * - Set once the view is attached to the DOM
      */
-    parent: HTMLElement | null;
+    parent?: HTMLElement;
 
     /**
      * Internal representation of the mounted view returned by `mountNode`.
@@ -40,7 +40,7 @@ export interface ViewContract<TTags extends Record<string, HTMLElement>> extends
      *
      * Will be `null` if the view has not been mounted yet.
      */
-    view: MountViewResult<TTags> | null;
+    view?: MountViewResult<TTags>;
 
     /**
      * Returns the root HTMLElement of the mounted view.
@@ -52,4 +52,4 @@ export interface ViewContract<TTags extends Record<string, HTMLElement>> extends
      * @throws {Error} If the view has not been mounted or initialized.
      */
     getView(): HTMLElement;
-}
+}

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

@@ -1,43 +1,42 @@
-
 /**
  * Configuration options for the virtualized recycler view.
  * Controls which element is used for scrolling, sizing heuristics, and how many
  * extra items are rendered outside the viewport to reduce popping.
  */
 export type VirtualOptions = {
-  /**
-   * The scroll container element used to measure scroll position and viewport.
-   * If omitted, the implementation may default to the nearest scrollable parent
-   * or the window (depending on your mount strategy).
-   */
-  scrollEl?: HTMLElement;
+    /**
+     * The scroll container element used to measure scroll position and viewport.
+     * If omitted, the implementation may default to the nearest scrollable parent
+     * or the window (depending on your mount strategy).
+     */
+    scrollEl?: HTMLElement;
 
-  /**
-   * Estimated height (in pixels) for a single item.
-   * Used as a heuristic before real measurements are available (especially when
-   * `dynamicHeights` is enabled) to compute the total scrollable size.
-   */
-  estimateItemHeight?: number;
+    /**
+     * Estimated height (in pixels) for a single item.
+     * Used as a heuristic before real measurements are available (especially when
+     * `dynamicHeights` is enabled) to compute the total scrollable size.
+     */
+    estimateItemHeight?: number;
 
-  /**
-   * Number of extra items to render above and below the visible range.
-   * Higher values reduce blanking during fast scroll at the cost of more DOM work.
-   */
-  overscan?: number;
+    /**
+     * Number of extra items to render above and below the visible range.
+     * Higher values reduce blanking during fast scroll at the cost of more DOM work.
+     */
+    overscan?: number;
 
-  /**
-   * Enables measuring and caching actual item heights.
-   * When `true`, the recycler view supports variable-height items instead of
-   * assuming a fixed height for all items.
-   */
-  dynamicHeights?: boolean;
+    /**
+     * Enables measuring and caching actual item heights.
+     * When `true`, the recycler view supports variable-height items instead of
+     * assuming a fixed height for all items.
+     */
+    dynamicHeights?: boolean;
 
-  /**
-   * Enables adaptive estimation based on observed item measurements.
-   * When `true`, `estimateItemHeight` may be refined over time to improve
-   * scrollbar accuracy and reduce layout jumps.
-   */
-  adaptiveEstimate?: boolean;
+    /**
+     * Enables adaptive estimation based on observed item measurements.
+     * When `true`, `estimateItemHeight` may be refined over time to improve
+     * scrollbar accuracy and reduce layout jumps.
+     */
+    adaptiveEstimate?: boolean;
 };
 
 /**
@@ -46,21 +45,21 @@ export type VirtualOptions = {
  * manipulate padding and host the rendered item elements.
  */
 export type VirtualRecyclerViewTags = {
-  /**
-   * Top spacer element that simulates the height of items scrolled past.
-   * Its height is adjusted to keep the visible items aligned with the scroll offset.
-   */
-  PadTop: HTMLDivElement;
+    /**
+     * Top spacer element that simulates the height of items scrolled past.
+     * Its height is adjusted to keep the visible items aligned with the scroll offset.
+     */
+    PadTop: HTMLDivElement;
 
-  /**
-   * Container that hosts the currently rendered (visible + overscan) item elements.
-   * Items are inserted/updated within this element during virtualization.
-   */
-  ItemsHost: HTMLDivElement;
+    /**
+     * Container that hosts the currently rendered (visible + overscan) item elements.
+     * Items are inserted/updated within this element during virtualization.
+     */
+    ItemsHost: HTMLDivElement;
 
-  /**
-   * Bottom spacer element that simulates the height of items not yet rendered.
-   * Its height is adjusted to represent remaining content below the visible range.
-   */
-  PadBottom: HTMLDivElement;
-};
+    /**
+     * Bottom spacer element that simulates the height of items not yet rendered.
+     * Its height is adjusted to represent remaining content below the visible range.
+     */
+    PadBottom: HTMLDivElement;
+};

package/src/ts/types/core/search-controller.type.ts

@@ -87,8 +87,24 @@ export type AjaxOptGroupItem = {
 export type NormalizedAjaxItem =
     | HTMLOptionElement
     | HTMLOptGroupElement
-    | { type: "option"; value: string; text: string; selected?: boolean; data?: Record<string, any> }
-    | { type: "optgroup"; label: string; data?: Record<string, any>; options: Array<{ value: string; text: string; selected?: boolean; data?: Record<string, any> }> };
+    | {
+          type: "option";
+          value: string;
+          text: string;
+          selected?: boolean;
+          data?: Record<string, any>;
+      }
+    | {
+          type: "optgroup";
+          label: string;
+          data?: Record<string, any>;
+          options: Array<{
+              value: string;
+              text: string;
+              selected?: boolean;
+              data?: Record<string, any>;
+          }>;
+      };
 
 /**
  * Represents the result of parsing an AJAX response.

package/src/ts/types/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

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

@@ -10,8 +10,8 @@ import { SelectiveOptions } from "../utils/selective.type";
 export interface PluginContext<TTags extends Record<string, HTMLElement>> {
     selectBox: SelectBox;
     options: SelectiveOptions;
-    adapter: AdapterContract<any> | null;
-    recycler: RecyclerViewContract<AdapterContract<any>> | null;
+    adapter?: AdapterContract<any>;
+    recycler?: RecyclerViewContract<AdapterContract<any>>;
     viewTags: TTags & { id: string };
     actions: SelectBoxAction;
 }

package/src/ts/types/services/effector.type.ts

@@ -3,7 +3,7 @@
  * Typically includes width and height of an element.
  */
 export interface SizeObject {
-    width: number;  // Element width in pixels
+    width: number; // Element width in pixels
     height: number; // Element height in pixels
 }
 
@@ -12,8 +12,8 @@ export interface SizeObject {
  * Includes scrollable height for overflow calculations.
  */
 export interface DimensionObject {
-    width: number;        // Element width in pixels
-    height: number;       // Element height in pixels
+    width: number; // Element width in pixels
+    height: number; // Element height in pixels
     scrollHeight: number; // Total scrollable height of the element
 }
 
@@ -87,45 +87,45 @@ export interface EffectorInterface {
  * Configuration options for expanding an element.
  */
 export type ExpandConfig = {
-    duration?: number;           // Animation duration in milliseconds
-    display?: string;            // CSS display property during expansion
-    width: number;               // Target width in pixels
-    left: number;                // Target left position
-    top: number;                 // Target top position
-    maxHeight: number;           // Maximum height allowed
-    realHeight: number;          // Actual height of the content
+    duration?: number; // Animation duration in milliseconds
+    display?: string; // CSS display property during expansion
+    width: number; // Target width in pixels
+    left: number; // Target left position
+    top: number; // Target top position
+    maxHeight: number; // Maximum height allowed
+    realHeight: number; // Actual height of the content
     position?: "top" | "bottom"; // Positioning reference
-    onComplete?: () => void;     // Callback after expansion completes
+    onComplete?: () => void; // Callback after expansion completes
 };
 
 /**
  * Configuration options for collapsing an element.
  */
 export type CollapseConfig = {
-    duration?: number;           // Animation duration in milliseconds
-    onComplete?: () => void;     // Callback after collapse completes
+    duration?: number; // Animation duration in milliseconds
+    onComplete?: () => void; // Callback after collapse completes
 };
 
 /**
  * Configuration options for swipe animations.
  */
 export type SwipeConfig = {
-    duration?: number;           // Animation duration in milliseconds
-    display?: string;            // CSS display property during swipe
-    onComplete?: () => void;     // Callback after swipe completes
+    duration?: number; // Animation duration in milliseconds
+    display?: string; // CSS display property during swipe
+    onComplete?: () => void; // Callback after swipe completes
 };
 
 /**
  * Configuration options for resizing an element.
  */
 export type ResizeConfig = {
-    duration?: number;           // Animation duration in milliseconds
-    width: number;               // Target width in pixels
-    left: number;                // Target left position
-    top: number;                 // Target top position
-    maxHeight: number;           // Maximum height allowed
-    realHeight: number;          // Actual height of the content
+    duration?: number; // Animation duration in milliseconds
+    width: number; // Target width in pixels
+    left: number; // Target left position
+    top: number; // Target top position
+    maxHeight: number; // Maximum height allowed
+    realHeight: number; // Actual height of the content
     position?: "top" | "bottom"; // Positioning reference
-    animate?: boolean;           // Whether to animate the resize
-    onComplete?: () => void;     // Callback after resize completes
-};
+    animate?: boolean; // Whether to animate the resize
+    onComplete?: () => void; // Callback after resize completes
+};

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

@@ -2,10 +2,14 @@
  * Represents the measurements for each side of a box (padding, border, or margin).
  */
 export interface BoxSides {
-    top: number;    // Size of the top side in pixels
-    right: number;  // Size of the right side in pixels
-    bottom: number; // Size of the bottom side in pixels
-    left: number;   // Size of the left side in pixels
+    /** Size of the top side in pixels */
+    top: number;
+    /** Size of the right side in pixels */
+    right: number;
+    /** Size of the bottom side in pixels */
+    bottom: number;
+    /** Size of the left side in pixels */
+    left: number;
 }
 
 /**
@@ -13,11 +17,18 @@ export interface BoxSides {
  * and box model properties (padding, border, margin).
  */
 export interface ElementMetrics {
-    width: number;       // Element width in pixels
-    height: number;      // Element height in pixels
-    top: number;         // Distance from the top of the parent/container
-    left: number;        // Distance from the left of the parent/container
-    padding: BoxSides;   // Padding values for all sides
-    border: BoxSides;    // Border thickness values for all sides
-    margin: BoxSides;    // Margin values for all sides
-}
+    /** Element width in pixels */
+    width: number;
+    /** Element height in pixels */
+    height: number;
+    /** Distance from the top of the parent/container */
+    top: number;
+    /** Distance from the left of the parent/container */
+    left: number;
+    /** Padding values for all sides */
+    padding: BoxSides;
+    /** Border thickness values for all sides */
+    border: BoxSides;
+    /** Margin values for all sides */
+    margin: BoxSides;
+}

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

@@ -63,7 +63,7 @@ export interface TimerEntry<T extends any[] = any[]> {
  *    - `null` when `run()` is called without parameters
  */
 export type StoredEntry = {
-    callback: (payload: any[] | null) => void;
+    callback: (payload?: any[]) => void;
     timeout: number;
     once: boolean;
-};
+};

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

@@ -37,4 +37,4 @@ export interface IEventToken {
 export type IEventHandler<TParams extends unknown[] = []> = (
     cb: IEventCallback,
     ...params: TParams
-) => void;
+) => void;