@aiquants/spreadsheet 0.8.0

package/src/selection/usePointDrag.ts

@@ -0,0 +1,273 @@
+/**
+ * @fileoverview Reference-drag owner for formula pointing (v0.8 plan §4.1.18 / design v5) — a
+ * DISTINCT drag owner beside useFillHandle with its own draggingRef, buildRange, pointer
+ * capture and autoscroller context. The cell engine consults `onPointerDown` BEFORE its
+ * commit gate; an accepted press inserts the pointed cell into the formula, captures the
+ * pointer on the body and thereafter replaces that token with the rectangle `press ∪ hover`
+ * on every rAF-coalesced move and every autoscroller tick (ONE construction point shared by
+ * both writers). The selection, anchor and active cell are frozen: this owner has no
+ * setSelection seam at all. Escape (`abortDrag`) restores the sink snapshot taken before the
+ * press — the token reverts, the editing session stays (cancelEdit is never called); the
+ * primary release / capture loss keep the last replaced token (`cleanupDrag`). The drag rect
+ * is painted through the root's onDragFrame relay, which reads the composite drag mode
+ * (`"point"` while this owner is in flight).
+ *
+ * 数式ポインティングの参照ドラッグ所有者 (v0.8 計画 §4.1.18 / 設計 v5) — useFillHandle の兄弟
+ * となる独立所有者で、自前の draggingRef / buildRange / pointer capture / autoscroller
+ * コンテキストを持つ。セルエンジンは commit ゲートより**先**に `onPointerDown` に諮る。受理
+ * された押下は指したセルを数式へ挿入し body へ capture、以後は rAF 合流の move と autoscroller
+ * の tick (両書き手が共有する単一構築点) のたびに矩形 `押下 ∪ hover` でそのトークンを置換する。
+ * 選択 / anchor / active は凍結 — この所有者は setSelection シームをそもそも持たない。Escape
+ * (`abortDrag`) は押下前のシンク断面を復元 (トークンは戻り、セッションは残る — cancelEdit は
+ * 呼ばない)。主ボタン解放 / capture 喪失は最後に置換したトークンを残す (`cleanupDrag`)。矩形は
+ * root の onDragFrame リレー経由で描く (リレーは合成ドラッグモードを読み、飛行中は "point")。
+ */
+
+import type { VirtualGridHandle } from "@aiquants/virtualscroll"
+import { type RefObject, useCallback, useEffect, useMemo, useRef } from "react"
+import type { SinkSnapshot } from "../editor/useCellEditor.ts"
+import type { AxisModel } from "../model/axisModel.ts"
+import { type CellCoord, type CellRange, makeRange } from "../model/cellCoord.ts"
+import type { ReferenceAxis } from "../model/formulaRefs.ts"
+import { type AutoScroller, SCROLLER_ARM_THRESHOLD } from "./useAutoScroller.ts"
+import { hitTestCell, type SelectionEngine } from "./useSelectionEngine.ts"
+
+type UsePointDragParams = {
+    /** Zoom scale reader (v0.3): client px = logical px × zoom — divide client deltas once at this boundary. / ズーム倍率 reader (v0.3)。client px = 論理 px × zoom — client 差分はこの境界で 1 回だけ除算する。 */
+    zoomRef: RefObject<number>
+    /** Rewire gate (empty grid) — also refuses presses while false. / 再結線ゲート (空グリッド) — false の間は押下も拒む。 */
+    enabled: boolean
+    bodyRef: RefObject<HTMLElement | null>
+    handleRef: RefObject<VirtualGridHandle | null>
+    rowAxis: AxisModel
+    colAxis: AxisModel
+    /** The editor's live pointing predicate (evaluated at the press — never cached here). / エディタの live ポインティング述語 (押下時に評価 — ここではキャッシュしない)。 */
+    getPointing: () => boolean
+    /** The editor's reference writer (insert at press, replace on every tick). / エディタの参照書込 (押下で挿入、tick ごとに置換)。 */
+    insertReference: (target: CellCoord | CellRange, axis: ReferenceAxis) => void
+    /** Sink snapshot taken before the press (null = no sink ⇒ the press is refused). / 押下前のシンク断面 (null = シンク不在 ⇒ 押下拒否)。 */
+    captureSink: () => SinkSnapshot | null
+    /** Escape restore of the pre-press snapshot. / Escape での押下前断面の復元。 */
+    restoreSink: (snapshot: SinkSnapshot) => void
+    focusSink: () => void
+    /** The dedicated both-axis edge scroller (the root's 6th useAutoScroller, writer = onDragFrame). / 専用の両軸端スクローラー (root の 6 台目、writer は onDragFrame)。 */
+    autoScroller: AutoScroller
+    /** Drag-rect writer relay (null hides the resident node); the relay stamps the composite mode. / ドラッグ矩形 writer リレー (null = 非表示)。モードはリレーが合成面から刻む。 */
+    onDragFrame: (range: CellRange | null) => void
+}
+
+/** The owner surface: the engine's composite shape plus the press entry the engine consults. / 所有者の面: エンジン合成面 + エンジンが諮る押下入口。 */
+export type PointDragOwner = SelectionEngine & {
+    /** Consulted by the cell engine before its commit gate; true = the press was consumed (selection frozen). / セルエンジンが commit ゲート前に諮る。true = 押下を消費 (選択凍結)。 */
+    onPointerDown: (event: PointerEvent) => boolean
+}
+
+/**
+ * Wires the reference-drag owner onto the body element (move / up / capture-loss listeners
+ * attach once; the press entry is called by the engine).
+ * body 要素へ参照ドラッグ所有者を結線する (move / up / capture 喪失リスナーは 1 回結線、押下
+ * 入口はエンジンが呼ぶ)。
+ */
+export const usePointDrag = (params: UsePointDragParams): PointDragOwner => {
+    // paramsRef パターン: リスナーは結線 1 回、最新パラメータはレンダー毎にここへ写す
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    const draggingRef = useRef(false)
+    /** Sink snapshot taken at the press (the Escape restore truth). / 押下時のシンク断面 (Escape 復元の真実)。 */
+    const snapshotRef = useRef<SinkSnapshot | null>(null)
+    const bodyRectRef = useRef<DOMRect | null>(null)
+    const pointerRef = useRef({ clientX: 0, clientY: 0 })
+    /** Press point for the scroller arming distance gate (the engine's twin). / スクローラー武装距離ゲート用の押下点 (エンジンの双子)。 */
+    const pressPointRef = useRef({ clientX: 0, clientY: 0 })
+    const dragRafRef = useRef<number | null>(null)
+    const capturedPointerRef = useRef<number | null>(null)
+    /** `buttons` reported by the press — the primary bit vanishing on a captured move is the chorded primary release (R4). / 押下時の `buttons` (主ビットの消失 = chord 中の主ボタン解放)。 */
+    const pressButtonsRef = useRef(0)
+    /** Per-drag range-building closure shared by the move rAF and the autoscroller tick (single construction point — it also performs the token replacement). / ドラッグ毎の矩形構築クロージャ (move rAF と tick の共有 — 単一構築点。トークン置換もここで行う)。 */
+    const buildRangeRef = useRef<((hover: CellCoord) => CellRange) | null>(null)
+    /** Pressed (pointed) cell — the rectangle anchor and the frozen home-territory anchor. / 押下 (指した) セル — 矩形の起点かつ凍結ホームテリトリーのアンカー。 */
+    const originRef = useRef<CellCoord | null>(null)
+    const scrollerArmedRef = useRef(false)
+
+    /** The engine's shared hit test over this owner's press-cached rect (ONE mapping — plan §4.1.18). / エンジンと共有のヒットテスト (当所有者の押下時計測 rect 上 — 単一写像、計画 §4.1.18)。 */
+    const hitTest = useCallback((clientX: number, clientY: number): CellCoord | null => {
+        const { handleRef, rowAxis, colAxis, zoomRef } = paramsRef.current
+        return hitTestCell(handleRef.current, bodyRectRef.current, rowAxis, colAxis, zoomRef.current, clientX, clientY)
+    }, [])
+
+    /** Idempotent cleanup: flags / snapshot / rAF / scroller / capture / drag rect — the last replaced token stays. / 冪等な後始末: フラグ / 断面 / rAF / スクローラー / capture / 矩形 — 最後に置換したトークンは残る。 */
+    const cleanupDrag = useCallback(() => {
+        const { autoScroller, bodyRef, onDragFrame } = paramsRef.current
+        draggingRef.current = false
+        snapshotRef.current = null
+        buildRangeRef.current = null
+        originRef.current = null
+        scrollerArmedRef.current = false
+        bodyRectRef.current = null
+        if (dragRafRef.current !== null) {
+            cancelAnimationFrame(dragRafRef.current)
+            dragRafRef.current = null
+        }
+        autoScroller.stop()
+        const body = bodyRef.current
+        if (body !== null && capturedPointerRef.current !== null && body.hasPointerCapture?.(capturedPointerRef.current)) {
+            body.releasePointerCapture(capturedPointerRef.current)
+        }
+        capturedPointerRef.current = null
+        // 参照矩形を hidden へ (常設ノード)
+        onDragFrame(null)
+    }, [])
+
+    /** Escape: restores the pre-press sink (token reverts) and cleans up — the session stays. / Escape: 押下前シンクを復元 (トークンが戻る) して後始末 — セッションは残る。 */
+    const abortDrag = useCallback(() => {
+        if (!draggingRef.current) {
+            return
+        }
+        const snapshot = snapshotRef.current
+        if (snapshot !== null) {
+            paramsRef.current.restoreSink(snapshot)
+        }
+        cleanupDrag()
+    }, [cleanupDrag])
+
+    const onPointerDown = useCallback(
+        (event: PointerEvent): boolean => {
+            const p = paramsRef.current
+            const body = p.bodyRef.current
+            // 述語はここでその場評価 (getCellFormula 未宣言なら必ず false = v0.7 恒等でエンジンへ素通し)
+            if (!p.enabled || body === null || !p.getPointing()) {
+                return false
+            }
+            // bodyRect は押下で 1 回計測しドラッグ中はキャッシュ (§6.4.3-3)
+            bodyRectRef.current = body.getBoundingClientRect()
+            const cell = hitTest(event.clientX, event.clientY)
+            if (cell === null) {
+                bodyRectRef.current = null
+                return false
+            }
+            // 断面はシンク不在なら取れない = セッション無し — 押下はエンジンへ返す
+            const snapshot = p.captureSink()
+            if (snapshot === null) {
+                bodyRectRef.current = null
+                return false
+            }
+            // 受理: 既定動作 (フォーカス移動 / テキスト選択) を止めシンクを保持したまま参照を挿入
+            event.preventDefault()
+            p.focusSink()
+            snapshotRef.current = snapshot
+            originRef.current = cell
+            p.insertReference(cell, "cells")
+            draggingRef.current = true
+            pointerRef.current = { clientX: event.clientX, clientY: event.clientY }
+            pressPointRef.current = { clientX: event.clientX, clientY: event.clientY }
+            capturedPointerRef.current = event.pointerId
+            pressButtonsRef.current = event.buttons
+            try {
+                // jsdom は合成イベントの pointerId で InvalidPointerId を投げうる — 実ブラウザでは成功。
+                // capture 失敗時も pointermove/up は body リスナーで受かるため機能劣化は端外 drop のみ
+                body.setPointerCapture(event.pointerId)
+            } catch {
+                capturedPointerRef.current = null
+            }
+            // 単一構築点: 矩形 = 押下セル ∪ hover。置換もここで行う (move rAF と tick が共有)
+            buildRangeRef.current = (hover) => {
+                const range = makeRange(cell, hover)
+                paramsRef.current.insertReference(range, "cells")
+                return range
+            }
+            // 押下時自己修復 (エンジンと同規約): 宙吊りジェスチャの旧スクローラーと stale 武装フラグを掃除
+            p.autoScroller.stop()
+            scrollerArmedRef.current = false
+            // 押下直後の参照矩形 (1×1) を描く
+            p.onDragFrame(makeRange(cell, cell))
+            return true
+        },
+        [hitTest],
+    )
+
+    const { enabled, bodyRef } = params
+    useEffect(() => {
+        const body = bodyRef.current
+        if (!enabled || body === null) {
+            return
+        }
+
+        /** Whether the event belongs to the pointer that started the drag (mouse-only on all phases — engine twin). / ドラッグを開始したポインタ本人か (全フェーズ mouse 限定 — エンジンの双子)。 */
+        const isOwnPointer = (event: PointerEvent): boolean => (capturedPointerRef.current !== null ? event.pointerId === capturedPointerRef.current : event.pointerType === "mouse")
+
+        const onPointerMove = (event: PointerEvent) => {
+            if (!(draggingRef.current && isOwnPointer(event))) {
+                return
+            }
+            pointerRef.current = { clientX: event.clientX, clientY: event.clientY }
+            // 距離ゲートつき武装 (エンジンと同じ SCROLLER_ARM_THRESHOLD — ジッタ 1 発では武装しない)
+            const buildRange = buildRangeRef.current
+            const origin = originRef.current
+            if (!scrollerArmedRef.current && buildRange !== null && origin !== null) {
+                const armDx = Math.abs(event.clientX - pressPointRef.current.clientX)
+                const armDy = Math.abs(event.clientY - pressPointRef.current.clientY)
+                if (Math.max(armDx, armDy) >= SCROLLER_ARM_THRESHOLD) {
+                    scrollerArmedRef.current = true
+                    paramsRef.current.autoScroller.start({ getPointerPosition: () => pointerRef.current, buildRange, anchorCol: origin.col, anchorRow: origin.row })
+                }
+            }
+            // rAF 合流で矩形 + トークン置換 (React 未介在)
+            if (dragRafRef.current === null) {
+                dragRafRef.current = requestAnimationFrame(() => {
+                    dragRafRef.current = null
+                    const build = buildRangeRef.current
+                    if (!draggingRef.current || build === null) {
+                        return
+                    }
+                    const hover = hitTest(pointerRef.current.clientX, pointerRef.current.clientY)
+                    if (hover !== null) {
+                        paramsRef.current.onDragFrame(build(hover))
+                    }
+                })
+            }
+            // chord 中の主ボタン解放 (R4 — エンジンと同型): 主ビットを失った own move は解放 = 確定
+            if ((pressButtonsRef.current & 1) !== 0 && (event.buttons & 1) === 0) {
+                cleanupDrag()
+            }
+        }
+
+        const onPointerUp = (event: PointerEvent) => {
+            // 主ボタンのリリースのみ確定 (最後の tick が既にトークンを置換済み — 書込は無い)
+            if (event.button !== 0 || !(draggingRef.current && isOwnPointer(event))) {
+                return
+            }
+            cleanupDrag()
+        }
+
+        const onLostPointerCapture = (event: PointerEvent) => {
+            // 所有 pointerId の capture 喪失 (ウィンドウ外 drop 等) は最後のトークンのまま終了
+            if (!draggingRef.current || capturedPointerRef.current === null || event.pointerId !== capturedPointerRef.current) {
+                return
+            }
+            cleanupDrag()
+        }
+
+        body.addEventListener("pointermove", onPointerMove)
+        body.addEventListener("pointerup", onPointerUp)
+        body.addEventListener("lostpointercapture", onLostPointerCapture)
+        return () => {
+            body.removeEventListener("pointermove", onPointerMove)
+            body.removeEventListener("pointerup", onPointerUp)
+            body.removeEventListener("lostpointercapture", onLostPointerCapture)
+            cleanupDrag()
+        }
+    }, [enabled, bodyRef, hitTest, cleanupDrag])
+
+    return useMemo(
+        () => ({
+            isDragging: () => draggingRef.current,
+            // 参照矩形は常に "point" (合成面 dragModeAny が飛行中だけこの値を overlay へ配る)
+            getDragMode: (): "add" | "subtract" | "point" => "point",
+            abortDrag,
+            cancelDrag: cleanupDrag,
+            onPointerDown,
+        }),
+        [abortDrag, cleanupDrag, onPointerDown],
+    )
+}