@aiquants/spreadsheet 0.18.0 → 0.19.0

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.
@@ -12,7 +12,7 @@
12
12
  * the idle-sink self-repair. Modifier matching is STRICT per the table legend — combos not
13
13
  * listed in a row fall through untouched. v0.8 (plan §4.2.7 / ADR-17): the IME guard is the
14
14
  * shared `isCompositionKeydown`; the merged shortcut table is consulted ONCE per column
15
- * (editing column: after the pointing rows, only for EDITING_COLUMN_COMMANDS; idle column:
15
+ * (editing column: after the pointing rows, where only EDITING_COLUMN_COMMANDS run; idle column:
16
16
  * after the drag freeze, before the Arrow rows); the editing column gains the pointing rows
17
17
  * (Arrow / Shift+Arrow / Ctrl+Arrow move the reference cursor, F2 toggles the arm, F4 cycles
18
18
  * the anchor) and the reference-drag freeze (Escape aborts the drag only, every other key is
@@ -32,6 +32,12 @@
32
32
  * the v0.7 keymap. v0.10 read-only cells (design §4.1, via the required `rejectReadOnly`
33
33
  * funnel): G3 refuses the whole Delete / Backspace when the selection contains a read-only
34
34
  * cell — after the limit gate, before enumeration; an undeclared capability is byte-identical.
35
+ * v0.19: the chord of an available command with no editing-column row (fillDown's Ctrl+D,
36
+ * fillRight's Ctrl+R, insertLink's Ctrl+K …) never runs while editing, and when it types nothing
37
+ * in a text field (`isConsumedWhileEditing` — no Alt, a function key or Ctrl with a character
38
+ * key) the editing column consumes it after every row, so the browser's own shortcut (bookmark,
39
+ * reload, search box) never fires; the session is left untouched and `onCommandBlockedWhileEditing`
40
+ * reports the command and chord.
35
41
  *
36
42
  * シンク keydown 上のキーマップ実装 (§6.6.1 の契約表 — idle 列。編集列は Phase 3 の編集
37
43
  * セッションへ委譲)。v0.2 で findDataEdge ナビゲーション + ディスパッチ前 fail-fast 検証 (§2)・
@@ -43,7 +49,7 @@
43
49
  * タイミングガード・idle シンク自己修復を所有する。修飾は表の凡例どおり厳密一致 — 表に無い
44
50
  * 組合せは素通し。v0.8 (計画 §4.2.7 / ADR-17): IME ガードは共有の `isCompositionKeydown`、
45
51
  * merge 済みショートカット表は列ごとに 1 回だけ参照 (編集列: ポインティング行の後、
46
- * EDITING_COLUMN_COMMANDS に限る / idle 列: ドラッグ凍結の後、Arrow 系の前)。編集列は
52
+ * 実行は EDITING_COLUMN_COMMANDS に限る / idle 列: ドラッグ凍結の後、Arrow 系の前)。編集列は
47
53
  * ポインティング行 (Arrow / Shift+Arrow / Ctrl+Arrow が参照カーソル、F2 が武装トグル、F4 が
48
54
  * $ 循環) と参照ドラッグ凍結 (Escape はドラッグだけ中断、他キーは consume) を得る。Delete は
49
55
  * 側面宣言時に `hyperlink: null` を運び、Escape チェーンは step 0 (ノート tip 消灯) と step 1
@@ -58,7 +64,11 @@
58
64
  * Sheets やコマンド行と同じく成立する (ラテン配列では生成文字照合と同一)。追加は全て能力 param —
59
65
  * 不在 = v0.7 キーマップ。v0.10 読み取り専用セル (設計 §4.1、必須 `rejectReadOnly` 漏斗経由):
60
66
  * G3 は選択に読み取り専用セルを含む Delete / Backspace を全体拒否する — 限度ゲート後・列挙前。
61
- * 能力未宣言はバイト恒等。
67
+ * 能力未宣言はバイト恒等。v0.19: 編集列に行の無い利用可能なコマンドのチョード (fillDown の Ctrl+D・
68
+ * fillRight の Ctrl+R・insertLink の Ctrl+K …) は編集中に走らず、入力欄に何も打たないチョード
69
+ * (`isConsumedWhileEditing` — Alt なしで機能キーか Ctrl + 文字キー) なら編集列が全ての行の後で消費する
70
+ * — ブラウザの既定 (ブックマーク・再読込・検索欄) は発火しない。セッションには触らず、
71
+ * `onCommandBlockedWhileEditing` がコマンドとチョードを報告する。
62
72
  */
63
73
 
64
74
  import type { VirtualGridHandle } from "@aiquants/virtualscroll"
@@ -71,7 +81,7 @@ import { aspectCapabilities, type CellEdit, type EditRejection, type ReadOnlyRej
71
81
  import { colToViewportX, rowToViewportY } from "../model/frozenPartition.ts"
72
82
  import { reduceActiveCycle, type SelectionState } from "../selection/selectionState.ts"
73
83
  import { COMPOSITION_CLEAR_MS, isCompositionKeydown } from "./compositionGuard.ts"
74
- import { EDITING_COLUMN_COMMANDS, matchChord, parseChord, resolveCommand, type SpreadsheetCommand } from "./shortcuts.ts"
84
+ import { type CommandBinding, EDITING_COLUMN_COMMANDS, isConsumedWhileEditing, matchChord, parseChord, resolveBinding, resolveCommand, type SpreadsheetCommand } from "./shortcuts.ts"
75
85
 
76
86
  /** Discriminated moveActive input (§6.6.2-3). / moveActive の判別 union 入力。 */
77
87
  export type MoveActiveInput = { mode: "cycle"; direction: SpreadsheetDirection } | { mode: "reset" | "extend"; cell: CellCoord }
@@ -153,6 +163,14 @@ type UseGridKeyboardParams = {
153
163
  rearmSink: () => void
154
164
  /** v0.8 capability (ADR-17): consumer-rebindable command rows. Undefined = no command rows (v0.7 keymap). / v0.8 能力 (ADR-17): 再バインド可能なコマンド行。undefined = コマンド行なし (v0.7 キーマップ)。 */
155
165
  commands?: CommandDispatch
166
+ /**
167
+ * Report of a command chord the editing column consumed without running (v0.19): an available command with no
168
+ * editing-column row whose chord types nothing (`isConsumedWhileEditing`) — the session is left untouched. Read
169
+ * through paramsRef; undefined = the chord is still consumed, silently.
170
+ * 編集列が実行せずに消費したコマンドのチョードの報告 (v0.19): 編集列に行の無い利用可能なコマンドで、チョードが何も打たない
171
+ * もの (`isConsumedWhileEditing`)。セッションには触らない。paramsRef 経由で読む。undefined でもチョードは黙って消費する。
172
+ */
173
+ onCommandBlockedWhileEditing?: (binding: CommandBinding) => void
156
174
  /** v0.8 capability (§2.7): the editor's pointing seams for the editing column. Undefined = no pointing rows (v0.7 editing column). / v0.8 能力 (§2.7): 編集列のポインティングシーム。undefined = ポインティング行なし (v0.7 編集列)。 */
157
175
  pointing?: PointingSeams
158
176
  /** v0.8 capability: the adapter whose declared aspects shape the Delete patch (`hyperlink: null` only when getCellHyperlink is declared). Undefined = text-only clear (v0.7). / v0.8 能力: Delete パッチの側面を決めるアダプタ (getCellHyperlink 宣言時だけ `hyperlink: null`)。undefined = text だけの消去 (v0.7)。 */
@@ -501,13 +519,11 @@ export const useGridKeyboard = (params: UseGridKeyboardParams): void => {
501
519
  // --- 編集列のコマンド (ADR-17 — EDITING_COLUMN_COMMANDS のみ: fillSelection / insertDate /
502
520
  // insertTime / 書式トグル / 揃え / 数値書式)。能力分岐: 表未配線 = 行不在 ---
503
521
  const editingCommands = p.commands
504
- if (editingCommands !== undefined) {
505
- const command = resolveCommand(editingCommands.table, event)
506
- if (command !== null && EDITING_COLUMN_COMMANDS.has(command) && editingCommands.isAvailable(command)) {
507
- event.preventDefault()
508
- editingCommands.execute(command)
509
- return
510
- }
522
+ const binding = editingCommands === undefined ? null : resolveBinding(editingCommands.table, event)
523
+ if (editingCommands !== undefined && binding !== null && EDITING_COLUMN_COMMANDS.has(binding.command) && editingCommands.isAvailable(binding.command)) {
524
+ event.preventDefault()
525
+ editingCommands.execute(binding.command)
526
+ return
511
527
  }
512
528
  if (direction !== undefined && !alt) {
513
529
  if (ctrl && event.shiftKey) {
@@ -566,6 +582,15 @@ export const useGridKeyboard = (params: UseGridKeyboardParams): void => {
566
582
  p.cancelEdit()
567
583
  return
568
584
  }
585
+ // --- 編集列に行の無いコマンドのチョード (fillDown の Ctrl+D / fillRight の Ctrl+R / insertLink の Ctrl+K …):
586
+ // 実行しないが、入力欄に何も打たないチョードはブラウザの既定 (ブックマーク / 再読込で入力値が消える /
587
+ // 検索欄へ移る) へも渡さない。Alt や文字の編集キーを含むチョードは文字の上の意味 (macOS の Option の文字・
588
+ // 単語移動、AltGr の文字) を保つため素通し。行の判定 (表の行) を全て見た後に置き、能力の読みは最後 ---
589
+ if (editingCommands !== undefined && binding !== null && !EDITING_COLUMN_COMMANDS.has(binding.command) && isConsumedWhileEditing(binding.chord) && editingCommands.isAvailable(binding.command)) {
590
+ event.preventDefault()
591
+ p.onCommandBlockedWhileEditing?.(binding)
592
+ return
593
+ }
569
594
  // その他 (Home / End / Delete / Ctrl+A / Z / Y / C / X / V / F2 / 印字) はネイティブへ素通し
570
595
  return
571
596
  }
@@ -68,6 +68,37 @@ export const rangeSize = (range: CellRange): { rows: number; cols: number } => (
68
68
  /** Total cell count across ranges WITHOUT materializing. / 実体化せずレンジ群の総セル数を見積もる (重複は重複のまま数え、上限判定を保守側に倒す)。 */
69
69
  export const countRangeCells = (ranges: readonly CellRange[]): number => ranges.reduce((sum, r) => sum + rangeSize(r).rows * rangeSize(r).cols, 0)
70
70
 
71
+ /**
72
+ * The cells of a range other than one cell, as at most four disjoint ranges in reading order: the rows above the cell,
73
+ * the cells left of it and right of it on its row, and the rows below. A range that does not contain the cell comes
74
+ * back whole (the same object); a 1×1 range of the cell itself leaves nothing.
75
+ * レンジから 1 セルを除いたセル。読む順で高々 4 つの非交なレンジ: セルより上の行・同じ行のセルの左と右・下の行。セルを
76
+ * 含まないレンジはそのまま (同じオブジェクト) 返し、そのセル自身の 1×1 のレンジは何も残さない。
77
+ *
78
+ * @param range - The range. レンジ。
79
+ * @param cell - The cell to leave out. 除くセル。
80
+ * @returns The disjoint ranges covering the rest. 残りを覆う非交なレンジ。
81
+ */
82
+ export const subtractCell = (range: CellRange, cell: CellCoord): readonly CellRange[] => {
83
+ if (!rangeContains(range, cell)) {
84
+ return [range]
85
+ }
86
+ const rest: CellRange[] = []
87
+ if (cell.row > range.startRow) {
88
+ rest.push(makeRange({ row: range.startRow, col: range.startCol }, { row: cell.row - 1, col: range.endCol }))
89
+ }
90
+ if (cell.col > range.startCol) {
91
+ rest.push(makeRange({ row: cell.row, col: range.startCol }, { row: cell.row, col: cell.col - 1 }))
92
+ }
93
+ if (cell.col < range.endCol) {
94
+ rest.push(makeRange({ row: cell.row, col: cell.col + 1 }, { row: cell.row, col: range.endCol }))
95
+ }
96
+ if (cell.row < range.endRow) {
97
+ rest.push(makeRange({ row: cell.row + 1, col: range.startCol }, { row: range.endRow, col: range.endCol }))
98
+ }
99
+ return rest
100
+ }
101
+
71
102
  /**
72
103
  * Enumerates the union of ranges exactly once per cell (row-major).
73
104
  * レンジ群の和集合をセル単位で**重複なく**行優先順に列挙する単一シーム。Delete のような
@@ -167,17 +167,25 @@ export type EditRejection = { source: "edit"; editSession: "kept" | "discarded"
167
167
  * refused gesture — the adapter was never called, so this is neither an {@link EditRejection}
168
168
  * (applyEdits never threw) nor an operation limit. `kind: "edit"` is a refused single-cell
169
169
  * text-write entry or commit and carries the cell; `kind: "operation"` is a refused whole
170
- * operation with its producer's own overlap-naive `cellCount` arithmetic (the same numbers the
171
- * limit channel reports — never a dedup count).
170
+ * operation with its producer's own overlap-naive `cellCount` arithmetic (the limit channel's
171
+ * vocabulary — overlapping ranges count once per range, never a dedup count). A refused fill
172
+ * (`op: "fill"`, v0.19) also names its `gesture` and carries its geometry, so a host can tell
173
+ * which cells refused it without re-deriving the fill rules: `targets` are the cells the fill
174
+ * would write (the read-only walk's domain — a read-only source never refuses) and `cellCount` is
175
+ * their total area; `sources` are the cells whose content it copies.
172
176
  * 読み取り専用拒否の文脈 (v0.10 — onReadOnlyRejected が届ける): 拒否されたジェスチャ毎に 1 回
173
177
  * 発火。adapter は呼ばれていないため {@link EditRejection} (applyEdits の throw) でも操作上限
174
178
  * でもない。`kind: "edit"` はセル単位テキスト書込の入口 / 確定の拒否でセル座標を運び、
175
179
  * `kind: "operation"` は操作全体の拒否で、`cellCount` はプロデューサ自身の overlap-naive 算術
176
- * (上限チャネルと同じ数 — dedup 数ではない)。
180
+ * (上限チャネルと同じ語彙 — 重なるレンジはレンジ毎に数え、dedup 数ではない)。fill の拒否
181
+ * (`op: "fill"`、v0.19) はさらに `gesture` を名指し幾何を運ぶ — host は fill の規則を写さずに
182
+ * どのセルが拒んだかを知れる: `targets` は fill が書くセル (読み取り専用 walk の対象 — 読み取り専用の
183
+ * 複製元は拒まない) で `cellCount` はその面積の和、`sources` は内容を複製されるセル。
177
184
  */
178
185
  // 明示リテラル union で宣言する (api-extractor は Exclude<SpreadsheetOperation, ...> 等の lib 汎用型を
179
186
  // d.ts ロールアップできない — EditRejection と同じ制約)。op の 7 リテラル (copy / cut / resize を除いた
180
- // 集合 + "cut") と editSession の 3 リテラルは dataAdapter.spec.ts の型パリティガードが双方向に機械封印する
187
+ // 集合 + "cut" — 2 つの operation 腕の和) と editSession の 3 リテラル、fill 腕の gesture の 4 リテラルと
188
+ // 幾何の必須性は dataAdapter.spec.ts の型パリティガードが双方向に機械封印する
181
189
  export type ReadOnlyRejection =
182
190
  | {
183
191
  readonly kind: "edit"
@@ -193,9 +201,49 @@ export type ReadOnlyRejection =
193
201
  }
194
202
  | {
195
203
  readonly kind: "operation"
196
- readonly op: "cut" | "delete" | "paste" | "fill" | "format" | "calc" | "annotate"
204
+ readonly op: "cut" | "delete" | "paste" | "format" | "calc" | "annotate"
197
205
  readonly cellCount: number
198
206
  }
207
+ | {
208
+ readonly kind: "operation"
209
+ readonly op: "fill"
210
+ /** Total area of `targets`. / `targets` の面積の和。 */
211
+ readonly cellCount: number
212
+ /**
213
+ * The refused gesture: the command (`fillDown` Ctrl+D, `fillRight` Ctrl+R, `fillSelection`
214
+ * Ctrl+Enter — idle, or with an open session) or `fillHandle`, the fill handle's drag.
215
+ * 拒否されたジェスチャ: コマンド (`fillDown` Ctrl+D・`fillRight` Ctrl+R・`fillSelection`
216
+ * Ctrl+Enter — 待機中、またはセッション中) か `fillHandle` (フィルハンドルのドラッグ)。
217
+ */
218
+ readonly gesture: "fillDown" | "fillRight" | "fillSelection" | "fillHandle"
219
+ /**
220
+ * The cells whose content the fill copies: fillDown — each range's first row, or the row
221
+ * above a one-row range; fillRight — each range's first column, or the column left of a
222
+ * one-column range; an idle fillSelection — the active cell; fillHandle — the dragged
223
+ * source block. A fillSelection with an open session writes the session's text and copies
224
+ * no cell: `[]`.
225
+ * 内容を複製されるセル: fillDown — 各レンジの先頭行 (1 行のレンジは上の行)、fillRight — 各
226
+ * レンジの先頭列 (1 列のレンジは左の列)、待機中の fillSelection — active セル、fillHandle —
227
+ * ドラッグした複製元の塊。セッション中の fillSelection はセッションの文字列を書きセルを複製
228
+ * しないので `[]`。
229
+ */
230
+ readonly sources: readonly CellRange[]
231
+ /**
232
+ * The cells the fill writes, in grid coordinates: fillDown / fillRight — each range without
233
+ * its source row / column (a one-row / one-column range whole; such a range on the first
234
+ * row / column has no neighbour and is skipped); an idle fillSelection — each range without
235
+ * the active cell (up to four rects per range); with an open session — every selected
236
+ * range, the active cell included; fillHandle — the drag's extension outside the source (one
237
+ * rect, or two disjoint ones forming an L on a diagonal drag). Rects overlap only where the
238
+ * selection's ranges do.
239
+ * fill が書くセル (グリッド座標): fillDown / fillRight — 各レンジから複製元の行 / 列を除いた
240
+ * もの (1 行 / 1 列のレンジは全体。先頭の行 / 列のそうしたレンジは隣が無いので飛ばす)、待機中の
241
+ * fillSelection — 各レンジから active セルを除いたもの (レンジ毎に高々 4 矩形)、セッション中 —
242
+ * active セルを含む全選択レンジ、fillHandle — ドラッグの複製元の外の拡張域 (1 矩形、斜めの
243
+ * ドラッグは L 字の非交な 2 矩形)。矩形が重なるのは選択のレンジが重なるところだけ。
244
+ */
245
+ readonly targets: readonly CellRange[]
246
+ }
199
247
 
200
248
  /**
201
249
  * The single data boundary between the grid and the consumer. Reads via getCellText (renderCell
@@ -258,17 +258,20 @@ const NO_TRACKS: readonly [number, number] = Object.freeze([0, -1] as const)
258
258
  export type FrameSpan = { near: number; far: number; nearOpen: boolean; farOpen: boolean }
259
259
 
260
260
  /**
261
- * One axis of a frame inside one layer (v0.18), or null when the layer paints none of the range on this axis or the
262
- * range lies wholly beyond the layer's ± 1 screen margin. The layer paints the tracks `first..last`; a side whose range
263
- * edge lies before `first` or after `last` continues into another pane (or past the axis's scrolled-away part), so it
264
- * is pushed to the margin and marked open — every pane frames only the cells it paints and the panes join into one
265
- * frame without a seam. An edge clamped into the margin is open too (it is not there). Exported for the direct value
266
- * pins (barrel-private).
267
- * 1 つの層の中の外枠の 1 つの軸 (v0.18)。層がこの軸で範囲のどこも描かないか、範囲が層の ±1 画面の余白より外にあれば null。層は
268
- * トラック `first..last` を描く。範囲の端が `first` より前か `last` より後にある側は別のペイン (かスクロールで外れた部分) へ続くため、
269
- * 余白の端に置いて開く — ペインはどれも自分が描くセルだけを囲み、継ぎ目の無い 1 つの枠になる。余白へ詰めた辺も (そこに無いので)
270
- * 開く。値ピン用にモジュール export (バレル非公開)。
261
+ * Resolves one axis of a frame inside one layer into `span` (v0.18) and answers whether the layer frames anything on
262
+ * it: false when the layer paints none of the range on this axis or the range lies wholly beyond the layer's ± 1 screen
263
+ * margin (`span` is then left as it was). The layer paints the tracks `first..last`; a side whose range edge lies
264
+ * before `first` or after `last` continues into another pane (or past the axis's scrolled-away part), so it is pushed
265
+ * to the margin's edge and marked open — every pane frames only the cells it paints and the panes join into one frame
266
+ * without a seam. An edge clamped into the margin is open too (it is not there). The span is written in place, so the
267
+ * repaint path resolves a frame without allocating. Exported for the direct value pins (barrel-private).
268
+ * 1 つの層の中の外枠の 1 つの軸を `span` へ解き (v0.18)、層がこの軸で何かを囲むかを返す。層がこの軸で範囲のどこも描かないか、
269
+ * 範囲が層の ±1 画面の余白より外にあれば false (`span` はそのまま)。層はトラック `first..last` を描く。範囲の端が `first` より前か
270
+ * `last` より後にある側は別のペイン (かスクロールで外れた部分) へ続くため、余白の端に置いて開く — ペインはどれも自分が描くセルだけを
271
+ * 囲み、継ぎ目の無い 1 つの枠になる。余白へ詰めた辺も (そこに無いので) 開く。範囲はその場へ書くため、描き直しの道は確保なしに
272
+ * 外枠を解く。値ピン用にモジュール export (バレル非公開)。
271
273
  *
274
+ * @param span - The span to write. 書く軸の範囲。
272
275
  * @param start - The range's first track on this axis. 範囲のこの軸の最初のトラック。
273
276
  * @param end - The range's last track on this axis. 範囲のこの軸の最後のトラック。
274
277
  * @param first - The layer's first painted track. 層が描く最初のトラック。
@@ -276,11 +279,11 @@ export type FrameSpan = { near: number; far: number; nearOpen: boolean; farOpen:
276
279
  * @param nearEdge - The range's near edge through the layer's map (px). 層の写像を通した範囲の近い辺 (px)。
277
280
  * @param farEdge - The range's far edge through the layer's map (px). 層の写像を通した範囲の遠い辺 (px)。
278
281
  * @param clamp - The layer's clamp extent (px). 層のクランプ範囲 (px)。
279
- * @returns The span, or null. 軸の範囲、または null。
282
+ * @returns Whether the layer frames anything on this axis. 層がこの軸で何かを囲むか。
280
283
  */
281
- export const frameSpanOf = (start: number, end: number, first: number, last: number, nearEdge: number, farEdge: number, clamp: number): FrameSpan | null => {
284
+ export const frameSpanInto = (span: FrameSpan, start: number, end: number, first: number, last: number, nearEdge: number, farEdge: number, clamp: number): boolean => {
282
285
  if (clamp <= 0 || last < first || end < first || start > last) {
283
- return null
286
+ return false
284
287
  }
285
288
  const low = -clamp * CLAMP_MARGIN_SCREENS
286
289
  const high = clamp * (1 + CLAMP_MARGIN_SCREENS)
@@ -289,9 +292,45 @@ export const frameSpanOf = (start: number, end: number, first: number, last: num
289
292
  const near = nearInside ? nearEdge : low
290
293
  const far = farInside ? farEdge : high
291
294
  if (far <= low || near >= high) {
292
- return null
295
+ return false
293
296
  }
294
- return { near: Math.max(near, low), far: Math.min(far, high), nearOpen: !nearInside || near < low, farOpen: !farInside || far > high }
297
+ span.near = Math.max(near, low)
298
+ span.far = Math.min(far, high)
299
+ span.nearOpen = !nearInside || near < low
300
+ span.farOpen = !farInside || far > high
301
+ return true
302
+ }
303
+
304
+ /**
305
+ * A span no frame has resolved into yet (NaN edges never equal a resolved one, so the first placement always writes).
306
+ * まだどの外枠も解いていない軸の範囲を作る処理 (NaN の辺は解いた辺と等しくならず、最初の置き方は必ず書く)。
307
+ *
308
+ * @returns The span. 軸の範囲。
309
+ */
310
+ const unresolvedSpanOf = (): FrameSpan => ({ near: Number.NaN, far: Number.NaN, nearOpen: false, farOpen: false })
311
+
312
+ /**
313
+ * Whether two spans place a frame's axis alike (their edges and open sides).
314
+ * 2 つの軸の範囲が外枠の軸を同じに置くか (辺と開いた側)。
315
+ *
316
+ * @param a - One span. 一方の範囲。
317
+ * @param b - The other span. もう一方の範囲。
318
+ * @returns True when they are alike. 同じなら true。
319
+ */
320
+ const sameSpan = (a: FrameSpan, b: FrameSpan): boolean => a.near === b.near && a.far === b.far && a.nearOpen === b.nearOpen && a.farOpen === b.farOpen
321
+
322
+ /**
323
+ * Copies a span's edges and open sides.
324
+ * 軸の範囲の辺と開いた側を写す処理。
325
+ *
326
+ * @param to - The span to write. 書く範囲。
327
+ * @param from - The span to read. 読む範囲。
328
+ */
329
+ const copySpan = (to: FrameSpan, from: FrameSpan): void => {
330
+ to.near = from.near
331
+ to.far = from.far
332
+ to.nearOpen = from.nearOpen
333
+ to.farOpen = from.farOpen
295
334
  }
296
335
 
297
336
  /** The frame's sides in the CSS order, bit i of an open-side mask naming side i (v0.18). / CSS の順の外枠の辺 (v0.18)。開いた辺のマスクの bit i が辺 i。 */
@@ -742,29 +781,41 @@ export type ResizeGuide = { axis: "row" | "col"; position: number; anchor: "lead
742
781
  type FillSlot = { node: HTMLDivElement; last: { shown: boolean; width: number; height: number; transform: string } }
743
782
 
744
783
  /**
745
- * The frame node of one quadrant plus its last-written values (v0.18 — same-value suppressed like a fill slot): the
746
- * insets and sizes as CSS ("" = cleared) and the open-side mask of `data-aqsp-frame-open` (-1 = never written).
747
- * 象限 1 つの外枠のノードと直近の書き込み値 (v0.18 — fill のスロットと同じく同値抑止): CSS の詰めと大きさ ("" は外した値) と、
748
- * `data-aqsp-frame-open` の開いた辺のマスク (-1 は未書込)。
784
+ * The frame node of one quadrant plus its placement state (v0.18 — same-value suppressed like a fill slot): the spans
785
+ * each repaint resolves into (`x`, `y`), the spans last placed (`drawnX`, `drawnY` — CSS is built only when they differ),
786
+ * the insets and sizes last written as CSS ("" = cleared) and the open-side mask of `data-aqsp-frame-open` (-1 = never
787
+ * written). A repaint that changes nothing allocates nothing.
788
+ * 象限 1 つの外枠のノードと置き方の状態 (v0.18 — fill のスロットと同じく同値抑止): 描き直しのたびに解く軸の範囲 (`x`・`y`)、最後に
789
+ * 置いた軸の範囲 (`drawnX`・`drawnY` — 違うときだけ CSS を作る)、最後に書いた CSS の詰めと大きさ ("" は外した値) と、
790
+ * `data-aqsp-frame-open` の開いた辺のマスク (-1 は未書込)。何も変えない描き直しは何も確保しない。
749
791
  */
750
- type FrameSlot = { node: HTMLDivElement; last: { shown: boolean; left: string; top: string; right: string; bottom: string; width: string; height: string; open: number } }
792
+ type FrameSlot = {
793
+ node: HTMLDivElement
794
+ x: FrameSpan
795
+ y: FrameSpan
796
+ drawnX: FrameSpan
797
+ drawnY: FrameSpan
798
+ last: { shown: boolean; left: string; top: string; right: string; bottom: string; width: string; height: string; open: number }
799
+ }
751
800
 
752
801
  /**
753
- * One axis of a frame node's CSS placement (v0.18): a closed near side at its mapped position and an open one at the
754
- * quadrant's edge (0); a closed far side through the size and an open one pinned to the quadrant's far edge (end inset
755
- * 0, size auto). Open sides follow the quadrant's own size, so a resize that repaints nothing still runs the frame's
756
- * other lines to the quadrant's edge. Exported for the direct value pins (barrel-private).
757
- * 外枠のノードの 1 つの軸の CSS の置き方 (v0.18): 閉じた近い辺は写像の位置、開いた近い辺は象限の端 (0)。閉じた遠い辺は大きさで、
758
- * 開いた遠い辺は象限の遠い端に付ける (端の詰め 0、大きさ auto)。開いた辺は象限自身の大きさに従うため、何も描き直さない大きさの変化
759
- * でも、枠のほかの線は象限の端まで届く。値ピン用にモジュール export (バレル非公開)。
802
+ * One axis of a frame node's CSS placement (v0.18): the near side at its span position — a closed one where the range
803
+ * starts, an open one at the margin's edge, a screen before the quadrant's start, where its missing line is out of view
804
+ * — and a closed far side through the size, an open one pinned to the quadrant's far edge (end inset 0, size auto). The
805
+ * size of a closed far side is therefore never negative (its edge lies past the margin's), so a range that scrolled
806
+ * out before the quadrant's start leaves no stale box, and its far line sits where the range ends even within a line's
807
+ * width of the start. An open far side follows the quadrant's own size, so a resize that repaints nothing still runs
808
+ * the frame's other lines to the quadrant's edge. Exported for the direct value pins (barrel-private).
809
+ * 外枠のノードの 1 つの軸の CSS の置き方 (v0.18): 近い辺は軸の範囲の位置 — 閉じた辺は範囲の始まり、開いた辺は余白の端 (象限の始まりの
810
+ * 1 画面手前。描かない線は見えない所) — に置く。閉じた遠い辺は大きさで、開いた遠い辺は象限の遠い端に付ける (端の詰め 0、大きさ
811
+ * auto)。そのため閉じた遠い辺の大きさは負にならず (その辺は余白の端より先にある)、象限の始まりより手前へスクロールで外れた範囲が
812
+ * 古い箱を残さず、始まりから線の太さの内でも遠い線は範囲の終わりに描かれる。開いた遠い辺は象限自身の大きさに従うため、何も描き
813
+ * 直さない大きさの変化でも、枠のほかの線は象限の端まで届く。値ピン用にモジュール export (バレル非公開)。
760
814
  *
761
- * @param span - The axis's span (`frameSpanOf`). 軸の範囲 (`frameSpanOf`)。
815
+ * @param span - The axis's span (`frameSpanInto`). 軸の範囲 (`frameSpanInto`)。
762
816
  * @returns The start inset, the end inset and the size as CSS ("" = cleared). 始まりの詰め・終わりの詰め・大きさの CSS ("" は外す)。
763
817
  */
764
- export const frameAxisCssOf = (span: FrameSpan): { start: string; end: string; size: string } => {
765
- const start = span.nearOpen ? 0 : span.near
766
- return span.farOpen ? { start: `${start}px`, end: "0px", size: "" } : { start: `${start}px`, end: "", size: `${span.far - start}px` }
767
- }
818
+ export const frameAxisCssOf = (span: FrameSpan): { start: string; end: string; size: string } => (span.farOpen ? { start: `${span.near}px`, end: "0px", size: "" } : { start: `${span.near}px`, end: "", size: `${span.far - span.near}px` })
768
819
 
769
820
  /** Resident node set of one overlay layer (v0.5 layer split; every layer owns a dedicated container). / overlay 1 層ぶんの常設ノード束 (v0.5 の層分割。全層が専用コンテナを持つ)。 */
770
821
  type LayerNodes = {
@@ -887,14 +938,18 @@ type LayerCtx = {
887
938
  */
888
939
  cells: BandExtents
889
940
  /**
890
- * The layer's cells per axis from the tracks alone (`layerCellsOf`, v0.18) — null for a frozen band and in an unframed
891
- * grid. They size the band clip and stop the dividers through CSS (`cellsSizeCssOf` / `cellsEndCssOf`), so both keep up
892
- * with a resize that repaints nothing.
893
- * 層の軸ごとのトラックだけから決まるセル (`layerCellsOf`、v0.18) — 凍結の帯と枠の無いグリッドは null。帯の切り抜きの大きさと
894
- * 分割線の止まる所を CSS で決め (`cellsSizeCssOf` / `cellsEndCssOf`)、何も描き直さない大きさの変化にも追いつく。
941
+ * The CSS of the layer's cells per axis (v0.18), resolved with the cached descriptors from the tracks alone
942
+ * (`layerCellsOf`): the band clip's size (`cellsSizeCssOf`) and the dividers' end inset (`cellsEndCssOf`) — the whole
943
+ * quadrant for a frozen band and in an unframed grid. CSS keeps both up with a resize that repaints nothing, and
944
+ * resolving them once per split geometry keeps a steady scroll frame from building them again.
945
+ * 層の軸ごとのセルの CSS (v0.18)。キャッシュした記述子と一緒に、トラックだけ (`layerCellsOf`) から解く: 帯の切り抜きの大きさ
946
+ * (`cellsSizeCssOf`) と分割線の端の詰め (`cellsEndCssOf`) — 凍結の帯と枠の無いグリッドは象限いっぱい。CSS が何も描き直さない
947
+ * 大きさの変化にも追いつき、分割の幾何ごとに 1 度だけ解くため、定常のスクロールのフレームは作り直さない。
895
948
  */
896
- xCells: number | null
897
- yCells: number | null
949
+ xCellsSizeCss: string
950
+ yCellsSizeCss: string
951
+ xCellsEndCss: string
952
+ yCellsEndCss: string
898
953
  }
899
954
 
900
955
  /**
@@ -1105,14 +1160,6 @@ export const SelectionOverlay = ({
1105
1160
  nodes.dividerShown[slot] = shown
1106
1161
  node.style.display = shown ? "" : "none"
1107
1162
  }, [])
1108
- /**
1109
- * Equality-suppressed end heal of one divider slot (v0.18): a framed grid stops its dividers at the last painted
1110
- * cell, so the vertical slots (0, 1) take `bottom` and the horizontal ones (2, 3) take `right` — the layer's clamp
1111
- * extent minus its painted extent. An unframed grid computes 0, the JSX's end, and writes nothing.
1112
- * 分割線スロット 1 つの端の等値抑制 heal (v0.18): 枠のあるグリッドは分割線を最後に描くセルで止めるため、縦のスロット (0・1) は
1113
- * `bottom`、横 (2・3) は `right` に、層のクランプ範囲からセルを描く長さを引いた値を書く。枠の無いグリッドは JSX の端と同じ 0 に
1114
- * なり、何も書かない。
1115
- */
1116
1163
  /**
1117
1164
  * Equality-suppressed size heal of the quadrant's band clip (v0.18): the cells the layer paints, so the band groups
1118
1165
  * inside it end at the last painted cell. A quadrant without a clip (no frame) writes nothing.
@@ -1133,6 +1180,15 @@ export const SelectionOverlay = ({
1133
1180
  clip.style.height = height
1134
1181
  }
1135
1182
  }, [])
1183
+ /**
1184
+ * Equality-suppressed end heal of one divider slot (v0.18): a framed grid stops its dividers at the last painted
1185
+ * cell, so the vertical slots (0, 1) take `bottom` and the horizontal ones (2, 3) take `right` — the part of the
1186
+ * quadrant past the layer's cells as CSS (`cellsEndCssOf`, resolved with the layer's descriptor), which follows a
1187
+ * resize that repaints nothing. An unframed grid's inset is `0px`, the JSX's end, and writes nothing.
1188
+ * 分割線スロット 1 つの端の等値抑制 heal (v0.18): 枠のあるグリッドは分割線を最後に描くセルで止めるため、縦のスロット (0・1) は
1189
+ * `bottom`、横 (2・3) は `right` に、象限のうち層のセルより先の部分を CSS で書く (`cellsEndCssOf`。層の記述子と一緒に解く)。何も
1190
+ * 描き直さない大きさの変化にも従う。枠の無いグリッドの詰めは JSX の端と同じ `0px` で、何も書かない。
1191
+ */
1136
1192
  const healDividerEnd = useCallback((nodes: LayerNodes, slot: number, inset: string) => {
1137
1193
  const node = nodes.dividerSlots[slot]
1138
1194
  if (node === null || nodes.dividerEnd[slot] === inset) {
@@ -1275,8 +1331,10 @@ export const SelectionOverlay = ({
1275
1331
  yFirst,
1276
1332
  yLast,
1277
1333
  cells: { clampWidth: paintedExtentOf(xs.clamp, xCells), clampHeight: paintedExtentOf(ys.clamp, yCells) },
1278
- xCells,
1279
- yCells,
1334
+ xCellsSizeCss: cellsSizeCssOf(xCells),
1335
+ yCellsSizeCss: cellsSizeCssOf(yCells),
1336
+ xCellsEndCss: cellsEndCssOf(xCells),
1337
+ yCellsEndCss: cellsEndCssOf(yCells),
1280
1338
  })
1281
1339
  }
1282
1340
  }
@@ -1320,14 +1378,12 @@ export const SelectionOverlay = ({
1320
1378
  healDivider(ctx.nodes, 2, showYLead)
1321
1379
  healDivider(ctx.nodes, 3, showYTrail)
1322
1380
  // 枠のあるグリッドの分割線は層のセルで止める (縦は下、横は右を詰める。枠が無ければ 0px で書かない)
1323
- const endY = cellsEndCssOf(ctx.yCells)
1324
- const endX = cellsEndCssOf(ctx.xCells)
1325
- healDividerEnd(ctx.nodes, 0, endY)
1326
- healDividerEnd(ctx.nodes, 1, endY)
1327
- healDividerEnd(ctx.nodes, 2, endX)
1328
- healDividerEnd(ctx.nodes, 3, endX)
1381
+ healDividerEnd(ctx.nodes, 0, ctx.yCellsEndCss)
1382
+ healDividerEnd(ctx.nodes, 1, ctx.yCellsEndCss)
1383
+ healDividerEnd(ctx.nodes, 2, ctx.xCellsEndCss)
1384
+ healDividerEnd(ctx.nodes, 3, ctx.xCellsEndCss)
1329
1385
  // 帯の切り抜きは層のセルの大きさ (枠の無いグリッドには切り抜きが無い)
1330
- healBandClip(ctx.nodes, cellsSizeCssOf(ctx.xCells), cellsSizeCssOf(ctx.yCells))
1386
+ healBandClip(ctx.nodes, ctx.xCellsSizeCss, ctx.yCellsSizeCss)
1331
1387
  }
1332
1388
  return cache.ctxs
1333
1389
  },
@@ -1365,7 +1421,7 @@ export const SelectionOverlay = ({
1365
1421
  * のときだけで、毎フレームでは走らない。
1366
1422
  */
1367
1423
  const setFrameSlot = useCallback((n: LayerNodes, el: HTMLDivElement | null) => {
1368
- n.frame = el === null ? null : { node: el, last: { shown: false, left: "", top: "", right: "", bottom: "", width: "", height: "", open: -1 } }
1424
+ n.frame = el === null ? null : { node: el, x: unresolvedSpanOf(), y: unresolvedSpanOf(), drawnX: unresolvedSpanOf(), drawnY: unresolvedSpanOf(), last: { shown: false, left: "", top: "", right: "", bottom: "", width: "", height: "", open: -1 } }
1369
1425
  rebuildChrome(n)
1370
1426
  }, [])
1371
1427
  /**
@@ -1563,17 +1619,26 @@ export const SelectionOverlay = ({
1563
1619
  }, [])
1564
1620
 
1565
1621
  /**
1566
- * Places one quadrant's frame (v0.18): the part of the frame range the layer paints (`frameSpanOf` on both axes, the
1567
- * range first cut to the grid by `frameRangeWithin`), with the sides the range continues past marked open
1622
+ * The frame range cut to the grid (`frameRangeWithin`), resolved again only when the range or the grid's counts
1623
+ * change, so a repaint pass reads it without allocating.
1624
+ * グリッドへ切った外枠の範囲 (`frameRangeWithin`)。範囲かグリッドの数が変わったときだけ解き直し、描き直しのパスは確保なしに読む。
1625
+ */
1626
+ const frameWithinRef = useRef<{ range: CellRange | undefined; rows: number; cols: number; within: CellRange | null }>({ range: undefined, rows: -1, cols: -1, within: null })
1627
+ /**
1628
+ * Places one quadrant's frame (v0.18): the part of the frame range the layer paints (`frameSpanInto` on both axes,
1629
+ * the range first cut to the grid by `frameRangeWithin`), with the sides the range continues past marked open
1568
1630
  * (`data-aqsp-frame-open`), hidden when the layer paints none of it, placed by insets (`frameAxisCssOf`) so its open
1569
- * sides follow the quadrant's size. Every write is same-value suppressed (the fill slot's census #23 discipline): a
1570
- * steady scroll frame writes at most one inset per scrolled axis — the frame is one leaf node per quadrant, so the
1571
- * layout an inset costs is negligible next to keeping the open sides right without a repaint.
1572
- * 象限 1 つの外枠を置く (v0.18): 範囲 (先に `frameRangeWithin` でグリッドへ切る) のうち層が描く部分 (両軸の `frameSpanOf`) を
1631
+ * far sides follow the quadrant's size. The spans resolve into the slot's own spans and the CSS is built only when
1632
+ * they differ from the spans last placed, so a repaint that moves nothing allocates nothing; every write is
1633
+ * same-value suppressed besides (the fill slot's census #23 discipline): a steady scroll frame writes at most the
1634
+ * insets of the scrolled axis — the frame is one leaf node per quadrant, so the layout an inset costs is negligible
1635
+ * next to keeping the open sides right without a repaint.
1636
+ * 象限 1 つの外枠を置く (v0.18): 範囲 (先に `frameRangeWithin` でグリッドへ切る) のうち層が描く部分 (両軸の `frameSpanInto`) を
1573
1637
  * 囲み、範囲が先へ続く辺は開く (`data-aqsp-frame-open`)。層が範囲のどこも描かなければ隠す。詰め (`frameAxisCssOf`) で置き、開いた
1574
- * 辺は象限の大きさに従う。書き込みはどれも同値抑止 (fill のスロットの census #23 の規律) で、定常のスクロールのフレームが書くのは
1575
- * スクロールした軸の詰め 1 つまで — 外枠は象限に 1 つの葉のノードで、詰めが起こす配置の手間は、描き直さずに開いた辺を正しく保つ
1576
- * ことに比べて小さい。
1638
+ * 遠い辺は象限の大きさに従う。軸の範囲はスロット自身の範囲へ解き、最後に置いた範囲と違うときだけ CSS を作るため、何も動かさない
1639
+ * 描き直しは何も確保しない。そのうえ書き込みはどれも同値抑止 (fill のスロットの census #23 の規律) で、定常のスクロールのフレームが
1640
+ * 書くのはスクロールした軸の詰めまで — 外枠は象限に 1 つの葉のノードで、詰めが起こす配置の手間は、描き直さずに開いた辺を正しく
1641
+ * 保つことに比べて小さい。
1577
1642
  */
1578
1643
  const placeFrame = useCallback(
1579
1644
  (ctx: LayerCtx) => {
@@ -1581,13 +1646,22 @@ export const SelectionOverlay = ({
1581
1646
  if (slot === null) {
1582
1647
  return
1583
1648
  }
1649
+ const cut = frameWithinRef.current
1584
1650
  const range = frameRangeRef.current
1585
- const within = range === undefined ? null : frameRangeWithin(range, rowAxis.count, colAxis.count)
1586
- const x = within === null ? null : frameSpanOf(within.startCol, within.endCol, ctx.xFirst, ctx.xLast, ctx.mapX(colAxis.offsetOf(within.startCol)), ctx.mapX(colAxis.offsetOf(within.endCol) + colAxis.sizeOf(within.endCol)), ctx.clampWidth)
1587
- const y = within === null ? null : frameSpanOf(within.startRow, within.endRow, ctx.yFirst, ctx.yLast, ctx.mapY(rowAxis.offsetOf(within.startRow)), ctx.mapY(rowAxis.offsetOf(within.endRow) + rowAxis.sizeOf(within.endRow)), ctx.clampHeight)
1651
+ if (cut.range !== range || cut.rows !== rowAxis.count || cut.cols !== colAxis.count) {
1652
+ cut.range = range
1653
+ cut.rows = rowAxis.count
1654
+ cut.cols = colAxis.count
1655
+ cut.within = range === undefined ? null : frameRangeWithin(range, rowAxis.count, colAxis.count)
1656
+ }
1657
+ const within = cut.within
1588
1658
  const last = slot.last
1589
1659
  const style = slot.node.style
1590
- if (x === null || y === null) {
1660
+ const framed =
1661
+ within !== null &&
1662
+ frameSpanInto(slot.x, within.startCol, within.endCol, ctx.xFirst, ctx.xLast, ctx.mapX(colAxis.offsetOf(within.startCol)), ctx.mapX(colAxis.offsetOf(within.endCol) + colAxis.sizeOf(within.endCol)), ctx.clampWidth) &&
1663
+ frameSpanInto(slot.y, within.startRow, within.endRow, ctx.yFirst, ctx.yLast, ctx.mapY(rowAxis.offsetOf(within.startRow)), ctx.mapY(rowAxis.offsetOf(within.endRow) + rowAxis.sizeOf(within.endRow)), ctx.clampHeight)
1664
+ if (!framed) {
1591
1665
  if (last.shown) {
1592
1666
  last.shown = false
1593
1667
  style.display = "none"
@@ -1598,33 +1672,39 @@ export const SelectionOverlay = ({
1598
1672
  last.shown = true
1599
1673
  style.display = "block"
1600
1674
  }
1601
- const horizontal = frameAxisCssOf(x)
1602
- const vertical = frameAxisCssOf(y)
1603
- if (horizontal.start !== last.left) {
1604
- last.left = horizontal.start
1605
- style.left = horizontal.start
1606
- }
1607
- if (horizontal.end !== last.right) {
1608
- last.right = horizontal.end
1609
- style.right = horizontal.end
1610
- }
1611
- if (horizontal.size !== last.width) {
1612
- last.width = horizontal.size
1613
- style.width = horizontal.size
1614
- }
1615
- if (vertical.start !== last.top) {
1616
- last.top = vertical.start
1617
- style.top = vertical.start
1618
- }
1619
- if (vertical.end !== last.bottom) {
1620
- last.bottom = vertical.end
1621
- style.bottom = vertical.end
1675
+ if (!sameSpan(slot.x, slot.drawnX)) {
1676
+ copySpan(slot.drawnX, slot.x)
1677
+ const horizontal = frameAxisCssOf(slot.x)
1678
+ if (horizontal.start !== last.left) {
1679
+ last.left = horizontal.start
1680
+ style.left = horizontal.start
1681
+ }
1682
+ if (horizontal.end !== last.right) {
1683
+ last.right = horizontal.end
1684
+ style.right = horizontal.end
1685
+ }
1686
+ if (horizontal.size !== last.width) {
1687
+ last.width = horizontal.size
1688
+ style.width = horizontal.size
1689
+ }
1622
1690
  }
1623
- if (vertical.size !== last.height) {
1624
- last.height = vertical.size
1625
- style.height = vertical.size
1691
+ if (!sameSpan(slot.y, slot.drawnY)) {
1692
+ copySpan(slot.drawnY, slot.y)
1693
+ const vertical = frameAxisCssOf(slot.y)
1694
+ if (vertical.start !== last.top) {
1695
+ last.top = vertical.start
1696
+ style.top = vertical.start
1697
+ }
1698
+ if (vertical.end !== last.bottom) {
1699
+ last.bottom = vertical.end
1700
+ style.bottom = vertical.end
1701
+ }
1702
+ if (vertical.size !== last.height) {
1703
+ last.height = vertical.size
1704
+ style.height = vertical.size
1705
+ }
1626
1706
  }
1627
- const open = frameOpenMaskOf(x, y)
1707
+ const open = frameOpenMaskOf(slot.x, slot.y)
1628
1708
  if (open !== last.open) {
1629
1709
  last.open = open
1630
1710
  if (open === 0) {