@aiquants/virtualscroll 3.11.0 → 3.11.1

package/src/VirtualScroll.tsx

@@ -1,9 +1,9 @@
-import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react"
+import React, { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from "react"
 import { type DevicePixelSnapEdge, snapToDevicePixelGrid, usePaintingDevicePixelRatio } from "./devicePixelGrid.ts"
 import { resolveVirtualScrollLabels, type VirtualScrollLabelOverrides, type VirtualScrollLocale } from "./labels.ts"
 import { Logger } from "./logger.ts"
 import { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneProps } from "./ScrollPane.tsx"
-import { useFenwickMapTree } from "./useFenwickMapTree.ts"
+import { FENWICK_LOOKUP_ONLY, useFenwickMapTree, useFenwickTreeRevision } from "./useFenwickMapTree.ts"
 import { getAxisScale, keepFocusOnPress, minmax } from "./utils.ts"
 
 /**
@@ -906,17 +906,6 @@ const ItemsWrapper = ({ translateY, snapEdge, children, boundaryRef }: ItemsWrap
  */
 const DEFAULT_HORIZONTAL_KEY_STEP = 40
 
-/**
- * Advances VirtualScroll's tree revision by one (the reducer of the revision that the memos reading the row-height tree
- * depend on).
- *
- * VirtualScroll の木の版数を 1 つ進める処理 (行の高さの木を読む memo が依存する版数の reducer)。
- *
- * @param revision - The current revision / 今の版数
- * @returns The next revision / 次の版数
- */
-const nextTreeRevision = (revision: number): number => revision + 1
-
 /**
  * Converts a numeric size into a non-negative bigint for large collection handling.
  *
@@ -947,9 +936,6 @@ export type VisibleStartRow = {
  */
 type VisibleStartRowTree = Pick<ReturnType<typeof useFenwickMapTree>, "findIndexAtOrAfter" | "prefixSum">
 
-/** Tree reads that only look the rows up, never materialising them / 行を引くだけで具現化しない木の読み方 */
-const LOOKUP_ONLY = { materializeOption: { materialize: false } } as const
-
 /**
  * Resolves the first visible row at a logical scroll position by the visible-start boundary rule — the one rule that
  * `scrollTo` pins, `getScrollAnchor` reports, `updateItemSize` compensates above and `computeRenderingRanges` renders from
@@ -981,9 +967,9 @@ const LOOKUP_ONLY = { materializeOption: { materialize: false } } as const
  */
 export const resolveVisibleStartRow = (fenwickTree: VisibleStartRowTree, position: number, itemCount: number): VisibleStartRow => {
     const lastIndex = itemCount - 1
-    const found = fenwickTree.findIndexAtOrAfter(position, LOOKUP_ONLY)
+    const found = fenwickTree.findIndexAtOrAfter(position, FENWICK_LOOKUP_ONLY)
     if (found.index === -1 || found.index > lastIndex || found.cumulative === undefined || found.currentValue === undefined) {
-        const last = fenwickTree.prefixSum(lastIndex, LOOKUP_ONLY)
+        const last = fenwickTree.prefixSum(lastIndex, FENWICK_LOOKUP_ONLY)
         return { index: lastIndex, top: last.cumulative - last.currentValue }
     }
     if (found.cumulative === position && found.index < lastIndex) {
@@ -1059,11 +1045,11 @@ export const computeRenderingRangesHuge = (effectiveScrollPosition: number, view
             // number へ安全に変換できない領域では木のクエリが不正確になるため打ち切る
             return null
         }
-        const { cumulative: runBottom } = fenwickTree.prefixSum(lastNumber, LOOKUP_ONLY)
+        const { cumulative: runBottom } = fenwickTree.prefixSum(lastNumber, FENWICK_LOOKUP_ONLY)
         if (!Number.isFinite(runBottom)) {
             return null
         }
-        const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom + 0.5, LOOKUP_ONLY)
+        const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom + 0.5, FENWICK_LOOKUP_ONLY)
         if (jumpIndex === -1) {
             return null
         }
@@ -1138,11 +1124,11 @@ export const computeRenderingRangesHuge = (effectiveScrollPosition: number, view
                     if (!Number.isSafeInteger(indexNumber)) {
                         break
                     }
-                    const { cumulative: runBottom } = fenwickTree.prefixSum(indexNumber, LOOKUP_ONLY)
+                    const { cumulative: runBottom } = fenwickTree.prefixSum(indexNumber, FENWICK_LOOKUP_ONLY)
                     if (!Number.isFinite(runBottom)) {
                         break
                     }
-                    const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom - 0.5, LOOKUP_ONLY)
+                    const { index: jumpIndex } = fenwickTree.findIndexAtOrAfter(runBottom - 0.5, FENWICK_LOOKUP_ONLY)
                     const jumpBig = jumpIndex === -1 ? -1n : toSafeBigInt(jumpIndex)
                     if (jumpBig >= 0n && jumpBig < backwardStart) {
                         // 0 行の連続を飛び越えて直前の非 0 行から走査を続行する
@@ -1219,8 +1205,8 @@ export const computeRenderingRanges = (scrollPosition: number, viewportSize: num
             if (currentHeight === 0) {
                 zeroRun++
                 if (zeroRun > ZERO_HEIGHT_RUN_LIMIT) {
-                    const { cumulative: runBottom } = fenwickTree.prefixSum(forwardCursor - 1, { materializeOption: { materialize: false } })
-                    const { index: jumpIndex } = Number.isFinite(runBottom) ? fenwickTree.findIndexAtOrAfter(runBottom + 0.5, { materializeOption: { materialize: false } }) : { index: -1 }
+                    const { cumulative: runBottom } = fenwickTree.prefixSum(forwardCursor - 1, FENWICK_LOOKUP_ONLY)
+                    const { index: jumpIndex } = Number.isFinite(runBottom) ? fenwickTree.findIndexAtOrAfter(runBottom + 0.5, FENWICK_LOOKUP_ONLY) : { index: -1 }
                     if (jumpIndex > forwardCursor) {
                         // 0 行の連続を飛び越えて次の非 0 行から走査を続行する
                         forwardCursor = jumpIndex
@@ -1259,8 +1245,8 @@ export const computeRenderingRanges = (scrollPosition: number, viewportSize: num
                 backwardZeroRun++
                 if (backwardZeroRun > ZERO_HEIGHT_RUN_LIMIT) {
                     // 連続 0 行の直前にある非 0 行へ後方ジャンプ (木上の累積位置 -0.5 で探索)
-                    const { cumulative: runBottom } = fenwickTree.prefixSum(backwardCursor, { materializeOption: { materialize: false } })
-                    const { index: jumpIndex } = Number.isFinite(runBottom) ? fenwickTree.findIndexAtOrAfter(runBottom - 0.5, { materializeOption: { materialize: false } }) : { index: -1 }
+                    const { cumulative: runBottom } = fenwickTree.prefixSum(backwardCursor, FENWICK_LOOKUP_ONLY)
+                    const { index: jumpIndex } = Number.isFinite(runBottom) ? fenwickTree.findIndexAtOrAfter(runBottom - 0.5, FENWICK_LOOKUP_ONLY) : { index: -1 }
                     if (jumpIndex !== -1 && jumpIndex < backwardCursor) {
                         // 0 行の連続を飛び越えて直前の非 0 行から走査を続行する
                         backwardCursor = jumpIndex
@@ -1572,34 +1558,10 @@ const VirtualScrollInner = <T,>(
     const fenwickTree = useFenwickMapTree(itemCount, getItemHeight, fenwickTreeOptions)
 
     // ❗ 木は同一性を保ったまま描画の外で書き換わる (updateItemSize・高さの照合・scrollToIndex の具現化)。接頭辞和の変化は総和が
-    // 変わらなくても (差の和が 0 の測り直しの組) 描いた行の上端と高さ、描画範囲を変えるので、木を読むどの memo もこの版数に
-    // 依存させる。総和 (中身の寸法) は相殺で変わらず、同じ値の書き込みは React が捨てるため、変化の合図にならない
-    const [treeRevision, advanceTreeRevision] = useReducer(nextTreeRevision, 0)
-
-    /**
-     * Runs one change of the row-height tree made outside render (`updateItemSize`, the height reconciliation, the
-     * materialisation of `scrollToIndex`) and, when the tree's revision moved (`FenwickMapTree.revision`), advances the tree
-     * revision, so the next commit re-places the rendered rows and re-resolves the rendering range whether or not the total
-     * changed.
-     *
-     * 描画の外で行う行の高さの木の変更を 1 回実行し (`updateItemSize`・高さの照合・`scrollToIndex` の具現化)、木の版
-     * (`FenwickMapTree.revision`) が動いたら木の版数を進める処理。総和が変わったかどうかによらず、次の確定が描いた行を置き直し、
-     * 描画範囲を解決し直す。
-     *
-     * @param change - The change of the tree / 木の変更
-     * @returns What `change` returned / `change` の戻り値
-     */
-    const changeTree = useCallback(
-        <Result,>(change: () => Result): Result => {
-            const revisionBefore = fenwickTree.revision
-            const result = change()
-            if (fenwickTree.revision !== revisionBefore) {
-                advanceTreeRevision()
-            }
-            return result
-        },
-        [fenwickTree],
-    )
+    // 変わらなくても (差の和が 0 の測り直しの組) 描いた行の上端と高さ、描画範囲を変えるので、描画の外の変更はどれも changeTree を
+    // 通し、木を読むどの memo も treeRevision に依存させる。総和 (中身の寸法) は相殺で変わらず、同じ値の書き込みは React が捨てるため、
+    // 変化の合図にならない
+    const { revision: treeRevision, change: changeTree } = useFenwickTreeRevision(fenwickTree)
 
     const [initialValues] = useState(() => {
         let position = 0
@@ -2163,7 +2125,7 @@ const VirtualScrollInner = <T,>(
         if (pendingVisibleStartIndexRef.current !== null) {
             const { index, align, offset } = pendingVisibleStartIndexRef.current
             const safeIndex = sanitizeIndex(index, itemCount)
-            const { cumulative: itemBottom, currentValue: itemHeight } = fenwickTree.prefixSum(safeIndex, { materializeOption: { materialize: false } })
+            const { cumulative: itemBottom, currentValue: itemHeight } = fenwickTree.prefixSum(safeIndex, FENWICK_LOOKUP_ONLY)
 
             if (itemBottom !== undefined && itemHeight !== undefined) {
                 const itemTop = Math.max(itemBottom - itemHeight, 0)
@@ -2349,7 +2311,7 @@ const VirtualScrollInner = <T,>(
                     throw new RangeError(`[VirtualScroll] scrollToIndex: align "nearest" takes no offset (it lands the row at the edge of the band a visible scroll-to-edge pill leaves); received an offset of type ${typeof offset}.`)
                 }
                 // 見せるかどうかは今の木で決める。描画の窓とその周りの行は照合で実際の高さを持ち、窓から遠い行は表示域の中にない
-                const row = fenwickTree.prefixSum(safeIndex, LOOKUP_ONLY)
+                const row = fenwickTree.prefixSum(safeIndex, FENWICK_LOOKUP_ONLY)
                 const reveal = resolveRevealAlignment({ top: row.cumulative - row.currentValue, bottom: row.cumulative }, toLogicalPositionWithInset(latestScrollPositionRef.current, resolvedInsets.top), viewportSize, readObscuredInsets())
                 if (reveal === null) {
                     return
@@ -2978,7 +2940,7 @@ const VirtualScrollInner = <T,>(
 
         const safeRenderingStartIndex = sanitizeIndex(renderingStartIndex, itemCount)
         const safeRenderingEndIndex = sanitizeIndex(renderingEndIndex, itemCount)
-        const { cumulative, currentValue: oldHeight } = fenwickTree.prefixSum(safeRenderingStartIndex, { materializeOption: { materialize: false } })
+        const { cumulative, currentValue: oldHeight } = fenwickTree.prefixSum(safeRenderingStartIndex, FENWICK_LOOKUP_ONLY)
         const startPosition = cumulative - oldHeight
 
         // 量子化アンカーの再基準化: 描画ウィンドウ先頭が現アンカーから一定距離を超えて離れたときだけ

package/src/useFenwickMapTree.ts

@@ -11,7 +11,7 @@
  * それを管理するための React フック `useFenwickMapTree` の提供。
  * 動的なアイテムサイズを持つ仮想スクロールのシナリオに最適化されている。
  */
-import { useRef } from "react"
+import { useCallback, useReducer, useRef } from "react"
 import { Logger } from "./logger.ts"
 import { minmax } from "./utils.ts"
 
@@ -32,6 +32,17 @@ type MaterializeConfig = { materializeOption?: MaterializeOption }
 type DeltaUpdate = { index: number; change: number }
 type ValueUpdate = { index: number; value: number }
 
+/**
+ * The options of a tree read that only looks rows up and never materialises them (`prefixSum`, `get`, `getTotal`,
+ * `findIndexAtOrAfter`, `findIndexAtOrBefore`): the read leaves the stored values, the size and `revision` as they are. One
+ * frozen value that every lookup passes, so no caller spells the option out. Internal to the package (not in the barrel).
+ *
+ * 行を引くだけで具現化しない木の読み取り (`prefixSum`・`get`・`getTotal`・`findIndexAtOrAfter`・`findIndexAtOrBefore`) の選択肢。
+ * 読み取りは保持する値・要素数・`revision` をそのまま残す。どの引き当ても渡す凍結した 1 つの値で、呼び出し側は選択肢を書き下さない。
+ * パッケージの内部用 (バレル非公開)。
+ */
+export const FENWICK_LOOKUP_ONLY = Object.freeze({ materializeOption: Object.freeze({ materialize: false }) })
+
 /**
  * Validates that `valueFn` returned a finite number, throwing otherwise. A single NaN/Infinity
  * propagated into the tree poisons `tree`/`total` irrecoverably, so the materialization and
@@ -1432,3 +1443,73 @@ export const useFenwickMapTree = (size: number, valueOrFn: number | ((index: num
 
     return tree
 }
+
+/**
+ * What `useFenwickTreeRevision` returns: the revision the memos that read one tree depend on, and the one way to change that
+ * tree outside render so that they see the change.
+ *
+ * `useFenwickTreeRevision` の戻り値。1 本の木を読む memo が依存する版数と、memo が変化に気付くように描画の外でその木を変える
+ * ただ 1 つの方法。
+ */
+export type FenwickTreeRevision = {
+    /** Advances by one per change made through `change` that moved the tree's revision / `change` を通した変更が木の版を動かすたびに 1 つ進む数 */
+    readonly revision: number
+    /** Runs one change of the tree made outside render and returns its result; advances `revision` only when the tree's revision moved / 描画の外で行う木の変更を 1 回実行してその結果を返し、木の版が動いたときだけ `revision` を進める処理 */
+    readonly change: <Result>(mutate: () => Result) => Result
+}
+
+/**
+ * Advances a component's tree revision by one (the reducer behind `FenwickTreeRevision["revision"]`).
+ *
+ * コンポーネントの木の版数を 1 つ進める処理 (`FenwickTreeRevision["revision"]` の reducer)。
+ *
+ * @param revision - The current revision / 今の版数
+ * @returns The next revision / 次の版数
+ */
+const nextTreeRevision = (revision: number): number => revision + 1
+
+/**
+ * Ties the memos of a component to the contents of a Fenwick tree. The tree keeps its identity while its contents change
+ * (`useFenwickMapTree`), so a memo that derives anything from its prefix sums (row tops, a rendering range, the placed
+ * columns) cannot see a change through the tree itself, and the total is no signal either: a batch of changes that cancel out
+ * leaves it as it was. Every change made outside render goes through `change`, which advances `revision` exactly when the
+ * tree's own revision (`FenwickMapTree.revision`) moved, so the next commit recomputes the memos that depend on `revision`,
+ * and a change that stores the same values (an update to the value a row already has, a materialisation that finds the stored
+ * value) adds no commit. Changes made during render (a reset or a resize by `useFenwickMapTree`) come with new props, which the
+ * memos depend on already. Internal to the package (not in the barrel).
+ *
+ * コンポーネントの memo を Fenwick 木の中身に結び付けるフック。木は中身が変わっても同一性を保つ (`useFenwickMapTree`) ので、
+ * 接頭辞和から何か (行の上端・描画範囲・配置した列) を導く memo は木そのものからは変化に気付けず、総和も合図にならない (打ち消し合う
+ * 変更の組は総和を変えない)。描画の外の変更はすべて `change` を通し、`change` は木自身の版 (`FenwickMapTree.revision`) が動いたとき
+ * ちょうどに `revision` を進める。だから次の確定は `revision` に依存する memo を計算し直し、同じ値を保つ変更 (行が既に持つ値への更新・
+ * 保持する値と同じ値を見つけた具現化) は確定を足さない。描画中の変更 (`useFenwickMapTree` のリセットと大きさの変更) は新しい props と
+ * 一緒に来るので、memo は既にそれに依存している。パッケージの内部用 (バレル非公開)。
+ *
+ * @param tree - The tree whose changes the memos must see / memo が変化に気付くべき木
+ * @returns The revision and the change runner / 版数と変更の実行関数
+ */
+export const useFenwickTreeRevision = (tree: FenwickMapTree): FenwickTreeRevision => {
+    const [revision, advanceRevision] = useReducer(nextTreeRevision, 0)
+
+    /**
+     * Runs one change of the tree and advances the revision when the tree's revision moved.
+     *
+     * 木の変更を 1 回実行し、木の版が動いたら版数を進める処理。
+     *
+     * @param mutate - The change of the tree / 木の変更
+     * @returns What `mutate` returned / `mutate` の戻り値
+     */
+    const change = useCallback(
+        <Result>(mutate: () => Result): Result => {
+            const revisionBefore = tree.revision
+            const result = mutate()
+            if (tree.revision !== revisionBefore) {
+                advanceRevision()
+            }
+            return result
+        },
+        [tree],
+    )
+
+    return { revision, change }
+}

package/src/useLruCache.ts

@@ -91,10 +91,10 @@ class DoublyLinkedList<K, V> {
     }
 
     /**
-     * @method peekHead
-     * @description Returns the head of the list (the least recently used item) without removing it.
-     * @description リストの先頭 (最も最近使用されていないアイテム) を外さずに返します。
-     * @returns {DoublyLinkedListNode<K, V> | null} The head node, or null if the list is empty.
+     * Returns the head of the list (the least recently used item) without removing it.
+     * リストの先頭 (最も最近使用されていないアイテム) を外さずに返す処理。
+     *
+     * @returns {DoublyLinkedListNode<K, V> | null} The head node, or null if the list is empty / 先頭のノード (空なら null)
      */
     peekHead(): DoublyLinkedListNode<K, V> | null {
         return this.head