selective-ui 1.4.0 → 1.4.1

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

@@ -6,13 +6,13 @@ import { SelectiveOptions } from "./selective.type";
  * Each event can have multiple callbacks.
  */
 export type StorageEvents = {
-    load?: Array<(...args: any[]) => void>;          // Triggered when data or component is loaded
-    beforeShow?: Array<(...args: any[]) => void>;    // Triggered before the panel is shown
-    show?: Array<(...args: any[]) => void>;          // Triggered when the panel is displayed
-    beforeChange?: Array<(...args: any[]) => void>;  // Triggered before a value change occurs
-    change?: Array<(...args: any[]) => void>;        // Triggered after a value change occurs
-    beforeClose?: Array<(...args: any[]) => void>;   // Triggered before the panel is closed
-    close?: Array<(...args: any[]) => void>;         // Triggered when the panel is closed
+    load?: Array<(...args: any[]) => void>; // Triggered when data or component is loaded
+    beforeShow?: Array<(...args: any[]) => void>; // Triggered before the panel is shown
+    show?: Array<(...args: any[]) => void>; // Triggered when the panel is displayed
+    beforeChange?: Array<(...args: any[]) => void>; // Triggered before a value change occurs
+    change?: Array<(...args: any[]) => void>; // Triggered after a value change occurs
+    beforeClose?: Array<(...args: any[]) => void>; // Triggered before the panel is closed
+    close?: Array<(...args: any[]) => void>; // Triggered when the panel is closed
 };
 
 /**
@@ -20,51 +20,51 @@ export type StorageEvents = {
  * Includes UI settings, behavior flags, and AJAX configuration.
  */
 export interface DefaultConfig {
-    accessoryVisible?: boolean;      // Whether to show the accessory panel initially
-    virtualScroll?: boolean;         // Enable virtual scroll
-    accessoryStyle?: string;         // CSS style for accessory elements
-    multiple?: boolean;              // Enable multiple selection
-    minWidth?: string;               // Minimum width of the component
-    width?: string;                  // Fixed width of the component
-    offsetWidth?: number | null;     // Offset width for positioning
-    minHeight?: string;              // Minimum height of the component
-    height?: string;                 // Fixed height of the component
-    panelHeight?: string;            // Height of the dropdown panel
-    panelMinHeight?: string;         // Minimum height of the dropdown panel
-    disabled?: boolean;              // Disable the component
-    readonly?: boolean;              // Make the component read-only
-    selectall?: boolean;             // Enable "Select All" functionality
-    keepSelected?: boolean;          // Keep selected items after refresh
-    placeholder?: string;            // Placeholder text
-    altMask?: string;                // Alternative mask for display
-    autoclose?: boolean;             // Close panel automatically after selection
-    autoscroll?: boolean;            // Auto-scroll to selected item
-    autofocus?: boolean;             // Focus on input automatically
-    searchable?: boolean;            // Enable search functionality
-    loadingfield?: boolean;          // Show loading indicator in the field
-    preload?: boolean;               // Preload data on initialization
-    visible?: boolean;               // Control visibility of the component
-    skipError?: boolean;             // Skip error handling
-    customDelimiter?: string;        // Custom delimiter for multiple values
-    textLoading?: string;            // Text shown during loading
-    textNoData?: string;             // Text shown when no data is available
-    textNotFound?: string;           // Text shown when no search results are found
-    textSelectAll?: string;          // Label for "Select All"
-    textDeselectAll?: string;        // Label for "Deselect All"
-    textAccessoryDeselect?: string;  // Label for accessory deselect button
-    animationtime?: number;          // Animation duration in milliseconds
-    delaysearchtime?: number;        // Delay before triggering search (ms)
-    allowHtml?: boolean;             // Allow HTML in option labels
-    maxSelected?: number;            // Maximum number of selections allowed
-    labelHalign?: string;            // Horizontal alignment for labels
-    labelValign?: string;            // Vertical alignment for labels
-    imageMode?: boolean;             // Enable image display in options
-    imageWidth?: string;             // Width for option images
-    imageHeight?: string;            // Height for option images
-    imageBorderRadius?: string;      // Border radius for option images
-    imagePosition?: string;          // Position of images relative to text
-    ajax?: AjaxConfig | null;        // AJAX configuration for dynamic data loading
-    on?: StorageEvents;              // Event handlers for component lifecycle
+    accessoryVisible?: boolean; // Whether to show the accessory panel initially
+    virtualScroll?: boolean; // Enable virtual scroll
+    accessoryStyle?: string; // CSS style for accessory elements
+    multiple?: boolean; // Enable multiple selection
+    minWidth?: string; // Minimum width of the component
+    width?: string; // Fixed width of the component
+    offsetWidth?: number; // Offset width for positioning
+    minHeight?: string; // Minimum height of the component
+    height?: string; // Fixed height of the component
+    panelHeight?: string; // Height of the dropdown panel
+    panelMinHeight?: string; // Minimum height of the dropdown panel
+    disabled?: boolean; // Disable the component
+    readonly?: boolean; // Make the component read-only
+    selectall?: boolean; // Enable "Select All" functionality
+    keepSelected?: boolean; // Keep selected items after refresh
+    placeholder?: string; // Placeholder text
+    altMask?: string; // Alternative mask for display
+    autoclose?: boolean; // Close panel automatically after selection
+    autoscroll?: boolean; // Auto-scroll to selected item
+    autofocus?: boolean; // Focus on input automatically
+    searchable?: boolean; // Enable search functionality
+    loadingfield?: boolean; // Show loading indicator in the field
+    preload?: boolean; // Preload data on initialization
+    visible?: boolean; // Control visibility of the component
+    skipError?: boolean; // Skip error handling
+    customDelimiter?: string; // Custom delimiter for multiple values
+    textLoading?: string; // Text shown during loading
+    textNoData?: string; // Text shown when no data is available
+    textNotFound?: string; // Text shown when no search results are found
+    textSelectAll?: string; // Label for "Select All"
+    textDeselectAll?: string; // Label for "Deselect All"
+    textAccessoryDeselect?: string; // Label for accessory deselect button
+    animationtime?: number; // Animation duration in milliseconds
+    delaysearchtime?: number; // Delay before triggering search (ms)
+    allowHtml?: boolean; // Allow HTML in option labels
+    maxSelected?: number; // Maximum number of selections allowed
+    labelHalign?: string; // Horizontal alignment for labels
+    labelValign?: string; // Vertical alignment for labels
+    imageMode?: boolean; // Enable image display in options
+    imageWidth?: string; // Width for option images
+    imageHeight?: string; // Height for option images
+    imageBorderRadius?: string; // Border radius for option images
+    imagePosition?: string; // Position of images relative to text
+    ajax?: AjaxConfig; // AJAX configuration for dynamic data loading
+    on?: StorageEvents; // Event handlers for component lifecycle
 }
 
 /**
@@ -72,13 +72,15 @@ export interface DefaultConfig {
  * Includes options, container reference, and lifecycle actions.
  */
 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>
+    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?: TContainer;                 // Reference to the container element
-    action?: TAction;    // Action handlers or methods
+    options: SelectiveOptions; // Component options
+    container?: TContainer; // Reference to the container element
+    action?: TAction; // Action handlers or methods
     self?: TSelf; // Self-reference with optional cleanup
 };
 
@@ -87,5 +89,5 @@ export type BinderMap<
  */
 export type PropertiesType = {
     type: "variable" | "get-set" | "func"; // Property type (variable, getter/setter, or function)
-    name: string;                           // Property name
-};
+    name: string; // Property name
+};

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

@@ -3,19 +3,19 @@
  * Includes attributes, styles, events, and accessibility properties.
  */
 export type NodeSpec = {
-    node: string;                                // Tag name of the node (e.g., "div", "span")
-    classList?: string | string[];              // CSS classes to apply
-    style?: Partial<CSSStyleDeclaration>;       // Inline styles for the node
-    dataset?: Record<string, string>;           // Data attributes (e.g., data-* values)
-    role?: string;                               // ARIA role for accessibility
-    ariaLive?: string;                           // ARIA live region setting
-    ariaLabelledby?: string;                     // ARIA labelledby reference
-    ariaControls?: string;                       // ARIA controls reference
-    ariaHaspopup?: string;                       // ARIA haspopup attribute
-    ariaMultiselectable?: string;                // ARIA multiselectable attribute
-    ariaAutocomplete?: string;                   // ARIA autocomplete attribute
-    event?: Record<string, EventListener>;       // Event listeners mapped by event name
-    [key: string]: unknown;                      // Allow additional custom properties
+    node: string; // Tag name of the node (e.g., "div", "span")
+    classList?: string | string[]; // CSS classes to apply
+    style?: Partial<CSSStyleDeclaration>; // Inline styles for the node
+    dataset?: Record<string, string>; // Data attributes (e.g., data-* values)
+    role?: string; // ARIA role for accessibility
+    ariaLive?: string; // ARIA live region setting
+    ariaLabelledby?: string; // ARIA labelledby reference
+    ariaControls?: string; // ARIA controls reference
+    ariaHaspopup?: string; // ARIA haspopup attribute
+    ariaMultiselectable?: string; // ARIA multiselectable attribute
+    ariaAutocomplete?: string; // ARIA autocomplete attribute
+    event?: Record<string, EventListener>; // Event listeners mapped by event name
+    [key: string]: unknown; // Allow additional custom properties
 };
 
 /**
@@ -24,7 +24,9 @@ export type NodeSpec = {
  *
  * @template TTags - A map of tag names to their corresponding HTMLElement instances.
  */
-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
-};
+export type MountViewResult<
+    TTags extends Record<string, HTMLElement> = Record<string, HTMLElement>,
+> = {
+    view?: HTMLElement; // 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

@@ -7,9 +7,12 @@ import type { SelectivePlugin } from "../plugins/plugin.type";
  * Extends DefaultConfig with additional internal identifiers.
  */
 export type SelectiveOptions = DefaultConfig & {
-    SEID?: string;        // Unique Selective Element ID
-    SEID_LIST?: string;   // ID for the list container
-    SEID_HOLDER?: string; // ID for the holder element
+    /** Unique Selective Element ID */
+    SEID?: string;
+    /** ID for the list container */
+    SEID_LIST?: string;
+    /** ID for the holder element */
+    SEID_HOLDER?: string;
 };
 
 /**

package/src/ts/types/views/view.group.type.ts

@@ -5,9 +5,12 @@ import { MountViewResult } from "../utils/libs.type";
  * These tags correspond to key sections of the group UI.
  */
 export type GroupViewTags = {
-    GroupView: HTMLDivElement;    // Root container for the group view
-    GroupHeader: HTMLDivElement;  // Header section displaying the group title
-    GroupItems: HTMLDivElement;   // Container for the group's items
+    /** Root container for the group view */
+    GroupView: HTMLDivElement;
+    /** Header section displaying the group title */
+    GroupHeader: HTMLDivElement;
+    /** Container for the group's items */
+    GroupItems: HTMLDivElement;
 };
 
 /**
@@ -15,5 +18,6 @@ export type GroupViewTags = {
  * Extends MountViewResult with a guaranteed root element (`view`).
  */
 export type GroupViewResult = MountViewResult<GroupViewTags> & {
-    view: Element; // The root element of the mounted group view
-};
+    /** The root element of the mounted group view */
+    view: Element;
+};

package/src/ts/types/views/view.option.type.ts

@@ -5,11 +5,16 @@ import { MountViewResult } from "../utils/libs.type";
  * These tags correspond to key elements of the option UI.
  */
 export type OptionViewTags = {
-    OptionView: HTMLDivElement;      // Root container for the option view
-    OptionInput: HTMLInputElement;   // Input element (checkbox or radio)
-    OptionLabel: HTMLLabelElement;   // Label element for the option
-    LabelContent: HTMLDivElement;    // Container for label text content
-    OptionImage: HTMLImageElement;   // Image element for options with images
+    /** Root container for the option view */
+    OptionView: HTMLDivElement;
+    /** Input element (checkbox or radio) */
+    OptionInput: HTMLInputElement;
+    /** Label element for the option */
+    OptionLabel: HTMLLabelElement;
+    /** Container for label text content */
+    LabelContent: HTMLDivElement;
+    /** Image element for options with images */
+    OptionImage: HTMLImageElement;
 };
 
 /**
@@ -17,7 +22,8 @@ export type OptionViewTags = {
  * Extends MountViewResult with a guaranteed root element (`view`).
  */
 export type OptionViewResult = MountViewResult<OptionViewTags> & {
-    view: Element; // The root element of the mounted option view
+    /** The root element of the mounted option view */
+    view: Element;
 };
 
 /**
@@ -39,20 +45,36 @@ export type LabelHalign = "left" | "center" | "right";
  * Configuration options for rendering an option.
  */
 export type OptionConfig = {
-    isMultiple: boolean;           // Indicates if multiple selection is allowed
-    hasImage: boolean;             // Indicates if the option includes an image
-    imagePosition: ImagePosition;  // Position of the image relative to the label
-    imageWidth: string;            // Width of the image
-    imageHeight: string;           // Height of the image
-    imageBorderRadius: string;     // Border radius for the image
-    labelValign: LabelValign;      // Vertical alignment of the label
-    labelHalign: LabelHalign;      // Horizontal alignment of the label
+    /** Indicates if multiple selection is allowed */
+    isMultiple: boolean;
+    /** Indicates if the option includes an image */
+    hasImage: boolean;
+    /** Position of the image relative to the label */
+    imagePosition: ImagePosition;
+    /** Width of the image */
+    imageWidth: string;
+    /** Height of the image */
+    imageHeight: string;
+    /** Border radius for the image */
+    imageBorderRadius: string;
+    /** Vertical alignment of the label */
+    labelValign: LabelValign;
+    /** Horizontal alignment of the label */
+    labelHalign: LabelHalign;
 };
 
 /**
  * Partial configuration patch for updating specific option properties.
  * Includes only image and label alignment-related properties.
  */
-export type OptionConfigPatch = Partial<Pick<OptionConfig,
-    "imageWidth" | "imageHeight" | "imageBorderRadius" | "imagePosition" | "labelValign" | "labelHalign"
->>;
+export type OptionConfigPatch = Partial<
+    Pick<
+        OptionConfig,
+        | "imageWidth"
+        | "imageHeight"
+        | "imageBorderRadius"
+        | "imagePosition"
+        | "labelValign"
+        | "labelHalign"
+    >
+>;

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

@@ -1,4 +1,8 @@
-import { StoredEntry, TimerKey, TimerOptions } from "../types/utils/callback-scheduler.type";
+import {
+    StoredEntry,
+    TimerKey,
+    TimerOptions,
+} from "../types/utils/callback-scheduler.type";
 
 /**
  * CallbackScheduler
@@ -82,14 +86,14 @@ export class CallbackScheduler {
      *
      * @public
      * @param {TimerKey} key - Group identifier for callbacks.
-     * @param {(payload: any[] | null) => void} callback - Function to execute after debounce timeout.
+     * @param {(payload?: any[]) => void} callback - Function to execute after debounce timeout.
      * @param {TimerOptions} [options={}] - Scheduling options (`debounce`, `once`).
      * @returns {void}
      */
     public on(
         key: TimerKey,
-        callback: (payload: any[] | null) => void,
-        options: TimerOptions = {}
+        callback: (payload?: any[]) => void,
+        options: TimerOptions = {},
     ): void {
         const timeout = options.debounce ?? 50;
         const once = options.once ?? false;
@@ -176,13 +180,14 @@ export class CallbackScheduler {
                 const timer = setTimeout(async () => {
                     try {
                         const resp = entry.callback(
-                            params.length > 0 ? params : null
+                            params.length > 0 ? params : null,
                         ) as any;
 
                         if (resp instanceof Promise) {
                             await resp;
                         }
-                    } catch {} finally {
+                    } catch {
+                    } finally {
                         if (entry.once) {
                             executes[i] = undefined;
 
@@ -230,4 +235,4 @@ export class CallbackScheduler {
             this.off(k);
         }
     }
-}
+}

package/src/ts/utils/ievents.ts

@@ -1,4 +1,8 @@
-import { IEventCallback, IEventHandler, IEventToken } from "../types/utils/ievents.type";
+import {
+    IEventCallback,
+    IEventHandler,
+    IEventToken,
+} from "../types/utils/ievents.type";
 
 /**
  * iEvents
@@ -58,7 +62,10 @@ export class iEvents {
      * - `token`: immutable view of the dispatch state.
      * - `callback`: controller passed into handlers to modify dispatch flow.
      */
-    public static buildEventToken(): { token: IEventToken; callback: IEventCallback } {
+    public static buildEventToken(): {
+        token: IEventToken;
+        callback: IEventCallback;
+    } {
         const privToken = { isContinue: true, isCancel: false };
 
         const token: IEventToken = {
@@ -104,7 +111,7 @@ export class iEvents {
      * @returns The {@link IEventToken} describing the final dispatch state.
      */
     public static callEvent<TParams extends unknown[]>(
-        params: TParams | null,
+        params?: TParams,
         ...handles: Array<IEventHandler<TParams> | unknown>
     ): IEventToken {
         const { token, callback } = this.buildEventToken();
@@ -139,7 +146,7 @@ export class iEvents {
     public static trigger(
         element: HTMLElement | Window | Document,
         eventType: string,
-        opts: EventInit = { bubbles: true, cancelable: true }
+        opts: EventInit = { bubbles: true, cancelable: true },
     ): Event {
         const evt = new Event(eventType, opts);
         element.dispatchEvent(evt);
@@ -167,4 +174,4 @@ export class iEvents {
             (fn as (...args: TParams) => unknown)(...params);
         }
     }
-}
+}

package/src/ts/utils/istorage.ts

@@ -61,11 +61,13 @@ export class iStorage {
     };
 
     /** Bound instance map (keyed by select element). */
-    public bindedMap: Map<HTMLSelectElement|HTMLElement, BinderMap> = new Map();
+    public bindedMap: Map<HTMLSelectElement | HTMLElement, BinderMap> =
+        new Map();
 
     /** Unbind cache map (keyed by select element). */
-    public unbindedMap: Map<HTMLSelectElement|HTMLElement, BinderMap> = new Map();
+    public unbindedMap: Map<HTMLSelectElement | HTMLElement, BinderMap> =
+        new Map();
 
     /** List of bound selectors/commands. */
     public bindedCommand: string[] = [];
-}
+}