selective-ui 1.2.4 → 1.2.6

package/src/ts/components/option-handle.ts

@@ -6,58 +6,98 @@ import { iEvents } from "../utils/ievents";
 import { Libs } from "../utils/libs";
 
 /**
- * UI control that exposes "Select All" / "Deselect All" actions
- * for multiple-selection lists.
+ * OptionHandle
  *
- * Responsibilities:
- * - Renders two action controls (links/buttons)
- * - Shows/hides itself based on configuration flags
- * - Allows registration of callbacks for both actions
- * - Participates in the standard `Lifecycle`
+ * Headless-friendly, DOM-driven UI control that exposes bulk selection actions
+ * ("Select all" / "Deselect all") for multiple-selection experiences.
  *
- * Visibility rule:
- * - Visible only when `options.multiple` and `options.selectall` are truthy.
+ * ### Responsibility
+ * - Creates and owns a small DOM subtree (root + two action elements).
+ * - Exposes registration APIs for action callbacks (`onSelectAll`, `onDeSelectAll`).
+ * - Reflects feature flags from {@link SelectiveOptions} by showing/hiding itself.
+ * - Participates in the library {@link Lifecycle} finite-state machine (FSM).
+ *
+ * ### Lifecycle (Strict FSM)
+ * - Constructed in `NEW`.
+ * - {@link initialize} builds DOM and calls `init()` → transitions to `INITIALIZED`.
+ * - {@link update} is safe to call repeatedly; it re-evaluates visibility and then
+ *   delegates to `super.update()` (idempotent once in `UPDATED`).
+ * - {@link destroy} is a terminal transition; subsequent calls are no-ops.
+ *
+ * ### Event / Callback Flow
+ * - User interaction is handled via DOM `onclick` handlers bound during initialization.
+ * - On click, this component dispatches callbacks through {@link iEvents.callFunctions}.
+ * - This class does not own selection state; it only emits intent via callbacks.
+ *
+ * ### Visibility Contract
+ * Visible only when BOTH flags are enabled:
+ * - `options.multiple` truthy (after {@link Libs.string2Boolean} coercion)
+ * - `options.selectall` truthy (after {@link Libs.string2Boolean} coercion)
+ *
+ * ### DOM / a11y Notes
+ * - Uses `<a>` elements as action triggers. This is a DOM-side effect and may have
+ *   accessibility implications depending on `href`, keyboard handling, and ARIA.
  *
  * @extends Lifecycle
  */
 export class OptionHandle extends Lifecycle {
-
     /**
-     * Internal reference to the mounted node structure returned by `Libs.mountNode`.
-     * Used to access typed tags if needed. Null before initialization.
+     * Result returned by {@link Libs.mountNode}.
+     *
+     * Stores the mounted view structure so the component can keep a stable reference
+     * to its created DOM nodes. `null` before {@link initialize}.
+     *
+     * @internal
      */
-    private nodeMounted: MountViewResult<any> | null = null;
+    private nodeMounted: MountViewResult | null = null;
 
     /**
-     * Root DOM element of the option handle component.
-     * Created during initialization and removed on destroy.
+     * Root element of this control.
+     *
+     * Created during {@link initialize}. This node is used by {@link show}/{@link hide}
+     * and removed during {@link destroy}.
      */
     public node: HTMLDivElement | null = null;
 
     /**
-     * Configuration options controlling labels and feature flags.
-     * (e.g., textSelectAll, textDeselectAll, multiple, selectall)
+     * Configuration snapshot used for:
+     * - labels (`textSelectAll`, `textDeselectAll`)
+     * - feature flags (`multiple`, `selectall`)
+     *
+     * Treated as read-only after initialization; cleared on {@link destroy}.
+     *
+     * @internal
      */
     private options: SelectiveOptions | null = null;
 
     /**
-     * Registered callbacks executed when "Select All" is activated.
+     * Callback list invoked when the "Select all" control is activated.
+     *
+     * Callbacks are invoked via {@link iEvents.callFunctions}. This component does not
+     * interpret arguments; it delegates invocation semantics to the dispatcher helper.
+     *
+     * @internal
      */
     private actionOnSelectAll: Array<(...args: unknown[]) => unknown> = [];
 
     /**
-     * Registered callbacks executed when "Deselect All" is activated.
+     * Callback list invoked when the "Deselect all" control is activated.
+     *
+     * Callbacks are invoked via {@link iEvents.callFunctions}. This component does not
+     * interpret arguments; it delegates invocation semantics to the dispatcher helper.
+     *
+     * @internal
      */
     private actionOnDeSelectAll: Array<(...args: unknown[]) => unknown> = [];
 
     /**
-     * Creates a new OptionHandle control.
+     * Creates an {@link OptionHandle}.
      *
-     * If `options` are provided, the component is initialized immediately and
-     * enters the lifecycle (init). Otherwise, call a custom initializer later
-     * to set it up.
+     * If `options` is provided, the instance immediately performs {@link initialize}
+     * and enters the {@link Lifecycle} (calls `init()` internally).
+     * If `options` is `null`, the instance stays in `NEW` until initialized elsewhere.
      *
-     * @param options - Configuration with texts and feature flags.
+     * @param options - Feature flags and labels for the two actions.
      */
     public constructor(options: SelectiveOptions | null = null) {
         super();
@@ -65,26 +105,33 @@ export class OptionHandle extends Lifecycle {
     }
 
     /**
-     * Initializes the option handle UI.
+     * Initializes DOM and binds event handlers.
+     *
+     * DOM structure (conceptually):
+     * - Root: `div.seui-option-handle.hide`
+     * - Child: `a.seui-option-handle-item` ("Select all")
+     * - Child: `a.seui-option-handle-item` ("Deselect all")
      *
-     * Builds the DOM:
-     * - Root: `.selective-ui-option-handle.hide`
-     * - Children: "Select All" and "Deselect All" controls
+     * Click handlers:
+     * - "Select all" → dispatches {@link actionOnSelectAll} via {@link iEvents.callFunctions}
+     * - "Deselect all" → dispatches {@link actionOnDeSelectAll} via {@link iEvents.callFunctions}
      *
-     * Wires their click handlers to invoke registered callbacks
-     * via the `iEvents.callFunctions` helper.
+     * Side effects:
+     * - Creates DOM nodes (via {@link Libs.mountNode})
+     * - Transitions lifecycle by calling `init()` at the end
      *
      * @param options - Configuration providing labels and feature flags.
+     * @internal
      */
     private initialize(options: SelectiveOptions): void {
-        this.nodeMounted = Libs.mountNode({
+        this.nodeMounted = Libs.mountNode<MountViewResult>({
             OptionHandle: {
-                tag: { node: "div", classList: ["selective-ui-option-handle", "hide"] },
+                tag: { node: "div", classList: ["seui-option-handle", "hide"] },
                 child: {
                     SelectAll: {
                         tag: {
                             node: "a",
-                            classList: "selective-ui-option-handle-item",
+                            classList: "seui-option-handle-item",
                             textContent: options.textSelectAll,
                             onclick: () => {
                                 iEvents.callFunctions(this.actionOnSelectAll);
@@ -94,7 +141,7 @@ export class OptionHandle extends Lifecycle {
                     DeSelectAll: {
                         tag: {
                             node: "a",
-                            classList: "selective-ui-option-handle-item",
+                            classList: "seui-option-handle-item",
                             textContent: options.textDeselectAll,
                             onclick: () => {
                                 iEvents.callFunctions(this.actionOnDeSelectAll);
@@ -103,7 +150,7 @@ export class OptionHandle extends Lifecycle {
                     },
                 },
             },
-        }) as MountViewResult<any>;
+        });
 
         this.node = this.nodeMounted.view as HTMLDivElement;
         this.options = options;
@@ -112,14 +159,16 @@ export class OptionHandle extends Lifecycle {
     }
 
     /**
-     * Returns whether the handle should be available (and thus visible)
-     * based on current configuration flags.
+     * Computes whether this control is enabled/available under current configuration.
      *
-     * Availability requires:
-     * - `multiple` is truthy
-     * - `selectall` is truthy
+     * This method performs a boolean coercion using {@link Libs.string2Boolean} to
+     * support string-like flags in {@link SelectiveOptions}.
      *
-     * @returns True if both features are enabled; otherwise false.
+     * No-ops:
+     * - Returns `false` when {@link options} has not been set.
+     *
+     * @returns `true` when both `multiple` and `selectall` are enabled; otherwise `false`.
+     * @internal
      */
     private available(): boolean {
         if (!this.options) return false;
@@ -127,12 +176,17 @@ export class OptionHandle extends Lifecycle {
     }
 
     /**
-     * Refreshes the visibility based on `available()` and emits the update lifecycle.
+     * Re-evaluates visibility and advances the lifecycle update step.
+     *
+     * Behavior:
+     * - If {@link node} exists, toggles the `hide` class based on {@link available}.
+     * - Always delegates to `super.update()` to participate in the FSM transition.
      *
-     * - Shows the handle when available
-     * - Hides it otherwise
+     * Idempotency:
+     * - Repeated calls remain safe; DOM class toggling is stable and the underlying
+     *   {@link Lifecycle} update is expected to be idempotent after the first transition.
      *
-     * Note: `super.update()` transitions lifecycle to `UPDATED` (idempotent after first call).
+     * @override
      */
     public override update(): void {
         if (this.node) {
@@ -147,9 +201,9 @@ export class OptionHandle extends Lifecycle {
     }
 
     /**
-     * Makes the option handle visible.
+     * Shows the control by removing the `hide` CSS class on the root node.
      *
-     * Removes the `hide` class from the root node.
+     * No-ops when {@link node} is `null`.
      */
     public show(): void {
         if (!this.node) return;
@@ -157,9 +211,9 @@ export class OptionHandle extends Lifecycle {
     }
 
     /**
-     * Hides the option handle.
+     * Hides the control by adding the `hide` CSS class on the root node.
      *
-     * Adds the `hide` class to the root node.
+     * No-ops when {@link node} is `null`.
      */
     public hide(): void {
         if (!this.node) return;
@@ -167,12 +221,15 @@ export class OptionHandle extends Lifecycle {
     }
 
     /**
-     * Registers a callback for the "Select All" action.
+     * Registers a callback for the external "Select all" intent.
      *
-     * The callback will be invoked with the arguments provided
-     * by the action dispatcher (if any).
+     * Notes:
+     * - This is an "external event" hook: it notifies the host/controller layer that a
+     *   bulk action was requested. This component does not mutate selection state itself.
+     * - Callbacks are executed by {@link iEvents.callFunctions} when the corresponding
+     *   DOM control is activated.
      *
-     * @param action - Function to execute when "Select All" is triggered.
+     * @param action - Callback invoked on activation; ignored when not a function.
      */
     public onSelectAll(action: ((...args: unknown[]) => unknown) | null = null): void {
         if (typeof action === "function") {
@@ -181,12 +238,15 @@ export class OptionHandle extends Lifecycle {
     }
 
     /**
-     * Registers a callback for the "Deselect All" action.
+     * Registers a callback for the external "Deselect all" intent.
      *
-     * The callback will be invoked with the arguments provided
-     * by the action dispatcher (if any).
+     * Notes:
+     * - This is an "external event" hook: it notifies the host/controller layer that a
+     *   bulk deselection was requested. This component does not mutate selection state itself.
+     * - Callbacks are executed by {@link iEvents.callFunctions} when the corresponding
+     *   DOM control is activated.
      *
-     * @param action - Function to execute when "Deselect All" is triggered.
+     * @param action - Callback invoked on activation; ignored when not a function.
      */
     public onDeSelectAll(action: ((...args: unknown[]) => unknown) | null = null): void {
         if (typeof action === "function") {
@@ -195,10 +255,17 @@ export class OptionHandle extends Lifecycle {
     }
 
     /**
-     * Destroys the option handle component.
+     * Tears down DOM resources and terminates the lifecycle.
+     *
+     * Strict FSM / idempotency:
+     * - If already in {@link LifecycleState.DESTROYED}, this method returns immediately.
+     *
+     * Side effects:
+     * - Removes the root DOM node from the document (if present).
+     * - Clears references to options and callback lists to allow GC.
+     * - Delegates to `super.destroy()` to finalize the lifecycle transition.
      *
-     * Removes the DOM node, clears stored options,
-     * and terminates the lifecycle.
+     * @override
      */
     public override destroy(): void {
         if (this.is(LifecycleState.DESTROYED)) {

package/src/ts/components/placeholder.ts

@@ -4,37 +4,63 @@ import { SelectiveOptions } from "../types/utils/selective.type";
 import { Libs } from "../utils/libs";
 
 /**
- * UI component representing a placeholder for the Select UI.
+ * PlaceHolder
  *
- * The placeholder displays contextual guidance when no value is selected.
- * It supports dynamic updates and optional HTML content, depending on configuration.
+ * DOM-driven placeholder view for the Select UI when no value is selected.
+ * This component is intentionally minimal: it owns a single DOM node and exposes
+ * getter/setter APIs for the placeholder content.
  *
- * The component manages a single DOM node and participates
- * in the standard `Lifecycle`.
+ * ### Responsibility
+ * - Create and own the placeholder DOM element (`.seui-placeholder`).
+ * - Render placeholder content from {@link SelectiveOptions.placeholder}.
+ * - Support runtime updates via {@link set}, optionally persisting into options.
+ * - Participate in the shared {@link Lifecycle} FSM.
+ *
+ * ### Lifecycle (Strict FSM)
+ * - Constructed in `NEW`.
+ * - {@link initialize} creates DOM and calls `init()` → transitions to `INITIALIZED`.
+ * - Updates are data-driven via {@link set}; this class does not override `update()`.
+ * - {@link destroy} removes the DOM node and clears references; repeat calls are no-ops
+ *   once {@link LifecycleState.DESTROYED}.
+ *
+ * ### DOM / Rendering Notes
+ * - Content is written through `innerHTML` (DOM side effect).
+ * - {@link Libs.tagTranslate} is applied to the incoming value before rendering.
+ * - When `options.allowHtml` is falsy, HTML is stripped via {@link Libs.stripHtml}
+ *   to reduce injection risk. When truthy, translated HTML is rendered as-is.
  *
  * @extends Lifecycle
  */
 export class PlaceHolder extends Lifecycle {
-
     /**
-     * Root DOM element of the placeholder component.
-     * Created during initialization and removed on destroy.
+     * Root DOM element for the placeholder.
+     *
+     * Created during {@link initialize}. Removed from the DOM during {@link destroy}.
+     * `null` before initialization and after destruction.
      */
     public node: HTMLElement | null = null;
 
     /**
-     * Configuration options containing placeholder text
-     * and rendering preferences (e.g., allowHtml).
+     * Configuration snapshot used to render and optionally persist placeholder content.
+     *
+     * Key fields used by this component:
+     * - `placeholder`: initial/current placeholder text/markup
+     * - `allowHtml`: controls whether HTML is rendered or stripped
+     *
+     * Cleared during {@link destroy}.
+     *
+     * @internal
      */
     private options: SelectiveOptions | null = null;
 
     /**
-     * Creates a new PlaceHolder instance.
+     * Creates a new {@link PlaceHolder}.
      *
-     * If options are provided, the component is initialized immediately.
+     * If `options` is provided, the component initializes immediately and enters the
+     * {@link Lifecycle} by calling `init()` internally. If `options` is `null`, the
+     * instance remains in `NEW` until initialized elsewhere (by design).
      *
-     * @param options - Configuration object containing placeholder text
-     *                  and HTML rendering settings.
+     * @param options - Select UI options containing placeholder content and rendering flags.
      */
     constructor(options: SelectiveOptions | null) {
         super();
@@ -42,20 +68,22 @@ export class PlaceHolder extends Lifecycle {
     }
 
     /**
-     * Initializes the placeholder component.
+     * Builds the placeholder DOM node and starts the lifecycle.
      *
-     * Creates the DOM node, applies base styling,
-     * renders the initial placeholder content,
-     * stores configuration options, and starts the lifecycle.
+     * Side effects:
+     * - Creates a `div.seui-placeholder` node via {@link Libs.nodeCreator}.
+     * - Writes initial placeholder content into `innerHTML`.
+     * - Transitions the lifecycle by calling `init()`.
      *
-     * @param options - Configuration object containing placeholder settings.
+     * @param options - Options providing placeholder content and rendering behavior.
+     * @internal
      */
     private initialize(options: SelectiveOptions): void {
-        this.node = Libs.nodeCreator({
+        this.node = Libs.nodeCreator<HTMLElement>({
             node: "div",
-            classList: "selective-ui-placeholder",
+            classList: "seui-placeholder",
             innerHTML: options.placeholder,
-        }) as HTMLElement;
+        });
 
         this.options = options;
 
@@ -63,25 +91,29 @@ export class PlaceHolder extends Lifecycle {
     }
 
     /**
-     * Returns the current placeholder text from the configuration.
+     * Returns the current placeholder content as stored in {@link options}.
+     *
+     * This method does not read from the DOM; it returns the configuration value.
      *
-     * @returns The current placeholder value, or an empty string if not set.
+     * @returns The configured placeholder string, or an empty string if uninitialized.
      */
     public get(): string {
         return this.options?.placeholder ?? "";
     }
 
     /**
-     * Updates the placeholder content.
+     * Updates the rendered 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
+     * Behavior:
+     * - No-ops if the component is not initialized (`node`/`options` missing).
+     * - Optionally persists the new value back into {@link options.placeholder}.
+     * - Applies {@link Libs.tagTranslate} before rendering.
+     * - Renders using `innerHTML`:
+     *   - If `options.allowHtml` is truthy, renders translated HTML.
+     *   - Otherwise, strips HTML via {@link Libs.stripHtml} and renders safe text/markup.
      *
-     * @param value - The new placeholder content.
-     * @param isSave - Whether to persist the value in the configuration.
-     *                 Defaults to `true`.
+     * @param value - New placeholder content to render.
+     * @param isSave - When `true` (default), also updates {@link options.placeholder}.
      */
     public set(value: string, isSave: boolean = true): void {
         if (!this.node || !this.options) return;
@@ -97,10 +129,16 @@ export class PlaceHolder extends Lifecycle {
     }
 
     /**
-     * Destroys the placeholder component.
+     * Disposes the placeholder DOM and terminates the lifecycle.
+     *
+     * Strict FSM / idempotency:
+     * - If already {@link LifecycleState.DESTROYED}, returns immediately.
+     *
+     * Side effects:
+     * - Removes {@link node} from the DOM (if present).
+     * - Clears references to allow garbage collection.
      *
-     * Removes the DOM node, clears stored options,
-     * and terminates the lifecycle.
+     * @override
      */
     public override destroy(): void {
         if (this.is(LifecycleState.DESTROYED)) {

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

@@ -5,37 +5,61 @@ import { SelectiveOptions } from "../../types/utils/selective.type";
 import { Libs } from "../../utils/libs";
 
 /**
- * UI component that represents an empty state.
+ * Lightweight UI state box that renders contextual "empty" feedback.
  *
- * The empty state is used to display contextual feedback when:
- * - No data is available
- * - A search yields no matching results
+ * ### Responsibility
+ * - Owns a single DOM node that can be shown/hidden to communicate:
+ *   - **No data** (no options available)
+ *   - **Not found** (search produced zero visible results)
+ * - Exposes a minimal imperative API (`show`, `hide`, `isVisible`) used by higher-level
+ *   controllers/components (e.g., popup/search flows).
  *
- * It manages a single DOM node and participates in the standard lifecycle.
+ * ### Lifecycle (Strict FSM)
+ * - Constructed in `NEW`. When `options` are provided, {@link initialize} is called and the
+ *   instance transitions to `INITIALIZED` via {@link Lifecycle.init}.
+ * - This component does not automatically mount itself into a container; consumers are expected
+ *   to append {@link node} where appropriate.
+ * - {@link destroy} removes the node and transitions to `DESTROYED`.
+ *
+ * ### Idempotency / No-ops
+ * - {@link show} and {@link hide} are **no-ops** until {@link node} exists.
+ * - {@link destroy} is idempotent once in {@link LifecycleState.DESTROYED}.
+ *
+ * ### Accessibility / DOM side effects
+ * - Uses `role="status"` and `aria-live="polite"` so screen readers announce changes without
+ *   interrupting the user.
+ * - Visibility is controlled via the `"hide"` CSS class; hiding does not remove the element.
  *
  * @extends Lifecycle
+ * @see {@link LifecycleState}
+ * @see {@link EmptyStateType}
  */
 export class EmptyState extends Lifecycle {
-
     /**
-     * Root DOM element of the empty state component.
-     * Created during initialization and removed on destroy.
+     * Root DOM element for the empty state UI.
+     *
+     * - Created during {@link initialize}.
+     * - Intended to be appended by the parent container (component does not auto-attach).
+     * - Removed from DOM during {@link destroy}.
      */
     public node: HTMLDivElement | null = null;
 
     /**
-     * Configuration options providing display text
-     * for different empty state scenarios.
+     * Configuration source for empty state messages.
+     *
+     * Expected to provide at least:
+     * - `textNoData` (for `"nodata"`)
+     * - `textNotFound` (for `"notfound"`)
      */
     public options: SelectiveOptions | null = null;
 
     /**
-     * Creates a new EmptyState instance.
+     * Creates a new {@link EmptyState}.
      *
-     * If options are provided, the component is initialized immediately.
+     * If `options` are provided, initialization runs immediately (creates {@link node} and
+     * transitions to `INITIALIZED`).
      *
-     * @param options - Configuration containing messages for
-     *                  "no data" and "not found" states.
+     * @param {SelectiveOptions | null} [options=null] - Configuration containing empty state messages.
      */
     public constructor(options: SelectiveOptions | null = null) {
         super();
@@ -43,35 +67,39 @@ export class EmptyState extends Lifecycle {
     }
 
     /**
-     * Initializes the empty state component.
+     * Initializes internal resources for this component.
      *
-     * Creates the root DOM element, applies accessibility attributes,
-     * stores configuration options, and starts the lifecycle.
+     * Side effects:
+     * - Creates the root `div` node with `role="status"` and `aria-live="polite"`.
+     * - Applies base CSS classes: `"seui-empty-state"` and `"hide"`.
+     * - Stores the options reference and calls {@link Lifecycle.init}.
      *
-     * @param options - Configuration object containing empty state messages.
+     * @param {SelectiveOptions} options - Configuration object containing empty state messages.
+     * @returns {void}
      */
     private initialize(options: SelectiveOptions): void {
         this.options = options;
 
-        this.node = Libs.nodeCreator({
+        this.node = Libs.nodeCreator<HTMLDivElement>({
             node: "div",
-            classList: ["selective-ui-empty-state", "hide"],
+            classList: ["seui-empty-state", "hide"],
             role: "status",
             ariaLive: "polite",
-        }) as HTMLDivElement;
+        });
 
         this.init();
     }
 
     /**
-     * Displays the empty state message.
+     * Shows the empty state message for the given scenario.
      *
-     * The message content depends on the provided type:
-     * - `"nodata"`: no data available
-     * - `"notfound"`: no matching search results
+     * - `"nodata"`: uses `options.textNoData`
+     * - `"notfound"`: uses `options.textNotFound`
      *
-     * @param type - Type of empty state to display.
-     *               Defaults to `"nodata"`.
+     * No-op if {@link node} or {@link options} are not initialized.
+     *
+     * @param {EmptyStateType} [type="nodata"] - Which empty state message to display.
+     * @returns {void}
      */
     public show(type: EmptyStateType = "nodata"): void {
         if (!this.node || !this.options) return;
@@ -86,10 +114,12 @@ export class EmptyState extends Lifecycle {
     }
 
     /**
-     * Hides the empty state component.
+     * Hides the empty state node by applying the `"hide"` CSS class.
+     *
+     * This does not remove the element from the DOM.
+     * No-op if {@link node} is not initialized.
      *
-     * This does not remove the element from the DOM;
-     * it only updates its visibility via CSS.
+     * @returns {void}
      */
     public hide(): void {
         if (!this.node) return;
@@ -97,19 +127,25 @@ export class EmptyState extends Lifecycle {
     }
 
     /**
-     * Indicates whether the empty state is currently visible.
+     * Whether the empty state is currently visible.
      *
-     * @returns True if the empty state is shown; otherwise false.
+     * @returns {boolean} `true` when {@link node} exists and does not have the `"hide"` class.
      */
     public get isVisible(): boolean {
         return !!this.node && !this.node.classList.contains("hide");
     }
 
     /**
-     * Destroys the empty state component.
+     * Releases resources owned by this component.
+     *
+     * - Removes the root DOM node (if present).
+     * - Clears stored options and internal references.
+     * - Transitions to `DESTROYED`.
+     *
+     * Idempotent: returns early if already in {@link LifecycleState.DESTROYED}.
      *
-     * Removes the DOM node, clears stored options,
-     * and terminates the lifecycle.
+     * @returns {void}
+     * @override
      */
     public override destroy(): void {
         if (this.is(LifecycleState.DESTROYED)) {