@aiquants/spreadsheet 0.20.1 → 0.20.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -423,6 +423,17 @@ export declare type CommentPopoverProps = {
423
423
  labels: SpreadsheetLabels;
424
424
  };
425
425
 
426
+ /**
427
+ * What the handle's `commitEdit` did: `"committed"` — the open session closed (its text written through `applyEdits`, or
428
+ * closed without a write when the text was unchanged); `"rejected"` — the commit was refused and the session stays open
429
+ * with the typed text (the refusal went through `onEditRejected`, `onValidationRejected` or `onReadOnlyRejected`, as an
430
+ * Enter's would); `"idle"` — no session was open and nothing happened.
431
+ * handle の `commitEdit` の結果: `"committed"` — 開いていたセッションが閉じた (字を `applyEdits` で書いた、または字が変わらず書かずに
432
+ * 閉じた)。`"rejected"` — 確定が断られ、打った字のままセッションが続く (断りは Enter と同じく `onEditRejected`・`onValidationRejected`・
433
+ * `onReadOnlyRejected` で知らせた)。`"idle"` — セッションが無く、何もしなかった。
434
+ */
435
+ export declare type CommitEditOutcome = "committed" | "rejected" | "idle";
436
+
426
437
  /** Ordered comparison vocabulary of `cellValue` (the same eight words as the validation engine); between / notBetween include both bounds. / cellValue の比較語彙 (検証エンジンと同じ 8 語)。between / notBetween は両端含み。 */
427
438
  export declare type CompareOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "between" | "notBetween";
428
439
 
@@ -555,6 +566,20 @@ export declare type EditRejection = {
555
566
  source: "paste" | "fill" | "delete" | "format" | "calc" | "annotate";
556
567
  };
557
568
 
569
+ /**
570
+ * The open in-place edit session (§6.7.1): the cell it writes to, captured when it opened, and how it opened — `"edit"`
571
+ * (F2, a double-click, `startEdit("edit")`: the cell's text with the caret in it) or `"replace"` (a printable key, an IME
572
+ * composition, `startEdit("replace")`: an empty editor). Reported by `onEditSessionChange` and read by the handle's
573
+ * `getEditSession`; the grid replaces the object, never mutates it.
574
+ * 開いているその場の入力のセッション (§6.7.1): 開いた時に捉えた書き込み先のマスと、開き方 — `"edit"` (F2・ダブルクリック・
575
+ * `startEdit("edit")`。マスの字にキャレット) か `"replace"` (印字キー・IME の変換・`startEdit("replace")`。空の入力欄)。
576
+ * `onEditSessionChange` が知らせ、handle の `getEditSession` が読む。グリッドは物を差し替え、書き換えない。
577
+ */
578
+ export declare type EditSession = {
579
+ readonly cell: CellCoord;
580
+ readonly mode: "edit" | "replace";
581
+ };
582
+
558
583
  /**
559
584
  * Every write path of the grid (the union of the two EditContext arms' `source`; equal to
560
585
  * `EditRejection["source"]`, sealed in dataAdapter.spec.ts): the editor commit ("edit" — also
@@ -1221,6 +1246,19 @@ export declare type ScrollToCellOptions = {
1221
1246
  offsetY?: number;
1222
1247
  };
1223
1248
 
1249
+ /**
1250
+ * Why a confirmed selection changed — the second argument of `onSelectionChange`. `"user"`: a gesture, a chord, a command
1251
+ * or a paste moved it, including a command or paste the host runs through the handle (`executeCommand`, `paste`) for the
1252
+ * user; `"setSelection"`: the host placed it through the handle's `setSelection`; `"sheetSwitch"`: the adapter identity
1253
+ * changed to a non-empty adapter and the selection reset to A1; `"countShrink"`: the same adapter's `rowCount` /
1254
+ * `colCount` shrank and the selection was pulled onto the grid.
1255
+ * 確定選択が変わった理由 — `onSelectionChange` の 2 つ目の引数。`"user"`: ジェスチャ・チョード・コマンド・貼り付けが動かした (利用側が
1256
+ * 利用者の代わりに handle で走らせるコマンドと貼り付け — `executeCommand`・`paste` — も含む)。`"setSelection"`: 利用側が handle の
1257
+ * `setSelection` で置いた。`"sheetSwitch"`: アダプタの同一性が空でないアダプタへ替わり、選択が A1 へ戻った。`"countShrink"`: 同じ
1258
+ * アダプタの `rowCount` / `colCount` が縮み、選択をグリッドの中へ畳んだ。
1259
+ */
1260
+ export declare type SelectionChangeReason = "user" | "setSelection" | "sheetSwitch" | "countShrink";
1261
+
1224
1262
  /** Selection state (tail of ranges = the "current range"). / 選択状態 (末尾が現在レンジ)。 */
1225
1263
  export declare type SelectionState = {
1226
1264
  /** Non-contiguous range list; the tail is the "current range". / 非連続選択のレンジ列 (末尾が現在レンジ)。 */
@@ -1282,6 +1320,17 @@ export declare const serializeHtmlTable: (payload: ClipPayload, clipJson: string
1282
1320
  */
1283
1321
  export declare const serializeTsv: (matrix: readonly (readonly string[])[]) => string;
1284
1322
 
1323
+ /**
1324
+ * Options of the handle's `setSelection`. `scroll: true` brings the placed active cell into view with the keyboard's
1325
+ * minimal scroll (the grid's own viewport, then the page); absent or `false` leaves every scroll position alone — pair it
1326
+ * with `scrollToCell` for an alignment of your own.
1327
+ * handle の `setSelection` の選択肢。`scroll: true` は、置いたアクティブなマスをキーの移動と同じ最小の送りで見せる (グリッド自身の
1328
+ * 表示域、続けてページ)。無しか `false` はどのスクロール位置も変えない — 揃えを選ぶなら `scrollToCell` と組み合わせる。
1329
+ */
1330
+ export declare type SetSelectionOptions = {
1331
+ scroll?: boolean;
1332
+ };
1333
+
1285
1334
  /**
1286
1335
  * Shifts the relative parts of every reference by (dRow, dCol) — the paste-offset transform.
1287
1336
  * Absolute (`$`) parts stay; a reference shifted below row / column 0 becomes `#REF!` (behind
@@ -1706,6 +1755,46 @@ export declare type SpreadsheetHandle = {
1706
1755
  paste: (options: PasteOptions) => Promise<PasteOutcome>;
1707
1756
  /** The confirmed selection (imperative read). / 確定選択の命令読み。 */
1708
1757
  getSelection: () => SelectionState;
1758
+ /**
1759
+ * Places the selection — its ranges, anchor and active cell — where the host decides (a row the page chose from its
1760
+ * URL, the same month after the host moved the window a year). It goes through the same write path as a gesture:
1761
+ * `onSelectionChange` fires once with reason `"setSelection"` (never for a selection equal to the current one), the
1762
+ * announcement formatters run, the active cell's input message shows, and the next Arrow key moves from the placed
1763
+ * active cell. The grid keeps a copy, so the host may reuse its object. A hidden row or column is a valid place.
1764
+ * Focus does not move (call `focus()` for that), and an open popover keeps its cell.
1765
+ * 選択 (レンジ・anchor・アクティブなマス) を利用側が決めた所へ置く (ページが URL から選んだ行・利用側が窓を 1 年送った後の同じ月)。
1766
+ * ジェスチャと同じ書き込みの道を通る: `onSelectionChange` が理由 `"setSelection"` で 1 回発火 (今と等しい選択では発火しない)、読み上げの
1767
+ * 整形が走り、アクティブなマスの入力メッセージが出て、次の矢印キーは置いたアクティブなマスから動く。グリッドは写しを持つので、利用側は
1768
+ * 自分の物を使い回してよい。隠した行・列の上にも置ける。焦点は動かさず (要るなら `focus()`)、開いているポップオーバーは自分のマスを保つ。
1769
+ *
1770
+ * @param selection - The ranges (at least one, each start at most its end), the anchor (inside the last range) and the active cell (inside some range), all inside the grid. レンジ (1 つ以上、始まりは終わり以下)・anchor (末尾のレンジの中)・アクティブなマス (どれかのレンジの中)。どれもグリッドの中。
1771
+ * @param options - `scroll: true` brings the active cell into view as an Arrow key does; absent or `false` leaves the scroll alone. `scroll: true` は矢印キーと同じくアクティブなマスを見せる。無しか `false` は送らない。
1772
+ * @returns True when the selection is placed (or already was); false — nothing changed — while a cell is being edited (the session stays open) or a pointer drag is in flight. 置けた (または既にその選択だった) なら true。セルの入力中 (セッションは続く) とポインタのドラッグの途中は false で何も変えない。
1773
+ * @throws {RangeError} When the selection is not a valid selection of the grid (no range, a bound that is not a whole number inside the grid, a range whose start is after its end, the anchor outside the last range, the active cell outside every range — a grid without rows or columns throws for any selection), or `options.scroll` is neither `true`, `false` nor absent. 選択がグリッドの正しい選択でないとき (レンジが無い・境がグリッドの中の整数でない・始まりが終わりより後のレンジ・末尾のレンジの外の anchor・どのレンジの外のアクティブなマス — 行か列の無いグリッドではどの選択も投げる)、または `options.scroll` が `true`・`false`・無しのどれでもないとき。
1774
+ */
1775
+ setSelection: (selection: SelectionState, options?: SetSelectionOptions) => boolean;
1776
+ /**
1777
+ * The open in-place edit session — the cell it writes to and how it opened — or null when no cell is being edited
1778
+ * (the same object `onEditSessionChange` last reported).
1779
+ * 開いているその場の入力のセッション (書き込み先のマスと開き方)。入力中のセルが無ければ null (`onEditSessionChange` が最後に知らせた物と同じ)。
1780
+ *
1781
+ * @returns The session, or null. セッション、または null。
1782
+ */
1783
+ getEditSession: () => EditSession | null;
1784
+ /**
1785
+ * Commits the open session as Enter does, without moving the active cell — for a host that saves from outside the
1786
+ * grid's keys (a Ctrl+S listener) and must not lose the typed text. The text is validated and written through
1787
+ * `applyEdits` when it changed; an unchanged text just closes the session. A refused commit keeps the session open
1788
+ * with the typed text and reports the refusal through the same callback as an Enter. An IME composition in flight is
1789
+ * confirmed first, as a press elsewhere in the grid confirms it (the hidden input blurs and takes the focus back).
1790
+ * 開いているセッションを Enter と同じく確定する (アクティブなマスは動かさない) — グリッドのキーの外で保存する利用側 (Ctrl+S の聞き手)
1791
+ * が、打った字を失わないため。字が変わっていれば検めて `applyEdits` で書き、変わっていなければセッションを閉じるだけ。断られた確定は打った字の
1792
+ * ままセッションを続け、Enter と同じ口で断りを知らせる。IME の変換中なら、グリッドの中の押下と同じく先に変換を確定させる (隠れた入力欄を
1793
+ * blur して焦点を取り戻す)。
1794
+ *
1795
+ * @returns `"committed"` when the session closed, `"rejected"` when the commit was refused (the session stays), `"idle"` when no session was open. セッションが閉じたら `"committed"`、断られたら `"rejected"` (セッションは続く)、開いていなければ `"idle"`。
1796
+ */
1797
+ commitEdit: () => CommitEditOutcome;
1709
1798
  /** The adapter's BASE format of a cell (toolbar state) — the getCellFormat capability branch. / セルの base 書式 (getCellFormat の能力分岐)。 */
1710
1799
  getBaseFormat: (cell: CellCoord) => CellFormat | undefined;
1711
1800
  /** base ⊕ conditional formats of a cell (the paint the user sees). / base ⊕ 条件付き書式 (描画される書式)。 */
@@ -2005,31 +2094,48 @@ export declare type SpreadsheetProps = {
2005
2094
  renderCell?: (ctx: RenderCellContext) => ReactNode;
2006
2095
  /**
2007
2096
  * Fires on every confirmed SelectionState change (press replace, extend confirm, cycling,
2008
- * paste replace, Ctrl+A, ...), including one run by a handle call (the handle `paste` moves
2009
- * the selection to the written block and fires like the keyboard paste). Never during a drag
2010
- * (state frozen — one fire at pointerup), with ONE documented in-drag firing point: the header
2011
- * subtract reservation converts to a real press on the first movement, firing the deferred
2012
- * press replace mid-drag (total fire count matches v0.1 — conversion 1 + up 1). Never for the
2013
- * initial A1 mount. TWO adapter-driven fire points, each firing from a layout effect of the
2014
- * commit that brings the new adapter or counts (neither a gesture nor a handle call): a sheet
2015
- * switch (a new adapter identity) to a non-empty adapter resets the selection to A1 through
2016
- * the wrapper and fires once, unless the selection already was the lone cell A1; and a
2017
- * same-adapter rowCount / colCount shrink that moved the selection fires once (ADR-33). A
2018
- * switch or a shrink that leaves 0 rows or 0 columns (so no A1) writes the empty-grid state
2019
- * directly and never fires.
2097
+ * paste replace, Ctrl+A, ...), with the reason as the second argument
2098
+ * ({@link SelectionChangeReason}): `"user"` for gestures, chords, commands and pastes — one
2099
+ * run by a handle call too (the handle `paste` moves the selection to the written block and
2100
+ * fires like the keyboard paste) — and `"setSelection"` for the handle's `setSelection`. Never
2101
+ * during a drag (state frozen — one fire at pointerup), with ONE documented in-drag firing
2102
+ * point: the header subtract reservation converts to a real press on the first movement,
2103
+ * firing the deferred press replace mid-drag (total fire count matches v0.1 — conversion 1 +
2104
+ * up 1). Never for the initial A1 mount. TWO adapter-driven fire points, each firing from a
2105
+ * layout effect of the commit that brings the new adapter or counts (neither a gesture nor a
2106
+ * handle call): a sheet switch (a new adapter identity) to a non-empty adapter resets the
2107
+ * selection to A1 through the wrapper and fires once with `"sheetSwitch"`, unless the
2108
+ * selection already was the lone cell A1; and a same-adapter rowCount / colCount shrink that
2109
+ * moved the selection fires once with `"countShrink"` (ADR-33). A switch or a shrink that
2110
+ * leaves 0 rows or 0 columns (so no A1) writes the empty-grid state directly and never fires.
2020
2111
  * Independent of the live region's 200ms debounce (firing point: the §6.9-1 setSelection
2021
2112
  * wrapper).
2022
- * 確定 SelectionState が変わるたびに発火。handle の呼び出しが走らせた変化も含む (handle の
2023
- * `paste` は選択を書いた範囲へ動かし、キーボードの貼り付けと同じく発火)。ドラッグ中と初期マウント
2024
- * では発火しない。明文のドラッグ中発火点が 1 つ: ヘッダー減算予約の実 press 変換 (初動 move) は
2025
- * 遅延 press 置換をドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。adapter 起点の
2026
- * 発火点は 2 つで、どちらも新しい adapter や行数・列数を運んだ commit の layout effect から発火
2027
- * (ジェスチャでも handle の呼び出しでもない): 空でない adapter へのシート切替 (adapter の同一性の
2028
- * 変化) は、ラッパー経由の A1 へのリセットで 1 回発火 (選択が既に A1 の 1 マスだけなら発火なし)。
2029
- * 同一 adapter の rowCount / colCount 縮小で選択が動いたときも 1 回発火 (ADR-33)。0 行または
2030
- * 0 列 (A1 が無い) になる切替と縮小は、空グリッドの状態をラッパーを通さずに書き、発火なし。
2113
+ * 確定 SelectionState が変わるたびに発火し、2 つ目の引数で理由を渡す ({@link SelectionChangeReason}):
2114
+ * ジェスチャ・チョード・コマンド・貼り付けは `"user"` (handle の呼び出しが走らせた変化も — handle の
2115
+ * `paste` は選択を書いた範囲へ動かし、キーボードの貼り付けと同じく発火)、handle の `setSelection` は
2116
+ * `"setSelection"`。ドラッグ中と初期マウントでは発火しない。明文のドラッグ中発火点が 1 つ: ヘッダー減算
2117
+ * 予約の実 press 変換 (初動 move) は遅延 press 置換をドラッグ中に発火する (発火総数は v0.1 と同一 —
2118
+ * 変換 1 + up 1)。adapter 起点の発火点は 2 つで、どちらも新しい adapter や行数・列数を運んだ commit の
2119
+ * layout effect から発火 (ジェスチャでも handle の呼び出しでもない): 空でない adapter へのシート切替
2120
+ * (adapter の同一性の変化) は、ラッパー経由の A1 へのリセットで `"sheetSwitch"` を 1 回発火 (選択が
2121
+ * 既に A1 の 1 マスだけなら発火なし)。同一 adapter の rowCount / colCount 縮小で選択が動いたときは
2122
+ * `"countShrink"` を 1 回発火 (ADR-33)。0 行または 0 列 (A1 が無い) になる切替と縮小は、空グリッドの
2123
+ * 状態をラッパーを通さずに書き、発火なし。
2124
+ */
2125
+ onSelectionChange?: (selection: SelectionState, reason: SelectionChangeReason) => void;
2126
+ /**
2127
+ * Notice of the in-place edit session: the new {@link EditSession} right after a session opens (F2, a double-click,
2128
+ * a printable key, an IME composition, the handle's `startEdit`), `null` right after it closes — a commit (after
2129
+ * `applyEdits` returned, before the Enter / Tab that committed moves the active cell), a cancel, the focus leaving
2130
+ * the grid, an adapter switch, a count shrink that removed the cell, an editing Ctrl+Enter fill. A refused commit
2131
+ * keeps the session open and reports nothing here. Not called on unmount. Read when it fires (no remount). The
2132
+ * handle's `getEditSession` returns the same object.
2133
+ * その場の入力のセッションの知らせ: セッションが開いた直後 (F2・ダブルクリック・印字キー・IME の変換・handle の `startEdit`) に新しい
2134
+ * {@link EditSession}、閉じた直後に `null` — 確定 (`applyEdits` が戻った後、確定した Enter / Tab がアクティブなマスを動かす前)・取り消し・
2135
+ * 焦点のグリッドの外への離脱・アダプタの切り替え・マスを消した縮小・入力中の Ctrl+Enter の埋め。断られた確定はセッションを続け、ここでは
2136
+ * 何も知らせない。アンマウントでは呼ばない。発火の時に読む (再マウント不要)。handle の `getEditSession` は同じ物を返す。
2031
2137
  */
2032
- onSelectionChange?: (selection: SelectionState) => void;
2138
+ onEditSessionChange?: (session: EditSession | null) => void;
2033
2139
  /** Consumer context menu (§6.4.3-4 / §6.6.1 Shift+F10); keyboard origin carries the active cell viewport rect. / consumer コンテキストメニュー。 */
2034
2140
  onCellContextMenu?: (cell: CellCoord, origin: {
2035
2141
  kind: "pointer";
package/dist/index.d.ts CHANGED
@@ -423,6 +423,17 @@ export declare type CommentPopoverProps = {
423
423
  labels: SpreadsheetLabels;
424
424
  };
425
425
 
426
+ /**
427
+ * What the handle's `commitEdit` did: `"committed"` — the open session closed (its text written through `applyEdits`, or
428
+ * closed without a write when the text was unchanged); `"rejected"` — the commit was refused and the session stays open
429
+ * with the typed text (the refusal went through `onEditRejected`, `onValidationRejected` or `onReadOnlyRejected`, as an
430
+ * Enter's would); `"idle"` — no session was open and nothing happened.
431
+ * handle の `commitEdit` の結果: `"committed"` — 開いていたセッションが閉じた (字を `applyEdits` で書いた、または字が変わらず書かずに
432
+ * 閉じた)。`"rejected"` — 確定が断られ、打った字のままセッションが続く (断りは Enter と同じく `onEditRejected`・`onValidationRejected`・
433
+ * `onReadOnlyRejected` で知らせた)。`"idle"` — セッションが無く、何もしなかった。
434
+ */
435
+ export declare type CommitEditOutcome = "committed" | "rejected" | "idle";
436
+
426
437
  /** Ordered comparison vocabulary of `cellValue` (the same eight words as the validation engine); between / notBetween include both bounds. / cellValue の比較語彙 (検証エンジンと同じ 8 語)。between / notBetween は両端含み。 */
427
438
  export declare type CompareOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "between" | "notBetween";
428
439
 
@@ -555,6 +566,20 @@ export declare type EditRejection = {
555
566
  source: "paste" | "fill" | "delete" | "format" | "calc" | "annotate";
556
567
  };
557
568
 
569
+ /**
570
+ * The open in-place edit session (§6.7.1): the cell it writes to, captured when it opened, and how it opened — `"edit"`
571
+ * (F2, a double-click, `startEdit("edit")`: the cell's text with the caret in it) or `"replace"` (a printable key, an IME
572
+ * composition, `startEdit("replace")`: an empty editor). Reported by `onEditSessionChange` and read by the handle's
573
+ * `getEditSession`; the grid replaces the object, never mutates it.
574
+ * 開いているその場の入力のセッション (§6.7.1): 開いた時に捉えた書き込み先のマスと、開き方 — `"edit"` (F2・ダブルクリック・
575
+ * `startEdit("edit")`。マスの字にキャレット) か `"replace"` (印字キー・IME の変換・`startEdit("replace")`。空の入力欄)。
576
+ * `onEditSessionChange` が知らせ、handle の `getEditSession` が読む。グリッドは物を差し替え、書き換えない。
577
+ */
578
+ export declare type EditSession = {
579
+ readonly cell: CellCoord;
580
+ readonly mode: "edit" | "replace";
581
+ };
582
+
558
583
  /**
559
584
  * Every write path of the grid (the union of the two EditContext arms' `source`; equal to
560
585
  * `EditRejection["source"]`, sealed in dataAdapter.spec.ts): the editor commit ("edit" — also
@@ -1221,6 +1246,19 @@ export declare type ScrollToCellOptions = {
1221
1246
  offsetY?: number;
1222
1247
  };
1223
1248
 
1249
+ /**
1250
+ * Why a confirmed selection changed — the second argument of `onSelectionChange`. `"user"`: a gesture, a chord, a command
1251
+ * or a paste moved it, including a command or paste the host runs through the handle (`executeCommand`, `paste`) for the
1252
+ * user; `"setSelection"`: the host placed it through the handle's `setSelection`; `"sheetSwitch"`: the adapter identity
1253
+ * changed to a non-empty adapter and the selection reset to A1; `"countShrink"`: the same adapter's `rowCount` /
1254
+ * `colCount` shrank and the selection was pulled onto the grid.
1255
+ * 確定選択が変わった理由 — `onSelectionChange` の 2 つ目の引数。`"user"`: ジェスチャ・チョード・コマンド・貼り付けが動かした (利用側が
1256
+ * 利用者の代わりに handle で走らせるコマンドと貼り付け — `executeCommand`・`paste` — も含む)。`"setSelection"`: 利用側が handle の
1257
+ * `setSelection` で置いた。`"sheetSwitch"`: アダプタの同一性が空でないアダプタへ替わり、選択が A1 へ戻った。`"countShrink"`: 同じ
1258
+ * アダプタの `rowCount` / `colCount` が縮み、選択をグリッドの中へ畳んだ。
1259
+ */
1260
+ export declare type SelectionChangeReason = "user" | "setSelection" | "sheetSwitch" | "countShrink";
1261
+
1224
1262
  /** Selection state (tail of ranges = the "current range"). / 選択状態 (末尾が現在レンジ)。 */
1225
1263
  export declare type SelectionState = {
1226
1264
  /** Non-contiguous range list; the tail is the "current range". / 非連続選択のレンジ列 (末尾が現在レンジ)。 */
@@ -1282,6 +1320,17 @@ export declare const serializeHtmlTable: (payload: ClipPayload, clipJson: string
1282
1320
  */
1283
1321
  export declare const serializeTsv: (matrix: readonly (readonly string[])[]) => string;
1284
1322
 
1323
+ /**
1324
+ * Options of the handle's `setSelection`. `scroll: true` brings the placed active cell into view with the keyboard's
1325
+ * minimal scroll (the grid's own viewport, then the page); absent or `false` leaves every scroll position alone — pair it
1326
+ * with `scrollToCell` for an alignment of your own.
1327
+ * handle の `setSelection` の選択肢。`scroll: true` は、置いたアクティブなマスをキーの移動と同じ最小の送りで見せる (グリッド自身の
1328
+ * 表示域、続けてページ)。無しか `false` はどのスクロール位置も変えない — 揃えを選ぶなら `scrollToCell` と組み合わせる。
1329
+ */
1330
+ export declare type SetSelectionOptions = {
1331
+ scroll?: boolean;
1332
+ };
1333
+
1285
1334
  /**
1286
1335
  * Shifts the relative parts of every reference by (dRow, dCol) — the paste-offset transform.
1287
1336
  * Absolute (`$`) parts stay; a reference shifted below row / column 0 becomes `#REF!` (behind
@@ -1706,6 +1755,46 @@ export declare type SpreadsheetHandle = {
1706
1755
  paste: (options: PasteOptions) => Promise<PasteOutcome>;
1707
1756
  /** The confirmed selection (imperative read). / 確定選択の命令読み。 */
1708
1757
  getSelection: () => SelectionState;
1758
+ /**
1759
+ * Places the selection — its ranges, anchor and active cell — where the host decides (a row the page chose from its
1760
+ * URL, the same month after the host moved the window a year). It goes through the same write path as a gesture:
1761
+ * `onSelectionChange` fires once with reason `"setSelection"` (never for a selection equal to the current one), the
1762
+ * announcement formatters run, the active cell's input message shows, and the next Arrow key moves from the placed
1763
+ * active cell. The grid keeps a copy, so the host may reuse its object. A hidden row or column is a valid place.
1764
+ * Focus does not move (call `focus()` for that), and an open popover keeps its cell.
1765
+ * 選択 (レンジ・anchor・アクティブなマス) を利用側が決めた所へ置く (ページが URL から選んだ行・利用側が窓を 1 年送った後の同じ月)。
1766
+ * ジェスチャと同じ書き込みの道を通る: `onSelectionChange` が理由 `"setSelection"` で 1 回発火 (今と等しい選択では発火しない)、読み上げの
1767
+ * 整形が走り、アクティブなマスの入力メッセージが出て、次の矢印キーは置いたアクティブなマスから動く。グリッドは写しを持つので、利用側は
1768
+ * 自分の物を使い回してよい。隠した行・列の上にも置ける。焦点は動かさず (要るなら `focus()`)、開いているポップオーバーは自分のマスを保つ。
1769
+ *
1770
+ * @param selection - The ranges (at least one, each start at most its end), the anchor (inside the last range) and the active cell (inside some range), all inside the grid. レンジ (1 つ以上、始まりは終わり以下)・anchor (末尾のレンジの中)・アクティブなマス (どれかのレンジの中)。どれもグリッドの中。
1771
+ * @param options - `scroll: true` brings the active cell into view as an Arrow key does; absent or `false` leaves the scroll alone. `scroll: true` は矢印キーと同じくアクティブなマスを見せる。無しか `false` は送らない。
1772
+ * @returns True when the selection is placed (or already was); false — nothing changed — while a cell is being edited (the session stays open) or a pointer drag is in flight. 置けた (または既にその選択だった) なら true。セルの入力中 (セッションは続く) とポインタのドラッグの途中は false で何も変えない。
1773
+ * @throws {RangeError} When the selection is not a valid selection of the grid (no range, a bound that is not a whole number inside the grid, a range whose start is after its end, the anchor outside the last range, the active cell outside every range — a grid without rows or columns throws for any selection), or `options.scroll` is neither `true`, `false` nor absent. 選択がグリッドの正しい選択でないとき (レンジが無い・境がグリッドの中の整数でない・始まりが終わりより後のレンジ・末尾のレンジの外の anchor・どのレンジの外のアクティブなマス — 行か列の無いグリッドではどの選択も投げる)、または `options.scroll` が `true`・`false`・無しのどれでもないとき。
1774
+ */
1775
+ setSelection: (selection: SelectionState, options?: SetSelectionOptions) => boolean;
1776
+ /**
1777
+ * The open in-place edit session — the cell it writes to and how it opened — or null when no cell is being edited
1778
+ * (the same object `onEditSessionChange` last reported).
1779
+ * 開いているその場の入力のセッション (書き込み先のマスと開き方)。入力中のセルが無ければ null (`onEditSessionChange` が最後に知らせた物と同じ)。
1780
+ *
1781
+ * @returns The session, or null. セッション、または null。
1782
+ */
1783
+ getEditSession: () => EditSession | null;
1784
+ /**
1785
+ * Commits the open session as Enter does, without moving the active cell — for a host that saves from outside the
1786
+ * grid's keys (a Ctrl+S listener) and must not lose the typed text. The text is validated and written through
1787
+ * `applyEdits` when it changed; an unchanged text just closes the session. A refused commit keeps the session open
1788
+ * with the typed text and reports the refusal through the same callback as an Enter. An IME composition in flight is
1789
+ * confirmed first, as a press elsewhere in the grid confirms it (the hidden input blurs and takes the focus back).
1790
+ * 開いているセッションを Enter と同じく確定する (アクティブなマスは動かさない) — グリッドのキーの外で保存する利用側 (Ctrl+S の聞き手)
1791
+ * が、打った字を失わないため。字が変わっていれば検めて `applyEdits` で書き、変わっていなければセッションを閉じるだけ。断られた確定は打った字の
1792
+ * ままセッションを続け、Enter と同じ口で断りを知らせる。IME の変換中なら、グリッドの中の押下と同じく先に変換を確定させる (隠れた入力欄を
1793
+ * blur して焦点を取り戻す)。
1794
+ *
1795
+ * @returns `"committed"` when the session closed, `"rejected"` when the commit was refused (the session stays), `"idle"` when no session was open. セッションが閉じたら `"committed"`、断られたら `"rejected"` (セッションは続く)、開いていなければ `"idle"`。
1796
+ */
1797
+ commitEdit: () => CommitEditOutcome;
1709
1798
  /** The adapter's BASE format of a cell (toolbar state) — the getCellFormat capability branch. / セルの base 書式 (getCellFormat の能力分岐)。 */
1710
1799
  getBaseFormat: (cell: CellCoord) => CellFormat | undefined;
1711
1800
  /** base ⊕ conditional formats of a cell (the paint the user sees). / base ⊕ 条件付き書式 (描画される書式)。 */
@@ -2005,31 +2094,48 @@ export declare type SpreadsheetProps = {
2005
2094
  renderCell?: (ctx: RenderCellContext) => ReactNode;
2006
2095
  /**
2007
2096
  * Fires on every confirmed SelectionState change (press replace, extend confirm, cycling,
2008
- * paste replace, Ctrl+A, ...), including one run by a handle call (the handle `paste` moves
2009
- * the selection to the written block and fires like the keyboard paste). Never during a drag
2010
- * (state frozen — one fire at pointerup), with ONE documented in-drag firing point: the header
2011
- * subtract reservation converts to a real press on the first movement, firing the deferred
2012
- * press replace mid-drag (total fire count matches v0.1 — conversion 1 + up 1). Never for the
2013
- * initial A1 mount. TWO adapter-driven fire points, each firing from a layout effect of the
2014
- * commit that brings the new adapter or counts (neither a gesture nor a handle call): a sheet
2015
- * switch (a new adapter identity) to a non-empty adapter resets the selection to A1 through
2016
- * the wrapper and fires once, unless the selection already was the lone cell A1; and a
2017
- * same-adapter rowCount / colCount shrink that moved the selection fires once (ADR-33). A
2018
- * switch or a shrink that leaves 0 rows or 0 columns (so no A1) writes the empty-grid state
2019
- * directly and never fires.
2097
+ * paste replace, Ctrl+A, ...), with the reason as the second argument
2098
+ * ({@link SelectionChangeReason}): `"user"` for gestures, chords, commands and pastes — one
2099
+ * run by a handle call too (the handle `paste` moves the selection to the written block and
2100
+ * fires like the keyboard paste) — and `"setSelection"` for the handle's `setSelection`. Never
2101
+ * during a drag (state frozen — one fire at pointerup), with ONE documented in-drag firing
2102
+ * point: the header subtract reservation converts to a real press on the first movement,
2103
+ * firing the deferred press replace mid-drag (total fire count matches v0.1 — conversion 1 +
2104
+ * up 1). Never for the initial A1 mount. TWO adapter-driven fire points, each firing from a
2105
+ * layout effect of the commit that brings the new adapter or counts (neither a gesture nor a
2106
+ * handle call): a sheet switch (a new adapter identity) to a non-empty adapter resets the
2107
+ * selection to A1 through the wrapper and fires once with `"sheetSwitch"`, unless the
2108
+ * selection already was the lone cell A1; and a same-adapter rowCount / colCount shrink that
2109
+ * moved the selection fires once with `"countShrink"` (ADR-33). A switch or a shrink that
2110
+ * leaves 0 rows or 0 columns (so no A1) writes the empty-grid state directly and never fires.
2020
2111
  * Independent of the live region's 200ms debounce (firing point: the §6.9-1 setSelection
2021
2112
  * wrapper).
2022
- * 確定 SelectionState が変わるたびに発火。handle の呼び出しが走らせた変化も含む (handle の
2023
- * `paste` は選択を書いた範囲へ動かし、キーボードの貼り付けと同じく発火)。ドラッグ中と初期マウント
2024
- * では発火しない。明文のドラッグ中発火点が 1 つ: ヘッダー減算予約の実 press 変換 (初動 move) は
2025
- * 遅延 press 置換をドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。adapter 起点の
2026
- * 発火点は 2 つで、どちらも新しい adapter や行数・列数を運んだ commit の layout effect から発火
2027
- * (ジェスチャでも handle の呼び出しでもない): 空でない adapter へのシート切替 (adapter の同一性の
2028
- * 変化) は、ラッパー経由の A1 へのリセットで 1 回発火 (選択が既に A1 の 1 マスだけなら発火なし)。
2029
- * 同一 adapter の rowCount / colCount 縮小で選択が動いたときも 1 回発火 (ADR-33)。0 行または
2030
- * 0 列 (A1 が無い) になる切替と縮小は、空グリッドの状態をラッパーを通さずに書き、発火なし。
2113
+ * 確定 SelectionState が変わるたびに発火し、2 つ目の引数で理由を渡す ({@link SelectionChangeReason}):
2114
+ * ジェスチャ・チョード・コマンド・貼り付けは `"user"` (handle の呼び出しが走らせた変化も — handle の
2115
+ * `paste` は選択を書いた範囲へ動かし、キーボードの貼り付けと同じく発火)、handle の `setSelection` は
2116
+ * `"setSelection"`。ドラッグ中と初期マウントでは発火しない。明文のドラッグ中発火点が 1 つ: ヘッダー減算
2117
+ * 予約の実 press 変換 (初動 move) は遅延 press 置換をドラッグ中に発火する (発火総数は v0.1 と同一 —
2118
+ * 変換 1 + up 1)。adapter 起点の発火点は 2 つで、どちらも新しい adapter や行数・列数を運んだ commit の
2119
+ * layout effect から発火 (ジェスチャでも handle の呼び出しでもない): 空でない adapter へのシート切替
2120
+ * (adapter の同一性の変化) は、ラッパー経由の A1 へのリセットで `"sheetSwitch"` を 1 回発火 (選択が
2121
+ * 既に A1 の 1 マスだけなら発火なし)。同一 adapter の rowCount / colCount 縮小で選択が動いたときは
2122
+ * `"countShrink"` を 1 回発火 (ADR-33)。0 行または 0 列 (A1 が無い) になる切替と縮小は、空グリッドの
2123
+ * 状態をラッパーを通さずに書き、発火なし。
2124
+ */
2125
+ onSelectionChange?: (selection: SelectionState, reason: SelectionChangeReason) => void;
2126
+ /**
2127
+ * Notice of the in-place edit session: the new {@link EditSession} right after a session opens (F2, a double-click,
2128
+ * a printable key, an IME composition, the handle's `startEdit`), `null` right after it closes — a commit (after
2129
+ * `applyEdits` returned, before the Enter / Tab that committed moves the active cell), a cancel, the focus leaving
2130
+ * the grid, an adapter switch, a count shrink that removed the cell, an editing Ctrl+Enter fill. A refused commit
2131
+ * keeps the session open and reports nothing here. Not called on unmount. Read when it fires (no remount). The
2132
+ * handle's `getEditSession` returns the same object.
2133
+ * その場の入力のセッションの知らせ: セッションが開いた直後 (F2・ダブルクリック・印字キー・IME の変換・handle の `startEdit`) に新しい
2134
+ * {@link EditSession}、閉じた直後に `null` — 確定 (`applyEdits` が戻った後、確定した Enter / Tab がアクティブなマスを動かす前)・取り消し・
2135
+ * 焦点のグリッドの外への離脱・アダプタの切り替え・マスを消した縮小・入力中の Ctrl+Enter の埋め。断られた確定はセッションを続け、ここでは
2136
+ * 何も知らせない。アンマウントでは呼ばない。発火の時に読む (再マウント不要)。handle の `getEditSession` は同じ物を返す。
2031
2137
  */
2032
- onSelectionChange?: (selection: SelectionState) => void;
2138
+ onEditSessionChange?: (session: EditSession | null) => void;
2033
2139
  /** Consumer context menu (§6.4.3-4 / §6.6.1 Shift+F10); keyboard origin carries the active cell viewport rect. / consumer コンテキストメニュー。 */
2034
2140
  onCellContextMenu?: (cell: CellCoord, origin: {
2035
2141
  kind: "pointer";