selective-ui 1.2.3 → 1.2.5

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

@@ -0,0 +1,258 @@
+import { LifecycleHookContext, LifecycleHooks, LifecycleState } from "src/ts/types/core/base/lifecycle.type";
+
+type LifecycleHookName = keyof LifecycleHooks;
+
+/**
+ * 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**.
+ *
+ * ### 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.
+     *
+     * Starts at {@link LifecycleState.NEW} and transitions through the FSM via
+     * {@link init}, {@link mount}, {@link update}, {@link destroy}.
+     */
+    protected state: LifecycleState = LifecycleState.NEW;
+
+    /**
+     * Registered lifecycle hooks.
+     *
+     * 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<(ctx: LifecycleHookContext) => void>> = new Map();
+
+    /**
+     * Constructs the lifecycle manager and pre-registers hook containers.
+     *
+     * 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());
+        this.hooks.set("onMount", new Set());
+        this.hooks.set("onUpdate", new Set());
+        this.hooks.set("onDestroy", new Set());
+    }
+
+    /**
+     * Subscribes a callback to a lifecycle hook.
+     *
+     * 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: (ctx: LifecycleHookContext) => void): this {
+        this.hooks.get(hook)!.add(fn);
+        return this;
+    }
+
+    /**
+     * Unsubscribes a previously registered callback from a lifecycle hook.
+     *
+     * 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: (ctx: LifecycleHookContext) => void): this {
+        this.hooks.get(hook)!.delete(fn);
+        return this;
+    }
+
+    /**
+     * Emits a lifecycle hook by executing all registered callbacks for that hook.
+     *
+     * 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 = {
+            state: this.state,
+            prevState,
+        };
+
+        for (const fn of this.hooks.get(hook)!) {
+            try {
+                fn(ctx);
+            } catch (err) {
+                this.handleHookError(err, hook);
+            }
+        }
+    }
+
+    /**
+     * 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 `NEW → INITIALIZED` and emits `onInit`.
+     *
+     * Idempotent: **no-op** unless current state is {@link LifecycleState.NEW}.
+     *
+     * @returns {void}
+     * @see {@link LifecycleHooks.onInit}
+     */
+    init(): void {
+        if (this.state !== LifecycleState.NEW) return;
+
+        const prev = this.state;
+        this.state = LifecycleState.INITIALIZED;
+        this.emit("onInit", prev);
+    }
+
+    /**
+     * Transitions `INITIALIZED → MOUNTED` and emits `onMount`.
+     *
+     * Guarded: **no-op** unless current state is {@link LifecycleState.INITIALIZED}.
+     *
+     * @returns {void}
+     * @see {@link LifecycleHooks.onMount}
+     */
+    mount(): void {
+        if (this.state !== LifecycleState.INITIALIZED) return;
+
+        const prev = this.state;
+        this.state = LifecycleState.MOUNTED;
+        this.emit("onMount", prev);
+    }
+
+    /**
+     * 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`.
+     *
+     * @returns {void}
+     * @see {@link LifecycleHooks.onUpdate}
+     */
+    update(): void {
+        if (
+            this.state !== LifecycleState.MOUNTED &&
+            this.state !== LifecycleState.UPDATED
+        ) {
+            return;
+        }
+
+        const prev = this.state;
+        this.state = LifecycleState.UPDATED;
+        this.emit("onUpdate", prev);
+    }
+
+    /**
+     * Transitions to `DESTROYED`, emits `onDestroy`, then clears all hook registrations.
+     *
+     * Idempotent: **no-op** if already {@link LifecycleState.DESTROYED}.
+     *
+     * @returns {void}
+     * @see {@link LifecycleHooks.onDestroy}
+     */
+    destroy(): void {
+        if (this.state === LifecycleState.DESTROYED) return;
+
+        const prev = this.state;
+        this.state = LifecycleState.DESTROYED;
+        this.emit("onDestroy", prev);
+        this.clearHooks();
+    }
+
+    /**
+     * Returns the current lifecycle state.
+     *
+     * @returns {LifecycleState} Current FSM state.
+     */
+    getState(): LifecycleState {
+        return this.state;
+    }
+
+    /**
+     * Checks whether the lifecycle is in the specified state.
+     *
+     * @param {LifecycleState} state - State to compare against.
+     * @returns {boolean} `true` if current state matches; otherwise `false`.
+     */
+    is(state: LifecycleState): boolean {
+        return this.state === state;
+    }
+
+    /**
+     * Clears all registered lifecycle hooks.
+     *
+     * 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()) {
+            set.clear();
+        }
+    }
+}

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

@@ -1,81 +1,170 @@
 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";
 
 /**
- * @template TTarget
- * @template TTags
- * @template TView
+ * 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).
+ *
+ * ### 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,
     TTags extends Record<string, HTMLElement>,
     TView extends ViewContract<TTags>,
     TOptions = unknown
-> implements ModelContract<TTarget, TView> {
+> extends Lifecycle implements ModelContract<TTarget, TView> {
+
+    /**
+     * 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 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.
+     *
+     * 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 used by list infrastructure for ordering/tracking.
+     * Semantics are library-specific (e.g., top-level index or adapter position).
+     */
     public position = -1;
 
+    /**
+     * 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 this model has been removed/destroyed from the active dataset.
+     * Set to `true` during {@link destroy}.
+     */
     public isRemoved = false;
+
     /**
-     * Returns the current value from the underlying target element's "value" attribute.
-     * For single-select, this is typically a string; for multi-select, may be an array depending on usage.
+     * 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.
+     *
+     * @returns {string | null | string[]} The value representation of the target element.
      */
     public get value(): string | null | string[] {
         return this.targetElement?.getAttribute("value") ?? 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 a new model instance and initializes lifecycle state.
+     *
+     * - Captures {@link options}.
+     * - Optionally binds an initial {@link targetElement} and {@link view}.
+     * - Calls {@link Lifecycle.init} immediately (`NEW → INITIALIZED`).
      *
      * @param {TOptions} options - Configuration options for the model.
-     * @param {TTarget|null} [targetElement=null] - The underlying element (e.g., <option> or group node).
-     * @param {TView|null} [view=null] - The associated view responsible for rendering 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, targetElement: TTarget | null = null, view: TView | null = null) {
+    public constructor(
+        options: TOptions,
+        targetElement: TTarget | null = null,
+        view: TView | null = null
+    ) {
+        super();
         this.options = options;
         this.targetElement = targetElement;
         this.view = view;
+
+        this.init();
     }
 
     /**
-     * Updates the bound target element reference and invokes the change hook.
+     * Rebinds this model to a new target DOM element and marks the model as updated.
      *
-     * @param {TTarget|null} targetElement - The new target element to bind to the 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 update(targetElement: TTarget | null): void {
+    public updateTarget(targetElement: TTarget | null): void {
         this.targetElement = targetElement;
-        this.onTargetChanged();
+        this.update();
     }
 
     /**
-     * Cleans up references and invokes the removal hook when the model is no longer needed.
+     * 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.
+     *
+     * @returns {void}
+     * @override
      */
-    public remove() {
+    public override destroy(): void {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+
         this.targetElement = null;
-        this.view?.getView()?.remove?.();
+        this.view?.destroy();
         this.view = null;
         this.isRemoved = true;
-        this.onRemove();
-    }
-
-    /**
-     * Hook invoked whenever the target element changes.
-     * Override in subclasses to react to attribute/content updates (e.g., text, disabled state).
-     */
-    public onTargetChanged(): void { }
 
-    /**
-     * Hook invoked whenever the target element is removed.
-     * Override in subclasses to react to removal of the element.
-     */
-    public onRemove(): void {}
+        super.destroy();
+    }
 }

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

@@ -1,18 +1,34 @@
 import type { ModelContract } from "../../types/core/base/model.type";
 import type { AdapterContract } from "../../types/core/base/adapter.type";
 import type { RecyclerViewContract } from "../../types/core/base/recyclerview.type";
+import { Lifecycle } from "./lifecycle";
+import { LifecycleState } from "src/ts/types/core/base/lifecycle.type";
 
 /**
- * @template TItem
- * @template TAdapter
+ * RecyclerView renders models provided by an Adapter into a container element.
+ *
+ * Responsibilities:
+ * - Maintain a root container (`viewElement`) where item views are rendered
+ * - Attach an Adapter and wire item-change lifecycle:
+ *   - `onPropChanging('items')` → clear container before items change
+ *   - `onPropChanged('items')` → re-render after items change
+ * - Expose rendering utilities: `render()`, `clear()`, `refresh()`
+ * - Participate in the standard lifecycle (`init` → `mount` → `update` → `destroy`)
+ *
+ * @template TItem - The model type handled by the adapter.
+ * @template TAdapter - The adapter type that manages items and updates the view.
+ *
  * @implements {RecyclerViewContract<TAdapter>}
  */
 export class RecyclerView<
     TItem extends ModelContract<any, any>,
     TAdapter extends AdapterContract<TItem>
-> implements RecyclerViewContract<TAdapter> {
+> extends Lifecycle implements RecyclerViewContract<TAdapter> {
+
+    /** Root container that hosts rendered item views. */
     public viewElement: HTMLDivElement | null = null;
 
+    /** The adapter that manages models and updates the RecyclerView on changes. */
     public adapter: TAdapter | null = null;
 
     /**
@@ -21,23 +37,20 @@ export class RecyclerView<
      * @param {HTMLDivElement|null} [viewElement=null] - The root element where the adapter will render items.
      */
     constructor(viewElement: HTMLDivElement | null = null) {
+        super();
         this.viewElement = viewElement;
-    }
-
-    /**
-     * Sets or updates the container element used to render the adapter's item views.
-     *
-     * @param {HTMLDivElement} viewElement - The root element for rendering.
-     */
-    public setView(viewElement: HTMLDivElement): void {
-        this.viewElement = viewElement;
+        this.init();
     }
 
     /**
      * Attaches an adapter to the RecyclerView and wires item-change lifecycle:
-     * - onPropChanging("items"): clears the container before items change,
-     * - onPropChanged("items"): re-renders after items change,
-     * then performs an initial render.
+     * - `onPropChanging('items')`: clears the container before items change
+     * - `onPropChanged('items')`: re-renders after items change
+     *
+     * Then performs:
+     * - `adapter.mount()` to initialize the adapter
+     * - `this.mount()` to mark the RecyclerView as mounted
+     * - An initial `render()` to sync the UI
      *
      * @param {TAdapter} adapter - The adapter managing models and their views.
      */
@@ -52,12 +65,15 @@ export class RecyclerView<
             this.render();
         });
 
+        adapter.mount();
+
+        this.mount();
         this.render();
     }
 
     /**
      * Removes all child nodes from the rendering container, if present.
-     * Used prior to re-rendering or when items are changing.
+     * Typically used right before re-rendering or when items are about to change.
      */
     public clear(): void {
         if (!this.viewElement) return;
@@ -67,19 +83,40 @@ export class RecyclerView<
     /**
      * Renders the current adapter contents into the container.
      * No-ops if either the adapter or the container is not set.
+     * Emits the `update` lifecycle after delegating rendering to the adapter.
      */
     public render(): void {
         if (!this.adapter || !this.viewElement) return;
         this.adapter.updateRecyclerView(this.viewElement);
+        this.update();
     }
 
     /**
      * Forces a re-render of the current adapter state into the container.
      * Useful when visual updates are required without changing the data.
-     * 
-     * @param isUpdate - Indicates if this refresh is due to an update operation.
+     *
+     * @param {boolean} isUpdate - Indicates if this refresh originates from an update operation.
+     *                             (Reserved for future use; no impact on logic.)
      */
     public refresh(isUpdate: boolean): void {
         this.render();
     }
+
+    /**
+     * Destroys the RecyclerView, detaching from its adapter and container.
+     *
+     * - Delegates teardown to the adapter
+     * - Clears strong references (adapter, viewElement)
+     * - Ends the lifecycle
+     */
+    public override destroy(): void {
+        if (this.is(LifecycleState.DESTROYED)) {
+            return;
+        }
+        
+        this.viewElement = null;
+        this.adapter = null;
+
+        super.destroy();
+    }
 }