selective-ui 1.2.4 → 1.2.6

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,25 +203,35 @@ 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;
         const viewEl = this.view?.getView?.();
 
-        if (input) (input as HTMLInputElement).checked = value;
+        if (input) {
+            input.checked = value;
+        }
 
         if (viewEl && this.targetElement) {
             viewEl.classList.toggle("checked", !!value);
@@ -142,16 +239,24 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
             this.targetElement.toggleAttribute("selected", !!value);
         }
 
-        if (this.targetElement) this.targetElement.selected = value;
+        if (this.targetElement) {
+            this.targetElement.selected = value;
+        }
 
         iEvents.callEvent<[OptionModel, boolean]>([this, value], ...this.privOnInternalSelected);
     }
 
     /**
-     * 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`.
      *
-     * @type {string}
+     * Policy:
+     * - When `options.allowHtml === true`, returns translated HTML.
+     * - When `options.allowHtml === false`, returns plain text (HTML stripped).
+     *
+     * @returns {string}
      */
     public get text(): string {
         const raw = this.dataset?.mask ?? this.targetElement?.text ?? "";
@@ -160,40 +265,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.
+     *
+     * - If `allowHtml` is enabled, strips HTML from {@link text}.
+     * - Otherwise returns {@link text} directly (already plain).
      *
-     * @type {string}
+     * @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);
+        return this.targetElement?.dataset ?? {};
     }
 
     /**
-     * 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).
      *
-     * @type {boolean}
+     * Side effects:
+     * - Toggles `"highlight"` CSS class on the view root element.
+     *
+     * @param {boolean} value - New highlight state.
+     * @returns {void}
      */
     public set highlighted(value: boolean) {
         const val = !!value;
@@ -204,36 +318,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());
@@ -253,8 +381,12 @@ export class OptionModel extends Model<HTMLOptionElement, OptionViewTags, Option
 
         const imageTag = this.view.view.tags.OptionImage;
         if (imageTag && this.hasImage) {
-            (imageTag as HTMLImageElement).src = this.imageSrc;
-            (imageTag as HTMLImageElement).alt = this.text;
+            if (imageTag.src != this.imageSrc) {
+                imageTag.src = this.imageSrc;
+            }
+            if (imageTag.alt != this.text) {
+                imageTag.alt = this.text;
+            }
         }
 
         if (this.targetElement) this.selectedNonTrigger = this.targetElement.selected;
@@ -262,6 +394,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;

package/src/ts/services/dataset-observer.ts

@@ -1,18 +1,59 @@
 /**
- * @class
+ * DatasetObserver
+ *
+ * Lightweight observer that watches `data-*` attribute mutations on a target element
+ * and emits a debounced snapshot of `element.dataset`.
+ *
+ * ### Responsibility
+ * - Detect changes to `data-*` attributes using a {@link MutationObserver}.
+ * - Debounce rapid attribute mutations into a single callback invocation.
+ * - Provide a secondary/manual notification path via a custom `"dataset:changed"` event.
+ *
+ * ### Event Model (External vs. Internal)
+ * - **External changes**: DOM attribute mutations (e.g., `el.dataset.disabled = "1"`) are detected
+ *   by {@link MutationObserver} and delivered after the debounce window.
+ * - **Internal/manual signal**: dispatching `"dataset:changed"` on the element forces an immediate
+ *   snapshot emission (not debounced here), useful when dataset-like state is updated through
+ *   non-attribute paths or when consumers want an explicit refresh signal.
+ *
+ * ### Debounce Semantics
+ * - Multiple attribute changes within ~50ms are coalesced into a single {@link onChanged} call.
+ * - The callback receives a shallow copy of the current dataset (`{ ...element.dataset }`),
+ *   ensuring callers do not hold a live reference.
+ *
+ * ### Usage
+ * - Create instance with a target element.
+ * - Call {@link connect} to start observing.
+ * - Implement/assign {@link onChanged} to react to updates.
+ * - Call {@link disconnect} during teardown to prevent leaks.
  */
 export class DatasetObserver {
+    /** Underlying MutationObserver instance used to detect `data-*` attribute mutations. */
     private observer: MutationObserver;
 
+    /** Target element whose dataset (`data-*` attributes) is observed. */
     private element: HTMLElement;
 
+    /**
+     * Debounce timer handle for coalescing rapid attribute mutations.
+     * Cleared/replaced whenever a new relevant mutation arrives within the debounce window.
+     */
     private debounceTimer: ReturnType<typeof setTimeout> | null = null;
 
     /**
-     * Observes data-* attribute changes on a target element and debounces notifications.
-     * Sets up a MutationObserver to detect dataset mutations and a fallback custom event listener.
+     * Creates a {@link DatasetObserver} for the given element.
+     *
+     * Side effects:
+     * - Instantiates a {@link MutationObserver} that filters for `attributes` mutations
+     *   where `attributeName` starts with `"data-"`.
+     * - Registers a `"dataset:changed"` event listener on the element to allow manual
+     *   emission of dataset snapshots.
      *
-     * @param {HTMLElement} element - The element whose dataset (data-* attributes) will be observed.
+     * Notes:
+     * - Observation does not begin until {@link connect} is called.
+     * - The `"dataset:changed"` listener is always active after construction.
+     *
+     * @param element - The element whose `data-*` attributes will be observed.
      */
     public constructor(element: HTMLElement) {
         this.element = element;
@@ -41,8 +82,17 @@ export class DatasetObserver {
     }
 
     /**
-     * Starts observing the element for attribute changes, including old values.
-     * Uses MutationObserver to track updates to data-* attributes.
+     * Starts observing the target element for attribute changes.
+     *
+     * - Observes all attribute mutations and relies on the mutation callback to filter
+     *   down to `data-*` changes.
+     * - `attributeOldValue` is enabled to allow future diagnostics; the current implementation
+     *   does not consume old values directly.
+     *
+     * No-op behavior:
+     * - Calling `connect()` multiple times will register multiple observations on the same
+     *   element in standard DOM APIs. Consumers should treat this as "call once" unless the
+     *   implementation is extended to guard idempotency.
      */
     public connect(): void {
         this.observer.observe(this.element, {
@@ -52,10 +102,15 @@ export class DatasetObserver {
     }
 
     /**
-     * Callback invoked when the element's dataset changes (debounced).
-     * Override in subclasses to handle dataset updates.
+     * Hook invoked when the element's dataset changes.
+     *
+     * Consumers typically override this method (or assign to it) to react to changes such as:
+     * - disabled / readonly / visible flags
+     * - feature toggles exposed via `data-*` attributes
+     *
+     * The `dataset` argument is a shallow copy of the *current* dataset at the time of emission.
      *
-     * @param {Record<string, string>} dataset - A shallow copy of the element's current dataset.
+     * @param dataset - Snapshot of `element.dataset` (string values).
      */
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     public onChanged(dataset: Record<string, string>): void {
@@ -63,7 +118,14 @@ export class DatasetObserver {
     }
 
     /**
-     * Stops observing the element and clears any pending debounce timers.
+     * Stops observing and clears pending debounce work.
+     *
+     * Side effects:
+     * - Cancels the pending debounce timer (if any).
+     * - Disconnects the underlying {@link MutationObserver}.
+     *
+     * Idempotency:
+     * - Safe to call multiple times; subsequent calls will be effectively no-ops after disconnect.
      */
     public disconnect(): void {
         if (this.debounceTimer) clearTimeout(this.debounceTimer);