selective-ui 1.3.1 → 1.4.1

package/src/ts/core/base/adapter.ts

@@ -62,9 +62,12 @@ import { LifecycleState } from "src/ts/types/core/base/lifecycle.type";
  * @see {@link ModelContract}
  */
 export class Adapter<
-    TItem extends ModelContract<any, any> & { view: TViewer | null; isInit: boolean },
-    TViewer extends ViewContract<any>
-> extends Lifecycle implements AdapterContract<TItem> {
+    TItem extends ModelContract<any, any> & { view?: TViewer; isInit: boolean },
+    TViewer extends ViewContract<any>,
+>
+    extends Lifecycle
+    implements AdapterContract<TItem>
+{
     /**
      * Current list of items managed by the adapter.
      *
@@ -118,7 +121,11 @@ export class Adapter<
      * @param {number} position - Index of the item within the adapter item list.
      * @returns {void}
      */
-    public onViewHolder(item: TItem, viewer: TViewer | null, position: number): void {
+    public onViewHolder(
+        item: TItem,
+        viewer?: TViewer,
+        position?: number,
+    ): void {
         void position;
 
         const v = viewer;
@@ -142,8 +149,15 @@ export class Adapter<
      * @returns {void}
      * @see {@link changingProp}
      */
-    public onPropChanging(propName: string, callback: (...args: unknown[]) => void): void {
-        Libs.callbackScheduler.on(`${propName}ing_${this.adapterKey}`, callback, { debounce: 0 });
+    public onPropChanging(
+        propName: string,
+        callback: (...args: unknown[]) => void,
+    ): void {
+        Libs.callbackScheduler.on(
+            `${propName}ing_${this.adapterKey}`,
+            callback,
+            { debounce: 0 },
+        );
     }
 
     /**
@@ -159,8 +173,13 @@ export class Adapter<
      * @returns {void}
      * @see {@link changeProp}
      */
-    public onPropChanged(propName: string, callback: (...args: unknown[]) => void): void {
-        Libs.callbackScheduler.on(`${propName}_${this.adapterKey}`, callback, { debounce: 0 });
+    public onPropChanged(
+        propName: string,
+        callback: (...args: unknown[]) => void,
+    ): void {
+        Libs.callbackScheduler.on(`${propName}_${this.adapterKey}`, callback, {
+            debounce: 0,
+        });
     }
 
     /**
@@ -174,7 +193,10 @@ export class Adapter<
      * @returns {Promise<void>} Resolves when scheduled callbacks complete.
      */
     public changeProp(propName: string, ...params: unknown[]): Promise<void> {
-        return Libs.callbackScheduler.run(`${propName}_${this.adapterKey}`, ...params);
+        return Libs.callbackScheduler.run(
+            `${propName}_${this.adapterKey}`,
+            ...params,
+        );
     }
 
     /**
@@ -188,7 +210,10 @@ export class Adapter<
      * @returns {Promise<void>} Resolves when scheduled callbacks complete.
      */
     public changingProp(propName: string, ...params: unknown[]): Promise<void> {
-        return Libs.callbackScheduler.run(`${propName}ing_${this.adapterKey}`, ...params);
+        return Libs.callbackScheduler.run(
+            `${propName}ing_${this.adapterKey}`,
+            ...params,
+        );
     }
 
     /**
@@ -198,9 +223,9 @@ export class Adapter<
      *
      * @param {HTMLElement} parent - Container element that will host the viewer.
      * @param {TItem} item - The model for which the viewer is created.
-     * @returns {TViewer | null} The created viewer instance; `null` by default.
+     * @returns {TViewer} The created viewer instance; `null` by default.
      */
-    public viewHolder(parent: HTMLElement, item: TItem): TViewer | null {
+    public viewHolder?(parent: HTMLElement, item: TItem): TViewer {
         void parent;
         void item;
         return null;
@@ -317,9 +342,9 @@ export class Adapter<
         }
 
         this.recyclerView = null;
-        this.items.forEach(item => {
+        this.items.forEach((item) => {
             item?.destroy?.();
         });
         this.items = [];
     }
-}
+}

package/src/ts/core/base/fenwick.ts

@@ -131,7 +131,8 @@ export class Fenwick extends Lifecycle {
      * Returns 0 if the first element already exceeds `target`.
      */
     public lowerBoundPrefix(target: number): number {
-        let idx = 0, bitMask = 1;
+        let idx = 0,
+            bitMask = 1;
         while (bitMask << 1 <= this.stackNum) bitMask <<= 1;
 
         let cur = 0;
@@ -144,4 +145,4 @@ export class Fenwick extends Lifecycle {
         }
         return idx;
     }
-}
+}

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

@@ -1,4 +1,8 @@
-import { LifecycleHookContext, LifecycleHooks, LifecycleState } from "src/ts/types/core/base/lifecycle.type";
+import {
+    LifecycleHookContext,
+    LifecycleHooks,
+    LifecycleState,
+} from "src/ts/types/core/base/lifecycle.type";
 
 type LifecycleHookName = keyof LifecycleHooks;
 
@@ -59,7 +63,10 @@ export class Lifecycle {
      * 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();
+    private hooks: Map<
+        LifecycleHookName,
+        Set<(ctx: LifecycleHookContext) => void>
+    > = new Map();
 
     /**
      * Constructs the lifecycle manager and pre-registers hook containers.
@@ -98,7 +105,10 @@ export class Lifecycle {
      * @param {(ctx: LifecycleHookContext) => void} fn - Callback to remove.
      * @returns {this} The current instance (chainable).
      */
-    off(hook: LifecycleHookName, fn: (ctx: LifecycleHookContext) => void): this {
+    off(
+        hook: LifecycleHookName,
+        fn: (ctx: LifecycleHookContext) => void,
+    ): this {
         this.hooks.get(hook)!.delete(fn);
         return this;
     }
@@ -255,4 +265,4 @@ export class Lifecycle {
             set.clear();
         }
     }
-}
+}

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

@@ -43,16 +43,18 @@ export class Model<
     TTarget extends HTMLElement,
     TTags extends Record<string, HTMLElement>,
     TView extends ViewContract<TTags>,
-    TOptions = unknown
-> extends Lifecycle implements ModelContract<TTarget, TView> {
-
+    TOptions = unknown,
+>
+    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;
+    public targetElement?: TTarget;
 
     /**
      * Configuration options supplied at construction time.
@@ -66,25 +68,25 @@ export class 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;
+    public view?: TView;
 
     /**
      * Position index used by list infrastructure for ordering/tracking.
      * Semantics are library-specific (e.g., top-level index or adapter position).
      */
-    public position = -1;
+    public position: number = -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;
+    public isInit: boolean = false;
 
     /**
      * Indicates whether this model has been removed/destroyed from the active dataset.
      * Set to `true` during {@link destroy}.
      */
-    public isRemoved = false;
+    public isRemoved: boolean = false;
 
     /**
      * Returns the current "value" associated with the bound target element.
@@ -107,13 +109,13 @@ export class Model<
      * - Calls {@link Lifecycle.init} immediately (`NEW → INITIALIZED`).
      *
      * @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.
+     * @param {TTarget} [targetElement=null] - Optional DOM element to bind.
+     * @param {TView} [view=null] - Optional view responsible for rendering this model.
      */
     public constructor(
         options: TOptions,
-        targetElement: TTarget | null = null,
-        view: TView | null = null
+        targetElement?: TTarget,
+        view?: TView,
     ) {
         super();
         this.options = options;
@@ -134,10 +136,10 @@ export class Model<
      * - Assigns {@link targetElement}.
      * - Calls {@link Lifecycle.update} (guarded by lifecycle state).
      *
-     * @param {TTarget | null} targetElement - The new DOM element to associate with this model.
+     * @param {TTarget} targetElement - The new DOM element to associate with this model.
      * @returns {void}
      */
-    public updateTarget(targetElement: TTarget | null): void {
+    public updateTarget(targetElement?: TTarget): void {
         this.targetElement = targetElement;
         this.update();
     }
@@ -167,4 +169,4 @@ export class Model<
 
         super.destroy();
     }
-}
+}

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

@@ -22,9 +22,11 @@ import { LifecycleState } from "src/ts/types/core/base/lifecycle.type";
  */
 export class RecyclerView<
     TItem extends ModelContract<any, any>,
-    TAdapter extends AdapterContract<TItem>
-> extends Lifecycle implements RecyclerViewContract<TAdapter> {
-
+    TAdapter extends AdapterContract<TItem>,
+>
+    extends Lifecycle
+    implements RecyclerViewContract<TAdapter>
+{
     /** Root container that hosts rendered item views. */
     public viewElement: HTMLDivElement | null = null;
 
@@ -113,10 +115,10 @@ export class RecyclerView<
         if (this.is(LifecycleState.DESTROYED)) {
             return;
         }
-        
+
         this.viewElement = null;
         this.adapter = null;
 
         super.destroy();
     }
-}
+}

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

@@ -39,13 +39,16 @@ import { LifecycleState } from "src/ts/types/core/base/lifecycle.type";
  * @see {@link ViewContract}
  * @see {@link LifecycleState}
  */
-export class View<TTags extends Record<string, HTMLElement>> extends Lifecycle implements ViewContract<TTags> {
+export class View<TTags extends Record<string, HTMLElement>>
+    extends Lifecycle
+    implements ViewContract<TTags>
+{
     /**
      * 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;
+    public parent?: HTMLElement;
 
     /**
      * Mounted view result containing:
@@ -54,7 +57,7 @@ export class View<TTags extends Record<string, HTMLElement>> extends Lifecycle i
      *
      * This is expected to be assigned by subclasses (or a mount helper) before {@link getView} is called.
      */
-    public view: MountViewResult<TTags> | null = null;
+    public view?: MountViewResult<TTags>;
 
     /**
      * Creates a View bound to the specified parent container and initializes lifecycle state.
@@ -79,7 +82,9 @@ export class View<TTags extends Record<string, HTMLElement>> extends Lifecycle i
      */
     public getView(): HTMLElement {
         if (!this.view?.view) {
-            throw new Error("View is not mounted. Did you forget to set this.view?");
+            throw new Error(
+                "View is not mounted. Did you forget to set this.view?",
+            );
         }
         return this.view.view;
     }
@@ -108,4 +113,4 @@ export class View<TTags extends Record<string, HTMLElement>> extends Lifecycle i
 
         super.destroy();
     }
-}
+}

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

@@ -2,7 +2,10 @@ import { ModelContract } from "src/ts/types/core/base/model.type";
 import { RecyclerView } from "./recyclerview";
 import { AdapterContract } from "src/ts/types/core/base/adapter.type";
 import { Libs } from "src/ts/utils/libs";
-import { VirtualOptions, VirtualRecyclerViewTags } from "src/ts/types/core/base/virtual-recyclerview.type";
+import {
+    VirtualOptions,
+    VirtualRecyclerViewTags,
+} from "src/ts/types/core/base/virtual-recyclerview.type";
 import { Lifecycle } from "./lifecycle";
 import { LifecycleState } from "src/ts/types/core/base/lifecycle.type";
 import { Fenwick } from "./fenwick";
@@ -58,7 +61,7 @@ import { Fenwick } from "./fenwick";
  */
 export class VirtualRecyclerView<
     TItem extends ModelContract<any, any>,
-    TAdapter extends AdapterContract<TItem>
+    TAdapter extends AdapterContract<TItem>,
 > extends RecyclerView<TItem, TAdapter> {
     /**
      * Virtualization settings (materialized to `Required<VirtualOptions>`).
@@ -109,8 +112,8 @@ export class VirtualRecyclerView<
     private resizeObs?: ResizeObserver;
 
     /** Pending animation frame ids for window and measurement. */
-    private rafId: number | null = null;
-    private measureRaf: number | null = null;
+    private rafId?: number;
+    private measureRaf?: number;
 
     /** Re-entrancy/suspension flags used to prevent feedback loops. */
     private updating = false;
@@ -138,9 +141,9 @@ export class VirtualRecyclerView<
      *
      * Note: The virtualization scaffold is built when an adapter is set via {@link setAdapter}.
      *
-     * @param {HTMLDivElement | null} [viewElement=null] - Optional root container for the recycler view.
+     * @param {HTMLDivElement} [viewElement=null] - Optional root container for the recycler view.
      */
-    constructor(viewElement: HTMLDivElement | null = null) {
+    constructor(viewElement?: HTMLDivElement) {
         super(viewElement);
     }
 
@@ -187,24 +190,37 @@ export class VirtualRecyclerView<
 
         this.viewElement.replaceChildren();
 
-        const nodeMounted = Libs.mountNode({
-            PadTop:   { tag: { node: "div", classList: "seui-virtual-pad-top" } },
-            ItemsHost:{ tag: { node: "div", classList: "seui-virtual-items" } },
-            PadBottom:{ tag: { node: "div", classList: "seui-virtual-pad-bottom" } },
-        }, this.viewElement) as VirtualRecyclerViewTags;
+        const nodeMounted = Libs.mountNode<VirtualRecyclerViewTags>(
+            {
+                PadTop: {
+                    tag: { node: "div", classList: "seui-virtual-pad-top" },
+                },
+                ItemsHost: {
+                    tag: { node: "div", classList: "seui-virtual-items" },
+                },
+                PadBottom: {
+                    tag: { node: "div", classList: "seui-virtual-pad-bottom" },
+                },
+            },
+            this.viewElement,
+        );
 
         this.PadTop = nodeMounted.PadTop;
         this.ItemsHost = nodeMounted.ItemsHost;
         this.PadBottom = nodeMounted.PadBottom;
 
-        this.scrollEl = this.opts.scrollEl
-            ?? (this.viewElement.closest(".seui-popup") as HTMLElement)
-            ?? (this.viewElement.parentElement as HTMLElement);
+        this.scrollEl =
+            this.opts.scrollEl ??
+            (this.viewElement.closest(".seui-popup") as HTMLElement) ??
+            (this.viewElement.parentElement as HTMLElement);
 
-        if (!this.scrollEl) throw new Error("VirtualRecyclerView: scrollEl not found");
+        if (!this.scrollEl)
+            throw new Error("VirtualRecyclerView: scrollEl not found");
 
         this.boundOnScroll = this.onScroll.bind(this);
-        this.scrollEl.addEventListener("scroll", this.boundOnScroll, { passive: true });
+        this.scrollEl.addEventListener("scroll", this.boundOnScroll, {
+            passive: true,
+        });
 
         this.refresh(false);
         this.attachResizeObserverOnce();
@@ -249,7 +265,9 @@ export class VirtualRecyclerView<
         this.suspended = false;
 
         if (this.scrollEl && this.boundOnScroll) {
-            this.scrollEl.addEventListener("scroll", this.boundOnScroll, { passive: true });
+            this.scrollEl.addEventListener("scroll", this.boundOnScroll, {
+                passive: true,
+            });
         }
 
         if (this.resumeResizeAfter) {
@@ -310,7 +328,10 @@ export class VirtualRecyclerView<
      * @param {{ scrollIntoView?: boolean }} [opt] - Optional behavior controls.
      * @returns {void}
      */
-    public ensureRendered(index: number, opt?: { scrollIntoView?: boolean }): void {
+    public ensureRendered(
+        index: number,
+        opt?: { scrollIntoView?: boolean },
+    ): void {
         this.mountRange(index, index);
         if (opt?.scrollIntoView) this.scrollToIndex(index);
     }
@@ -334,7 +355,10 @@ export class VirtualRecyclerView<
         const topInContainer = this.offsetTopOf(index);
         const containerTop = this.containerTopInScroll();
         const target = containerTop + topInContainer;
-        const maxScroll = Math.max(0, this.scrollEl.scrollHeight - this.scrollEl.clientHeight);
+        const maxScroll = Math.max(
+            0,
+            this.scrollEl.scrollHeight - this.scrollEl.clientHeight,
+        );
 
         this.scrollEl.scrollTop = Math.min(Math.max(0, target), maxScroll);
     }
@@ -358,7 +382,7 @@ export class VirtualRecyclerView<
         }
 
         this.resizeObs?.disconnect();
-        this.created.forEach(el => el.remove());
+        this.created.forEach((el) => el.remove());
         this.created.clear();
     }
 
@@ -442,7 +466,7 @@ export class VirtualRecyclerView<
      * @returns {void}
      */
     private resetState(): void {
-        this.created.forEach(el => el.remove());
+        this.created.forEach((el) => el.remove());
         this.created.clear();
         this.heightCache = [];
         this.fenwick.reset(0);
@@ -557,7 +581,9 @@ export class VirtualRecyclerView<
         const now = performance.now();
         if (now - this.stickyCacheTick < 16) return this.stickyCacheVal;
 
-        const sticky = this.scrollEl.querySelector(".seui-option-handle:not(.hide)") as HTMLElement | null;
+        const sticky = this.scrollEl.querySelector(
+            ".seui-option-handle:not(.hide)",
+        ) as HTMLElement | null;
         this.stickyCacheVal = sticky?.offsetHeight ?? 0;
         this.stickyCacheTick = now;
         return this.stickyCacheVal;
@@ -623,7 +649,7 @@ export class VirtualRecyclerView<
     private rebuildFenwick(count: number): void {
         const est = this.getEstimate();
         const arr = Array.from({ length: count }, (_, i) =>
-            this.isIndexVisible(i) ? (this.heightCache[i] ?? est) : 0
+            this.isIndexVisible(i) ? (this.heightCache[i] ?? est) : 0,
         );
         this.fenwick.buildFrom(arr);
     }
@@ -738,8 +764,12 @@ export class VirtualRecyclerView<
         const next = el.nextElementSibling as HTMLElement | null;
 
         const needsReorder =
-            (prev && Number(prev.getAttribute(VirtualRecyclerView.ATTR_INDEX)) > index) ||
-            (next && Number(next.getAttribute(VirtualRecyclerView.ATTR_INDEX)) < index);
+            (prev &&
+                Number(prev.getAttribute(VirtualRecyclerView.ATTR_INDEX)) >
+                    index) ||
+            (next &&
+                Number(next.getAttribute(VirtualRecyclerView.ATTR_INDEX)) <
+                    index);
 
         if (needsReorder) {
             el.remove();
@@ -763,7 +793,13 @@ export class VirtualRecyclerView<
         if (this.resizeObs) return;
 
         this.resizeObs = new ResizeObserver(() => {
-            if (this.suppressResize || this.suspended || !this.adapter || this.measureRaf != null) return;
+            if (
+                this.suppressResize ||
+                this.suspended ||
+                !this.adapter ||
+                this.measureRaf != null
+            )
+                return;
 
             this.measureRaf = requestAnimationFrame(() => {
                 this.measureRaf = null;
@@ -794,7 +830,9 @@ export class VirtualRecyclerView<
             if (!this.isIndexVisible(i)) continue;
 
             const item = this.adapter.items[i];
-            const el = (item as any)?.view?.getView?.() as HTMLElement | undefined;
+            const el = (item as any)?.view?.getView?.() as
+                | HTMLElement
+                | undefined;
             if (!el) continue;
 
             const newH = this.measureOuterHeight(el);
@@ -857,7 +895,8 @@ export class VirtualRecyclerView<
 
             const anchorIndex = this.findFirstVisibleIndex(stRel, count);
             const anchorTop = this.offsetTopOf(anchorIndex);
-            const anchorDelta = containerTop + anchorTop - this.scrollEl.scrollTop;
+            const anchorDelta =
+                containerTop + anchorTop - this.scrollEl.scrollTop;
 
             const firstVis = this.findFirstVisibleIndex(stRel, count);
             if (firstVis === -1) {
@@ -868,12 +907,21 @@ export class VirtualRecyclerView<
             const est = this.getEstimate();
             const overscanPx = this.opts.overscan * est;
 
-            let startIndex = this.nextVisibleFrom(
-                Math.min(count - 1, this.fenwick.lowerBoundPrefix(Math.max(0, stRel - overscanPx))),
-                count
-            ) ?? firstVis;
-
-            let endIndex = Math.min(count - 1, this.fenwick.lowerBoundPrefix(stRel + vhEff + overscanPx));
+            let startIndex =
+                this.nextVisibleFrom(
+                    Math.min(
+                        count - 1,
+                        this.fenwick.lowerBoundPrefix(
+                            Math.max(0, stRel - overscanPx),
+                        ),
+                    ),
+                    count,
+                ) ?? firstVis;
+
+            let endIndex = Math.min(
+                count - 1,
+                this.fenwick.lowerBoundPrefix(stRel + vhEff + overscanPx),
+            );
 
             if (startIndex === this.start && endIndex === this.end) return;
 
@@ -900,8 +948,12 @@ export class VirtualRecyclerView<
 
             // Keep anchor item stable to prevent scroll jump
             const anchorTopNew = this.offsetTopOf(anchorIndex);
-            const targetScroll = this.containerTopInScroll() + anchorTopNew - anchorDelta;
-            const maxScroll = Math.max(0, this.scrollEl.scrollHeight - this.scrollEl.clientHeight);
+            const targetScroll =
+                this.containerTopInScroll() + anchorTopNew - anchorDelta;
+            const maxScroll = Math.max(
+                0,
+                this.scrollEl.scrollHeight - this.scrollEl.clientHeight,
+            );
             const clamped = Math.min(Math.max(0, targetScroll), maxScroll);
 
             const heightChanged = Math.abs(anchorTopNew - anchorTop) > 1;
@@ -1036,4 +1088,4 @@ export class VirtualRecyclerView<
     private totalHeight(count: number): number {
         return this.fenwick.sum(count);
     }
-}
+}