@aiquants/spreadsheet 0.18.1 → 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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aiquants/spreadsheet",
3
- "version": "0.18.1",
3
+ "version": "0.19.0",
4
4
  "description": "Excel-grade spreadsheet grid for React: multi-cell selection, TSV/HTML clipboard, in-place editing on top of @aiquants/virtualscroll",
5
5
  "sideEffects": [
6
6
  "**/*.css"
@@ -62,7 +62,7 @@
62
62
  },
63
63
  "devDependencies": {
64
64
  "@aiquants/virtualscroll": "3.22.1",
65
- "@playwright/test": "^1.59.1",
65
+ "@playwright/test": "^1.64.1",
66
66
  "@tailwindcss/cli": "^4.1.18",
67
67
  "@testing-library/jest-dom": "^6.9.1",
68
68
  "@testing-library/react": "^16.3.0",
@@ -669,6 +669,24 @@ export type SpreadsheetProps = {
669
669
  * 二重束縛は render 中 RangeError)。ref 経由で参照。
670
670
  */
671
671
  shortcuts?: ShortcutOverrides
672
+ /**
673
+ * Notice that a command chord was pressed while a cell is being edited and was consumed without running (v0.19):
674
+ * the command has no editing-column row (only the 16 editing-column commands run in an edit session — `fillDown`'s
675
+ * Ctrl+D, `fillRight`'s Ctrl+R, `insertLink`'s Ctrl+K do not) and the chord types nothing in a text field (no Alt;
676
+ * a function key, or Ctrl / Cmd with a letter, digit, punctuation or numpad key), so the grid stops the browser's own
677
+ * shortcut (bookmark, reload, search box) and leaves the session and its typed value untouched. `chord` is the
678
+ * canonical chord (Cmd reads as `Ctrl`). Chords with Alt or a text-editing key keep their text meaning and never come
679
+ * here; an unavailable or unbound command's chord is not consumed. To commit and run the command instead, call
680
+ * `executeCommand(command)` on the handle from this callback. Omit for silence (the chord is still consumed).
681
+ * セルの編集中に押されたコマンドのチョードを、実行せずに消費したことの通知 (v0.19)。そのコマンドは編集列に行が無く
682
+ * (編集セッションで走るのは編集列の 16 コマンドだけ — `fillDown` の Ctrl+D・`fillRight` の Ctrl+R・`insertLink` の Ctrl+K は
683
+ * 走らない)、チョードが入力欄に何も打たない (Alt なしで、機能キーか Ctrl / Cmd + 英字・数字・記号・テンキー) ため、グリッドは
684
+ * ブラウザの既定 (ブックマーク・再読込・検索欄) を止め、セッションと入力値には触らない。`chord` は正準チョード (Cmd は
685
+ * `Ctrl` と読む)。Alt や文字の編集キーを含むチョードは文字の上の意味を保ちここへは来ず、利用できないか未束縛のコマンドの
686
+ * チョードは消費しない。確定してから実行したいときは、このコールバックから handle の `executeCommand(command)` を呼ぶ。
687
+ * 省略で通知なし (チョードは消費する)。
688
+ */
689
+ onCommandBlockedWhileEditing?: (blocked: { readonly command: SpreadsheetCommand; readonly chord: string }) => void
672
690
  /**
673
691
  * Custom colour slots for `fillColorCustom1..5` / `fontColorCustom1..5`: each axis is exactly
674
692
  * 5 `#rrggbb` strings (a different length or a non-hex entry throws a RangeError at prop
@@ -1014,6 +1032,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
1014
1032
  locale,
1015
1033
  labels,
1016
1034
  shortcuts,
1035
+ onCommandBlockedWhileEditing,
1017
1036
  colors,
1018
1037
  formats,
1019
1038
  highlight,
@@ -2635,6 +2654,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2635
2654
  rearmSink,
2636
2655
  // v0.8 (§4.2.7): コマンド表、編集列のポインティング行、Delete の hyperlink 消去、Escape step 0、Ctrl+Shift+V
2637
2656
  commands: commandDispatch,
2657
+ onCommandBlockedWhileEditing,
2638
2658
  pointing: editor,
2639
2659
  adapter,
2640
2660
  hideNoteTip: () => hideNoteTipRef.current(),
@@ -92,7 +92,7 @@ import { gateResizeEntries, type ResizeEntry, ROW_FANOUT_DIVISOR, ROW_HIDDEN_LIM
92
92
  import { EDITING_COLUMN_COMMANDS, type SpreadsheetCommand } from "../keyboard/shortcuts.ts"
93
93
  import type { AxisModel } from "../model/axisModel.ts"
94
94
  import { type CellCommentInput, normalizeAdapterHyperlink, normalizeHyperlink } from "../model/cellAnnotations.ts"
95
- import { type CellCoord, type CellRange, countRangeCells, enumerateRangeCells, makeRange, type SpreadsheetOperation } from "../model/cellCoord.ts"
95
+ import { type CellCoord, type CellRange, countRangeCells, enumerateRangeCells, makeRange, type SpreadsheetOperation, subtractCell } from "../model/cellCoord.ts"
96
96
  import { BORDER_DEFAULT_COLOR, type CellBorder, type CellBorders, type CellFormat, type CellFormatPatch, type CellValueFormat, mergeFormat } from "../model/cellFormat.ts"
97
97
  import { normalizeColor } from "../model/cellPaint.ts"
98
98
  import { type CellEdit, type EditRejection, isReadOnlyCell, type ReadOnlyRejection, rangesContainReadOnly, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
@@ -314,6 +314,12 @@ const COMMAND_SPECS: { readonly [K in SpreadsheetCommand]: CommandSpec } = {
314
314
  toggleIntersectionHighlight: { kind: "highlight", target: "intersection" },
315
315
  }
316
316
 
317
+ /**
318
+ * The command behind each idle fill direction of COMMAND_SPECS — the `gesture` a G8 read-only refusal names.
319
+ * COMMAND_SPECS の待機中の fill の向きごとのコマンド — G8 の読み取り専用の拒否が名指す `gesture`。
320
+ */
321
+ const FILL_GESTURES = { down: "fillDown", right: "fillRight", selection: "fillSelection" } as const satisfies { readonly [D in "down" | "right" | "selection"]: SpreadsheetCommand }
322
+
317
323
  /** `clearFormatting` = every CellFormat key cleared (`-?` makes a newly added key a tsc error here). / clearFormatting = CellFormat 全キーの消去 (`-?` により新キーの追加漏れは tsc エラー)。 */
318
324
  const CLEAR_PATCH: { readonly [K in keyof CellFormat]-?: null } = { value: null, align: null, verticalAlign: null, wrap: null, background: null, color: null, bold: null, italic: null, underline: null, strikethrough: null, fontFamily: null, fontSize: null, borders: null }
319
325
 
@@ -526,12 +532,13 @@ export const useCommands = (params: UseCommandsParams): CommandRunner => {
526
532
  /**
527
533
  * fillDown / fillRight / fillSelection (idle) — two phases since v0.10 (§0.2 R2): phase 1
528
534
  * collects the (source, targets) pairs with coordinate arithmetic only (no reads, no edits),
535
+ * together with the gesture's geometry as rects (the sources and targets a G8 refusal reports),
529
536
  * the G8 read-only walk runs over the collected targets, and only a passing gesture
530
537
  * materialises (readFillSource + fillSourceEdit) and commits.
531
538
  * fillDown / fillRight / fillSelection (idle) — v0.10 から 2 相 (§0.2 R2): 第 1 相は座標算術
532
- * だけで (source, targets) 対を収集 (読みも edits 生成もしない)、G8 の読み取り専用 walk を
533
- * 収集済み targets に掛け、通過したジェスチャだけが実体化 (readFillSource + fillSourceEdit)
534
- * して commit する。
539
+ * だけで (source, targets) 対を収集し (読みも edits 生成もしない)、同時にジェスチャの幾何を矩形で
540
+ * 集める (G8 の拒否が報告する複製元と写し先)。G8 の読み取り専用 walk を収集済み targets に掛け、
541
+ * 通過したジェスチャだけが実体化 (readFillSource + fillSourceEdit) して commit する。
535
542
  */
536
543
  const runFill = useCallback(
537
544
  (direction: "down" | "right" | "selection"): boolean => {
@@ -540,8 +547,11 @@ export const useCommands = (params: UseCommandsParams): CommandRunner => {
540
547
  if (!gateSelectionWrite("fill", selection.ranges, p.maxOperationCells, p.onOperationRejected)) {
541
548
  return false
542
549
  }
543
- // 第 1 相: (source, targets) 対の収集のみ — 対の順序は従来の fillEdits 呼出し順と同一 (byte 恒等)
550
+ // 第 1 相: (source, targets) 対の収集のみ — 対の順序は従来の fillEdits 呼出し順と同一 (byte 恒等)。
551
+ // 矩形の幾何は対と同じ分岐で集める (fill の規則を拒否側で写し直さない)
544
552
  const pairs: { source: CellCoord; targets: CellCoord[] }[] = []
553
+ const sourceRects: CellRange[] = []
554
+ const targetRects: CellRange[] = []
545
555
  if (direction === "selection") {
546
556
  // active の内容を active 以外の全選択セルへ
547
557
  const active = selection.active
@@ -552,6 +562,10 @@ export const useCommands = (params: UseCommandsParams): CommandRunner => {
552
562
  }
553
563
  })
554
564
  pairs.push({ source: active, targets })
565
+ sourceRects.push(makeRange(active, active))
566
+ for (const range of selection.ranges) {
567
+ targetRects.push(...subtractCell(range, active))
568
+ }
555
569
  } else {
556
570
  for (const range of selection.ranges) {
557
571
  if (direction === "down") {
@@ -561,9 +575,12 @@ export const useCommands = (params: UseCommandsParams): CommandRunner => {
561
575
  continue
562
576
  }
563
577
  const sourceRow = single ? range.startRow - 1 : range.startRow
578
+ const firstTargetRow = single ? range.startRow : range.startRow + 1
579
+ sourceRects.push(makeRange({ row: sourceRow, col: range.startCol }, { row: sourceRow, col: range.endCol }))
580
+ targetRects.push(makeRange({ row: firstTargetRow, col: range.startCol }, { row: range.endRow, col: range.endCol }))
564
581
  for (let col = range.startCol; col <= range.endCol; col += 1) {
565
582
  const targets: CellCoord[] = []
566
- for (let row = single ? range.startRow : range.startRow + 1; row <= range.endRow; row += 1) {
583
+ for (let row = firstTargetRow; row <= range.endRow; row += 1) {
567
584
  targets.push({ row, col })
568
585
  }
569
586
  pairs.push({ source: { row: sourceRow, col }, targets })
@@ -575,9 +592,12 @@ export const useCommands = (params: UseCommandsParams): CommandRunner => {
575
592
  continue
576
593
  }
577
594
  const sourceCol = single ? range.startCol - 1 : range.startCol
595
+ const firstTargetCol = single ? range.startCol : range.startCol + 1
596
+ sourceRects.push(makeRange({ row: range.startRow, col: sourceCol }, { row: range.endRow, col: sourceCol }))
597
+ targetRects.push(makeRange({ row: range.startRow, col: firstTargetCol }, { row: range.endRow, col: range.endCol }))
578
598
  for (let row = range.startRow; row <= range.endRow; row += 1) {
579
599
  const targets: CellCoord[] = []
580
- for (let col = single ? range.startCol : range.startCol + 1; col <= range.endCol; col += 1) {
600
+ for (let col = firstTargetCol; col <= range.endCol; col += 1) {
581
601
  targets.push({ row, col })
582
602
  }
583
603
  pairs.push({ source: { row, col: sourceCol }, targets })
@@ -586,16 +606,12 @@ export const useCommands = (params: UseCommandsParams): CommandRunner => {
586
606
  }
587
607
  }
588
608
  // G8 (v0.10 §6.9): 収集済み対の全 targets を 1 サイトで walk (最初の hit で短絡)。読み取り
589
- // 専用**ソース**は walk 外 = 合法のまま (Excel 同等 — RC-G8)。拒否 cellCount = Σ targets.length
590
- // (overlap-naive — ONE 語彙)。実体化 (ソース読み) より前に立つ
609
+ // 専用**ソース**は walk 外 = 合法のまま (Excel 同等 — RC-G8)。拒否 cellCount = 写し先の矩形の面積の和
610
+ // (overlap-naive — ONE 語彙。重なる選択レンジも各レンジで数える)。実体化 (ソース読み) より前に立つ
591
611
  for (const pair of pairs) {
592
612
  for (const target of pair.targets) {
593
613
  if (isReadOnlyCell(p.adapter, target.row, target.col)) {
594
- let cellCount = 0
595
- for (const counted of pairs) {
596
- cellCount += counted.targets.length
597
- }
598
- p.rejectReadOnly({ kind: "operation", op: "fill", cellCount })
614
+ p.rejectReadOnly({ kind: "operation", op: "fill", cellCount: countRangeCells(targetRects), gesture: FILL_GESTURES[direction], sources: sourceRects, targets: targetRects })
599
615
  return false
600
616
  }
601
617
  }
@@ -636,9 +652,10 @@ export const useCommands = (params: UseCommandsParams): CommandRunner => {
636
652
  return false
637
653
  }
638
654
  // G9 (v0.10 §6.9): 読み取り専用壁 — validateCommit walk より前・セッション保持で
639
- // 全体拒否 (書込集合 = 選択そのもの、意図した粗さ — 設計 rule 3)
655
+ // 全体拒否 (書込集合 = 選択そのもの、意図した粗さ — 設計 rule 3)。セッションの文字列はセルではないので
656
+ // 複製元は空
640
657
  if (rangesContainReadOnly(p.adapter, selection.ranges)) {
641
- p.rejectReadOnly({ kind: "operation", op: "fill", cellCount: countRangeCells(selection.ranges) })
658
+ p.rejectReadOnly({ kind: "operation", op: "fill", cellCount: countRangeCells(selection.ranges), gesture: "fillSelection", sources: [], targets: selection.ranges })
642
659
  return false
643
660
  }
644
661
  // 検証ゲート (分冊 08 §4.2) は対象セル毎 — 規則はセル毎に違い得る。最初の strict 拒否で
@@ -9,8 +9,10 @@
9
9
  * Latin letter, otherwise by the `event.code` letter; digits / punctuation / function keys always
10
10
  * by code), strict chord matching with the AltGraph refusal (a row containing Alt is never
11
11
  * claimed by a real AltGr press), the column-aware consumer validation (merge = REPLACE per
12
- * command; every invalid input is a RangeError — fail-fast on the API surface) and the O(1)
13
- * runtime resolution of one keydown to a command.
12
+ * command; every invalid input is a RangeError — fail-fast on the API surface), the O(1)
13
+ * runtime resolution of one keydown to a command and its chord, and the rule that tells which
14
+ * chords of a command with no editing-column row the editing column consumes (a chord that types
15
+ * nothing in a text field — never one with Alt or a text-editing key).
14
16
  *
15
17
  * 再バインド可能コマンド表 (v0.8 ADR-17 — 計画 §1.5 / §2.6 / §4.1.11)。純関数・React 非依存:
16
18
  * SpreadsheetCommand の語彙、正準チョード文法 (`Ctrl+Alt+Shift+KEY` — 使う修飾だけ・順序固定・
@@ -20,7 +22,9 @@
20
22
  * トークンへ写す VK 規則 (文字は `event.key` が単一ラテン文字ならそれ、そうでなければ
21
23
  * `event.code` の文字。数字 / 記号 / 機能キーは常に code)、AltGraph 拒否つきの厳密チョード照合
22
24
  * (Alt を含む行は実 AltGr 押下で決して成立しない)、列を意識した consumer 検証 (merge = コマンド毎
23
- * REPLACE。無効入力は全て RangeError — API 面での fail-fast)、keydown 1 件の O(1) コマンド解決。
25
+ * REPLACE。無効入力は全て RangeError — API 面での fail-fast)、keydown 1 件の O(1) コマンドと
26
+ * チョードの解決、編集列に行の無いコマンドのチョードのうち編集列が消費するものを決める規則
27
+ * (入力欄に何も打たないチョード — Alt や文字の編集キーを含むものは決して消費しない)。
24
28
  */
25
29
 
26
30
  /**
@@ -760,17 +764,25 @@ export const validateShortcuts = (overrides: ShortcutOverrides | undefined): Rea
760
764
  return table
761
765
  }
762
766
 
767
+ /** A command and the canonical chord of the keydown that resolved to it. / コマンドと、それへ解決した keydown の正準チョード。 */
768
+ export type CommandBinding = { readonly command: SpreadsheetCommand; readonly chord: string }
769
+
763
770
  /**
764
- * Runtime resolution for one keydown: the command whose (merged) chord matches, or null. O(1) —
765
- * the event is folded to its canonical chord through the VK rule and looked up; an Alt chord
766
- * under a real AltGr press (`getModifierState("AltGraph")`) is never claimed. Equivalent to
767
- * "some table entry satisfies matchChord" because the grammar has one spelling per chord.
768
- * keydown 1 件のコマンド解決: (merge 済み) チョードが一致するコマンド、なければ null。O(1) —
771
+ * Runtime resolution for one keydown: the command whose (merged) chord matches, with that chord,
772
+ * or null. O(1) — the event is folded to its canonical chord through the VK rule and looked up; an
773
+ * Alt chord under a real AltGr press (`getModifierState("AltGraph")`) is never claimed.
774
+ * Equivalent to "some table entry satisfies matchChord" because the grammar has one spelling per
775
+ * chord.
776
+ * keydown 1 件の解決: (merge 済み) チョードが一致するコマンドとそのチョード、なければ null。O(1) —
769
777
  * event を VK 規則で正準チョードへ畳んで引く。実 AltGr 押下 (`getModifierState("AltGraph")`) の
770
778
  * Alt チョードは決して請求しない。文法がチョード 1 つに綴り 1 つなので「表のいずれかの項が
771
779
  * matchChord を満たす」と等価。
780
+ *
781
+ * @param table - The merged chord → command table (validateShortcuts' result). merge 済みのチョード → コマンド表。
782
+ * @param event - The keydown. keydown。
783
+ * @returns The binding, or null. 束縛、または null。
772
784
  */
773
- export const resolveCommand = (table: ReadonlyMap<string, SpreadsheetCommand>, event: KeyboardEvent): SpreadsheetCommand | null => {
785
+ export const resolveBinding = (table: ReadonlyMap<string, SpreadsheetCommand>, event: KeyboardEvent): CommandBinding | null => {
774
786
  const key = resolveKeyToken(event)
775
787
  if (key === null) {
776
788
  return null
@@ -780,6 +792,57 @@ export const resolveCommand = (table: ReadonlyMap<string, SpreadsheetCommand>, e
780
792
  if (alt && event.getModifierState("AltGraph")) {
781
793
  return null
782
794
  }
783
- const found = table.get(formatChord({ ctrl: event.ctrlKey || event.metaKey, alt, shift: event.shiftKey, key }))
784
- return found === undefined ? null : found
795
+ const chord = formatChord({ ctrl: event.ctrlKey || event.metaKey, alt, shift: event.shiftKey, key })
796
+ const command = table.get(chord)
797
+ return command === undefined ? null : { command, chord }
798
+ }
799
+
800
+ /**
801
+ * The command of {@link resolveBinding} for one keydown, or null.
802
+ * keydown 1 件の {@link resolveBinding} のコマンド、なければ null。
803
+ *
804
+ * @param table - The merged chord → command table. merge 済みのチョード → コマンド表。
805
+ * @param event - The keydown. keydown。
806
+ * @returns The command, or null. コマンド、または null。
807
+ */
808
+ export const resolveCommand = (table: ReadonlyMap<string, SpreadsheetCommand>, event: KeyboardEvent): SpreadsheetCommand | null => {
809
+ const binding = resolveBinding(table, event)
810
+ return binding === null ? null : binding.command
811
+ }
812
+
813
+ /**
814
+ * KEY tokens whose chords keep a meaning in a text field while Ctrl / Cmd or Shift is held: caret and selection moves
815
+ * (arrows, Home / End, the page keys), deletion (Delete / Backspace — Ctrl deletes a word), Enter, Tab, Space, Escape,
816
+ * Insert (Ctrl+Insert / Shift+Insert copy and paste on Windows) and the context-menu key.
817
+ * Ctrl / Cmd や Shift を押したままでも入力欄で意味を持つ KEY トークン: キャレットと選択の移動 (矢印・Home / End・ページの
818
+ * キー)・削除 (Delete / Backspace — Ctrl つきは単語単位)・Enter・Tab・Space・Escape・Insert (Windows の Ctrl+Insert /
819
+ * Shift+Insert はコピーと貼り付け)・コンテキストメニューのキー。
820
+ */
821
+ const TEXT_EDITING_KEY_TOKENS: ReadonlySet<string> = new Set(["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown", "Enter", "NumpadEnter", "Escape", "Space", "Tab", "Delete", "Backspace", "Insert", "ContextMenu"])
822
+
823
+ /** Function-key tokens (`F1`..`F12`). / 機能キーのトークン (`F1`..`F12`)。 */
824
+ const FUNCTION_KEY_TOKEN = /^F(?:[1-9]|1[0-2])$/
825
+
826
+ /**
827
+ * Whether the editing column consumes the chord of a command that does not run while a cell is being edited: true when
828
+ * the chord carries no Alt and is a function key (whatever the other modifiers) or Ctrl / Cmd with a character key (a
829
+ * letter, a digit, a punctuation key or a numpad key). Such a chord types nothing in a text field, while browsers bind
830
+ * many of them — Ctrl+D bookmarks the page, Ctrl+R reloads it and loses the typed value, Ctrl+K moves to the search box,
831
+ * Shift+F5 reloads past the cache. A chord with Alt (macOS Option characters and word moves, AltGr characters) or with
832
+ * a text-editing key keeps its meaning in the text and is never consumed; neither is Shift with a character key (typing).
833
+ * 編集中は走らないコマンドのチョードを編集列が消費するか。Alt を含まず、機能キー (ほかの修飾は問わない) か Ctrl / Cmd +
834
+ * 文字キー (英字・数字・記号・テンキー) なら true。こうしたチョードは入力欄に何も打たない一方、ブラウザが多くを束縛する —
835
+ * Ctrl+D はブックマーク、Ctrl+R は再読込で入力値を失い、Ctrl+K は検索欄へ移り、Shift+F5 はキャッシュを越えて再読込する。Alt を
836
+ * 含むチョード (macOS の Option の文字と単語移動・AltGr の文字) と文字の編集キーを含むチョードは文字の上で意味を保ち、決して
837
+ * 消費しない。Shift + 文字キー (文字の入力) も同じ。
838
+ *
839
+ * @param chord - A canonical chord. 正準のチョード。
840
+ * @returns True when the editing column consumes the chord. 編集列がそのチョードを消費するなら true。
841
+ */
842
+ export const isConsumedWhileEditing = (chord: string): boolean => {
843
+ const parsed = parseChord(chord)
844
+ if (parsed.alt || TEXT_EDITING_KEY_TOKENS.has(parsed.key)) {
845
+ return false
846
+ }
847
+ return parsed.ctrl || FUNCTION_KEY_TOKEN.test(parsed.key)
785
848
  }
@@ -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
@@ -18,8 +18,9 @@
18
18
  * v0.10 read-only wall (G7 — design ADR-28 rule 5): `confirmFill` walks the ≤2-rect disjoint
19
19
  * decomposition of box ∖ source (`fillExtensionRects` — diagonal L legs included) after the limit
20
20
  * gate and before `expandFill`; a hit refuses the WHOLE fill through the required
21
- * `rejectReadOnly` funnel with `cellCount` = box area − source area (exact — deliberately not the
22
- * limit gate's estimate) and the limit-refusal cleanup (no selection growth, no bumpEdit). Fill
21
+ * `rejectReadOnly` funnel — `gesture: "fillHandle"`, `sources` = the source block, `targets` = the
22
+ * walked rects and `cellCount` = their area = box area − source area (exact — deliberately not the
23
+ * limit gate's estimate) — with the limit-refusal cleanup (no selection growth, no bumpEdit). Fill
23
24
  * FROM a read-only source stays legal; capability undeclared = byte-identical behaviour.
24
25
  *
25
26
  * v0.9 trailing freeze (plan §2.1 / §4.5 — census #5 / #6): the hover hit test builds BOTH
@@ -47,8 +48,9 @@
47
48
  *
48
49
  * v0.10 読み取り専用壁 (G7 — 設計 ADR-28 rule 5): `confirmFill` は限度ゲート後・`expandFill` 前に
49
50
  * box ∖ source の ≤2 非交矩形分解 (`fillExtensionRects` — 斜めの L 字 2 レッグ込み) を walk し、
50
- * hit は必須 `rejectReadOnly` 漏斗経由で fill 全体を拒否する (cellCount = box 面積 − source 面積 —
51
- * 限度ゲートの見積りとは意図的に別の数)。後始末は限度拒否と同一 (選択不伸長・bumpEdit なし)。
51
+ * hit は必須 `rejectReadOnly` 漏斗経由で fill 全体を拒否する (`gesture: "fillHandle"`、`sources` = 複製元の
52
+ * 塊、`targets` = walk した矩形、cellCount = その面積 = box 面積 − source 面積 — 限度ゲートの見積りとは
53
+ * 意図的に別の数)。後始末は限度拒否と同一 (選択不伸長・bumpEdit なし)。
52
54
  * 読み取り専用ソースからの fill は合法のまま。能力未宣言は挙動バイト恒等。
53
55
  *
54
56
  * v0.9 末尾凍結 (計画 §2.1 / §4.5 — census #5 / #6): hover ヒットテストは 1 ハンドル快照から
@@ -63,7 +65,7 @@ import type { VirtualGridHandle } from "@aiquants/virtualscroll"
63
65
  import { type RefObject, useCallback, useEffect, useMemo, useRef } from "react"
64
66
  import { estimateFillCellCount, expandFill, fillExtensionRects, fillSourceEdit, readFillSource } from "../clipboard/tiling.ts"
65
67
  import type { AxisModel } from "../model/axisModel.ts"
66
- import { type CellCoord, type CellRange, clampCoord, makeRange, type SpreadsheetOperation } from "../model/cellCoord.ts"
68
+ import { type CellCoord, type CellRange, clampCoord, countRangeCells, makeRange, type SpreadsheetOperation } from "../model/cellCoord.ts"
67
69
  import { type CellEdit, type EditRejection, type ReadOnlyRejection, rangesContainReadOnly, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
68
70
  import { type AxisForwardCtx, colToViewportX, rowToViewportY, viewportXToCol, viewportYToRow } from "../model/frozenPartition.ts"
69
71
  import type { SelectionState } from "../selection/selectionState.ts"
@@ -289,13 +291,12 @@ export const useFillHandle = (params: UseFillHandleParams): SelectionEngine => {
289
291
  // G7 (v0.10 §6.8 / 設計 ADR-28 rule 5): 読み取り専用壁 — walk は拡張域 (box ∖ source) の
290
292
  // ≤2 非交矩形分解 fillExtensionRects (斜めドラッグの L 字 2 レッグ対応)。ソース行 / 列は
291
293
  // 書込対象ではないため walk 外 = 読み取り専用ソースからの fill は合法 (Excel 同等)。座席は
292
- // 限度ゲート後・expandFill (実体化) 前。cellCount = box 面積 − source 面積 (正確 — 限度
293
- // チャネルの見積り estimateFillCellCount とは別の数、登記済み非対称)。後始末は限度拒否と
294
- // 同一 (cleanupDrag 済み — 選択不伸長・bumpEdit なし)
295
- if (rangesContainReadOnly(p.adapter, fillExtensionRects(source, box))) {
296
- const boxArea = (box.endRow - box.startRow + 1) * (box.endCol - box.startCol + 1)
297
- const sourceArea = (source.endRow - source.startRow + 1) * (source.endCol - source.startCol + 1)
298
- p.rejectReadOnly({ kind: "operation", op: "fill", cellCount: boxArea - sourceArea })
294
+ // 限度ゲート後・expandFill (実体化) 前。拒否は walk した矩形をそのまま写し先として運び、cellCount =
295
+ // その面積の和 = box 面積 − source 面積 (正確 — 限度チャネルの見積り estimateFillCellCount とは別の数、
296
+ // 登記済み非対称)。後始末は限度拒否と同一 (cleanupDrag 済み — 選択不伸長・bumpEdit なし)
297
+ const extension = fillExtensionRects(source, box)
298
+ if (rangesContainReadOnly(p.adapter, extension)) {
299
+ p.rejectReadOnly({ kind: "operation", op: "fill", cellCount: countRangeCells(extension), gesture: "fillHandle", sources: [source], targets: extension })
299
300
  return
300
301
  }
301
302
  // 展開は fillDown / fillRight と同じソース毎規則 (分冊 08 §4 の fill 行): 種 (数式ソースか正準