@aiquants/virtualscroll 3.1.0 → 3.4.0

package/src/VirtualScroll.tsx

@@ -338,6 +338,20 @@ export type VirtualScrollProps<T> = {
      * ここへ流れる。名前は 2.x で公開済みのため据え置くが、意味は「横軸が N px 動いた。横軸はあなたの所有物である」。
      */
     onWheelHorizontal?: (deltaX: number) => void
+    /**
+     * Delegates the horizontal component of a pointer pan (touch / pen drag) upstream — the pan
+     * twin of `onWheelHorizontal`, same sign convention (positive = scroll right), per-move
+     * increments divided by the press-time x-axis ancestor scale (v3.2.0 VirtualGrid seam).
+     * ❗ Belongs to the SAME horizontal-seam family as `onWheelHorizontal` and is deliberately a
+     * top-level prop: wrappers that seal the horizontal axis with `Omit<>` (e.g.
+     * `@aiquants/directory-tree`) must add this name to their seal list on the 3.2.0 bump
+     * (the pass-through review their seal guard mandates).
+     * ポインタパン (タッチ / ペン) の横成分を上流へ委譲する — `onWheelHorizontal` のパン対
+     * (符号同一・per-move 増分・押下時横 scale 除算、v3.2.0 VirtualGrid シーム)。横シーム
+     * ファミリの一員として意図的にトップレベル: `Omit<>` で横軸を封じるラッパーは 3.2.0
+     * 更新時に本名を封印リストへ追加すること (封印ガードが義務化する pass-through review)。
+     */
+    onPanHorizontal?: (deltaX: number) => void
     /**
      * Keyboard gestures that emit a horizontal scroll delta through `onWheelHorizontal` (default: none).
      * `onWheelHorizontal` へ横スクロール量を流すキーボード操作の種別 (既定: 無効)。
@@ -453,20 +467,28 @@ const toPanePositionWithInset = (logical: number, top: number) => (logical <= 0
 
 /**
  * Maximum run length of consecutive zero-height rows scanned linearly before attempting an
- * O(log n) jump to the next non-zero row via the Fenwick tree.
+ * O(log n) jump to the next non-zero row via the Fenwick tree. Module-level export (NOT in the
+ * package barrel) so VirtualGrid's column axis shares the SAME constant instead of duplicating
+ * the value (the §5 no-copy rule — same treatment as ANCHOR_REBASE_DISTANCE).
  *
- * 高さ 0 行の連続をこの件数まで線形走査し、超えたら Fenwick 木で次の非 0 行へ O(log n) ジャンプする閾値。
+ * 高さ 0 行の連続をこの件数まで線形走査し、超えたら Fenwick 木で次の非 0 行へ O(log n) ジャンプ
+ * する閾値。モジュールレベル export (バレル非公開) — VirtualGrid 列軸が値の複製でなく同一定数を
+ * 共有するため (§5 複製禁止規範 — ANCHOR_REBASE_DISTANCE と同じ扱い)。
  */
-const ZERO_HEIGHT_RUN_LIMIT = 1000
+export const ZERO_HEIGHT_RUN_LIMIT = 1000
 
 /**
  * Safety cap for the number of item nodes materialized in a single render pass.
  * Guards against pathological rendering ranges (e.g. a huge contiguous run of zero-height rows).
+ * Module-level export (NOT in the package barrel) — VirtualGrid's rendered-row estimator caps
+ * its materialized-row walk with the SAME constant (zero-height rows DO materialize as DOM rows).
  *
  * 1 回のレンダーで具現化するアイテムノード数の安全上限。
- * 病的な描画範囲 (巨大な高さ 0 行の連続など) からの防御。
+ * 病的な描画範囲 (巨大な高さ 0 行の連続など) からの防御。モジュールレベル export (バレル非公開) —
+ * VirtualGrid の描画行見積りが具現化行ウォークの上限として同一定数を共有する
+ * (高さ 0 行も DOM 行として具現化されるため)。
  */
-const MAX_RENDERED_ITEMS = 2000
+export const MAX_RENDERED_ITEMS = 2000
 
 /**
  * Distance (px) between the rendering window start and the current render anchor beyond which
@@ -477,7 +499,7 @@ const MAX_RENDERED_ITEMS = 2000
  * 行 top とラッパー translateY をブラウザのレイアウト座標上限 (LayoutUnit 約 2^25 px) と
  * compositor の f32 精度内に収めるための量子化距離。
  */
-const ANCHOR_REBASE_DISTANCE = 1_048_576 // 2^20 px
+export const ANCHOR_REBASE_DISTANCE = 1_048_576 // 2^20 px — VirtualGrid の横アンカーが共有 import する (パッケージバレルへは非公開)
 
 /**
  * Pixels emitted per horizontal arrow key press. Matches the ~40px browsers scroll for an arrow key.
@@ -996,6 +1018,7 @@ const VirtualScrollInner = <T,>(
         scrollBarOptions,
         behaviorOptions,
         onWheelHorizontal,
+        onPanHorizontal,
         horizontalKeyInputs,
         horizontalKeyStep = DEFAULT_HORIZONTAL_KEY_STEP,
         contentProps,
@@ -2559,6 +2582,7 @@ const VirtualScrollInner = <T,>(
             renderThumbOverlay={renderThumbOverlay}
             wheelSpeedMultiplier={wheelSpeedMultiplier}
             onWheelHorizontal={onWheelHorizontal}
+            onPanHorizontal={onPanHorizontal}
             contentInsets={resolvedInsets}
             contentProps={contentProps}
             visibleStartIndex={visibleStartIndex}

package/src/index.ts

@@ -15,6 +15,7 @@ export { useHeightCache } from "./useHeightCache.ts"
 export { useLruCache } from "./useLruCache.ts"
 export { useWheelBridge, type WheelBridgeOptions, type WheelBridgeTarget } from "./useWheelBridge.ts"
 export { minmax } from "./utils.ts"
+export { MAX_FROZEN_LEADING_COLS, MAX_FROZEN_LEADING_ROWS, MAX_RENDERED_CELLS, MAX_TRACK_SIZE, VirtualGrid, type VirtualGridBehaviorOptions, type VirtualGridHandle, type VirtualGridLiveRegionOptions, type VirtualGridProps, type VirtualGridRange } from "./VirtualGrid.tsx"
 export {
     VirtualScroll,
     type VirtualScrollBehaviorOptions,

package/src/styles/virtualscroll.css

@@ -348,3 +348,123 @@
   clip-path: inset(50%);
   white-space: nowrap;
 }
+
+/* ============================================================
+ * VirtualGrid (v3.2.0) — 汎用 2D 仮想化。横軸は残差 transform
+ * (--aqvs-grid-hx-residual — 書き手は VirtualGrid の root 直書きのみ。
+ * 消費者は .aqvs-grid-row の translateX、凍結モード (v3.3.0) では
+ * .aqvs-grid-row-scroll-inner の calc(残差 − W_F))。
+ * grid-template-rows の minmax(0, 1fr) は必須 — 素の 1fr は暗黙
+ * min-content 下限で縮小追随が壊れる (既知クラスの再発防止)。
+ * ============================================================ */
+.aqvs-grid {
+  position: relative;
+  display: grid;
+  grid-template-rows: minmax(0, 1fr) auto;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+}
+
+/* 凍結行帯 (行凍結設計 §4-2): R > 0 のときだけルートへ行を 1 本足す (auto = H_F)。
+ * R = 0 はクラスも帯要素も出力されず従来テンプレートと恒等 (F = 0 恒等契約の行版)。 */
+.aqvs-grid-has-frozen-rows {
+  grid-template-rows: auto minmax(0, 1fr) auto;
+}
+
+.aqvs-grid-frozen-rows {
+  position: relative;
+  min-width: 0;
+  overflow: hidden;
+}
+
+/* 帯行の中身 (.aqvs-grid-row — height 100%) は帯行枠へそのまま追随する (VirtualScroll の
+ * item-container 内と同じ前提が成立するため追加宣言は不要)。 */
+.aqvs-grid-frozen-band-row {
+  position: absolute;
+  left: 0;
+  /* right はインライン (= scrollBarWidth — 縦バーコーナーの予約。ペインのクリップ箱と一致させ、
+   * 帯行のセル / 消費側背景がバー上へはみ出さない)。overflow はその実クリップ器。 */
+  overflow: hidden;
+}
+
+.aqvs-grid-main {
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+}
+
+/* 行ラッパー — セルの containing block、かつ横残差の消費者。
+ * 変数は残差のみ (生 hx は配らない — 深部の f32/LayoutUnit 破綻の根治)。
+ * ❗ 消費者はグリッド所有のこのクラスに限る: contentProps className 経由でペインの
+ * コンテンツ要素へ載せる方式は、ScrollPane が contentProps を構造クラスより後に
+ * 展開するため `aqvs-scroll-pane-content` (overflow/position/flex) を破壊する。
+ * クリップはペインのコンテンツ要素 (overflow: hidden) が従来どおり担う。
+ * 入れ子の素の VirtualScroll / 内側の VirtualGrid には波及しない (このクラスは
+ * VirtualGrid の renderRow だけが出力し、変数はそれぞれの root でスコープされる)。 */
+.aqvs-grid-row {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+  transform: translateX(var(--aqvs-grid-hx-residual, 0px));
+}
+
+/* セル — left は「列絶対座標 − 列アンカー」(常に有界)。 */
+.aqvs-grid-cell {
+  position: absolute;
+  top: 0;
+  height: 100%;
+  overflow: hidden;
+}
+
+/* 凍結モード (v3.3.0 — 設計 §8): 行は静的化する (残差はスクロール帯 inner が消費)。
+ * 複合セレクタ (0,2,0) は意図的 — .aqvs-grid-row (0,1,0) の translateX をソース順序に
+ * 依存せず常に上書きする (ルール並べ替えで沈黙退行しない特異度設計)。 */
+.aqvs-grid-row.aqvs-grid-row-frozen-host {
+  transform: none;
+}
+
+/* スクロール帯の静的クリップ (§8-b/c): 左端 = W_F。transform を持つ要素は自分のクリップ箱ごと
+ * 動くため、クリップ (この要素) と残差 translate (子の inner) は必ず分離する。 */
+.aqvs-grid-row-scroll {
+  position: absolute;
+  top: 0;
+  height: 100%;
+  left: var(--aqvs-grid-frozen-width, 0px);
+  right: 0;
+  overflow: hidden;
+}
+
+/* スクロール帯の座標ホルダー — 残差 − W_F の原点シフト項 (§8-b)。クリップ原点が W_F にあるため
+ * セル最終位置は (列絶対 − colAnchor) + (colAnchor − hx − W_F) + W_F = 列絶対 − hx で不変。 */
+.aqvs-grid-row-scroll-inner {
+  position: absolute;
+  top: 0;
+  height: 100%;
+  left: 0;
+  width: 100%;
+  transform: translateX(calc(var(--aqvs-grid-hx-residual, 0px) - var(--aqvs-grid-frozen-width, 0px)));
+}
+
+/* 横バー帯。 */
+.aqvs-grid-hbar-strip {
+  position: relative;
+  min-width: 0;
+  /* 凍結列帯の整列 (実証是正): トラック原点をスクロール帯開始 (W_F) へ。F = 0 は変数不在で
+   * 0px — DOM / 描画とも従来恒等 (インライン属性を足さないため §8 の恒等契約を保つ)。 */
+  padding-left: var(--aqvs-grid-frozen-width, 0px);
+}
+
+/* 読み上げ用リージョン (視覚非表示 — sr-only 相当)。 */
+.aqvs-grid-live-region {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+  border: 0;
+}

package/src/useFenwickMapTree.ts

@@ -160,9 +160,9 @@ export class FenwickMapTree {
      * @description Fenwick Tree の初期化。
      * @param {number} size - The total number of items.
      * @param {number | ((index: number) => number)} valueOrFn - The value for all elements, or a function to generate values.
-     * @param {{ sampleRange?: { from: number; to: number }, materialize?: boolean }} [options] - Optional settings for initialization.
+     * @param {{ sampleRange?: { from: number; to: number }, materialize?: boolean, baseValue?: number }} [options] - Optional settings for initialization (`baseValue` skips sampling — see reset). / 初期化オプション (`baseValue` はサンプリング省略 — reset 参照)。
      */
-    constructor(size: number, valueOrFn: number | ((index: number) => number), options?: { sampleRange?: { from: number; to: number }; materialize?: boolean }) {
+    constructor(size: number, valueOrFn: number | ((index: number) => number), options?: { sampleRange?: { from: number; to: number }; materialize?: boolean; baseValue?: number }) {
         this.reset(size, valueOrFn, options)
     }
 
@@ -179,9 +179,9 @@ export class FenwickMapTree {
      * throw しつつ木を半構築で残さず直前の状態を無傷に保つ方針。
      * @param {number} size - The total number of items.
      * @param {number | ((index: number) => number)} valueOrFn - The value for all elements, or a function to generate values.
-     * @param {{ sampleRange?: { from: number; to: number }, materialize?: boolean }} [options] - Optional settings for initialization.
+     * @param {{ sampleRange?: { from: number; to: number }, materialize?: boolean, baseValue?: number }} [options] - Optional settings for initialization. `baseValue` (finite, >= 0 — RangeError otherwise) skips all sampling and fixes the uniform estimate for unmaterialized items (v3.2.0, the VirtualGrid defaultColWidth path). / 初期化オプション。`baseValue` (有限かつ 0 以上 — 違反は RangeError) は全サンプリングを省略し未具現化アイテムの見積りを固定する (v3.2.0、VirtualGrid defaultColWidth 経路)。
      */
-    reset(size: number, valueOrFn: number | ((index: number) => number), options?: { sampleRange?: { from: number; to: number }; materialize?: boolean }) {
+    reset(size: number, valueOrFn: number | ((index: number) => number), options?: { sampleRange?: { from: number; to: number }; materialize?: boolean; baseValue?: number }) {
         // size を正規化する: 非有限 (NaN/Infinity)・非正は 0、小数は切り捨て。
         // NaN size は `this.size > 0` 系の判定をすり抜けて total を NaN 汚染するため入口で遮断する。
         const safeSize = Number.isFinite(size) && size > 0 ? Math.trunc(size) : 0
@@ -201,7 +201,27 @@ export class FenwickMapTree {
         // (半構築状態を残さない)。検証済みの値だけを後段のコミットフェーズで木へ流し込む。
         let baseValue = 0
         let seed: { from: number; values: number[] } | undefined
-        if (safeSize > 0) {
+        // 明示 baseValue (v3.2.0): サンプリングを丸ごと省略し、未具現化アイテムの見積りを
+        // 呼び出し側が確定させる (VirtualGrid の defaultColWidth 経路)。非有限・負は fail-fast
+        // (黙って 0 やサンプリングへ読み替えない)
+        const explicitBase = options?.baseValue
+        if (explicitBase !== undefined && !(Number.isFinite(explicitBase) && explicitBase >= 0)) {
+            throw new RangeError(`[FenwickMapTree] options.baseValue must be a finite number >= 0, received ${explicitBase}.`)
+        }
+        if (safeSize > 0 && explicitBase !== undefined) {
+            baseValue = explicitBase
+            // 具現化要求は従来どおり初期可視ウィンドウのみ対象 (正確性の維持)
+            if (options?.materialize) {
+                const range = options?.sampleRange ?? { from: 0, to: Math.min(SAMPLE_COUNT - 1, safeSize - 1) }
+                let from = Math.max(0, Math.trunc(range.from))
+                let to = Math.min(Math.trunc(range.to), safeSize - 1)
+                if (from > to) {
+                    from = 0
+                    to = Math.min(SAMPLE_COUNT - 1, safeSize - 1)
+                }
+                seed = { from, values: FenwickMapTree._collectValidatedValues(valueOrFn, from, to) }
+            }
+        } else if (safeSize > 0) {
             // 初期可視ウィンドウ (= 具現化対象) の範囲を決定する。
             // baseValue の推定範囲とは分離する: 具現化は利用者が最初に見る領域だけ正確化すればよいが、
             // baseValue は未具現化の全アイテムの総高さ推定に効くため、リスト全体を代表する値が必要。
@@ -1358,12 +1378,12 @@ const sampleRangeChanged = (a?: { sampleRange?: { from: number; to: number } },
  * @param {number} size - The total number of items.
  * @param {number | ((index: number) => number)} valueOrFn - The value for all elements, or a function to generate values.
  * @param {number | ((index: number) => number)} valueOrFn - 全要素の均一な値、または値を生成する関数。不要なツリーの再作成を防ぐため、この関数は `useCallback` でメモ化すること。
- * @param {{ sampleRange?: { from: number; to: number }, resetOnValueFnChange?: boolean, debug?: boolean }} [options] - Optional settings.
- * @param {{ sampleRange?: { from: number; to: number } }} [options] - 初期化時のオプション設定。不要なツリーの再作成を防ぐため、このオブジェクトは `useMemo` でメモ化すること。
+ * @param {{ sampleRange?: { from: number; to: number }, resetOnValueFnChange?: boolean, debug?: boolean, baseValue?: number }} [options] - Optional settings (`baseValue` skips sampling — see FenwickMapTree.reset). / オプション (`baseValue` はサンプリング省略 — FenwickMapTree.reset 参照)。
+ * @param {{ sampleRange?: { from: number; to: number }, resetOnValueFnChange?: boolean, debug?: boolean, baseValue?: number }} [options] - 初期化時のオプション設定 (`baseValue` はサンプリング省略 — FenwickMapTree.reset 参照)。不要なツリーの再作成を防ぐため、このオブジェクトは `useMemo` でメモ化すること。
  * @returns {FenwickMapTree} The FenwickMapTree instance.
  * @returns {FenwickMapTree} FenwickMapTree インスタンス。
  */
-export const useFenwickMapTree = (size: number, valueOrFn: number | ((index: number) => number), options?: { sampleRange?: { from: number; to: number }; debug?: boolean; resetOnValueFnChange?: boolean }): FenwickMapTree => {
+export const useFenwickMapTree = (size: number, valueOrFn: number | ((index: number) => number), options?: { sampleRange?: { from: number; to: number }; debug?: boolean; resetOnValueFnChange?: boolean; baseValue?: number }): FenwickMapTree => {
     // size を正規化する: 非有限 (NaN は Math.max(0, NaN) を素通りする)・非正は 0、小数は切り捨て。
     // reset / changeSize へ渡る前にここで遮断し、木の内部を NaN 汚染させない (reset と同一規則)。
     const validSize = Number.isFinite(size) && size > 0 ? Math.trunc(size) : 0
@@ -1380,10 +1400,12 @@ export const useFenwickMapTree = (size: number, valueOrFn: number | ((index: num
     // Detect changes
     const sizeChanged = prev.size !== validSize
     const valueOrFnChanged = prev.valueOrFn !== valueOrFn
-    // options は参照比較ではなく sampleRange の値で比較する。
-    // 非メモ化のインライン options でも sampleRange が同一なら reset を起こさない
-    // (計測済み delta を毎レンダーで破棄しないため)。
-    const optionsChanged = sampleRangeChanged(prev.options, options)
+    // options は参照比較ではなく sampleRange / baseValue の値で比較する。
+    // 非メモ化のインライン options でも値が同一なら reset を起こさない
+    // (計測済み delta を毎レンダーで破棄しないため)。baseValue の値変化は未具現化アイテムの
+    // 見積り総和そのものを変えるため reset (新 base での再構築) を要する — 黙って旧 base の
+    // まま握り潰すと総和・バー写像・深部着地が stale 化する。
+    const optionsChanged = sampleRangeChanged(prev.options, options) || prev.options?.baseValue !== options?.baseValue
 
     // 旧 size が 0 の木は baseValue が未確立 (0) のまま。増分伸長 (changeSize) では
     // total = 0 * N = 0 で固着するため、0 -> N の伸長は resetOnValueFnChange の設定に

package/src/utils.ts

@@ -14,3 +14,45 @@
 export const minmax = (value: number, min: number, max: number): number => {
     return Math.max(min, Math.min(max, value))
 }
+
+/**
+ * Computes an element's CSS transform scale along one axis (visual px / layout px).
+ *
+ * 要素の指定軸方向 CSS transform スケール (視覚px / レイアウトpx) を算出。
+ * 祖先に transform: scale(...) があると client 座標 (視覚px) がレイアウトpx とズレるため、
+ * その比率でドラッグ量・クリック座標を補正する。分母には整数丸めされる offsetWidth/offsetHeight
+ * ではなく、transform の影響を受けず小数精度を持つ getComputedStyle のレイアウト寸法
+ * (content + padding + border) を優先して使い、transform なしなら厳密に 1 を返す。
+ * 取得不能時 (jsdom 等) は offset 寸法へフォールバックし、それも 0 なら 1 を返す。
+ *
+ * @param element The element to measure. / 計測対象要素。
+ * @param axis The axis to measure along ("x" = width, "y" = height). / 計測軸。
+ * @returns The visual/layout scale ratio (1 when unmeasurable). / 視覚/レイアウト比 (計測不能時 1)。
+ */
+export const getAxisScale = (element: HTMLElement, axis: "x" | "y"): number => {
+    const isX = axis === "x"
+    const rect = element.getBoundingClientRect()
+    const visualSize = isX ? rect.width : rect.height
+    // computed style の値 (px 文字列) を数値化する。解釈不能なら 0 とみなす。
+    const parseSize = (value: string) => {
+        const parsed = Number.parseFloat(value)
+        return Number.isFinite(parsed) ? parsed : 0
+    }
+    const computed = window.getComputedStyle(element)
+    const contentSize = parseSize(isX ? computed.width : computed.height)
+    // rect (border-box) と同系になるよう content + padding + border を合成する。
+    const computedLayoutSize =
+        contentSize > 0
+            ? contentSize +
+              parseSize(isX ? computed.paddingLeft : computed.paddingTop) +
+              parseSize(isX ? computed.paddingRight : computed.paddingBottom) +
+              parseSize(isX ? computed.borderLeftWidth : computed.borderTopWidth) +
+              parseSize(isX ? computed.borderRightWidth : computed.borderBottomWidth)
+            : 0
+    // computed が取れない環境 (jsdom 等) では従来の offset 寸法へフォールバックする。
+    const layoutSize = computedLayoutSize > 0 ? computedLayoutSize : isX ? element.offsetWidth : element.offsetHeight
+    if (layoutSize <= 0 || visualSize <= 0) {
+        return 1
+    }
+    return visualSize / layoutSize
+}