@aiquants/virtualscroll 1.20.0 → 1.22.0

package/src/useFenwickMapTree.ts

@@ -1006,6 +1006,11 @@ export class FenwickMapTree {
      * @method calculateAccumulatedError
      * @description Compares the cached total sum with a theoretical total calculated directly from the source values (`deltas` and `baseValue`, or `valueFn`). This helps detect any discrepancy in the tree's cached state, which might be caused by floating-point errors or other inconsistencies.
      * @description キャッシュされている合計値と、元の値 (`deltas` と `baseValue`、または `valueFn`) から直接計算した理論上の合計値とを比較します。これにより、浮動小数点数の累積誤差やその他の不整合によって生じる可能性のある、ツリーのキャッシュ状態の不一致を検出できます。
+     *
+     * ❗ 集計対象は `[0, size)` の範囲内にある delta だけです。`changeSize(0)` は
+     * ロード中の一時クリアとみなして delta を温存する (再伸長時にキャッシュを再利用するため) ので、
+     * 範囲外の delta まで数えると**木は健全なのに空リストの間ずっと非ゼロ**が返り、
+     * この値を破損検知に使う利用者が毎回不要な復旧処理を走らせてしまいます。
      * @returns {number} The difference between the cached total and the theoretical total.
      */
     calculateAccumulatedError(): number {
@@ -1014,10 +1019,12 @@ export class FenwickMapTree {
             return 0
         }
 
-        // 理論上の合計値を計算
+        // 理論上の合計値を計算する。範囲外へ退避している delta は木に載っていないので数えない
         let theoreticalTotal = this.baseValue * this.size
-        for (const delta of this.deltas.values()) {
-            theoreticalTotal += delta
+        for (const [index, delta] of this.deltas) {
+            if (index < this.size) {
+                theoreticalTotal += delta
+            }
         }
 
         // キャッシュされている合計値との差を返す
@@ -1038,6 +1045,18 @@ export class FenwickMapTree {
      * サイズ差分のみを受け取りインデックスの対応表は受け取らないため、要素は末尾に追加/末尾から削除
      * されると仮定する。既存行は index↔高さ の対応を保つ。したがって中間挿入/削除は表現できず、その
      * ような構造変更の後は index↔高さ の対応が保存されず、木の delta が誤った行へ適用されてしまう。
+     * ❗ `changeSize(0)` は例外的に delta を消去しない。ロード中に一覧が一瞬空になるフローで
+     * 実測済みの行高を捨てないための特例で、`changeSize(N > 0)` で再伸長したときに範囲内の delta が
+     * そのまま復元される (範囲外の delta はそこで刈られる)。size が 0 に留まっている間、
+     * `get()` / `getTotal()` は 0 を返し、`calculateAccumulatedError()` は範囲内 delta だけを
+     * 集計するので 0 のままになる。**別データセットへ差し替える場合は温存が害になる**ため、
+     * `reset()` を呼ぶか新しい `key` で作り直すこと。
+     * ❗ `changeSize(0)` intentionally keeps its deltas so a list that briefly empties while loading
+     * does not lose measured row heights; growing back restores the in-range ones (out-of-range
+     * deltas are pruned then). While the size stays 0, `get()` / `getTotal()` return 0 and
+     * `calculateAccumulatedError()` stays 0 because it only sums in-range deltas. Replacing the
+     * dataset instead of reloading the same one must go through `reset()` or a fresh instance.
+     *
      * 中間で要素を挿入/削除する消費側は、代わりに木をリセットするか (`useFenwickMapTree` の
      * `resetOnValueFnChange`。VirtualScroll では `resetOnGetItemHeightChange` として公開) 、新しい
      * `key` でコンポーネントを再マウントすること。
@@ -1062,16 +1081,40 @@ export class FenwickMapTree {
         }
 
         if (targetSize > oldSize) {
-            // 末尾への伸長は増分更新で済ませる (全再構築 O(D log n) を回避)。
-            // 既存ノード (treeIndex <= oldSize) は不変であり、新規要素は delta 0 なので、
-            // oldSize で伝播が止まっていた既存 delta を新たに有効化されたノード
-            // (oldSize, targetSize] にのみ伝播すればよい。
-            this._growSize(oldSize, targetSize)
+            // ❗ oldSize === 0 からの伸長は増分では表現できない。
+            // `_minCoveredLowBound(0, N)` は 0 を返すため `candidateCount = 0 - 0 = 0` となり、
+            // 候補ループが 1 度も回らず**温存した delta が木へ 1 件も伝播しない**。
+            // その結果 `get()` は delta 込み・`prefixSum()` / `getTotal()` は base のみ、という
+            // 恒久的な乖離が生じ (末尾の整合検査は木由来の 2 値を比べるだけなので検知しない)、
+            // 行の描画高さとスクロール位置の解決が食い違う。木が空なら全再構築で作り直す。
+            if (oldSize === 0 && this.deltas.size > 0) {
+                // 一時クリアで温存した delta のうち、新しいサイズの範囲外にあるものは捨てる。
+                // 残すと、後でさらに伸長したときに**別データの行高**として復活してしまう。
+                // 「伸長後は deltas ⊆ [0, size)」を不変条件として維持する
+                // (`size` に留まったままの範囲外 delta は `calculateAccumulatedError` が集計対象外にする)。
+                for (const index of this.deltas.keys()) {
+                    if (index >= targetSize) {
+                        this.deltas.delete(index)
+                    }
+                }
+                this.size = targetSize
+                this.rebuildTree()
+            } else {
+                // 末尾への伸長は増分更新で済ませる (全再構築 O(D log n) を回避)。
+                // 既存ノード (treeIndex <= oldSize) は不変であり、新規要素は delta 0 なので、
+                // oldSize で伝播が止まっていた既存 delta を新たに有効化されたノード
+                // (oldSize, targetSize] にのみ伝播すればよい。
+                this._growSize(oldSize, targetSize)
+            }
         } else {
-            // サイズが小さくなる場合、範囲外の delta を削除してからツリーを再構築する
-            for (const index of this.deltas.keys()) {
-                if (index >= targetSize) {
-                    this.deltas.delete(index)
+            // サイズが小さくなる場合、範囲外の delta を削除してからツリーを再構築する。
+            // ただし targetSize が 0 の場合は、ロード中の空配列への一時的クリアとみなし、
+            // キャッシュ温存のため deltas を消去せずに残す。
+            if (targetSize > 0) {
+                for (const index of this.deltas.keys()) {
+                    if (index >= targetSize) {
+                        this.deltas.delete(index)
+                    }
                 }
             }
             this.size = targetSize
@@ -1199,6 +1242,35 @@ export class FenwickMapTree {
         return this.size
     }
 
+    /**
+     * @description Gets the base value of the tree — the height every row starts from before
+     * its own delta is applied. `useFenwickMapTree` reads it to decide whether a `0 → N` growth
+     * should re-sample from scratch (`reset`) or reuse the measured heights kept across the
+     * empty state (`changeSize`), so removing or renaming it silently disables that cache
+     * preservation.
+     *
+     * ❗ This is NOT a "has the tree warmed up?" flag. `0` is a legitimate base — it is what a
+     * tree constructed with `new FenwickMapTree(n, 0)` has, and what sampling produces when the
+     * value function returns 0 for not-yet-measured rows (a common virtualization pattern).
+     * Such a tree can hold plenty of measured deltas while `base` stays `0`. The hook's
+     * `0 → N` guard therefore trades cache preservation for correctness in exactly that case:
+     * a base of `0` cannot be distinguished from "never established", and growing incrementally
+     * from a zero base would pin `total` at `0 × N = 0`.
+     * @description ツリーの基準値 (各行が自身の delta を適用される前の高さ) を取得。
+     * `useFenwickMapTree` は `0 → N` の伸長を再サンプリング (`reset`) と実測高さの温存 (`changeSize`) の
+     * どちらへ倒すかの判定にこの値を読むため、削除・改名するとキャッシュ温存が黙って無効化される。
+     *
+     * ❗ **「木が温まったか」のフラグではない。** `0` は正当な基準値であり、
+     * `new FenwickMapTree(n, 0)` や「未計測行に 0 を返す `getItemHeight`」(仮想化では定番) の
+     * サンプリング結果として普通に発生する。その木は実測 delta を大量に持っていても `base` は `0` のまま。
+     * フックの `0 → N` ガードは、まさにこの場合にキャッシュ温存より整合を優先する
+     * (基準値 0 は「未確立」と区別できず、0 のまま増分伸長すると `total = 0 × N = 0` で固着するため)。
+     * @returns {number} The base value. 基準値。
+     */
+    get base(): number {
+        return this.baseValue
+    }
+
     /**
      * @method findIndexAtOrAfter
      * @description Finds the first index where the cumulative sum is greater than or equal to a target value.
@@ -1316,7 +1388,17 @@ export const useFenwickMapTree = (size: number, valueOrFn: number | ((index: num
     // 旧 size が 0 の木は baseValue が未確立 (0) のまま。増分伸長 (changeSize) では
     // total = 0 * N = 0 で固着するため、0 -> N の伸長は resetOnValueFnChange の設定に
     // 関わらず常に reset (サンプリング込み) へ倒す。sizeChanged のみの分岐と前提を統一する。
-    const growingFromZero = prev.size === 0 && validSize > 0
+    // ただし、以前に baseValue が確立されている（base > 0）かつ deltas が維持されている場合は、
+    // reset を回避して changeSize (増分伸長) に倒し、蓄積された高さキャッシュを再利用する。
+    //
+    // ❗ **温存は「同じデータが読み込み中に一瞬 0 件になった」場合を想定している。**
+    // N -> 0 -> M が**別データセットへの差し替え**だった場合、baseValue も実測 delta も
+    // 旧データのものが引き継がれる (描画ウィンドウ内の行は次レンダーの高さ照合で
+    // getItemHeight へ巻き戻るが、ウィンドウ外の行は巻き戻らないため総高さ・つまみ長・
+    // scrollToIndex の着地点が食い違う)。行高が可変で、かつ 0 件を経由して中身が入れ替わる
+    // 消費側は `resetOnValueFnChange` (VirtualScroll では `resetOnGetItemHeightChange`) を
+    // 有効にするか、新しい `key` で再マウントすること。
+    const growingFromZero = prev.size === 0 && validSize > 0 && (!treeRef.current || treeRef.current.base === 0)
 
     if (valueOrFnChanged || optionsChanged) {
         const resetRequested = options?.resetOnValueFnChange ?? true