@aiquants/spreadsheet 0.16.1 → 0.17.0

package/src/Spreadsheet.tsx

@@ -53,7 +53,7 @@ import { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle
 import type { ClipChannel } from "./clipboard/clipPayload.ts"
 import type { PasteOptions } from "./clipboard/pasteSpecial.ts"
 import { type ClipInfo, type PasteOutcome, type PasteSheet, useClipboard } from "./clipboard/useClipboard.ts"
-import { type BorderPreset, type CommandRunner, useCommands } from "./commands/useCommands.ts"
+import { type BorderPreset, type CommandRunner, type KeyboardCellRect, useCommands } from "./commands/useCommands.ts"
 import { type SinkSnapshot, useCellEditor } from "./editor/useCellEditor.ts"
 import type { RenderCellContext } from "./grid/CellView.tsx"
 import { GridBody } from "./grid/GridBody.tsx"
@@ -85,7 +85,7 @@ import { clampSelectionToGrid, reduceActiveCycle, reduceSelectionExtend, reduceS
 import { useAutoScroller } from "./selection/useAutoScroller.ts"
 import { type PointDragOwner, usePointDrag } from "./selection/usePointDrag.ts"
 import { useSelectionEngine } from "./selection/useSelectionEngine.ts"
-import { clampSpreadsheetZoom, SPREADSHEET_DEFAULT_COLUMN_WIDTH_PX, SPREADSHEET_MAX_OPERATION_CELLS, stepSpreadsheetZoom } from "./view.ts"
+import { clampSpreadsheetZoom, SPREADSHEET_DEFAULT_COLUMN_WIDTH_PX, SPREADSHEET_MAX_OPERATION_CELLS, SPREADSHEET_SCROLLBAR_SIZE_PX, stepSpreadsheetZoom } from "./view.ts"
 
 export type { SelectionState } from "./selection/selectionState.ts"
 
@@ -103,12 +103,42 @@ export type { SelectionState } from "./selection/selectionState.ts"
  */
 export type ScrollToCellOptions = { alignY?: "top" | "bottom" | "center"; alignX?: "start" | "end" | "center"; offsetX?: number; offsetY?: number }
 
+/**
+ * The size of a grid's content in CSS px of the page (v0.17): the column-letter and row-number bands (0 when `headings`
+ * is false), every column and row at its current size, and the two scroll bars the grid always reserves, all scaled by
+ * the zoom — the box a host gives the grid to show every column and row without scrolling.
+ * グリッドの中身の大きさ (ページの CSS px。v0.17)。列の記号と行の番号の帯 (`headings` が false なら 0)、今の大きさの全部の列と行、
+ * グリッドがいつも取る 2 本のスクロールバーを、どれも倍率で伸び縮みさせたもの。ホストがスクロールなしで全部の列と行を見せる箱の大きさ。
+ */
+export type SpreadsheetContentSize = {
+    /** The width in CSS px. 幅 (CSS px)。 */
+    readonly width: number
+    /** The height in CSS px. 高さ (CSS px)。 */
+    readonly height: number
+}
+
 /** Imperative surface (§6.9-8). / 命令 API (§6.9-8)。 */
 export type SpreadsheetHandle = {
     /** Row-height pair seam (§6.9-8). / 行高変更の対シーム。 */
     resizeRow: (row: number, heightPx: number) => void
     /** Column-width resize (§6.9-8). / 列幅変更。 */
     resizeColumn: (col: number, widthPx: number) => void
+    /**
+     * Fits each listed column to the widest text of ALL its rows (header rows included; v0.17), as Alt+Shift+= fits the
+     * active column over the rows in view: the same painted fonts, the 9 px padding and the 10,000 px bound, measured with
+     * the cells' base font. A hidden column keeps its width and so does an empty one. Refused through
+     * onOperationRejected("resize", cells, "limit") when the cells to measure exceed `maxOperationCells`. Works whatever
+     * `enableResizeUI` and `headings` say (an imperative path, like resizeColumn).
+     * 名指した列を、その列の**全部の行** (見出しの行も) で最も広い文字に合わせる (v0.17)。Alt+Shift+= が表示中の行で active 列を
+     * 合わせるのと同じ塗りの書体・余白 9 px・上限 10,000 px で、セルの基本の書体で測る。隠した列と空の列は幅を保つ。測るセルが
+     * `maxOperationCells` を超えると onOperationRejected("resize", セル, "limit") で拒む。`enableResizeUI` と `headings` に依らず
+     * 働く (resizeColumn と同じ命令の経路)。
+     *
+     * @param columns - The columns to fit (repeats count once). 合わせる列 (重複は 1 回)。
+     * @returns True when the fit ran (a hidden or empty column changes nothing); false when refused or when the grid cannot measure (`renderCell` is set, or the grid is not mounted). 走ったら true (隠した列・空の列は何も変えない)。拒まれたとき・測れないとき (`renderCell` がある、または未装着) は false。
+     * @throws {RangeError} When a column is not an integer between 0 and the column count − 1. 列が 0〜列数 − 1 の整数でない場合。
+     */
+    autoFitColumns: (columns: readonly number[]) => boolean
     /**
      * Programmatic viewport jump to a cell (delegates to the engine's scrollToCell — the
      * floor-and-pin jump API). Selection is unchanged; the deep grid stays reachable at any
@@ -448,6 +478,29 @@ export type SpreadsheetProps = {
      * 復元手段を失う (命令 API のみ)。
      */
     enableResizeUI?: boolean
+    /**
+     * v0.17 — Shows the column letters, the row numbers and the corner (Excel's "headings"; not `headerRows`), true by
+     * default. False draws none of the three and collapses their grid tracks to 0, so the cells start at the grid's
+     * top-left corner; the gestures that live only on them go with them (header presses, the corner's select-all, the
+     * resize strips and unhide markers), and their keyboard twins stay (Ctrl+Space, Shift+Space, Ctrl+A, Alt+Shift+Arrow,
+     * Alt+Shift+=). The bands are `aria-hidden`, so assistive technology meets the same grid. The root carries
+     * `data-aqsp-headings-hidden` while they are hidden. LIVE prop.
+     * v0.17 — 列の記号・行の番号・角 (Excel の「見出し」。`headerRows` とは別) を見せるか (既定 true)。false は 3 つを描かず、
+     * その格子の帯を 0 にしてセルを根の左上から始める。それらの上にだけある操作 (見出しの押下・角の全選択・境の帯と再表示の印) は
+     * 無くなり、キーの双子 (Ctrl+Space・Shift+Space・Ctrl+A・Alt+Shift+矢印・Alt+Shift+=) は残る。帯は `aria-hidden` なので、
+     * 支援技術から見えるグリッドは変わらない。隠している間、根は `data-aqsp-headings-hidden` を持つ。
+     */
+    headings?: boolean
+    /**
+     * v0.17 — Receives the size of the grid's content (`SpreadsheetContentSize`) after the first layout and again after
+     * every change of it: a track's size (a resize, an autofit, a hide or unhide, the imperative resizeRow / resizeColumn),
+     * the row or column count, the default sizes, the zoom or `headings`. An unchanged size is not repeated. A host uses it
+     * to size the grid's box to its content.
+     * v0.17 — グリッドの中身の大きさ (`SpreadsheetContentSize`) を、最初の配置の後と、それが変わるたびに受け取る (トラックの
+     * 大きさ — 境の操作・autofit・隠す・再表示・命令の resizeRow / resizeColumn —、行や列の数、既定の大きさ、倍率、`headings`)。
+     * 同じ大きさは繰り返さない。ホストはこれでグリッドの箱を中身に合わせる。
+     */
+    onContentSizeChange?: (size: SpreadsheetContentSize) => void
     /**
      * AT announcement text for the active cell; omit for silence (no built-in strings). `text`
      * is the RAW canonical getCellText; `displayText` is the value-format display string (the
@@ -837,6 +890,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         maxOperationCells = SPREADSHEET_MAX_OPERATION_CELLS,
         enableFillHandle = true,
         enableResizeUI = true,
+        headings = true,
+        onContentSizeChange,
         formatCellAnnouncement,
         formatSelectionAnnouncement,
         formatCommandAnnouncement,
@@ -1064,6 +1119,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         }
     }, [requestZoom, zoomGestureEnabled])
     const bodyRef = useRef<HTMLDivElement | null>(null)
+    const bodyStackRef = useRef<HTMLDivElement | null>(null)
+    const revealRef = useRef<HTMLDivElement | null>(null)
     const handleRef = useRef<VirtualGridHandle | null>(null)
     const sinkRef = useRef<HTMLTextAreaElement | null>(null)
     const rowTrackRef = useRef<HTMLDivElement | null>(null)
@@ -1347,9 +1404,133 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         ensureDepsRef.current = { rowAxis, colAxis }
         ensureCellVisibleRef.current = createEnsureCellVisible({ handleRef, rowAxis, colAxis })
     }
-    const ensureCellVisible = useCallback((cell: CellCoord) => {
-        ensureCellVisibleRef.current?.(cell)
-    }, [])
+    /**
+     * A cell's rect in visual px relative to the body pane, read now through the three-way forward map (v0.9 §4.9 census
+     * #11 — the keyboard-origin cellRect recipe, the onCellContextMenu twin): the one judgment site of this file, shared by
+     * the keyboard cellRect and the page reveal.
+     * セルの本体ペイン基準の視覚 px 矩形 (3 分岐順写像の判断時読み — v0.9 §4.9 census #11 の keyboard 起点 cellRect のレシピ、
+     * onCellContextMenu と同式)。このファイル唯一の判断点で、keyboard の cellRect とページの追従が共有する。
+     *
+     * @param cell - The cell. セル。
+     * @returns The rect in visual px. 視覚 px の矩形。
+     */
+    const cellRectOf = useCallback(
+        (cell: CellCoord): KeyboardCellRect => {
+            const handle = handleRef.current
+            const position = handle === null ? { x: 0, y: 0 } : handle.getScrollPosition()
+            // 帯件数と extent も同じ判断で読む (v0.9 計画 §4.9、census #11 — AxisForwardCtx はこの場で
+            // インライン構築、§2.1 規則 1)。detached ハンドルは件数 0 / extent 0 の縮退 (末尾分岐不活性 = v0.8 恒等)
+            const frozen = handle === null ? { rows: 0, cols: 0, trailingRows: 0, trailingCols: 0 } : handle.getFrozenSize()
+            const viewport = handle === null ? { width: 0, height: 0 } : handle.getViewportSize()
+            // 両軸とも番兵クランプ (detached の {-1, -1} を座標へ流さない)、ズーム境界で視覚 px へ
+            const z = zoomRef.current
+            return {
+                // 行 / 列とも凍結パーティション 3 分岐順写像 (末尾は extent アンカー — v0.9 §2.1)。×zoom は写像後 (契約不変)
+                top: rowToViewportY(rowAxis, cell.row, { scroll: Math.max(0, position.y), frozenCount: frozen.rows, trailingCount: frozen.trailingRows, extent: viewport.height }) * z,
+                left: colToViewportX(colAxis, cell.col, { scroll: Math.max(0, position.x), frozenCount: frozen.cols, trailingCount: frozen.trailingCols, extent: viewport.width }) * z,
+                width: colAxis.sizeOf(cell.col) * z,
+                height: rowAxis.sizeOf(cell.row) * z,
+            }
+        },
+        [rowAxis, colAxis],
+    )
+
+    /**
+     * Brings a cell the grid has just landed in its own viewport into view in the scroll containers outside the grid (a
+     * host's box, the page), by the least scroll (block and inline "nearest", honouring their scroll-padding): a grid
+     * taller or wider than its scroll container would otherwise keep the active cell off-screen, since the grid sees it
+     * inside its own viewport (WCAG 2.4.11 / 2.4.12). The marker sits under the root, outside every container inside the
+     * grid, and is clipped to the root's box, so only containers outside the grid move.
+     * グリッドが自分の表示域の中へ着地させたセルを、グリッドの外のスクロールの容器 (ホストの箱・ページ) の中でも最小の量で見せる
+     * 処理 (block・inline とも nearest、容器の scroll-padding に従う)。スクロールの容器より高い・広いグリッドでは、グリッドは自分の
+     * 表示域の中にセルを見ているため、選んだセルが画面の外に残る (WCAG 2.4.11・2.4.12)。印は根の直下でグリッドの中のどの容器の
+     * 外にも置き、根の箱に切り詰めるので、動くのはグリッドの外の容器だけ。
+     *
+     * @param cell - The cell, already in the grid's viewport. グリッドの表示域に着地済みのセル。
+     */
+    const revealCellInPage = useCallback(
+        (cell: CellCoord): void => {
+            const marker = revealRef.current
+            const root = rootRef.current
+            const stack = bodyStackRef.current
+            if (marker === null || root === null || stack === null || handleRef.current === null) {
+                return
+            }
+            const z = zoomRef.current
+            const rect = cellRectOf(cell)
+            // 本体ペインの原点は帯の分だけ根の左上から離れる (論理 px の offset を倍率で視覚 px へ)
+            const top = stack.offsetTop * z + rect.top
+            const left = stack.offsetLeft * z + rect.left
+            // 根は overflow: hidden のスクロールの容器。印が根の箱からはみ出すと scrollIntoView が根自身を動かすので、根の箱に切り詰める
+            const clippedTop = Math.max(0, top)
+            const clippedLeft = Math.max(0, left)
+            const clippedBottom = Math.min(root.clientHeight, top + rect.height)
+            const clippedRight = Math.min(root.clientWidth, left + rect.width)
+            if (clippedBottom <= clippedTop || clippedRight <= clippedLeft) {
+                return
+            }
+            marker.style.top = `${clippedTop}px`
+            marker.style.left = `${clippedLeft}px`
+            marker.style.width = `${clippedRight - clippedLeft}px`
+            marker.style.height = `${clippedBottom - clippedTop}px`
+            // 配置された箱を持たない印 (display: none の中のグリッド) には見せる位置が無い
+            const box = marker.getBoundingClientRect()
+            if (box.width === 0 && box.height === 0) {
+                return
+            }
+            marker.scrollIntoView({ block: "nearest", inline: "nearest" })
+        },
+        [cellRectOf],
+    )
+
+    const ensureCellVisible = useCallback(
+        (cell: CellCoord) => {
+            ensureCellVisibleRef.current?.(cell)
+            revealCellInPage(cell)
+        },
+        [revealCellInPage],
+    )
+
+    // ---- 中身の大きさの知らせ (v0.17) ----
+    const onContentSizeChangeRef = useRef(onContentSizeChange)
+    onContentSizeChangeRef.current = onContentSizeChange
+    const reportedContentSizeRef = useRef<SpreadsheetContentSize | null>(null)
+    /**
+     * Reports the content size to `onContentSizeChange` when it differs from the last one reported: the bands' tracks (the
+     * body pane's offset in the zoom wrapper, so a host's band-size variables and `headings` count as laid out), every
+     * track, and the two scroll bars the grid always reserves, all inside the zoom wrapper and so scaled by the zoom.
+     * 中身の大きさを、前に知らせたものと違うときだけ `onContentSizeChange` へ知らせる処理。帯の格子の帯 (ズームの包みの中の本体
+     * ペインの位置なので、ホストの帯の寸法の変数と `headings` が配置どおりに入る)、全部のトラック、グリッドがいつも取る 2 本の
+     * スクロールバーで、どれもズームの包みの中にあるので倍率で伸び縮みする。
+     */
+    const reportContentSize = useCallback((): void => {
+        const listener = onContentSizeChangeRef.current
+        const stack = bodyStackRef.current
+        if (listener === undefined || stack === null) {
+            return
+        }
+        const z = zoomRef.current
+        const size: SpreadsheetContentSize = {
+            width: (stack.offsetLeft + colAxis.totalSize() + SPREADSHEET_SCROLLBAR_SIZE_PX) * z,
+            height: (stack.offsetTop + rowAxis.totalSize() + SPREADSHEET_SCROLLBAR_SIZE_PX) * z,
+        }
+        const last = reportedContentSizeRef.current
+        if (last !== null && last.width === size.width && last.height === size.height) {
+            return
+        }
+        reportedContentSizeRef.current = size
+        listener(size)
+    }, [rowAxis, colAxis])
+    // 描画のたびに測る (倍率・headings・行と列の数・既定の大きさの変化はどれも再描画を伴う)。知らせる先が外れたら次に付いた先へ
+    // 今の大きさを改めて知らせ、同じ関数でない新しい知らせ先 (描画ごとに作るアロー関数) には値が変わるまで繰り返さない (同じ値の
+    // 再送が知らせ先の状態更新と再描画を無限に回すため)
+    useLayoutEffect(() => {
+        if (onContentSizeChange === undefined) {
+            reportedContentSizeRef.current = null
+            return
+        }
+        reportContentSize()
+    })
 
     // ---- 読み上げ (live region — §6.9-9) ----
     const announceTimerRef = useRef<number | null>(null)
@@ -1755,6 +1936,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 // 同期 repaint はエンジン再レンダー前の stale getFrozenSize — 分割線可視は
                 // post-commit heal が commit 済み値で整合させる (§2.7 — スクロール介在なし)
                 scheduleDividerHeal()
+                // 寸法の変更は再描画を伴わない命令の経路なので、描画の後の知らせを待たずにここで知らせる
+                reportContentSize()
                 return
             }
             for (const entry of entries) {
@@ -1768,8 +1951,9 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
             repaintOverlay()
             // 行側も同文 (H_F / H_T の分割線可視は commit 済み値で heal — §2.7)
             scheduleDividerHeal()
+            reportContentSize()
         },
-        [rowAxis, colAxis, viewStore, repaintColHeaders, repaintHeaders, repaintOverlay, scheduleDividerHeal],
+        [rowAxis, colAxis, viewStore, repaintColHeaders, repaintHeaders, repaintOverlay, scheduleDividerHeal, reportContentSize],
     )
 
     /** Pointer contextmenu relay to onCellContextMenu (§6.4.3-4 sole channel). / pointer 起点の横流し。 */
@@ -1864,9 +2048,10 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     })
 
     // ---- ヘッダー選択 (§6.8 — 列 / 行の転置共通機械) ----
+    // 帯の上の機械は帯があるときだけ結線する (headings を切り替えると依存が変わり、新しい帯の要素へ結線し直す)
     const colHeaderMachine = useHeaderSelection({
         zoomRef,
-        enabled: !isEmpty,
+        enabled: !isEmpty && headings,
         axis: "col",
         headerRef: colHeaderRef,
         mainAxis: colAxis,
@@ -1885,7 +2070,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     })
     const rowHeaderMachine = useHeaderSelection({
         zoomRef,
-        enabled: !isEmpty,
+        enabled: !isEmpty && headings,
         axis: "row",
         headerRef: rowHeaderRef,
         mainAxis: rowAxis,
@@ -1906,9 +2091,10 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     // ---- リサイズ / unhide 機械 (§7 PT-1) + fill 機械 (§8 PT-2) ----
     const headerResizeMachine = useHeaderResize({
         zoomRef,
-        enabled: !isEmpty && enableResizeUI,
+        enabled: !isEmpty && enableResizeUI && headings,
         colBandRef: colHeaderRef,
         rowBandRef: rowHeaderRef,
+        fontSourceRef: bodyRef,
         colAxis,
         rowAxis,
         viewStore,
@@ -2144,26 +2330,12 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
 
     // ---- コマンド実行 (v0.8 §4.1.13 / ADR-17) ----
     /** The active cell's viewport rect in visual px via the three-way forward map (v0.9 §4.9 census #11 — the keyboard-origin cellRect recipe, onCellContextMenu twin) for onPasteSpecialRequest. / active セルの視覚 px 矩形 — 3 分岐順写像 (v0.9 §4.9 census #11。keyboard 起点 cellRect のレシピ、onCellContextMenu と同式)。 */
-    const keyboardCellRect = useCallback(() => {
+    const keyboardCellRect = useCallback((): KeyboardCellRect => {
         const active = selectionRef.current.active
         // 画面外座標へメニューを出さない (§6.6.1) — 可視化してからハンドルの同期読み (§7-4)
         ensureCellVisible(active)
-        const handle = handleRef.current
-        const position = handle === null ? { x: 0, y: 0 } : handle.getScrollPosition()
-        // 帯件数と extent も同じ判断で読む (v0.9 計画 §4.9、census #11 — AxisForwardCtx はこの場で
-        // インライン構築、§2.1 規則 1)。detached ハンドルは件数 0 / extent 0 の縮退 (末尾分岐不活性 = v0.8 恒等)
-        const frozen = handle === null ? { rows: 0, cols: 0, trailingRows: 0, trailingCols: 0 } : handle.getFrozenSize()
-        const viewport = handle === null ? { width: 0, height: 0 } : handle.getViewportSize()
-        // 両軸とも番兵クランプ (detached の {-1, -1} を座標へ流さない)、ズーム境界で視覚 px へ
-        const z = zoomRef.current
-        return {
-            // 行 / 列とも凍結パーティション 3 分岐順写像 (末尾は extent アンカー — v0.9 §2.1)。×zoom は写像後 (契約不変)
-            top: rowToViewportY(rowAxis, active.row, { scroll: Math.max(0, position.y), frozenCount: frozen.rows, trailingCount: frozen.trailingRows, extent: viewport.height }) * z,
-            left: colToViewportX(colAxis, active.col, { scroll: Math.max(0, position.x), frozenCount: frozen.cols, trailingCount: frozen.trailingCols, extent: viewport.width }) * z,
-            width: colAxis.sizeOf(active.col) * z,
-            height: rowAxis.sizeOf(active.row) * z,
-        }
-    }, [rowAxis, colAxis, ensureCellVisible])
+        return cellRectOf(active)
+    }, [ensureCellVisible, cellRectOf])
     const commands = useCommands({
         adapter,
         // キーボードの寸法の変更は帯のリサイズ UI と同じ可否 (enableResizeUI が false なら利用者は寸法を変えない)
@@ -2725,6 +2897,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 repaintOverlay()
                 // 分割線可視は commit 済み getFrozenSize の post-commit heal で整合 (§2.7)
                 scheduleDividerHeal()
+                reportContentSize()
             },
             resizeColumn: (col: number, widthPx: number) => {
                 // 対呼び出し (§3.8): colAxis (SSOT) を先に更新し、グリッドの幅木へ通知する。
@@ -2739,6 +2912,15 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 repaintOverlay()
                 // 分割線可視は commit 済み getFrozenSize の post-commit heal で整合 (§2.7)
                 scheduleDividerHeal()
+                reportContentSize()
+            },
+            autoFitColumns: (columns: readonly number[]) => {
+                for (const col of columns) {
+                    if (!Number.isInteger(col) || col < 0 || col >= colAxis.count) {
+                        throw new RangeError(`[spreadsheet] autoFitColumns: each column must be a whole number from 0 to ${colAxis.count - 1} (got ${String(col)})`)
+                    }
+                }
+                return headerResizeMachine.autofitColumnsInAllRows(columns)
             },
             scrollToCell: (cell: CellCoord, options?: ScrollToCellOptions) => {
                 // エンジンのセル狙いジャンプへ素通し (§7-4 の真実。選択は変えない — 純 viewport 移動)。
@@ -2773,7 +2955,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 openPopoverRef.current(kind)
             },
         }),
-        [rowAxis, colAxis, viewStore, repaintColHeaders, repaintHeaders, repaintOverlay, scheduleDividerHeal, focusSink, isEditing, rearmSink, adapter, paintedFormatOf, startEdit, requireCommands],
+        [rowAxis, colAxis, viewStore, repaintColHeaders, repaintHeaders, repaintOverlay, scheduleDividerHeal, reportContentSize, headerResizeMachine, focusSink, isEditing, rearmSink, adapter, paintedFormatOf, startEdit, requireCommands],
     )
 
     // ---- 空グリッド分岐 (§6.9-1: フックの後・結線の前) ----
@@ -2791,75 +2973,79 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     return (
         // biome-ignore lint/a11y/useSemanticElements: fieldset はフォーム意味論であり不適。role="group" は Escape 脱出の着地点に現在地名を与えるための選択 (§6.9-7 / §10-4)
         // biome-ignore lint/a11y/noNoninteractiveTabindex: tabIndex=0 は WCAG 2.1.2 の脱出着地点 + グリッド再進入口 (§10-4) — 意図的な tab stop
-        <div ref={rootRef} className={className ? `aqsp-root ${className}` : "aqsp-root"} role="group" {...rootName} tabIndex={0} onFocus={onRootFocus} onBlur={onRootBlur} data-aqsp-root="" data-testid={testId}>
+        <div ref={rootRef} className={className ? `aqsp-root ${className}` : "aqsp-root"} role="group" {...rootName} tabIndex={0} onFocus={onRootFocus} onBlur={onRootBlur} data-aqsp-root="" data-aqsp-headings-hidden={headings ? undefined : ""} data-testid={testId}>
             {/* ズームラッパー (v0.3): 視覚は transform スケール、内側レイアウトは 100%/z の論理 px —
                 virtualscroll の実測 (ResizeObserver / clientHeight) は論理値のまま。z=1 は無スタイル
                 (v0.2 と byte 同一の DOM 幾何 — 既存全ゲートの不変性) */}
             <div className="aqsp-zoom" data-aqsp-zoom={zoomValue} onPointerDown={onZoomPointerDown} style={zoomValue === 1 ? undefined : { width: `${100 / zoomValue}%`, height: `${100 / zoomValue}%`, transform: `scale(${zoomValue})` }}>
-                <div
-                    className="aqsp-corner"
-                    aria-hidden="true"
-                    data-aqsp-corner=""
-                    onPointerDown={(event) => {
-                        // mouse 限定 (§6.4.1 の表ヘッダー「mouse のみ」— エンジン / ヘッダー機械と同一ゲート)
-                        if (event.pointerType !== "mouse") {
-                            return
-                        }
-                        // 非主ボタンも既定のフォーカス移動だけは止める (全押下面共通 — R2 是正)
-                        event.preventDefault()
-                        if (event.button !== 0) {
-                            return
-                        }
-                        // 参照ポインティング中 (v0.8 §4.2.13): コーナー押下は consume + シンクへ焦点 (全選択も確定もしない)
-                        if (isPointing()) {
-                            focusSink()
-                            return
-                        }
-                        // 編集中の requestCommit ゲート (§6.8-3 — コーナーもフォーカス不動で focusout 不発)
-                        if (isEditing() && !requestCommit()) {
-                            focusSink()
-                            return
-                        }
-                        focusSink()
-                        // コーナーの全セル選択は単一構築 state の setSelection 1 回 (過渡状態なし)。active = A1
-                        setSelection({
-                            ranges: [makeRange({ row: 0, col: 0 }, { row: adapter.rowCount - 1, col: adapter.colCount - 1 })],
-                            anchor: { row: 0, col: 0 },
-                            active: { row: 0, col: 0 },
-                        })
-                    }}
-                />
-                <ColumnHeader
-                    viewStore={viewStore}
-                    colAxis={colAxis}
-                    frozenCols={frozenColumns}
-                    frozenTrailingCols={frozenTrailingColumns}
-                    handleRef={handleRef}
-                    bandRef={colHeaderRef}
-                    colTrackRef={colTrackRef}
-                    windowOriginXRef={windowOriginXRef}
-                    repaintColHeaders={repaintColHeaders}
-                    selectionRanges={selection.ranges}
-                    enableResizeUI={enableResizeUI}
-                    dividerLeadingRef={dividerXLeadingRef}
-                    dividerTrailingRef={dividerXTrailingRef}
-                />
-                <RowHeader
-                    viewStore={viewStore}
-                    rowAxis={rowAxis}
-                    handleRef={handleRef}
-                    bandRef={rowHeaderRef}
-                    selectionRanges={selection.ranges}
-                    rowTrackRef={rowTrackRef}
-                    windowOriginYRef={windowOriginYRef}
-                    repaintHeaders={repaintHeaders}
-                    enableResizeUI={enableResizeUI}
-                    frozenRows={frozenRows}
-                    frozenTrailingRows={frozenTrailingRows}
-                    dividerLeadingRef={dividerYLeadingRef}
-                    dividerTrailingRef={dividerYTrailingRef}
-                />
-                <div className="aqsp-body-stack" data-aqsp-body-stack="">
+                {headings ? (
+                    <>
+                        <div
+                            className="aqsp-corner"
+                            aria-hidden="true"
+                            data-aqsp-corner=""
+                            onPointerDown={(event) => {
+                                // mouse 限定 (§6.4.1 の表ヘッダー「mouse のみ」— エンジン / ヘッダー機械と同一ゲート)
+                                if (event.pointerType !== "mouse") {
+                                    return
+                                }
+                                // 非主ボタンも既定のフォーカス移動だけは止める (全押下面共通 — R2 是正)
+                                event.preventDefault()
+                                if (event.button !== 0) {
+                                    return
+                                }
+                                // 参照ポインティング中 (v0.8 §4.2.13): コーナー押下は consume + シンクへ焦点 (全選択も確定もしない)
+                                if (isPointing()) {
+                                    focusSink()
+                                    return
+                                }
+                                // 編集中の requestCommit ゲート (§6.8-3 — コーナーもフォーカス不動で focusout 不発)
+                                if (isEditing() && !requestCommit()) {
+                                    focusSink()
+                                    return
+                                }
+                                focusSink()
+                                // コーナーの全セル選択は単一構築 state の setSelection 1 回 (過渡状態なし)。active = A1
+                                setSelection({
+                                    ranges: [makeRange({ row: 0, col: 0 }, { row: adapter.rowCount - 1, col: adapter.colCount - 1 })],
+                                    anchor: { row: 0, col: 0 },
+                                    active: { row: 0, col: 0 },
+                                })
+                            }}
+                        />
+                        <ColumnHeader
+                            viewStore={viewStore}
+                            colAxis={colAxis}
+                            frozenCols={frozenColumns}
+                            frozenTrailingCols={frozenTrailingColumns}
+                            handleRef={handleRef}
+                            bandRef={colHeaderRef}
+                            colTrackRef={colTrackRef}
+                            windowOriginXRef={windowOriginXRef}
+                            repaintColHeaders={repaintColHeaders}
+                            selectionRanges={selection.ranges}
+                            enableResizeUI={enableResizeUI}
+                            dividerLeadingRef={dividerXLeadingRef}
+                            dividerTrailingRef={dividerXTrailingRef}
+                        />
+                        <RowHeader
+                            viewStore={viewStore}
+                            rowAxis={rowAxis}
+                            handleRef={handleRef}
+                            bandRef={rowHeaderRef}
+                            selectionRanges={selection.ranges}
+                            rowTrackRef={rowTrackRef}
+                            windowOriginYRef={windowOriginYRef}
+                            repaintHeaders={repaintHeaders}
+                            enableResizeUI={enableResizeUI}
+                            frozenRows={frozenRows}
+                            frozenTrailingRows={frozenTrailingRows}
+                            dividerLeadingRef={dividerYLeadingRef}
+                            dividerTrailingRef={dividerYTrailingRef}
+                        />
+                    </>
+                ) : null}
+                <div ref={bodyStackRef} className="aqsp-body-stack" data-aqsp-body-stack="">
                     <GridBody
                         adapter={adapter}
                         rowAxis={rowAxis}
@@ -2934,6 +3120,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                 </div>
                 {hasAnnouncement ? <div ref={liveRegionRef} className="aqsp-live-region" aria-live="polite" data-aqsp-live-region="" /> : null}
             </div>
+            {/* キーの移動で選んだセルをページの中で見せる印 (位置は revealCellInPage が書く)。ズームの包みの外の根の直下に置き、グリッドの中の容器を動かさない */}
+            <div ref={revealRef} className="aqsp-reveal" aria-hidden="true" data-aqsp-reveal="" />
         </div>
     )
 })