@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.
package/dist/index.d.cts CHANGED
@@ -1061,13 +1061,20 @@ export declare const rangeSize: (range: CellRange) => {
1061
1061
  * refused gesture — the adapter was never called, so this is neither an {@link EditRejection}
1062
1062
  * (applyEdits never threw) nor an operation limit. `kind: "edit"` is a refused single-cell
1063
1063
  * text-write entry or commit and carries the cell; `kind: "operation"` is a refused whole
1064
- * operation with its producer's own overlap-naive `cellCount` arithmetic (the same numbers the
1065
- * limit channel reports — never a dedup count).
1064
+ * operation with its producer's own overlap-naive `cellCount` arithmetic (the limit channel's
1065
+ * vocabulary — overlapping ranges count once per range, never a dedup count). A refused fill
1066
+ * (`op: "fill"`, v0.19) also names its `gesture` and carries its geometry, so a host can tell
1067
+ * which cells refused it without re-deriving the fill rules: `targets` are the cells the fill
1068
+ * would write (the read-only walk's domain — a read-only source never refuses) and `cellCount` is
1069
+ * their total area; `sources` are the cells whose content it copies.
1066
1070
  * 読み取り専用拒否の文脈 (v0.10 — onReadOnlyRejected が届ける): 拒否されたジェスチャ毎に 1 回
1067
1071
  * 発火。adapter は呼ばれていないため {@link EditRejection} (applyEdits の throw) でも操作上限
1068
1072
  * でもない。`kind: "edit"` はセル単位テキスト書込の入口 / 確定の拒否でセル座標を運び、
1069
1073
  * `kind: "operation"` は操作全体の拒否で、`cellCount` はプロデューサ自身の overlap-naive 算術
1070
- * (上限チャネルと同じ数 — dedup 数ではない)。
1074
+ * (上限チャネルと同じ語彙 — 重なるレンジはレンジ毎に数え、dedup 数ではない)。fill の拒否
1075
+ * (`op: "fill"`、v0.19) はさらに `gesture` を名指し幾何を運ぶ — host は fill の規則を写さずに
1076
+ * どのセルが拒んだかを知れる: `targets` は fill が書くセル (読み取り専用 walk の対象 — 読み取り専用の
1077
+ * 複製元は拒まない) で `cellCount` はその面積の和、`sources` は内容を複製されるセル。
1071
1078
  */
1072
1079
  export declare type ReadOnlyRejection = {
1073
1080
  readonly kind: "edit";
@@ -1082,8 +1089,47 @@ export declare type ReadOnlyRejection = {
1082
1089
  readonly editSession: "none" | "kept" | "discarded";
1083
1090
  } | {
1084
1091
  readonly kind: "operation";
1085
- readonly op: "cut" | "delete" | "paste" | "fill" | "format" | "calc" | "annotate";
1092
+ readonly op: "cut" | "delete" | "paste" | "format" | "calc" | "annotate";
1086
1093
  readonly cellCount: number;
1094
+ } | {
1095
+ readonly kind: "operation";
1096
+ readonly op: "fill";
1097
+ /** Total area of `targets`. / `targets` の面積の和。 */
1098
+ readonly cellCount: number;
1099
+ /**
1100
+ * The refused gesture: the command (`fillDown` Ctrl+D, `fillRight` Ctrl+R, `fillSelection`
1101
+ * Ctrl+Enter — idle, or with an open session) or `fillHandle`, the fill handle's drag.
1102
+ * 拒否されたジェスチャ: コマンド (`fillDown` Ctrl+D・`fillRight` Ctrl+R・`fillSelection`
1103
+ * Ctrl+Enter — 待機中、またはセッション中) か `fillHandle` (フィルハンドルのドラッグ)。
1104
+ */
1105
+ readonly gesture: "fillDown" | "fillRight" | "fillSelection" | "fillHandle";
1106
+ /**
1107
+ * The cells whose content the fill copies: fillDown — each range's first row, or the row
1108
+ * above a one-row range; fillRight — each range's first column, or the column left of a
1109
+ * one-column range; an idle fillSelection — the active cell; fillHandle — the dragged
1110
+ * source block. A fillSelection with an open session writes the session's text and copies
1111
+ * no cell: `[]`.
1112
+ * 内容を複製されるセル: fillDown — 各レンジの先頭行 (1 行のレンジは上の行)、fillRight — 各
1113
+ * レンジの先頭列 (1 列のレンジは左の列)、待機中の fillSelection — active セル、fillHandle —
1114
+ * ドラッグした複製元の塊。セッション中の fillSelection はセッションの文字列を書きセルを複製
1115
+ * しないので `[]`。
1116
+ */
1117
+ readonly sources: readonly CellRange[];
1118
+ /**
1119
+ * The cells the fill writes, in grid coordinates: fillDown / fillRight — each range without
1120
+ * its source row / column (a one-row / one-column range whole; such a range on the first
1121
+ * row / column has no neighbour and is skipped); an idle fillSelection — each range without
1122
+ * the active cell (up to four rects per range); with an open session — every selected
1123
+ * range, the active cell included; fillHandle — the drag's extension outside the source (one
1124
+ * rect, or two disjoint ones forming an L on a diagonal drag). Rects overlap only where the
1125
+ * selection's ranges do.
1126
+ * fill が書くセル (グリッド座標): fillDown / fillRight — 各レンジから複製元の行 / 列を除いた
1127
+ * もの (1 行 / 1 列のレンジは全体。先頭の行 / 列のそうしたレンジは隣が無いので飛ばす)、待機中の
1128
+ * fillSelection — 各レンジから active セルを除いたもの (レンジ毎に高々 4 矩形)、セッション中 —
1129
+ * active セルを含む全選択レンジ、fillHandle — ドラッグの複製元の外の拡張域 (1 矩形、斜めの
1130
+ * ドラッグは L 字の非交な 2 矩形)。矩形が重なるのは選択のレンジが重なるところだけ。
1131
+ */
1132
+ readonly targets: readonly CellRange[];
1087
1133
  };
1088
1134
 
1089
1135
  /**
@@ -1302,8 +1348,10 @@ export declare const SPREADSHEET_RESERVED_SHORTCUTS: readonly string[];
1302
1348
  * Latin letter, otherwise by the `event.code` letter; digits / punctuation / function keys always
1303
1349
  * by code), strict chord matching with the AltGraph refusal (a row containing Alt is never
1304
1350
  * claimed by a real AltGr press), the column-aware consumer validation (merge = REPLACE per
1305
- * command; every invalid input is a RangeError — fail-fast on the API surface) and the O(1)
1306
- * runtime resolution of one keydown to a command.
1351
+ * command; every invalid input is a RangeError — fail-fast on the API surface), the O(1)
1352
+ * runtime resolution of one keydown to a command and its chord, and the rule that tells which
1353
+ * chords of a command with no editing-column row the editing column consumes (a chord that types
1354
+ * nothing in a text field — never one with Alt or a text-editing key).
1307
1355
  *
1308
1356
  * 再バインド可能コマンド表 (v0.8 ADR-17 — 計画 §1.5 / §2.6 / §4.1.11)。純関数・React 非依存:
1309
1357
  * SpreadsheetCommand の語彙、正準チョード文法 (`Ctrl+Alt+Shift+KEY` — 使う修飾だけ・順序固定・
@@ -1313,7 +1361,9 @@ export declare const SPREADSHEET_RESERVED_SHORTCUTS: readonly string[];
1313
1361
  * トークンへ写す VK 規則 (文字は `event.key` が単一ラテン文字ならそれ、そうでなければ
1314
1362
  * `event.code` の文字。数字 / 記号 / 機能キーは常に code)、AltGraph 拒否つきの厳密チョード照合
1315
1363
  * (Alt を含む行は実 AltGr 押下で決して成立しない)、列を意識した consumer 検証 (merge = コマンド毎
1316
- * REPLACE。無効入力は全て RangeError — API 面での fail-fast)、keydown 1 件の O(1) コマンド解決。
1364
+ * REPLACE。無効入力は全て RangeError — API 面での fail-fast)、keydown 1 件の O(1) コマンドと
1365
+ * チョードの解決、編集列に行の無いコマンドのチョードのうち編集列が消費するものを決める規則
1366
+ * (入力欄に何も打たないチョード — Alt や文字の編集キーを含むものは決して消費しない)。
1317
1367
  */
1318
1368
  /**
1319
1369
  * Every rebindable command of the grid (camelCase — the exact plan §1.5 list). The first block
@@ -2209,6 +2259,27 @@ export declare type SpreadsheetProps = {
2209
2259
  * 二重束縛は render 中 RangeError)。ref 経由で参照。
2210
2260
  */
2211
2261
  shortcuts?: ShortcutOverrides;
2262
+ /**
2263
+ * Notice that a command chord was pressed while a cell is being edited and was consumed without running (v0.19):
2264
+ * the command has no editing-column row (only the 16 editing-column commands run in an edit session — `fillDown`'s
2265
+ * Ctrl+D, `fillRight`'s Ctrl+R, `insertLink`'s Ctrl+K do not) and the chord types nothing in a text field (no Alt;
2266
+ * a function key, or Ctrl / Cmd with a letter, digit, punctuation or numpad key), so the grid stops the browser's own
2267
+ * shortcut (bookmark, reload, search box) and leaves the session and its typed value untouched. `chord` is the
2268
+ * canonical chord (Cmd reads as `Ctrl`). Chords with Alt or a text-editing key keep their text meaning and never come
2269
+ * here; an unavailable or unbound command's chord is not consumed. To commit and run the command instead, call
2270
+ * `executeCommand(command)` on the handle from this callback. Omit for silence (the chord is still consumed).
2271
+ * セルの編集中に押されたコマンドのチョードを、実行せずに消費したことの通知 (v0.19)。そのコマンドは編集列に行が無く
2272
+ * (編集セッションで走るのは編集列の 16 コマンドだけ — `fillDown` の Ctrl+D・`fillRight` の Ctrl+R・`insertLink` の Ctrl+K は
2273
+ * 走らない)、チョードが入力欄に何も打たない (Alt なしで、機能キーか Ctrl / Cmd + 英字・数字・記号・テンキー) ため、グリッドは
2274
+ * ブラウザの既定 (ブックマーク・再読込・検索欄) を止め、セッションと入力値には触らない。`chord` は正準チョード (Cmd は
2275
+ * `Ctrl` と読む)。Alt や文字の編集キーを含むチョードは文字の上の意味を保ちここへは来ず、利用できないか未束縛のコマンドの
2276
+ * チョードは消費しない。確定してから実行したいときは、このコールバックから handle の `executeCommand(command)` を呼ぶ。
2277
+ * 省略で通知なし (チョードは消費する)。
2278
+ */
2279
+ onCommandBlockedWhileEditing?: (blocked: {
2280
+ readonly command: SpreadsheetCommand;
2281
+ readonly chord: string;
2282
+ }) => void;
2212
2283
  /**
2213
2284
  * Custom colour slots for `fillColorCustom1..5` / `fontColorCustom1..5`: each axis is exactly
2214
2285
  * 5 `#rrggbb` strings (a different length or a non-hex entry throws a RangeError at prop
package/dist/index.d.ts CHANGED
@@ -1061,13 +1061,20 @@ export declare const rangeSize: (range: CellRange) => {
1061
1061
  * refused gesture — the adapter was never called, so this is neither an {@link EditRejection}
1062
1062
  * (applyEdits never threw) nor an operation limit. `kind: "edit"` is a refused single-cell
1063
1063
  * text-write entry or commit and carries the cell; `kind: "operation"` is a refused whole
1064
- * operation with its producer's own overlap-naive `cellCount` arithmetic (the same numbers the
1065
- * limit channel reports — never a dedup count).
1064
+ * operation with its producer's own overlap-naive `cellCount` arithmetic (the limit channel's
1065
+ * vocabulary — overlapping ranges count once per range, never a dedup count). A refused fill
1066
+ * (`op: "fill"`, v0.19) also names its `gesture` and carries its geometry, so a host can tell
1067
+ * which cells refused it without re-deriving the fill rules: `targets` are the cells the fill
1068
+ * would write (the read-only walk's domain — a read-only source never refuses) and `cellCount` is
1069
+ * their total area; `sources` are the cells whose content it copies.
1066
1070
  * 読み取り専用拒否の文脈 (v0.10 — onReadOnlyRejected が届ける): 拒否されたジェスチャ毎に 1 回
1067
1071
  * 発火。adapter は呼ばれていないため {@link EditRejection} (applyEdits の throw) でも操作上限
1068
1072
  * でもない。`kind: "edit"` はセル単位テキスト書込の入口 / 確定の拒否でセル座標を運び、
1069
1073
  * `kind: "operation"` は操作全体の拒否で、`cellCount` はプロデューサ自身の overlap-naive 算術
1070
- * (上限チャネルと同じ数 — dedup 数ではない)。
1074
+ * (上限チャネルと同じ語彙 — 重なるレンジはレンジ毎に数え、dedup 数ではない)。fill の拒否
1075
+ * (`op: "fill"`、v0.19) はさらに `gesture` を名指し幾何を運ぶ — host は fill の規則を写さずに
1076
+ * どのセルが拒んだかを知れる: `targets` は fill が書くセル (読み取り専用 walk の対象 — 読み取り専用の
1077
+ * 複製元は拒まない) で `cellCount` はその面積の和、`sources` は内容を複製されるセル。
1071
1078
  */
1072
1079
  export declare type ReadOnlyRejection = {
1073
1080
  readonly kind: "edit";
@@ -1082,8 +1089,47 @@ export declare type ReadOnlyRejection = {
1082
1089
  readonly editSession: "none" | "kept" | "discarded";
1083
1090
  } | {
1084
1091
  readonly kind: "operation";
1085
- readonly op: "cut" | "delete" | "paste" | "fill" | "format" | "calc" | "annotate";
1092
+ readonly op: "cut" | "delete" | "paste" | "format" | "calc" | "annotate";
1086
1093
  readonly cellCount: number;
1094
+ } | {
1095
+ readonly kind: "operation";
1096
+ readonly op: "fill";
1097
+ /** Total area of `targets`. / `targets` の面積の和。 */
1098
+ readonly cellCount: number;
1099
+ /**
1100
+ * The refused gesture: the command (`fillDown` Ctrl+D, `fillRight` Ctrl+R, `fillSelection`
1101
+ * Ctrl+Enter — idle, or with an open session) or `fillHandle`, the fill handle's drag.
1102
+ * 拒否されたジェスチャ: コマンド (`fillDown` Ctrl+D・`fillRight` Ctrl+R・`fillSelection`
1103
+ * Ctrl+Enter — 待機中、またはセッション中) か `fillHandle` (フィルハンドルのドラッグ)。
1104
+ */
1105
+ readonly gesture: "fillDown" | "fillRight" | "fillSelection" | "fillHandle";
1106
+ /**
1107
+ * The cells whose content the fill copies: fillDown — each range's first row, or the row
1108
+ * above a one-row range; fillRight — each range's first column, or the column left of a
1109
+ * one-column range; an idle fillSelection — the active cell; fillHandle — the dragged
1110
+ * source block. A fillSelection with an open session writes the session's text and copies
1111
+ * no cell: `[]`.
1112
+ * 内容を複製されるセル: fillDown — 各レンジの先頭行 (1 行のレンジは上の行)、fillRight — 各
1113
+ * レンジの先頭列 (1 列のレンジは左の列)、待機中の fillSelection — active セル、fillHandle —
1114
+ * ドラッグした複製元の塊。セッション中の fillSelection はセッションの文字列を書きセルを複製
1115
+ * しないので `[]`。
1116
+ */
1117
+ readonly sources: readonly CellRange[];
1118
+ /**
1119
+ * The cells the fill writes, in grid coordinates: fillDown / fillRight — each range without
1120
+ * its source row / column (a one-row / one-column range whole; such a range on the first
1121
+ * row / column has no neighbour and is skipped); an idle fillSelection — each range without
1122
+ * the active cell (up to four rects per range); with an open session — every selected
1123
+ * range, the active cell included; fillHandle — the drag's extension outside the source (one
1124
+ * rect, or two disjoint ones forming an L on a diagonal drag). Rects overlap only where the
1125
+ * selection's ranges do.
1126
+ * fill が書くセル (グリッド座標): fillDown / fillRight — 各レンジから複製元の行 / 列を除いた
1127
+ * もの (1 行 / 1 列のレンジは全体。先頭の行 / 列のそうしたレンジは隣が無いので飛ばす)、待機中の
1128
+ * fillSelection — 各レンジから active セルを除いたもの (レンジ毎に高々 4 矩形)、セッション中 —
1129
+ * active セルを含む全選択レンジ、fillHandle — ドラッグの複製元の外の拡張域 (1 矩形、斜めの
1130
+ * ドラッグは L 字の非交な 2 矩形)。矩形が重なるのは選択のレンジが重なるところだけ。
1131
+ */
1132
+ readonly targets: readonly CellRange[];
1087
1133
  };
1088
1134
 
1089
1135
  /**
@@ -1302,8 +1348,10 @@ export declare const SPREADSHEET_RESERVED_SHORTCUTS: readonly string[];
1302
1348
  * Latin letter, otherwise by the `event.code` letter; digits / punctuation / function keys always
1303
1349
  * by code), strict chord matching with the AltGraph refusal (a row containing Alt is never
1304
1350
  * claimed by a real AltGr press), the column-aware consumer validation (merge = REPLACE per
1305
- * command; every invalid input is a RangeError — fail-fast on the API surface) and the O(1)
1306
- * runtime resolution of one keydown to a command.
1351
+ * command; every invalid input is a RangeError — fail-fast on the API surface), the O(1)
1352
+ * runtime resolution of one keydown to a command and its chord, and the rule that tells which
1353
+ * chords of a command with no editing-column row the editing column consumes (a chord that types
1354
+ * nothing in a text field — never one with Alt or a text-editing key).
1307
1355
  *
1308
1356
  * 再バインド可能コマンド表 (v0.8 ADR-17 — 計画 §1.5 / §2.6 / §4.1.11)。純関数・React 非依存:
1309
1357
  * SpreadsheetCommand の語彙、正準チョード文法 (`Ctrl+Alt+Shift+KEY` — 使う修飾だけ・順序固定・
@@ -1313,7 +1361,9 @@ export declare const SPREADSHEET_RESERVED_SHORTCUTS: readonly string[];
1313
1361
  * トークンへ写す VK 規則 (文字は `event.key` が単一ラテン文字ならそれ、そうでなければ
1314
1362
  * `event.code` の文字。数字 / 記号 / 機能キーは常に code)、AltGraph 拒否つきの厳密チョード照合
1315
1363
  * (Alt を含む行は実 AltGr 押下で決して成立しない)、列を意識した consumer 検証 (merge = コマンド毎
1316
- * REPLACE。無効入力は全て RangeError — API 面での fail-fast)、keydown 1 件の O(1) コマンド解決。
1364
+ * REPLACE。無効入力は全て RangeError — API 面での fail-fast)、keydown 1 件の O(1) コマンドと
1365
+ * チョードの解決、編集列に行の無いコマンドのチョードのうち編集列が消費するものを決める規則
1366
+ * (入力欄に何も打たないチョード — Alt や文字の編集キーを含むものは決して消費しない)。
1317
1367
  */
1318
1368
  /**
1319
1369
  * Every rebindable command of the grid (camelCase — the exact plan §1.5 list). The first block
@@ -2209,6 +2259,27 @@ export declare type SpreadsheetProps = {
2209
2259
  * 二重束縛は render 中 RangeError)。ref 経由で参照。
2210
2260
  */
2211
2261
  shortcuts?: ShortcutOverrides;
2262
+ /**
2263
+ * Notice that a command chord was pressed while a cell is being edited and was consumed without running (v0.19):
2264
+ * the command has no editing-column row (only the 16 editing-column commands run in an edit session — `fillDown`'s
2265
+ * Ctrl+D, `fillRight`'s Ctrl+R, `insertLink`'s Ctrl+K do not) and the chord types nothing in a text field (no Alt;
2266
+ * a function key, or Ctrl / Cmd with a letter, digit, punctuation or numpad key), so the grid stops the browser's own
2267
+ * shortcut (bookmark, reload, search box) and leaves the session and its typed value untouched. `chord` is the
2268
+ * canonical chord (Cmd reads as `Ctrl`). Chords with Alt or a text-editing key keep their text meaning and never come
2269
+ * here; an unavailable or unbound command's chord is not consumed. To commit and run the command instead, call
2270
+ * `executeCommand(command)` on the handle from this callback. Omit for silence (the chord is still consumed).
2271
+ * セルの編集中に押されたコマンドのチョードを、実行せずに消費したことの通知 (v0.19)。そのコマンドは編集列に行が無く
2272
+ * (編集セッションで走るのは編集列の 16 コマンドだけ — `fillDown` の Ctrl+D・`fillRight` の Ctrl+R・`insertLink` の Ctrl+K は
2273
+ * 走らない)、チョードが入力欄に何も打たない (Alt なしで、機能キーか Ctrl / Cmd + 英字・数字・記号・テンキー) ため、グリッドは
2274
+ * ブラウザの既定 (ブックマーク・再読込・検索欄) を止め、セッションと入力値には触らない。`chord` は正準チョード (Cmd は
2275
+ * `Ctrl` と読む)。Alt や文字の編集キーを含むチョードは文字の上の意味を保ちここへは来ず、利用できないか未束縛のコマンドの
2276
+ * チョードは消費しない。確定してから実行したいときは、このコールバックから handle の `executeCommand(command)` を呼ぶ。
2277
+ * 省略で通知なし (チョードは消費する)。
2278
+ */
2279
+ onCommandBlockedWhileEditing?: (blocked: {
2280
+ readonly command: SpreadsheetCommand;
2281
+ readonly chord: string;
2282
+ }) => void;
2212
2283
  /**
2213
2284
  * Custom colour slots for `fillColorCustom1..5` / `fontColorCustom1..5`: each axis is exactly
2214
2285
  * 5 `#rrggbb` strings (a different length or a non-hex entry throws a RangeError at prop