@aiquants/virtualscroll 2.4.0 → 2.6.0

package/src/wheelAxes.ts

@@ -0,0 +1,90 @@
+/**
+ * @module wheelAxes
+ * @description Single source of truth for how a wheel event is split into scroll axes.
+ * Used only by `ScrollPane.applyWheel`, which is itself the single seam every wheel caller goes
+ * through, so the rules cannot drift between the pane and elements outside it.
+ *
+ * @description ホイールイベントをスクロール軸へ分解する規則の単一の真実。呼び出し元は
+ * `ScrollPane.applyWheel` **だけ**であり、その `applyWheel` がすべてのホイール呼び出し元
+ * (ペイン根のリスナー / `useWheelBridge` / 消費側の直接呼び出し) の唯一のシームなので、
+ * ペイン内外で規則が食い違わない。
+ *
+ * ❗ **公開 API ではない** (`index.ts` から export しない)。公開すると `LINE_HEIGHT_PX = 16`・
+ * 同値時の横倒し・4 フィールドの形が恒久的に凍結される。
+ */
+
+/** Line height (px) assumed for `DOM_DELTA_LINE`. / `DOM_DELTA_LINE` で仮定する 1 行の高さ (px)。 */
+const LINE_HEIGHT_PX = 16
+
+/**
+ * Wheel axes resolved from a raw wheel event.
+ * 生のホイールイベントから解決した軸情報。
+ */
+export type ResolvedWheelAxes = {
+    /** True when ctrl is held, i.e. the browser treats it as zoom. Deltas are still reported as-is. / ctrl 押下 (ブラウザがズームとして扱う) の場合に true。デルタはそのまま報告する。 */
+    isZoomGesture: boolean
+    /** True when the horizontal component dominates (includes shift+wheel). / 横成分が優勢な場合に true (shift+ホイールを含む)。 */
+    isHorizontalDominant: boolean
+    /** Horizontal delta in px (deltaMode already converted). / px 単位の横方向デルタ (deltaMode 変換済み)。 */
+    horizontalDelta: number
+    /** Vertical delta in px (deltaMode already converted). / px 単位の縦方向デルタ (deltaMode 変換済み)。 */
+    verticalDelta: number
+}
+
+/**
+ * Converts a raw delta to pixels according to the event's `deltaMode`.
+ * イベントの `deltaMode` に従って生のデルタを px へ変換する処理。
+ *
+ * @param delta - Raw delta from the event / イベントの生デルタ
+ * @param deltaMode - `WheelEvent.deltaMode` / `WheelEvent.deltaMode`
+ * @param viewportSize - Viewport length used for `DOM_DELTA_PAGE` / `DOM_DELTA_PAGE` で使うビューポート長
+ * @returns The delta in pixels / px 単位のデルタ
+ */
+const toPixelDelta = (delta: number, deltaMode: number, viewportSize: number): number => {
+    if (deltaMode === 1) {
+        // DOM_DELTA_LINE: 行単位
+        return delta * LINE_HEIGHT_PX
+    }
+    if (deltaMode === 2) {
+        // DOM_DELTA_PAGE: ページ単位
+        return delta * viewportSize
+    }
+    return delta
+}
+
+/**
+ * Splits a wheel event into scroll axes, in pixels, applying the package's gesture rules.
+ * ホイールイベントを px 単位の軸へ分解し、本パッケージのジェスチャ規則を適用する処理。
+ *
+ * 規則 (判定順序そのものが仕様):
+ *
+ * 1. **shift+ホイール**は `deltaX === 0` のとき縦量を横として読む (Windows 系の慣習)。ブラウザが既に
+ *    `deltaX` へマップ済みなら通常の軸のまま扱う。
+ * 2. **横優勢判定**は横成分と縦成分の絶対値比較。等しい場合 (`|h| === |v|`) は横に倒す。ただし
+ *    **両軸とも 0 のときは横優勢としない** — 慣性の惰性通知で毎 tick 送られる 0/0 を横として
+ *    消費すると、ページ側のスクロールを無言で飲み込む。
+ *
+ * ❗ **これは解決器であって方針ではない。** `isZoomGesture` (ctrl 押下) が true でもデルタは
+ * そのまま返す。「ズームは横取りしない」という**方針**は適用側 (`ScrollPane.applyWheel`) が持つ。
+ *
+ * @param event - The wheel event / ホイールイベント
+ * @param viewportSize - Viewport length for `DOM_DELTA_PAGE` conversion / `DOM_DELTA_PAGE` 変換に使うビューポート長
+ * @returns The resolved axes / 解決した軸情報
+ */
+export const resolveWheelAxes = (event: WheelEvent, viewportSize: number): ResolvedWheelAxes => {
+    const usesShiftAxis = event.shiftKey && event.deltaX === 0
+    const rawHorizontal = usesShiftAxis ? event.deltaY : event.deltaX
+    const rawVertical = usesShiftAxis ? 0 : event.deltaY
+    const isHorizontalDominant = rawHorizontal !== 0 && Math.abs(rawHorizontal) >= Math.abs(rawVertical)
+
+    return {
+        // ❗ ズームでもデルタは潰さない。ここは**事実だけ**を報告し、「横取りしない」という
+        // 判断は適用側 (applyWheel) が下す。ここで 0 を詰めると適用側の ctrl 判定が
+        // 到達不能な飾りになり、`ctrl+shift+ホイール` を横スクロールとして食う退行を
+        // どのテストも検出できなくなる (変異解析で実証済み)。
+        isZoomGesture: event.ctrlKey,
+        isHorizontalDominant,
+        horizontalDelta: toPixelDelta(rawHorizontal, event.deltaMode, viewportSize),
+        verticalDelta: toPixelDelta(rawVertical, event.deltaMode, viewportSize),
+    }
+}

package/src/wheelConsumption.ts

@@ -0,0 +1,36 @@
+/**
+ * @module wheelConsumption
+ * @description Tracks which wheel events this package has already applied.
+ *
+ * @description 本パッケージが既に適用したホイールイベントを記録するモジュール。
+ *
+ * ❗ **`event.defaultPrevented` では代用できない。** あれは「誰かがこのイベントを止めた」であって
+ * 「**我々が**消費した」ではない。両者を混同すると、ページ全体のスクロールロック
+ * (`document` に capture + `preventDefault` を張る定番の実装) を掛けただけで一覧が
+ * まったくスクロールできなくなる。逆に印が無いと、ペインの入れ子や祖先に張った `useWheelBridge` で
+ * **同じデルタが 2 回適用**される (実測: 内側と外側の一覧が 1 ノッチで両方 100px 動く)。
+ *
+ * `WeakSet` なのでイベントオブジェクトの寿命を延ばさない。
+ */
+
+/** Wheel events already applied by a pane in this page. / このページのペインが適用済みのホイールイベント。 */
+const consumedWheelEvents = new WeakSet<WheelEvent>()
+
+/**
+ * Marks a wheel event as applied by this package.
+ * ホイールイベントを「本パッケージが適用済み」として記録する処理。
+ *
+ * @param event - The wheel event that was applied / 適用したホイールイベント
+ */
+export const markWheelConsumed = (event: WheelEvent): void => {
+    consumedWheelEvents.add(event)
+}
+
+/**
+ * Reports whether this package already applied the given wheel event.
+ * 指定のホイールイベントを本パッケージが既に適用済みかどうかを返す処理。
+ *
+ * @param event - The wheel event to test / 判定するホイールイベント
+ * @returns True when it was already applied / 既に適用済みの場合に true
+ */
+export const wasWheelConsumed = (event: WheelEvent): boolean => consumedWheelEvents.has(event)