@aiquants/virtualscroll 1.22.0 → 1.22.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/virtualscroll",
-  "version": "1.22.0",
+  "version": "1.22.1",
   "description": "High-performance virtual scrolling component for React with variable item heights",
   "sideEffects": [
     "**/*.css"

package/src/ScrollBar.tsx

@@ -1410,6 +1410,13 @@ export const ScrollBar = ({
      * pointerup を待たずにドラッグ状態を破棄し、stale な pointerId の残留を防ぐ。
      */
     const handleLostPointerCaptureOnTrack = (event: React.PointerEvent<HTMLDivElement>) => {
+        // ❗ 発生源がトラック自身のときだけ反応する。`lostpointercapture` はバブリングするため、
+        // 子孫であるつまみやオーバーレイのキャプチャ遷移まで拾ってしまう。タッチ・ペンでは仕様
+        // (暗黙のポインタキャプチャ) により着地点の子孫が先にキャプチャを持つので、この取り違えは
+        // 実際に起こり得る。トラックのドラッグ状態を壊してよいのはトラック自身の喪失だけ。
+        if (event.target !== event.currentTarget) {
+            return
+        }
         if (trackDragStateRef.current.pointerId !== event.pointerId) {
             return
         }

package/src/ScrollPane.tsx

@@ -129,6 +129,21 @@ const isPointerDragAllowed = (pointerType: string, allowed: readonly ("mouse" |
     return !known || allowed.includes(pointerType)
 }
 
+/**
+ * Reports whether a pointer type can emit move events while no button is pressed.
+ * ボタン非押下のまま移動イベントを出し得るポインタ種別かどうかの判定処理。
+ *
+ * ❗ **タッチを含めてはならない。** 接地しているタッチポインタは仕様上つねに
+ * `buttons === 1` であり、ホバーが存在しないため接地終了後は二度とイベントを出さない。
+ * つまりタッチで `buttons === 0` が観測されるのはエンジン側の不具合に限られ
+ * (旧 Firefox の既知バグ等)、それを「pointerup の喪失」と解釈してドラッグを畳むと、
+ * エンジンの不具合がそのままスクロール不能として現れる。
+ *
+ * @param pointerType The event's pointer type. イベントのポインタ種別。
+ * @returns True when button-released moves are meaningful for the type. 非押下の移動が意味を持つ種別なら true。
+ */
+const isHoverCapablePointer = (pointerType: string): boolean => pointerType === "mouse" || pointerType === "pen"
+
 const DEFAULT_INERTIA_OPTIONS: ResolvedScrollPaneInertiaOptions = {
     maxVelocity: 6,
     minVelocity: 0.02,
@@ -825,6 +840,43 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 pushVelocitySample(event.clientY)
             }
 
+            /**
+             * Reports whether a terminal pointer event is authoritative enough to end this drag.
+             * 終端ポインタイベントがこのペインのドラッグを終わらせる権威を持つかどうかの判定処理。
+             *
+             * `true` を返すのは次のどちらかのときだけである。
+             *
+             * 1. ユーザーエージェントが発火したイベント (`isTrusted === true`)。
+             *    本物の中断はジェスチャの終了そのものなので、`target` が何であれ必ず従う。
+             * 2. このペイン自身を `target` とするイベント。宛先が明示されているため、
+             *    利用側やテストが意図してこのペインへ直接投げたものと解釈できる。
+             *
+             * 逆に `false` を返す — つまり従わない — のは「**`isTrusted` でなく、かつ
+             * このペイン以外を `target` とするイベント**」である。子孫・兄弟・`window` の
+             * いずれを `target` としていても区別なく従わない。生きた `pointerId` を載せた
+             * `pointercancel` を子孫へ `dispatchEvent` する実装 (長押しメニュー等) は
+             * 珍しくなく、それは `window` までバブルして届くため、真に受けると
+             * **健全なドラッグが指を離すまで死ぬ** (実ブラウザで再現確認済み)。
+             *
+             * ❗ **キャプチャの保持状況で判定してはならない。** `hasPointerCapture()` は
+             * `setPointerCapture()` 直後の**保留中**のキャプチャに対しても `true` を返す。
+             * ユーザーエージェントが `gotpointercapture` の処理前にポインタを取り消すと、
+             * 本物の `pointercancel` も後続の `lostpointercapture` も**旧保持者である子孫宛**の
+             * まま届くため、キャプチャ保持を条件にすると後始末の経路が 1 本残らず塞がり、
+             * `shouldCancelNextClick` が residue として残ってペイン内の次のクリックを 1 回
+             * 握り潰す。これは**キャプチャ保持を条件にしていた旧実装で実測した事象**であり、
+             * `isTrusted` を基準にする現在の実装ではそもそも成立しない (この取り違えを
+             * 構造的に起こさないため)。
+             *
+             * ❗ この判定は**終端イベント (`pointerup` / `pointercancel`) 専用**である。
+             * `pointermove` に適用してはならない。キャプチャ取得前の本物の `pointermove` は
+             * ヒット先の子孫を `target` として届くため、絞ると追従そのものが止まる。
+             *
+             * @param event The terminal pointer event to classify. 判定対象の終端ポインタイベント。
+             * @returns True when the event may end this pane's drag. ドラッグを終わらせてよい場合に true。
+             */
+            const isAuthoritativeForDrag = (event: PointerEvent) => event.isTrusted || event.target === element
+
             // pointerup を受け取れないままドラッグ継続が不可能になったときの共通終了処理。
             // Shared teardown for cases where the drag can no longer continue without receiving a pointerup.
             const abortDrag = (pointerId: number) => {
@@ -844,7 +896,9 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                 }
                 // ボタン非押下の pointermove は pointerup の喪失 (iframe 上での解放・Alt+Tab 等) を意味する。
                 // stale な dragState を破棄し、hover 移動がカーソル追従スクロール化するのを根絶する。
-                if (event.buttons === 0) {
+                // ❗ ホバーできる種別に限定する。接地中のタッチが 0 を報告するのはエンジンの不具合だけで、
+                // 従うとその不具合がドラッグの即死になる (判定理由は isHoverCapablePointer を参照)。
+                if (event.buttons === 0 && isHoverCapablePointer(event.pointerType)) {
                     abortDrag(event.pointerId)
                     return
                 }
@@ -906,6 +960,14 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                     armOrphanedClickSuppression()
                     return
                 }
+                // ❗ ここには `isAuthoritativeForDrag` を掛けていない。掛けないのは意図的である。
+                // `pointerup` は「ジェスチャが正常に終わった」の意味しか持たず、合成されても
+                // 状態が壊れるのではなく 1 回のドラッグが早く終わるだけで、次の pointerdown から
+                // 通常どおり再開できる。`pointercancel` のように**ドラッグ枠を残したまま
+                // 追従だけ止める**という壊れ方をしないため、絞る必要が無い。
+                // 一方で絞ると、window を target として `pointerup` を投げる利用側・テストの
+                // ジェスチャが終了できなくなる (本物の `pointerup` の target は要素であって
+                // window ではないが、合成側はそこまで再現しないのが普通)。
 
                 if (state.isDragging && state.shouldCancelNextClick && event.cancelable) {
                     event.preventDefault()
@@ -958,11 +1020,39 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
             }
 
             const handlePointerDown = (event: PointerEvent) => {
-                // アクティブなドラッグ中 (pointerId 保持中) の別ポインタの pointerdown は無視する (先勝ち)。
-                // 上書きを許すと 1 本目のドラッグが乗っ取られ、shouldCancelNextClick のクリアで
-                // 1 本目解放時の click 抑止も失われるため。
                 if (dragStateRef.current.pointerId !== null) {
-                    return
+                    // アクティブなドラッグ中の 2 本目以降 (非プライマリ) の pointerdown は無視する (先勝ち)。
+                    // 上書きを許すと 1 本目のドラッグが乗っ取られ、shouldCancelNextClick のクリアで
+                    // 1 本目解放時の click 抑止も失われるため。
+                    if (!event.isPrimary) {
+                        return
+                    }
+                    // 別種別のポインタは、記録中のドラッグがまだ生きている可能性がある
+                    // (プライマリは種別ごとに 1 つ存在し得るため) ので奪わせない。
+                    //
+                    // ❗ この制限の代償: **異種のポインタからは残骸を明け渡せない**。
+                    // 例えばタッチの残骸が残った状態でマウスに持ち替えても奪還できず、
+                    // さらにここで早期 return するため `shouldCancelNextClick` の残骸も消えず、
+                    // マウスの次のクリックが 1 回握り潰される。それでも、生きているドラッグを
+                    // 誤って奪う方が実害が大きいと判断した。残骸は同種のポインタで明け渡せる。
+                    if (event.pointerType !== dragStateRef.current.pointerType) {
+                        return
+                    }
+                    // **同種のプライマリ**が新たに接地したなら、前のポインタは既に終了しているとみなす。
+                    // Pointer Events Level 3 は「その種別にアクティブなポインタが他に無いときに
+                    // プライマリになる」と定めており、規範的な MUST ではないが主要 UA はこう振る舞う
+                    // (Chromium で実測確認済み)。なおマウスで 2 回目の pointerdown が来ない本当の根拠は
+                    // chorded button の遷移規則 (押されているボタンが 0 個から 1 個以上になったときだけ
+                    // pointerdown を発火する) であって、プライマリの規則ではない。
+                    //
+                    // dragState が残っているのは終端イベント (pointerup / pointercancel) を
+                    // 取りこぼしたということなので、残骸を捨てて新しいジェスチャへ明け渡す。
+                    // ここを無条件の先勝ちにすると、タッチでは復帰手段が一切無くなる:
+                    // タッチはホバーが無いため接地終了後にイベントを出さず、`buttons === 0` による
+                    // 自己修復は届かない。pointerId は仕様上 UA が再利用してよい (MAY) ため、
+                    // 番号の一致に依存した復帰も当てにできない。結果としてペインは
+                    // アンマウントされるまで永久に操作不能のまま固まる。
+                    abortDrag(dragStateRef.current.pointerId)
                 }
                 // 進行中ドラッグが無いのに抑止が残っているなら、click が来なかった前ジェスチャの残骸。
                 // 新しいジェスチャへ持ち越すと無関係なクリックを飲み込むのでここで捨てる
@@ -1008,10 +1098,40 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                     armOrphanedClickSuppression()
                     return
                 }
+                // アプリ層が投げた合成 pointercancel には従わない (判定理由は isAuthoritativeForDrag を参照)
+                if (!isAuthoritativeForDrag(event)) {
+                    return
+                }
                 abortDrag(event.pointerId)
             }
 
+            /**
+             * Ends the drag when this pane itself loses the pointer capture it holds.
+             * このペイン自身が保持しているポインタキャプチャを失ったときにドラッグを終了する処理。
+             *
+             * ❗ **発生源 (`event.target`) が自分自身のときだけ反応すること。**
+             * `lostpointercapture` はバブリングする。そしてタッチ・ペンでは仕様
+             * (Pointer Events Level 3 の暗黙のポインタキャプチャ) により、`pointerdown` の
+             * 着地点が先にキャプチャを持つ。仮想リストで指が着地するのは通常
+             * **このコンテンツ要素の子孫である行**である (`contentInsets` のパディング帯や
+             * 空リストではこの要素自身が着地点になることもあるが、その場合は付け替えが
+             * 起きないだけで無害)。`startDragging` がドラッグ確定時に祖先であるこの要素へ
+             * キャプチャを**付け替える**と、旧保持者である子孫に `lostpointercapture` が
+             * 発火し、**同じ `pointerId` を載せたまま**ここまでバブルしてくる。
+             *
+             * `pointerId` だけで判定すると、自分が起こした正常な付け替えを
+             * 「OS によるキャプチャ強制剥奪」と誤認し、**開始した直後のドラッグを自分で殺す**。
+             * 実機のスマートフォンでは「6px の閾値を跨いだ 1 フレームだけスクロールして、
+             * あとは指を離すまで完全に無反応」という症状になる (実測で確認)。
+             * マウスには暗黙のポインタキャプチャが無く付け替えが発生しないため、
+             * 同じコードでもデスクトップだけは無傷で通る。これが
+             * 「PC では動くのにスマートフォンだけ壊れる」の正体だった。
+             */
             const handleLostPointerCapture = (event: PointerEvent) => {
+                // 子孫から上がってきた通知は自分のキャプチャ喪失ではない (暗黙キャプチャの付け替え)
+                if (event.target !== element) {
+                    return
+                }
                 const state = dragStateRef.current
                 if (state.pointerId !== event.pointerId) {
                     return
@@ -1097,6 +1217,15 @@ export const ScrollPane = forwardRef<ScrollPaneHandle, ScrollPaneProps>(
                         // 短いリスト上のタッチがページ全体のパンを妨げるデッドゾーン化を防ぐ。
                         // 直接操作 (指・ペン) のドラッグを許可していない場合も付けない。
                         // touch-action はペン入力にも効くため、判定は touch と pen の論理和にする
+                        //
+                        // ❗ この値はタッチ開始時にラッチされる (実測: 1ms 後に none へ変えても手遅れ)。
+                        // 中身が非同期に届くリストでは、「まだスクロール不能」な一瞬に指が着地すると
+                        // **そのジェスチャ 1 回分**はブラウザに接収されたまま戻らない。
+                        // 指を離して置き直せば次のジェスチャからは正常に効くため、損失は 1 ジェスチャに
+                        // 限られ恒久破損にはならない (実測で確認)。ドラッグ許可の判定 (isScrollable) と
+                        // 同一条件で揃えてあるため状態としても一貫している。
+                        // 非同期コンテンツを先読みして確保する挙動は意図的に入れていない
+                        // (空のペインがページのパンを殺すデッドゾーンになり、そちらの実害の方が大きいため)。
                         ...(enablePointerDrag && isScrollable && pointerDragInputs.some((type) => type === "touch" || type === "pen") ? { touchAction: "none" } : {}),
                     }}
                     id={id}>

package/src/TapScrollCircle.tsx

@@ -298,6 +298,16 @@ export const TapScrollCircle = memo(
 
         const handleLostPointerCapture = useCallback(
             (event: ReactPointerEvent<HTMLDivElement>) => {
+                // ❗ 発生源が自分自身のときだけ反応する。`lostpointercapture` はバブリングし、
+                // タッチ・ペンでは仕様 (Pointer Events Level 3 の暗黙のポインタキャプチャ) により
+                // `pointerdown` の着地点 — サークルの中身を描く子要素 — が先にキャプチャを持つ。
+                // `handlePointerDown` がルートへキャプチャを付け替えると、旧保持者である子孫に
+                // `lostpointercapture` が発火し、同じ `pointerId` を載せたままここへバブルしてくる。
+                // `pointerId` だけで判定すると、自分が起こした正常な付け替えを強制剥奪と誤認して
+                // **触れた瞬間にタップスクロールが死ぬ** (マウスは暗黙キャプチャが無いため無傷)。
+                if (event.target !== event.currentTarget) {
+                    return
+                }
                 if (pointerIdRef.current !== event.pointerId) {
                     return
                 }