@aiquants/virtualscroll 3.9.1 → 3.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "3.9.1",
+  "version": "3.9.2",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"

package/src/VirtualScroll.tsx

@@ -678,6 +678,24 @@ const edgeOfAlignment = (align: "top" | "bottom" | "center" | undefined): Aligne
     return align === "bottom" ? "end" : "start"
 }
 
+/**
+ * Returns the canonical form of an alignment to remember: `null` for one that can never change the edge the items
+ * wrapper keeps, the alignment itself otherwise. An alignment at pane position 0 or below holds only at positions within
+ * `EDGE_POSITION_TOLERANCE` of position 0, where `resolveItemsWrapperSnapEdge` answers `"start"` from the position
+ * alone, so it means the same as remembering nothing. Storing only the canonical form keeps one state for one meaning:
+ * a list the user scrolled back to the top and a list `scrollToIndex` aligned there hold the same state, so aligning it
+ * to the top again writes nothing.
+ *
+ * 覚える揃えの正規形を返す処理。行ラッパーが守る端を決して変えない揃えは `null`、それ以外は揃えそのもの。ペイン位置 0 以下の
+ * 揃えが成り立つのは位置 0 から `EDGE_POSITION_TOLERANCE` 以内の位置だけで、そこでは `resolveItemsWrapperSnapEdge` が位置
+ * だけから `"start"` を返すため、何も覚えないのと同じ意味。正規形だけを持つことで 1 つの意味に 1 つの状態となり、利用者が
+ * 先頭へ戻した一覧と `scrollToIndex` が先頭へ揃えた一覧が同じ状態を持ち、先頭へ揃え直しても何も書かない。
+ *
+ * @param alignment - The alignment, or `null` / 揃え (無ければ `null`)
+ * @returns The canonical alignment, or `null` / 正規形の揃え (無ければ `null`)
+ */
+const canonicalAlignedEdge = (alignment: AlignedEdge | null): AlignedEdge | null => (alignment !== null && alignment.panePosition <= 0 ? null : alignment)
+
 /**
  * Chooses the edge the items-wrapper translate keeps when it is snapped to the device-pixel grid
  * (`snapToDevicePixelGrid`), so that aligned content never loses part of its edge gutter to the snap:
@@ -1428,26 +1446,48 @@ const VirtualScrollInner = <T,>(
 
     const [scrollPosition, setScrollPosition] = useState(initialValues.position)
     const [contentSize, setContentSize] = useState<number>(initialValues.total)
-    // 初期位置の index とアンカーは上端揃えの scrollToIndex と同じ位置なので、その位置の上端揃えとして覚えておく。位置 0 から
-    // 始まる一覧も先頭の行の上端に揃っている (位置 0 の行ラッパーは覚えた揃えによらず上端で揃える) ため、同じく覚える。覚えずに
-    // 始めると、先頭へ戻すだけの最初の scrollToIndex (ホストが開いた直後の打鍵で先頭へ戻すなど) が状態を書き、確定を 1 回足す
-    const [alignedEdge, setAlignedEdge] = useState<AlignedEdge | null>(() => ((initialScrollAnchor && itemCount > 0) || typeof initialScrollIndex === "number" || initialValues.position <= EDGE_POSITION_TOLERANCE ? { edge: "start", panePosition: initialValues.position } : null))
+    // 初期位置の index とアンカーは上端揃えの scrollToIndex と同じ位置なので、その位置の上端揃えとして覚えておく。覚えずに
+    // 始めると、同じ行へ揃え直すだけの最初の scrollToIndex が状態を書き、確定を 1 回足す。位置 0 では正規形が null になる
+    const [alignedEdge, setAlignedEdge] = useState<AlignedEdge | null>(() => ((initialScrollAnchor && itemCount > 0) || typeof initialScrollIndex === "number" ? canonicalAlignedEdge({ edge: "start", panePosition: initialValues.position }) : null))
     // 状態の同期の写し。手動スクロールのたびに状態へ null を書くと、同じ値でも React が描画を予約し得るため、写しで要否を決める
     const alignedEdgeRef = useRef(alignedEdge)
+    // contentSize の同期の写し。確定の直後は同じ値の setState でも React が描画を 1 回予約するため、書くかどうかを写しで決める
+    const contentSizeRef = useRef(contentSize)
+
+    /**
+     * Writes the content size the pane and the scroll bar are sized by, and its synchronous copy, only when the value
+     * differs from the one last written (every writer of the content size goes through here, so the copy is the value the
+     * state settles on).
+     *
+     * ペインとスクロールバーの寸法の元になる中身の寸法と、その同期の写しへ、最後に書いた値と違うときだけ書く処理 (中身の寸法の
+     * 書き手はすべてここを通るため、写しは状態が落ち着く値)。
+     *
+     * @param next - The content size (px) / 中身の寸法 (px)
+     */
+    const writeContentSize = useCallback((next: number): void => {
+        if (contentSizeRef.current === next) {
+            return
+        }
+        contentSizeRef.current = next
+        setContentSize(next)
+    }, [])
 
     /**
-     * Remembers the alignment that holds at a pane position, or forgets it with `null`: writes the state the items wrapper
-     * snaps with and its synchronous copy, only when the edge or the pane position differs from the remembered one.
+     * Remembers the alignment that holds at a pane position, or forgets it with `null`: reduces it to its canonical form
+     * (`canonicalAlignedEdge`, so an alignment at position 0 is the same as none), then writes the state the items wrapper
+     * snaps with and its synchronous copy, only when the canonical form differs from the remembered one in edge or pane
+     * position.
      *
-     * あるペイン位置で成り立つ揃えを覚える処理 (`null` で忘れる)。行ラッパーが揃えに使う状態と、その同期の写しへ、覚えた揃えと
-     * 辺かペイン位置が違うときだけ書く。
+     * あるペイン位置で成り立つ揃えを覚える処理 (`null` で忘れる)。揃えを正規形にし (`canonicalAlignedEdge`。位置 0 の揃えは
+     * 揃え無しと同じ)、行ラッパーが揃えに使う状態と、その同期の写しへ、正規形が覚えた揃えと辺かペイン位置で違うときだけ書く。
      *
-     * @param next - The alignment, or `null` / 揃え (無ければ `null`)
+     * @param alignment - The alignment, or `null` / 揃え (無ければ `null`)
      */
-    const rememberAlignedEdge = useCallback((next: AlignedEdge | null): void => {
+    const rememberAlignedEdge = useCallback((alignment: AlignedEdge | null): void => {
         const current = alignedEdgeRef.current
+        const next = canonicalAlignedEdge(alignment)
         // 同じ揃えでも新しいオブジェクトを書けば React は描画を予約する。同じ位置への scrollToIndex (ホストが打鍵ごとに
-        // 先頭へ戻すなど) のたびに確定が 1 回増えるため、辺と位置が同じなら書かない
+        // 揃え直すなど) のたびに確定が 1 回増えるため、辺と位置が同じなら書かない
         if (current === next || (current !== null && next !== null && current.edge === next.edge && current.panePosition === next.panePosition)) {
             return
         }
@@ -1457,10 +1497,15 @@ const VirtualScrollInner = <T,>(
 
     /**
      * Moves the remembered alignment along with a position change that keeps the aligned row in place (layout-shift
-     * compensation): when the alignment held at `fromPanePosition`, it now holds at `toPanePosition`.
+     * compensation): when the alignment held at `fromPanePosition`, it now holds at `toPanePosition`. Only a remembered
+     * alignment moves: the top edge a list keeps at position 0 comes from the position (`resolveItemsWrapperSnapEdge`), not
+     * from the state (`canonicalAlignedEdge`), so a move away from position 0 carries no edge, and an alignment carried to
+     * position 0 or below is dropped.
      *
      * 揃えた行をその場に留める位置の変化 (レイアウトシフトの補正) に合わせて、覚えた揃えを動かす処理。揃えが
-     * `fromPanePosition` で成り立っていたなら、`toPanePosition` で成り立つ。
+     * `fromPanePosition` で成り立っていたなら、`toPanePosition` で成り立つ。動くのは覚えた揃えだけ。位置 0 の一覧が守る上端は
+     * 状態ではなく位置から決まる (`resolveItemsWrapperSnapEdge`・`canonicalAlignedEdge`) ため、位置 0 から離れる変化は端を
+     * 運ばず、位置 0 以下へ運んだ揃えは消える。
      *
      * @param fromPanePosition - Pane position before the change / 変化の前のペイン位置
      * @param toPanePosition - Pane position after the change / 変化の後のペイン位置
@@ -1861,7 +1906,7 @@ const VirtualScrollInner = <T,>(
 
         const totalHeight = fenwickTree.getTotal()
         if (contentSize !== totalHeight) {
-            setContentSize(totalHeight)
+            writeContentSize(totalHeight)
             return
         }
 
@@ -1933,7 +1978,7 @@ const VirtualScrollInner = <T,>(
             }
         }
         isResizingRef.current = false
-    }, [contentSize, fenwickTree, itemCount, resolvedInsets.top, applySelfAdjustment, rememberAlignedEdge, updateScrollPositionImmediate, viewportSize, resolvedInsets.bottom])
+    }, [contentSize, fenwickTree, itemCount, resolvedInsets.top, applySelfAdjustment, rememberAlignedEdge, updateScrollPositionImmediate, viewportSize, resolvedInsets.bottom, writeContentSize])
 
     useEffect(() => {
         // 目的: 上部インセットが動的に変更された場合、論理スクロール位置を維持したまま、ペインのスクロール位置を再計算してずらす。
@@ -1985,7 +2030,7 @@ const VirtualScrollInner = <T,>(
 
             const total = fenwickTree.update(safeIndex, size)
             if (total !== undefined) {
-                setContentSize(total)
+                writeContentSize(total)
             }
             Logger.debug("[VirtualScroll] Updated item size manually", { index: safeIndex, size, total })
 
@@ -2028,16 +2073,23 @@ const VirtualScrollInner = <T,>(
                 Logger.debug("[VirtualScroll] Adjusted scroll for layout shift (manual update)", { from: currentPanePosition, to: newPosition, causedByIndex: safeIndex, delta, activeVisibleStartIndex })
             }
         },
-        [fenwickTree, itemCount, applySelfAdjustment, carryAlignedEdge, issueCompensationScroll, updateScrollPositionImmediate, contentInsets],
+        [fenwickTree, itemCount, applySelfAdjustment, carryAlignedEdge, issueCompensationScroll, updateScrollPositionImmediate, contentInsets, writeContentSize],
     )
 
     /**
      * Scrolls to the requested logical index: lands the pane exactly on the aligned position (clamped to the content),
      * pins it as the pending alignment for drift correction, and remembers the alignment's edge at that position for
-     * the device-pixel snap of the items wrapper (`resolveItemsWrapperSnapEdge`).
+     * the device-pixel snap of the items wrapper (`resolveItemsWrapperSnapEdge`, in its canonical form). The content size
+     * and the scroll position are written only when they differ from their synchronous copies (`writeContentSize`; for the
+     * position, `latestScrollPositionRef` while the render loop is stopped, read before the pane moves), so a call that
+     * leaves the list where it is (the same row, alignment and content) writes no state, schedules no render and reports
+     * no position to `onScroll`, like `scrollTo` to the current position.
      *
      * 指定インデックスへのスクロールを実行する処理。ペインを揃えた位置 (中身の範囲へクランプ) へ厳密に着地させ、ドリフト補正の
-     * 保留中の揃えとして留め、行ラッパーの装置の画素への揃えのためにその位置で揃えの端を覚える (`resolveItemsWrapperSnapEdge`)。
+     * 保留中の揃えとして留め、行ラッパーの装置の画素への揃えのためにその位置で揃えの端を正規形で覚える
+     * (`resolveItemsWrapperSnapEdge`)。中身の寸法とスクロール位置は同期の写し (`writeContentSize`。位置は描画ループが止まって
+     * いる間の `latestScrollPositionRef` を、ペインを動かす前に読む) と違うときだけ書くため、一覧をその場に留める呼び出し (同じ行・揃え・中身) は状態を書かず、描画を予約せず、`onScroll` へ位置を
+     * 知らせない (現在位置への `scrollTo` と同じ)。
      *
      * @param index - Item index / アイテムのインデックス
      * @param options - Alignment (`"top"` by default) and offset / 揃え方 (既定は `"top"`) と offset
@@ -2099,6 +2151,10 @@ const VirtualScrollInner = <T,>(
             const edge = edgeOfAlignment(options?.align)
             rememberAlignedEdge(edge === null ? null : { edge, panePosition: clampedPaneOffset })
 
+            // ❗ 判定はペインを動かす前に行う。ペインの scrollTo はスクロールの処理を同期で呼び、位置の写しを着地位置へ進めて
+            // 描画ループを起こすが、状態はそのループの次のフレームまで古いまま。描画ループが止まっている間だけ、状態 (予約済みの
+            // 値を含む) が位置の写しと一致する
+            const stateHoldsLanding = !renderLoopRef.current.loopActive && latestScrollPositionRef.current === clampedPaneOffset
             const currentPanePosition = scrollPaneRef.current?.getScrollPosition() ?? -1
             // ❗ 揃えは厳密に着地させる。半ピクセル未満のずれを残すと、揃えた行の端の余白をそのずれが削り、行ラッパーを
             // 揃えた端の側へ丸めても取り戻せない (覚えた揃えもペインの位置と一致せず効かない)
@@ -2120,12 +2176,15 @@ const VirtualScrollInner = <T,>(
                 scrollPaneRef.current?.scrollTo(clampedPaneOffset)
             }
 
-            setContentSize(total)
-            updateScrollPositionImmediate(clampedPaneOffset, { immediate: true })
+            writeContentSize(total)
+            // 確定の直後は同じ値の setState でも React が描画を 1 回予約するため、状態が既に着地位置なら書かない
+            if (!stateHoldsLanding) {
+                updateScrollPositionImmediate(clampedPaneOffset, { immediate: true })
+            }
 
             Logger.debug("[VirtualScroll] Setting scroll position to:", clampedPaneOffset, { original: paneOffset, max: maxScrollPosition })
         },
-        [fenwickTree, overscanCount, itemCount, resolvedInsets.top, resolvedInsets.bottom, viewportSize, rememberAlignedEdge, updateScrollPositionImmediate],
+        [fenwickTree, overscanCount, itemCount, resolvedInsets.top, resolvedInsets.bottom, viewportSize, rememberAlignedEdge, updateScrollPositionImmediate, writeContentSize],
     )
 
     // アンカー付きマウントが itemCount 0 で始まった場合の遅延適用 (一度きり)。
@@ -2652,7 +2711,7 @@ const VirtualScrollInner = <T,>(
         // contentSize は memo 本体では直接使わないが「反応辺」として依存に含める:
         // fenwickTree は安定参照のため、非同期高さ更新 (updateItemSize / 高さ照合マイクロタスクの
         // fenwickTree.updates) で木の prefix 和が変わってもこの memo は自動では失効しない。
-        // 両経路とも setContentSize を伴うため、contentSize を依存へ含めることで
+        // 両経路とも中身の寸法の書き込み (writeContentSize) を伴うため、contentSize を依存へ含めることで
         // 行 top を最新の prefix 和で確実に再計算させる (報告座標と視覚描画の desync 防止)。
         void contentSize
 
@@ -2763,7 +2822,7 @@ const VirtualScrollInner = <T,>(
                 if (isUnmountedRef.current || typeof total !== "number") {
                     return
                 }
-                setContentSize(total)
+                writeContentSize(total)
                 Logger.debug("[VirtualScroll] Updated heights for items", toUpdateHeights, "New total height:", total)
                 const panePosition = scrollPaneRef.current?.getScrollPosition() ?? latestScrollPositionRef.current
 
@@ -2807,6 +2866,7 @@ const VirtualScrollInner = <T,>(
         resolvedLabels,
         updateScrollPositionImmediate,
         visibleStartIndex,
+        writeContentSize,
     ])
 
     /**