@aiquants/virtualscroll 3.11.1 → 3.11.3

package/dist/residualQuantizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"residualQuantizer.d.ts","sourceRoot":"","sources":["../src/residualQuantizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACnC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAC/B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,MAAM,CAAA;IACzB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,wBAAwB,KAAG,iBAmC3E,CAAA"}
+{"version":3,"file":"residualQuantizer.d.ts","sourceRoot":"","sources":["../src/residualQuantizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACnC,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B;;;;;;;;;;;;;OAaG;IACH,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAC/B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,MAAM,CAAA;IACzB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,wBAAwB,KAAG,iBAiD3E,CAAA"}

package/dist/useGridTapScroll.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useGridTapScroll.d.ts","sourceRoot":"","sources":["../src/useGridTapScroll.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAA4B,KAAK,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAEvG,OAAO,KAAK,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAG5F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAA;AAalD,4MAA4M;AAC5M,MAAM,MAAM,sBAAsB,GAAG;IACjC,uIAAuI;IACvI,OAAO,EAAE,OAAO,CAAA;IAChB,mGAAmG;IACnG,WAAW,EAAE,MAAM,CAAA;IACnB,gIAAgI;IAChI,YAAY,EAAE,wBAAwB,CAAA;IACtC,6IAA6I;IAC7I,YAAY,EAAE,wBAAwB,CAAA;IACtC,sHAAsH;IACtH,UAAU,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;KAAE,CAAA;IAC1D,gDAAgD;IAChD,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,mJAAmJ;IACnJ,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,oVAAoV;IACpV,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC,8YAA8Y;IAC9Y,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,2HAA2H;IAC3H,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,mLAAmL;IACnL,mBAAmB,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IACzC,qKAAqK;IACrK,gBAAgB,EAAE,OAAO,CAAA;IACzB,4JAA4J;IAC5J,gBAAgB,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG;IACjC,4FAA4F;IAC5F,WAAW,EAAE,OAAO,CAAA;IACpB,qGAAqG;IACrG,yBAAyB,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACpE,4HAA4H;IAC5H,kBAAkB,EAAE,KAAK,CAAC,SAAS,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAA;CACpE,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,sBAAsB,KAAG,sBAuQjE,CAAA"}
+{"version":3,"file":"useGridTapScroll.d.ts","sourceRoot":"","sources":["../src/useGridTapScroll.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAA4B,KAAK,wBAAwB,EAAE,MAAM,+BAA+B,CAAA;AAEvG,OAAO,KAAK,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAG5F;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAA;AAalD,4MAA4M;AAC5M,MAAM,MAAM,sBAAsB,GAAG;IACjC,uIAAuI;IACvI,OAAO,EAAE,OAAO,CAAA;IAChB,mGAAmG;IACnG,WAAW,EAAE,MAAM,CAAA;IACnB,gIAAgI;IAChI,YAAY,EAAE,wBAAwB,CAAA;IACtC,6IAA6I;IAC7I,YAAY,EAAE,wBAAwB,CAAA;IACtC,sHAAsH;IACtH,UAAU,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;KAAE,CAAA;IAC1D,gDAAgD;IAChD,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,mJAAmJ;IACnJ,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,oVAAoV;IACpV,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC,8YAA8Y;IAC9Y,KAAK,EAAE,MAAM,MAAM,CAAA;IACnB,2HAA2H;IAC3H,QAAQ,EAAE,MAAM,MAAM,CAAA;IACtB,mLAAmL;IACnL,mBAAmB,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;IACzC,qKAAqK;IACrK,gBAAgB,EAAE,OAAO,CAAA;IACzB,4JAA4J;IAC5J,gBAAgB,EAAE,OAAO,CAAA;CAC5B,CAAA;AAED,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG;IACjC,4FAA4F;IAC5F,WAAW,EAAE,OAAO,CAAA;IACpB,qGAAqG;IACrG,yBAAyB,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IACpE,4HAA4H;IAC5H,kBAAkB,EAAE,KAAK,CAAC,SAAS,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAA;CACpE,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,sBAAsB,KAAG,sBAiSjE,CAAA"}

package/dist/useWheelBridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useWheelBridge.d.ts","sourceRoot":"","sources":["../src/useWheelBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAwC,MAAM,OAAO,CAAA;AAE9F;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;CAC7C,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,EAAE,UAAU,kBAAkB,KAAG,WAAW,CAAC,WAAW,CA+DjI,CAAA"}
+{"version":3,"file":"useWheelBridge.d.ts","sourceRoot":"","sources":["../src/useWheelBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAwC,MAAM,OAAO,CAAA;AAE9F;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC5B,UAAU,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAA;CAC7C,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,EAAE,UAAU,kBAAkB,KAAG,WAAW,CAAC,WAAW,CA6EjI,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "3.11.1",
+  "version": "3.11.3",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"
@@ -29,6 +29,7 @@
     "src",
     "!src/**/*.spec.ts",
     "!src/**/*.spec.tsx",
+    "!src/test-helpers/**",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -103,6 +104,8 @@
     "check:coverage": "node scripts/ratchet-coverage.mjs",
     "coverage:ratchet": "node scripts/ratchet-coverage.mjs --write",
     "coverage:adopt": "node scripts/ratchet-coverage.mjs --adopt",
+    "check:docstrings": "node scripts/ratchet-docstrings.mjs",
+    "docstrings:ratchet": "node scripts/ratchet-docstrings.mjs --write",
     "lint": "biome check src tests",
     "lint:fix": "biome check --write src tests",
     "format": "biome format --write src tests",

package/src/ScrollBar.tsx

@@ -379,7 +379,15 @@ const createOrientationConfig = (horizontal: boolean): OrientationConfig => {
             mainSizeKey: "width",
             crossSizeKey: "height",
             thumbTranslateFunction: "translateX",
+            /**
+             * Picks the component of a pointer drag along the horizontal bar.
+             * ポインタのドラッグの、横のバーに沿う成分を選ぶ処理。
+             */
             selectDelta: (deltaX: number, _deltaY: number) => deltaX,
+            /**
+             * Reads a pointer's coordinate along the horizontal bar.
+             * ポインタの、横のバーに沿う座標を読む処理。
+             */
             getPointerCoordinate: ({ clientX }) => clientX,
             arrowIcons: ["◀", "▶"],
             directionClass: "aqvs-scrollbar-horizontal",
@@ -391,7 +399,15 @@ const createOrientationConfig = (horizontal: boolean): OrientationConfig => {
         mainSizeKey: "height",
         crossSizeKey: "width",
         thumbTranslateFunction: "translateY",
+        /**
+         * Picks the component of a pointer drag along the vertical bar.
+         * ポインタのドラッグの、縦のバーに沿う成分を選ぶ処理。
+         */
         selectDelta: (_deltaX: number, deltaY: number) => deltaY,
+        /**
+         * Reads a pointer's coordinate along the vertical bar.
+         * ポインタの、縦のバーに沿う座標を読む処理。
+         */
         getPointerCoordinate: ({ clientY }) => clientY,
         arrowIcons: ["▲", "▼"],
         directionClass: "aqvs-scrollbar-vertical",
@@ -476,44 +492,55 @@ const useArrowAutoRepeat = ({ canUseArrowButtons, enableArrowButtons, keyboardOp
     }, [clearArrowTimers])
 
     const handleArrowPointerDown = useCallback(
-        (direction: 1 | -1) => (event: React.PointerEvent<HTMLButtonElement>) => {
-            if (!canUseArrowButtons) {
-                return
-            }
-            if (event.cancelable) {
-                event.preventDefault()
-            }
-            event.stopPropagation()
-            resetTapScroll()
-            clearArrowTimers()
-            scrollByStep(direction)
-            arrowHoldTimeoutRef.current = window.setTimeout(() => {
-                arrowHoldIntervalRef.current = window.setInterval(() => {
-                    scrollByStep(direction)
-                }, ARROW_HOLD_INTERVAL)
-            }, ARROW_HOLD_DELAY)
-            // ボタンが disabled 化 / ウィンドウ blur で pointerup を取りこぼしてもリピートを確実に止める保険。
-            const release = () => clearArrowTimers()
-            globalReleaseRef.current = release
-            window.addEventListener("pointerup", release)
-            window.addEventListener("pointercancel", release)
-            window.addEventListener("blur", release)
-        },
+        (direction: 1 | -1) =>
+            /**
+             * Handles a press on an arrow: one step at once, then a repeat while the press is held, ended by the release anywhere,
+             * a cancel or the window losing focus.
+             * 矢印の押下を扱う処理。すぐに 1 段進め、押している間は繰り返し、どこでの解放・取り消し・ウィンドウのフォーカスの喪失で止める。
+             */
+            (event: React.PointerEvent<HTMLButtonElement>) => {
+                if (!canUseArrowButtons) {
+                    return
+                }
+                if (event.cancelable) {
+                    event.preventDefault()
+                }
+                event.stopPropagation()
+                resetTapScroll()
+                clearArrowTimers()
+                scrollByStep(direction)
+                arrowHoldTimeoutRef.current = window.setTimeout(() => {
+                    arrowHoldIntervalRef.current = window.setInterval(() => {
+                        scrollByStep(direction)
+                    }, ARROW_HOLD_INTERVAL)
+                }, ARROW_HOLD_DELAY)
+                // ボタンが disabled 化 / ウィンドウ blur で pointerup を取りこぼしてもリピートを確実に止める保険。
+                const release = () => clearArrowTimers()
+                globalReleaseRef.current = release
+                window.addEventListener("pointerup", release)
+                window.addEventListener("pointercancel", release)
+                window.addEventListener("blur", release)
+            },
         [canUseArrowButtons, clearArrowTimers, resetTapScroll, scrollByStep],
     )
 
     const handleArrowKeyDown = useCallback(
-        (direction: 1 | -1) => (event: React.KeyboardEvent<HTMLButtonElement>) => {
-            // ポインタ専用のバーは支援技術から隠れていて、キーボードのスクロールはホストが持つ。スクリプトがフォーカスした矢印でも
-            // キーを受けると、隠れた部品がホストのキー操作と重なって一覧を動かす
-            if (!(enableArrowButtons && keyboardOperable)) {
-                return
-            }
-            if (event.key === "Enter" || event.key === " " || event.key === "Spacebar") {
-                event.preventDefault()
-                scrollByStep(direction)
-            }
-        },
+        (direction: 1 | -1) =>
+            /**
+             * Handles Enter and Space on a focused arrow as one step, unless the bar is pointer-only or its arrows are disabled.
+             * フォーカスした矢印での Enter と Space を 1 段として扱う処理 (バーがポインタ専用か矢印が無効なら何もしない)。
+             */
+            (event: React.KeyboardEvent<HTMLButtonElement>) => {
+                // ポインタ専用のバーは支援技術から隠れていて、キーボードのスクロールはホストが持つ。スクリプトがフォーカスした矢印でも
+                // キーを受けると、隠れた部品がホストのキー操作と重なって一覧を動かす
+                if (!(enableArrowButtons && keyboardOperable)) {
+                    return
+                }
+                if (event.key === "Enter" || event.key === " " || event.key === "Spacebar") {
+                    event.preventDefault()
+                    scrollByStep(direction)
+                }
+            },
         [enableArrowButtons, keyboardOperable, scrollByStep],
     )
 

package/src/ScrollPane.tsx

@@ -1064,12 +1064,28 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         useImperativeHandle(
             ref,
             () => ({
+                /**
+                 * Stops any inertia, then jumps to a pane position (clamped); returns the applied position.
+                 * 慣性を止めてからペインの位置へ跳ぶ (クランプする) 処理。当てた位置を返す。
+                 */
                 scrollTo: (pos, dimsOverride) => {
                     stopInertia()
                     return scrollTo(pos, dimsOverride)
                 },
+                /**
+                 * Reads the pane position (synchronously fresh, from the position ref).
+                 * ペインの位置を読む処理 (位置の ref から読むので同期で最新)。
+                 */
                 getScrollPosition: () => scrollPositionRef.current,
+                /**
+                 * Reads the content size the pane was given.
+                 * ペインが受け取った中身の寸法を読む処理。
+                 */
                 getContentSize: () => contentSize,
+                /**
+                 * Reads the viewport size the pane uses (given or measured).
+                 * ペインが使う表示域の寸法 (与えられたか測ったもの) を読む処理。
+                 */
                 getViewportSize: () => viewportSize,
                 applyWheel,
             }),

package/src/TapScrollCircle.tsx

@@ -360,9 +360,17 @@ export const TapScrollCircle = memo(
         useImperativeHandle(
             ref,
             () => ({
+                /**
+                 * Returns the circle to its resting state and reports it through `onDragChange`.
+                 * サークルを静止の状態へ戻し、`onDragChange` で知らせる処理。
+                 */
                 reset: () => {
                     resetState(true)
                 },
+                /**
+                 * Reads the circle's root element (null while it is not mounted).
+                 * サークルのルートの要素を読む処理 (マウントしていない間は null)。
+                 */
                 getElement: () => rootRef.current,
             }),
             [resetState],

package/src/VirtualGrid.tsx

@@ -1038,6 +1038,10 @@ const VirtualGridInner = <T,>(
         (root: HTMLDivElement) => {
             rootRef.current = root
             if (hasExplicitViewport) {
+                /**
+                 * Detaches the root (the given viewport needs no observer).
+                 * ルートを外す処理 (与えられたビューポートには監視が要らない)。
+                 */
                 return () => {
                     rootRef.current = null
                 }
@@ -1059,6 +1063,10 @@ const VirtualGridInner = <T,>(
             measure()
             const observer = new ResizeObserver(measure)
             observer.observe(root)
+            /**
+             * Detaches the root and stops the observer.
+             * ルートを外し、監視を止める処理。
+             */
             return () => {
                 observer.disconnect()
                 rootRef.current = null
@@ -1806,6 +1814,12 @@ const VirtualGridInner = <T,>(
     useImperativeHandle(
         ref,
         (): VirtualGridHandle => ({
+            /**
+             * Applies `y` through the embedded row list's `scrollTo` (it floors and pins a row anchor) and `x` through `applyHx`,
+             * clearing any column anchor; returns the applied position.
+             * `y` は埋め込みの行の一覧の `scrollTo` (切り捨てて行のアンカーを張る) で、`x` は列のアンカーを外して `applyHx` で当て、当てた位置を
+             * 返す処理。
+             */
             scrollTo: (pos) => {
                 const inner = scrollHandleRef.current
                 let y = vyRef.current
@@ -1822,6 +1836,11 @@ const VirtualGridInner = <T,>(
                 }
                 return { x, y }
             },
+            /**
+             * Applies a non-zero `y` delta through `applyVy` and a non-zero `x` delta through `applyHx` (clearing any column anchor);
+             * returns the applied position.
+             * 0 でない `y` の差分は `applyVy` で、0 でない `x` の差分は列のアンカーを外して `applyHx` で当て、当てた位置を返す処理。
+             */
             scrollBy: (delta) => {
                 // 縦の差分はタップの駆動と同じ継ぎ目 (applyVy) で当て、適用と鏡像の同期を 2 通りに書かない
                 const y = delta.y !== undefined && delta.y !== 0 ? applyVy(delta.y) : vyRef.current
@@ -1832,6 +1851,12 @@ const VirtualGridInner = <T,>(
                 }
                 return { x, y }
             },
+            /**
+             * Reveals a cell: a scroll row through the embedded row list's `scrollToIndex` (translated by −R), a scroll column by
+             * arming a column anchor and applying its position; a frozen or trailing band row or column leaves its axis as it is.
+             * セルを見せる処理。スクロール行は −R へ訳して埋め込みの行の一覧の `scrollToIndex` で、スクロール列は列のアンカーを張ってその位置を
+             * 当てる。先頭・末尾の帯の行や列を狙った軸はそのまま。
+             */
             scrollToCell: (row, col, options) => {
                 const inner = scrollHandleRef.current
                 if (inner !== null && rowCount > 0) {
@@ -1856,7 +1881,18 @@ const VirtualGridInner = <T,>(
                     }
                 }
             },
+            /**
+             * Reads the position: `x` from the horizontal cell, `y` through `getVy` (the embedded handle, or the last position once the
+             * grid has unmounted).
+             * 位置を読む処理。`x` は横の位置のセルから、`y` は `getVy` (埋め込みのハンドル。グリッドのアンマウントの後は最後の位置) から。
+             */
             getScrollPosition: () => ({ x: hxRef.current, y: getVy() }),
+            /**
+             * Captures the `{ row, col, offsetX, offsetY }` anchor of the first visible cell of the scroll band, on the same boundary
+             * rule as the row side; null when either count is 0 or there is no scroll row.
+             * スクロール帯の最初に見えるセルの `{ row, col, offsetX, offsetY }` のアンカーを、行の側と同じ境界の規則で捕える処理。どちらかの数が 0、
+             * またはスクロール行が無ければ null。
+             */
             getScrollAnchor: () => {
                 if (rowCount === 0 || colCount === 0) {
                     return null
@@ -1883,11 +1919,26 @@ const VirtualGridInner = <T,>(
                 // 行はシフト空間 → フル行空間へ +R 翻訳 (行凍結設計 §3 — 復元側は −R で往復恒等)
                 return { row: rowAnchor.index + effectiveFrozenRows, col: found.index, offsetX: Math.max(0, bandStart - (column.cumulative - column.currentValue)), offsetY: rowAnchor.offsetPx }
             },
+            /**
+             * Reads the cell viewport (the measured or given box without the bars).
+             * セルのビューポート (測ったか与えられた箱からバーを除いたもの) を読む処理。
+             */
             getViewportSize: () => ({ width: viewportRef.current.width, height: viewportRef.current.height }),
+            /**
+             * Reads the content size: the total column width, and the band heights plus the embedded row list's content size
+             * (insets included; 0 once the grid has unmounted).
+             * 中身の寸法を読む処理。列の総幅と、帯の高さに埋め込みの行の一覧の中身の高さ (インセット込み。グリッドのアンマウントの後は 0) を足したもの。
+             */
             // 縦はインセット込みの行側 getContentSize を単一情報源にする (range.totalHeight は木総高のみ)。
             // 3.5.0: height = H_F + 埋め込み + H_T
             getContentSize: () => ({ width: totalWidthRef.current, height: scrollHandleRef.current === null ? 0 : frozenHeightRef.current + trailingHeightRef.current + Math.max(0, scrollHandleRef.current.getContentSize()) }),
             getRange: buildRange,
+            /**
+             * Takes a row's new height (validated first): a leading or trailing band row re-reads its accessor through its epoch, a
+             * scroll row goes to the embedded row list's `updateItemSize` (translated by −R).
+             * 行の新しい高さを受け取る処理 (先に検証)。先頭・末尾の帯の行は epoch でアクセサを読み直させ、スクロール行は −R へ訳して埋め込みの
+             * 行の一覧の `updateItemSize` へ渡す。
+             */
             updateRowSize: (row, px) => {
                 validateTrackSize(px, "row", row)
                 // 凍結行はグリッド所有バンド — epoch 繰上げでアクセサ再読 (帯に第 2 の格納庫は
@@ -1901,12 +1952,20 @@ const VirtualGridInner = <T,>(
                     scrollHandleRef.current?.updateItemSize(Math.trunc(row) - effectiveFrozenRows, px)
                 }
             },
+            /**
+             * Takes a column's new width (validated first) into the width tree and mirrors the new total width at once.
+             * 列の新しい幅を (先に検証して) 幅木へ入れ、新しい総幅をすぐに写す処理。
+             */
             updateColSize: (col, px) => {
                 validateTrackSize(px, "col", col)
                 // 総幅は ref へも即時反映 (同 tick の scrollBy/scrollTo が旧上限でクランプしないため)。幅が変われば木の版数が進み、
                 // 窓キー不変でもセル配置を失効させる (バッチループは React 自動バッチングで 1 コミット)。同じ幅は何も失効させない
                 commitTotalWidth(changeColTree(() => colTree.update(minmax(Math.trunc(col), 0, Math.max(0, colCount - 1)), px)))
             },
+            /**
+             * Reads the effective frozen bands of both axes and both ends (the visible trailing sizes through `trailingVisibleSize`).
+             * 両軸・両端の実効の凍結帯を読む処理 (見えている末尾の寸法は `trailingVisibleSize` で求める)。
+             */
             getFrozenSize: () => ({
                 cols: effectiveFrozenCols,
                 width: frozenWidthRef.current,
@@ -1920,7 +1979,18 @@ const VirtualGridInner = <T,>(
                 trailingVisibleWidth: trailingVisibleSize(trailingWidthRef.current, frozenWidthRef.current, viewportRef.current.width),
                 trailingVisibleHeight: trailingVisibleSize(trailingHeightRef.current, frozenHeightRef.current, viewportRef.current.height),
             }),
+            /**
+             * Applies one wheel event through the embedded row list (its horizontal part reaches the grid's own axis through the
+             * row list's `onWheelHorizontal`); returns whether the event was consumed, false once the grid has unmounted.
+             * ホイールのイベント 1 つを埋め込みの行の一覧で当てる処理 (横の成分は行の一覧の `onWheelHorizontal` を通ってグリッド自身の軸へ届く)。
+             * 消費したかを返し、グリッドのアンマウントの後は false。
+             */
             applyWheel: (event) => scrollHandleRef.current?.applyWheel(event) ?? false,
+            /**
+             * Focuses a row: a leading or trailing band row through its band DOM, a scroll row through the embedded row list's
+             * `focusItemAtIndex` (translated by −R).
+             * 行へフォーカスする処理。先頭・末尾の帯の行は帯の DOM へ直接、スクロール行は −R へ訳して埋め込みの行の一覧の `focusItemAtIndex` で。
+             */
             focusRowAtIndex: (row, options) => {
                 // 凍結行はバンド行 DOM へ直接フォーカス、末尾帯行も帯行 DOM へ直接フォーカス
                 // (3.5.0 — 3 分岐。T = 0 は分岐不成立で従来挙動と恒等)、スクロール行は −R 翻訳して委譲