selective-ui 1.2.4 → 1.2.5

package/src/ts/models/group-model.ts

@@ -9,78 +9,145 @@ import { SelectiveOptions } from "../types/utils/selective.type";
 import { LifecycleState } from "../types/core/base/lifecycle.type";
 
 /**
- * @extends {Model<HTMLOptGroupElement, GroupViewTags, GroupView>}
+ * Domain model for a native `<optgroup>` element.
+ *
+ * This model represents a **group header** plus its **child options** and is used by
+ * adapters/recyclers to render grouped lists (e.g., {@link GroupView} + {@link OptionModel} rows).
+ *
+ * ### Responsibility
+ * - Mirror and synchronize state derived from the backing `<optgroup>`:
+ *   - `label` from `optgroup.label`
+ *   - `collapsed` from `optgroup.dataset.collapsed` (string → boolean)
+ * - Own and manage the group’s child {@link OptionModel} collection, including back-references.
+ * - Provide derived selectors for consumer logic: `value`, `selectedItems`, `visibleItems`, `hasVisibleItems`.
+ * - Emit collapsed-state change notifications to subscribers via `onCollapsedChanged(...)`.
+ *
+ * ### Lifecycle (Strict FSM)
+ * - Constructor delegates to {@link Model} and initializes base lifecycle (`NEW → INITIALIZED`).
+ * - {@link init} reads initial state from the target element and transitions to `MOUNTED`.
+ * - {@link update} keeps the attached {@link GroupView} in sync (label + collapsed state).
+ * - {@link destroy} destroys all child options and transitions to `DESTROYED` (idempotent).
+ *
+ * ### Relationships
+ * - **Model ↔ View**: `view` (when assigned) is a {@link GroupView} responsible for DOM updates.
+ * - **Group ↔ Options**: `items` contains child {@link OptionModel}s; each option holds `option.group`.
+ * - **Adapter/Recycler**: binders (e.g., MixedAdapter) call `addItem/removeItem`, set `view`,
+ *   and invoke {@link updateVisibility} based on filtering/virtualization outcomes.
+ *
+ * ### Events / Hooks
+ * - Collapsed changes are dispatched through {@link iEvents.callEvent} to callbacks registered via
+ *   {@link onCollapsedChanged}. These callbacks receive an `evtToken` for iEvents chaining/cancellation,
+ *   the model, and the new collapsed state.
+ *
+ * @extends {Model<HTMLOptGroupElement, GroupViewTags, GroupView, SelectiveOptions>}
+ * @see {@link OptionModel}
+ * @see {@link GroupView}
  */
 export class GroupModel extends Model<HTMLOptGroupElement, GroupViewTags, GroupView, SelectiveOptions> {
+    /** Group label (mirrors `HTMLSelectOptGroupElement.label`). */
     public label = "";
 
+    /**
+     * Child option models that belong to this group.
+     *
+     * Ownership: this group destroys its children in {@link destroy}.
+     */
     public items: OptionModel[] = [];
 
+    /**
+     * Whether this group is collapsed.
+     *
+     * Source-of-truth:
+     * - Initialized from `targetElement.dataset.collapsed` (string → boolean).
+     * - Toggled via {@link toggleCollapse}.
+     */
     public collapsed = false;
 
+    /**
+     * Subscribers invoked when collapsed state changes.
+     * Callbacks are invoked through {@link iEvents.callEvent}.
+     */
     private privOnCollapsedChanged: Array<(evtToken: IEventCallback, model: GroupModel, collapsed: boolean) => void> = [];
 
     /**
-     * Initializes a group model with options and an optional <optgroup> target.
-     * Reads the label and collapsed state from the target element's attributes/dataset.
+     * Creates a group model from configuration and an optional `<optgroup>` element.
      *
-     * @param {SelectiveOptions} options - Configuration for the model.
-     * @param {HTMLOptGroupElement} [targetElement] - The source <optgroup> element.
+     * @param {SelectiveOptions} options - Shared configuration for models/views.
+     * @param {HTMLOptGroupElement} [targetElement] - Backing `<optgroup>` element (when available).
      */
     public constructor(options: SelectiveOptions, targetElement?: HTMLOptGroupElement) {
         super(options, targetElement ?? null, null);
+        this.label = this.targetElement.label;
     }
-    
-    public override init() {
-        if (this.targetElement) {
-            this.label = this.targetElement.label;
-            this.collapsed = Libs.string2Boolean(this.targetElement.dataset?.collapsed);
-        }
+
+    /**
+     * Initializes group state from the backing `<optgroup>` (if present) and mounts the model.
+     *
+     * Behavior:
+     * - Reads `label` from `targetElement.label`.
+     * - Reads `collapsed` from `targetElement.dataset.collapsed` via {@link Libs.string2Boolean}.
+     * - Calls `super.init()` then transitions to `MOUNTED` via `mount()`.
+     *
+     * Idempotency:
+     * - Base {@link Model}/{@link Lifecycle} guards prevent duplicate `init()` transitions.
+     *
+     * @returns {void}
+     * @override
+     */
+    public override init(): void {
+        this.collapsed = Libs.string2Boolean(this.targetElement.dataset?.collapsed);
 
         super.init();
         this.mount();
     }
 
     /**
-     * Returns the array of values from all option items within the group.
+     * Returns all option values within this group.
      *
-     * @type {string[]}
+     * @returns {string[]} Values of all child options (in current `items` order).
      */
     public get value(): string[] {
         return this.items.map((item) => item.value);
     }
 
     /**
-     * Returns the list of option items currently selected within the group.
+     * Returns the subset of child options that are currently selected.
      *
-     * @type {OptionModel[]}
+     * @returns {OptionModel[]} Selected child options.
      */
     public get selectedItems(): OptionModel[] {
         return this.items.filter((item) => item.selected);
     }
 
     /**
-     * Returns the list of option items currently visible within the group.
+     * Returns the subset of child options that are currently visible.
      *
-     * @type {OptionModel[]}
+     * Visibility is typically controlled by filtering/search (e.g., toggling `OptionModel.visible`).
+     *
+     * @returns {OptionModel[]} Visible child options.
      */
     public get visibleItems(): OptionModel[] {
         return this.items.filter((item) => item.visible);
     }
 
     /**
-     * Indicates whether the group has at least one visible option item.
+     * Whether the group has at least one visible option.
      *
-     * @type {boolean}
+     * @returns {boolean} True if any child option is visible.
      */
     public get hasVisibleItems(): boolean {
         return this.visibleItems.length > 0;
     }
 
     /**
-     * Updates the group's label from the new target element and propagates the change to the view.
+     * Rebinds this model to a new `<optgroup>` element and synchronizes the label immediately.
+     *
+     * Notes:
+     * - This method updates the label and pushes it to the view, then triggers a lifecycle update.
+     * - The signature is intentionally stricter than the base model (`HTMLOptGroupElement` only).
      *
-     * @param {HTMLOptGroupElement} targetElement - The updated <optgroup> element.
+     * @param {HTMLOptGroupElement} targetElement - Updated backing `<optgroup>` element.
+     * @returns {void}
      */
     public updateTarget(targetElement: HTMLOptGroupElement): void {
         this.label = targetElement.label;
@@ -89,8 +156,14 @@ export class GroupModel extends Model<HTMLOptGroupElement, GroupViewTags, GroupV
     }
 
     /**
-     * Hook invoked when the target element reference changes.
-     * Updates the view's label and collapsed state to keep UI in sync.
+     * Synchronizes the attached view (if any) with current model state and emits lifecycle update.
+     *
+     * View sync:
+     * - Updates header label
+     * - Applies collapsed state
+     *
+     * @returns {void}
+     * @override
      */
     public override update(): void {
         if (this.view) {
@@ -100,6 +173,18 @@ export class GroupModel extends Model<HTMLOptGroupElement, GroupViewTags, GroupV
         super.update();
     }
 
+    /**
+     * Destroys the group model and releases owned resources.
+     *
+     * Behavior:
+     * - Idempotent once lifecycle is {@link LifecycleState.DESTROYED}.
+     * - Destroys all child {@link OptionModel} instances.
+     * - Clears the `items` array.
+     * - Completes lifecycle teardown via `super.destroy()`.
+     *
+     * @returns {void}
+     * @override
+     */
     public override destroy(): void {
         if (this.is(LifecycleState.DESTROYED)) {
             return;
@@ -114,16 +199,27 @@ export class GroupModel extends Model<HTMLOptGroupElement, GroupViewTags, GroupV
     }
 
     /**
-     * Registers a callback to be invoked when the group's collapsed state changes.
+     * Subscribes to changes in the group's collapsed state.
      *
-     * @param {(evtToken: IEventCallback, model: GroupModel, collapsed: boolean) => void} callback - Listener for collapse changes.
+     * Callbacks are invoked from {@link toggleCollapse} via {@link iEvents.callEvent}.
+     *
+     * @param {(evtToken: IEventCallback, model: GroupModel, collapsed: boolean) => void} callback
+     * Listener invoked with `(evtToken, model, collapsed)`.
+     * @returns {void}
      */
     public onCollapsedChanged(callback: (evtToken: IEventCallback, model: GroupModel, collapsed: boolean) => void): void {
         this.privOnCollapsedChanged.push(callback);
     }
 
     /**
-     * Toggles the group's collapsed state, updates the view, and notifies registered listeners.
+     * Toggles collapsed state, updates the view, and notifies subscribers.
+     *
+     * Side effects:
+     * - Mutates {@link collapsed}.
+     * - Calls `view.setCollapsed(...)` if a view is attached.
+     * - Dispatches callbacks registered via {@link onCollapsedChanged}.
+     *
+     * @returns {void}
      */
     public toggleCollapse(): void {
         this.collapsed = !this.collapsed;
@@ -133,9 +229,10 @@ export class GroupModel extends Model<HTMLOptGroupElement, GroupViewTags, GroupV
     }
 
     /**
-     * Adds an option item to this group and sets its back-reference to the group.
+     * Adds a child option to this group and sets the option's back-reference.
      *
-     * @param {OptionModel} optionModel - The option to add.
+     * @param {OptionModel} optionModel - Option to add.
+     * @returns {void}
      */
     public addItem(optionModel: OptionModel): void {
         this.items.push(optionModel);
@@ -143,9 +240,12 @@ export class GroupModel extends Model<HTMLOptGroupElement, GroupViewTags, GroupV
     }
 
     /**
-     * Removes an option item from this group and clears its group reference.
+     * Removes a child option from this group and clears the option's back-reference.
+     *
+     * No-op if the option is not present in {@link items}.
      *
-     * @param {OptionModel} optionModel - The option to remove.
+     * @param {OptionModel} optionModel - Option to remove.
+     * @returns {void}
      */
     public removeItem(optionModel: OptionModel): void {
         const index = this.items.indexOf(optionModel);
@@ -156,8 +256,14 @@ export class GroupModel extends Model<HTMLOptGroupElement, GroupViewTags, GroupV
     }
 
     /**
-     * Updates the group's visibility in the view, typically based on children visibility.
-     * No-ops if the view is not initialized.
+     * Requests the attached view (if any) to recompute/update its visibility.
+     *
+     * Typically called after child visibility changes (filter/search) so the group header can
+     * reflect whether it contains visible items.
+     *
+     * No-op if no view is attached.
+     *
+     * @returns {void}
      */
     public updateVisibility(): void {
         this.view?.updateVisibility();

package/src/ts/models/option-model.ts

@@ -10,33 +10,109 @@ import { SelectiveOptions } from "../types/utils/selective.type";
 import { LifecycleState } from "../types/core/base/lifecycle.type";
 
 /**
+ * Domain model for a native `<option>` element.
+ *
+ * This is the core selectable row model consumed by adapters/recyclers. It mirrors the backing
+ * `<option>` node while also carrying UI-only state used by the headless+DOM-driven layer
+ * (visibility, highlight, precomputed search key).
+ *
+ * ### Responsibility
+ * - Mirror and synchronize state with the backing `<option>` element:
+ *   - `value`, `selected`, `dataset`, and display label (with optional tag translation / HTML policy).
+ * - Provide derived properties for rendering:
+ *   - image resolution (`imageSrc` / `hasImage`),
+ *   - rich/stripped label (`text` / `textContent`),
+ *   - normalized search key (`textToFind`).
+ * - Maintain UI-only flags:
+ *   - `visible` for filtering/search,
+ *   - `highlighted` for keyboard navigation/hover.
+ * - Publish change notifications:
+ *   - **External** selection (`selected`) vs **internal** selection sync (`selectedNonTrigger`),
+ *   - visibility changes (`visible`).
+ *
+ * ### Lifecycle (Strict FSM)
+ * - Base {@link Model} calls `init()` during construction (`NEW → INITIALIZED`), and this subclass
+ *   overrides {@link init} to precompute {@link textToFind} before delegating to `super.init()`.
+ * - {@link init} then transitions to `MOUNTED` via `mount()` for first render readiness.
+ * - {@link update} recomputes derived text/search fields and pushes state into the {@link OptionView}
+ *   if attached, then emits lifecycle update.
+ * - {@link destroy} clears listeners/references and transitions to `DESTROYED` (idempotent).
+ *
+ * ### External vs internal selection semantics
+ * - `selected` is the **external** user-facing signal:
+ *   updates state (via {@link selectedNonTrigger}) and then notifies {@link onSelected} listeners.
+ * - `selectedNonTrigger` is the **internal** sync signal:
+ *   updates view/DOM/backing `<option>` and then notifies {@link onInternalSelected} listeners
+ *   **without** implying user intent.
+ *
+ * ### DOM & a11y side effects (when a view is attached)
+ * - Toggles CSS classes: `"hide"`, `"highlight"`, `"checked"`.
+ * - Updates `aria-selected` on the option row root element.
+ * - Updates label content (either `innerHTML` or `textContent` depending on `allowHtml`).
+ * - Mirrors selection state to the backing `<option>` (property + attribute).
+ *
  * @extends {Model<HTMLOptionElement, OptionViewTags, OptionView, SelectiveOptions>}
+ * @see {@link GroupModel}
+ * @see {@link OptionView}
  */
 export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, OptionView, SelectiveOptions> {
+    /**
+     * External selection subscribers (emitted by the {@link selected} setter).
+     * Use this for user-facing selection flows.
+     */
     private privOnSelected: Array<(evtToken: IEventCallback, el: OptionModel, selected: boolean) => void> = [];
 
+    /**
+     * Internal selection subscribers (emitted by the {@link selectedNonTrigger} setter).
+     * Use this for silent synchronization flows.
+     */
     private privOnInternalSelected: Array<(evtToken: IEventCallback, el: OptionModel, selected: boolean) => void> = [];
 
+    /**
+     * Visibility subscribers (emitted by the {@link visible} setter).
+     * Commonly used to recompute group visibility and update aggregated visibility stats.
+     */
     private privOnVisibilityChanged: Array<(evtToken: IEventCallback, model: OptionModel, visible: boolean) => void> = [];
 
+    /**
+     * Visibility flag used for filtering/search.
+     * When `false`, adapters/recyclers may treat this item as non-renderable.
+     */
     private _visible = true;
 
+    /** Highlight flag used for keyboard navigation / hover. */
     private _highlighted = false;
 
+    /**
+     * Parent group model (if this option belongs to a group).
+     * Assigned by grouping logic (e.g., GroupModel/MixedAdapter).
+     */
     public group: GroupModel | null = null;
 
     /**
-     * Constructs a Model instance with configuration options and optional bindings to a target element and view.
-     * Stores references for later updates and rendering.
+     * Creates an option model.
      *
-     * @param {SelectiveOptions} options - Configuration options for the model.
-     * @param {HTMLOptionElement|null} [targetElement=null] - The underlying element (e.g., <option> or group node).
-     * @param {OptionView|null} [view=null] - The associated view responsible for rendering the model.
+     * @param {SelectiveOptions} options - Shared configuration for models/views.
+     * @param {HTMLOptionElement | null} [targetElement=null] - Backing `<option>` element.
+     * @param {OptionView | null} [view=null] - Optional view used to render this model.
      */
-    public constructor(options: SelectiveOptions, targetElement: HTMLOptionElement | null = null, view: OptionView | null = null) {
+    public constructor(
+        options: SelectiveOptions,
+        targetElement: HTMLOptionElement | null = null,
+        view: OptionView | null = null
+    ) {
         super(options, targetElement, view);
     }
 
+    /**
+     * Initializes the model and precomputes the search key.
+     *
+     * - Computes {@link textToFind} from {@link textContent} (lowercased + normalized).
+     * - Delegates to `super.init()` and then transitions to `MOUNTED` via `mount()`.
+     *
+     * @returns {void}
+     * @override
+     */
     public override init(): void {
         this.textToFind = Libs.string2normalize(this.textContent.toLowerCase());
 
@@ -45,46 +121,50 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
     }
 
     /**
-     * Returns the image source from dataset (imgsrc or image), or an empty string if absent.
+     * Image source resolved from dataset (`imgsrc` or `image`), or empty string if absent.
      *
-     * @type {string}
+     * @returns {string}
      */
     public get imageSrc(): string {
         return this.dataset?.imgsrc || this.dataset?.image || "";
     }
 
     /**
-     * Indicates whether this option has an associated image source.
+     * Whether this option has an image associated with it.
      *
-     * @type {boolean}
+     * @returns {boolean}
      */
     public get hasImage(): boolean {
         return !!this.imageSrc;
     }
 
     /**
-     * Gets the option's current value from the underlying <option> element.
+     * Current value of the backing `<option>`.
      *
-     * @type {string}
+     * @returns {string}
      */
     public get value(): string {
         return this.targetElement?.value ?? "";
     }
 
     /**
-     * Gets whether the option is currently selected (proxied to the <option> element).
+     * Whether the backing `<option>` is selected.
      *
-     * @type {boolean}
+     * @returns {boolean}
      */
     public get selected(): boolean {
         return !!this.targetElement?.selected;
     }
 
     /**
-     * Sets the selected state and triggers external selection listeners.
-     * Uses selectedNonTrigger internally to update DOM/ARIA without firing external side effects first.
+     * Sets selected state and emits **external** selection listeners.
      *
-     * @type {boolean}
+     * Flow:
+     * - Delegates to {@link selectedNonTrigger} to synchronize view/DOM/backing element.
+     * - Notifies {@link onSelected} subscribers via {@link iEvents.callEvent}.
+     *
+     * @param {boolean} value - New selection state.
+     * @returns {void}
      */
     public set selected(value: boolean) {
         this.selectedNonTrigger = value;
@@ -92,18 +172,25 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
     }
 
     /**
-     * Gets whether the option is currently visible in the UI.
+     * Whether this option is visible (used for filtering/search).
      *
-     * @type {boolean}
+     * @returns {boolean}
      */
     public get visible(): boolean {
         return this._visible;
     }
 
     /**
-     * Sets the visibility state; toggles "hide" class on the view and notifies visibility listeners.
+     * Sets visibility and synchronizes the view (if attached), then emits visibility listeners.
+     *
+     * Side effects (when view attached):
+     * - Toggles `"hide"` CSS class on the view root element.
      *
-     * @type {boolean}
+     * Idempotent:
+     * - No-op if the new value equals the current state.
+     *
+     * @param {boolean} value - New visibility state.
+     * @returns {void}
      */
     public set visible(value: boolean) {
         if (this._visible === value) return;
@@ -116,19 +203,27 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
     }
 
     /**
-     * Gets the selected state without triggering external listeners (alias of selected).
+     * Reads selected state without emitting external selection listeners.
      *
-     * @type {boolean}
+     * @returns {boolean}
      */
     public get selectedNonTrigger(): boolean {
         return this.selected;
     }
 
     /**
-     * Sets the selected state and updates input checked, CSS classes, ARIA attributes,
-     * and the underlying <option> 'selected' attribute. Notifies internal selection listeners.
+     * Sets selected state **silently** (internal sync), updates view/a11y/backing DOM, then emits internal listeners.
+     *
+     * Side effects (when view/backing element exist):
+     * - Updates the input checked state (`OptionInput`) if present.
+     * - Toggles `"checked"` class on the root element.
+     * - Sets `aria-selected`.
+     * - Mirrors to backing `<option>`:
+     *   - toggles `selected` attribute,
+     *   - sets `targetElement.selected`.
      *
-     * @type {boolean}
+     * @param {boolean} value - New selection state.
+     * @returns {void}
      */
     public set selectedNonTrigger(value: boolean) {
         const input = this.view?.view?.tags?.OptionInput;
@@ -148,10 +243,16 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
     }
 
     /**
-     * Returns the display text for the option, applying tag translation and optional HTML allowance.
-     * If allowHtml=false, returns stripped/sanitized text.
+     * Display label for rendering (with tag translation and HTML policy).
+     *
+     * Source precedence:
+     * - `dataset.mask` if present, otherwise `targetElement.text`.
+     *
+     * Policy:
+     * - When `options.allowHtml === true`, returns translated HTML.
+     * - When `options.allowHtml === false`, returns plain text (HTML stripped).
      *
-     * @type {string}
+     * @returns {string}
      */
     public get text(): string {
         const raw = this.dataset?.mask ?? this.targetElement?.text ?? "";
@@ -160,40 +261,49 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
     }
 
     /**
-     * Returns a plain-text version of the display text (trimmed),
-     * stripping HTML if allowHtml is true, otherwise the raw text.
+     * Plain-text version of the display label, trimmed.
      *
-     * @type {string}
+     * - If `allowHtml` is enabled, strips HTML from {@link text}.
+     * - Otherwise returns {@link text} directly (already plain).
+     *
+     * @returns {string}
      */
     public get textContent(): string {
         return this.options.allowHtml ? Libs.stripHtml(this.text).trim() : this.text.trim();
     }
 
+    /**
+     * Normalized, lowercase search key used for filtering/search.
+     * Computed during {@link init} and recomputed in {@link update}.
+     */
     public textToFind: string;
 
     /**
-     * Returns the dataset object of the underlying <option> element, or an empty object.
+     * Dataset object of the backing `<option>` element.
      *
-     * @type {DOMStringMap|Record<string, string>}
+     * @returns {DOMStringMap}
      */
     public get dataset(): DOMStringMap {
         return this.targetElement?.dataset ?? ({} as DOMStringMap);
     }
 
     /**
-     * Gets whether the option is currently highlighted (e.g., via keyboard navigation).
+     * Whether this option is currently highlighted (navigation/hover).
      *
-     * @type {boolean}
+     * @returns {boolean}
      */
     public get highlighted(): boolean {
         return this._highlighted;
     }
 
     /**
-     * Sets the highlighted state and toggles the "highlight" CSS class on the view.
-     * Always syncs the DOM class even if the state is unchanged.
+     * Sets highlight state and synchronizes the view (if attached).
+     *
+     * Side effects:
+     * - Toggles `"highlight"` CSS class on the view root element.
      *
-     * @type {boolean}
+     * @param {boolean} value - New highlight state.
+     * @returns {void}
      */
     public set highlighted(value: boolean) {
         const val = !!value;
@@ -204,36 +314,50 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
     }
 
     /**
-     * Registers a listener invoked when external selection changes (via setter `selected`).
+     * Subscribes to **external** selection changes (emitted by {@link selected}).
      *
-     * @param {(evtToken: IEventCallback, el: OptionModel, selected: boolean) => void} callback - Selection listener.
+     * @param {(evtToken: IEventCallback, el: OptionModel, selected: boolean) => void} callback - Listener callback.
+     * @returns {void}
      */
     public onSelected(callback: (evtToken: IEventCallback, el: OptionModel, selected: boolean) => void): void {
         this.privOnSelected.push(callback);
     }
 
     /**
-     * Registers a listener invoked when internal selection changes (via setter `selectedNonTrigger`).
+     * Subscribes to **internal** selection changes (emitted by {@link selectedNonTrigger}).
      *
-     * @param {(evtToken: IEventCallback, el: OptionModel, selected: boolean) => void} callback - Internal selection listener.
+     * @param {(evtToken: IEventCallback, el: OptionModel, selected: boolean) => void} callback - Listener callback.
+     * @returns {void}
      */
     public onInternalSelected(callback: (evtToken: IEventCallback, el: OptionModel, selected: boolean) => void): void {
         this.privOnInternalSelected.push(callback);
     }
 
     /**
-     * Registers a listener invoked when visibility changes (via setter `visible`).
+     * Subscribes to visibility changes (emitted by {@link visible}).
      *
-     * @param {(evtToken: IEventCallback, model: OptionModel, visible: boolean) => void} callback - Visibility listener.
+     * @param {(evtToken: IEventCallback, model: OptionModel, visible: boolean) => void} callback - Listener callback.
+     * @returns {void}
      */
     public onVisibilityChanged(callback: (evtToken: IEventCallback, model: OptionModel, visible: boolean) => void): void {
         this.privOnVisibilityChanged.push(callback);
     }
 
     /**
-     * Hook called when the target <option> element changes.
-     * Updates label content (HTML or text), image src/alt if present,
-     * and synchronizes initial selected state to the view.
+     * Synchronizes derived fields and the attached view from the current backing element/options.
+     *
+     * Syncs:
+     * - {@link textToFind} (normalized search key)
+     * - Label content:
+     *   - `innerHTML` when `allowHtml` is enabled,
+     *   - otherwise `textContent`
+     * - Image attributes (`src`/`alt`) when present
+     * - Selected state from `targetElement.selected` via {@link selectedNonTrigger}
+     *
+     * No-op for view updates when no view is attached; still emits lifecycle update via `super.update()`.
+     *
+     * @returns {void}
+     * @override
      */
     public override update(): void {
         this.textToFind = Libs.string2normalize(this.textContent.toLowerCase());
@@ -262,6 +386,18 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
         super.update();
     }
 
+    /**
+     * Destroys the model and releases listener references.
+     *
+     * Behavior:
+     * - Idempotent once lifecycle is {@link LifecycleState.DESTROYED}.
+     * - Clears external/internal selection listeners and visibility listeners.
+     * - Detaches from parent group and clears cached search key.
+     * - Completes teardown via `super.destroy()` (base {@link Model} also destroys the view if present).
+     *
+     * @returns {void}
+     * @override
+     */
     public override destroy(): void {
         if (this.is(LifecycleState.DESTROYED)) {
             return;