@aiquants/virtualscroll 3.11.0 → 3.11.2

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/useFenwickMapTree.d.cts

@@ -17,6 +17,20 @@ 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 declare const FENWICK_LOOKUP_ONLY: Readonly<{
+    materializeOption: Readonly<{
+        materialize: false;
+    }>;
+}>;
 /**
  * @class FenwickTree
  * @classdesc Implements a Fenwick Tree (or Binary Indexed Tree).
@@ -513,4 +527,38 @@ export declare const useFenwickMapTree: (size: number, valueOrFn: number | ((ind
     resetOnValueFnChange?: boolean;
     baseValue?: number;
 }) => FenwickMapTree;
+/**
+ * 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;
+};
+/**
+ * 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 declare const useFenwickTreeRevision: (tree: FenwickMapTree) => FenwickTreeRevision;
 export {};

package/dist/useFenwickMapTree.d.ts

@@ -17,6 +17,20 @@ 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 declare const FENWICK_LOOKUP_ONLY: Readonly<{
+    materializeOption: Readonly<{
+        materialize: false;
+    }>;
+}>;
 /**
  * @class FenwickTree
  * @classdesc Implements a Fenwick Tree (or Binary Indexed Tree).
@@ -513,5 +527,39 @@ export declare const useFenwickMapTree: (size: number, valueOrFn: number | ((ind
     resetOnValueFnChange?: boolean;
     baseValue?: number;
 }) => FenwickMapTree;
+/**
+ * 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;
+};
+/**
+ * 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 declare const useFenwickTreeRevision: (tree: FenwickMapTree) => FenwickTreeRevision;
 export {};
 //# sourceMappingURL=useFenwickMapTree.d.ts.map

package/dist/useFenwickMapTree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFenwickMapTree.d.ts","sourceRoot":"","sources":["../src/useFenwickMapTree.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useFenwickMapTree.d.ts","sourceRoot":"","sources":["../src/useFenwickMapTree.ts"],"names":[],"mappings":"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"}

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.0",
+  "version": "3.11.2",
   "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

@@ -263,6 +263,39 @@ export type ScrollBarProps = {
 
 /** The minimum size of the scrollbar thumb. / スクロールバーのつまみの最小サイズ。 */
 const MIN_THUMB_SIZE = 20
+
+/**
+ * One whole percent: the precision of the value text the bar and its thumb announce (`maximumFractionDigits: 0`), and how far
+ * inside the two ends every position between them is held before it is rounded.
+ *
+ * 1 パーセント。バーとつまみが知らせる値の文字の精度 (`maximumFractionDigits: 0`) で、両端の間のどの位置も丸める前にこれだけ
+ * 端の内側へ留める幅。
+ */
+const VALUE_TEXT_PERCENT = 0.01
+
+/**
+ * Resolves the fraction of the scroll range the bar and its thumb announce as their value text (formatted as a whole
+ * percent): 0 at the top and for a bar with nothing to scroll, 1 at or past the maximum (a list that shrank before the pane
+ * clamped), and every position strictly between them held in [0.01, 0.99], so the rounding never announces an end the list
+ * has not reached ("99%" while 999 of 200,000 rows are still below the window, "1%" one pixel below the top).
+ *
+ * バーとつまみが値の文字として知らせるスクロール範囲の割合 (整数の百分率で書く) を決める処理。先頭とスクロールできないバーは 0、
+ * 最大位置とそれを越えた位置 (ペインがクランプする前に縮んだ一覧) は 1、その間のどの位置も [0.01, 0.99] に留めるので、丸めが
+ * まだ着いていない端を知らせることはない (200,000 行のうち 999 行が窓の下に残れば "99%"、先頭から 1 px 下なら "1%")。
+ *
+ * @param scrollPosition - Scroll position (px) / スクロール位置 (px)
+ * @param maxScrollPosition - Maximum scroll position (px; 0 when nothing scrolls) / 最大スクロール位置 (px。スクロールできなければ 0)
+ * @returns The fraction to format / 書式にかける割合
+ */
+const resolveValueTextFraction = (scrollPosition: number, maxScrollPosition: number): number => {
+    if (maxScrollPosition <= 0 || scrollPosition <= 0) {
+        return 0
+    }
+    if (scrollPosition >= maxScrollPosition) {
+        return 1
+    }
+    return minmax(scrollPosition / maxScrollPosition, VALUE_TEXT_PERCENT, 1 - VALUE_TEXT_PERCENT)
+}
 const ARROW_HOLD_DELAY = 250
 const ARROW_HOLD_INTERVAL = 60
 const MIN_ARROW_STEP = 20
@@ -346,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",
@@ -358,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",
@@ -443,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],
     )
 
@@ -780,9 +840,8 @@ export const ScrollBar = ({
     // 負値が aria-valuemax へ露出して ARIA 違反 (valuemax < valuemin) になる。644 行の
     // getScrollBarMetrics と同一のクランプ規約)
     const maxScrollPosition = Math.max(contentSize - viewportSize, 0)
-    // ポインタ専用のバーは支援技術から隠れるので値の文字を持たない。スクロールできないバーは 0 %、中身が縮んで一時的に最大位置を
-    // 越えた位置は 100 %
-    const valueText = pointerOnly ? undefined : valueTextFormat.format(maxScrollPosition > 0 ? minmax(scrollPosition / maxScrollPosition, 0, 1) : 0)
+    // ポインタ専用のバーは支援技術から隠れるので値の文字を持たない
+    const valueText = pointerOnly ? undefined : valueTextFormat.format(resolveValueTextFraction(scrollPosition, maxScrollPosition))
     const effectiveTrackLength = Math.max(trackLength - thumbSize, 0)
     // scrollPosition が範囲外 (コンテンツ縮小直後の未クランプ 1 フレームや iOS バウンス値) でも
     // サムがトラック外へはみ出さないよう、レンダー時に [0, effectiveTrackLength] へクランプする。

package/src/ScrollPane.tsx

@@ -382,6 +382,44 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
         // 同一内容の警告を繰り返さないための最後の警告キー。
         const lastViewportWarningRef = useRef<string | null>(null)
 
+        // 0 の帯の警告が読む中身の寸法。自己計測の副作用の依存にすると、中身の寸法が変わるたびに監視を作り直して offsetHeight を
+        // 確定の中で読み直し (レイアウトを強いる)、長い一覧の追記のたびにその代価を払う
+        const contentSizeRef = useRef(contentSize)
+        // 最後の計測が、レイアウトされているのに高さ 0 の帯を見つけたか。中身が後から届いたときの警告は DOM を読まずにこれで決める
+        const isZeroBandMeasuredRef = useRef(false)
+
+        /**
+         * Warns once when the last measurement found the content band laid out yet 0 px high while there is content: the host
+         * gave the pane no height (the self-measurement's precondition). Reads the last measurement and the content size, never
+         * the DOM, so a change of the content size can run it without a forced layout.
+         *
+         * 最後の計測が、中身があるのにレイアウトされた高さ 0 の帯を見つけたとき、1 度だけ警告する処理 (ホストがペインに高さを与えて
+         * いない = 自己計測の前提破り)。最後の計測と中身の寸法だけを読み、DOM は読まないので、中身の寸法の変化から呼んでもレイアウトを
+         * 強いない。
+         */
+        const warnIfHostGivesNoHeight = useCallback(() => {
+            if (!isZeroBandMeasuredRef.current || contentSizeRef.current <= 0 || lastViewportWarningRef.current === "zero") {
+                return
+            }
+            lastViewportWarningRef.current = "zero"
+            Logger.warn("[ScrollPane] The self-measured viewport is 0px. Give the scroll pane's host element a definite height (e.g. h-full, flex-1 + min-h-0, an explicit px height), or pass viewportSize explicitly.")
+        }, [])
+
+        /**
+         * Keeps the content size the zero-band warning reads, and runs that warning when content arrives after a 0 px
+         * measurement (content that loads after the pane mounted in a host without a height).
+         * 0 の帯の警告が読む中身の寸法を保ち、0 px の計測の後に中身が届いたとき (高さの無いホストでペインの後に読み込まれた中身)
+         * にその警告を走らせる副作用。
+         *
+         * 目的: 中身の寸法を自己計測の依存にせずに警告へ届ける。
+         * 依存関係: [contentSize, warnIfHostGivesNoHeight]
+         * クリーンアップ: 不要。
+         */
+        useLayoutEffect(() => {
+            contentSizeRef.current = contentSize
+            warnIfHostGivesNoHeight()
+        }, [contentSize, warnIfHostGivesNoHeight])
+
         /**
          * Tracks the real height of the content band so the pane can size itself.
          * ペインが自分の帯の実高さを追跡し、自己サイズ決定できるようにする副作用。
@@ -391,14 +429,18 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
          * 「計測した数値を書き戻して自分のサイズを変える」フィードバックループが構造的に起こらない。
          * ルート要素を測ると、消費側がルートへ付けた padding の分だけ帯を過大評価してしまう。
          *
+         * 読み取りはマウントの 1 回だけが同期で (確定の中なのでレイアウトを 1 回強いる。最初の描画を実寸で出すため)、以後は
+         * ペインの生涯に 1 つの ResizeObserver の通知から読む (通知はレイアウトの後・描画の前に届くので強制リフローにならない)。
+         * 中身の寸法の変化はこの副作用を走らせない。
+         *
          * ❗ **0 の計測は採用しない。** `display: none` のタブに置かれている等でレイアウトされて
          * いないとき `offsetHeight` は 0 になる。0 を採ると `isScrollable` が偽になり、サイズ調整
          * エフェクト (§9) が `scrollTo(0)` を発行して**タブ切替でスクロール位置が失われる**。
          * 0 は「帯が 0」ではなく「まだ測れない」と解釈し、直前の値を保つ。
          *
          * 目的: 自己計測モードで帯の高さを State へ反映する。
-         * 依存関係: [contentSize, isSelfMeasuringViewport]
-         * クリーンアップ: ResizeObserver を切断する。
+         * 依存関係: [isSelfMeasuringViewport, warnIfHostGivesNoHeight]
+         * クリーンアップ: ResizeObserver を切断し、0 の帯の記録を消す。
          */
         useLayoutEffect(() => {
             if (!isSelfMeasuringViewport) {
@@ -408,31 +450,32 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             if (!element) {
                 return
             }
-            // ResizeObserver の通知は layout の後・paint の前に届くため、ここでの読み取りは強制リフローにならない。
-            // transform: scale(...) の下でもレイアウト px を得るため rect ではなく offsetHeight を使う (整数丸め)。
+            /**
+             * Reads the content band's height into the measured viewport size, or records a 0 px band for the warning.
+             * コンテンツの帯の高さを計測したビューポートの高さへ読み込み、0 px なら警告のために記録する処理。
+             */
             const applyMeasuredSize = () => {
+                // transform: scale(...) の下でもレイアウト px を得るため rect ではなく offsetHeight を使う (整数丸め)。
                 const measured = element.offsetHeight
                 if (measured > 0) {
+                    isZeroBandMeasuredRef.current = false
                     setMeasuredViewportSize((previous) => (previous === measured ? previous : measured))
                     return
                 }
                 // offsetParent が null なら display: none 等で非表示 = 正常な未計測状態なので黙る。
                 // レイアウトされているのに 0 の場合はホストが高さを確定させていない (自己計測の前提破り)。
-                if (element.offsetParent !== null && contentSize > 0 && lastViewportWarningRef.current !== "zero") {
-                    lastViewportWarningRef.current = "zero"
-                    Logger.warn("[ScrollPane] The self-measured viewport is 0px. Give the scroll pane's host element a definite height (e.g. h-full, flex-1 + min-h-0, an explicit px height), or pass viewportSize explicitly.")
-                }
+                isZeroBandMeasuredRef.current = element.offsetParent !== null
+                warnIfHostGivesNoHeight()
             }
             applyMeasuredSize()
-            if (typeof ResizeObserver !== "function") {
-                return
-            }
-            const observer = new ResizeObserver(applyMeasuredSize)
-            observer.observe(element)
+            const observer = typeof ResizeObserver === "function" ? new ResizeObserver(applyMeasuredSize) : null
+            observer?.observe(element)
             return () => {
-                observer.disconnect()
+                observer?.disconnect()
+                // 明示の viewportSize へ切り替えた後に中身が届いても、測っていない帯の警告を出さない
+                isZeroBandMeasuredRef.current = false
             }
-        }, [contentSize, isSelfMeasuringViewport])
+        }, [isSelfMeasuringViewport, warnIfHostGivesNoHeight])
 
         /**
          * Publishes the self-measured viewport size to the owner.
@@ -1021,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],