@aiquants/spreadsheet 0.8.0

package/src/header/useHeaderSelection.ts

@@ -0,0 +1,454 @@
+/**
+ * @fileoverview Header selection machine — the cell engine's "one-axis-pinned" application
+ * (§6.8-1/-2). One shared implementation, transposed by an axis argument; press composes the
+ * two reducers into ONE setSelection (no transient 1x1 leaks), header drags drive the
+ * axis-limited auto-scroller with span-promoted drag frames. A Ctrl-press on a fully-selected
+ * index enters the subtract RESERVATION (§3.3): nothing is written and nothing is delivered
+ * until either the up subtracts that index's full span or a pointer move that BOTH really
+ * changes the client coordinates AND lands on a different header index converts the gesture
+ * into the normal Ctrl append drag (in-index jitter keeps the reservation). Exposes the same isDragging/abortDrag surface as
+ * the cell engine so the Escape priority chain (§6.6.1) covers header drags too. Listeners
+ * are attached ONCE and read live params through a ref (paramsRef pattern) — effect re-runs
+ * mid-drag would call cleanupDrag and kill the drag. v0.8 (plan §4.2.9): while the editor is
+ * POINTING, a primary header press inserts the whole-axis reference (`A:A` / `1:1`) into the
+ * formula instead of selecting — no commit, no selection write, no drag; a capability param,
+ * absent = the v0.7 press path.
+ *
+ * ヘッダー選択機械 — セル版選択機械の「片軸全域固定」適用 (§6.8-1/-2)。axis 引数で転置する
+ * 共通実装。press は reducer 合成の setSelection 1 回 (過渡 1×1 を漏らさない)、ドラッグは
+ * 軸制限オートスクローラーをスパン昇格つき buildRange で駆動する。全スパン選択済み index への
+ * Ctrl+押下は減算予約 (§3.3) — up で全スパン帯を減算するか、実ポインタ移動で通常の Ctrl 追加
+ * ドラッグへ変換するまで無書込・無配送。Escape 優先順 (§6.6.1) がヘッダードラッグにも効くよう、
+ * セルエンジンと同じ isDragging / abortDrag 面を公開する。リスナーは 1 回だけ結線し、最新
+ * パラメータは ref 経由で読む。v0.8 (計画 §4.2.9): エディタがポインティング中の主ボタン
+ * ヘッダー押下は選択でなく全軸参照 (`A:A` / `1:1`) を数式へ挿入する — commit も選択書込も
+ * ドラッグも無し。能力 param で、不在 = v0.7 の押下経路。
+ */
+
+import type { VirtualGridHandle } from "@aiquants/virtualscroll"
+import { type RefObject, useCallback, useEffect, useMemo, useRef } from "react"
+import type { PointingSeams } from "../editor/useCellEditor.ts"
+import type { AxisModel } from "../model/axisModel.ts"
+import { type CellCoord, type CellRange, makeRange } from "../model/cellCoord.ts"
+import { viewportXToCol, viewportYToRow } from "../model/frozenPartition.ts"
+import { reduceSelectionExtend, reduceSelectionPress, reduceSelectionSubtract, type SelectionState } from "../selection/selectionState.ts"
+import { type AutoScroller, SCROLLER_ARM_THRESHOLD } from "../selection/useAutoScroller.ts"
+import type { SelectionEngine } from "../selection/useSelectionEngine.ts"
+
+type UseHeaderSelectionParams = {
+    /** 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: wiring sleeps while the grid is empty and re-attaches on the non-empty transition (§6.9-1 empty branch). / 空グリッド間は結線を眠らせ、非空遷移で再結線するゲート。 */
+    enabled: boolean
+    /** Header axis: "col" = column header (full-row span), "row" = row header (full-column span). / "col" = 列ヘッダー (全行スパン)、"row" = 行ヘッダー (全列スパン)。 */
+    axis: "col" | "row"
+    headerRef: RefObject<HTMLElement | null>
+    mainAxis: AxisModel
+    crossCount: number
+    handleRef: RefObject<VirtualGridHandle | null>
+    isEditing: () => boolean
+    requestCommit: () => boolean
+    getSelection: () => SelectionState
+    setSelection: (next: SelectionState) => void
+    focusSink: () => void
+    onDragFrame: (range: CellRange | null) => void
+    /** Axis-limited auto-scroller (columns = "x", rows = "y" — §6.8). / 軸制限つきオートスクローラー。 */
+    autoScroller: AutoScroller
+    /** §8.2 repaint edges: press-after-flag + cleanup-end. / §8.2 の repaint エッジ (press 直後 + cleanup 末尾)。 */
+    repaintOverlay: () => void
+    /**
+     * v0.8 capability (plan §4.2.9): the editor's pointing seams (live predicate + reference
+     * writer — the root wires them through refs because the editor is built after the header
+     * machines). Undefined = no pointing press path (v0.7 identity).
+     * v0.8 能力 (計画 §4.2.9): エディタのポインティングシーム (live 述語 + 参照書込 — エディタは
+     * ヘッダー機械より後に構築されるため root が ref 経由で結線)。undefined = ポインティング押下
+     * 経路なし (v0.7 恒等)。
+     */
+    pointing?: Pick<PointingSeams, "getPointing" | "insertReference">
+}
+
+/**
+ * Wires column/row header selection onto the band element. Returns the drag surface for the
+ * keyboard Escape split (same shape as the cell engine).
+ * ヘッダー帯へ列 / 行選択を結線し、Escape 分担用のドラッグ面 (セルエンジンと同形) を返す。
+ */
+export const useHeaderSelection = (params: UseHeaderSelectionParams): SelectionEngine => {
+    // paramsRef パターン: リスナーは結線 1 回、最新パラメータはレンダー毎にここへ写す
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    const draggingRef = useRef(false)
+    const dragBeforeRef = useRef<SelectionState | null>(null)
+    const anchorIndexRef = useRef(0)
+    const headerRectRef = useRef<DOMRect | null>(null)
+    const pointerRef = 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 span-building closure shared by the move rAF and the autoscroller tick (single construction point). / ドラッグ毎のスパン構築クロージャ (move rAF と tick の共有 — 単一構築点)。 */
+    const buildRangeRef = useRef<((hover: CellCoord) => CellRange) | null>(null)
+    /**
+     * Subtract-reservation flag (§3.3): a Ctrl+press on a fully-selected index writes NOTHING
+     * at press. Up with the reservation intact = subtract that index's full span; the FIRST
+     * hitIndex change WITH a real client-coordinate change converts to a normal Ctrl append
+     * drag (deferred press write). While reserved: no autoscroller, no drag-rect delivery.
+     * 減算予約フラグ (§3.3): 全スパン選択済み index への Ctrl+press は press 非書込。予約のまま
+     * up = 当該 index の全スパン帯を減算。初回 hitIndex 変化 + client 座標の実変化で通常の
+     * Ctrl 追加ドラッグへ変換 (遅延 press 書込)。予約中は autoscroller 停止・矩形無配送。
+     */
+    const subtractReservationRef = useRef(false)
+    /** Reserved press index ((a) subtract target / (b) conversion anchor seed). / 予約押下 index ((a) の減算対象 / (b) 変換時の anchor 種)。 */
+    const reservedIndexRef = useRef(0)
+
+    /** Band coordinate to main-axis index (columns add hx, rows add vy). / 帯座標 → 主軸 index (列は hx、行は vy を加算)。 */
+    const hitIndex = useCallback((clientX: number, clientY: number): number | null => {
+        const { axis, mainAxis, handleRef, zoomRef } = paramsRef.current
+        const rect = headerRectRef.current
+        if (rect === null || mainAxis.totalSize() === 0) {
+            return null
+        }
+        // ズーム境界 (v0.3): client 差分を z で 1 回だけ除算して論理 px へ。
+        // 位置は両軸ともハンドルの同期読み (§7-4 — ドラッグ中オートスクロールでも最新の hx で
+        // 着地列が決まる。旧 rAF 写像読みは列ヘッダー帯ドラッグの鮮度非対称の現存証拠だった)
+        const z = zoomRef.current
+        if (axis === "col") {
+            const hx = handleRef.current?.getScrollPosition().x ?? -1
+            if (hx < 0) {
+                return null
+            }
+            // 凍結パーティション逆写像 (v0.5 計画 §2) — 凍結ヘッダー帯上の押下は静的座標で解決
+            const frozenWidth = handleRef.current?.getFrozenSize().width ?? 0
+            return Math.min(Math.max(viewportXToCol(mainAxis, (clientX - rect.left) / z, hx, frozenWidth), 0), mainAxis.count - 1)
+        }
+        const vy = handleRef.current?.getScrollPosition().y ?? -1
+        if (vy < 0) {
+            return null
+        }
+        // 行ヘッダーも凍結パーティション逆写像 (v0.6 計画 §2 — 凍結行ヘッダー帯上の押下は静的解決)
+        const frozenHeight = handleRef.current?.getFrozenSize().height ?? 0
+        return Math.min(Math.max(viewportYToRow(mainAxis, (clientY - rect.top) / z, vy, frozenHeight), 0), mainAxis.count - 1)
+    }, [])
+
+    /** Index to axis-full span corner cells. / index → 片軸全域スパンの両端セル。 */
+    const spanCorners = useCallback((fromIndex: number, toIndex: number): { press: CellCoord; extend: CellCoord } => {
+        const { axis, crossCount } = paramsRef.current
+        if (axis === "col") {
+            return { press: { row: 0, col: fromIndex }, extend: { row: crossCount - 1, col: toIndex } }
+        }
+        return { press: { row: fromIndex, col: 0 }, extend: { row: toIndex, col: crossCount - 1 } }
+    }, [])
+
+    /**
+     * The §3.3 toggle predicate (operational): SOME SINGLE range is a full cross-axis span
+     * containing the index. A union-only cover or a partial-span selection stays "add" (v0.1).
+     * §3.3 の判定述語 (操作的定義): ある単一レンジが当該 index を含む全交差軸スパンであること。
+     * 合併でのみ覆われる場合や部分スパン選択は従来どおり追加。
+     */
+    const isIndexFullySelected = useCallback((state: SelectionState, index: number): boolean => {
+        const { axis, crossCount } = paramsRef.current
+        return state.ranges.some((range) =>
+            axis === "col" ? range.startRow === 0 && range.endRow === crossCount - 1 && index >= range.startCol && index <= range.endCol : range.startCol === 0 && range.endCol === crossCount - 1 && index >= range.startRow && index <= range.endRow,
+        )
+    }, [])
+
+    /** Scroller armed flag (armed after >= SCROLLER_ARM_THRESHOLD px of real movement; press-time self-heal resets it). / スクローラー武装フラグ (累計 SCROLLER_ARM_THRESHOLD px 以上の実移動で武装。押下時自己修復でリセット)。 */
+    const scrollerArmedRef = useRef(false)
+    /** Press point for the arming distance gate. / 武装距離ゲート用の押下点。 */
+    const scrollerPressPointRef = useRef({ clientX: 0, clientY: 0 })
+
+    /** Idempotent drag cleanup (the cell engine's §6.4.3-8 twin — resets the armed flag too). / 冪等な後始末 (セルエンジン §6.4.3-8 の双子 — 武装フラグもリセット)。 */
+    const cleanupDrag = useCallback(() => {
+        scrollerArmedRef.current = false
+        const { autoScroller, headerRef, onDragFrame } = paramsRef.current
+        draggingRef.current = false
+        dragBeforeRef.current = null
+        buildRangeRef.current = null
+        subtractReservationRef.current = false
+        reservedIndexRef.current = 0
+        if (dragRafRef.current !== null) {
+            cancelAnimationFrame(dragRafRef.current)
+            dragRafRef.current = null
+        }
+        autoScroller.stop()
+        const header = headerRef.current
+        if (header !== null && capturedPointerRef.current !== null && header.hasPointerCapture?.(capturedPointerRef.current)) {
+            header.releasePointerCapture(capturedPointerRef.current)
+        }
+        capturedPointerRef.current = null
+        onDragFrame(null)
+        // cleanup 末尾の repaint エッジ (§8.2)
+        paramsRef.current.repaintOverlay()
+    }, [])
+
+    /** Aborts an in-flight drag, restoring the pre-press state (§6.4.3-8 mirror). / 押下前復元つき中断。 */
+    const abortDrag = useCallback(() => {
+        if (!draggingRef.current) {
+            return
+        }
+        const before = dragBeforeRef.current
+        if (before !== null) {
+            paramsRef.current.setSelection(before)
+        }
+        cleanupDrag()
+    }, [cleanupDrag])
+
+    const { enabled, headerRef } = params
+    useEffect(() => {
+        const header = headerRef.current
+        // enabled は空グリッドの間 false — 非空遷移で deps が変わり、実 DOM が揃った後に再結線される
+        if (!enabled || header === null) {
+            return
+        }
+
+        const onPointerDown = (event: PointerEvent) => {
+            const p = paramsRef.current
+            if (event.pointerType !== "mouse") {
+                return
+            }
+            // 非主ボタン (ヘッダー右クリック = ネイティブメニュー素通し — ADR-9) も押下の既定動作
+            // (フォーカス移動) だけは止める: 止めないと root group へ逃げたフォーカスで右クリック後の
+            // キーボードが全滅する。ネイティブメニューは preventDefault でも届く (R2 是正)
+            if (event.button !== 0) {
+                event.preventDefault()
+                return
+            }
+            // 予約フラグの掃除は主ボタンゲート直後の最上流 (編集ゲート拒否 / hitIndex null で
+            // 中断される押下でも必ず走る — 宙吊りジェスチャ (capture 失敗 + 帯外リリース) の
+            // stale true が後続 up を予約分岐へ誤誘導し全スパン選択を Name Box 1×1 へ潰す事故の
+            // 閉塞。セル機械の subtractModeRef 掃除と同型)
+            subtractReservationRef.current = false
+            // ポインティング中のヘッダー押下は A:A / 1:1 の挿入 (Excel — v0.8 §4.2.9)。選択は動かさず
+            // commit もしない (能力分岐: 未配線 / 述語不成立は従来の押下経路へ)
+            if (p.pointing?.getPointing()) {
+                headerRectRef.current = header.getBoundingClientRect()
+                const pointedIndex = hitIndex(event.clientX, event.clientY)
+                if (pointedIndex === null) {
+                    return
+                }
+                event.preventDefault()
+                p.focusSink()
+                // 交差軸成分は formatRangeReference が読まない (列帯は列、行帯は行だけ) — 0 で座標化
+                p.pointing.insertReference(p.axis === "col" ? { row: 0, col: pointedIndex } : { row: pointedIndex, col: 0 }, p.axis === "col" ? "columns" : "rows")
+                return
+            }
+            // 編集中の requestCommit ゲート (§6.8-1 — ヘッダーはフォーカスが動かず focusout が
+            // 発火しないため、このゲートが編集確定の唯一の経路)。拒否時は preventDefault で押下の
+            // 既定フォーカス移動 (root group へ) を止める — セッション生存中は onRootFocus が
+            // 再進入 rearm をしないため、止めないとシンクへ Escape が届かない宙吊りになる
+            if (p.isEditing() && !p.requestCommit()) {
+                event.preventDefault()
+                p.focusSink()
+                return
+            }
+            headerRectRef.current = header.getBoundingClientRect()
+            const index = hitIndex(event.clientX, event.clientY)
+            if (index === null) {
+                return
+            }
+            event.preventDefault()
+            p.focusSink()
+            const state = p.getSelection()
+            dragBeforeRef.current = state
+            const append = event.ctrlKey || event.metaKey
+            if (event.shiftKey) {
+                // Shift+click: anchor の交差軸成分を全域へ昇格してから extend (部分高さ矩形を作らない —
+                // §6.8-1 の anchor 軸全域昇格。転置側は列成分 0 昇格)
+                const promotedAnchor: CellCoord = p.axis === "col" ? { row: 0, col: state.anchor.col } : { row: state.anchor.row, col: 0 }
+                const { extend } = spanCorners(index, index)
+                const promoted: SelectionState = { ...state, anchor: promotedAnchor }
+                p.setSelection(reduceSelectionExtend(promoted, extend))
+                anchorIndexRef.current = p.axis === "col" ? promotedAnchor.col : promotedAnchor.row
+            } else if (append && isIndexFullySelected(state, index)) {
+                // 減算予約モード (§3.3): press では書き込まない (単一書込規律の維持)。
+                // dragBeforeRef は上で捕捉済み — 変換後の Escape / lostpointercapture 復元が依存
+                subtractReservationRef.current = true
+                reservedIndexRef.current = index
+                anchorIndexRef.current = index
+            } else {
+                // press は reducer 合成の setSelection 1 回 (2 回呼びは過渡 1×1 が発火判定へ漏れる)
+                const { press, extend } = spanCorners(index, index)
+                const pressed = reduceSelectionPress(state, press, { extend: false, append })
+                p.setSelection(reduceSelectionExtend(pressed, extend))
+                anchorIndexRef.current = index
+            }
+            draggingRef.current = true
+            // press 直後の repaint エッジ (§8.2)
+            p.repaintOverlay()
+            pointerRef.current = { clientX: event.clientX, clientY: event.clientY }
+            capturedPointerRef.current = event.pointerId
+            pressButtonsRef.current = event.buttons
+            try {
+                // jsdom は合成イベントの pointerId で InvalidPointerId を投げうる — 実ブラウザでは成功。
+                // capture 失敗時も pointermove/up は帯リスナーで受かるため機能劣化は端外 drop のみ
+                header.setPointerCapture(event.pointerId)
+            } catch {
+                capturedPointerRef.current = null
+            }
+            // buildRange は hover の主軸成分だけを読んで片軸全域スパンへ昇格する (§6.8-1 —
+            // オートスクローラーの hover は body 基準のヒットテストで交差軸成分が無意味なため)。
+            // move rAF もこの 1 クロージャを共有する (単一構築点 — 二重実装のドリフト防止)
+            buildRangeRef.current = (hover) => {
+                const hoverIndex = paramsRef.current.axis === "col" ? hover.col : hover.row
+                const { press } = spanCorners(anchorIndexRef.current, anchorIndexRef.current)
+                const { extend } = spanCorners(anchorIndexRef.current, hoverIndex)
+                return makeRange(press, extend)
+            }
+            // スクローラーは押下では起動しない (累計 4px 以上の実移動で武装 — fill / セル
+            // エンジンと同ポリシー。押下起動は左ゾーン内の press だけで毎フレームのドレインに
+            // なり、凍結列ヘッダーのクリックが可動帯の勝手な左スクロールに化ける — R5 是正)。
+            // 減算予約中の非武装 (§3.3) も同じ「move まで待つ」構造に吸収される (変換は move 時)。
+            // 押下時自己修復 (subtractModeRef 規約): 宙吊りジェスチャの旧スクローラーと stale
+            // 武装フラグを毎押下で掃除する
+            p.autoScroller.stop()
+            scrollerArmedRef.current = false
+            scrollerPressPointRef.current = { clientX: event.clientX, clientY: event.clientY }
+        }
+
+        /**
+         * Whether the event belongs to the pointer that started the drag (mouse-only §6.4.1
+         * on all drag phases — see the cell engine's twin for the concurrency rationale).
+         * ドラッグを開始したポインタ本人か (mouse 限定契約を全フェーズで保つ — 根拠はセル
+         * エンジン側の同名ガード参照)。
+         */
+        const isOwnPointer = (event: PointerEvent): boolean => (capturedPointerRef.current !== null ? event.pointerId === capturedPointerRef.current : event.pointerType === "mouse")
+
+        const applyPointerMove = (event: PointerEvent) => {
+            if (!(draggingRef.current && isOwnPointer(event))) {
+                return
+            }
+            if (subtractReservationRef.current) {
+                // 変換判定 (§3.3): 初回 hitIndex 変化 **かつ** client 座標の実変化のみが引き金。
+                // 比較は pointerRef 更新前の既存値と行う — ホイール後にブラウザが静止カーソルへ
+                // 配送する合成 pointermove は clientX/Y 不変のため予約を維持する
+                const moved = event.clientX !== pointerRef.current.clientX || event.clientY !== pointerRef.current.clientY
+                pointerRef.current = { clientX: event.clientX, clientY: event.clientY }
+                if (!moved) {
+                    return
+                }
+                const hit = hitIndex(event.clientX, event.clientY)
+                if (hit === null || hit === reservedIndexRef.current) {
+                    return // index 不変の実移動は予約維持 (矩形も配送しない)
+                }
+                // 予約破棄 → 通常の Ctrl 追加ドラッグへ変換: press 時の追加合成を setSelection 1 回で
+                // 遅延実行し、autoscroller 起動 + 矩形配送を再開して v0.1 の up 確定フローへ合流
+                subtractReservationRef.current = false
+                const p = paramsRef.current
+                const { press, extend } = spanCorners(reservedIndexRef.current, reservedIndexRef.current)
+                const pressed = reduceSelectionPress(p.getSelection(), press, { extend: false, append: true })
+                p.setSelection(reduceSelectionExtend(pressed, extend))
+                // 変換はスクローラーを即武装しない (R6 是正): トラック境界に近い押下は 1〜2px の
+                // ジッタでも hitIndex が変わり変換が成立する — 武装だけは §4.2 の距離ゲートへ委ねる
+                // (押下点は予約押下で記録済み。閾値未達なら以後の move の通常ゲートが武装する)
+                const buildRange = buildRangeRef.current
+                const convDx = Math.abs(event.clientX - scrollerPressPointRef.current.clientX)
+                const convDy = Math.abs(event.clientY - scrollerPressPointRef.current.clientY)
+                if (buildRange !== null && Math.max(convDx, convDy) >= SCROLLER_ARM_THRESHOLD) {
+                    scrollerArmedRef.current = true
+                    p.autoScroller.start({ getPointerPosition: () => pointerRef.current, buildRange, anchorCol: p.axis === "col" ? anchorIndexRef.current : undefined, anchorRow: p.axis === "row" ? anchorIndexRef.current : undefined })
+                }
+            } else {
+                pointerRef.current = { clientX: event.clientX, clientY: event.clientY }
+                // 距離ゲートつき武装 (press 起動の廃止 + fill の FILL_ARM_THRESHOLD 双子 —
+                // R5 是正: ジッタ 1 発では武装させない)。列ヘッダー機械はアンカー列を
+                // ホームテリトリー規則へ渡す (行機械は縦専用で横駆動なし — 省略)
+                if (!scrollerArmedRef.current && buildRangeRef.current !== null) {
+                    const armDx = Math.abs(event.clientX - scrollerPressPointRef.current.clientX)
+                    const armDy = Math.abs(event.clientY - scrollerPressPointRef.current.clientY)
+                    if (Math.max(armDx, armDy) >= SCROLLER_ARM_THRESHOLD) {
+                        scrollerArmedRef.current = true
+                        paramsRef.current.autoScroller.start({
+                            getPointerPosition: () => pointerRef.current,
+                            buildRange: buildRangeRef.current,
+                            anchorCol: paramsRef.current.axis === "col" ? anchorIndexRef.current : undefined,
+                            anchorRow: paramsRef.current.axis === "row" ? anchorIndexRef.current : undefined,
+                        })
+                    }
+                }
+            }
+            if (dragRafRef.current === null) {
+                dragRafRef.current = requestAnimationFrame(() => {
+                    dragRafRef.current = null
+                    const buildRange = buildRangeRef.current
+                    if (!draggingRef.current || buildRange === null) {
+                        return
+                    }
+                    // hitIndex は主軸 index — buildRange は主軸成分しか読まないため転置座標で包んで渡す
+                    const hover = hitIndex(pointerRef.current.clientX, pointerRef.current.clientY)
+                    if (hover !== null) {
+                        paramsRef.current.onDragFrame(buildRange(paramsRef.current.axis === "col" ? { row: 0, col: hover } : { row: hover, col: 0 }))
+                    }
+                })
+            }
+        }
+
+        const onPointerMove = (event: PointerEvent) => {
+            applyPointerMove(event)
+            // chord 中の主ボタン解放 (R4 是正 — セル機械と同型): 主ビットを失った own move で確定する
+            if (draggingRef.current && isOwnPointer(event) && (pressButtonsRef.current & 1) !== 0 && (event.buttons & 1) === 0) {
+                confirmAt(event)
+            }
+        }
+
+        const onPointerUp = (event: PointerEvent) => {
+            // 主ボタンのリリースのみ確定 (非主ボタンの up は同一 pointerId で isOwnPointer を通過
+            // してしまう — セル機械と同じ閉塞。右リリースでの早期確定 / 宙吊り誤確定の両遮断)
+            if (event.button !== 0 || !(draggingRef.current && isOwnPointer(event))) {
+                return
+            }
+            confirmAt(event)
+        }
+
+        /** Confirms the in-flight gesture at the event position (primary release — pointerup or chorded move). / 飛行中ジェスチャの確定 (主ボタン解放 — pointerup または chord 中の move)。 */
+        const confirmAt = (event: PointerEvent) => {
+            const p = paramsRef.current
+            if (subtractReservationRef.current) {
+                // (a) 予約のまま up → 押下 index の全スパン帯を減算 (書込 1 回)。判定は up 時点の
+                // 予約フラグ — ホイールで hitIndex が動いても予約は維持され押下 index を減算する
+                // (§3.3)。pressCell = Name Box セル ({0, col} / {row, 0}) = スパンの press 隅
+                const { press, extend } = spanCorners(reservedIndexRef.current, reservedIndexRef.current)
+                p.setSelection(reduceSelectionSubtract(p.getSelection(), makeRange(press, extend), press))
+                cleanupDrag()
+                return
+            }
+            const hover = hitIndex(event.clientX, event.clientY)
+            if (hover !== null) {
+                const { extend } = spanCorners(anchorIndexRef.current, hover)
+                p.setSelection(reduceSelectionExtend(p.getSelection(), extend))
+            }
+            cleanupDrag()
+        }
+
+        const onLostPointerCapture = (event: PointerEvent) => {
+            // capture 喪失 (ウィンドウ外 drop 等) は押下前状態へ復元 (§6.4.3-8 のミラー)。所有
+            // pointerId 限定 — 他ポインタ (touch 等) の capture 解放で巻き戻さない
+            if (!draggingRef.current || capturedPointerRef.current === null || event.pointerId !== capturedPointerRef.current) {
+                return
+            }
+            abortDrag()
+        }
+
+        header.addEventListener("pointerdown", onPointerDown)
+        header.addEventListener("pointermove", onPointerMove)
+        header.addEventListener("pointerup", onPointerUp)
+        header.addEventListener("lostpointercapture", onLostPointerCapture)
+        return () => {
+            header.removeEventListener("pointerdown", onPointerDown)
+            header.removeEventListener("pointermove", onPointerMove)
+            header.removeEventListener("pointerup", onPointerUp)
+            header.removeEventListener("lostpointercapture", onLostPointerCapture)
+            cleanupDrag()
+        }
+    }, [enabled, headerRef, hitIndex, spanCorners, cleanupDrag, abortDrag])
+
+    return useMemo(
+        () => ({
+            isDragging: () => draggingRef.current,
+            // ヘッダー面の減算は予約方式で矩形を配送しない (§3.3) — 配送モードは常に加算
+            getDragMode: (): "add" | "subtract" | "point" => "add",
+            abortDrag,
+            cancelDrag: cleanupDrag,
+        }),
+        [abortDrag, cleanupDrag],
+    )
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+/**
+ * @aiquants/spreadsheet
+ *
+ * Excel-grade spreadsheet grid for React on top of @aiquants/virtualscroll.
+ * @aiquants/virtualscroll 上に構築する React 用 Excel 級スプレッドシートグリッド。
+ *
+ * The public surface (§6.11 + the named unions SpreadsheetDirection / SpreadsheetOperation,
+ * extended by the v0.8 rich-cell vocabulary — plan §1.11). Internal hooks
+ * (useSelectionEngine / useGridKeyboard / useCellEditor / useClipboard / useCommands /
+ * usePopovers etc.) stay private — exporting them would freeze their parameter shapes. The
+ * pure engines (clipboard TSV / payload / HTML interop, cell format canonicalisation,
+ * validation, formula reference rewriting, chord parsing, labels) are exported as the reuse
+ * surface for consumers building their own paste UIs, toolbars, import features or popovers.
+ *
+ * Nameability rule (spec 00 §5): every own named type that an exported declaration reaches —
+ * parameter / return annotations, union arms, property types — is exported as well, so a
+ * consumer can spell it by name instead of extracting it with `Awaited<ReturnType<>>` /
+ * indexed access / `Extract<>` (v0.7 precedent ScrollToCellOptions / EditRejection).
+ * api-extractor rolls an unexported referenced type up as a bare local `declare type`, so the
+ * build stays green while the name is unreachable from the package (TS2459) — `index.spec.ts`
+ * is the machine gate. The single exception is the test-only seam SpreadsheetTestProps
+ * (spec 00 §5.2).
+ *
+ * 公開面 (§6.11 + 名前つき union SpreadsheetDirection / SpreadsheetOperation に v0.8 のリッチセル
+ * 語彙を加えたもの — 計画 §1.11)。内部フック (useSelectionEngine / useGridKeyboard / useCellEditor /
+ * useClipboard / useCommands / usePopovers 等) は公開しない — 公開した瞬間に引数形が凍結される。
+ * 純関数エンジン (クリップボードの TSV / payload / HTML 相互運用、書式の正準化、検証、数式参照の
+ * 書換え、チョード解析、ラベル) はコンシューマーが独自の貼り付け UI・ツールバー・インポート機能・
+ * ポップオーバーを組むための再利用面として公開する。
+ *
+ * 名指し可能性の規則 (分冊 00 §5): 公開宣言から到達する自前の名前つき型 (引数 / 戻り値注釈、union の
+ * 腕、プロパティ型) は全て export する — consumer が `Awaited<ReturnType<>>` / indexed access /
+ * `Extract<>` 抽出を強いられない (v0.7 の ScrollToCellOptions / EditRejection の前例)。api-extractor は
+ * 未公開の参照型をローカル `declare type` として同梱するのでビルドは緑のまま名前だけが到達不能
+ * (TS2459) になる — 機械ゲートは `index.spec.ts`。唯一の例外はテスト専用シーム SpreadsheetTestProps
+ * (分冊 00 §5.2)。
+ */
+
+export { type ClipCell, type ClipChannel, type ClipComment, type ClipFlavours, type ClipPayload, type ClipSource, detectClipSource, parseClipPayload, serializeClipPayload } from "./clipboard/clipPayload.ts"
+export { type HtmlTableKind, type HtmlTableResult, parseHtmlTable, serializeHtmlTable } from "./clipboard/htmlInterop.ts"
+// parseHtmlTable の第 3 引数型 — 復号器のホスト宣言 (codec 本体は非公開のまま、引数型だけ名指しできるようにする)
+export type { NumberFormatDecodeOptions } from "./clipboard/numberFormatCodec.ts"
+export type { PasteMode, PasteOperation, PasteOptions } from "./clipboard/pasteSpecial.ts"
+export { estimatePasteCellCount, expandPaste } from "./clipboard/tiling.ts"
+export { parseTsv, serializeTsv } from "./clipboard/tsv.ts"
+export type { ClipInfo, PasteOutcome } from "./clipboard/useClipboard.ts"
+export type { BorderPreset } from "./commands/useCommands.ts"
+// renderCell の ctx 型 — prop が公開面にある以上、その引数型も名指しできなければならない
+// (未公開だと consumer は Parameters<...> 抽出を強いられる)。型のみの追加で非破壊
+export type { RenderCellContext } from "./grid/CellView.tsx"
+export { columnIndexToName, columnNameToIndex } from "./header/columnName.ts"
+export { DEFAULT_SHORTCUTS, type ParsedChord, parseChord, type ShortcutMap, type ShortcutOverrides, SPREADSHEET_RESERVED_SHORTCUTS, type SpreadsheetCommand } from "./keyboard/shortcuts.ts"
+export { type CellComment, type CellCommentInput, normalizeHyperlink } from "./model/cellAnnotations.ts"
+export { type CellCoord, type CellRange, enumerateRangeCells, makeRange, rangeContains, rangeSize, type SpreadsheetDirection, type SpreadsheetOperation } from "./model/cellCoord.ts"
+// 表示形式 (v0.7) + リッチ書式 (v0.8): getCellFormat 能力の型 + 純関数エンジン (整形 / 正準化 / 合成 —
+// 組み込みだが consumer が直接呼べるよう公開: renderCell 内の再利用、ツールバー、独自整形の基盤)
+export {
+    BORDER_DEFAULT_COLOR,
+    type CellAlign,
+    type CellBorder,
+    type CellBorderStyle,
+    type CellBorders,
+    type CellFormat,
+    type CellFormatPatch,
+    type CellValueFormat,
+    type CellVerticalAlign,
+    canonicalizeFormat,
+    formatCellValue,
+    formatEquals,
+    mergeFormat,
+} from "./model/cellFormat.ts"
+// 条件付き書式の語彙 — 規則 / 入力 / スタイルに加え、CfCondition の 6 つの腕と text 条件の op 語彙も名指しできる
+export type {
+    CellValueCondition,
+    CfCondition,
+    CfTextOp,
+    ColorScaleCondition,
+    CompareOp,
+    ConditionalFormatRule,
+    ConditionalFormatRuleInput,
+    ConditionalFormatStyle,
+    CustomFormulaCondition,
+    EmptyCondition,
+    FormulaValue,
+    NotEmptyCondition,
+    RangeExtrema,
+    ScalePoint,
+    TextCondition,
+} from "./model/conditionalFormat.ts"
+export type { CellEdit, CellPatch, EditContext, EditRejection, EditSource, PasteEditContext, PlainEditContext, SpreadsheetDataAdapter } from "./model/dataAdapter.ts"
+// データ検証の語彙 — 規則 union / 判定に加え、共通オプション・7 つの腕・op 語彙・validateCellText の評価器型も名指しできる
+export {
+    type CheckboxValidationRule,
+    type CustomValidationRule,
+    type DataValidationRule,
+    type DateValidationRule,
+    type ListValidationRule,
+    type NumberValidationRule,
+    type TextLengthValidationRule,
+    type TextValidationRule,
+    type ValidationCompareOp,
+    type ValidationEvaluate,
+    type ValidationRuleBase,
+    type ValidationTextOp,
+    type ValidationVerdict,
+    validateCellText,
+} from "./model/dataValidation.ts"
+export { fromR1C1, shiftFormula, toR1C1 } from "./model/formulaRefs.ts"
+export { DEFAULT_LABELS, resolveLabel, type SpreadsheetLabelOverrides, type SpreadsheetLabels } from "./model/labels.ts"
+export { DEFAULT_HIGHLIGHT_COLORS, type HighlightColors, type HighlightState } from "./overlay/SelectionOverlay.tsx"
+// 既定ポップオーバー 6 種 — renderPopover の部品 (kind 別に差し替え、残りは既定を組み合わせる)
+export { CommentPopover, type CommentPopoverProps } from "./popover/CommentPopover.tsx"
+export { LinkPopover, type LinkPopoverProps } from "./popover/LinkPopover.tsx"
+export { ListPopover, type ListPopoverProps } from "./popover/ListPopover.tsx"
+export { MessagePopover, type MessagePopoverProps } from "./popover/MessagePopover.tsx"
+export { NotePopover, type NotePopoverProps } from "./popover/NotePopover.tsx"
+export { NoteTip, type NoteTipProps } from "./popover/NoteTip.tsx"
+// PopoverContext.anchorRect の型 (層座標系の矩形) — 配置エンジン placePopover 本体は非公開のまま
+export type { PopoverRect } from "./popover/placement.ts"
+export type { CommentPopoverContext, LinkPopoverContext, ListPopoverContext, MessagePopoverContext, NotePopoverContext, NoteTipContext, PopoverContext, PopoverKind, PopoverOverrides } from "./popover/usePopovers.ts"
+export { DEFAULT_CUSTOM_COLORS, type ScrollToCellOptions, Spreadsheet, type SpreadsheetHandle, type SpreadsheetProps } from "./Spreadsheet.tsx"
+export type { SelectionState } from "./selection/selectionState.ts"

package/src/keyboard/compositionGuard.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview IME composition keydown guard (v0.8 §4.1.10) — the single source of truth
+ * for the "must this keydown be ignored?" question that the grid keymap and every popover
+ * keydown handler ask first. Two clauses, extracted verbatim from useGridKeyboard: (1) a
+ * keydown that arrives DURING composition (isComposing, or the legacy keyCode 229 that
+ * Chromium / Safari deliver for IME-processed keys) is never a command; (2) Safari fires
+ * compositionend BEFORE the confirming Enter / Escape keydown, so those two keys are skipped
+ * inside a 50 ms window after the last compositionend. The window is deliberately limited to
+ * Enter / Escape — applying it to every key would eat the first post-confirmation keystroke on
+ * Chrome / Firefox, a measured regression.
+ *
+ * IME 変換中 keydown ガード (v0.8 §4.1.10) — グリッドキーマップと全ポップオーバーの keydown が
+ * 冒頭で問う「この keydown は無視すべきか」の単一真実源。useGridKeyboard から逐語抽出した 2 条:
+ * (1) 変換中の keydown (isComposing、または Chromium / Safari が IME 処理キーへ与えるレガシー
+ * keyCode 229) はコマンドではない、(2) Safari は確定 Enter / Escape の keydown より先に
+ * compositionend を発火するため、直近 compositionend から 50 ms 窓内の Enter / Escape をスキップ。
+ * 窓の対象を Enter / Escape に限定するのは必須 — 全キー対象にすると Chrome / Firefox で確定後の
+ * 1 打鍵を食う退行 (実測)。
+ */
+
+/** Safari compositionend→keydown skip window in ms. / Safari 順序差スキップ窓 (ms)。 */
+export const COMPOSITION_SKIP_WINDOW_MS = 50
+
+/**
+ * Guard-clear insurance timer in ms: the compositionend stamp is dropped after this delay
+ * (a setTimeout(0) clear is task-boundary dependent and can erase the stamp before the
+ * skipped keydown arrives). Must exceed COMPOSITION_SKIP_WINDOW_MS.
+ * ガード解除の保険タイマ (ms)。compositionend の刻印はこの遅延後に破棄 (setTimeout(0) は
+ * タスク境界依存でスキップ対象の keydown より先に刻印が消え得る)。COMPOSITION_SKIP_WINDOW_MS
+ * より長いことが必須。
+ */
+export const COMPOSITION_CLEAR_MS = 100
+
+/**
+ * True when the keydown must be ignored: isComposing / keyCode 229, or Enter / Escape within
+ * COMPOSITION_SKIP_WINDOW_MS after the last compositionend (`compositionEndedAt` is that
+ * event's timeStamp, or null when no compositionend is pending). Pure — reads only the event.
+ * 無視すべき keydown なら true: isComposing / keyCode 229、または直近 compositionend
+ * (`compositionEndedAt` = その timeStamp、未保留なら null) から COMPOSITION_SKIP_WINDOW_MS
+ * 以内の Enter / Escape。純関数 — event しか読まない。
+ */
+export const isCompositionKeydown = (event: KeyboardEvent, compositionEndedAt: number | null): boolean => {
+    // 変換中の keydown と IME 処理キー (keyCode 229) は無条件に無視 (§6.6.2-1 の冒頭ガード)
+    if (event.isComposing || event.keyCode === 229) {
+        return true
+    }
+    // Safari 順序差: compositionend 直後 (< 50ms) の Enter / Escape のみスキップ (対象限定必須 —
+    // 全キー対象にすると Chrome / Firefox で確定後の 1 打鍵を食う退行になる)
+    if ((event.key === "Enter" || event.key === "Escape") && compositionEndedAt !== null) {
+        return event.timeStamp - compositionEndedAt < COMPOSITION_SKIP_WINDOW_MS
+    }
+    return false
+}