@aiquants/spreadsheet 0.8.0

package/src/popover/placement.ts

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview Pure popover geometry (v0.8 §2.5 / §4.1.15): `popoverWidth` is the single source
+ * of the frame width (min(POPOVER_MAX_WIDTH, usable − margin) — the layer writes it BEFORE
+ * measuring the frame, because the wrapped height depends on it); `placePopover` picks the
+ * first of four candidate positions (below-right → below-left → above-right → above-left) that
+ * fits the body minus the scrollbar strip, otherwise SHRINKS the height to the larger free space
+ * beside the anchor (below or above — the kind roots scroll the rest) and pins the popover to
+ * the top-left margin only when even that is below `POPOVER_MIN_HEIGHT` or the width does not
+ * fit; `shouldShowNoteTip` is the single show predicate of the hover note tip (cell change AND
+ * the next cell has a note AND no drag — reference drags included — is in flight). React / DOM
+ * free; every branch is pinned by placement.spec.ts.
+ *
+ * ポップオーバー幾何の純関数 (v0.8 §2.5 / §4.1.15)。popoverWidth はフレーム幅の唯一の源
+ * (min(POPOVER_MAX_WIDTH, 使用可能幅 − マージン) — 折り返し後の高さは幅に依存するため、層は
+ * 計測の**前**にこれを書く)。placePopover は 4 候補 (below-right → below-left → above-right →
+ * above-left) のうち body − スクロールバー帯に最初に収まるものを選び、どれも収まらなければ
+ * アンカー脇の広い方 (下 / 上) の空きへ高さを**縮めて**置き (残りは kind ルートがスクロール)、
+ * それすら POPOVER_MIN_HEIGHT を割る / 幅が収まらないときだけ左上マージンへピン留め。
+ * shouldShowNoteTip はホバー note tip の唯一の表示述語 (セル変化 ∧ 次セルにノートあり ∧ いかなる
+ * ドラッグ (参照ドラッグ含む) も飛行中でない)。React / DOM 非依存で、全分岐を placement.spec.ts が固定。
+ */
+
+import { type CellCoord, coordEquals } from "../model/cellCoord.ts"
+import { SCROLLBAR_WIDTH } from "../model/viewStore.ts"
+
+/** A rectangle in the popover layer's coordinate space (logical viewport px). / ポップオーバー層座標系 (論理 viewport px) の矩形。 */
+export type PopoverRect = { top: number; left: number; width: number; height: number }
+
+/** The body (layer) size placement works in. / 配置が扱う body (層) の寸法。 */
+export type PopoverBodySize = { width: number; height: number }
+
+/** Maximum popover width in logical px. / ポップオーバーの最大幅 (論理 px)。 */
+export const POPOVER_MAX_WIDTH = 320
+
+/** Margin subtracted from the usable body and used as the pinned top-left offset. / 使用可能領域から差し引くマージン兼ピン留め時の左上オフセット。 */
+export const POPOVER_MARGIN = 8
+
+/** The smallest height a popover shrunk beside its anchor keeps (about two tip lines); below it the popover is pinned instead. / アンカー脇へ縮めたポップオーバーが保つ最小高 (tip 約 2 行)。これを割るならピン留め。 */
+export const POPOVER_MIN_HEIGHT = 64
+
+/** Grace after the pointer leaves the tip's cell before the tip hides (hoverable tip). / ポインタが tip のセルを離れてから消灯するまでの猶予 (tip はホバー可)。 */
+export const NOTE_TIP_LEAVE_GRACE_MS = 150
+
+/**
+ * The popover width for a body: min(POPOVER_MAX_WIDTH, usable width − margin), never negative,
+ * where the usable width is the body minus the scrollbar strip. It depends on the body only, so
+ * the layer applies it to the frame BEFORE reading the frame's height (a narrower frame wraps
+ * more lines — measuring at another width under-estimates the height).
+ * body に対するポップオーバー幅: min(POPOVER_MAX_WIDTH, 使用可能幅 − マージン) (負にしない)。
+ * 使用可能幅 = body − スクロールバー帯。body だけで決まるため、層はフレームの高さを読む**前**に
+ * これを書く (狭いフレームは行数が増える — 別の幅で測ると高さを過小評価する)。
+ */
+export const popoverWidth = (bodyRect: PopoverBodySize): number => Math.max(0, Math.min(POPOVER_MAX_WIDTH, bodyRect.width - SCROLLBAR_WIDTH - POPOVER_MARGIN))
+
+/**
+ * Places a popover of `measuredHeight` (measured at `popoverWidth(bodyRect)`) next to
+ * `anchorRect` inside `bodyRect` (both in layer px). The usable area is the body minus the
+ * scrollbar strip on both axes; the height is capped at usable − margin (never negative).
+ * Candidates are tried in the fixed order below-right, below-left, above-right, above-left; the
+ * first one lying entirely inside the usable area wins. When none fits at full height, the height
+ * is shrunk to the larger free space beside the anchor (below the anchor's bottom edge, or above
+ * its top edge — below wins a tie) and the popover is placed there with the first horizontal
+ * alignment (anchor-left, then anchor-right) that fits, so it never covers the anchor cell; only
+ * when that free space is below `POPOVER_MIN_HEIGHT` or no alignment fits horizontally is the
+ * popover pinned at (POPOVER_MARGIN, POPOVER_MARGIN).
+ * ポップオーバー (高さ measuredHeight — popoverWidth(bodyRect) の幅で計測済み) を anchorRect の隣へ
+ * bodyRect 内 (いずれも層 px) に配置。使用可能領域は body から両軸のスクロールバー帯を引いたもの。
+ * 高さは 使用可能高 − マージン で上限 (負にはしない)。候補は below-right → below-left →
+ * above-right → above-left の固定順で、使用可能領域に丸ごと収まる最初の候補を採用。全高で収まる
+ * 候補が無ければ、アンカー脇の広い方の空き (アンカー下辺より下 / 上辺より上 — 同点は下) へ高さを縮め、
+ * 横に収まる最初の揃え (アンカー左揃え → 右辺揃え) で置く (アンカーセルを覆わない)。その空きが
+ * POPOVER_MIN_HEIGHT を割るか横にどちらも収まらないときだけ (POPOVER_MARGIN, POPOVER_MARGIN) へピン留め。
+ */
+export const placePopover = (anchorRect: PopoverRect, measuredHeight: number, bodyRect: PopoverBodySize): PopoverRect => {
+    // 使用可能領域 = body − スクロールバー帯 (両軸)
+    const usableWidth = bodyRect.width - SCROLLBAR_WIDTH
+    const usableHeight = bodyRect.height - SCROLLBAR_WIDTH
+    // 幅は body から (層が計測前に書いた値と同じ源)、高さは実測をマージン込みの使用可能高で上限 (負にしない)
+    const width = popoverWidth(bodyRect)
+    const height = Math.max(0, Math.min(measuredHeight, usableHeight - POPOVER_MARGIN))
+    const anchorRight = anchorRect.left + anchorRect.width
+    const anchorBottom = anchorRect.top + anchorRect.height
+    // 横の揃えはアンカー左揃え → 右辺揃えの固定順、使用可能幅に丸ごと収まるもの
+    const fitsX = (left: number): boolean => left >= 0 && left + width <= usableWidth
+    const lefts: readonly number[] = [anchorRect.left, anchorRight - width]
+    // 候補順は固定 (below-right → below-left → above-right → above-left)
+    const candidates: readonly { left: number; top: number }[] = [
+        { left: anchorRect.left, top: anchorBottom },
+        { left: anchorRight - width, top: anchorBottom },
+        { left: anchorRect.left, top: anchorRect.top - height },
+        { left: anchorRight - width, top: anchorRect.top - height },
+    ]
+    for (const candidate of candidates) {
+        // 使用可能領域に丸ごと収まる最初の候補
+        if (fitsX(candidate.left) && candidate.top >= 0 && candidate.top + height <= usableHeight) {
+            return { left: candidate.left, top: candidate.top, width, height }
+        }
+    }
+    // 全高では収まらない ⇒ アンカー脇の広い方 (下 / 上) の空きへ高さを縮める (残りは kind ルートがスクロール)
+    const freeBelow = usableHeight - anchorBottom
+    const freeAbove = anchorRect.top
+    const shrunk = Math.min(height, Math.max(freeBelow, freeAbove))
+    if (shrunk >= POPOVER_MIN_HEIGHT) {
+        // 同点は下 (候補順と同じ優先)、上なら上辺揃え
+        const top = freeBelow >= freeAbove ? anchorBottom : anchorRect.top - shrunk
+        for (const left of lefts) {
+            if (fitsX(left)) {
+                return { left, top, width, height: shrunk }
+            }
+        }
+    }
+    // 横に収まらない / 縮めても最小高を割る ⇒ 左上マージンへピン留め
+    return { left: POPOVER_MARGIN, top: POPOVER_MARGIN, width, height }
+}
+
+/**
+ * The note-tip show predicate: true only when the hovered cell CHANGED to a cell that has a note
+ * while no drag (selection / header / resize / fill / reference) is in flight. `hasNote` is
+ * consulted only when the other conditions hold (no adapter read on a same-cell move or mid-drag).
+ * note tip の表示述語: ホバーセルがノートを持つ別のセルへ**変化**し、かつドラッグ (選択 /
+ * ヘッダー / リサイズ / fill / 参照) が 1 つも飛行中でないときだけ true。hasNote は他条件が
+ * 成立したときだけ諮る (同一セル内の移動やドラッグ中にアダプタを読まない)。
+ */
+export const shouldShowNoteTip = (prev: CellCoord | null, next: CellCoord | null, isDraggingAny: boolean, hasNote: (cell: CellCoord) => boolean): boolean => {
+    // 離脱 (null) は表示しない
+    if (next === null) {
+        return false
+    }
+    // 同一セル内の移動は変化ではない
+    if (prev !== null && coordEquals(prev, next)) {
+        return false
+    }
+    // いかなるドラッグ飛行中も表示しない (参照ドラッグ含む)
+    if (isDraggingAny) {
+        return false
+    }
+    return hasNote(next)
+}