selective-ui 1.4.0 → 1.4.2

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;
@@ -119,6 +122,12 @@ export class VirtualRecyclerView<
     private suspended = false;
     private boundOnScroll?: () => void;
     private resumeResizeAfter = false;
+    /**
+     * When set, scrollToIndex() will be called after the next measureVisibleAndUpdate()
+     * completes and Fenwick has been updated with real heights.
+     * Set by ensureRendered() and cleared after the corrective scroll fires.
+     */
+    private pendingScrollToIndex: number | null = null;
 
     /** Small cache for sticky header height (≈16ms TTL) to limit layout reads. */
     private stickyCacheTick = 0;
@@ -138,9 +147,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 +196,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 +271,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,9 +334,25 @@ export class VirtualRecyclerView<
      * @param {{ scrollIntoView?: boolean }} [opt] - Optional behavior controls.
      * @returns {void}
      */
-    public ensureRendered(index: number, opt?: { scrollIntoView?: boolean }): void {
-        this.mountRange(index, index);
-        if (opt?.scrollIntoView) this.scrollToIndex(index);
+    public ensureRendered(
+        index: number,
+        opt?: { scrollIntoView?: boolean },
+    ): void {
+        if (!opt?.scrollIntoView) {
+            // No scroll requested — mount only (legacy path, used by probes).
+            this.mountRange(index, index);
+            return;
+        }
+
+        // Pass 1: instant — brings window to vicinity, triggers measure.
+        // Must be instant so Pass 2 smooth scroll isn't interrupted mid-animation.
+        this.scrollToIndex(index, "instant");
+
+        // Pass 2: measureVisibleAndUpdate() will consume this and fire a corrective
+        // smooth scroll after Fenwick has been updated with real heights.
+        // rv.resume() is guaranteed to run before this callback (popup.open onComplete
+        // calls rv.resume() first), so the window is already rendered when we arrive here.
+        this.pendingScrollToIndex = index;
     }
 
     /**
@@ -327,16 +367,32 @@ export class VirtualRecyclerView<
      * @param {number} index - Item index to bring into view.
      * @returns {void}
      */
-    public scrollToIndex(index: number): void {
+    public scrollToIndex(index: number, behavior: ScrollBehavior = "smooth"): void {
         const count = this.adapter?.itemCount?.() ?? 0;
         if (count <= 0) return;
 
         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 stickyH = this.stickyTopHeight();
+        const viewportH = Math.max(0, this.scrollEl.clientHeight - stickyH);
+
+        // item height from cache, or current estimate for unmeasured items
+        const est = this.getEstimate();
+        const itemH = this.heightCache[index] ?? est;
 
-        this.scrollEl.scrollTop = Math.min(Math.max(0, target), maxScroll);
+        // Align item center to viewport center (below any sticky header).
+        // viewportH already excludes stickyH, so no further offset needed.
+        // Equivalent to scrollIntoView({ block: "center" }).
+        const centeredTarget = containerTop + topInContainer
+            - (viewportH - itemH) / 3;
+
+        const maxScroll = Math.max(
+            0,
+            this.scrollEl.scrollHeight - this.scrollEl.clientHeight,
+        );
+
+        const clamped = Math.min(Math.max(0, centeredTarget), maxScroll);
+        this.scrollEl.scrollTo({ top: clamped, behavior });
     }
 
     /**
@@ -358,7 +414,7 @@ export class VirtualRecyclerView<
         }
 
         this.resizeObs?.disconnect();
-        this.created.forEach(el => el.remove());
+        this.created.forEach((el) => el.remove());
         this.created.clear();
     }
 
@@ -411,9 +467,24 @@ export class VirtualRecyclerView<
         if (count <= 0) return;
 
         this.suspend();
-        this.resetState();
+        this.pendingScrollToIndex = null;
+
+        // When visibility changes (search filter applied or cleared), heightCache may
+        // contain heights measured while only a subset of items was visible. Re-using
+        // these partial measurements in rebuildFenwick() causes incorrect prefix sums
+        // (e.g. items measured while scrolled into a filtered window have real heights,
+        // while surrounding items still use estimates — creating an uneven Fenwick).
+        //
+        // Safe fix: clear heightCache entirely on visibility change. The adaptive
+        // estimator will re-seed from probeInitialHeight() on the next render, and
+        // items will be re-measured as they scroll into view.
+        this.heightCache = [];
+        this.measuredSum = 0;
+        this.measuredCount = 0;
+        this.firstMeasured = false;
+
+        this.resetDOM();
         this.cleanupInvisibleItems();
-        this.recomputeMeasuredStats(count);
         this.rebuildFenwick(count);
         this.start = 0;
         this.end = -1;
@@ -433,7 +504,31 @@ export class VirtualRecyclerView<
     }
 
     /**
-     * Resets internal state: mounted elements, caches, Fenwick sums, padding, and estimator stats.
+     * Resets DOM nodes, Fenwick sums, padding, and estimator stats — but preserves {@link heightCache}.
+     *
+     * Use this inside {@link refreshItem} so that {@link recomputeMeasuredStats} can still
+     * read previously measured heights before the Fenwick tree is rebuilt.
+     *
+     * DOM side effects:
+     * - Removes all currently mounted item elements tracked in {@link created}.
+     * - Resets pad heights to `0px`.
+     *
+     * @returns {void}
+     */
+    private resetDOM(): void {
+        this.created.forEach((el) => el.remove());
+        this.created.clear();
+        this.fenwick.reset(0);
+        this.PadTop.style.height = "0px";
+        this.PadBottom.style.height = "0px";
+        this.firstMeasured = false;
+    }
+
+    /**
+     * Full reset: clears DOM nodes, Fenwick sums, padding, estimator stats, AND {@link heightCache}.
+     *
+     * Use this for complete teardown (e.g., adapter swap, destroy sequence) where all
+     * cached measurements should be discarded.
      *
      * DOM side effects:
      * - Removes all currently mounted item elements tracked in {@link created}.
@@ -442,7 +537,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 +652,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 +720,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 +835,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 +864,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 +901,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);
@@ -805,6 +914,16 @@ export class VirtualRecyclerView<
             if (this.opts.adaptiveEstimate) this.rebuildFenwick(count);
             this.scheduleUpdateWindow();
         }
+
+        // Corrective scroll: if ensureRendered() registered a target index, fire
+        // scrollToIndex() now that real heights are in Fenwick. Clear the target
+        // first to prevent infinite re-triggering (scrollToIndex may cause another
+        // measure cycle, but heights won't change so changed === false next time).
+        if (this.pendingScrollToIndex !== null) {
+            const target = this.pendingScrollToIndex;
+            this.pendingScrollToIndex = null;
+            this.scrollToIndex(target, "smooth");
+        }
     }
 
     /**
@@ -857,7 +976,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 +988,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 +1029,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 +1169,4 @@ export class VirtualRecyclerView<
     private totalHeight(count: number): number {
         return this.fenwick.sum(count);
     }
-}
+}

package/src/ts/core/model-manager.ts

@@ -50,17 +50,19 @@ import { Lifecycle } from "./base/lifecycle";
  */
 export class ModelManager<
     TModel extends MixedItem,
-    TAdapter extends Adapter<MixedItem, ViewContract<any>>
+    TAdapter extends Adapter<MixedItem, ViewContract<any>>,
 > extends Lifecycle {
     private privModelList: Array<MixedItem> = [];
 
     private privAdapter!: new (...args: any[]) => TAdapter;
 
-    private privAdapterHandle: TAdapter | null = null;
+    private privAdapterHandle?: TAdapter;
 
-    private privRecyclerView!: new (...args: any[]) => RecyclerViewContract<TAdapter>;
+    private privRecyclerView!: new (
+        ...args: any[]
+    ) => RecyclerViewContract<TAdapter>;
 
-    private privRecyclerViewHandle: RecyclerViewContract<TAdapter> | null = null;
+    private privRecyclerViewHandle?: RecyclerViewContract<TAdapter>;
 
     private options: SelectiveOptions = null;
 
@@ -97,7 +99,9 @@ export class ModelManager<
      * @param {new (...args: any[]) => RecyclerViewContract<TAdapter>} recyclerView - The recycler view constructor.
      * @returns {void}
      */
-    public setupRecyclerView(recyclerView: new (...args: any[]) => RecyclerViewContract<TAdapter>): void {
+    public setupRecyclerView(
+        recyclerView: new (...args: any[]) => RecyclerViewContract<TAdapter>,
+    ): void {
         this.privRecyclerView = recyclerView;
     }
 
@@ -113,7 +117,9 @@ export class ModelManager<
      * @param {Array<HTMLOptGroupElement | HTMLOptionElement>} modelData - Parsed DOM elements from the source `<select>`.
      * @returns {Array<GroupModel | OptionModel>} The ordered list of group and option models.
      */
-    public createModelResources(modelData: Array<HTMLOptGroupElement | HTMLOptionElement>): Array<GroupModel | OptionModel> {
+    public createModelResources(
+        modelData: Array<HTMLOptGroupElement | HTMLOptionElement>,
+    ): Array<GroupModel | OptionModel> {
         if (this.is(LifecycleState.INITIALIZED)) {
             this.mount();
         }
@@ -123,14 +129,26 @@ export class ModelManager<
 
         modelData.forEach((data) => {
             if (data.tagName === "OPTGROUP") {
-                currentGroup = new GroupModel(this.options, data as HTMLOptGroupElement);
+                currentGroup = new GroupModel(
+                    this.options,
+                    data as HTMLOptGroupElement,
+                );
                 this.privModelList.push(currentGroup);
             } else if (data.tagName === "OPTION") {
-                const optionModel = new OptionModel(this.options, data as HTMLOptionElement);
-
-                const parentGroup = data["__parentGroup"] as HTMLOptGroupElement | undefined;
-
-                if (parentGroup && currentGroup && parentGroup === currentGroup.targetElement) {
+                const optionModel = new OptionModel(
+                    this.options,
+                    data as HTMLOptionElement,
+                );
+
+                const parentGroup = data["__parentGroup"] as
+                    | HTMLOptGroupElement
+                    | undefined;
+
+                if (
+                    parentGroup &&
+                    currentGroup &&
+                    parentGroup === currentGroup.targetElement
+                ) {
                     currentGroup.addItem(optionModel);
                     optionModel.group = currentGroup;
                 } else {
@@ -155,7 +173,9 @@ export class ModelManager<
      * @returns {Promise<void>} Resolves when the adapter (if any) completes syncing.
      * @see Adapter#syncFromSource
      */
-    public async replace(modelData: Array<HTMLOptGroupElement | HTMLOptionElement>): Promise<void> {
+    public async replace(
+        modelData: Array<HTMLOptGroupElement | HTMLOptionElement>,
+    ): Promise<void> {
         this.createModelResources(modelData);
 
         if (this.privAdapterHandle) {
@@ -199,9 +219,9 @@ export class ModelManager<
     public load<TExtra extends object = {}>(
         viewElement: HTMLElement,
         adapterOpt: Partial<TAdapter> = {},
-        recyclerViewOpt: Partial<RecyclerViewContract<TAdapter>> & TExtra = {} as any
+        recyclerViewOpt: Partial<RecyclerViewContract<TAdapter>> &
+            TExtra = {} as any,
     ): void {
-
         this.privAdapterHandle = new this.privAdapter(this.privModelList);
         Object.assign(this.privAdapterHandle, adapterOpt);
 
@@ -230,7 +250,9 @@ export class ModelManager<
      * @returns {void}
      * @see Adapter#updateData
      */
-    public updateModel(modelData: Array<HTMLOptGroupElement | HTMLOptionElement>): void {
+    public updateModel(
+        modelData: Array<HTMLOptGroupElement | HTMLOptionElement>,
+    ): void {
         const oldModels = this.privModelList;
         const newModels: Array<MixedItem> = [];
 
@@ -256,9 +278,10 @@ export class ModelManager<
 
                 if (existingGroup) {
                     // Label is used as key; keep original behavior.
-                    const hasLabelChange = existingGroup.label !== dataVset.label;
+                    const hasLabelChange =
+                        existingGroup.label !== dataVset.label;
                     if (hasLabelChange) {
-                        existingGroup.updateTarget(dataVset)
+                        existingGroup.updateTarget(dataVset);
                     }
 
                     existingGroup.position = position;
@@ -283,7 +306,9 @@ export class ModelManager<
                     existingOption.updateTarget(dataVset);
                     existingOption.position = position;
 
-                    const parentGroup = dataVset["__parentGroup"] as HTMLOptGroupElement;
+                    const parentGroup = dataVset[
+                        "__parentGroup"
+                    ] as HTMLOptGroupElement;
 
                     if (parentGroup && currentGroup) {
                         currentGroup.addItem(existingOption);
@@ -298,7 +323,9 @@ export class ModelManager<
                     const newOption = new OptionModel(this.options, dataVset);
                     newOption.position = position;
 
-                    const parentGroup = dataVset["__parentGroup"] as HTMLOptGroupElement;
+                    const parentGroup = dataVset[
+                        "__parentGroup"
+                    ] as HTMLOptGroupElement;
 
                     if (parentGroup && currentGroup) {
                         currentGroup.addItem(newOption);
@@ -438,4 +465,4 @@ export class ModelManager<
     public triggerChanged(event_name: string): Promise<void> {
         return this.privAdapterHandle?.changeProp(event_name);
     }
-}
+}