@aiquants/spreadsheet 0.15.0 → 0.16.1

package/dist/view.d.ts

@@ -13,9 +13,22 @@
  */
 export declare const clampSpreadsheetZoom: (value: number) => number;
 
+/** Column index (0-based) to Excel-style name (0 → A, 26 → AA, 16383 → XFD). / 列 index → 列名。 */
+export declare const columnIndexToName: (index: number) => string;
+
 /** The height of the column-header band in CSS px (`--aqsp-col-header-height` in the stylesheet). 列見出しの帯の高さ (CSS px。スタイルシートの `--aqsp-col-header-height`)。 */
 export declare const SPREADSHEET_COLUMN_HEADER_HEIGHT_PX = 24;
 
+/** The default column width in CSS px, the width of every column the host does not size. 既定の列幅 (CSS px。ホストが寸法を決めない列の幅)。 */
+export declare const SPREADSHEET_DEFAULT_COLUMN_WIDTH_PX = 100;
+
+/**
+ * The default of `maxOperationCells` (ADR-12): the largest number of cells one operation (paste, fill, clear, format)
+ * may touch before the grid refuses it.
+ * `maxOperationCells` の既定値 (ADR-12)。1 つの操作 (貼り付け・フィル・消去・書式) が触れてよいセル数の上限で、超えるとグリッドが拒む。
+ */
+export declare const SPREADSHEET_MAX_OPERATION_CELLS = 100000;
+
 /** The width of the row-header band in CSS px (`--aqsp-row-header-width` in the stylesheet). 行見出しの帯の幅 (CSS px。スタイルシートの `--aqsp-row-header-width`)。 */
 export declare const SPREADSHEET_ROW_HEADER_WIDTH_PX = 64;
 
@@ -33,16 +46,27 @@ export declare const SPREADSHEET_ZOOM_MAX = 4;
 export declare const SPREADSHEET_ZOOM_MIN = 0.25;
 
 /**
- * The 0.1-grid step of the zoom gestures (Alt+Wheel and Ctrl+Alt+= / -), unclamped and free of float drift. From an
- * off-grid value (the 0.25 bound or a host's 1.25) the step lands on the nearest detent in the travel direction (0.25
- * goes to 0.3 up and 0.2 down); rounding would skip a detent (0.25 to 0.4). Clamp the result with clampSpreadsheetZoom.
- * 拡大縮小の操作 (Alt+ホイールと Ctrl+Alt+= / -) の 0.1 刻み (範囲で切らず、浮動小数のずれを持ち込まない)。刻みの外の値
- * (下限の 0.25 やホストの 1.25) からは、進む向きの最寄りの刻みへ着く (0.25 から上は 0.3、下は 0.2)。丸めると刻みを飛ばす
- * (0.25 から 0.4) ため使わない。結果は clampSpreadsheetZoom で切る。
+ * The zoom ladder of the gestures (Alt+Wheel and Ctrl+Alt+= / -): the geometric series `2^(k/4)` for every integer `k`
+ * from −8 to 8, rounded to hundredths, so it runs from SPREADSHEET_ZOOM_MIN (0.25) through 1 to SPREADSHEET_ZOOM_MAX (4)
+ * in steps of about 19 % and every power of two is a step.
+ * 拡大縮小の操作 (Alt+ホイールと Ctrl+Alt+= / -) の段。−8 から 8 までの整数 `k` の等比数列 `2^(k/4)` を 100 分の 1 に丸めた
+ * もので、SPREADSHEET_ZOOM_MIN (0.25) から 1 を通って SPREADSHEET_ZOOM_MAX (4) まで約 19 % ずつ進み、2 の累乗はどれも段に乗る。
+ */
+export declare const SPREADSHEET_ZOOM_STEPS: readonly number[];
+
+/**
+ * The next step of SPREADSHEET_ZOOM_STEPS in the travel direction, from any finite value, including a value off the
+ * ladder (a host's 1.25 goes to 1.41 up and 1.19 down). The input is clamped first, as clampSpreadsheetZoom does, and
+ * the step is taken from the clamped value: 9 zooms out to 3.36 and 0.01 zooms in to 0.3, and at a bound the result stays
+ * at that bound (in from SPREADSHEET_ZOOM_MAX, out from SPREADSHEET_ZOOM_MIN). A non-finite value fails fast.
+ * 進む向きの SPREADSHEET_ZOOM_STEPS の次の段を返す処理。段の外の値 (ホストの 1.25 は上で 1.41、下で 1.19) を含む、どの有限の
+ * 値からでも求める。入力を先に clampSpreadsheetZoom と同じく範囲へ切り、切った値から一歩進む (9 からの縮小は 3.36、0.01 からの
+ * 拡大は 0.3)。端では端に留まる (SPREADSHEET_ZOOM_MAX からの拡大、SPREADSHEET_ZOOM_MIN からの縮小)。有限でない値はすぐに投げる。
  *
  * @param value - The current zoom. 今の拡大率。
  * @param direction - 1 to zoom in, -1 to zoom out. 拡大は 1、縮小は -1。
- * @returns The next detent in that direction. その向きの次の刻み。
+ * @returns The next ladder step in that direction from the clamped input. 範囲へ切った入力からのその向きの次の段。
+ * @throws {RangeError} When the value is not finite. 有限でない場合。
  */
 export declare const stepSpreadsheetZoom: (value: number, direction: 1 | -1) => number;
 

package/dist/view.js

@@ -1,14 +1,14 @@
-const e = 24, o = 64, _ = 12, S = 0.25, n = 4, s = (E) => {
-  if (!Number.isFinite(E))
-    throw new RangeError(`[spreadsheet] zoom must be a finite number (got ${E})`);
-  return Math.min(4, Math.max(0.25, E));
-}, r = (E, t) => t > 0 ? (Math.floor(E * 10 + 1e-6) + 1) / 10 : (Math.ceil(E * 10 - 1e-6) - 1) / 10;
+import { f as _, b as a, d as s, g as A, S as T, h as H, i as P, j as R, a as D, c as O, s as e } from "./view-DycJZi_t.js";
 export {
-  e as SPREADSHEET_COLUMN_HEADER_HEIGHT_PX,
-  o as SPREADSHEET_ROW_HEADER_WIDTH_PX,
-  _ as SPREADSHEET_SCROLLBAR_SIZE_PX,
-  n as SPREADSHEET_ZOOM_MAX,
-  S as SPREADSHEET_ZOOM_MIN,
-  s as clampSpreadsheetZoom,
-  r as stepSpreadsheetZoom
+  _ as SPREADSHEET_COLUMN_HEADER_HEIGHT_PX,
+  a as SPREADSHEET_DEFAULT_COLUMN_WIDTH_PX,
+  s as SPREADSHEET_MAX_OPERATION_CELLS,
+  A as SPREADSHEET_ROW_HEADER_WIDTH_PX,
+  T as SPREADSHEET_SCROLLBAR_SIZE_PX,
+  H as SPREADSHEET_ZOOM_MAX,
+  P as SPREADSHEET_ZOOM_MIN,
+  R as SPREADSHEET_ZOOM_STEPS,
+  D as clampSpreadsheetZoom,
+  O as columnIndexToName,
+  e as stepSpreadsheetZoom
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiquants/spreadsheet",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Excel-grade spreadsheet grid for React: multi-cell selection, TSV/HTML clipboard, in-place editing on top of @aiquants/virtualscroll",
   "sideEffects": [
     "**/*.css"
@@ -56,12 +56,12 @@
     "LICENSE.md"
   ],
   "peerDependencies": {
-    "@aiquants/virtualscroll": "^3.22.0",
+    "@aiquants/virtualscroll": "^3.22.1",
     "react": "^19.2.7",
     "react-dom": "^19.2.7"
   },
   "devDependencies": {
-    "@aiquants/virtualscroll": "3.22.0",
+    "@aiquants/virtualscroll": "3.22.1",
     "@playwright/test": "^1.59.1",
     "@tailwindcss/cli": "^4.1.18",
     "@testing-library/jest-dom": "^6.9.1",

package/src/Spreadsheet.tsx

@@ -63,7 +63,7 @@ import { RowHeader } from "./header/RowHeader.tsx"
 import { useHeaderResize } from "./header/useHeaderResize.ts"
 import { useHeaderSelection } from "./header/useHeaderSelection.ts"
 import { createEnsureCellVisible } from "./keyboard/ensureCellVisible.ts"
-import { type ShortcutOverrides, type SpreadsheetCommand, validateShortcuts } from "./keyboard/shortcuts.ts"
+import { RESIZE_COMMANDS, type ShortcutOverrides, type SpreadsheetCommand, toAriaKeyShortcut, validateShortcuts } from "./keyboard/shortcuts.ts"
 import { type CommandDispatch, type MoveActiveInput, useGridKeyboard } from "./keyboard/useGridKeyboard.ts"
 import { useAxisModel } from "./model/axisModel.ts"
 import { type CellCommentInput, normalizeAdapterHyperlink } from "./model/cellAnnotations.ts"
@@ -71,7 +71,7 @@ import { type CellCoord, type CellRange, clampCoord, makeRange, rangeSize, type
 import { type CellBorder, type CellFormat, type CellFormatPatch, formatCellValue } from "./model/cellFormat.ts"
 import { type EditPaint, IDLE_EDIT_PAINT, normalizeColor, resolveEditPaint } from "./model/cellPaint.ts"
 import { buildCfIndex, type CfIndex, type CfMemo, createCfMemo, resolvePaintedFormat } from "./model/conditionalFormat.ts"
-import { type CellEdit, type EditContext, type EditRejection, type EditSource, isReadOnlyCell, lazyCellText, type ReadOnlyRejection, readOnlyDeclared, resolveCellAlign, type SpreadsheetDataAdapter } from "./model/dataAdapter.ts"
+import { type CellEdit, type EditContext, type EditRejection, type EditSource, isReadOnlyCell, lazyCellText, type ReadOnlyRejection, readOnlyAdapterView, readOnlyDeclared, resolveCellAlign, type SpreadsheetDataAdapter } from "./model/dataAdapter.ts"
 import { type DataValidationRule, type ValidationVerdict, validateCellText } from "./model/dataValidation.ts"
 import type { ReferenceAxis } from "./model/formulaRefs.ts"
 import { colToViewportX, rowToViewportY } from "./model/frozenPartition.ts"
@@ -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, stepSpreadsheetZoom } from "./view.ts"
+import { clampSpreadsheetZoom, SPREADSHEET_DEFAULT_COLUMN_WIDTH_PX, SPREADSHEET_MAX_OPERATION_CELLS, stepSpreadsheetZoom } from "./view.ts"
 
 export type { SelectionState } from "./selection/selectionState.ts"
 
@@ -187,6 +187,15 @@ export type SpreadsheetProps = {
      * 位置に依らず常時可視で、可視化の縦成分は no-op。飛行中の変更は全ドラッグを取り消す。
      */
     frozenRows?: number
+    /**
+     * The leading rows whose cells are column headers (default 0): their cells take `role="columnheader"` and the
+     * stylesheet's header-row paint (`--aqsp-header-row-*`), so assistive technology reads them as the headers of the
+     * columns below. An integer in [0, frozenRows]: header rows are always frozen rows; anything else is a RangeError
+     * during render.
+     * 先頭の見出しの行数 (既定 0)。そのセルは `role="columnheader"` とスタイルシートの見出し行の塗り (`--aqsp-header-row-*`)
+     * を受け、支援技術は下の列の見出しとして読む。[0, frozenRows] の整数 (見出しの行は常に凍結行)。それ以外は描画中の RangeError。
+     */
+    headerRows?: number
     /**
      * Freezes the LAST N columns at the right edge (v0.9 — the VirtualGrid frozenTrailingCols
      * pass-through; LIVE prop, default 0). Validation SSOT is the engine's fail-fast contract
@@ -382,6 +391,26 @@ export type SpreadsheetProps = {
      * region は溢れない。
      */
     formatReadOnlyAnnouncement?: (rejection: ReadOnlyRejection) => string
+    /**
+     * Makes the whole grid read-only (default false): `aria-readonly="true"` on the `role="grid"` element and on the
+     * hidden input, and every cell is read-only whatever the adapter's `isCellReadOnly` says, so every write is refused
+     * through `onReadOnlyRejected` / `formatReadOnlyAnnouncement` and the cell announcement's `readOnly` is true. View
+     * changes stay available: selection, copy, scrolling, zoom, resizing, hiding and highlighting.
+     * グリッド全体を読み取り専用にする (既定 false)。`role="grid"` の要素と隠しの入力に `aria-readonly="true"` を付け、アダプタの
+     * `isCellReadOnly` に関わらず全てのセルを読み取り専用にする (書き込みは全て `onReadOnlyRejected` / `formatReadOnlyAnnouncement`
+     * で拒まれ、セルの読み上げの `readOnly` は true)。見た目の変更 (選択・コピー・スクロール・拡大率・寸法・非表示・強調) は使える。
+     */
+    readOnly?: boolean
+    /**
+     * The id of the element that names the grid (a caption or heading of the host): the `role="grid"` element and the
+     * focusable root (the Escape landing point) both take `aria-labelledby` with it instead of the built-in
+     * `labels.rootAriaLabel`. A non-empty id without whitespace; anything else is a RangeError during render. Omitted:
+     * the root and the grid both carry `labels.rootAriaLabel` as `aria-label`.
+     * グリッドに名前を与える要素の id (ホストの表題や見出し)。`role="grid"` の要素とフォーカスを受けるルート (Escape の着地点) は
+     * 組み込みの `labels.rootAriaLabel` の代わりにこれを `aria-labelledby` に持つ。空白を含まない空でない id で、それ以外は描画中の
+     * RangeError。省略するとルートとグリッドの両方が `labels.rootAriaLabel` を `aria-label` に持つ。
+     */
+    labelledBy?: string
     /**
      * Paste outcome summary (v0.10 plan §3.1): the menu channel mirrors `paste(options)`'s
      * resolve value 1:1 (read refusals and the write-time re-gate included); the event channel
@@ -446,6 +475,15 @@ export type SpreadsheetProps = {
      * コマンドの AT 通知 (opt-in、v0.8 §1.9)。`state` はトグル後状態 (非トグルは null)。live region へ。
      */
     formatCommandAnnouncement?: (ctx: { command: SpreadsheetCommand; state: boolean | null }) => string
+    /**
+     * Live-region text after a keyboard resize (increaseColumnWidth / decreaseColumnWidth / increaseRowHeight /
+     * decreaseRowHeight / autoFitColumnWidth): the active track's axis, index and new size in CSS px. Omit for silence
+     * (no built-in strings); it shares the announcement debounce.
+     * キーボードの寸法の変更 (increaseColumnWidth / decreaseColumnWidth / increaseRowHeight / decreaseRowHeight /
+     * autoFitColumnWidth) の後の読み上げ文言。アクティブなトラックの軸・番号・新しい寸法 (CSS px) を受ける。省略で無音
+     * (組み込み文言なし)。読み上げのデバウンスを共有する。
+     */
+    formatResizeAnnouncement?: (ctx: { command: SpreadsheetCommand; axis: "row" | "column"; index: number; size: number }) => string
     /**
      * UI chrome language ("en" | "ja"; default "en"): selects the label catalog, the built-in
      * data-validation messages, and is forwarded to the grid scrollbars (arrow labels,
@@ -585,6 +623,34 @@ export type SpreadsheetProps = {
  * 本層所有)。undefined は宣言不在信号 (エンジン既定) で対象外。非整数・負値は RangeError (メッセージは
  * 生の入力を映す — 数値は Infinity / NaN 込みでそのまま、文字列は引用符つき — JS ホストの "5" は引用符で映る)。
  */
+/**
+ * Validates `headerRows` during render: an integer in [0, frozenRows], since header rows are always frozen rows.
+ * 描画中に `headerRows` を確かめる処理。見出しの行は常に凍結行なので [0, frozenRows] の整数。
+ *
+ * @param headerRows - The prop. prop。
+ * @param frozenRows - The frozen leading rows. 先頭の凍結行数。
+ * @throws {RangeError} When the value is not an integer in [0, frozenRows]. [0, frozenRows] の整数でない場合。
+ */
+const validateHeaderRows = (headerRows: number, frozenRows: number): void => {
+    // 0 は凍結行数を問わず有効: 凍結行数そのものの検証はエンジン (VirtualGrid) の単層に任せ、ここで先に投げない
+    if (!Number.isInteger(headerRows) || headerRows < 0 || (headerRows > 0 && headerRows > frozenRows)) {
+        throw new RangeError(`[spreadsheet] headerRows must be a whole number from 0 to frozenRows = ${frozenRows} (got ${headerRows})`)
+    }
+}
+
+/**
+ * Validates `labelledBy` during render: omitted, or one non-empty id without whitespace.
+ * 描画中に `labelledBy` を確かめる処理。省略か、空白を含まない空でない id 1 つ。
+ *
+ * @param labelledBy - The prop. prop。
+ * @throws {RangeError} When the value is empty or holds whitespace. 空か空白を含む場合。
+ */
+const validateLabelledBy = (labelledBy: string | undefined): void => {
+    if (labelledBy !== undefined && (typeof labelledBy !== "string" || labelledBy === "" || /\s/u.test(labelledBy))) {
+        throw new RangeError(`[spreadsheet] labelledBy must be one non-empty id without whitespace (got ${JSON.stringify(labelledBy)})`)
+    }
+}
+
 const validateOverscan = (name: "overscanRows" | "overscanCols", value: number | undefined): number | undefined => {
     if (value !== undefined && !(Number.isInteger(value) && value >= 0)) {
         throw new RangeError(`[spreadsheet] ${name} must be a non-negative integer (got ${typeof value === "string" ? JSON.stringify(value) : String(value)})`)
@@ -622,8 +688,6 @@ type SpreadsheetTestProps = {
 }
 
 const DEFAULT_ROW_HEIGHT = 24
-const DEFAULT_COLUMN_WIDTH = 100
-const DEFAULT_MAX_OPERATION_CELLS = 100_000
 /** Live region debounce in ms (§6.9-9). / live region デバウンス (ms)。 */
 const ANNOUNCE_DEBOUNCE_MS = 200
 /** Default custom colour slots (v0.8 §1.9) for `fillColorCustom1..5` / `fontColorCustom1..5`. / カスタム色 5 スロットの既定 (v0.8 §1.9)。 */
@@ -744,9 +808,12 @@ const INITIAL_SELECTION: SelectionState = {
  */
 export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & SpreadsheetTestProps>(function Spreadsheet(
     {
-        adapter,
+        adapter: hostAdapter,
+        headerRows = 0,
+        readOnly = false,
+        labelledBy,
         defaultRowHeight = DEFAULT_ROW_HEIGHT,
-        defaultColumnWidth = DEFAULT_COLUMN_WIDTH,
+        defaultColumnWidth = SPREADSHEET_DEFAULT_COLUMN_WIDTH_PX,
         frozenColumns = 0,
         frozenRows = 0,
         frozenTrailingColumns = 0,
@@ -767,12 +834,13 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         onReadOnlyRejected,
         formatReadOnlyAnnouncement,
         dataVersion,
-        maxOperationCells = DEFAULT_MAX_OPERATION_CELLS,
+        maxOperationCells = SPREADSHEET_MAX_OPERATION_CELLS,
         enableFillHandle = true,
         enableResizeUI = true,
         formatCellAnnouncement,
         formatSelectionAnnouncement,
         formatCommandAnnouncement,
+        formatResizeAnnouncement,
         locale,
         labels,
         shortcuts,
@@ -802,6 +870,9 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     }: SpreadsheetProps & SpreadsheetTestProps,
     ref,
 ): ReactNode {
+    // 全体の読み取り専用はアダプタのビュー 1 つで表す: 全ての読み取り専用のゲートと塗りはアダプタの宣言だけを読むため、
+    // ゲートごとに旗を通さずに全ての書き込みが同じ経路で拒まれる。同一性はシート切替の判定 (hostAdapter) に使わない
+    const adapter = useMemo(() => (readOnly ? readOnlyAdapterView(hostAdapter) : hostAdapter), [hostAdapter, readOnly])
     // §6.9-1: フックは常に呼び、空グリッドはレンダー分岐でのみ返す (indexAt fail-fast の前提)
     const rowAxis = useAxisModel(adapter.rowCount, defaultRowHeight)
     const colAxis = useAxisModel(adapter.colCount, defaultColumnWidth)
@@ -822,6 +893,15 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     const scrollLabels = useValueStableScrollLabels(pickEngineLabels(resolvedLabels))
     // コマンド表: validateShortcuts の 5 条件 (+ 未知キー) は consumer の設定誤り — render 中に表面化
     const commandTable = useMemo(() => validateShortcuts(shortcuts), [shortcuts])
+    // 寸法のキーボード操作を隠しの入力の aria-keyshortcuts で示す (再束縛の後の実効チョード。束縛が無ければ属性を出さない)
+    const resizeKeyShortcuts = useMemo(() => {
+        if (!enableResizeUI) {
+            return undefined
+        }
+        const chords = [...commandTable].filter(([, command]) => RESIZE_COMMANDS.includes(command)).sort(([, a], [, b]) => RESIZE_COMMANDS.indexOf(a) - RESIZE_COMMANDS.indexOf(b))
+        const names = chords.map(([chord]) => toAriaKeyShortcut(chord)).filter((name): name is string => name !== null)
+        return names.length === 0 ? undefined : names.join(" ")
+    }, [commandTable, enableResizeUI])
     // カスタム色スロット (各軸ちょうど 5 本の #rrggbb)
     const resolvedColors = useMemo(() => ({ fill: resolveColorSlots("fill", colors === undefined ? undefined : colors.fill), font: resolveColorSlots("font", colors === undefined ? undefined : colors.font) }), [colors])
     // 帯パレットの prop 時検証 (identity 安定): 宣言時だけ検証し、未宣言は undefined のまま — overlay へ渡す
@@ -831,6 +911,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     if (adapter.getConditionalFormats !== undefined && adapter.getCellFormat === undefined) {
         throw new RangeError("[spreadsheet] getConditionalFormats requires getCellFormat")
     }
+    validateHeaderRows(headerRows, frozenRows)
+    validateLabelledBy(labelledBy)
 
     // ---- renderVersion (editVersion 購読 + dataVersion) と CF 索引 / memo (v0.8 §2.1) ----
     // GridBody と同じ合流購読 (rAF 合流) — 親が先に描画するため、子のスライスが読む .current は常に新
@@ -1838,6 +1920,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         adapter,
         // autofit の採用条件 = renderCell 未指定 (カスタム DOM は measureText 計測を保証できない §10)
         autofitEnabled: renderCell === undefined,
+        headerRows,
         defaultRowHeight,
         defaultColumnWidth,
         maxOperationCells,
@@ -2083,6 +2166,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     }, [rowAxis, colAxis, ensureCellVisible])
     const commands = useCommands({
         adapter,
+        // キーボードの寸法の変更は帯のリサイズ UI と同じ可否 (enableResizeUI が false なら利用者は寸法を変えない)
+        trackResize: enableResizeUI && !isEmpty ? headerResizeMachine : undefined,
         getSelection,
         commitEdits,
         getActive,
@@ -2112,6 +2197,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
         now,
         announce,
         formatCommandAnnouncement,
+        formatResizeAnnouncement,
         keyboardCellRect,
         // v0.10: G8–G13 / G15 の拒否漏斗 (§6.4)
         rejectReadOnly,
@@ -2447,10 +2533,11 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
     // 旧グリッド座標のレンジは新軸で out-of-bounds になり得て、repaintOverlay の sizeOf が
     // 例外を投げる (Fenwick は範囲外 index で fail-fast) — クランプでなくシート切替の意味論
     // どおり全リセット (Excel のシート切替と同じく選択は持ち越さない)
-    const prevAdapterRef = useRef(adapter)
+    // 判定はホストのアダプタの同一性で行う (readOnly の切替が作るビューの交代はシート切替ではない)
+    const prevAdapterRef = useRef(hostAdapter)
     useLayoutEffect(() => {
-        if (prevAdapterRef.current !== adapter) {
-            prevAdapterRef.current = adapter
+        if (prevAdapterRef.current !== hostAdapter) {
+            prevAdapterRef.current = hostAdapter
             // 飛行中ドラッグは復元なしで取り消す (各機械の dragBeforeRef は旧シート座標 — 復元経路
             // (Escape / lostpointercapture) から新軸へ範囲外選択が漏れるのを断つ)
             engine.cancelDrag()
@@ -2490,7 +2577,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
             // effect 化する将来変更でこの順序が実防壁になるため維持する
             onAdapterSwitchRef.current()
         }
-    }, [adapter, isEmpty, setSelection, engine, colHeaderMachine, rowHeaderMachine, headerResizeMachine, fillMachine, pointDrag, viewStore, editor.cancelEdit])
+    }, [hostAdapter, isEmpty, setSelection, engine, colHeaderMachine, rowHeaderMachine, headerResizeMachine, fillMachine, pointDrag, viewStore, editor.cancelEdit])
 
     // ---- 行数 / 列数の縮小 (同一 adapter — 絞り込み / カテゴリ / 期間の変更で明細が減る) は保持中の
     //      座標を新グリッドへ畳む (ADR-33) ----
@@ -2696,12 +2783,15 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
 
     // live region は読み上げ prop のどれか 1 つでも宣言されたときだけ描く (コマンド通知も同じ領域へ)
     // v0.10: formatReadOnlyAnnouncement も live region の存在条件 (拒否読み上げは announce() 経由 — §6.4)
-    const hasAnnouncement = formatCellAnnouncement !== undefined || formatSelectionAnnouncement !== undefined || formatCommandAnnouncement !== undefined || formatReadOnlyAnnouncement !== undefined
+    const hasAnnouncement = formatCellAnnouncement !== undefined || formatSelectionAnnouncement !== undefined || formatCommandAnnouncement !== undefined || formatReadOnlyAnnouncement !== undefined || formatResizeAnnouncement !== undefined
+
+    // 名前は labelledBy があればホストの要素 (aria-labelledby)、無ければ組み込みの名前 (aria-label) — グリッドも同じ規則で名前を持つ
+    const rootName = labelledBy === undefined ? { "aria-label": resolvedLabels.rootAriaLabel } : { "aria-labelledby": labelledBy }
 
     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" aria-label={resolvedLabels.rootAriaLabel} 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-testid={testId}>
             {/* ズームラッパー (v0.3): 視覚は transform スケール、内側レイアウトは 100%/z の論理 px —
                 virtualscroll の実測 (ResizeObserver / clientHeight) は論理値のまま。z=1 は無スタイル
                 (v0.2 と byte 同一の DOM 幾何 — 既存全ゲートの不変性) */}
@@ -2783,6 +2873,10 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                         frozenRows={frozenRows}
                         frozenTrailingColumns={frozenTrailingColumns}
                         frozenTrailingRows={frozenTrailingRows}
+                        headerRows={headerRows}
+                        labelledBy={labelledBy}
+                        gridLabel={labelledBy === undefined ? resolvedLabels.rootAriaLabel : undefined}
+                        readOnly={readOnly}
                         tapScrollCircleOptions={tapScrollCircleOptions}
                         overscanRows={validateOverscan("overscanRows", overscanRows)}
                         overscanCols={validateOverscan("overscanCols", overscanCols)}
@@ -2825,6 +2919,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
                         trailingCols={frozenTrailingColumns}
                         trailingRows={frozenTrailingRows}
                         sinkAriaLabel={resolvedLabels.sinkAriaLabel}
+                        sinkReadOnly={readOnly}
+                        sinkKeyShortcuts={resizeKeyShortcuts}
                         onSinkMouseDown={onSinkMouseDown}
                         editPaintRef={editPaintRef}
                         highlightRef={highlightRef}