@aiquants/spreadsheet 0.8.0

package/src/popover/ListPopover.tsx

@@ -0,0 +1,161 @@
+/**
+ * @fileoverview Default validation list picker (v0.8 §4.1.16): a combobox input narrowing the
+ * list rule's values by case-insensitive PREFIX, over a `role="listbox"` of `role="option"`
+ * items tracked through `aria-activedescendant`. Keys: ArrowDown / ArrowUp move the active
+ * option (clamped to the RENDERED options), Enter commits it, Escape closes; a pointer click
+ * commits the clicked option (its pointerdown is prevented so the input keeps focus). An empty
+ * match shows `labels.listEmpty`. At most `LIST_POPOVER_MAX_OPTIONS` matches are mounted — a
+ * larger match set appends one non-option `labels.listMore` row naming the hidden count (a
+ * pasted foreign rule may carry an arbitrarily large values array; mounting it whole would
+ * freeze the tab, so the picker renders a bounded prefix and the prefix filter narrows the
+ * rest). Leaving by focus closes. DOM hooks: `data-aqsp-popover="list"`, `data-aqsp-list-input`,
+ * `data-aqsp-list-option="<value>"`, `data-aqsp-list-empty`, `data-aqsp-list-more`.
+ *
+ * 既定の検証リスト (v0.8 §4.1.16): list 規則の値を大文字小文字を無視した**前方一致**で絞る
+ * combobox 入力 + `role="listbox"` / `role="option"` (aria-activedescendant で追跡)。キー:
+ * ArrowDown / ArrowUp で活性項目を移動 (**描画済み**候補へクランプ)、Enter で確定、Escape で
+ * 閉じる。ポインタのクリックはその項目を確定 (pointerdown を止めて入力のフォーカスを保つ)。
+ * 一致なしは `labels.listEmpty`。マウントする候補は `LIST_POPOVER_MAX_OPTIONS` 件まで — 超過分は
+ * 非 option の `labels.listMore` 行 1 つが非表示件数を示す (貼り付けた外来規則の values は任意長で、
+ * 全量マウントはタブを固まらせるため、描画は上限つきの先頭区間に絞り残りは前方一致で狭める)。
+ * フォーカス離脱で閉じる。
+ */
+
+import { type FocusEvent, type KeyboardEvent, type ReactNode, useId, useMemo, useRef, useState } from "react"
+import { resolveLabel, type SpreadsheetLabels } from "../model/labels.ts"
+import type { ListPopoverContext } from "./usePopovers.ts"
+
+export type ListPopoverProps = { ctx: ListPopoverContext; labels: SpreadsheetLabels }
+
+/**
+ * The most options one render mounts (v0.8 §4.1.16): a foreign list rule pasted from the wire
+ * may carry hundreds of thousands of values, and mounting one DOM node per value freezes the
+ * tab on open and on every keystroke re-filter. Matches beyond the cap stay reachable through
+ * the prefix filter and are announced by the `labels.listMore` row.
+ * 1 レンダーでマウントする候補数の上限 (v0.8 §4.1.16)。wire から貼り付けた外来 list 規則の values は
+ * 数十万件になり得て、1 値 1 DOM ノードのマウントは開いた瞬間と絞込のたびにタブを固まらせる。上限超の
+ * 一致は前方一致の絞込で到達でき、`labels.listMore` 行が存在を告知する。
+ */
+export const LIST_POPOVER_MAX_OPTIONS = 500
+
+/**
+ * Renders the list picker for one cell.
+ * 1 セルのリスト選択を描画する。
+ */
+export const ListPopover = ({ ctx, labels }: ListPopoverProps): ReactNode => {
+    const [typed, setTyped] = useState(ctx.typed)
+    const [index, setIndex] = useState(0)
+    const listId = useId()
+    const settlingRef = useRef(false)
+    // 前方一致 (大文字小文字無視) の絞込 — 元の順序を保つ
+    const filtered = useMemo(() => {
+        const needle = typed.toLowerCase()
+        return ctx.current.filter((value) => value.toLowerCase().startsWith(needle))
+    }, [ctx.current, typed])
+    // マウントは上限まで — 外来規則の巨大 values で 1 コミットに数十万ノードを積まない
+    const visible = useMemo(() => (filtered.length > LIST_POPOVER_MAX_OPTIONS ? filtered.slice(0, LIST_POPOVER_MAX_OPTIONS) : filtered), [filtered])
+    // 上限で切られた一致の数 (> 0 のとき listMore 行を描く)
+    const hidden = filtered.length - visible.length
+    // 絞込後の活性 index は描画済み候補の末尾へクランプ (項目が減っても・上限超でも範囲外を指さない)
+    const active = visible.length === 0 ? -1 : Math.min(index, visible.length - 1)
+
+    const settle = (action: () => void): void => {
+        settlingRef.current = true
+        try {
+            action()
+        } finally {
+            settlingRef.current = false
+        }
+    }
+    const commitActive = (): void => {
+        if (active < 0) {
+            return
+        }
+        settle(() => ctx.commit(visible[active]))
+    }
+    const onKeyDown = (event: KeyboardEvent<HTMLInputElement>): void => {
+        if (event.key === "Escape") {
+            event.preventDefault()
+            settle(ctx.close)
+            return
+        }
+        if (event.key === "Enter") {
+            event.preventDefault()
+            commitActive()
+            return
+        }
+        if (event.key === "ArrowDown") {
+            event.preventDefault()
+            // 上端のクランプはレンダー時 (active の導出) が担う — ここで重ねて丸めない
+            setIndex(active + 1)
+            return
+        }
+        if (event.key === "ArrowUp") {
+            event.preventDefault()
+            setIndex(Math.max(active - 1, 0))
+        }
+    }
+    const onBlur = (event: FocusEvent<HTMLDivElement>): void => {
+        if (settlingRef.current || (event.relatedTarget instanceof Node && event.currentTarget.contains(event.relatedTarget))) {
+            return
+        }
+        settle(ctx.close)
+    }
+    const optionId = (i: number): string => `${listId}-${i}`
+
+    return (
+        // biome-ignore lint/a11y/noStaticElementInteractions: 枠は combobox + listbox の focusout 合流点 (relatedTarget の内外判定) — 自身は操作面でない
+        <div className="aqsp-popover-list" data-aqsp-popover="list" onBlur={onBlur}>
+            <input
+                className="aqsp-popover-input"
+                data-aqsp-list-input=""
+                data-aqsp-popover-autofocus=""
+                type="text"
+                role="combobox"
+                aria-label={resolveLabel(labels, "listTitle")}
+                aria-expanded="true"
+                aria-autocomplete="list"
+                aria-controls={listId}
+                aria-activedescendant={active < 0 ? undefined : optionId(active)}
+                value={typed}
+                onChange={(event) => {
+                    setTyped(event.currentTarget.value)
+                    setIndex(0)
+                }}
+                onKeyDown={onKeyDown}
+            />
+            {/* role="listbox" は combobox の候補一覧 (select 要素では aria-activedescendant 追跡と前方一致絞込を表現できない) */}
+            <div className="aqsp-popover-options" id={listId} role="listbox" aria-label={resolveLabel(labels, "listTitle")}>
+                {visible.length === 0 ? (
+                    <div className="aqsp-popover-empty" data-aqsp-list-empty="">
+                        {resolveLabel(labels, "listEmpty")}
+                    </div>
+                ) : (
+                    visible.map((value, i) => (
+                        // key は位置由来 (optionId) — wire 契約は重複値を許し、値 key は兄弟間で衝突する
+                        // (項目は毎レンダー絞込から再導出される状態なし葉なので位置 key で安全)
+                        // biome-ignore lint/a11y/useKeyWithClickEvents: キーボード操作は combobox 入力の onKeyDown が担う (aria-activedescendant パターン — 項目はポインタ確定の面、tabIndex -1 でプログラム的にだけ焦点可)
+                        <div
+                            key={optionId(i)}
+                            className="aqsp-popover-option"
+                            id={optionId(i)}
+                            role="option"
+                            tabIndex={-1}
+                            aria-selected={i === active}
+                            data-aqsp-list-option={value}
+                            onPointerDown={(event) => event.preventDefault()}
+                            onClick={() => settle(() => ctx.commit(value))}>
+                            {value}
+                        </div>
+                    ))
+                )}
+                {hidden > 0 ? (
+                    // 描画特性は listEmpty 行と同じ情報行 (クラス共有)、role は与えない — 選択不能な告知面
+                    <div className="aqsp-popover-empty" data-aqsp-list-more="">
+                        {resolveLabel(labels, "listMore", hidden)}
+                    </div>
+                ) : null}
+            </div>
+        </div>
+    )
+}

package/src/popover/MessagePopover.tsx

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Default validation message popover (v0.8 §4.1.16): a `role="status"` box with the
+ * title and the message (the rule's input message, or a strict rejection verdict when
+ * `current.rejected`) and a Close button. It never takes focus — the layer skips the autofocus for
+ * this kind so typing continues in the sink. DOM hooks: `data-aqsp-popover="message"`,
+ * `data-aqsp-popover-title`, `data-aqsp-popover-message-text`, `data-aqsp-popover-rejected`,
+ * `data-aqsp-popover-close`.
+ *
+ * 既定の検証メッセージ (v0.8 §4.1.16): 題名と本文 (規則の入力メッセージ、または `current.rejected`
+ * のとき strict 拒否の判定文) + 閉じるボタンの `role="status"`。フォーカスは奪わない — 層はこの
+ * kind の初期フォーカスを省き、入力はシンクで続く。
+ */
+
+import type { ReactNode } from "react"
+import { resolveLabel, type SpreadsheetLabels } from "../model/labels.ts"
+import type { MessagePopoverContext } from "./usePopovers.ts"
+
+export type MessagePopoverProps = { ctx: MessagePopoverContext; labels: SpreadsheetLabels }
+
+/**
+ * Renders the validation message.
+ * 検証メッセージを描画する。
+ */
+export const MessagePopover = ({ ctx, labels }: MessagePopoverProps): ReactNode => (
+    <div className="aqsp-popover-message" data-aqsp-popover="message" data-aqsp-popover-rejected={ctx.current.rejected ? "" : undefined} role="status">
+        <div className="aqsp-popover-title" data-aqsp-popover-title="">
+            {ctx.current.title}
+        </div>
+        <p className="aqsp-popover-message-text" data-aqsp-popover-message-text="">
+            {ctx.current.message}
+        </p>
+        <button type="button" className="aqsp-popover-button" data-aqsp-popover-close="" aria-label={resolveLabel(labels, "popoverClose")} onClick={ctx.close}>
+            ×
+        </button>
+    </div>
+)

package/src/popover/NotePopover.tsx

@@ -0,0 +1,106 @@
+/**
+ * @fileoverview Default note editor popover (v0.8 §4.1.16): a textarea draft with Save / Close
+ * buttons. Keys: Escape saves-if-changed and closes in the normal state, closes WITHOUT saving in
+ * the rejected state; Ctrl+Enter saves (or retries after a rejection). Leaving the popover by
+ * focus saves-if-changed — an anchor scrolled under a frozen band is clipped, not un-rendered
+ * (SelectionOverlay `placeAnchor`), so the textarea keeps focus and that is NOT a leave: the
+ * editor hides and comes back with its draft. The textarea's `aria-describedby` points at the hint paragraph, which
+ * swaps between `labels.noteEscapeHint` and `labels.noteRejectedHint` with the rejected state.
+ * DOM hooks: `data-aqsp-popover="note"`, `data-aqsp-popover-title`, `data-aqsp-note-input`,
+ * `data-aqsp-popover-save`, `data-aqsp-popover-close`, `data-aqsp-popover-hint`,
+ * `data-aqsp-popover-rejected`.
+ *
+ * 既定の note エディタ (v0.8 §4.1.16): textarea の下書き + 保存 / 閉じるボタン。キー: Escape は
+ * 通常状態で「変更があれば保存して閉じる」、拒否状態では保存せず閉じる。Ctrl+Enter は保存 (拒否後は
+ * 再試行)。フォーカスがポップオーバーを離れたら変更があれば保存 — 凍結帯の下へ潜ったアンカーは
+ * clip されるだけで描画から外れない (SelectionOverlay の placeAnchor) ので textarea はフォーカスを保ち、
+ * 離脱には当たらない: エディタは隠れて下書きごと戻る。textarea の aria-describedby は
+ * ヒント段落を指し、拒否状態で `labels.noteEscapeHint` ↔ `labels.noteRejectedHint` が差し替わる。
+ */
+
+import { type FocusEvent, type KeyboardEvent, type ReactNode, useId, useRef, useState } from "react"
+import { resolveLabel, type SpreadsheetLabels } from "../model/labels.ts"
+import type { NotePopoverContext } from "./usePopovers.ts"
+
+export type NotePopoverProps = { ctx: NotePopoverContext; labels: SpreadsheetLabels }
+
+/**
+ * Renders the note editor for one cell.
+ * 1 セルの note エディタを描画する。
+ */
+export const NotePopover = ({ ctx, labels }: NotePopoverProps): ReactNode => {
+    const initial = ctx.current === undefined ? "" : ctx.current
+    const [draft, setDraft] = useState(initial)
+    const titleId = useId()
+    const hintId = useId()
+    /** True while THIS component drives a commit / close (its synchronous focusout must not re-fire the save). / 自分が commit / close を駆動している間 true (同期 focusout の二重保存を防ぐ)。 */
+    const settlingRef = useRef(false)
+
+    /** Runs a terminal action with the focusout re-entry guard engaged. / focusout 再入ガードを立てて終端動作を実行。 */
+    const settle = (action: () => void): void => {
+        settlingRef.current = true
+        try {
+            action()
+        } finally {
+            settlingRef.current = false
+        }
+    }
+    const save = (): void => {
+        // 空の下書きはノート消去
+        settle(() => ctx.commit(draft === "" ? null : draft))
+    }
+    const saveIfChanged = (): void => {
+        if (draft !== initial) {
+            save()
+        } else {
+            settle(ctx.close)
+        }
+    }
+    const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>): void => {
+        if (event.key === "Escape") {
+            event.preventDefault()
+            // 拒否状態の Escape は保存せず閉じる、通常状態は変更があれば保存して閉じる
+            if (ctx.rejected) {
+                settle(ctx.close)
+            } else {
+                saveIfChanged()
+            }
+            return
+        }
+        if (event.key === "Enter" && (event.ctrlKey || event.metaKey) && !event.altKey && !event.shiftKey) {
+            event.preventDefault()
+            save()
+        }
+    }
+    const onBlur = (event: FocusEvent<HTMLDivElement>): void => {
+        // ポップオーバー内の移動 (ボタンへ) と自分が起こした遷移は離脱ではない
+        if (settlingRef.current || (event.relatedTarget instanceof Node && event.currentTarget.contains(event.relatedTarget))) {
+            return
+        }
+        // 拒否状態はフォーカス離脱で黙って再試行しない (利用者の明示操作を待つ)
+        if (ctx.rejected) {
+            return
+        }
+        saveIfChanged()
+    }
+
+    return (
+        <div className="aqsp-popover-note" data-aqsp-popover="note" data-aqsp-popover-rejected={ctx.rejected ? "" : undefined} role="dialog" aria-labelledby={titleId} onBlur={onBlur}>
+            <div className="aqsp-popover-title" data-aqsp-popover-title="" id={titleId}>
+                {resolveLabel(labels, "noteTitle")}
+            </div>
+            <textarea className="aqsp-popover-textarea" data-aqsp-note-input="" data-aqsp-popover-autofocus="" value={draft} aria-describedby={hintId} aria-invalid={ctx.rejected ? true : undefined} onChange={(event) => setDraft(event.currentTarget.value)} onKeyDown={onKeyDown} />
+            <p className="aqsp-popover-hint" id={hintId} data-aqsp-popover-hint="">
+                {resolveLabel(labels, ctx.rejected ? "noteRejectedHint" : "noteEscapeHint")}
+            </p>
+            <div className="aqsp-popover-actions">
+                <button type="button" className="aqsp-popover-button" data-aqsp-popover-save="" onClick={save}>
+                    {resolveLabel(labels, "noteSave")}
+                </button>
+                <button type="button" className="aqsp-popover-button" data-aqsp-popover-close="" aria-label={resolveLabel(labels, "popoverClose")} onClick={() => settle(ctx.close)}>
+                    ×
+                </button>
+            </div>
+        </div>
+    )
+}

package/src/popover/NoteTip.tsx

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Default hover note tip (v0.8 §4.1.16): a read-only `role="tooltip"` box showing
+ * the hovered cell's note. It has no controls — the hook hides it (leave grace / Escape step 0)
+ * and the sink references it through `aria-describedby` while the hovered cell is active.
+ * DOM hook: `data-aqsp-popover="note-tip"`.
+ *
+ * 既定のホバー note tip (v0.8 §4.1.16): ホバーセルのノートを示す読み取り専用の `role="tooltip"`。
+ * 操作子は持たない — 消灯はフック (離脱猶予 / Escape step 0) が担い、ホバーセルが active の間は
+ * シンクが aria-describedby で参照する。
+ */
+
+import type { ReactNode } from "react"
+import type { SpreadsheetLabels } from "../model/labels.ts"
+import type { NoteTipContext } from "./usePopovers.ts"
+
+export type NoteTipProps = { ctx: NoteTipContext; labels: SpreadsheetLabels }
+
+/**
+ * Renders the note tip text.
+ * note tip の本文を描画する。
+ */
+export const NoteTip = ({ ctx }: NoteTipProps): ReactNode => (
+    <div className="aqsp-popover-note-tip" data-aqsp-popover="note-tip" role="tooltip">
+        {ctx.current}
+    </div>
+)

package/src/popover/PopoverLayer.tsx

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview The popover layer DOM (v0.8 §4.1.15 — ADR-15): a sibling of the selection
+ * overlay inside `.aqsp-body-stack` holding the TWO resident anchors (`interactive`, `tip`) the
+ * overlay's repaintOverlay positions through the refs handed in here. A popover frame is mounted
+ * INSIDE its anchor only while the controller has a context (lazy mount — a closed layer renders
+ * the two empty anchors and nothing else); the frame is placed by `placePopover` relative to the
+ * anchor cell, so it follows the anchor through scrolling for free. A closed anchor is `inert`
+ * (it neither intercepts pointer events nor takes focus). The overlay's `placeAnchor` hides an
+ * anchor without a cell, outside the viewport or under a frozen band by CLIPPING it
+ * (`clip-path`), never by un-rendering it: an open frame — its focused textarea, its draft —
+ * stays mounted and focused while hidden and simply reappears when the cell scrolls back
+ * (hide-and-restore, plan §5.7-13; `display: none` would fire the browser's focus fixup and the
+ * editor's focus-leave rule). A frame is keyed by kind + cell, so re-opening the same kind on another
+ * cell remounts its component (fresh draft) while a rejected re-present on the same cell keeps
+ * it (the draft survives for the retry); every presented context is re-PLACED though — a same-cell
+ * re-present (a rejected retry, an inputMessage replaced by a strict rejection) re-measures at the
+ * new content so the previous `maxHeight` never clips it — while the initial focus fires once per
+ * placement (a re-present does not steal the caret). The layer also owns the cross-kind wiring: the IME guard
+ * (`isCompositionKeydown` swallowed in the capture phase before any popover handler), the
+ * compositionend registration, the Escape fallback (an un-prevented Escape closes — the default
+ * components prevent their own), and the initial focus (`[data-aqsp-popover-autofocus]`, skipped
+ * for the passive `message` kind). `renderPopover` replaces the default components per context.
+ * DOM hooks: `[data-aqsp-popover-layer]`, `[data-aqsp-popover-anchor="interactive" | "tip"]`,
+ * `[data-aqsp-popover-frame="<kind>"]`, `[data-aqsp-popover-open]` on an anchor holding a frame
+ * (anchor open-state only — the link editor's Open button is `data-aqsp-link-open`).
+ *
+ * ポップオーバー層の DOM (v0.8 §4.1.15 — ADR-15)。`.aqsp-body-stack` 内で選択 overlay の兄弟と
+ * して、overlay の repaintOverlay がここで渡す ref 経由で配置する 2 つの常設アンカー
+ * (`interactive` / `tip`) を持つ。フレームはコントローラに文脈があるときだけアンカーの**内側**へ
+ * マウントする (遅延マウント — 閉じた層は空のアンカー 2 つ以外を描かない)。フレームは
+ * placePopover でアンカーセル相対に置くので、スクロールにはアンカーごと追随する。閉じたアンカーは
+ * `inert` (ポインタも取らずフォーカスも受けない)。セルの無い / viewport 外 / 凍結帯の下のアンカーは
+ * overlay の placeAnchor が **clip** (`clip-path`) で隠し、描画から外すことはしない: 開いたフレーム
+ * (フォーカス中の textarea も下書きも) は隠れている間もマウント + フォーカスのまま残り、セルが戻れば
+ * そのまま再び見える (隠して戻す — 計画 §5.7-13。`display: none` はブラウザの focus fixup とエディタの
+ * focus-leave 規則を起こす)。フレームは kind + セルをキーにするため、同じ kind を別セルで開き直すとコンポーネントは
+ * 再マウント (新しい下書き)、同セルの拒否再提示は保持 (再試行のため下書きが残る)。ただし提示された文脈は
+ * 毎回**再配置**する — 同セルの再提示 (拒否の再試行、inputMessage の strict 拒否への差替) も新しい内容で
+ * 再計測し、前回の maxHeight が切り詰めない。初期フォーカスは配置 (kind + セル) につき 1 回
+ * (再提示はキャレットを奪わない)。
+ * 層は kind 横断の結線も所有: IME ガード (capture 段で isCompositionKeydown を握り潰す)、
+ * compositionend 登録、Escape フォールバック (preventDefault されていない Escape は閉じる —
+ * 既定コンポーネントは自前で prevent する)、初期フォーカス (`[data-aqsp-popover-autofocus]`、受動的な
+ * `message` は省く)。`renderPopover` は文脈ごとに既定コンポーネントを置き換える。
+ */
+
+import { type CompositionEvent, type KeyboardEvent, type ReactNode, type RefObject, useLayoutEffect, useRef } from "react"
+import type { SpreadsheetLabels } from "../model/labels.ts"
+import { CommentPopover } from "./CommentPopover.tsx"
+import { LinkPopover } from "./LinkPopover.tsx"
+import { ListPopover } from "./ListPopover.tsx"
+import { MessagePopover } from "./MessagePopover.tsx"
+import { NotePopover } from "./NotePopover.tsx"
+import { NoteTip } from "./NoteTip.tsx"
+import { placePopover, popoverWidth } from "./placement.ts"
+import type { PopoverContext, PopoverController } from "./usePopovers.ts"
+
+export type PopoverLayerProps = {
+    controller: PopoverController
+    /** Consumer replacement of the default components (receives the discriminated context). / 既定コンポーネントの差替 (判別文脈を受け取る)。 */
+    renderPopover?: (ctx: PopoverContext) => ReactNode
+    labels: SpreadsheetLabels
+    /** The interactive anchor node (positioned by the overlay). / 対話アンカーノード (overlay が配置)。 */
+    interactiveAnchorRef: RefObject<HTMLDivElement | null>
+    /** The tip anchor node (positioned by the overlay). / tip アンカーノード (overlay が配置)。 */
+    tipAnchorRef: RefObject<HTMLDivElement | null>
+}
+
+/** The default component per kind. / kind 毎の既定コンポーネント。 */
+const renderDefault = (ctx: PopoverContext, labels: SpreadsheetLabels): ReactNode => {
+    switch (ctx.kind) {
+        case "note":
+            return <NotePopover ctx={ctx} labels={labels} />
+        case "note-tip":
+            return <NoteTip ctx={ctx} labels={labels} />
+        case "comment":
+            return <CommentPopover ctx={ctx} labels={labels} />
+        case "link":
+            return <LinkPopover ctx={ctx} labels={labels} />
+        case "list":
+            return <ListPopover ctx={ctx} labels={labels} />
+        default:
+            return <MessagePopover ctx={ctx} labels={labels} />
+    }
+}
+
+/** Identity of a placement (kind + cell) — the frame key and the initial-focus once-guard; a rejected re-present keeps both (no remount / re-focus) but IS re-placed. / 配置の同一性 (kind + セル) — フレームキー兼初期フォーカスの既済ガード。拒否再提示はどちらも保つ (再マウント / 再フォーカスなし) が再配置はする。 */
+const placementKeyOf = (ctx: PopoverContext | null): string | null => (ctx === null ? null : `${ctx.kind}:${ctx.cell.row}:${ctx.cell.col}`)
+
+/**
+ * Renders the layer, its two anchors and the lazily mounted frames.
+ * 層・2 アンカー・遅延マウントされるフレームを描画する。
+ */
+export const PopoverLayer = ({ controller, renderPopover, labels, interactiveAnchorRef, tipAnchorRef }: PopoverLayerProps): ReactNode => {
+    const { context, tipContext } = controller
+    const frameRef = useRef<HTMLDivElement | null>(null)
+    const tipFrameRef = useRef<HTMLDivElement | null>(null)
+    // tip effect は ref 経由で最新値を読む (deps は配置の同一性だけ — tip の内容は同セルでは変わらない)
+    const tipContextRef = useRef(tipContext)
+    tipContextRef.current = tipContext
+    const controllerRef = useRef(controller)
+    controllerRef.current = controller
+    const placementKey = placementKeyOf(context)
+    const tipPlacementKey = placementKeyOf(tipContext)
+    /** The placement that already received its initial focus — a re-present re-places but must not move the caret. / 初期フォーカス既済の配置 — 再提示は再配置するがキャレットは動かさない。 */
+    const focusedPlacementRef = useRef<string | null>(null)
+
+    /**
+     * Places a frame relative to its anchor cell: the width (`popoverWidth` of the layer) is
+     * written and any previous clamp is cleared BEFORE the height is measured, so the measured
+     * height is the wrapped height at the final width (a narrower layer wraps more lines; the
+     * un-keyed tip frame carries the previous cell's `maxHeight`) — one forced layout per placement.
+     * フレームをアンカーセル相対に配置する: 幅 (層の popoverWidth) を書き前回のクランプを外して**から**
+     * 高さを測る — 計測値は最終幅で折り返した実高になる (狭い層は行数が増え、キー無しの tip フレームは
+     * 前セルの maxHeight を持ち越す)。配置 1 回につき forced layout は 1 回。
+     */
+    const place = (frame: HTMLDivElement, anchorRect: { top: number; left: number; width: number; height: number }): void => {
+        const layer = controllerRef.current.getLayerSize()
+        // 幅を確定しクランプを外してから測る (折り返し後の実高で候補判定する)
+        frame.style.width = `${popoverWidth(layer)}px`
+        frame.style.maxHeight = ""
+        const placed = placePopover(anchorRect, frame.offsetHeight, layer)
+        // アンカーはセル左上に置かれる — 層座標からアンカー相対へ
+        frame.style.left = `${placed.left - anchorRect.left}px`
+        frame.style.top = `${placed.top - anchorRect.top}px`
+        frame.style.maxHeight = `${placed.height}px`
+    }
+
+    useLayoutEffect(() => {
+        const frame = frameRef.current
+        if (frame === null || context === null) {
+            // 閉じたら既済を戻す (同セルの開き直しは新フレームなので初期フォーカスをやり直す)
+            focusedPlacementRef.current = null
+            return
+        }
+        // 同セル再提示 (拒否の再試行 / inputMessage → strict 拒否の差替) も毎回再計測する — 前回の maxHeight で新しい文面を切らない
+        place(frame, context.anchorRect)
+        // 受動的な message はフォーカスを奪わない (入力はシンクで続く)
+        if (context.kind === "message") {
+            return
+        }
+        // 初期フォーカスは配置につき 1 回 — 再提示で下書きのキャレットを奪い直さない
+        const key = placementKeyOf(context)
+        if (focusedPlacementRef.current === key) {
+            return
+        }
+        focusedPlacementRef.current = key
+        const target = frame.querySelector<HTMLElement>("[data-aqsp-popover-autofocus]")
+        if (target !== null) {
+            target.focus({ preventScroll: true })
+        } else {
+            frame.focus({ preventScroll: true })
+        }
+    }, [context])
+
+    useLayoutEffect(() => {
+        const frame = tipFrameRef.current
+        const ctx = tipContextRef.current
+        if (frame === null || ctx === null) {
+            return
+        }
+        place(frame, ctx.anchorRect)
+    }, [tipPlacementKey])
+
+    const render = (ctx: PopoverContext): ReactNode => (renderPopover === undefined ? renderDefault(ctx, labels) : renderPopover(ctx))
+    const onKeyDownCapture = (event: KeyboardEvent<HTMLDivElement>): void => {
+        // IME 由来の keydown は全 popover ハンドラより先に握り潰す (Escape / Enter が変換確定を壊さない)
+        if (controller.isCompositionKey(event.nativeEvent)) {
+            event.stopPropagation()
+        }
+    }
+    const onKeyDown = (event: KeyboardEvent<HTMLDivElement>): void => {
+        // フォールバック: コンポーネントが処理しなかった Escape は閉じる
+        if (event.key === "Escape" && !event.defaultPrevented) {
+            event.preventDefault()
+            controller.close()
+        }
+    }
+    const onCompositionEnd = (event: CompositionEvent<HTMLDivElement>): void => {
+        controller.registerCompositionEnd(event.timeStamp)
+    }
+
+    return (
+        // biome-ignore lint/a11y/noStaticElementInteractions: 層は kind 横断の keydown 結線点 (IME ガード / Escape フォールバック) — 対話子孫のイベントを受けるだけで自身は操作面でない
+        <div className="aqsp-popover-layer" data-aqsp-popover-layer="" onKeyDownCapture={onKeyDownCapture} onKeyDown={onKeyDown} onCompositionEnd={onCompositionEnd}>
+            <div ref={interactiveAnchorRef} className="aqsp-popover-anchor" data-aqsp-popover-anchor="interactive" data-aqsp-popover-open={context === null ? undefined : ""} inert={context === null}>
+                {context === null ? null : (
+                    // フレームは autofocus 対象のない消費者レンダラのフォーカス着地点 (tabIndex -1 = プログラム的にだけ受ける)
+                    <div key={placementKey} ref={frameRef} className="aqsp-popover" data-aqsp-popover-frame={context.kind} tabIndex={-1}>
+                        {render(context)}
+                    </div>
+                )}
+            </div>
+            <div
+                ref={tipAnchorRef}
+                className="aqsp-popover-anchor"
+                data-aqsp-popover-anchor="tip"
+                data-aqsp-popover-open={tipContext === null ? undefined : ""}
+                inert={tipContext === null}
+                onPointerEnter={controller.onTipPointerEnter}
+                onPointerLeave={controller.onTipPointerLeave}>
+                {tipContext === null ? null : (
+                    <div ref={tipFrameRef} id={controller.tipId} className="aqsp-popover" data-aqsp-popover-frame="note-tip">
+                        {render(tipContext)}
+                    </div>
+                )}
+            </div>
+        </div>
+    )
+}