selective-ui 1.2.4 → 1.2.5

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

@@ -1,32 +1,97 @@
-
 import { View } from "../core/base/view";
 import { Libs } from "../utils/libs";
 import type { GroupViewTags, GroupViewResult } from "../types/views/view.group.type";
 
 /**
- * View implementation responsible for rendering and managing
- * a grouped collection of selectable items.
+ * GroupView
+ *
+ * View implementation for rendering grouped collections of selectable items.
+ *
+ * ### Responsibility
+ * - Renders a semantic group structure: header (label) + items container.
+ * - Manages group-level visibility based on child item state.
+ * - Supports collapse/expand interactions with accessibility annotations.
+ * - Provides typed access to DOM structure via {@link view}.
+ *
+ * ### Structure
+ * ```
+ * GroupView (root)
+ *   ├─ GroupHeader (label, role="presentation")
+ *   └─ GroupItems (container, role="group")
+ * ```
+ *
+ * ### Lifecycle (View-based FSM)
+ * - **Construction**: Accepts parent container, transitions `NEW → INITIALIZED`.
+ * - **{@link mount}**: Creates DOM structure, appends to parent, transitions `INITIALIZED → MOUNTED`.
+ * - **{@link update}**: Refreshes group header label, transitions `MOUNTED → UPDATED → MOUNTED`.
+ * - **{@link destroy}**: Removes DOM nodes, transitions to `DESTROYED`.
+ *
+ * ### Visibility semantics
+ * - {@link updateVisibility} hides the entire group when all child items are hidden.
+ * - Checks for `"hide"` class on children (does not inspect `display` or `visibility` styles).
  *
- * The group consists of:
- * - A header element (label)
- * - A container holding child item views
+ * ### Accessibility
+ * - Root container: `role="group"`, `aria-labelledby` points to header.
+ * - Header: `role="presentation"`, unique ID for labeling.
+ * - Items container: `role="group"` (nested group).
+ * - Collapse state: `aria-expanded` attribute on header (managed by {@link setCollapsed}).
+ *
+ * ### DOM side effects
+ * - {@link mount} creates and appends DOM structure.
+ * - {@link updateLabel} mutates header `textContent`.
+ * - {@link setCollapsed} toggles CSS classes and ARIA attributes.
+ * - {@link updateVisibility} toggles `"hide"` class on root.
+ *
+ * ### No-op / Idempotency
+ * - {@link updateLabel}, {@link updateVisibility}, {@link setCollapsed} are no-ops if not mounted (early return guards).
+ * - Safe to call multiple times without side effects beyond DOM state updates.
  *
  * @extends View<GroupViewTags>
+ * @template GroupViewTags - Type descriptor for the group's DOM structure.
+ * @see {@link GroupViewResult}
+ * @see {@link View}
  */
 export class GroupView extends View<GroupViewTags> {
 
     /**
      * Strongly-typed reference to the mounted group view structure.
-     * Will be null until the view has been mounted.
+     *
+     * Structure:
+     * - **view**: Root container element.
+     * - **tags**: Named references to header and items container.
+     *
+     * Lifecycle:
+     * - `null` until {@link mount} completes.
+     * - Cleared during {@link destroy}.
+     *
+     * @public
      */
     public view: GroupViewResult | null = null;
 
     /**
      * Mounts the group view into the DOM.
      *
-     * Creates the group container, header, and items wrapper,
-     * applies required ARIA attributes, and appends the root
-     * element to the parent container.
+     * Creation flow:
+     * 1. Generates unique group ID (7-character random string).
+     * 2. Creates DOM structure via {@link Libs.mountView}:
+     *    - Root: `<div role="group" aria-labelledby="seui-{id}-header">`
+     *    - Header: `<div role="presentation" id="seui-{id}-header">`
+     *    - Items: `<div role="group">` (nested group for child items)
+     * 3. Appends root to {@link parent} container.
+     * 4. Transitions `INITIALIZED → MOUNTED` via `super.mount()`.
+     *
+     * Accessibility setup:
+     * - Root `aria-labelledby` associates group with header text.
+     * - Header `role="presentation"` hides it from navigation (purely visual label).
+     * - Items container `role="group"` creates semantic boundary for children.
+     *
+     * Postcondition:
+     * - {@link view} is populated with typed DOM references.
+     *
+     * @public
+     * @returns {void}
+     * @override
+     * @throws {Error} If {@link parent} is null (should never occur due to base `View` constructor).
      */
     public override mount(): void {
         const group_id = Libs.randomString(7);
@@ -67,10 +132,19 @@ export class GroupView extends View<GroupViewTags> {
     }
 
     /**
-     * Called when the view needs to be updated.
+     * Updates the group view in response to state changes.
+     *
+     * Behavior:
+     * - Refreshes the group header label via {@link updateLabel}.
+     * - Transitions `MOUNTED → UPDATED → MOUNTED` via `super.update()`.
      *
-     * Currently performs a lightweight refresh by updating
-     * the group header label.
+     * Notes:
+     * - Currently performs only label refresh; extend for additional update logic.
+     * - Does **not** update visibility or collapse state automatically.
+     *
+     * @public
+     * @returns {void}
+     * @override
      */
     public override update(): void {
         this.updateLabel();
@@ -80,8 +154,18 @@ export class GroupView extends View<GroupViewTags> {
     /**
      * Updates the text content of the group header.
      *
-     * @param label - The new label to display.
-     *                If null, the existing label is preserved.
+     * Behavior:
+     * - No-op if not mounted ({@link view} is `null`).
+     * - If `label` is `null`, preserves existing header text.
+     * - Otherwise, replaces header `textContent` with new label.
+     *
+     * Notes:
+     * - Does **not** escape HTML (uses `textContent`, not `innerHTML`).
+     * - Safe to call multiple times with same value (idempotent).
+     *
+     * @public
+     * @param {string | null} [label=null] - New label to display; `null` preserves current label.
+     * @returns {void}
      */
     public updateLabel(label: string | null = null): void {
         if (!this.view) return;
@@ -93,11 +177,15 @@ export class GroupView extends View<GroupViewTags> {
     }
 
     /**
-     * Returns the container element that holds all item/option views
-     * belonging to this group.
+     * Returns the container element for child item views.
      *
-     * @returns The HTMLDivElement used as the items container.
-     * @throws {Error} If the view has not been mounted yet.
+     * Usage:
+     * - Caller appends `OptionView` or other child views to this container.
+     * - Container provides semantic grouping (`role="group"`).
+     *
+     * @public
+     * @returns {HTMLDivElement} The items container element.
+     * @throws {Error} If the view has not been mounted yet ({@link view} is `null`).
      */
     public getItemsContainer(): HTMLDivElement {
         if (!this.view) {
@@ -107,10 +195,22 @@ export class GroupView extends View<GroupViewTags> {
     }
 
     /**
-     * Updates the visibility of the group based on its children.
+     * Updates the group's visibility based on child item state.
+     *
+     * Visibility rules:
+     * - Iterates through direct children of the items container.
+     * - Counts children **without** the `"hide"` CSS class.
+     * - Toggles `"hide"` class on root container:
+     *   - **Added** if all children are hidden (zero visible).
+     *   - **Removed** if any child is visible.
+     *
+     * Notes:
+     * - No-op if not mounted ({@link view} is `null`).
+     * - Only checks for `"hide"` class; does **not** inspect `display` or `visibility` styles.
+     * - Safe to call repeatedly (idempotent based on current child state).
      *
-     * If all child items are hidden, the entire group
-     * will be hidden as well.
+     * @public
+     * @returns {void}
      */
     public updateVisibility(): void {
         if (!this.view) return;
@@ -126,11 +226,22 @@ export class GroupView extends View<GroupViewTags> {
     /**
      * Sets the collapsed/expanded state of the group.
      *
-     * This updates both:
-     * - Visual state (CSS classes)
-     * - Accessibility state (ARIA attributes)
+     * State updates:
+     * - **CSS**: Toggles `"collapsed"` class on root container.
+     * - **ARIA**: Sets `aria-expanded` attribute on header (`"true"` or `"false"`).
+     *
+     * Visual effects:
+     * - CSS class typically controls item container visibility (via stylesheet).
+     * - ARIA attribute communicates state to assistive technologies.
+     *
+     * Notes:
+     * - No-op if not mounted ({@link view} is `null`).
+     * - Does **not** animate or transition; relies on CSS for presentation.
+     * - Safe to call with same value repeatedly (idempotent).
      *
-     * @param collapsed - True to collapse the group, false to expand it.
+     * @public
+     * @param {boolean} collapsed - `true` to collapse the group; `false` to expand.
+     * @returns {void}
      */
     public setCollapsed(collapsed: boolean): void {
         if (!this.view) return;

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"`
      *
-     * The Proxy intercepts property assignments and:
-     * - Updates internal state
-     * - Applies targeted DOM changes when the view is already rendered
+     * 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.
      *
-     * No DOM mutations occur before the initial render.
+     * Postcondition:
+     * - {@link config} and {@link configProxy} are initialized.
+     * - Transitions `NEW → INITIALIZED` via `this.init()`.
+     *
+     * 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,27 +231,44 @@ 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;
     }
 
     /**
-     * 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.
      *
-     * When rendered:
-     * - Toggles related CSS classes
-     * - Creates or removes the `<img>` element dynamically
+     * 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.
+     *
+     * 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;
@@ -147,20 +277,42 @@ export class OptionView extends View<OptionViewTags> {
     /**
      * 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).
      *
-     * Only properties whose values differ from the current state
-     * are assigned to the Proxy and processed.
+     * Diffed properties:
+     * - `imageWidth`, `imageHeight`, `imageBorderRadius`
+     * - `imagePosition`
+     * - `labelValign`, `labelHalign`
      *
-     * @param config - Partial configuration patch
+     * 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.
+     *
+     * @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,9 +345,30 @@ 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.mountView}.
+     * 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"];
@@ -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,
@@ -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;