@aiquants/spreadsheet 0.17.0 → 0.17.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -49,7 +49,7 @@
49
49
 
50
50
  import { resolveVirtualScrollLocale, type ScrollBarTapCircleOptions, VIRTUAL_SCROLL_LABEL_KEYS, type VirtualGridHandle, type VirtualGridRange, type VirtualScrollLabels } from "@aiquants/virtualscroll"
51
51
  import type { ProfilerOnRenderCallback } from "react"
52
- import { forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react"
52
+ import { type CSSProperties, forwardRef, type ReactNode, useCallback, useEffect, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react"
53
53
  import type { ClipChannel } from "./clipboard/clipPayload.ts"
54
54
  import type { PasteOptions } from "./clipboard/pasteSpecial.ts"
55
55
  import { type ClipInfo, type PasteOutcome, type PasteSheet, useClipboard } from "./clipboard/useClipboard.ts"
@@ -117,6 +117,82 @@ export type SpreadsheetContentSize = {
117
117
  readonly height: number
118
118
  }
119
119
 
120
+ /**
121
+ * The content size of a grid that draws nothing (no rows or no columns: no cells, bands or scroll bars).
122
+ * 何も描かないグリッド (行か列が無い。セルも帯もスクロールバーも無い) の中身の大きさ。
123
+ */
124
+ const EMPTY_CONTENT_SIZE: SpreadsheetContentSize = Object.freeze({ width: 0, height: 0 })
125
+
126
+ /**
127
+ * The samples a page move takes down the body pane to find the part the reader sees; each boundary between a hidden and a
128
+ * seen sample is then bisected to 1 px.
129
+ * ページ移動が読み手に見えている本体ペインの部分を探すために縦に取る見本の数 (見えない見本と見える見本の間の境は、その後 1 px まで二分で詰める)。
130
+ */
131
+ const PAGE_SEEN_SAMPLES = 33
132
+
133
+ /**
134
+ * Whether a node is a document or a shadow root, the scopes a hit test runs in (a connected grid's root node is one).
135
+ * ノードが当たり判定の範囲 (文書か影の根) か (文書に繋がったグリッドの根のノードはどちらか)。
136
+ *
137
+ * @param node - The node. ノード。
138
+ * @returns Whether it is one. そうであるか。
139
+ */
140
+ const isHitTestScope = (node: Node): node is Document | ShadowRoot => node.nodeType === Node.DOCUMENT_NODE || node.nodeType === Node.DOCUMENT_FRAGMENT_NODE
141
+
142
+ /**
143
+ * The span of y, in px of the screen, in which the reader sees a box along one vertical line: samples over [top, bottom],
144
+ * then each boundary between a hidden and a seen sample bisected to 1 px. The seen part is taken as one run, from the first
145
+ * seen sample to the last.
146
+ * 縦の 1 本の線に沿って、読み手に箱が見えている y の範囲 (画面の px) を求める処理。[top, bottom] を見本で調べ、見えない見本と見える見本の間の
147
+ * 境を 1 px まで二分で詰める。見えている部分は、最初に見えた見本から最後に見えた見本までの 1 続きとみなす。
148
+ *
149
+ * @param seen - Whether the reader sees the box at a y. ある y で箱が見えるか。
150
+ * @param top - The top of the span to search. 探す範囲の上端。
151
+ * @param bottom - The bottom of the span to search, not above top. 探す範囲の下端 (上端より上ではない)。
152
+ * @returns The seen span, or null when no sample is seen. 見えている範囲 (どの見本も見えなければ null)。
153
+ */
154
+ const seenSpanOf = (seen: (y: number) => boolean, top: number, bottom: number): { readonly top: number; readonly bottom: number } | null => {
155
+ const step = (bottom - top) / (PAGE_SEEN_SAMPLES - 1)
156
+ let first = -1
157
+ let last = -1
158
+ for (let index = 0; index < PAGE_SEEN_SAMPLES; index++) {
159
+ if (seen(top + step * index)) {
160
+ if (first === -1) {
161
+ first = index
162
+ }
163
+ last = index
164
+ }
165
+ }
166
+ if (first === -1) {
167
+ return null
168
+ }
169
+ /**
170
+ * The seen y nearest the boundary between a hidden y and a seen y, within 1 px.
171
+ * 見えない y と見える y の間の境に 1 px 以内で最も近い、見える y。
172
+ *
173
+ * @param hidden - A y where the box is hidden. 箱が見えない y。
174
+ * @param shown - A y where the box is seen. 箱が見える y。
175
+ * @returns The seen y at the boundary. 境の見える y。
176
+ */
177
+ const boundaryOf = (hidden: number, shown: number): number => {
178
+ let outside = hidden
179
+ let inside = shown
180
+ while (Math.abs(inside - outside) > 1) {
181
+ const middle = (outside + inside) / 2
182
+ if (seen(middle)) {
183
+ inside = middle
184
+ } else {
185
+ outside = middle
186
+ }
187
+ }
188
+ return inside
189
+ }
190
+ return {
191
+ top: first === 0 ? top : boundaryOf(top + step * (first - 1), top + step * first),
192
+ bottom: last === PAGE_SEEN_SAMPLES - 1 ? bottom : boundaryOf(top + step * (last + 1), top + step * last),
193
+ }
194
+ }
195
+
120
196
  /** Imperative surface (§6.9-8). / 命令 API (§6.9-8)。 */
121
197
  export type SpreadsheetHandle = {
122
198
  /** Row-height pair seam (§6.9-8). / 行高変更の対シーム。 */
@@ -494,11 +570,13 @@ export type SpreadsheetProps = {
494
570
  /**
495
571
  * v0.17 — Receives the size of the grid's content (`SpreadsheetContentSize`) after the first layout and again after
496
572
  * every change of it: a track's size (a resize, an autofit, a hide or unhide, the imperative resizeRow / resizeColumn),
497
- * the row or column count, the default sizes, the zoom or `headings`. An unchanged size is not repeated. A host uses it
498
- * to size the grid's box to its content.
573
+ * the row or column count, the default sizes, the zoom or `headings`. An unchanged size is not repeated. A grid with no
574
+ * rows or no columns draws nothing and reports 0 × 0; a grid without a layout box (under a `display: none` ancestor)
575
+ * reports once it has one. A host uses it to size the grid's box to its content.
499
576
  * v0.17 — グリッドの中身の大きさ (`SpreadsheetContentSize`) を、最初の配置の後と、それが変わるたびに受け取る (トラックの
500
577
  * 大きさ — 境の操作・autofit・隠す・再表示・命令の resizeRow / resizeColumn —、行や列の数、既定の大きさ、倍率、`headings`)。
501
- * 同じ大きさは繰り返さない。ホストはこれでグリッドの箱を中身に合わせる。
578
+ * 同じ大きさは繰り返さない。行か列の無いグリッドは何も描かないので 0 × 0、配置の箱の無いグリッド (display: none の祖先の中)
579
+ * は箱を得てから知らせる。ホストはこれでグリッドの箱を中身に合わせる。
502
580
  */
503
581
  onContentSizeChange?: (size: SpreadsheetContentSize) => void
504
582
  /**
@@ -1120,6 +1198,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
1120
1198
  }, [requestZoom, zoomGestureEnabled])
1121
1199
  const bodyRef = useRef<HTMLDivElement | null>(null)
1122
1200
  const bodyStackRef = useRef<HTMLDivElement | null>(null)
1201
+ const cornerRef = useRef<HTMLDivElement | null>(null)
1123
1202
  const revealRef = useRef<HTMLDivElement | null>(null)
1124
1203
  const handleRef = useRef<VirtualGridHandle | null>(null)
1125
1204
  const sinkRef = useRef<HTMLTextAreaElement | null>(null)
@@ -1232,6 +1311,16 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
1232
1311
  const focusSink = useCallback((options?: { preventScroll?: boolean }) => {
1233
1312
  sinkRef.current?.focus(options)
1234
1313
  }, [])
1314
+ /**
1315
+ * Focus recovery from a press (v0.17.2): the pressed point is on screen, and the sink still sits on the previous active
1316
+ * cell until the press moves the selection, so the page must not scroll to it — a grid taller than its page would
1317
+ * jump back to that cell (a box that shows every row, back to A1) on the first press into it.
1318
+ * 押下からのフォーカス回収 (v0.17.2)。押した点は画面にあり、シンクは押下が選択を動かすまで前の選んだセルにあるため、ページをそこへ
1319
+ * スクロールさせない (ページより高いグリッドは、焦点の無い状態の最初の押下でそのセル — 全部の行を見せる箱なら A1 — へ跳び戻る)。
1320
+ */
1321
+ const focusSinkFromPress = useCallback(() => {
1322
+ focusSink({ preventScroll: true })
1323
+ }, [focusSink])
1235
1324
 
1236
1325
  // ---- WCAG 2.1.2 脱出の旗 (§10-4): Escape の root.focus() だけが root に留まれる内部移動 ----
1237
1326
  const escapeHandOffRef = useRef(false)
@@ -1478,7 +1567,8 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
1478
1567
  if (box.width === 0 && box.height === 0) {
1479
1568
  return
1480
1569
  }
1481
- marker.scrollIntoView({ block: "nearest", inline: "nearest" })
1570
+ // キーの移動は打鍵ごとにその場で着地させる (ホストの scroll-behavior: smooth に任せると、打鍵の速さに描画が遅れる)
1571
+ marker.scrollIntoView({ block: "nearest", inline: "nearest", behavior: "instant" })
1482
1572
  },
1483
1573
  [cellRectOf],
1484
1574
  )
@@ -1491,28 +1581,95 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
1491
1581
  [revealCellInPage],
1492
1582
  )
1493
1583
 
1584
+ /**
1585
+ * The height a page move travels, in logical px (v0.17.2): the grid's own viewport, cut to the part of its body pane the
1586
+ * reader sees. A grid taller than its page (a box that shows every row) would otherwise page from any row to its last,
1587
+ * while the page shows a screenful of it. The seen part comes from the browser's own hit test down the body's middle,
1588
+ * so every clip (scroll containers, the window, the overflow the root element passes to the viewport), the top layer
1589
+ * (a modal dialog, a popover, full screen), shadow trees and anything painted over the body count as drawn. -1 while
1590
+ * the viewport is unmeasured; a screenful of the window while no part of the body is seen (scrolled out or covered).
1591
+ * ページ移動が進む高さ (論理 px。v0.17.2)。グリッド自身の表示域を、読み手に見えている本体ペインの部分で切り詰めたもの。ページより
1592
+ * 高いグリッド (全部の行を見せる箱) では、そうしないと、ページが 1 画面しか見せないのにどの行からでも最後の行へ移る。見えている部分は
1593
+ * 本体の中ほどを縦に調べるブラウザ自身の当たり判定で決めるため、切り抜き (スクロールの容器・窓・根の要素が窓へ渡す overflow)・最上位の
1594
+ * 層 (モーダルの dialog・ポップオーバー・全画面)・影の木・本体の上に重なる描画は描いたとおりに入る。表示域が未計測なら -1、本体が
1595
+ * どこも見えない (ページの外へスクロールした・覆われた) 間は窓の 1 画面。
1596
+ *
1597
+ * @returns The travel in logical px, or -1. 論理 px の移動量、または -1。
1598
+ */
1599
+ const pageExtent = useCallback((): number => {
1600
+ const handle = handleRef.current
1601
+ const viewport = handle === null ? -1 : handle.getViewportSize().height
1602
+ const body = bodyRef.current
1603
+ const root = rootRef.current
1604
+ if (viewport <= 0 || body === null || root === null) {
1605
+ return viewport
1606
+ }
1607
+ const rect = body.getBoundingClientRect()
1608
+ const scope = root.getRootNode()
1609
+ if (rect.height <= 0 || body.offsetHeight <= 0 || !isHitTestScope(scope)) {
1610
+ return viewport
1611
+ }
1612
+ const view = root.ownerDocument.documentElement
1613
+ const left = Math.max(rect.left, 0)
1614
+ const right = Math.min(rect.right, view.clientWidth)
1615
+ // 箱の端の上の点は隣の箱に当たるため、半 px 内側を調べる (見えた高さには両端の半 px を足して戻す)
1616
+ const top = Math.max(rect.top, 0) + 0.5
1617
+ const bottom = Math.min(rect.bottom, view.clientHeight) - 0.5
1618
+ const x = (left + right) / 2
1619
+ const span =
1620
+ right > left && bottom >= top
1621
+ ? seenSpanOf(
1622
+ (y) => {
1623
+ const hit = scope.elementFromPoint(x, y)
1624
+ return hit !== null && root.contains(hit)
1625
+ },
1626
+ top,
1627
+ bottom,
1628
+ )
1629
+ : null
1630
+ const seen = span === null ? view.clientHeight : span.bottom - span.top + 1
1631
+ // 画面の px を本体の論理 px へ (グリッドの倍率と祖先の伸び縮みの両方を含む比)
1632
+ return Math.min(viewport, seen * (body.offsetHeight / rect.height))
1633
+ }, [])
1634
+
1494
1635
  // ---- 中身の大きさの知らせ (v0.17) ----
1495
1636
  const onContentSizeChangeRef = useRef(onContentSizeChange)
1496
1637
  onContentSizeChangeRef.current = onContentSizeChange
1497
1638
  const reportedContentSizeRef = useRef<SpreadsheetContentSize | null>(null)
1498
1639
  /**
1499
1640
  * Reports the content size to `onContentSizeChange` when it differs from the last one reported: the bands' tracks (the
1500
- * body pane's offset in the zoom wrapper, so a host's band-size variables and `headings` count as laid out), every
1501
- * track, and the two scroll bars the grid always reserves, all inside the zoom wrapper and so scaled by the zoom.
1502
- * 中身の大きさを、前に知らせたものと違うときだけ `onContentSizeChange` へ知らせる処理。帯の格子の帯 (ズームの包みの中の本体
1503
- * ペインの位置なので、ホストの帯の寸法の変数と `headings` が配置どおりに入る)、全部のトラック、グリッドがいつも取る 2 本の
1504
- * スクロールバーで、どれもズームの包みの中にあるので倍率で伸び縮みする。
1641
+ * corner's size, which fills the bands' crossing, so a host's band-size variables and `headings` count as laid out, on
1642
+ * either side of the body in a right-to-left grid and in a box smaller than the bands), every track, and the two scroll
1643
+ * bars the grid always reserves, all inside the zoom wrapper and so scaled by the zoom. A grid with no rows or no
1644
+ * columns draws nothing and reports 0 × 0; a grid without a layout box (under a `display: none` ancestor) does not
1645
+ * report until it has one.
1646
+ * 中身の大きさを、前に知らせたものと違うときだけ `onContentSizeChange` へ知らせる処理。帯の格子の帯 (2 本の帯の交わりを満たす角の
1647
+ * 大きさ。ホストの帯の寸法の変数と `headings` が配置どおりに入り、右から左のグリッドでも、帯より小さい箱でも同じ)、全部のトラック、
1648
+ * グリッドがいつも取る 2 本のスクロールバーで、どれもズームの包みの中にあるので倍率で伸び縮みする。行か列の無いグリッドは何も描かない
1649
+ * ので 0 × 0、配置の箱の無いグリッド (display: none の祖先の中) は箱を得るまで知らせない。
1505
1650
  */
1506
1651
  const reportContentSize = useCallback((): void => {
1507
1652
  const listener = onContentSizeChangeRef.current
1508
- const stack = bodyStackRef.current
1509
- if (listener === undefined || stack === null) {
1653
+ if (listener === undefined) {
1510
1654
  return
1511
1655
  }
1512
- const z = zoomRef.current
1513
- const size: SpreadsheetContentSize = {
1514
- width: (stack.offsetLeft + colAxis.totalSize() + SPREADSHEET_SCROLLBAR_SIZE_PX) * z,
1515
- height: (stack.offsetTop + rowAxis.totalSize() + SPREADSHEET_SCROLLBAR_SIZE_PX) * z,
1656
+ const stack = bodyStackRef.current
1657
+ let size: SpreadsheetContentSize
1658
+ if (stack === null) {
1659
+ // 行か列の無いグリッドは本体を描かない (セルも帯もスクロールバーも無い) ため、中身は大きさを持たない
1660
+ size = EMPTY_CONTENT_SIZE
1661
+ } else if (stack.getClientRects().length === 0) {
1662
+ // 配置の箱の無いグリッド (display: none の祖先の中) では帯の大きさが 0 に読まれる。箱を得た時の大きさの変化で知らせ直す
1663
+ return
1664
+ } else {
1665
+ // 帯の大きさは角の大きさで読む。包みと本体の差は、箱が帯より小さいと本体のトラックが 0 に潰れて帯から箱の大きさだけ欠け、本体の
1666
+ // 左の位置は右から左のグリッドで帯を数えない。見出しを出さないグリッドは角も帯も描かない
1667
+ const corner = cornerRef.current
1668
+ const z = zoomRef.current
1669
+ size = {
1670
+ width: ((corner === null ? 0 : corner.offsetWidth) + colAxis.totalSize() + SPREADSHEET_SCROLLBAR_SIZE_PX) * z,
1671
+ height: ((corner === null ? 0 : corner.offsetHeight) + rowAxis.totalSize() + SPREADSHEET_SCROLLBAR_SIZE_PX) * z,
1672
+ }
1516
1673
  }
1517
1674
  const last = reportedContentSizeRef.current
1518
1675
  if (last !== null && last.width === size.width && last.height === size.height) {
@@ -1531,6 +1688,18 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
1531
1688
  }
1532
1689
  reportContentSize()
1533
1690
  })
1691
+ // 配置の箱を得た時 (display: none の祖先が外れた時) と、帯の寸法の変数の変化は描き直しを伴わないため、本体の大きさの変化で
1692
+ // 知らせ直す (同じ大きさは上の処理が繰り返さない)
1693
+ const reportsContentSize = onContentSizeChange !== undefined
1694
+ useEffect(() => {
1695
+ const stack = bodyStackRef.current
1696
+ if (!reportsContentSize || stack === null) {
1697
+ return
1698
+ }
1699
+ const observer = new ResizeObserver(() => reportContentSize())
1700
+ observer.observe(stack)
1701
+ return () => observer.disconnect()
1702
+ }, [reportsContentSize, reportContentSize, isEmpty])
1534
1703
 
1535
1704
  // ---- 読み上げ (live region — §6.9-9) ----
1536
1705
  const announceTimerRef = useRef<number | null>(null)
@@ -1999,7 +2168,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
1999
2168
  requestCommit,
2000
2169
  getSelection,
2001
2170
  setSelection,
2002
- focusSink,
2171
+ focusSink: focusSinkFromPress,
2003
2172
  onDragFrame,
2004
2173
  onContextMenuSelect,
2005
2174
  onRequestEdit,
@@ -2061,7 +2230,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2061
2230
  requestCommit,
2062
2231
  getSelection,
2063
2232
  setSelection,
2064
- focusSink,
2233
+ focusSink: focusSinkFromPress,
2065
2234
  onDragFrame,
2066
2235
  autoScroller: colAutoScroller,
2067
2236
  repaintOverlay,
@@ -2080,7 +2249,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2080
2249
  requestCommit,
2081
2250
  getSelection,
2082
2251
  setSelection,
2083
- focusSink,
2252
+ focusSink: focusSinkFromPress,
2084
2253
  onDragFrame,
2085
2254
  autoScroller: rowAutoScroller,
2086
2255
  repaintOverlay,
@@ -2101,7 +2270,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2101
2270
  handleRef,
2102
2271
  isEditing,
2103
2272
  requestCommit,
2104
- focusSink,
2273
+ focusSink: focusSinkFromPress,
2105
2274
  getSelection,
2106
2275
  adapter,
2107
2276
  // autofit の採用条件 = renderCell 未指定 (カスタム DOM は measureText 計測を保証できない §10)
@@ -2127,7 +2296,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2127
2296
  handleRef,
2128
2297
  getSelection,
2129
2298
  setSelection,
2130
- focusSink,
2299
+ focusSink: focusSinkFromPress,
2131
2300
  adapter,
2132
2301
  commitEdits,
2133
2302
  maxOperationCells,
@@ -2152,7 +2321,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2152
2321
  insertReference: pointingSeams.insertReference,
2153
2322
  captureSink: () => captureSinkRef.current(),
2154
2323
  restoreSink: (snapshot) => restoreSinkRef.current(snapshot),
2155
- focusSink,
2324
+ focusSink: focusSinkFromPress,
2156
2325
  autoScroller: pointAutoScroller,
2157
2326
  onDragFrame,
2158
2327
  })
@@ -2401,6 +2570,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2401
2570
  setSelection,
2402
2571
  moveActive,
2403
2572
  ensureCellVisible,
2573
+ pageExtent,
2404
2574
  isEditing,
2405
2575
  requestCommit,
2406
2576
  startEdit,
@@ -2469,11 +2639,11 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2469
2639
  (event: MouseEvent) => {
2470
2640
  if (!(isEditingRef.current?.() ?? false)) {
2471
2641
  event.preventDefault()
2472
- focusSink()
2642
+ focusSinkFromPress()
2473
2643
  rearmSink()
2474
2644
  }
2475
2645
  },
2476
- [focusSink, rearmSink],
2646
+ [focusSinkFromPress, rearmSink],
2477
2647
  )
2478
2648
 
2479
2649
  // ---- WCAG 2.1.2 再進入 (§10-4): React onFocus (focusin バブリング) + relatedTarget 規則 ----
@@ -2489,9 +2659,12 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2489
2659
  // 他の root 内要素からの着地 (スクロールバー矢印ボタンや renderCell のフォーカス要素からの
2490
2660
  // Shift+Tab 後方巡回) は休止点として root に留める — 戻すと後方 Tab がグリッド内で巡回に
2491
2661
  // 消費され、後方脱出が Escape 経由でしかできなくなる (R3 / R4 是正 — フォーカス不変条件)
2662
+ // キーボードの進入 (:focus-visible) はシンクのある選んだセルまでページを送り、押下 (触れるタップ・押下の既定動作) から来た
2663
+ // 焦点は押した点が画面にあるため送らない (送ると、ページより高いグリッドは前の選んだセルへ跳び戻る)
2664
+ const preventScroll = root !== null && !root.matches(":focus-visible")
2492
2665
  if (root !== null && related instanceof Node && root.contains(related)) {
2493
2666
  if (event.target === root && related === sinkRef.current && !escapeHandOffRef.current) {
2494
- focusSink()
2667
+ focusSink({ preventScroll })
2495
2668
  }
2496
2669
  return
2497
2670
  }
@@ -2502,7 +2675,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2502
2675
  return
2503
2676
  }
2504
2677
  // 外部からの Tab / Shift+Tab 進入・プログラム focus → シンクへ回収 + 再武装
2505
- focusSink()
2678
+ focusSink({ preventScroll })
2506
2679
  rearmSink()
2507
2680
  },
2508
2681
  [focusSink, rearmSink],
@@ -2653,17 +2826,17 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2653
2826
  }
2654
2827
  // 参照ポインティング中 (v0.8 §4.2.13): 死空間押下は consume してシンクへ焦点を戻すだけ (確定も挿入もしない)
2655
2828
  if (isPointing()) {
2656
- focusSink()
2829
+ focusSinkFromPress()
2657
2830
  return
2658
2831
  }
2659
2832
  // 編集中の requestCommit ゲート (§6.8-3): 死空間もフォーカス不動で focusout が発火しない
2660
2833
  if (isEditing() && !requestCommit()) {
2661
- focusSink()
2834
+ focusSinkFromPress()
2662
2835
  return
2663
2836
  }
2664
- focusSink()
2837
+ focusSinkFromPress()
2665
2838
  },
2666
- [focusSink, isEditing, requestCommit, isPointing],
2839
+ [focusSinkFromPress, isEditing, requestCommit, isPointing],
2667
2840
  )
2668
2841
 
2669
2842
  // ---- マウント武装 + 初期 rowRange 種付け (空→非空「エッジ」限定 — Phase 1 実装レビュー R3 の
@@ -2977,10 +3150,15 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2977
3150
  {/* ズームラッパー (v0.3): 視覚は transform スケール、内側レイアウトは 100%/z の論理 px —
2978
3151
  virtualscroll の実測 (ResizeObserver / clientHeight) は論理値のまま。z=1 は無スタイル
2979
3152
  (v0.2 と byte 同一の DOM 幾何 — 既存全ゲートの不変性) */}
2980
- <div className="aqsp-zoom" data-aqsp-zoom={zoomValue} onPointerDown={onZoomPointerDown} style={zoomValue === 1 ? undefined : { width: `${100 / zoomValue}%`, height: `${100 / zoomValue}%`, transform: `scale(${zoomValue})` }}>
3153
+ <div
3154
+ className="aqsp-zoom"
3155
+ data-aqsp-zoom={zoomValue}
3156
+ onPointerDown={onZoomPointerDown}
3157
+ style={zoomValue === 1 ? undefined : ({ width: `${100 / zoomValue}%`, height: `${100 / zoomValue}%`, transform: `scale(${zoomValue})`, "--_aqsp-zoom": String(zoomValue) } as CSSProperties)}>
2981
3158
  {headings ? (
2982
3159
  <>
2983
3160
  <div
3161
+ ref={cornerRef}
2984
3162
  className="aqsp-corner"
2985
3163
  aria-hidden="true"
2986
3164
  data-aqsp-corner=""
@@ -2996,15 +3174,15 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2996
3174
  }
2997
3175
  // 参照ポインティング中 (v0.8 §4.2.13): コーナー押下は consume + シンクへ焦点 (全選択も確定もしない)
2998
3176
  if (isPointing()) {
2999
- focusSink()
3177
+ focusSinkFromPress()
3000
3178
  return
3001
3179
  }
3002
3180
  // 編集中の requestCommit ゲート (§6.8-3 — コーナーもフォーカス不動で focusout 不発)
3003
3181
  if (isEditing() && !requestCommit()) {
3004
- focusSink()
3182
+ focusSinkFromPress()
3005
3183
  return
3006
3184
  }
3007
- focusSink()
3185
+ focusSinkFromPress()
3008
3186
  // コーナーの全セル選択は単一構築 state の setSelection 1 回 (過渡状態なし)。active = A1
3009
3187
  setSelection({
3010
3188
  ranges: [makeRange({ row: 0, col: 0 }, { row: adapter.rowCount - 1, col: adapter.colCount - 1 })],
@@ -3071,7 +3249,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
3071
3249
  renderCell={renderCell}
3072
3250
  onScroll={onScroll}
3073
3251
  onRangeChange={onRangeChange}
3074
- focusSink={focusSink}
3252
+ focusSink={focusSinkFromPress}
3075
3253
  isEditing={isEditing}
3076
3254
  requestCommit={requestCommit}
3077
3255
  testId={testId ? `${testId}-vs` : undefined}
@@ -94,8 +94,10 @@ type UseHeaderResizeParams = {
94
94
  rowBandRef: RefObject<HTMLElement | null>
95
95
  /**
96
96
  * The element whose computed font is the cells' base font (the body pane, the cells' parent): autofit measures with it,
97
- * so it works whether the header bands are shown or not.
98
- * 計算済みの書体がセルの基本の書体になる要素 (セルの親の本体ペイン)。autofit はこれで測るので、見出しの帯の有無に依らない。
97
+ * and with the letter and word spacing a hidden sample inside it computes for each measured font, so it works whether the
98
+ * header bands are shown or not.
99
+ * 計算済みの書体がセルの基本の書体になる要素 (セルの親の本体ペイン)。autofit はこれの書体と、この中の見えない見本が測る書体ごとに
100
+ * 計算する文字・語の間隔で測るので、見出しの帯の有無に依らない。
99
101
  */
100
102
  fontSourceRef: RefObject<HTMLElement | null>
101
103
  colAxis: AxisModel
@@ -345,11 +347,13 @@ export const useHeaderResize = (params: UseHeaderResizeParams): HeaderResizeMach
345
347
 
346
348
  /**
347
349
  * The measuring core of both autofit entries: fits `targets` to the widest painted text of `measuredRows` (per-column
348
- * canvas measurement in each cell's painted font over the cells' base font from fontSourceRef, bucketed by font key),
350
+ * canvas measurement in each cell's painted font over the cells' base font from fontSourceRef, bucketed by font key, with
351
+ * the letter and word spacing a hidden sample inside fontSourceRef computes for the bucket's font),
349
352
  * gated at `measureLimit` measured cells. No row to measure, no 2d context (jsdom) or an all-empty column set changes
350
353
  * nothing and still counts as a run (true).
351
354
  * 両方の autofit の入口が共有する計測の芯。`targets` を `measuredRows` の最も広い塗りの文字に合わせる (fontSourceRef のセルの
352
- * 基本の書体の上で、セルごとの塗りの書体で列ごとに canvas で測り、書体の鍵で束ねる)。測るセルは `measureLimit` まで。測る行が無い・
355
+ * 基本の書体の上で、セルごとの塗りの書体で列ごとに canvas で測り、書体の鍵で束ねる。文字・語の間隔は fontSourceRef の中の見えない
356
+ * 見本がバケットの書体で計算する値)。測るセルは `measureLimit` まで。測る行が無い・
353
357
  * 2d の文脈が無い (jsdom)・全部が空の列は何も変えずに走ったものとする (true)。
354
358
  *
355
359
  * @param targets - The columns to fit. 合わせる列。
@@ -423,10 +427,21 @@ export const useHeaderResize = (params: UseHeaderResizeParams): HeaderResizeMach
423
427
  }
424
428
  }
425
429
  }
426
- // バケット毎にフォントを 1 回設定して計測 (E2E は ctx.font 代入回数 ≤ 異なりフォント数 + 1 を数える)
430
+ // バケット毎にフォントを 1 回設定して計測 (E2E は ctx.font 代入回数 ≤ 異なりフォント数 + 1 を数える)。文字の間隔 (読み手の
431
+ // スタイルの上書きを含む。WCAG 1.4.12) も描くとおりに測る: canvas は CSS の間隔を受け継がず、上書きはふつう em で書かれて書体の
432
+ // 大きさに比例するため、本体ペインの中でバケットの書体を当てた見えない見本の計算値を読む (計算値の normal は間隔 0)
433
+ const probe = fontSource.ownerDocument.createElement("span")
434
+ probe.setAttribute("aria-hidden", "true")
435
+ probe.style.position = "absolute"
436
+ probe.style.visibility = "hidden"
437
+ fontSource.append(probe)
427
438
  const widestByCol = new Map<number, number>()
428
439
  for (const [font, cells] of buckets) {
429
440
  context.font = font
441
+ probe.style.font = font
442
+ const spacing = getComputedStyle(probe)
443
+ context.letterSpacing = spacing.letterSpacing === "normal" ? "0px" : spacing.letterSpacing
444
+ context.wordSpacing = spacing.wordSpacing === "normal" ? "0px" : spacing.wordSpacing
430
445
  for (const cell of cells) {
431
446
  const width = context.measureText(cell.text).width
432
447
  const widest = widestByCol.get(cell.col)
@@ -435,6 +450,7 @@ export const useHeaderResize = (params: UseHeaderResizeParams): HeaderResizeMach
435
450
  }
436
451
  }
437
452
  }
453
+ probe.remove()
438
454
  const entries: ResizeEntry[] = []
439
455
  for (const col of targets) {
440
456
  const widest = widestByCol.get(col)
@@ -120,6 +120,12 @@ type UseGridKeyboardParams = {
120
120
  setSelection: (next: SelectionState) => void
121
121
  moveActive: (input: MoveActiveInput) => void
122
122
  ensureCellVisible: (cell: CellCoord) => void
123
+ /**
124
+ * The height a page move travels, in logical px, or -1 while unmeasured (v0.17.1): the grid's viewport cut to the part
125
+ * of the body the reader sees, so a grid taller than its page pages by a screenful. / ページ移動が進む高さ (論理 px。未計測は
126
+ * -1。v0.17.1)。グリッドの表示域を読み手に見えている本体の部分で切り詰めたもので、ページより高いグリッドも 1 画面ずつ進む。
127
+ */
128
+ pageExtent: () => number
123
129
  isEditing: () => boolean
124
130
  requestCommit: () => boolean
125
131
  startEdit: (mode: "edit" | "replace") => void
@@ -390,19 +396,25 @@ export const useGridKeyboard = (params: UseGridKeyboardParams): void => {
390
396
  * approximation replaced by Fenwick geometry; O(log n)). The base is the MOVING
391
397
  * endpoint: active for reset moves, the extension corner for Shift+Page (an active
392
398
  * base would mis-land on tall selections AND identity-bail the 2nd keystroke). The
393
- * landing is structurally visible (indexAt skips zero-size tracks — §5.2).
399
+ * landing is structurally visible (indexAt skips zero-size tracks — §5.2). The travel is
400
+ * `pageExtent` (v0.17.1): the viewport cut to the part of the body the reader sees. A travel
401
+ * shorter than the base row (a tall row, a body barely seen) still moves one visible row (v0.17.2).
394
402
  * 基点行からの正確なページ移動先 (§9 — v0.1 の一様割り近似を Fenwick 幾何へ置換)。
395
403
  * 基点は移動する端点 (reset = active、Shift 系 = 伸長隅)。着地は構造的に可視 (§5.2)。
404
+ * 進む高さは `pageExtent` (v0.17.1。表示域を読み手に見えている本体の部分で切り詰めたもの)。
405
+ * 基点の行より短い移動量 (高い行・わずかしか見えない本体) でも見える 1 行は進む (v0.17.2)。
396
406
  */
397
407
  const pageTargetRow = (baseRow: number, direction: "up" | "down"): number => {
398
408
  const p = paramsRef.current
399
- const viewportH = handleRef.current?.getViewportSize().height ?? -1
409
+ const viewportH = p.pageExtent()
400
410
  if (viewportH <= 0) {
401
411
  // ペイン未計測 (番兵 -1 / 高さ 0) はページ幾何が定義できない — 可視 1 歩へ縮退
402
412
  return stepVisible(p.rowAxis, baseRow, direction === "down" ? 1 : -1)
403
413
  }
404
414
  // indexAt は入力を [0, totalSize) へ内部クランプする — 端超過は最初 / 最後の可視行に解決
405
- return p.rowAxis.indexAt(p.rowAxis.offsetOf(baseRow) + (direction === "down" ? viewportH : -viewportH))
415
+ const target = p.rowAxis.indexAt(p.rowAxis.offsetOf(baseRow) + (direction === "down" ? viewportH : -viewportH))
416
+ // 下への移動量が基点の行の高さに届かないと着地は基点のまま — 押したキーが何もしないことにせず、見える 1 歩を進む
417
+ return target === baseRow ? stepVisible(p.rowAxis, baseRow, direction === "down" ? 1 : -1) : target
406
418
  }
407
419
 
408
420
  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: §6.6.1 キーマップ表を 1 枚の平坦 dispatch として写経した契約実装 — 表の行 = コードの分岐を 1:1 で保つことが監査可能性の根拠であり、キー別関数へ分割すると表との突合が壊れる (ADR-9: 表が契約)
@@ -111,6 +111,8 @@
111
111
  width: 100%;
112
112
  height: 100%;
113
113
  transform-origin: 0 0;
114
+ /* 包みの中の倍率 (倍率が 1 でないときは部品がインラインの style で上書きする)。包みの中で縮む線の太さを見た目で保つために読む */
115
+ --_aqsp-zoom: 1;
114
116
  }
115
117
 
116
118
  /* 見出し (列の記号・行の番号・角) を出さないグリッド (headings={false}): 格子の 2 本の帯を 0 にし、本体を根の左上から始める */
@@ -385,11 +387,19 @@
385
387
  mix-blend-mode: multiply;
386
388
  }
387
389
 
390
+ /*
391
+ * 選んだセルの枠 (キーボードの焦点の見え方。WCAG 2.4.13): ズームの包みの中で倍率ごと縮むため、太さを倍率で割り、整数の px へ
392
+ * 切り上げる。ブラウザは border の太さを整数の px へ切り捨てるので、割っただけでは 3 px を下回る段がある (2 倍で 1 px = 見た目 2 px)。
393
+ * 見た目の太さは 3 CSS px 以上・3 + 倍率 未満。セルの内側の 3 px の帯の面積 6(W + H) − 36 は、焦点の無いセルの 2 px の周の面積
394
+ * 4(W + H) + 16 を W + H ≥ 26 で上回り (倍率 25 % の 25 × 6 px のセルでも 150 ≥ 140)、帯が太くても面積は減らない。round() を
395
+ * 解さないブラウザでは太さの宣言が無効になり、初期値の 3 px (倍率ごと縮む) に戻る
396
+ */
388
397
  .aqsp-active-frame {
389
398
  position: absolute;
390
399
  top: 0;
391
400
  left: 0;
392
- border: 2px solid var(--_aqsp-accent);
401
+ border: 3px solid var(--_aqsp-accent);
402
+ border-width: round(up, calc(3px / var(--_aqsp-zoom)), 1px);
393
403
  box-sizing: border-box;
394
404
  }
395
405
 
@@ -1122,7 +1132,7 @@
1122
1132
  * v0.9 凍結分割線 (計画 §2.4 — ADR-20 / ADR-24): 全凍結境界の強い Excel / Sheets 風の線。
1123
1133
  * consumer 面は CSS 変数 2 つだけ (--aqsp-divider-color / --aqsp-divider-width — パッケージは
1124
1134
  * 読むだけで書き手は consumer スタイルシート単独。色の既定は .aqsp-root の別名 --_aqsp-divider-color が 1 度だけ書く)。
1125
- * 既定は 2px の #9ca3af (gray-400 — 既存全罫線より 1 段濃い)。width 0px は逃げ道 — 象限別 fill 断片の継ぎ目が再露出し forced-colors も
1135
+ * 既定は 2px の #858e9d (面と見出しの帯の両方に 3:1 — WCAG 1.4.11)。width 0px は逃げ道 — 象限別 fill 断片の継ぎ目が再露出し forced-colors も
1126
1136
  * 無描画 (意図的、README / 分冊 05 §8 登記)。位置 (leading 縁 0 / trailing 縁 0) と長さは
1127
1137
  * 各セグメントの静的インライン幾何 + ホストクリップが供給し、このブロックは太さと色だけを持つ。
1128
1138
  * pointer-events: none — バーは不活性で、リサイズの operand は帯側隣接ストリップ (ADR-20)。