selective-ui 1.2.4 → 1.2.5

package/src/ts/core/base/lifecycle.ts

@@ -1,18 +1,51 @@
-
 import { LifecycleHookContext, LifecycleHooks, LifecycleState } from "src/ts/types/core/base/lifecycle.type";
 
 type LifecycleHookName = keyof LifecycleHooks;
 
 /**
- * Lightweight lifecycle manager that provides:
- * - A finite-state lifecycle machine (`NEW` → `INITIALIZED` → `MOUNTED` → `UPDATED` → `DESTROYED`)
- * - A simple hooks system to subscribe to lifecycle events (`onInit`, `onMount`, `onUpdate`, `onDestroy`)
+ * Minimal lifecycle finite-state machine (FSM) with a lightweight hook system.
+ *
+ * ### Responsibility
+ * - Provide a **strict**, **guarded** lifecycle FSM:
+ *   `NEW → INITIALIZED → MOUNTED → UPDATED → DESTROYED`
+ * - Provide an in-memory hook registry to observe lifecycle transitions:
+ *   `onInit`, `onMount`, `onUpdate`, `onDestroy`
+ *
+ * This class is designed to be extended by core primitives (Model/View/Adapter/Controller)
+ * so they share consistent lifecycle semantics without coupling to any rendering runtime.
+ *
+ * ### FSM & Idempotency
+ * - `init()` is **idempotent**: only transitions `NEW → INITIALIZED`; otherwise **no-op**.
+ * - `mount()` is **guarded**: only transitions `INITIALIZED → MOUNTED`; otherwise **no-op**.
+ * - `update()` is **repeatable** once mounted: allowed in `MOUNTED` and `UPDATED`.
+ *   It always emits `onUpdate` and keeps state at `UPDATED`.
+ * - `destroy()` is **idempotent**: once `DESTROYED`, subsequent calls are **no-op**.
  *
- * Classes in the core (e.g., Model/View) can extend this to standardize initialization,
- * mounting, updates, and teardown. Hooks are stored as in-memory callbacks and cleared on destroy.
+ * ### Hook semantics
+ * - Hooks are stored in a `Set` per hook name:
+ *   - de-duplicates identical callback references,
+ *   - preserves insertion order for deterministic execution.
+ * - Hook callbacks receive a {@link LifecycleHookContext} containing:
+ *   - `state` (current state after transition),
+ *   - `prevState` (state prior to the transition).
+ * - Hook exceptions are caught and forwarded to {@link handleHookError},
+ *   preventing a single subscriber from breaking the lifecycle flow.
+ *
+ * ### Memory & teardown
+ * - All registered hooks are cleared on `destroy()` via {@link clearHooks}.
+ * - Post-destroy calls to lifecycle methods do not emit further hooks.
+ *
+ * @see {@link LifecycleState}
+ * @see {@link LifecycleHooks}
+ * @see {@link LifecycleHookContext}
  */
 export class Lifecycle {
-    /** Current lifecycle state */
+    /**
+     * Current lifecycle state.
+     *
+     * Starts at {@link LifecycleState.NEW} and transitions through the FSM via
+     * {@link init}, {@link mount}, {@link update}, {@link destroy}.
+     */
     protected state: LifecycleState = LifecycleState.NEW;
 
     /**
@@ -21,12 +54,18 @@ export class Lifecycle {
      * Uses a Set per hook to:
      * - Avoid duplicate registrations
      * - Preserve insertion order for deterministic execution
+     *
+     * @remarks
+     * This map is initialized with keys for all supported hooks in the constructor.
+     * Callbacks are cleared on {@link destroy}.
      */
-    private hooks: Map<LifecycleHookName, Set<Function>> = new Map();
+    private hooks: Map<LifecycleHookName, Set<(ctx: LifecycleHookContext) => void>> = new Map();
 
     /**
      * Constructs the lifecycle manager and pre-registers hook containers.
-     * No hooks are executed during construction.
+     *
+     * No hooks are executed during construction; consumers must call
+     * {@link init}, {@link mount}, {@link update}, or {@link destroy}.
      */
     constructor() {
         this.hooks.set("onInit", new Set());
@@ -38,11 +77,14 @@ export class Lifecycle {
     /**
      * Subscribes a callback to a lifecycle hook.
      *
-     * @param hook - The lifecycle hook name to listen to
-     * @param fn - The callback to execute when the hook is emitted
-     * @returns `this` for chaining
+     * Hook callbacks are invoked in insertion order. Duplicate callback references are ignored
+     * due to Set semantics.
+     *
+     * @param {LifecycleHookName} hook - Hook name to subscribe to.
+     * @param {(ctx: LifecycleHookContext) => void} fn - Callback invoked when the hook is emitted.
+     * @returns {this} The current instance (chainable).
      */
-    on(hook: LifecycleHookName, fn: () => void): this {
+    on(hook: LifecycleHookName, fn: (ctx: LifecycleHookContext) => void): this {
         this.hooks.get(hook)!.add(fn);
         return this;
     }
@@ -50,22 +92,31 @@ export class Lifecycle {
     /**
      * Unsubscribes a previously registered callback from a lifecycle hook.
      *
-     * @param hook - The lifecycle hook name
-     * @param fn - The callback to remove
-     * @returns `this` for chaining
+     * Safe to call even if the callback was never registered (no-op).
+     *
+     * @param {LifecycleHookName} hook - Hook name to unsubscribe from.
+     * @param {(ctx: LifecycleHookContext) => void} fn - Callback to remove.
+     * @returns {this} The current instance (chainable).
      */
-    off(hook: LifecycleHookName, fn: () => void): this {
+    off(hook: LifecycleHookName, fn: (ctx: LifecycleHookContext) => void): this {
         this.hooks.get(hook)!.delete(fn);
         return this;
     }
 
     /**
-     * Emits a lifecycle hook, executing all registered callbacks
-     * in the order they were added.
+     * Emits a lifecycle hook by executing all registered callbacks for that hook.
      *
-     * @param hook - The lifecycle hook to emit
-     * @internal Prefer using the public lifecycle methods (`init/mount/update/destroy`)
-     *           which call `emit` at the correct times.
+     * Execution model:
+     * - Callbacks run in insertion order.
+     * - Errors thrown by callbacks are caught and forwarded to {@link handleHookError}.
+     *
+     * @param {LifecycleHookName} hook - The hook to emit.
+     * @param {LifecycleState} prevState - The state prior to the transition.
+     * @returns {void}
+     *
+     * @internal
+     * Prefer invoking the public lifecycle methods ({@link init}, {@link mount}, {@link update}, {@link destroy})
+     * which call `emit()` at the correct time and enforce FSM guards.
      */
     protected emit(hook: LifecycleHookName, prevState: LifecycleState): void {
         const ctx: LifecycleHookContext = {
@@ -82,14 +133,28 @@ export class Lifecycle {
         }
     }
 
+    /**
+     * Handles errors thrown by lifecycle hook callbacks.
+     *
+     * Default behavior logs to `console.error` with a hook-scoped prefix.
+     * Subclasses may override to integrate with application logging/telemetry.
+     *
+     * @param {unknown} error - Error thrown by a hook callback.
+     * @param {LifecycleHookName} hook - Hook name during which the error occurred.
+     * @returns {void}
+     * @protected
+     */
     protected handleHookError(error: unknown, hook: LifecycleHookName): void {
         console.error(`[Lifecycle:${hook}]`, error);
     }
 
     /**
-     * Transitions from `NEW` → `INITIALIZED` and emits `onInit`.
+     * Transitions `NEW → INITIALIZED` and emits `onInit`.
+     *
+     * Idempotent: **no-op** unless current state is {@link LifecycleState.NEW}.
      *
-     * Safe to call multiple times; subsequent calls are no-ops unless current state is `NEW`.
+     * @returns {void}
+     * @see {@link LifecycleHooks.onInit}
      */
     init(): void {
         if (this.state !== LifecycleState.NEW) return;
@@ -100,9 +165,12 @@ export class Lifecycle {
     }
 
     /**
-     * Transitions from `INITIALIZED` → `MOUNTED` and emits `onMount`.
+     * Transitions `INITIALIZED → MOUNTED` and emits `onMount`.
      *
-     * No-ops if current state is not `INITIALIZED` (guards against invalid order).
+     * Guarded: **no-op** unless current state is {@link LifecycleState.INITIALIZED}.
+     *
+     * @returns {void}
+     * @see {@link LifecycleHooks.onMount}
      */
     mount(): void {
         if (this.state !== LifecycleState.INITIALIZED) return;
@@ -113,10 +181,16 @@ export class Lifecycle {
     }
 
     /**
-     * Transitions from `MOUNTED` → `UPDATED` and emits `onUpdate`.
+     * Emits `onUpdate` and transitions to/keeps state `UPDATED`.
+     *
+     * Allowed states:
+     * - `MOUNTED` → `UPDATED`
+     * - `UPDATED` → `UPDATED` (repeatable updates still emit)
+     *
+     * Guarded: **no-op** unless current state is `MOUNTED` or `UPDATED`.
      *
-     * No-ops if not currently `MOUNTED`. Subsequent `update()` calls will keep the state
-     * at `UPDATED` while still emitting `onUpdate`.
+     * @returns {void}
+     * @see {@link LifecycleHooks.onUpdate}
      */
     update(): void {
         if (
@@ -132,9 +206,12 @@ export class Lifecycle {
     }
 
     /**
-     * Transitions to `DESTROYED` and emits `onDestroy`, then clears all hooks.
+     * Transitions to `DESTROYED`, emits `onDestroy`, then clears all hook registrations.
      *
-     * Idempotent: calling `destroy()` multiple times after destruction has no effect.
+     * Idempotent: **no-op** if already {@link LifecycleState.DESTROYED}.
+     *
+     * @returns {void}
+     * @see {@link LifecycleHooks.onDestroy}
      */
     destroy(): void {
         if (this.state === LifecycleState.DESTROYED) return;
@@ -147,16 +224,18 @@ export class Lifecycle {
 
     /**
      * Returns the current lifecycle state.
+     *
+     * @returns {LifecycleState} Current FSM state.
      */
     getState(): LifecycleState {
         return this.state;
     }
 
     /**
-     * Checks if the lifecycle is in the specified state.
+     * Checks whether the lifecycle is in the specified state.
      *
-     * @param state - The state to compare against
-     * @returns True if the current state matches; otherwise false
+     * @param {LifecycleState} state - State to compare against.
+     * @returns {boolean} `true` if current state matches; otherwise `false`.
      */
     is(state: LifecycleState): boolean {
         return this.state === state;
@@ -165,7 +244,11 @@ export class Lifecycle {
     /**
      * Clears all registered lifecycle hooks.
      *
-     * Called automatically during `destroy()`.
+     * Called automatically during {@link destroy}. After clearing, the hook containers remain
+     * allocated (map keys persist) but contain no subscribers.
+     *
+     * @returns {void}
+     * @private
      */
     private clearHooks(): void {
         for (const set of this.hooks.values()) {

package/src/ts/core/base/model.ts

@@ -1,19 +1,43 @@
-
 import { ModelContract } from "src/ts/types/core/base/model.type";
 import { ViewContract } from "src/ts/types/core/base/view.type";
 import { Lifecycle } from "./lifecycle";
 import { LifecycleState } from "src/ts/types/core/base/lifecycle.type";
 
 /**
- * Base Model class that connects a target DOM element with its corresponding View.
- * Handles lifecycle, state, and synchronization between model, view, and DOM.
+ * Base model primitive that binds a domain object to a target DOM element and an optional View.
+ *
+ * This class is the **Model** part of the library's Model/View separation:
+ * - The **Model** owns references to the authoritative DOM source (`targetElement`) and configuration (`options`).
+ * - The **View** (if attached) owns rendering and DOM event wiring for the model.
+ * - Higher-level infrastructure (e.g., Adapter / RecyclerView) orchestrates when models are created,
+ *   bound to views, and updated.
+ *
+ * ### Lifecycle (Strict FSM)
+ * - Constructor calls {@link Lifecycle.init} immediately, transitioning `NEW → INITIALIZED`.
+ * - This base model does not call `mount()` by itself; mounting is typically handled by the View layer.
+ * - {@link updateTarget} triggers {@link Lifecycle.update}, which emits `onUpdate` lifecycle hooks in
+ *   `MOUNTED/UPDATED` states (and is guarded otherwise).
+ * - {@link destroy} transitions to `DESTROYED`, clears references, and destroys the associated view.
+ *
+ * ### Idempotency / No-ops
+ * - {@link destroy} is idempotent once in {@link LifecycleState.DESTROYED}.
+ * - {@link updateTarget} is safe to call multiple times; consumers should treat repeated assignments
+ *   as a no-op when the target does not change (this base class does not compare equality).
  *
- * @template TTarget - The HTML element this model is bound to
- * @template TTags - A map of named HTML elements used by the view
- * @template TView - The view implementation associated with this model
- * @template TOptions - Configuration options for the model
+ * ### Ownership & side effects
+ * - This model **owns** its `view` reference and will call `view.destroy()` during {@link destroy}.
+ * - The model itself does not mutate the DOM, except reading from `targetElement` (e.g., {@link value}).
+ *   Any DOM side effects are expected to live in the View implementation.
+ *
+ * @template TTarget - The DOM element type this model is bound to (e.g., HTMLOptionElement).
+ * @template TTags - Named element map used by the view (view-specific DOM handles).
+ * @template TView - View implementation associated with this model.
+ * @template TOptions - Configuration/options type carried by the model.
  *
  * @implements {ModelContract<TTarget, TView>}
+ * @extends Lifecycle
+ * @see {@link ViewContract}
+ * @see {@link LifecycleState}
  */
 export class Model<
     TTarget extends HTMLElement,
@@ -22,43 +46,69 @@ export class Model<
     TOptions = unknown
 > extends Lifecycle implements ModelContract<TTarget, TView> {
 
-    /** The underlying DOM element associated with this model */
+    /**
+     * The currently bound target DOM element.
+     *
+     * This element typically represents the source-of-truth node in the host DOM (e.g., a native `<option>`).
+     * May be replaced via {@link updateTarget} during reconciliation.
+     */
     public targetElement: TTarget | null = null;
 
-    /** Configuration options provided at construction time */
+    /**
+     * Configuration options supplied at construction time.
+     * Stored as-is and intended to be consumed by subclasses and/or the view layer.
+     */
     public options: TOptions;
 
-    /** View instance responsible for rendering this model */
+    /**
+     * View instance responsible for rendering this model.
+     *
+     * Ownership: this model will destroy the view on {@link destroy}.
+     * The view may be attached/assigned by external orchestrators (Adapter/RecyclerView) after construction.
+     */
     public view: TView | null = null;
 
-    /** Position index of the model (used for ordering or tracking) */
+    /**
+     * Position index used by list infrastructure for ordering/tracking.
+     * Semantics are library-specific (e.g., top-level index or adapter position).
+     */
     public position = -1;
 
-    /** Indicates whether the model has been initialized */
+    /**
+     * Indicates whether this model has completed its initial binding step.
+     * Typically set by the adapter/view binding layer to prevent duplicate listener wiring.
+     */
     public isInit = false;
 
-    /** Indicates whether the model has been destroyed/removed */
+    /**
+     * Indicates whether this model has been removed/destroyed from the active dataset.
+     * Set to `true` during {@link destroy}.
+     */
     public isRemoved = false;
 
     /**
-     * Returns the current value of the bound target element.
+     * Returns the current "value" associated with the bound target element.
+     *
+     * Implementation note:
+     * - Reads from the target element's `"value"` attribute via `getAttribute("value")`.
+     * - Returns `null` when no target is bound or the attribute is not present.
      *
-     * - For single-value elements, this is usually a string
-     * - For multi-value elements, this may be an array depending on usage
+     * @returns {string | null | string[]} The value representation of the target element.
      */
     public get value(): string | null | string[] {
         return this.targetElement?.getAttribute("value") ?? null;
     }
 
     /**
-     * Creates a new Model instance.
+     * Creates a new model instance and initializes lifecycle state.
      *
-     * Initializes the model with configuration options and optionally binds
-     * it to a target DOM element and a view.
+     * - Captures {@link options}.
+     * - Optionally binds an initial {@link targetElement} and {@link view}.
+     * - Calls {@link Lifecycle.init} immediately (`NEW → INITIALIZED`).
      *
-     * @param options - Configuration options for the model
-     * @param targetElement - Optional DOM element to bind to this model
-     * @param view - Optional view responsible for rendering the model
+     * @param {TOptions} options - Configuration options for the model.
+     * @param {TTarget | null} [targetElement=null] - Optional DOM element to bind.
+     * @param {TView | null} [view=null] - Optional view responsible for rendering this model.
      */
     public constructor(
         options: TOptions,
@@ -74,9 +124,18 @@ export class Model<
     }
 
     /**
-     * Updates the bound target element and triggers the update lifecycle.
+     * Rebinds this model to a new target DOM element and marks the model as updated.
      *
-     * @param targetElement - The new DOM element to associate with this model
+     * Typical usage:
+     * - Reconciliation when the underlying DOM node is replaced (e.g., `<option>` node recreated).
+     * - Keeping model identity stable while swapping its backing DOM node.
+     *
+     * Side effects:
+     * - Assigns {@link targetElement}.
+     * - Calls {@link Lifecycle.update} (guarded by lifecycle state).
+     *
+     * @param {TTarget | null} targetElement - The new DOM element to associate with this model.
+     * @returns {void}
      */
     public updateTarget(targetElement: TTarget | null): void {
         this.targetElement = targetElement;
@@ -84,20 +143,19 @@ export class Model<
     }
 
     /**
-     * Hook executed when the model is updated.
-     * Intended to be overridden by subclasses.
-     */
-    public onUpdate() { }
-
-    /**
-     * Destroys the model and releases all references.
+     * Destroys this model and releases owned resources.
+     *
+     * Behavior:
+     * - Idempotent once lifecycle is {@link LifecycleState.DESTROYED}.
+     * - Clears {@link targetElement}.
+     * - Destroys the associated {@link view} (if present) and clears the reference.
+     * - Marks {@link isRemoved} as `true`.
+     * - Calls {@link Lifecycle.destroy} to transition to `DESTROYED` and clear hooks.
      *
-     * - Unbinds the target element
-     * - Removes the associated view from the DOM
-     * - Marks the model as removed
-     * - Triggers lifecycle cleanup
+     * @returns {void}
+     * @override
      */
-    public override destroy() {
+    public override destroy(): void {
         if (this.is(LifecycleState.DESTROYED)) {
             return;
         }

package/src/ts/core/base/recyclerview.ts

@@ -114,7 +114,6 @@ export class RecyclerView<
             return;
         }
         
-        this.adapter?.destroy?.();
         this.viewElement = null;
         this.adapter = null;
 

package/src/ts/core/base/view.ts

@@ -4,40 +4,66 @@ import { Lifecycle } from "./lifecycle";
 import { LifecycleState } from "src/ts/types/core/base/lifecycle.type";
 
 /**
- * Base View class that anchors a mounted DOM structure into a parent container.
+ * Base View primitive that anchors a mounted DOM structure into a parent container.
  *
- * Responsibilities:
- * - Hold a reference to the parent container (`parent`)
- * - Store the mounted structure (`view`) returned by a mounting helper
- * - Provide a safe getter for the root element (`getView()`)
- * - Participate in the standard lifecycle (`init` → `mount` → `update` → `destroy`)
+ * This class is the **View** part of the library's Model/View separation:
+ * - A View is responsible for owning/manipulating DOM nodes and exposing typed handles (`tags`)
+ *   for efficient updates.
+ * - A View is typically created/managed by an Adapter/RecyclerView layer and assigned back to a Model.
  *
- * Typical usage:
- * - Subclasses set `this.view` inside `onMount()` using a mounting utility
- * - Then call `this.parent!.appendChild(this.view.view)`
+ * ### Responsibility
+ * - Hold a reference to the host container (`parent`) where the view's root element is attached.
+ * - Store the mounted structure (`view`) produced by a mount utility (root element + typed tag map).
+ * - Provide a safe root accessor ({@link getView}) for downstream code (e.g., scrolling, a11y, styling).
  *
- * @template TTags - A map of tag names to their corresponding HTMLElement instances.
+ * ### Lifecycle (Strict FSM)
+ * - Constructor calls {@link Lifecycle.init} immediately (`NEW → INITIALIZED`).
+ * - Mounting is performed by subclasses / infrastructure:
+ *   - populate {@link view} (usually during a subclass mount hook),
+ *   - append `view.view` to {@link parent},
+ *   - then transition to `MOUNTED` via {@link Lifecycle.mount} (typically done by the base/framework).
+ * - {@link destroy} transitions to `DESTROYED` and removes the root element from the DOM.
+ *
+ * ### Idempotency / No-ops
+ * - {@link destroy} is idempotent once in {@link LifecycleState.DESTROYED}.
+ * - {@link getView} throws if the view is not yet mounted (i.e., {@link view} is unset).
+ *
+ * ### DOM side effects / Ownership
+ * - Owns the root element produced by the mount helper and removes it on {@link destroy}.
+ * - Does not automatically append the root node; external orchestrators (Adapter/RecyclerView) control attachment.
+ *
+ * @template TTags - Map of tag names to their corresponding HTMLElement instances.
  * @implements {ViewContract<TTags>}
+ * @extends Lifecycle
+ * @see {@link MountViewResult}
+ * @see {@link ViewContract}
+ * @see {@link LifecycleState}
  */
 export class View<TTags extends Record<string, HTMLElement>> extends Lifecycle implements ViewContract<TTags> {
-
-    /** The parent DOM element into which this view is rendered. */
+    /**
+     * Host container element into which this view's root element is rendered/attached.
+     *
+     * This reference is captured at construction time and cleared on {@link destroy}.
+     */
     public parent: HTMLElement | null = null;
 
     /**
-     * Mounted result containing:
+     * Mounted view result containing:
      * - `view`: the root element of this view
-     * - `tags`: a strongly-typed map of child elements
+     * - `tags`: a strongly-typed map of child elements for fast access
+     *
+     * This is expected to be assigned by subclasses (or a mount helper) before {@link getView} is called.
      */
     public view: MountViewResult<TTags> | null = null;
 
     /**
-     * Creates a View bound to the specified parent container.
+     * Creates a View bound to the specified parent container and initializes lifecycle state.
      *
-     * Note: Subclasses should assign `this.view` during `onMount()` before
-     * attempting to access `getView()` or manipulate the root element.
+     * Notes:
+     * - This base constructor **does not** perform DOM mounting or attachment.
+     * - Subclasses typically assign {@link view} during their mount step, then append `view.view` to {@link parent}.
      *
-     * @param parent - The parent element into which this view will render.
+     * @param {HTMLElement} parent - Host element into which this view will render.
      */
     public constructor(parent: HTMLElement) {
         super();
@@ -48,8 +74,8 @@ export class View<TTags extends Record<string, HTMLElement>> extends Lifecycle i
     /**
      * Returns the root HTMLElement of the mounted view.
      *
-     * @returns The root element produced by the mounting helper.
-     * @throws {Error} If the view has not been mounted or `this.view` is not set.
+     * @returns {HTMLElement} The root element produced by the mounting helper.
+     * @throws {Error} If {@link view} is not set or the view has not been mounted yet.
      */
     public getView(): HTMLElement {
         if (!this.view?.view) {
@@ -61,9 +87,14 @@ export class View<TTags extends Record<string, HTMLElement>> extends Lifecycle i
     /**
      * Destroys the view and releases DOM references.
      *
-     * - Removes the root element from the DOM (if present)
-     * - Clears references to `parent` and `view`
-     * - Ends the lifecycle via `super.destroy()`
+     * Behavior:
+     * - Idempotent: returns early if already in {@link LifecycleState.DESTROYED}.
+     * - Removes the root element from the DOM (if present).
+     * - Clears references to {@link parent} and {@link view}.
+     * - Completes teardown by calling {@link Lifecycle.destroy}.
+     *
+     * @returns {void}
+     * @override
      */
     public override destroy(): void {
         if (this.is(LifecycleState.DESTROYED)) {