@aiquants/virtualscroll 3.5.0 → 3.6.0

package/src/useGridTapScroll.ts

@@ -0,0 +1,370 @@
+/**
+ * Two-axis rAF driver hook for the grid-owned unified tap circle (v3.6.0). Transplants the
+ * ScrollBar tap-loop semantics per axis: residual accumulators with candidate-at-edge boundary
+ * reinforcement, per-axis direction-flip residual discard, per-frame immobility stop rule,
+ * extent-growth re-arm, and the fail-closed cancel trio.
+ * グリッド所有の統合タップサークル用 2 軸 rAF ドライバフック (v3.6.0)。ScrollBar タップループの
+ * 意味論を軸別に移植: 端候補補強つき残差アキュムレータ・軸別方向反転残差破棄・毎フレーム
+ * immobile 停止則・延長成長の再武装・fail-closed のキャンセル 3 系。
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react"
+import { computeTapScrollVelocity, type TapScrollAxisSpeedParams } from "./computeTapScrollVelocity.ts"
+import { TAP_SCROLL_CANCEL_EVENT, TAP_SCROLL_MAX_FRAME_DELTA_SECONDS } from "./ScrollBar.tsx"
+import type { TapScrollCircleDragState, TapScrollCircleHandle } from "./TapScrollCircle.tsx"
+import { minmax } from "./utils.ts"
+
+/**
+ * Default corner-relative offset (px) for BOTH grid tap-circle axes — the reachability arm (R)
+ * of the three-arm placement law (plan §5). Derivation: full speed needs
+ * `maxVisualDistance = 240 px` of advancing pull toward the far screen edge, which is a hard
+ * stop on touch (`touch-action: none`). With `off = −200` the disc center sits
+ * `sbw − off − size/2 = 12 + 200 − 20 = 192 px` inboard of each far root edge, giving a
+ * worst-case (fullscreen, flush) reachable pull fraction `n = 192/240 = 0.80` (`0.66` with the
+ * ~34 px OS gesture-navigation zone) ≈ 78 % / 63 % of full-pull speed under the default curve
+ * (`n^1.1`). K = 120 (= −200 − (−80)) is half the pull range — the smallest K keeping the
+ * nav-zone envelope ≥ ~2/3. Deliberately a LITERAL: it must NOT track a consumer-supplied
+ * `maxVisualDistance` (coupling two knobs would make one silently move the other), and
+ * shrinking `maxVisualDistance` instead is forbidden (it changes the speed law's `maxDistance`
+ * input and breaks the T1 identity anchor).
+ * グリッドタップサークル両軸のコーナー相対既定オフセット (px) — 3 アーム配置則の到達性アーム
+ * (R)。導出: 全速には前進方向へ 240 px の引きが要り、タッチではスクリーン端がハードストップ。
+ * −200 で中心は各遠端から 192 px 内側 = 最悪ケース引き分率 0.80 (ナビ帯込み 0.66)。意図的な
+ * リテラル — 消費側 `maxVisualDistance` へ連動させない (ノブ連動の登記済み禁止)。
+ */
+export const GRID_TAP_CIRCLE_DEFAULT_OFFSET = -200
+
+/** Per-axis driver bookkeeping (residual + last travel direction). / 軸別のドライバ内部状態 (残差 + 直前進行方向)。 */
+type AxisDriveState = {
+    /** Unconsumed scroll amount carried across frames. / フレームを跨いで持ち越す未消化スクロール量。 */
+    residual: number
+    /** Last non-zero travel direction (flip discards the residual). / 直前の非ゼロ進行方向 (反転で残差破棄)。 */
+    direction: -1 | 0 | 1
+}
+
+/** Idle drag state (the TapScrollCircle INITIAL_STATE shape — component-private, mirrored here like ScrollBar does). / 待機ドラッグ状態 (TapScrollCircle の INITIAL_STATE と同形 — ScrollBar と同じくコンポーネント私有形の写し)。 */
+const GRID_TAP_INITIAL_STATE: TapScrollCircleDragState = { active: false, offsetX: 0, offsetY: 0, distance: 0, direction: 0, pointerId: null }
+
+/** Parameters for `useGridTapScroll` (read live through a params ref — identity-stability is not required of callers). / `useGridTapScroll` のパラメータ (params ref 経由で毎フレーム最新を読む — 呼出し側に identity 安定を要求しない)。 */
+export type UseGridTapScrollParams = {
+    /** Whether the unified circle is live (resolved `enabled` ∧ `gridScrollable`). / 統合サークルが生きているか (解決済み `enabled` ∧ `gridScrollable`)。 */
+    enabled: boolean
+    /** Shared pull range (= `max(maxVisualDistance, 1)`). / 共有引き範囲 (= `max(maxVisualDistance, 1)`)。 */
+    maxDistance: number
+    /** Horizontal speed parameters (§4.1 Pₓ). / 横軸速度パラメータ (§4.1 Pₓ)。 */
+    xSpeedParams: TapScrollAxisSpeedParams
+    /** Vertical speed parameters (§4.1 P_y). / 縦軸速度パラメータ (§4.1 P_y)。 */
+    ySpeedParams: TapScrollAxisSpeedParams
+    /** The grid's x apply seam (absolute position in, clamped applied position out). / グリッドの x 適用シーム (絶対位置 → クランプ後位置)。 */
+    applyHxRef: { readonly current: (next: number) => number }
+    /** Synchronous-fresh hx read. / hx の同期・最新読み。 */
+    getHx: () => number
+    /** The ONE extracted x clamp law (`getMaxHx` SSOT — §3.5-7). / 唯一抽出の x クランプ則 (`getMaxHx` SSOT — §3.5-7)。 */
+    getMaxHx: () => number
+    /** y apply seam: wraps `scrollBy(delta)` AND syncs `vyRef.current = applied` before returning (§3.5-8 — NOT a bare handle passthrough). / y 適用シーム: `scrollBy(delta)` をラップし `vyRef.current = applied` を同期してから返す (§3.5-8 — 素のハンドル素通しではない)。 */
+    applyVy: (delta: number) => number
+    /** Synchronous-fresh vy read. / vy の同期・最新読み。 */
+    getVy: () => number
+    /** y extent read through the embedded handle's freshness channel (never re-derived). / 埋め込みハンドルの鮮度チャネル経由の y 延長 (再導出禁止)。 */
+    getMaxVy: () => number
+    /** Pending column anchor — cleared ONLY on frames whose APPLIED hx delta ≠ 0 (§3.5-5). / 保留列アンカー — 適用済み hx デルタ ≠ 0 のフレームのみ解除 (§3.5-5)。 */
+    pendingColAnchorRef: { current: unknown }
+    /** x extent-growth freshness key (columnWindow / total width — §3.5-3). / x 延長成長の鮮度キー (columnWindow / 総幅 — §3.5-3)。 */
+    xExtentFreshness: unknown
+    /** y extent-growth freshness key (the vertical range state — §3.5-3). / y 延長成長の鮮度キー (縦レンジ state — §3.5-3)。 */
+    yExtentFreshness: unknown
+}
+
+/** Result of `useGridTapScroll`. / `useGridTapScroll` の返り値。 */
+export type UseGridTapScrollResult = {
+    /** Whether a tap drag is engaged (drives the opacity law). / タップドラッグ係合中か (opacity 則を駆動)。 */
+    isTapActive: boolean
+    /** onDragChange handler for the grid's TapScrollCircle. / グリッドの TapScrollCircle へ渡す onDragChange。 */
+    handleTapCircleDragChange: (state: TapScrollCircleDragState) => void
+    /** Handle ref for the grid's TapScrollCircle (reset + containment reads). / グリッドの TapScrollCircle 用ハンドル ref (リセットと内包判定)。 */
+    tapCircleHandleRef: React.RefObject<TapScrollCircleHandle | null>
+}
+
+/**
+ * Owns the unified tap circle's drag state and the two-axis rAF integration loop.
+ * 統合タップサークルのドラッグ状態と 2 軸 rAF 積分ループを所有するフック。
+ *
+ * Per-frame semantics (plan §8.3 — implemented verbatim):
+ *
+ * ```text
+ * dt = min(max((t − last)/1000, 0), TAP_SCROLL_MAX_FRAME_DELTA_SECONDS); skip if dt ≤ 0
+ * (vx, vy) = computeTapScrollVelocity({ offsetX, offsetY, maxDistance, x: Pₓ, y: P_y })
+ * x: request = vx·dt → residual-apply via applyHx; applied hx delta ≠ 0 clears the col anchor
+ * y: request = vy·dt → residual-apply via applyVy (scrollBy + vyRef sync)
+ * immobile_a = (maxExtent_a ≤ 0) || atBoundary_a || (o_a === 0)   // atBoundary_a from THIS
+ *                                                                 // frame's apply — never latched
+ * stop iff !active || direction === 0 || (immobile_x && immobile_y)
+ * ```
+ *
+ * @param params Injected seams (read live through a ref). / 注入シーム (ref 経由で最新を読む)。
+ * @returns Drag-state wiring for the grid's circle. / グリッドサークル用のドラッグ結線。
+ */
+export const useGridTapScroll = (params: UseGridTapScrollParams): UseGridTapScrollResult => {
+    // パラメータは ref 経由で毎フレーム最新を読む (既存フック配線 effect に deps を足さない規律)
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    const tapDragStateRef = useRef<TapScrollCircleDragState>(GRID_TAP_INITIAL_STATE)
+    const tapCircleHandleRef = useRef<TapScrollCircleHandle | null>(null)
+    const [isTapActive, setIsTapActive] = useState(false)
+    const frameRef = useRef<number | null>(null)
+    const lastTimestampRef = useRef<number | null>(null)
+    const xDriveRef = useRef<AxisDriveState>({ residual: 0, direction: 0 })
+    const yDriveRef = useRef<AxisDriveState>({ residual: 0, direction: 0 })
+
+    /**
+     * Stops the rAF loop and clears per-axis integration state.
+     * rAF ループを停止し、軸別積分状態をクリアする処理。
+     */
+    const stopLoop = useCallback(() => {
+        if (frameRef.current !== null) {
+            window.cancelAnimationFrame(frameRef.current)
+            frameRef.current = null
+        }
+        lastTimestampRef.current = null
+        xDriveRef.current = { residual: 0, direction: 0 }
+        yDriveRef.current = { residual: 0, direction: 0 }
+    }, [])
+
+    /**
+     * Applies one axis's per-frame request through its residual accumulator and reports the
+     * applied delta plus THIS frame's boundary flag (candidate-at-edge ∧ no movement, or exact
+     * edge arrival). The flag is never stored across frames (§3.5-2 freshness rule).
+     * 1 軸の毎フレーム要求を残差アキュムレータ経由で適用し、適用デルタと**このフレームの**
+     * 境界フラグ (端候補 ∧ 不動、または端値到達) を返す処理。フラグはフレームを跨いで保存
+     * しない (§3.5-2 の鮮度規律)。
+     *
+     * @param drive Axis bookkeeping (mutated in place). / 軸別内部状態 (この場で更新)。
+     * @param velocity Signed axis velocity (px/s). / 符号付き軸速度 (px/s)。
+     * @param dt Frame delta (s). / フレーム時間 (秒)。
+     * @param getPos Fresh position read. / 位置の最新読み。
+     * @param getMax Fresh extent read. / 延長の最新読み。
+     * @param applyDelta Applies a delta and returns the applied position. / 差分を適用し適用後位置を返す。
+     * @returns Applied delta and the per-frame boundary flag. / 適用デルタと毎フレーム境界フラグ。
+     */
+    const stepAxis = useCallback((drive: AxisDriveState, velocity: number, dt: number, getPos: () => number, getMax: () => number, applyDelta: (delta: number) => number): { actualDelta: number; atBoundary: boolean } => {
+        // 方向反転の残差破棄 (軸別 — ScrollBar の方向転換破棄の成分双子): 逆向き残差を
+        // 持ち越すと燃焼し切るまで反転が固着する
+        const travelDirection: -1 | 0 | 1 = velocity > 0 ? 1 : velocity < 0 ? -1 : 0
+        if (travelDirection !== 0 && travelDirection !== drive.direction) {
+            drive.direction = travelDirection
+            drive.residual = 0
+        }
+        drive.residual += velocity * dt
+        const maxExtent = Math.max(getMax(), 0)
+        // 残差の暴走防止: 全スクロール範囲を超える残差は意味を持たない (ScrollBar と同じ保険)
+        if (maxExtent > 0) {
+            drive.residual = minmax(drive.residual, -maxExtent, maxExtent)
+        }
+        const request = drive.residual
+        if (request === 0) {
+            return { actualDelta: 0, atBoundary: false }
+        }
+        const before = getPos()
+        const appliedPosition = applyDelta(request)
+        const actualDelta = appliedPosition - before
+        drive.residual -= actualDelta
+        // 端候補補強 (ScrollBar applyScrollDelta の双子): 量子化する親では実位置が端値ちょうどに
+        // 届かないため、「クランプ前の要求候補が端に達しているのに位置が変わらない」も境界とみなす
+        const candidateAtMin = request < 0 && before + request <= 0
+        const candidateAtMax = request > 0 && before + request >= maxExtent
+        const atBoundary = (request < 0 && (appliedPosition <= 0 || (candidateAtMin && actualDelta === 0))) || (request > 0 && (appliedPosition >= maxExtent || (candidateAtMax && actualDelta === 0)))
+        if (atBoundary) {
+            drive.residual = 0
+        }
+        return { actualDelta, atBoundary }
+    }, [])
+
+    /**
+     * One integration frame of the two-axis loop.
+     * 2 軸ループの 1 積分フレーム。
+     */
+    const step = useCallback(
+        (timestamp: number) => {
+            // この rAF ループ意味論は ScrollBar.tsx の tap ループ (stepAutoScroll) と双子 — 片方を直したらもう片方も直すこと (ADR-27)
+            const current = paramsRef.current
+            const state = tapDragStateRef.current
+            if (!state.active || state.direction === 0) {
+                stopLoop()
+                return
+            }
+            const lastTimestamp = lastTimestampRef.current ?? timestamp
+            const deltaSecondsRaw = Math.max((timestamp - lastTimestamp) / 1000, 0)
+            const deltaSeconds = Math.min(deltaSecondsRaw, TAP_SCROLL_MAX_FRAME_DELTA_SECONDS)
+            lastTimestampRef.current = timestamp
+            if (deltaSeconds <= 0) {
+                frameRef.current = window.requestAnimationFrame(step)
+                return
+            }
+            // live state ref から毎フレーム分解 (§4.1 — 方向余弦分解)
+            const velocity = computeTapScrollVelocity({ offsetX: state.offsetX, offsetY: state.offsetY, maxDistance: current.maxDistance, x: current.xSpeedParams, y: current.ySpeedParams })
+            const xResult = stepAxis(xDriveRef.current, velocity.x, deltaSeconds, current.getHx, current.getMaxHx, (delta) => current.applyHxRef.current(current.getHx() + delta))
+            if (xResult.actualDelta !== 0) {
+                // 適用済み hx デルタのみが保留列アンカーを解除する (§3.5-5 — バーの要求時規則より厳格:
+                // 余弦則下ではほぼ縦のドラッグも常に付随 vx ≠ 0 を運ぶため、要求ゲートでは
+                // 右端で休んでいるだけでアンカーが無言脱落する)
+                current.pendingColAnchorRef.current = null
+            }
+            const yResult = stepAxis(yDriveRef.current, velocity.y, deltaSeconds, current.getVy, current.getMaxVy, current.applyVy)
+            // 停止則 (§3.5-2): 軸別 immobile を毎フレーム評価。o_a === 0 腕は厳密 (v_a ≡ 0) で、
+            // 軸上保持のアイドル空転とコーナー保持空転の両穴を閉じる。片軸境界は他軸の積分を続行
+            const immobileX = current.getMaxHx() <= 0 || xResult.atBoundary || state.offsetX === 0
+            const immobileY = current.getMaxVy() <= 0 || yResult.atBoundary || state.offsetY === 0
+            if (immobileX && immobileY) {
+                // パーク: onDragChange は毎 pointermove 発火 + 冪等 start なので、角度が付けば再開する
+                stopLoop()
+                return
+            }
+            frameRef.current = window.requestAnimationFrame(step)
+        },
+        [stopLoop, stepAxis],
+    )
+
+    /**
+     * Starts the loop if it is not already scheduled (idempotent — the ScrollBar twin).
+     * 未予約ならループを開始する処理 (冪等 — ScrollBar の双子)。
+     */
+    const startLoop = useCallback(() => {
+        if (frameRef.current === null) {
+            lastTimestampRef.current = null
+            xDriveRef.current = { residual: 0, direction: 0 }
+            yDriveRef.current = { residual: 0, direction: 0 }
+            frameRef.current = window.requestAnimationFrame(step)
+        }
+    }, [step])
+
+    /**
+     * Resets the drag state, the circle, and the loop (the fail-closed reset target).
+     * ドラッグ状態・サークル・ループをリセットする処理 (fail-closed のリセット着地点)。
+     */
+    const resetTapScroll = useCallback(() => {
+        tapDragStateRef.current = { ...GRID_TAP_INITIAL_STATE }
+        setIsTapActive(false)
+        tapCircleHandleRef.current?.reset()
+        stopLoop()
+    }, [stopLoop])
+
+    /**
+     * Receives drag-state updates from the circle and starts/stops the loop.
+     * サークルからのドラッグ状態更新を受け、ループを開始 / 停止する処理。
+     */
+    const handleTapCircleDragChange = useCallback(
+        (state: TapScrollCircleDragState) => {
+            tapDragStateRef.current = state
+            setIsTapActive(state.active)
+            if (state.active && state.direction !== 0) {
+                startLoop()
+            } else {
+                stopLoop()
+            }
+        },
+        [startLoop, stopLoop],
+    )
+
+    const { enabled, xExtentFreshness, yExtentFreshness } = params
+
+    /**
+     * Re-arms a boundary-parked loop when either axis's extent grows under a held finger.
+     * 保持中にどちらかの軸の延長が伸びたとき、境界パーク中のループを張り直す副作用。
+     *
+     * ❗ ループは境界 / immobile で自分を止め、`startLoop()` はポインタイベントからしか呼ばれ
+     * ない。無限スクロール / ストリーミング取得では指を離すまで動かない状態になるため、
+     * グリッド自身の鮮度チャネル (x: columnWindow / 総幅、y: 縦レンジ state) をキーに再開する
+     * (ScrollBar の contentSize / viewportSize 再武装の 2 軸双子)。冪等 start のため多重起動なし。
+     *
+     * 目的: 延長成長時の再前進 (§3.5-3)。
+     * 依存関係: [xExtentFreshness, yExtentFreshness, startLoop]
+     * クリーンアップ: 不要 (停止はループ自身とアンマウント副作用が担う)。
+     */
+    useEffect(() => {
+        const state = tapDragStateRef.current
+        if (!state.active || state.direction === 0) {
+            return
+        }
+        startLoop()
+    }, [xExtentFreshness, yExtentFreshness, startLoop])
+
+    /**
+     * Cancel path (a): the package-wide cancel event — UNCONDITIONAL reset.
+     * キャンセル系 (a): パッケージ全域のキャンセルイベント — 無条件リセット。
+     *
+     * ❗ 出荷済み hbar 意味論の継承: `ariaControls` を持たないバーはページ全域のキャンセルに
+     * 反応する (paneId フィルタなし)。統合サークルも一様に無条件 = 厳密 fail-closed。
+     *
+     * 目的: コンテンツパン等の外部操作でタップスクロールを止める。
+     * 依存関係: [resetTapScroll]
+     * クリーンアップ: リスナ解除。
+     */
+    useEffect(() => {
+        const handleTapScrollCancel = () => {
+            resetTapScroll()
+        }
+        window.addEventListener(TAP_SCROLL_CANCEL_EVENT, handleTapScrollCancel)
+        return () => {
+            window.removeEventListener(TAP_SCROLL_CANCEL_EVENT, handleTapScrollCancel)
+        }
+    }, [resetTapScroll])
+
+    /**
+     * Cancel path (b): document-capture pointerdown outside the circle (another pointer).
+     * キャンセル系 (b): サークル外の別ポインタによる document 捕捉 pointerdown。
+     *
+     * 目的: ドラッグ中の別指タッチで fail-closed に停止する (ScrollBar の双子)。
+     * 依存関係: [enabled, resetTapScroll]
+     * クリーンアップ: リスナ解除。
+     */
+    useEffect(() => {
+        if (!enabled) {
+            return
+        }
+        const handlePointerDown = (event: PointerEvent) => {
+            if (!tapDragStateRef.current.active) {
+                return
+            }
+            // ドラッグ中のポインター自身は無視 (通常はキャプチャ済みでここへ来ないが念のため)
+            if (tapDragStateRef.current.pointerId === event.pointerId) {
+                return
+            }
+            const targetNode = event.target
+            if (!(targetNode instanceof Node)) {
+                resetTapScroll()
+                return
+            }
+            const element = tapCircleHandleRef.current?.getElement()
+            if (element?.contains(targetNode)) {
+                return
+            }
+            resetTapScroll()
+        }
+        document.addEventListener("pointerdown", handlePointerDown, true)
+        return () => {
+            document.removeEventListener("pointerdown", handlePointerDown, true)
+        }
+    }, [enabled, resetTapScroll])
+
+    /**
+     * Cancel path (c): `enabled` → false resets; unmount stops the loop.
+     * キャンセル系 (c): `enabled` → false でリセット、アンマウントでループ停止。
+     *
+     * 目的: 無効化 / 退場時に rAF を残さない。
+     * 依存関係: [enabled, resetTapScroll] / [stopLoop]
+     * クリーンアップ: アンマウント時のループ停止。
+     */
+    useEffect(() => {
+        if (!enabled) {
+            resetTapScroll()
+        }
+    }, [enabled, resetTapScroll])
+    useEffect(() => {
+        return () => {
+            stopLoop()
+        }
+    }, [stopLoop])
+
+    return { isTapActive, handleTapCircleDragChange, tapCircleHandleRef }
+}