@aiquants/spreadsheet 0.8.0

package/src/keyboard/ensureCellVisible.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Self-implemented nearest-visibility scroll (§6.6.3). scrollToCell has NO
+ * "no-op when visible" align (start/end/center only, and it pins anchors), so arrow-key
+ * navigation must use edge-delta scrollBy on BOTH axes to avoid per-keystroke snapping
+ * (§7-7 of the VirtualGrid design plan — scrollTo is the floor-and-pin jump API and is
+ * deliberately not used here).
+ *
+ * 自前 nearest 可視化スクロール (§6.6.3)。scrollToCell に「可視なら no-op」は存在しない
+ * (start/end/center のみ、かつアンカーを張る) ため、矢印ナビは両軸ともはみ出し分だけの
+ * scrollBy で自作する (設計計画 §7-7 — scrollTo は floor + アンカー張りのジャンプ API で不使用)。
+ */
+
+import type { VirtualGridHandle } from "@aiquants/virtualscroll"
+import type { RefObject } from "react"
+import type { AxisModel } from "../model/axisModel.ts"
+import type { CellCoord } from "../model/cellCoord.ts"
+
+/** Factory dependencies. / 構築時依存。 */
+type EnsureCellVisibleDeps = {
+    handleRef: RefObject<VirtualGridHandle | null>
+    rowAxis: AxisModel
+    colAxis: AxisModel
+}
+
+/**
+ * Builds the ensureCellVisible helper (constructed once in Spreadsheet, injected into
+ * keyboard / editor / Shift+F10 — §6.9-7 ownership). Both axes read the grid handle
+ * synchronously (the truth — §7-4) and land via edge-delta scrollBy.
+ * ensureCellVisible の構築 (Spreadsheet で 1 回構築し keyboard / editor / Shift+F10 へ配る)。
+ * 両軸ともグリッドハンドルの同期読み (§7-4 の真実) + 端差分 scrollBy で着地する。
+ */
+export const createEnsureCellVisible = ({ handleRef, rowAxis, colAxis }: EnsureCellVisibleDeps) => {
+    return (cell: CellCoord): void => {
+        const handle = handleRef.current
+        if (handle === null) {
+            return
+        }
+        // 位置と窓寸はハンドルから同期で読む (§7-4 の鮮度序列 — viewStore に位置は存在しない)。
+        // ペイン未接続の番兵 ({-1,-1}) と寸法 0 (未測定 / 不可視) では何もしない — 寸法 0 の
+        // ビューポートに「可視化」は定義できず、全打鍵が無意味な scrollBy を飛ばすため
+        const { x: hx, y: vy } = handle.getScrollPosition()
+        const { width: viewportW, height: viewportH } = handle.getViewportSize()
+        if (vy < 0 || hx < 0) {
+            return
+        }
+        // 縦: 論理座標で可視域と比較し、はみ出しぶんだけ scrollBy (端差分 — §7-7)。
+        // 凍結行 (v0.6 計画 §3 — 横の凍結列 no-op と同文) は常時可視のため縦成分のみ no-op
+        // (横調整は下ブロックで続行 — 凍結行 × スクロール列のセルは横スクロールが要る)。
+        // スクロール行の上可視限界は木座標 H_F + vy (viewport 上端 y = H_F がスクロール帯の始まり)
+        if (viewportH > 0 && cell.row >= handle.getFrozenSize().rows) {
+            const frozenHeight = handle.getFrozenSize().height
+            const top = rowAxis.offsetOf(cell.row)
+            const bottom = top + rowAxis.sizeOf(cell.row)
+            if (top < frozenHeight + vy) {
+                handle.scrollBy({ y: top - (frozenHeight + vy) })
+            } else if (bottom > vy + viewportH) {
+                handle.scrollBy({ y: bottom - (vy + viewportH) })
+            }
+        }
+        // 横: 同型の nearest 計算 → 端差分 scrollBy (クランプはハンドルが担う)。
+        // 凍結列 (v0.5 計画 §3-4) は常時可視のため no-op。スクロール列の左可視限界は木座標
+        // W_F + hx (viewport 左端 x = W_F がスクロール帯の始まり — エンジン §8-a)
+        if (viewportW > 0) {
+            const frozen = handle.getFrozenSize()
+            if (cell.col < frozen.cols) {
+                return
+            }
+            const left = colAxis.offsetOf(cell.col)
+            const right = left + colAxis.sizeOf(cell.col)
+            if (left < frozen.width + hx) {
+                handle.scrollBy({ x: left - (frozen.width + hx) })
+            } else if (right > hx + viewportW) {
+                handle.scrollBy({ x: right - (hx + viewportW) })
+            }
+        }
+    }
+}