@aiquants/virtualscroll 3.4.0 → 3.6.0

package/src/computeTapScrollVelocity.ts

@@ -0,0 +1,150 @@
+/**
+ * Pure two-axis velocity decomposition for the unified grid tap circle (v3.6.0).
+ * 統合 2 軸タップサークル (v3.6.0) 用の純関数 2 軸速度分解モジュール。
+ */
+
+import { computeTapScrollSpeed } from "./ScrollBar.tsx"
+
+/**
+ * Per-axis speed parameters for `computeTapScrollVelocity` — the exact tuple one bar resolves
+ * today. Deliberately an explicit structural type (NOT `Omit<TapScrollSpeedInput, …>`):
+ * api-extractor cannot roll up `Omit<>` on the public surface (house rule).
+ * `computeTapScrollVelocity` の軸別速度パラメータ — 今日 1 本のバーが解決する組そのもの。
+ * 意図的な明示構造型 (`Omit<>` 非使用 — api-extractor がロールアップできないための既定方針)。
+ */
+export type TapScrollAxisSpeedParams = {
+    /** Viewport length on this axis (px). / この軸のビューポート長 (px)。 */
+    viewportSize: number
+    /** Minimum speed multiplier (viewport-relative). / 最小速度倍率 (ビューポート比)。 */
+    minSpeedMultiplier: number
+    /** Maximum speed multiplier (viewport-relative). / 最大速度倍率 (ビューポート比)。 */
+    maxSpeedMultiplier: number
+    /** Whether `maxSpeedMultiplier` was explicitly supplied (controls the 1,200 px/s auto floor). / `maxSpeedMultiplier` が明示指定か (1,200 px/s 自動床の制御)。 */
+    hasCustomMaxSpeedMultiplier: boolean
+    /** Optional speed-curve shape (same contract as `TapScrollSpeedInput.curve`). / 任意の速度曲線形状 (`TapScrollSpeedInput.curve` と同契約)。 */
+    curve?: { exponentialSteepness: number; exponentialScale?: number; easedOffset?: number }
+}
+
+/**
+ * Input for `computeTapScrollVelocity`.
+ * `computeTapScrollVelocity` の入力。
+ */
+export type TapScrollVelocityInput = {
+    /** Signed px from the circle center (state canonical field). / サークル中心からの符号付き px (state 正準フィールド)。 */
+    offsetX: number
+    /** Signed px from the circle center (state canonical field). / サークル中心からの符号付き px (state 正準フィールド)。 */
+    offsetY: number
+    /** Shared pull range (= `max(maxVisualDistance, 1)`). / 共有引き範囲 (= `max(maxVisualDistance, 1)`)。 */
+    maxDistance: number
+    /** Horizontal-axis speed parameters. / 横軸の速度パラメータ。 */
+    x: TapScrollAxisSpeedParams
+    /** Vertical-axis speed parameters. / 縦軸の速度パラメータ。 */
+    y: TapScrollAxisSpeedParams
+}
+
+/**
+ * Decomposes a 2-D tap-circle pull into per-axis scroll velocities (px/s, signed):
+ *
+ * ```text
+ * r = 0  =>  v = (0, 0)
+ * r > 0  =>  v = ( s_x(r) * ox / r ,  s_y(r) * oy / r )
+ * ```
+ *
+ * where `r = ||(ox, oy)||_2` and `s_a` is the UNCHANGED `computeTapScrollSpeed` under axis `a`'s
+ * parameters (`distance: r`, shared `maxDistance`).
+ *
+ * Derivation summary (the axioms this law is the unique solution of):
+ *
+ * - D1 (legacy reproduction): pure-axis inputs reproduce each 1-D bar law to within 1 ulp
+ *   under the pinned order — deviations hit a config-dependent ~9% of probed pure-axis points,
+ *   so never assert bit-equality (`toBe` / `Object.is`) of a pure-axis component against
+ *   `computeTapScrollSpeed` outside the committed exact fixtures. The rejected order
+ *   `s * (o / r)` would be bit-exact on pure axes (`o / r = ±1` exactly); the pin below
+ *   trades that for fixture-order independence (plan §4.2 T1 / §4.3).
+ * - D2 (radial law under isotropy): when `s_x = s_y = s`, `|v| = s(r)` at every angle.
+ * - D3 (separability): `v_a = s_a(r) * u_a(theta)` for a direction-only unit field `u`.
+ * - D4 (isotropic direction fidelity — a CHOSEN axiom, not derived): when `s_x = s_y`,
+ *   `v` is parallel to the offset with a positive scalar (rotational equivariance).
+ *
+ * D1-D3 alone do NOT force this law: they admit the whole family
+ * `u = (cos phi(theta), sin phi(theta))` for any continuous strictly increasing angle remap
+ * `phi` fixing the four cardinal angles (e.g. `phi(theta) = theta - epsilon * sin(4 theta)`).
+ * D4 pins `phi = id`. That family is the registered invariant-preserving tuning point for
+ * near-axis leakage (plan §4.4); v3.6.0 ships `phi = id`.
+ *
+ * Evaluation-order pin: each component is computed literally as `s_a(r) * o_a / r`
+ * (left-to-right, i.e. `(s * o) / r`). The two orders differ by 1 ulp for SOME inputs —
+ * verified witness: `40 * (7 / 25) = 11.200000000000001` while `(40 * 7) / 25 = 11.2` exactly.
+ * The committed spec fixtures happen to agree under BOTH orders (`200 * (30 / 50) === 120`
+ * etc. — the products land inside half-ulp and round back); the pin exists so the fixtures'
+ * `toBe` exactness never depends on that luck of the operand set. Do NOT "test" the old,
+ * numerically false claim that `200 * (30 / 50)` misrounds — it does not; deleting this pin
+ * because that claim fails would discard a sound pin.
+ *
+ * Totality: non-finite `ox` / `oy` are sanitized to 0 and `r = 0` returns `(0, 0)` (the origin
+ * has no continuous extension — the limit depends on the approach angle). Components are always
+ * finite: `s_a` is the existing sole NaN barrier and `|o_a| / r <= 1`.
+ *
+ * External reproduction of what a bar/grid actually resolves (same pattern as the
+ * `computeTapScrollSpeed` docstring):
+ *
+ * ```ts
+ * const velocity = computeTapScrollVelocity({
+ *     offsetX,
+ *     offsetY,
+ *     maxDistance: options.maxVisualDistance ?? TAP_SCROLL_SPEED_DEFAULTS.maxDistance,
+ *     x: {
+ *         viewportSize: bandWidth,
+ *         minSpeedMultiplier: options.minSpeedMultiplier ?? TAP_SCROLL_SPEED_DEFAULTS.minSpeedMultiplier,
+ *         maxSpeedMultiplier: options.maxSpeedMultiplier ?? computeAutoTapScrollMaxSpeedMultiplier(colCount),
+ *         hasCustomMaxSpeedMultiplier: options.maxSpeedMultiplier !== undefined,
+ *         curve: options.maxSpeedCurve,
+ *     },
+ *     y: { …same with the pane height and rowCount… },
+ * })
+ * ```
+ *
+ * 2 次元のタップサークル引きを軸別スクロール速度 (px/s、符号付き) へ分解する処理。方向余弦
+ * 分解 `v = (s_x(r)·ox/r, s_y(r)·oy/r)` — `s_a` は無改造の `computeTapScrollSpeed`。D4
+ * (等方時の方向忠実) は導出ではなく選択公理で、許容リマップ族 `u = (cos φ(θ), sin φ(θ))` を
+ * `φ = id` に固定する。評価順序は `s_a(r) * o_a / r` (左から右) にピン — 1 ulp 証人は
+ * `40*(7/25) ≠ (40*7)/25`。D1 の純軸再現はピン順序下で ≤ 1 ulp (構成依存の約 9% の点で乖離 —
+ * ビット恒等は棄却順序 `s·(o/r)` の側で、ピンはそれをフィクスチャ順序非依存と引き換えた)。
+ * 非有限オフセットは 0 へ消毒し、`r = 0` は `(0, 0)`。
+ *
+ * @param input Offsets, shared pull range, and per-axis speed parameters. / オフセット・共有引き範囲・軸別速度パラメータ。
+ * @returns Signed per-axis velocities in px/s (always finite). / 軸別の符号付き速度 (px/s、常に有限)。
+ */
+export const computeTapScrollVelocity = ({ offsetX, offsetY, maxDistance, x, y }: TapScrollVelocityInput): { x: number; y: number } => {
+    // 非有限オフセットの消毒 (finiteOr 規律): 素通しすると r と両成分が NaN 化し、
+    // スクロール位置の NaN 汚染 (文書化済みの回復不能故障) へ直結する
+    const ox = Number.isFinite(offsetX) ? offsetX : 0
+    const oy = Number.isFinite(offsetY) ? offsetY : 0
+    const r = Math.hypot(ox, oy)
+    // 原点は連続拡張が存在しない (極限が接近角に依存) ため全域関数規約で (0, 0) を返す。
+    // ドライバのゲートが積分時 r >= 6 を保証するので、この分岐は純関数側の防御でもある
+    if (r === 0) {
+        return { x: 0, y: 0 }
+    }
+    const speedX = computeTapScrollSpeed({
+        distance: r,
+        maxDistance,
+        viewportSize: x.viewportSize,
+        minSpeedMultiplier: x.minSpeedMultiplier,
+        maxSpeedMultiplier: x.maxSpeedMultiplier,
+        hasCustomMaxSpeedMultiplier: x.hasCustomMaxSpeedMultiplier,
+        curve: x.curve,
+    })
+    const speedY = computeTapScrollSpeed({
+        distance: r,
+        maxDistance,
+        viewportSize: y.viewportSize,
+        minSpeedMultiplier: y.minSpeedMultiplier,
+        maxSpeedMultiplier: y.maxSpeedMultiplier,
+        hasCustomMaxSpeedMultiplier: y.hasCustomMaxSpeedMultiplier,
+        curve: y.curve,
+    })
+    // 評価順序ピン (§4.3): s_a(r) * o_a / r — 左から右。括弧で順序を固定し、
+    // 「同値だから」と (s·(o/r)) へ並べ替える 1 ulp ドリフトを封じる
+    return { x: (speedX * ox) / r, y: (speedY * oy) / r }
+}

package/src/index.ts

@@ -5,6 +5,7 @@
  * 可変なアイテム高さに対応したReact用の高性能仮想スクロールコンポーネント。
  */
 
+export { computeTapScrollVelocity, type TapScrollAxisSpeedParams, type TapScrollVelocityInput } from "./computeTapScrollVelocity.ts"
 export { createResidualQuantizer, type ResidualQuantizer, type ResidualQuantizerOptions } from "./residualQuantizer.ts"
 export { computeAutoTapScrollMaxSpeedMultiplier, computeTapScrollSpeed, ScrollBar, type ScrollBarProps, type ScrollBarTapCircleOptions, type ScrollBarThumbOverlayRenderProps, TAP_SCROLL_SPEED_DEFAULTS, type TapScrollSpeedInput } from "./ScrollBar.tsx"
 export { ScrollPane, type ScrollPaneContentInsets, type ScrollPaneHandle, type ScrollPaneInertiaOptions, type ScrollPaneProps } from "./ScrollPane.tsx"
@@ -15,7 +16,20 @@ 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 {
+    MAX_FROZEN_LEADING_COLS,
+    MAX_FROZEN_LEADING_ROWS,
+    MAX_FROZEN_TRAILING_COLS,
+    MAX_FROZEN_TRAILING_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

@@ -372,6 +372,16 @@
   grid-template-rows: auto minmax(0, 1fr) auto;
 }
 
+/* 末尾行帯 (3.5.0): T > 0 のときだけ最終 hbar 行の直前に auto 行を足す。テンプレート合成は
+ * 4 通り — 基本 / 先頭のみ (既存) / 末尾のみ / 両方。行高そのものはインライン H_T_vis
+ * (高さの CSS 変数は存在しない — 帯寸の変数は幅 2 つのみ。残差 var --aqvs-grid-hx-residual は別系)。 */
+.aqvs-grid-has-trailing-rows {
+  grid-template-rows: minmax(0, 1fr) auto auto;
+}
+.aqvs-grid-has-frozen-rows.aqvs-grid-has-trailing-rows {
+  grid-template-rows: auto minmax(0, 1fr) auto auto;
+}
+
 .aqvs-grid-frozen-rows {
   position: relative;
   min-width: 0;
@@ -388,6 +398,29 @@
   overflow: hidden;
 }
 
+/* 末尾行帯のクリップ (テンプレート行 = H_T_vis インライン) と bottom 定着 inner (木高 H_T
+ * インライン)。inner の bottom: 0 が「帯上端 = extent − H_T_vis」を全構成で成立させ、
+ * 重複縮退では帯の末尾行が可視に残る (フロー配置帯の誤登録クラスの構造的封鎖)。 */
+.aqvs-grid-trailing-rows {
+  position: relative;
+  min-width: 0;
+  overflow: hidden;
+}
+.aqvs-grid-trailing-rows-inner {
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+}
+
+/* 帯行の実クリップ器 (先頭帯行 .aqvs-grid-frozen-band-row の転置 — right はインライン
+ * scrollBarWidth のコーナー予約)。 */
+.aqvs-grid-trailing-band-row {
+  position: absolute;
+  left: 0;
+  overflow: hidden;
+}
+
 .aqvs-grid-main {
   position: relative;
   min-width: 0;
@@ -432,7 +465,9 @@
   top: 0;
   height: 100%;
   left: var(--aqvs-grid-frozen-width, 0px);
-  right: 0;
+  /* 末尾凍結 (3.5.0): 右インセット = W_T。変数不在 (T = 0) は 0px フォールバックで
+   * 計算結果・出力ともバイト恒等 (T = 0 恒等契約)。 */
+  right: var(--aqvs-grid-trailing-width, 0px);
   overflow: hidden;
 }
 
@@ -447,6 +482,29 @@
   transform: translateX(calc(var(--aqvs-grid-hx-residual, 0px) - var(--aqvs-grid-frozen-width, 0px)));
 }
 
+/* 末尾列クリップ (3.5.0 — ADR-19-3): left の max() は先頭優先の CSS エンコード。
+ * ❗ この max() 形は trailingVisibleSize の calc() 版そのもの (クリップ左端 = extent − W_T_vis
+ * が恒等) — CSS は JS ヘルパーを読めないための登記済み例外 (単一情報源レジスタのエントリ 1)。 */
+.aqvs-grid-row-trailing {
+  position: absolute;
+  top: 0;
+  height: 100%;
+  left: max(var(--aqvs-grid-frozen-width, 0px), calc(100% - var(--aqvs-grid-trailing-width, 0px)));
+  right: 0;
+  overflow: hidden;
+}
+
+/* 右アンカーの座標ホルダー — 末尾セルは帯ローカル left で置かれ、inner の右定着が
+ * 「末尾が 2 番目に潰れる」を幾何で成立させる (クリップ / transform 分離の恒久契約に従い
+ * transform は持たない)。 */
+.aqvs-grid-row-trailing-inner {
+  position: absolute;
+  top: 0;
+  height: 100%;
+  right: 0;
+  width: var(--aqvs-grid-trailing-width, 0px);
+}
+
 /* 横バー帯。 */
 .aqvs-grid-hbar-strip {
   position: relative;
@@ -468,3 +526,34 @@
   white-space: nowrap;
   border: 0;
 }
+
+/* 統合 2 軸タップサークル (v3.6.0)。
+ * 純配置 — 意図的に transition を持たない: フェードする opacity は子 (サークルルート) に
+ * 住む。バー配置の「効果における双子」(DOM 形状の双子ではない)。 */
+.aqvs-grid-tap-circle-wrapper {
+  position: absolute;
+  z-index: 50; /* バーと同層 (.aqvs-scrollbar) — DOM 後勝ちで最前 */
+  pointer-events: auto;
+}
+
+/* ❗ このファイル内で .aqvs-tap-scroll-circle より「後」に置くこと: 両規則が同一要素へ
+ * 同特異度で transition longhand を設定し、後の規則が丸ごと勝つ — 出荷済み
+ * .aqvs-scrollbar-tap-circle-wrapper が今日それを行っているのと同一機構。バーサークルの
+ * 実効 transition (opacity のみ 150ms) をバイト再現し、transform 平滑化は意図的に無し
+ * (出荷挙動と一致)。順序はテストでピンする (プラン §10.2)。 */
+.aqvs-grid-tap-circle {
+  transition-property: opacity;
+  transition-duration: 150ms;
+  transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+/* パッケージ全域・単一所有者 — 本 CSS 初の forced-colors 規則: グラデーション視覚は
+ * forced-colors で平坦化され、輪郭なしではサークルが不可視になる (描画モード修正 —
+ * 単体サークルにも輪郭が付くのは登記済みの挙動非変更デルタ)。 */
+@media (forced-colors: active) {
+  .aqvs-tap-scroll-circle {
+    outline: 1px solid CanvasText;
+    outline-offset: -1px;
+    border-radius: 50%;
+  }
+}