selective-ui 1.2.4 → 1.2.6

package/src/ts/views/option-view.ts

@@ -1,4 +1,3 @@
-
 import { View } from "../core/base/view";
 import { Libs } from "../utils/libs";
 import type {
@@ -9,52 +8,144 @@ import type {
 } from "../types/views/view.option.type";
 
 /**
- * View implementation for a single selectable option.
+ * OptionView
+ *
+ * View implementation for a single selectable option with reactive configuration.
+ *
+ * ### Responsibility
+ * - Renders an option with input (radio/checkbox) + optional image + label.
+ * - Supports **reactive configuration** via Proxy-based change tracking.
+ * - Applies **incremental DOM updates** for configuration changes (no full re-render).
+ * - Manages input type switching (radio ↔ checkbox) based on selection mode.
+ * - Dynamically creates/removes image elements when {@link hasImage} changes.
+ *
+ * ### Structure
+ * ```
+ * OptionView (root, role="option")
+ *   ├─ OptionInput (<input type="radio|checkbox">)
+ *   ├─ OptionImage (<img>, conditional)
+ *   └─ OptionLabel (<label>)
+ *       └─ LabelContent (<div>)
+ * ```
+ *
+ * ### Lifecycle (View-based FSM)
+ * - **Construction**: Calls {@link initialize}, sets up config Proxy, transitions `NEW → INITIALIZED`.
+ * - **{@link mount}**: Creates DOM structure based on current config, transitions `INITIALIZED → MOUNTED`.
+ * - **Reactive updates**: After mount, config changes trigger {@link applyPartialChange} (targeted DOM updates).
+ * - **{@link destroy}**: Removes DOM nodes, transitions to `DESTROYED`.
+ *
+ * ### Reactive configuration strategy
+ * - **{@link config}**: Internal target object (should not be mutated directly).
+ * - **{@link configProxy}**: Proxy wrapper; assignments trigger {@link applyPartialChange}.
+ * - **{@link isRendered}**: Gates partial updates (no DOM changes before initial {@link mount}).
+ * - **Batch updates**: {@link optionConfig} setter applies multiple changes efficiently (only diffed properties).
  *
- * An option may consist of:
- * - An input element (radio or checkbox)
- * - An optional image
- * - A label container
+ * ### Partial update semantics
+ * - **`isMultiple`**: Toggles `"multiple"` class, switches input `type` (radio ↔ checkbox).
+ * - **`hasImage`**: Toggles `"has-image"` class, creates/removes `<img>` element.
+ * - **`imagePosition`**: Replaces `image-{position}` class (top/right/bottom/left).
+ * - **`imageWidth/Height/BorderRadius`**: Mutates `<img>` inline styles.
+ * - **`labelValign/Halign`**: Replaces label alignment classes.
  *
- * This view supports reactive configuration changes via a Proxy,
- * allowing partial DOM updates without fully re-rendering the view.
+ * ### Image lifecycle
+ * - Created on-demand via {@link createImage} when `hasImage = true`.
+ * - Removed via `remove()` when `hasImage = false`.
+ * - Reference stored in `view.tags.OptionImage` (nulled after removal).
+ *
+ * ### Accessibility
+ * - Root: `role="option"`, `aria-selected="false"` (managed externally), `tabindex="-1"`.
+ * - Input: Associated with label via unique `id` / `htmlFor`.
+ * - Label: Clickable, triggers input selection.
+ *
+ * ### DOM side effects
+ * - {@link mount} creates and appends full structure.
+ * - {@link applyPartialChange} mutates classes, attributes, styles, or child nodes.
+ * - {@link createImage} inserts `<img>` element.
+ * - Setters ({@link isMultiple}, {@link hasImage}) trigger Proxy → DOM updates.
+ *
+ * ### No-op / Idempotency
+ * - {@link applyPartialChange} is no-op if view not mounted (early return guard).
+ * - {@link createImage} is no-op if image already exists.
+ * - {@link optionConfig} setter only assigns diffed properties (avoids redundant Proxy triggers).
+ * - Safe to call setters multiple times with same value (Proxy guards against no-op updates).
  *
  * @extends View<OptionViewTags>
+ * @template OptionViewTags - Type descriptor for the option's DOM structure.
+ * @see {@link OptionViewResult}
+ * @see {@link OptionConfig}
+ * @see {@link View}
  */
 export class OptionView extends View<OptionViewTags> {
 
     /**
-     * Reference to the mounted option view.
-     * Set during `onMount`; null before render.
+     * Strongly-typed reference to the mounted option view structure.
+     *
+     * Structure:
+     * - **view**: Root container element.
+     * - **tags**: Named references to input, image (conditional), label, label content.
+     *
+     * Lifecycle:
+     * - `null` until {@link mount} completes.
+     * - Cleared during {@link destroy}.
+     *
+     * @public
      */
     public view: OptionViewResult | null = null;
 
     /**
-     * Internal configuration state used as the Proxy target.
-     * Should not be mutated directly.
+     * Internal configuration object (Proxy target).
+     *
+     * Lifecycle:
+     * - Initialized during {@link initialize} with default values.
+     * - Mutated via {@link configProxy} Proxy trap.
+     *
+     * Notes:
+     * - **Should not be mutated directly**; use {@link configProxy} or typed setters.
+     * - Contains default values for layout, image, and alignment.
+     *
+     * @private
      */
     private config: OptionConfig | null = null;
 
     /**
-     * Proxy wrapper around `config`.
-     * Assigning properties on this object triggers incremental
-     * DOM updates once the view has been rendered.
+     * Reactive Proxy wrapper around {@link config}.
+     *
+     * Behavior:
+     * - Intercepts property assignments via `set` trap.
+     * - Triggers {@link applyPartialChange} for diffed values when {@link isRendered} is `true`.
+     * - Prevents redundant DOM updates when value hasn't changed.
+     *
+     * Usage:
+     * - Accessed via {@link optionConfig} getter or typed setters ({@link isMultiple}, {@link hasImage}).
+     *
+     * @private
      */
     private configProxy: OptionConfig | null = null;
 
     /**
-     * Indicates whether the initial render has been completed.
-     * Partial DOM updates are skipped until this becomes true.
+     * Flag indicating whether the initial render has completed.
+     *
+     * Lifecycle:
+     * - `false` until {@link mount} finishes.
+     * - `true` afterward (enables partial updates).
+     *
+     * Purpose:
+     * - Gates {@link applyPartialChange} to prevent DOM mutations before structure exists.
+     *
+     * @private
      */
     private isRendered = false;
 
     /**
      * Creates a new OptionView bound to the given parent element.
      *
-     * Initializes the internal configuration and sets up
-     * a reactive Proxy to track and apply configuration changes.
+     * Initialization flow:
+     * 1. Calls `super(parent)` (View base constructor).
+     * 2. Calls {@link initialize} to set up config and Proxy.
+     * 3. Transitions `NEW → INITIALIZED` via `this.init()` inside {@link initialize}.
      *
-     * @param parent - The container element that will host this option view.
+     * @public
+     * @param {HTMLElement} parent - Container element that will host this option view.
      */
     public constructor(parent: HTMLElement) {
         super(parent);
@@ -62,13 +153,31 @@ export class OptionView extends View<OptionViewTags> {
     }
 
     /**
-     * Initializes the default configuration object and wraps it in a Proxy.
+     * Initializes the default configuration and sets up reactive Proxy.
+     *
+     * Configuration defaults:
+     * - `isMultiple`: `false` (radio mode)
+     * - `hasImage`: `false` (no image)
+     * - `imagePosition`: `"right"`
+     * - `imageWidth/Height`: `"60px"`
+     * - `imageBorderRadius`: `"4px"`
+     * - `labelValign/Halign`: `"center"` / `"left"`
+     *
+     * Proxy behavior:
+     * - **`set` trap**: Compares old vs new value; if different:
+     *   1. Updates {@link config} target.
+     *   2. Calls {@link applyPartialChange} if {@link isRendered} is `true`.
+     * - Returns `true` to indicate success.
      *
-     * The Proxy intercepts property assignments and:
-     * - Updates internal state
-     * - Applies targeted DOM changes when the view is already rendered
+     * Postcondition:
+     * - {@link config} and {@link configProxy} are initialized.
+     * - Transitions `NEW → INITIALIZED` via `this.init()`.
      *
-     * No DOM mutations occur before the initial render.
+     * Notes:
+     * - No DOM mutations occur until {@link mount} is called.
+     *
+     * @public
+     * @returns {void}
      */
     public initialize(): void {
         const self = this;
@@ -108,8 +217,12 @@ export class OptionView extends View<OptionViewTags> {
     /**
      * Indicates whether the option supports multiple selection.
      *
-     * - `false`: single selection (radio)
-     * - `true`: multiple selection (checkbox)
+     * Semantics:
+     * - `false`: Single selection mode (radio input).
+     * - `true`: Multiple selection mode (checkbox input).
+     *
+     * @public
+     * @returns {boolean} Current selection mode.
      */
     public get isMultiple(): boolean {
         return this.config!.isMultiple;
@@ -118,49 +231,88 @@ export class OptionView extends View<OptionViewTags> {
     /**
      * Enables or disables multiple selection mode.
      *
-     * When rendered:
-     * - Toggles the `multiple` CSS class on the root element
-     * - Switches the input type between `radio` and `checkbox`
+     * Side effects (when rendered):
+     * - Toggles `"multiple"` CSS class on root element.
+     * - Switches input `type` attribute (`"radio"` ↔ `"checkbox"`).
+     *
+     * Notes:
+     * - Assignments trigger Proxy → {@link applyPartialChange}.
+     * - No-op if value hasn't changed (Proxy guards).
+     *
+     * @public
+     * @param {boolean} value - `true` for multiple selection; `false` for single.
      */
     public set isMultiple(value: boolean) {
-        (this.configProxy as OptionConfig).isMultiple = !!value;
+        this.configProxy.isMultiple = !!value;
     }
 
     /**
-     * Indicates whether the option displays an image next to the label.
+     * Indicates whether the option displays an image.
+     *
+     * @public
+     * @returns {boolean} `true` if image is visible; `false` otherwise.
      */
     public get hasImage(): boolean {
         return this.config!.hasImage;
     }
 
     /**
-     * Shows or hides the image block.
+     * Shows or hides the option's image element.
+     *
+     * Side effects (when rendered):
+     * - **`true`**: Toggles `"has-image"` class, adds `image-{position}` class, calls {@link createImage}.
+     * - **`false`**: Removes `"has-image"` and `image-*` classes, removes `<img>` element, nulls reference.
      *
-     * When rendered:
-     * - Toggles related CSS classes
-     * - Creates or removes the `<img>` element dynamically
+     * Notes:
+     * - Assignments trigger Proxy → {@link applyPartialChange}.
+     * - Image is created on-demand (not pre-rendered).
+     *
+     * @public
+     * @param {boolean} value - `true` to show image; `false` to hide.
      */
     public set hasImage(value: boolean) {
-        (this.configProxy as OptionConfig).hasImage = !!value;
+        this.configProxy.hasImage = !!value;
     }
 
     /**
      * Provides reactive access to the full option configuration.
      *
-     * Mutating properties on this object triggers incremental
-     * DOM updates when the view has already been rendered.
+     * Usage:
+     * - **Getter**: Returns {@link configProxy} for direct property access.
+     * - **Setter**: Applies batch configuration changes (see setter docs).
+     *
+     * Notes:
+     * - Mutating properties on the returned object triggers incremental DOM updates.
+     * - Safe to read/write after {@link initialize} completes.
+     *
+     * @public
+     * @returns {OptionConfig} Reactive configuration Proxy.
      */
     public get optionConfig(): OptionConfig {
         return this.configProxy as OptionConfig;
     }
 
     /**
-     * Applies a batch of configuration changes.
+     * Applies a batch of configuration changes efficiently.
+     *
+     * Optimization strategy:
+     * 1. Compares each incoming property against current {@link config} value.
+     * 2. Builds a `changes` object containing **only diffed properties**.
+     * 3. Assigns `changes` to {@link configProxy} via `Object.assign` (triggers Proxy traps).
+     *
+     * Diffed properties:
+     * - `imageWidth`, `imageHeight`, `imageBorderRadius`
+     * - `imagePosition`
+     * - `labelValign`, `labelHalign`
      *
-     * Only properties whose values differ from the current state
-     * are assigned to the Proxy and processed.
+     * Notes:
+     * - No-op if `config` is `null`, or no properties differ.
+     * - Prevents redundant Proxy triggers for unchanged values.
+     * - Each changed property triggers {@link applyPartialChange} individually.
      *
-     * @param config - Partial configuration patch
+     * @public
+     * @param {OptionConfigPatch | null} config - Partial configuration patch; `null` is no-op.
+     * @returns {void}
      */
     public set optionConfig(config: OptionConfigPatch | null) {
         if (!config || !this.configProxy || !this.config) return;
@@ -193,12 +345,33 @@ export class OptionView extends View<OptionViewTags> {
     /**
      * Performs the initial render of the option view.
      *
-     * Builds the DOM structure based on the current configuration,
-     * assigns CSS classes and ARIA attributes, mounts the view via
-     * `Libs.mountView`, and enables reactive updates afterward.
+     * Rendering flow:
+     * 1. Generates unique option ID (7-character random string).
+     * 2. Builds CSS classes based on current {@link config} (`multiple`, `has-image`, `image-{position}`).
+     * 3. Constructs child structure:
+     *    - **OptionInput**: `<input type="radio|checkbox">` with unique ID.
+     *    - **OptionImage** (conditional): `<img>` with inline styles (width/height/borderRadius).
+     *    - **OptionLabel**: `<label htmlFor="{inputID}">` with alignment classes.
+     *      - **LabelContent**: `<div>` (content placeholder).
+     * 4. Creates DOM via {@link Libs.mountNode}.
+     * 5. Appends root to {@link parent}.
+     * 6. Sets {@link isRendered} to `true` (enables reactive updates).
+     * 7. Transitions `INITIALIZED → MOUNTED` via `super.mount()`.
+     *
+     * Accessibility setup:
+     * - Root: `role="option"`, `aria-selected="false"`, `tabindex="-1"`.
+     * - Input/Label association via `id` / `htmlFor`.
+     *
+     * Postcondition:
+     * - {@link view} is populated with typed DOM references.
+     * - Reactive updates are now enabled.
+     *
+     * @public
+     * @returns {void}
+     * @override
      */
     public override mount(): void {
-        const viewClass: string[] = ["selective-ui-option-view"];
+        const viewClass: string[] = ["seui-option-view"];
         const opt_id = Libs.randomString(7);
         const inputID = `option_${opt_id}`;
 
@@ -245,7 +418,7 @@ export class OptionView extends View<OptionViewTags> {
             },
         };
 
-        this.view = Libs.mountView<OptionViewTags>({
+        this.view = Libs.mountNode<OptionViewResult>({
             OptionView: {
                 tag: {
                     node: "div",
@@ -257,7 +430,7 @@ export class OptionView extends View<OptionViewTags> {
                 },
                 child: childStructure,
             },
-        }) as OptionViewResult;
+        });
 
         this.parent!.appendChild(this.view.view);
         this.isRendered = true;
@@ -268,9 +441,33 @@ export class OptionView extends View<OptionViewTags> {
     /**
      * Applies a targeted DOM update for a single configuration change.
      *
-     * Updates only the affected parts of the view
-     * (classes, attributes, styles, or child nodes)
-     * without triggering a full re-render.
+     * Implementation strategy:
+     * - Retrieves DOM references from {@link view}.
+     * - Switches on `prop` to determine update type.
+     * - Mutates **only** the affected DOM nodes (classes, attributes, styles, or child structure).
+     *
+     * Update rules:
+     * - **`isMultiple`**: Toggle `"multiple"` class, switch input `type` (radio ↔ checkbox).
+     * - **`hasImage`**: Toggle `"has-image"` class, create/remove `<img>` element, manage `image-*` classes.
+     * - **`imagePosition`**: Replace `image-{position}` class (top/right/bottom/left).
+     * - **`imageWidth/Height/BorderRadius`**: Mutate `<img>` inline styles.
+     * - **`labelValign/Halign`**: Replace label alignment classes.
+     *
+     * No-op conditions:
+     * - If {@link view} is `null` (not mounted yet).
+     * - If affected element doesn't exist (e.g., image removed).
+     *
+     * Notes:
+     * - Called by Proxy `set` trap when {@link isRendered} is `true`.
+     * - Avoids full re-render; updates are incremental and efficient.
+     * - `oldValue` parameter is unused (reserved for future diffing logic).
+     *
+     * @private
+     * @template K - Key of {@link OptionConfig}.
+     * @param {K} prop - Property name that changed.
+     * @param {OptionConfig[K]} newValue - New value for the property.
+     * @param {OptionConfig[K]} oldValue - Previous value (currently unused).
+     * @returns {void}
      */
     private applyPartialChange<K extends keyof OptionConfig>(
         prop: K,
@@ -281,8 +478,8 @@ export class OptionView extends View<OptionViewTags> {
         if (!v || !v.view) return;
 
         const root = v.view;
-        const input = v.tags?.OptionInput as HTMLInputElement | undefined;
-        const label = v.tags?.OptionLabel as HTMLLabelElement | undefined;
+        const input = v.tags?.OptionInput;
+        const label = v.tags?.OptionLabel;
 
         switch (prop) {
             case "isMultiple": {
@@ -307,7 +504,7 @@ export class OptionView extends View<OptionViewTags> {
                         .replace(/image-(top|right|bottom|left)/g, "")
                         .trim();
 
-                    const img = v.tags?.OptionImage as HTMLImageElement | null | undefined;
+                    const img = v.tags?.OptionImage;
                     img?.remove();
                     v.tags.OptionImage = null;
                 }
@@ -327,7 +524,7 @@ export class OptionView extends View<OptionViewTags> {
             case "imageWidth":
             case "imageHeight":
             case "imageBorderRadius": {
-                const img = v.tags?.OptionImage as HTMLImageElement | null | undefined;
+                const img = v.tags?.OptionImage;
                 if (img) {
                     const styleProp =
                         prop === "imageWidth" ? "width" :
@@ -357,9 +554,24 @@ export class OptionView extends View<OptionViewTags> {
     /**
      * Creates and inserts the `<img>` element for the option on demand.
      *
-     * The image is styled using the current configuration and is inserted
-     * before the label when possible. If an image already exists, no action
-     * is taken.
+     * Creation flow:
+     * 1. Checks if image already exists (early return if present).
+     * 2. Creates `<img>` element with:
+     *    - Class: `"option-image"`
+     *    - Inline styles: `width`, `height`, `borderRadius` from {@link config}.
+     * 3. Inserts image before {@link OptionLabel} (if label exists), otherwise appends to root.
+     * 4. Stores reference in `view.tags.OptionImage`.
+     *
+     * No-op conditions:
+     * - If {@link view} is `null` (not mounted yet).
+     * - If image already exists in `view.tags.OptionImage`.
+     *
+     * Notes:
+     * - Called by {@link applyPartialChange} when `hasImage` transitions to `true`.
+     * - Insertion order ensures proper layout (image before label).
+     *
+     * @private
+     * @returns {void}
      */
     private createImage(): void {
         const v = this.view;
@@ -368,7 +580,7 @@ export class OptionView extends View<OptionViewTags> {
         if (v.tags?.OptionImage) return;
 
         const root = v.view;
-        const label = v.tags?.OptionLabel as HTMLLabelElement | undefined;
+        const label = v.tags?.OptionLabel;
 
         const image = document.createElement("img");
         image.className = "option-image";