selective-ui 1.2.3 → 1.2.4

package/src/ts/components/placeholder.ts

@@ -1,28 +1,56 @@
+import { Lifecycle } from "../core/base/lifecycle";
+import { LifecycleState } from "../types/core/base/lifecycle.type";
 import { SelectiveOptions } from "../types/utils/selective.type";
 import { Libs } from "../utils/libs";
 
 /**
- * @class
+ * UI component representing a placeholder for the Select UI.
+ *
+ * The placeholder displays contextual guidance when no value is selected.
+ * It supports dynamic updates and optional HTML content, depending on configuration.
+ *
+ * The component manages a single DOM node and participates
+ * in the standard `Lifecycle`.
+ *
+ * @extends Lifecycle
  */
-export class PlaceHolder {
+export class PlaceHolder extends Lifecycle {
+
+    /**
+     * Root DOM element of the placeholder component.
+     * Created during initialization and removed on destroy.
+     */
     public node: HTMLElement | null = null;
 
+    /**
+     * Configuration options containing placeholder text
+     * and rendering preferences (e.g., allowHtml).
+     */
     private options: SelectiveOptions | null = null;
 
     /**
-     * Represents a placeholder component for the Select UI, allowing dynamic updates to placeholder text.
-     * Supports HTML content based on configuration and provides methods to get or set the placeholder value.
+     * Creates a new PlaceHolder instance.
+     *
+     * If options are provided, the component is initialized immediately.
+     *
+     * @param options - Configuration object containing placeholder text
+     *                  and HTML rendering settings.
      */
     constructor(options: SelectiveOptions | null) {
-        if (options) this.init(options);
+        super();
+        if (options) this.initialize(options);
     }
 
     /**
-     * Initializes the placeholder element with provided options and renders its initial content.
+     * Initializes the placeholder component.
+     *
+     * Creates the DOM node, applies base styling,
+     * renders the initial placeholder content,
+     * stores configuration options, and starts the lifecycle.
      *
-     * @param {object} options - Configuration object containing placeholder text and HTML allowance.
+     * @param options - Configuration object containing placeholder settings.
      */
-    private init(options: SelectiveOptions): void {
+    private initialize(options: SelectiveOptions): void {
         this.node = Libs.nodeCreator({
             node: "div",
             classList: "selective-ui-placeholder",
@@ -30,30 +58,59 @@ export class PlaceHolder {
         }) as HTMLElement;
 
         this.options = options;
+
+        this.init();
     }
 
     /**
-     * Retrieves the current placeholder text from the configuration.
+     * Returns the current placeholder text from the configuration.
      *
-     * @returns {string} - The current placeholder text.
+     * @returns The current placeholder value, or an empty string if not set.
      */
     public get(): string {
         return this.options?.placeholder ?? "";
     }
 
     /**
-     * Updates the placeholder text and optionally saves it to the configuration.
-     * Applies HTML sanitization based on the allowHtml setting.
+     * Updates the placeholder content.
+     *
+     * The value can optionally be persisted back into the configuration.
+     * HTML rendering is controlled by the `allowHtml` option:
+     * - When enabled, translated HTML is rendered
+     * - When disabled, HTML tags are stripped for safety
      *
-     * @param {string} value - The new placeholder text.
-     * @param {boolean} [isSave=true] - Whether to persist the new value in the configuration.
+     * @param value - The new placeholder content.
+     * @param isSave - Whether to persist the value in the configuration.
+     *                 Defaults to `true`.
      */
     public set(value: string, isSave: boolean = true): void {
         if (!this.node || !this.options) return;
 
-        if (isSave) this.options.placeholder = value;
+        if (isSave) {
+            this.options.placeholder = value;
+        }
 
         const translated = Libs.tagTranslate(value);
-        this.node.innerHTML = this.options.allowHtml ? translated : Libs.stripHtml(translated);
+        this.node.innerHTML = this.options.allowHtml
+            ? translated
+            : Libs.stripHtml(translated);
+    }
+
+    /**
+     * Destroys the placeholder component.
+     *
+     * Removes the DOM node, clears stored options,
+     * and terminates the lifecycle.
+     */
+    public override destroy(): void {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        
+        this.node?.remove();
+        this.node = null;
+        this.options = null;
+
+        super.destroy();
     }
 }

package/src/ts/components/popup/empty-state.ts

@@ -0,0 +1,126 @@
+import { Lifecycle } from "../../core/base/lifecycle";
+import { EmptyStateType } from "../../types/components/state.box.type";
+import { LifecycleState } from "../../types/core/base/lifecycle.type";
+import { SelectiveOptions } from "../../types/utils/selective.type";
+import { Libs } from "../../utils/libs";
+
+/**
+ * UI component that represents an empty state.
+ *
+ * The empty state is used to display contextual feedback when:
+ * - No data is available
+ * - A search yields no matching results
+ *
+ * It manages a single DOM node and participates in the standard lifecycle.
+ *
+ * @extends Lifecycle
+ */
+export class EmptyState extends Lifecycle {
+
+    /**
+     * Root DOM element of the empty state component.
+     * Created during initialization and removed on destroy.
+     */
+    public node: HTMLDivElement | null = null;
+
+    /**
+     * Configuration options providing display text
+     * for different empty state scenarios.
+     */
+    public options: SelectiveOptions | null = null;
+
+    /**
+     * Creates a new EmptyState instance.
+     *
+     * If options are provided, the component is initialized immediately.
+     *
+     * @param options - Configuration containing messages for
+     *                  "no data" and "not found" states.
+     */
+    public constructor(options: SelectiveOptions | null = null) {
+        super();
+        if (options) this.initialize(options);
+    }
+
+    /**
+     * Initializes the empty state component.
+     *
+     * Creates the root DOM element, applies accessibility attributes,
+     * stores configuration options, and starts the lifecycle.
+     *
+     * @param options - Configuration object containing empty state messages.
+     */
+    private initialize(options: SelectiveOptions): void {
+        this.options = options;
+
+        this.node = Libs.nodeCreator({
+            node: "div",
+            classList: ["selective-ui-empty-state", "hide"],
+            role: "status",
+            ariaLive: "polite",
+        }) as HTMLDivElement;
+
+        this.init();
+    }
+
+    /**
+     * Displays the empty state message.
+     *
+     * The message content depends on the provided type:
+     * - `"nodata"`: no data available
+     * - `"notfound"`: no matching search results
+     *
+     * @param type - Type of empty state to display.
+     *               Defaults to `"nodata"`.
+     */
+    public show(type: EmptyStateType = "nodata"): void {
+        if (!this.node || !this.options) return;
+
+        const text =
+            type === "notfound"
+                ? this.options.textNotFound
+                : this.options.textNoData;
+
+        this.node.textContent = text;
+        this.node.classList.remove("hide");
+    }
+
+    /**
+     * Hides the empty state component.
+     *
+     * This does not remove the element from the DOM;
+     * it only updates its visibility via CSS.
+     */
+    public hide(): void {
+        if (!this.node) return;
+        this.node.classList.add("hide");
+    }
+
+    /**
+     * Indicates whether the empty state is currently visible.
+     *
+     * @returns True if the empty state is shown; otherwise false.
+     */
+    public get isVisible(): boolean {
+        return !!this.node && !this.node.classList.contains("hide");
+    }
+
+    /**
+     * Destroys the empty state component.
+     *
+     * Removes the DOM node, clears stored options,
+     * and terminates the lifecycle.
+     */
+    public override destroy(): void {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+
+        this.options = null;
+
+        this.node?.remove();
+        this.node = null;
+
+        super.destroy();
+    }
+}

package/src/ts/components/popup/loading-state.ts

@@ -0,0 +1,120 @@
+import { Lifecycle } from "../../core/base/lifecycle";
+import { LifecycleState } from "../../types/core/base/lifecycle.type";
+import { SelectiveOptions } from "../../types/utils/selective.type";
+import { Libs } from "../../utils/libs";
+
+/**
+ * UI component representing a loading state.
+ *
+ * The loading state is displayed while data is being fetched,
+ * processed, or updated asynchronously.
+ *
+ * It manages a single DOM element and participates in the
+ * standard lifecycle provided by `Lifecycle`.
+ *
+ * @extends Lifecycle
+ */
+export class LoadingState extends Lifecycle {
+
+    /**
+     * Root DOM element of the loading state component.
+     * Created during initialization and removed on destroy.
+     */
+    public node: HTMLDivElement | null = null;
+
+    /**
+     * Configuration options containing the loading message text.
+     */
+    public options: SelectiveOptions | null = null;
+
+    /**
+     * Creates a new LoadingState instance.
+     *
+     * If options are provided, the component is initialized immediately.
+     *
+     * @param options - Configuration object containing the loading message text.
+     */
+    public constructor(options: SelectiveOptions | null = null) {
+        super();
+        if (options) this.initialize(options);
+    }
+
+    /**
+     * Initializes the loading state component.
+     *
+     * Creates the root DOM element, sets the initial loading text,
+     * applies accessibility attributes, stores configuration options,
+     * and starts the lifecycle.
+     *
+     * @param options - Configuration object containing loading text.
+     */
+    private initialize(options: SelectiveOptions): void {
+        this.options = options;
+
+        this.node = Libs.nodeCreator({
+            node: "div",
+            classList: ["selective-ui-loading-state", "hide"],
+            textContent: options.textLoading,
+            role: "status",
+            ariaLive: "polite",
+        }) as HTMLDivElement;
+
+        this.init();
+    }
+
+    /**
+     * Displays the loading state.
+     *
+     * When items are already present, the loading state can be shown
+     * in a compact form by applying a reduced ("small") style.
+     *
+     * @param hasItems - True if existing items are present,
+     *                   enabling a compact loading indicator.
+     */
+    public show(hasItems: boolean): void {
+        if (!this.node || !this.options) return;
+
+        this.node.textContent = this.options.textLoading;
+        this.node.classList.toggle("small", !!hasItems);
+        this.node.classList.remove("hide");
+    }
+
+    /**
+     * Hides the loading state.
+     *
+     * This only toggles visibility via CSS and does not
+     * remove the element from the DOM.
+     */
+    public hide(): void {
+        if (!this.node) return;
+        this.node.classList.add("hide");
+    }
+
+    /**
+     * Indicates whether the loading state is currently visible.
+     *
+     * @returns True if the loading indicator is shown; otherwise false.
+     */
+    public get isVisible(): boolean {
+        return !!this.node && !this.node.classList.contains("hide");
+    }
+
+    /**
+     * Destroys the loading state component.
+     *
+     * Removes the DOM node, clears stored options,
+     * and terminates the lifecycle.
+     */
+    public override destroy(): void {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+
+        this.options = null;
+
+        this.node?.remove();
+        this.node = null;
+
+        super.destroy();
+    }
+}