@aiquants/spreadsheet 0.8.0

package/src/popover/usePopovers.ts

@@ -0,0 +1,642 @@
+/**
+ * @fileoverview Popover state machine (v0.8 §1.8 / §4.1.15 — ADR-15 interactive layer): the
+ * six popover kinds (note editor, hover note tip, comment thread, hyperlink editor, validation
+ * list picker, validation message) over the TWO resident anchors the overlay positions
+ * (`interactive` = note / comment / link / list / message, `tip` = note-tip). The hook owns:
+ * the layer derivation `layerEnabled = ∃K: popovers[K] !== false ∧ capability(K)` (a v0.7
+ * adapter with default props mounts NOTHING), the open / close / rejected transitions (a
+ * rejected `annotate` commit keeps the popover open with `rejected: true`; Ctrl+Enter retries;
+ * Escape in the rejected state closes without saving — both live in the default components),
+ * the commit gate before an interactive kind opens (`isEditing() && !requestCommit()` ⇒ abort),
+ * the focus return on close (`focusSink({ preventScroll: true })` + `rearmSink` when idle), the
+ * priority "open editor > validation message", the hover note tip (rAF-coalesced hit test on
+ * the body — the client point is queued and resolved once per frame —, `shouldShowNoteTip` —
+ * never while any drag incl. the reference drag is in flight, 150 ms leave grace, hoverable — a
+ * body `pointerleave` that is the other face of entering the tip frame starts no grace —,
+ * Escape chain step 0 `hideTip` — a re-show needs a cell CHANGE
+ * (the predicate's prev / next), so the tip stays hidden while the pointer rests on the cell —,
+ * sink `aria-describedby` while the hovered cell is active — an invariant, not an edge: it is
+ * re-evaluated by `syncTipAriaDescribedBy` on tip show / hide AND on every active-cell change
+ * (the root's active effect calls it), so arrowing away unbinds and arrowing onto the hovered
+ * cell binds —) and the
+ * IME guard the layer applies to every popover keydown (`isCompositionKeydown`). No DOM is
+ * rendered here — PopoverLayer.tsx renders from `context` / `tipContext` (lazy mount).
+ *
+ * ポップオーバー状態機械 (v0.8 §1.8 / §4.1.15 — ADR-15 対話層)。6 種 (note エディタ / ホバー
+ * note tip / コメントスレッド / ハイパーリンクエディタ / 検証リスト / 検証メッセージ) を overlay が
+ * 配置する 2 つの常設アンカー (`interactive` = note / comment / link / list / message、`tip` =
+ * note-tip) の上に載せる。本フックの所有: 層の導出 `layerEnabled = ∃K: popovers[K] !== false ∧
+ * capability(K)` (v0.7 アダプタ + 既定 props は何もマウントしない)、開閉 / 拒否遷移 (annotate の
+ * commit 拒否は `rejected: true` で開いたまま — Ctrl+Enter 再試行 / 拒否状態の Escape は保存せず
+ * 閉じる、いずれも既定コンポーネント側)、対話 kind を開く前の commit ゲート (`isEditing() &&
+ * !requestCommit()` ⇒ 中断)、閉じたときのフォーカス復帰 (`focusSink({ preventScroll: true })` +
+ * idle なら `rearmSink`)、優先順「開いているエディタ > 検証メッセージ」、ホバー note tip (body 上の
+ * rAF 合流ヒットテスト — client 座標を積みフレーム毎に 1 回解決 —、`shouldShowNoteTip` — 参照ドラッグ
+ * 含むドラッグ飛行中は表示しない、150 ms 離脱猶予、ホバー可 — tip フレーム進入の裏面である body の
+ * pointerleave は猶予を始めない —、Escape チェーン step 0 の `hideTip` — 再表示にはセル**変化** (述語の prev /
+ * next) が要るのでポインタがそのセルに留まる間は消えたまま —、ホバーセルが active の**間**シンクへ
+ * `aria-describedby` — エッジでなく不変条件: `syncTipAriaDescribedBy` が tip の表示 / 消灯と active セル
+ * 変化 (root の active 効果が呼ぶ) のたびに再評価し、離れれば外し、ホバー中セルへ乗れば結ぶ —)、
+ * 層が全 popover keydown に掛ける
+ * IME ガード (`isCompositionKeydown`)。DOM は描かない — PopoverLayer.tsx が `context` /
+ * `tipContext` から遅延マウントする。
+ */
+
+import type { VirtualGridHandle } from "@aiquants/virtualscroll"
+import { type RefObject, useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
+import { isCompositionKeydown } from "../keyboard/compositionGuard.ts"
+import type { AxisModel } from "../model/axisModel.ts"
+import { type CellComment, type CellCommentInput, normalizeAdapterHyperlink, normalizeHyperlink } from "../model/cellAnnotations.ts"
+import { type CellCoord, clampCoord, coordEquals } from "../model/cellCoord.ts"
+import type { CellEdit, EditRejection, SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
+import { colToViewportX, rowToViewportY, viewportXToCol, viewportYToRow } from "../model/frozenPartition.ts"
+import { resolveLabel, type SpreadsheetLabels } from "../model/labels.ts"
+import { NOTE_TIP_LEAVE_GRACE_MS, type PopoverRect, shouldShowNoteTip } from "./placement.ts"
+
+/** The six popover kinds (v0.8 §1.8). / 6 種のポップオーバー (v0.8 §1.8)。 */
+export type PopoverKind = "note" | "note-tip" | "comment" | "link" | "list" | "message"
+
+/** Every kind in declaration order (the layer derivation iterates it). / 宣言順の全 kind (層の導出が走査)。 */
+export const POPOVER_KINDS: readonly PopoverKind[] = ["note", "note-tip", "comment", "link", "list", "message"]
+
+/** The `popovers` prop: `false` disables a kind (its commands pass through, `openPopover` throws). / `popovers` prop: `false` はその kind を無効化 (コマンドは素通し、`openPopover` は RangeError)。 */
+export type PopoverOverrides = { readonly [K in PopoverKind]?: boolean }
+
+/** Note editor context (v0.8 §1.8). `current` undefined = no note yet; `commit(null)` clears. / note エディタ文脈。current undefined = ノートなし、commit(null) は消去。 */
+export type NotePopoverContext = { kind: "note"; cell: CellCoord; anchorRect: PopoverRect; current: string | undefined; commit: (next: string | null) => void; close: () => void; rejected: boolean }
+
+/** Hover note tip context (read-only). / ホバー note tip 文脈 (読み取り専用)。 */
+export type NoteTipContext = { kind: "note-tip"; cell: CellCoord; anchorRect: PopoverRect; current: string; close: () => void }
+
+/** Comment thread context: the reply UI commits `[...current (with ids), { text }]`; `null` clears the thread. / コメントスレッド文脈: 返信 UI は `[...current (id つき), { text }]` を commit、null はスレッド消去。 */
+export type CommentPopoverContext = { kind: "comment"; cell: CellCoord; anchorRect: PopoverRect; current: readonly CellComment[]; commit: (next: readonly CellCommentInput[] | null) => void; close: () => void; rejected: boolean }
+
+/** Hyperlink editor context: `url` on commit is a normalised href or null (clear); `canOpen` = onHyperlinkOpen declared. / ハイパーリンクエディタ文脈: commit の url は正規化済み href か null (消去)、canOpen = onHyperlinkOpen 宣言。 */
+export type LinkPopoverContext = { kind: "link"; cell: CellCoord; anchorRect: PopoverRect; current: { text: string; url: string | undefined }; commit: (next: { text: string; url: string | null }) => void; close: () => void; canOpen: boolean; open: () => void; rejected: boolean }
+
+/** Validation list picker context: `current` = the list rule's values, `typed` = the prefix that opened it. / 検証リスト文脈: current = list 規則の値、typed = 開いたときの入力プレフィックス。 */
+export type ListPopoverContext = { kind: "list"; cell: CellCoord; anchorRect: PopoverRect; current: readonly string[]; typed: string; commit: (value: string) => void; close: () => void }
+
+/** Validation message context (input message or a strict rejection). / 検証メッセージ文脈 (入力メッセージまたは strict 拒否)。 */
+export type MessagePopoverContext = { kind: "message"; cell: CellCoord; anchorRect: PopoverRect; current: { title: string; message: string; rejected: boolean }; close: () => void }
+
+/** The discriminated popover context handed to `renderPopover` / the default components (v0.8 §1.8). / renderPopover / 既定コンポーネントへ渡す判別文脈 (v0.8 §1.8)。 */
+export type PopoverContext = NotePopoverContext | NoteTipContext | CommentPopoverContext | LinkPopoverContext | ListPopoverContext | MessagePopoverContext
+
+/** Extra inputs of `open` (list: typed prefix; message: an explicit text, e.g. a strict-rejection verdict). / `open` の追加入力 (list: 入力プレフィックス、message: 明示テキスト — strict 拒否の判定文など)。 */
+export type PopoverOpenOptions = { typed?: string; message?: string; rejected?: boolean }
+
+/** Which cell each resident anchor sits on (null = hidden); written here, read by the overlay's repaintOverlay. / 各常設アンカーの載るセル (null = 非表示)。ここが書き、overlay の repaintOverlay が読む。 */
+export type PopoverAnchorState = { interactive: CellCoord | null; tip: CellCoord | null }
+
+/** The popover surface consumed by the layer, the keyboard (Escape chain), the commands and the handle. / 層 / キーボード (Escape チェーン) / コマンド / handle が消費する面。 */
+export type PopoverController = {
+    /** §1.8 derivation: some kind is enabled AND its adapter capability is declared. / §1.8 の導出: 有効かつ能力宣言済みの kind が 1 つでもある。 */
+    layerEnabled: boolean
+    /** Per-kind enablement (popovers[kind] !== false AND capability declared). / kind 別の有効判定。 */
+    isKindEnabled: (kind: PopoverKind) => boolean
+    /** Opens a kind on the ACTIVE cell; RangeError when the kind is disabled or its capability undeclared. / active セルで kind を開く。無効 / 能力未宣言は RangeError。 */
+    open: (kind: PopoverKind, options?: PopoverOpenOptions) => void
+    /** Closes the interactive popover (idempotent) and returns focus to the sink. / 対話ポップオーバーを閉じ (冪等) シンクへフォーカスを返す。 */
+    close: () => void
+    /** The open interactive kind or null. / 開いている対話 kind か null。 */
+    isOpen: () => PopoverKind | null
+    /** rAF-coalesced hover entry for the note tip by cell (null = pointer left the cells); the body's own pointermove path queues the client point and hit-tests inside the frame. / note tip のセル指定ホバー入口 (rAF 合流。null = セル領域から離脱)。body の pointermove 経路は client 座標を積みフレーム内でヒットテストする。 */
+    onCellHover: (cell: CellCoord | null) => void
+    /** Escape chain step 0: hides a visible tip (true; false when none) — it stays hidden until the pointer moves to ANOTHER cell (a re-show needs a cell change). / Escape チェーン step 0: 可視 tip を消灯 (true、無ければ false) — 再表示にはセル変化が要るので別セルへ移るまで消えたまま。 */
+    hideTip: () => boolean
+    /** Pointer entered the tip element — marks the tip hovered (the body's same-task `pointerleave` then starts no grace) and cancels a running grace (hoverable tip). / tip 要素へのポインタ進入 — tip ホバー中と記し (同一タスクの body pointerleave は猶予を始めない)、走っている猶予を取り消す (ホバー可)。 */
+    onTipPointerEnter: () => void
+    /** Pointer left the tip element — clears the hovered mark and starts the leave grace. / tip 要素からのポインタ離脱 — ホバー中の記しを外し離脱猶予を開始。 */
+    onTipPointerLeave: () => void
+    /** Re-evaluates the "sink aria-describedby while the hovered cell is active" invariant (bind when the visible tip's cell IS active, unbind own binding otherwise); the root calls it on every active-cell change. / 「ホバーセルが active の間シンクへ aria-describedby」不変条件の再評価 (可視 tip のセルが active なら結び、でなければ自分の結合だけ外す)。root が active セル変化のたびに呼ぶ。 */
+    syncTipAriaDescribedBy: () => void
+    /** The interactive popover context (React state — lazy mount) or null. / 対話ポップオーバー文脈 (React state — 遅延マウント) か null。 */
+    context: PopoverContext | null
+    /** The hover tip context or null. / ホバー tip 文脈か null。 */
+    tipContext: NoteTipContext | null
+    /** compositionend registration for the IME guard. / IME ガード用の compositionend 登録。 */
+    registerCompositionEnd: (timeStamp: number) => void
+    /** True when a keydown is an IME artefact (the layer swallows it before any popover handler). / keydown が IME 由来なら true (層が popover ハンドラより先に握り潰す)。 */
+    isCompositionKey: (event: KeyboardEvent) => boolean
+    /** The layer's usable size (grid viewport, logical px) for placement. / 配置用の層サイズ (グリッド viewport、論理 px)。 */
+    getLayerSize: () => { width: number; height: number }
+    /** Stable id of the tip frame (the sink's aria-describedby target). / tip フレームの安定 id (シンクの aria-describedby 先)。 */
+    tipId: string
+}
+
+export type UsePopoversParams = {
+    /** Rewire gate (§6.9-1 empty branch). / 再結線ゲート。 */
+    enabled: boolean
+    adapter: SpreadsheetDataAdapter
+    popovers: PopoverOverrides | undefined
+    sinkRef: RefObject<HTMLTextAreaElement | null>
+    bodyRef: RefObject<HTMLElement | null>
+    handleRef: RefObject<VirtualGridHandle | null>
+    rowAxis: AxisModel
+    colAxis: AxisModel
+    zoomRef: RefObject<number>
+    getActive: () => CellCoord
+    isEditing: () => boolean
+    requestCommit: () => boolean
+    focusSink: (options?: { preventScroll?: boolean }) => void
+    rearmSink: () => void
+    /** Composite drag probe incl. the reference drag — the tip is never shown mid-drag. / 参照ドラッグ含む合成ドラッグ判定 — ドラッグ中は tip を出さない。 */
+    isDraggingAny: () => boolean
+    commitEdits: (edits: readonly CellEdit[], rejection: EditRejection) => number | null
+    labels: SpreadsheetLabels
+    onHyperlinkOpen?: (url: string, cell: CellCoord) => void
+    /** Root-owned anchor state the overlay positions. / root 所有のアンカー状態 (overlay が配置)。 */
+    anchors: RefObject<PopoverAnchorState>
+    repaintOverlay: () => void
+}
+
+/** The adapter capability each kind requires (the "cannot write what you cannot read" gate). / 各 kind が要するアダプタ能力 (「読めないものは書けない」ゲート)。 */
+const capabilityOf = (adapter: SpreadsheetDataAdapter, kind: PopoverKind): boolean => {
+    switch (kind) {
+        case "note":
+        case "note-tip":
+            return adapter.getCellNote !== undefined
+        case "comment":
+            return adapter.getCellComments !== undefined
+        case "link":
+            return adapter.getCellHyperlink !== undefined
+        default:
+            return adapter.getCellValidation !== undefined
+    }
+}
+
+/** popovers[kind] !== false AND the capability is declared. / popovers[kind] !== false かつ能力宣言済み。 */
+const kindEnabled = (adapter: SpreadsheetDataAdapter, popovers: PopoverOverrides | undefined, kind: PopoverKind): boolean => (popovers === undefined ? true : popovers[kind] !== false) && capabilityOf(adapter, kind)
+
+/** A coalesced hover request: a resolved cell (null = left the cells) or a client point resolved inside the frame. / 合流するホバー要求: 解決済みセル (null = 離脱) か、フレーム内で解決する client 座標。 */
+type HoverRequest = { cell: CellCoord | null } | { clientX: number; clientY: number }
+
+/**
+ * Builds the popover controller; the layer renders from its `context` / `tipContext`.
+ * ポップオーバーコントローラを構築する。層は context / tipContext から描画する。
+ */
+export const usePopovers = (params: UsePopoversParams): PopoverController => {
+    // paramsRef パターン: リスナーは結線 1 回、最新パラメータはレンダー毎にここへ写す
+    const paramsRef = useRef(params)
+    paramsRef.current = params
+
+    const [context, setContext] = useState<PopoverContext | null>(null)
+    const [tipContext, setTipContext] = useState<NoteTipContext | null>(null)
+    /** Imperative mirror of the open interactive kind (state reads inside callbacks would be stale). / 開いている対話 kind の命令読みミラー。 */
+    const openKindRef = useRef<PopoverKind | null>(null)
+    /** The cell whose tip is visible (null = hidden). / tip を表示中のセル (null = 非表示)。 */
+    const tipCellRef = useRef<CellCoord | null>(null)
+    /** The last hovered cell (the predicate's `prev` — after hideTip the tip cannot re-show until this changes). / 直近のホバーセル (述語の prev — hideTip 後はこれが変わるまで再表示しない)。 */
+    const hoverPrevRef = useRef<CellCoord | null>(null)
+    /**
+     * True while the pointer is inside the tip frame. The frame is a sibling of the body, so
+     * entering it fires the body's `pointerleave` in the SAME input task as the tip's
+     * `pointerenter` — before the rAF-deferred evaluation; the evaluation consults this flag so
+     * that leave does not start the grace (hoverable tip). Reset when the tip unmounts (no
+     * `pointerleave` reaches an unmounted frame).
+     * ポインタが tip フレーム内にいる間 true。フレームは body の兄弟なので、進入は tip の
+     * pointerenter と**同じ入力タスク**で body の pointerleave を起こす (rAF 遅延の評価より前)。評価は
+     * この旗を見て離脱で猶予を始めない (ホバー可)。tip のアンマウントで戻す (消えたフレームに pointerleave は届かない)。
+     */
+    const tipHoveredRef = useRef(false)
+    const graceTimerRef = useRef<number | null>(null)
+    const hoverRafRef = useRef<number | null>(null)
+    /** What the next frame evaluates: a cell (`onCellHover`), a client point (body pointermove — hit-tested inside the frame) or null (left the cells). / 次フレームの評価対象: セル (onCellHover) / client 座標 (body の pointermove — ヒットテストはフレーム内で) / null (セル領域から離脱)。 */
+    const pendingHoverRef = useRef<HoverRequest | null>(null)
+    const compositionEndedAtRef = useRef<number | null>(null)
+    const tipId = useId()
+
+    /** The active cell's rect in layer px (the overlay's forward map — the same recipe as the keyboard cellRect). / active セルの層 px 矩形 (overlay の順写像 — keyboard cellRect と同じ式)。 */
+    const anchorRectOf = useCallback((cell: CellCoord): PopoverRect => {
+        const p = paramsRef.current
+        const handle = p.handleRef.current
+        // detached ハンドルは原点扱い (番兵クランプは keyboard と同じ)
+        const position = handle === null ? { x: 0, y: 0 } : handle.getScrollPosition()
+        const frozen = handle === null ? { rows: 0, cols: 0, width: 0, height: 0 } : handle.getFrozenSize()
+        return {
+            top: rowToViewportY(p.rowAxis, cell.row, Math.max(0, position.y), frozen.rows),
+            left: colToViewportX(p.colAxis, cell.col, Math.max(0, position.x), frozen.cols),
+            width: p.colAxis.sizeOf(cell.col),
+            height: p.rowAxis.sizeOf(cell.row),
+        }
+    }, [])
+
+    /** Writes the anchor state and repaints (the overlay moves the anchor nodes). / アンカー状態を書き repaint する (overlay がアンカーノードを動かす)。 */
+    const writeAnchors = useCallback((next: Partial<PopoverAnchorState>) => {
+        const p = paramsRef.current
+        p.anchors.current = { ...p.anchors.current, ...next }
+        p.repaintOverlay()
+    }, [])
+
+    const cancelGrace = useCallback(() => {
+        if (graceTimerRef.current !== null) {
+            window.clearTimeout(graceTimerRef.current)
+            graceTimerRef.current = null
+        }
+    }, [])
+
+    /**
+     * Re-evaluates the ADR-15 invariant "the sink's aria-describedby points at the tip WHILE the
+     * hovered cell is active": binds when the visible tip's cell IS the active cell, unbinds —
+     * only its own binding — otherwise. Called on tip show / hide here and by the root's
+     * active-cell effect, so the binding follows arrow keys in both directions.
+     * ADR-15 の不変条件「ホバーセルが active の**間**シンクの aria-describedby が tip を指す」の
+     * 再評価。可視 tip のセルが active なら結び、でなければ**自分の結合だけ**外す。ここでは tip の
+     * 表示 / 消灯で、root の active セル効果からも呼ばれ、結合が矢印キーの両方向に追随する。
+     */
+    const syncTipAriaDescribedBy = useCallback(() => {
+        const sink = paramsRef.current.sinkRef.current
+        if (sink === null) {
+            return
+        }
+        const tipCell = tipCellRef.current
+        if (tipCell !== null && coordEquals(tipCell, paramsRef.current.getActive())) {
+            sink.setAttribute("aria-describedby", tipId)
+        } else if (sink.getAttribute("aria-describedby") === tipId) {
+            // 外すのは自分の結合だけ — tip が無効 / 非表示のまま active が動いても他所の結合に触れない (v0.7 恒等)
+            sink.removeAttribute("aria-describedby")
+        }
+    }, [tipId])
+
+    /** Hides the tip now (true when one was visible). / tip を即時消灯 (可視だったら true)。 */
+    const hideTipNow = useCallback((): boolean => {
+        cancelGrace()
+        // 消えたフレームに pointerleave は届かない — ホバー旗はここで戻す (残すと次の tip が離脱で消えなくなる)
+        tipHoveredRef.current = false
+        if (tipCellRef.current === null) {
+            return false
+        }
+        tipCellRef.current = null
+        setTipContext(null)
+        writeAnchors({ tip: null })
+        // シンクの aria-describedby は tip の生存と同期 (不変条件の再評価 — 非表示なので自分の結合が外れる)
+        syncTipAriaDescribedBy()
+        return true
+    }, [cancelGrace, writeAnchors, syncTipAriaDescribedBy])
+
+    const startGrace = useCallback(() => {
+        cancelGrace()
+        graceTimerRef.current = window.setTimeout(() => {
+            graceTimerRef.current = null
+            hideTipNow()
+        }, NOTE_TIP_LEAVE_GRACE_MS)
+    }, [cancelGrace, hideTipNow])
+
+    /** Shows the tip for `cell` (the note read happens here, once). / cell の tip を表示する (ノート読みはここで 1 回)。 */
+    const showTip = useCallback(
+        (cell: CellCoord) => {
+            const p = paramsRef.current
+            cancelGrace()
+            // 能力は呼び手 (述語 hasNote) が確認済み — ここは読み 1 回
+            const note = p.adapter.getCellNote === undefined ? undefined : p.adapter.getCellNote(cell.row, cell.col)
+            if (note === undefined || note === "") {
+                return
+            }
+            tipCellRef.current = cell
+            setTipContext({ kind: "note-tip", cell, anchorRect: anchorRectOf(cell), current: note, close: hideTipNow })
+            writeAnchors({ tip: cell })
+            // ホバーセルが active のときだけシンクの説明として結ぶ (SR がフォーカス位置の注釈として読む) — 不変条件の再評価
+            syncTipAriaDescribedBy()
+        },
+        [anchorRectOf, cancelGrace, hideTipNow, writeAnchors, syncTipAriaDescribedBy],
+    )
+
+    /**
+     * One hover evaluation (rAF-coalesced): a leave (null) while the pointer is inside the tip
+     * frame is the other face of entering the tip and changes nothing (hover `prev` kept, no
+     * grace — hoverable tip); on the visible tip's own cell ⇒ keep it (cancel a running grace —
+     * no re-read, no re-render); on another cell ⇒ show (cell change + note + no drag) or start
+     * the leave grace when a tip is visible.
+     * ホバー評価 1 回 (rAF 合流): ポインタが tip フレーム内にいる間の離脱 (null) は tip 進入の裏面で
+     * 何も変えない (ホバーの prev 据置き、猶予なし — ホバー可)、可視 tip 自身のセルなら維持 (走っている
+     * 猶予を取消 — 再読も再描画もしない)、別セルなら表示 (セル変化 + ノート + 非ドラッグ) か、tip 可視なら
+     * 離脱猶予の開始。
+     */
+    const evaluateHover = useCallback(
+        (next: CellCoord | null) => {
+            const p = paramsRef.current
+            // tip 上にいる間の body 離脱は tip 進入の裏面 — 猶予も prev も動かさない (ホバー可)
+            if (next === null && tipHoveredRef.current) {
+                return
+            }
+            const prev = hoverPrevRef.current
+            hoverPrevRef.current = next
+            const tipCell = tipCellRef.current
+            // tip のセルに留まった / 戻った ⇒ 猶予取消だけ (再表示ではない)
+            if (tipCell !== null && next !== null && coordEquals(tipCell, next)) {
+                cancelGrace()
+                return
+            }
+            const hasNote = (cell: CellCoord): boolean => {
+                const note = p.adapter.getCellNote === undefined ? undefined : p.adapter.getCellNote(cell.row, cell.col)
+                return note !== undefined && note !== ""
+            }
+            // 表示はセル変化のときだけ (hideTip 後に同じセルへ留まっても再表示しない)
+            if (shouldShowNoteTip(prev, next, p.isDraggingAny(), hasNote)) {
+                // next は非 null (述語が保証)
+                if (next !== null) {
+                    showTip(next)
+                }
+                return
+            }
+            // tip のセルを離れた ⇒ 猶予開始 (tip 上へ移った離脱は先頭で除外済み、tip からの離脱は onTipPointerLeave が再開)
+            if (tipCell !== null) {
+                startGrace()
+            }
+        },
+        [showTip, cancelGrace, startGrace],
+    )
+
+    /** Hit-tests a client position to a cell (the fill machine's recipe). / client 座標をセルへヒットテスト (fill 機械と同じ式)。 */
+    const hitTest = useCallback((clientX: number, clientY: number): CellCoord | null => {
+        const p = paramsRef.current
+        const body = p.bodyRef.current
+        const handle = p.handleRef.current
+        if (body === null || handle === null) {
+            return null
+        }
+        const rect = body.getBoundingClientRect()
+        const z = p.zoomRef.current
+        const position = handle.getScrollPosition()
+        const frozen = handle.getFrozenSize()
+        return clampCoord({ row: viewportYToRow(p.rowAxis, (clientY - rect.top) / z, Math.max(0, position.y), frozen.height), col: viewportXToCol(p.colAxis, (clientX - rect.left) / z, Math.max(0, position.x), frozen.width) }, p.rowAxis.count, p.colAxis.count)
+    }, [])
+
+    /**
+     * Queues a hover request for the next frame (one evaluation per frame — the LAST request
+     * wins). A client point is hit-tested inside the frame, so a burst of pointermove events
+     * costs one body layout read per frame (the engines' press-cached-rect discipline), not one
+     * per event.
+     * ホバー要求を次フレームへ積む (1 フレーム 1 評価 — 最後の要求が勝つ)。client 座標のヒットテストは
+     * フレーム内で行うため、pointermove の連発でも body のレイアウト読みは 1 フレーム 1 回
+     * (エンジンの押下時矩形キャッシュと同じ規律) — イベント毎ではない。
+     */
+    const scheduleHover = useCallback(
+        (request: HoverRequest) => {
+            pendingHoverRef.current = request
+            // rAF 合流: 1 フレーム 1 評価
+            if (hoverRafRef.current === null) {
+                hoverRafRef.current = requestAnimationFrame(() => {
+                    hoverRafRef.current = null
+                    const pending = pendingHoverRef.current
+                    // 要求はフレーム内で解決 (セルはそのまま、client 座標はここで 1 回だけヒットテスト)
+                    evaluateHover(pending === null ? null : "cell" in pending ? pending.cell : hitTest(pending.clientX, pending.clientY))
+                })
+            }
+        },
+        [evaluateHover, hitTest],
+    )
+
+    const onCellHover = useCallback((cell: CellCoord | null) => scheduleHover({ cell }), [scheduleHover])
+
+    /** Escape chain step 0 (the hover `prev` stays on the cell, so no re-show until the pointer moves to another cell). / Escape チェーン step 0 (ホバーの prev はそのセルのままなので、別セルへ移るまで再表示しない)。 */
+    const hideTip = useCallback((): boolean => hideTipNow(), [hideTipNow])
+
+    /** Closes the interactive popover (idempotent) and returns focus to the sink. / 対話ポップオーバーを閉じ (冪等) フォーカスをシンクへ返す。 */
+    const close = useCallback(() => {
+        if (openKindRef.current === null) {
+            return
+        }
+        const p = paramsRef.current
+        openKindRef.current = null
+        setContext(null)
+        writeAnchors({ interactive: null })
+        // フォーカス復帰 (スクロールさせない) + idle なら再武装 (編集セッションの値は守る)
+        p.focusSink({ preventScroll: true })
+        if (!p.isEditing()) {
+            p.rearmSink()
+        }
+    }, [writeAnchors])
+
+    /** Places `ctx` on the interactive anchor (replacing whatever was open). / ctx を対話アンカーへ載せる (開いていたものは置換)。 */
+    const present = useCallback(
+        (ctx: PopoverContext) => {
+            openKindRef.current = ctx.kind
+            setContext(ctx)
+            writeAnchors({ interactive: ctx.cell })
+        },
+        [writeAnchors],
+    )
+
+    /** Runs an annotate commit; a rejection re-presents the context with `rejected: true`. / annotate の commit を実行し、拒否なら rejected: true で再提示する。 */
+    const commitOrReject = useCallback(
+        (ctx: NotePopoverContext | CommentPopoverContext | LinkPopoverContext, edits: readonly CellEdit[]) => {
+            const p = paramsRef.current
+            if (p.commitEdits(edits, { source: "annotate" }) === null) {
+                // 拒否: 開いたまま rejected 状態へ (既定コンポーネントが Ctrl+Enter 再試行 / Escape 破棄を担う)
+                present({ ...ctx, rejected: true })
+                return
+            }
+            close()
+        },
+        [present, close],
+    )
+
+    const open = useCallback(
+        (kind: PopoverKind, options?: PopoverOpenOptions) => {
+            const p = paramsRef.current
+            if (!kindEnabled(p.adapter, p.popovers, kind)) {
+                throw new RangeError(`[spreadsheet] openPopover("${kind}") is unavailable: the kind is disabled by the popovers prop or its adapter capability is undeclared`)
+            }
+            const cell = p.getActive()
+            if (kind === "note-tip") {
+                // 手動表示: active セルにノートがあるときだけ (ホバー述語とは独立)
+                showTip(cell)
+                return
+            }
+            if (kind === "message") {
+                // 優先順: 開いているエディタ (note / comment / link / list) は検証メッセージに置換されない
+                if (openKindRef.current !== null && openKindRef.current !== "message") {
+                    return
+                }
+                const explicit = options !== undefined && options.message !== undefined ? options.message : undefined
+                const rule = p.adapter.getCellValidation === undefined ? undefined : p.adapter.getCellValidation(cell.row, cell.col)
+                const message = explicit !== undefined ? explicit : rule === undefined ? undefined : rule.inputMessage
+                if (message === undefined) {
+                    return
+                }
+                const rejected = options !== undefined && options.rejected === true
+                // メッセージはフォーカスを奪わない (入力中の告知) — アンカーへ載せるだけ
+                present({ kind: "message", cell, anchorRect: anchorRectOf(cell), current: { title: resolveLabel(p.labels, "messageTitle"), message, rejected }, close })
+                return
+            }
+            // 対話 kind: 開く前の commit ゲート (拒否ならセッション維持で中断)
+            if (p.isEditing() && !p.requestCommit()) {
+                return
+            }
+            if (kind === "list") {
+                const rule = p.adapter.getCellValidation === undefined ? undefined : p.adapter.getCellValidation(cell.row, cell.col)
+                // list 規則のないセルでは何も開かない (Sheets の Alt+↓ と同じ)
+                if (rule === undefined || rule.type !== "list") {
+                    return
+                }
+                const typed = options !== undefined && options.typed !== undefined ? options.typed : ""
+                // ホバー tip はエディタに席を譲る
+                hideTipNow()
+                // 開く前にシンクへフォーカス (root の迷子回収に popover の初期フォーカスを奪わせない)
+                p.focusSink({ preventScroll: true })
+                present({
+                    kind: "list",
+                    cell,
+                    anchorRect: anchorRectOf(cell),
+                    current: rule.values,
+                    typed,
+                    commit: (value: string) => {
+                        // リスト確定はセル編集 (source "edit"、セッションなし = discarded)
+                        paramsRef.current.commitEdits([{ row: cell.row, col: cell.col, text: value }], { source: "edit", editSession: "discarded" })
+                        close()
+                    },
+                    close,
+                })
+                return
+            }
+            hideTipNow()
+            p.focusSink({ preventScroll: true })
+            if (kind === "note") {
+                const current = p.adapter.getCellNote === undefined ? undefined : p.adapter.getCellNote(cell.row, cell.col)
+                const ctx: NotePopoverContext = {
+                    kind: "note",
+                    cell,
+                    anchorRect: anchorRectOf(cell),
+                    current,
+                    commit: (next: string | null) => {
+                        commitOrReject(ctx, [{ row: cell.row, col: cell.col, note: next }])
+                    },
+                    close,
+                    rejected: false,
+                }
+                present(ctx)
+                return
+            }
+            if (kind === "comment") {
+                const thread = p.adapter.getCellComments === undefined ? undefined : p.adapter.getCellComments(cell.row, cell.col)
+                const ctx: CommentPopoverContext = {
+                    kind: "comment",
+                    cell,
+                    anchorRect: anchorRectOf(cell),
+                    current: thread === undefined ? [] : thread,
+                    commit: (next: readonly CellCommentInput[] | null) => {
+                        // スレッド全体を運ぶ (id つき既存 + id なし新規、null は消去) — id の採番は consumer
+                        commitOrReject(ctx, [{ row: cell.row, col: cell.col, comments: next }])
+                    },
+                    close,
+                    rejected: false,
+                }
+                present(ctx)
+                return
+            }
+            // 信頼境界 (ADR-10): 許可外スキームの生 URL はリンク無し扱い — 表示にも Open にも渡さない
+            const url = p.adapter.getCellHyperlink === undefined ? undefined : normalizeAdapterHyperlink(p.adapter.getCellHyperlink(cell.row, cell.col))
+            const text = p.adapter.getCellText(cell.row, cell.col)
+            const ctx: LinkPopoverContext = {
+                kind: "link",
+                cell,
+                anchorRect: anchorRectOf(cell),
+                current: { text, url },
+                commit: (next: { text: string; url: string | null }) => {
+                    // url は正規化済み href か null — 正規化不能はレンダラのバグ (既定コンポーネントは保存前に弾く)
+                    const normalized = next.url === null ? null : normalizeHyperlink(next.url)
+                    if (normalized === null && next.url !== null) {
+                        throw new RangeError(`[spreadsheet] link commit received an unnormalisable url ${JSON.stringify(next.url)}`)
+                    }
+                    // text が変わらなければ text キーは出さない (未指定 = 触らない)
+                    const edit: CellEdit = next.text === text ? { row: cell.row, col: cell.col, hyperlink: normalized } : { row: cell.row, col: cell.col, text: next.text, hyperlink: normalized }
+                    commitOrReject(ctx, [edit])
+                },
+                close,
+                canOpen: p.onHyperlinkOpen !== undefined,
+                open: () => {
+                    const open = paramsRef.current.onHyperlinkOpen
+                    if (open !== undefined && url !== undefined) {
+                        open(url, cell)
+                    }
+                },
+                rejected: false,
+            }
+            present(ctx)
+        },
+        [anchorRectOf, close, commitOrReject, hideTipNow, present, showTip],
+    )
+
+    const { enabled, bodyRef } = params
+    useEffect(() => {
+        const body = bodyRef.current
+        if (!enabled || body === null) {
+            return
+        }
+        const onPointerMove = (event: PointerEvent) => {
+            const p = paramsRef.current
+            // tip が無効 (prop / 能力) なら何も積まない (v0.7 恒等 — 読みゼロ)
+            if (!kindEnabled(p.adapter, p.popovers, "note-tip")) {
+                return
+            }
+            // 座標だけ積む — ヒットテスト (body の layout 読み) はフレーム内で 1 回
+            scheduleHover({ clientX: event.clientX, clientY: event.clientY })
+        }
+        const onPointerLeave = () => {
+            if (!kindEnabled(paramsRef.current.adapter, paramsRef.current.popovers, "note-tip")) {
+                return
+            }
+            scheduleHover({ cell: null })
+        }
+        body.addEventListener("pointermove", onPointerMove)
+        body.addEventListener("pointerleave", onPointerLeave)
+        return () => {
+            body.removeEventListener("pointermove", onPointerMove)
+            body.removeEventListener("pointerleave", onPointerLeave)
+        }
+    }, [enabled, bodyRef, scheduleHover])
+
+    // アンマウント時に rAF / 猶予タイマを回収する (全タイマ回収の規律)
+    useEffect(
+        () => () => {
+            if (hoverRafRef.current !== null) {
+                cancelAnimationFrame(hoverRafRef.current)
+            }
+            if (graceTimerRef.current !== null) {
+                window.clearTimeout(graceTimerRef.current)
+            }
+        },
+        [],
+    )
+
+    const { adapter, popovers } = params
+    const layerEnabled = useMemo(() => POPOVER_KINDS.some((kind) => kindEnabled(adapter, popovers, kind)), [adapter, popovers])
+
+    return useMemo(
+        () => ({
+            layerEnabled,
+            isKindEnabled: (kind: PopoverKind) => kindEnabled(paramsRef.current.adapter, paramsRef.current.popovers, kind),
+            open,
+            close,
+            isOpen: () => openKindRef.current,
+            onCellHover,
+            hideTip,
+            onTipPointerEnter: () => {
+                // 旗が先 — 同一タスクで後から届く body の pointerleave (rAF 評価) が猶予を始めない
+                tipHoveredRef.current = true
+                cancelGrace()
+            },
+            onTipPointerLeave: () => {
+                tipHoveredRef.current = false
+                if (tipCellRef.current !== null) {
+                    startGrace()
+                }
+            },
+            syncTipAriaDescribedBy,
+            context,
+            tipContext,
+            registerCompositionEnd: (timeStamp: number) => {
+                compositionEndedAtRef.current = timeStamp
+            },
+            isCompositionKey: (event: KeyboardEvent) => isCompositionKeydown(event, compositionEndedAtRef.current),
+            getLayerSize: () => {
+                const handle = paramsRef.current.handleRef.current
+                return handle === null ? { width: 0, height: 0 } : handle.getViewportSize()
+            },
+            tipId,
+        }),
+        [layerEnabled, open, close, onCellHover, hideTip, cancelGrace, startGrace, syncTipAriaDescribedBy, context, tipContext, tipId],
+    )
+}