@aiquants/spreadsheet 0.19.0 → 0.20.1

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
@@ -1895,6 +1895,23 @@ export declare type SpreadsheetProps = {
1895
1895
  * 宣言の不在信号 (エンジン既定) で、本パッケージでの値フォールバックなし。
1896
1896
  */
1897
1897
  tapScrollCircleOptions?: ScrollBarTapCircleOptions;
1898
+ /**
1899
+ * Which controls of the grid's two scrollbars respond to the pointer (LIVE prop): whether the bars draw their arrow
1900
+ * buttons, and whether dragging the thumb and pressing the track scroll ({@link SpreadsheetScrollBarControls} — each
1901
+ * member reaches both bars alike; an absent member, or an absent prop, keeps the engine's default `true`). The grid
1902
+ * reads the three members by value, so an inline object literal is fine: a render with equal values redraws nothing
1903
+ * below the grid's memo boundary, and keys outside the three are not read. The bar width and the bars' pointer-only
1904
+ * declaration stay the grid's own. A host turns all three off under a coarse pointer, where a finger drags the cells
1905
+ * instead. A prop that is not an object, or a member that is neither `true`, `false` nor absent (a JS host's `null`,
1906
+ * `0` or `""`, which the engine would read as off), throws a RangeError at render.
1907
+ * グリッドの 2 本のスクロールバーの部品のうちポインタに応えるもの (ライブ prop)。バーが矢印ボタンを描くか、つまみのドラッグと
1908
+ * トラックの押下がスクロールするか ({@link SpreadsheetScrollBarControls} — どの項目も両バーへ同じく届き、無い項目も prop の
1909
+ * 省略もエンジンの既定 `true` のまま)。グリッドは 3 項目を値で読むので、インラインの object literal でよい (値の等しい描画は
1910
+ * グリッドの memo 境界より下を描き直さず、3 項目の外のキーは読まない)。バーの幅とバーのポインタ専用の宣言はグリッド自身のもの。
1911
+ * 粗いポインタ (指がセルをドラッグする) では、ホストが 3 つとも切る想定。オブジェクトでない prop と、`true`・`false`・無しの
1912
+ * どれでもない項目 (JS のホストの `null`・`0`・`""`。エンジンは切ったと読む) は、描画で RangeError を投げる。
1913
+ */
1914
+ scrollBarControls?: SpreadsheetScrollBarControls;
1898
1915
  /**
1899
1916
  * Row-axis overscan pass-through (the VirtualGrid `overscanRows` knob; LIVE prop): rows
1900
1917
  * rendered beyond each vertical viewport edge. This slack is the only thing absorbing the
@@ -1988,19 +2005,29 @@ export declare type SpreadsheetProps = {
1988
2005
  renderCell?: (ctx: RenderCellContext) => ReactNode;
1989
2006
  /**
1990
2007
  * Fires on every confirmed SelectionState change (press replace, extend confirm, cycling,
1991
- * paste replace, Ctrl+A, ...). Never during a drag (state frozen — one fire at pointerup),
1992
- * with ONE documented in-drag firing point: the header subtract reservation converts to a
1993
- * real press on the first movement, firing the deferred press replace mid-drag (total fire
1994
- * count matches v0.1 — conversion 1 + up 1). Never for the initial A1 mount. ONE host-driven
1995
- * fire point outside gestures (ADR-33): a same-adapter rowCount / colCount shrink that moved
1996
- * the selection fires once from a layout effect of that commit — not a user gesture.
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.
1997
2020
  * Independent of the live region's 200ms debounce (firing point: the §6.9-1 setSelection
1998
2021
  * wrapper).
1999
- * 確定 SelectionState が変わるたびに発火。ドラッグ中と初期マウントでは発火しない。明文の
2000
- * ドラッグ中発火点が 1 つ: ヘッダー減算予約の実 press 変換 (初動 move) は遅延 press 置換を
2001
- * ドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。ジェスチャ外のホスト起点発火点が
2002
- * 1 つ (ADR-33): 同一 adapter の rowCount / colCount 縮小で選択が動いたとき、その commit の
2003
- * layout effect から 1 回発火する (ユーザー操作ではない)。
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 が無い) になる切替と縮小は、空グリッドの状態をラッパーを通さずに書き、発火なし。
2004
2031
  */
2005
2032
  onSelectionChange?: (selection: SelectionState) => void;
2006
2033
  /** Consumer context menu (§6.4.3-4 / §6.6.1 Shift+F10); keyboard origin carries the active cell viewport rect. / consumer コンテキストメニュー。 */
@@ -2113,13 +2140,20 @@ export declare type SpreadsheetProps = {
2113
2140
  */
2114
2141
  enableFillHandle?: boolean;
2115
2142
  /**
2116
- * §11 opt-out (default true): false suppresses the resize strip / unhide marker DOM
2117
- * entirely (track children, not resident nodes) and inerts the band listeners. NOTE:
2118
- * false also removes the unhide markers — a consumer with hidden tracks loses the
2119
- * in-package restore affordance (imperative resize API only).
2120
- * §11 の opt-out (既定 true)。false はストリップ / マーカーの DOM 生成ごと抑止 + 帯リスナー
2121
- * 不活性。注意: unhide マーカーも消える — 非表示トラックを持つ consumer はパッケージ内の
2122
- * 復元手段を失う (命令 API のみ)。
2143
+ * §11 opt-out (default true): false closes every way the user changes track sizes. The
2144
+ * resize strip / unhide marker DOM is suppressed entirely (track children, not resident
2145
+ * nodes) and the band listeners are inert; the keyboard resize commands and the hide /
2146
+ * unhide commands are unavailable (their chords pass through, `executeCommand` returns
2147
+ * false); a paste writes no column widths or row heights (a copy still carries them, and
2148
+ * a `columnWidths` paste resolves `"empty"`). Sizes then change only through the
2149
+ * imperative API (`resizeRow` / `resizeColumn` / `autoFitColumns`), which is also the
2150
+ * only restore path for hidden tracks.
2151
+ * §11 の opt-out (既定 true)。false は利用者が寸法を変える道を全て閉じる。ストリップ /
2152
+ * unhide マーカーの DOM 生成ごと抑止 + 帯リスナー不活性、寸法のキーのコマンドと非表示・
2153
+ * 再表示のコマンドは使えず (チョードは素通し、`executeCommand` は false)、貼り付けは列幅・
2154
+ * 行高を書かない (copy は運び、`columnWidths` の貼り付けは `"empty"`)。寸法を変えるのは
2155
+ * 命令 API (`resizeRow` / `resizeColumn` / `autoFitColumns`) だけで、非表示トラックの
2156
+ * 復元もこの API だけ。
2123
2157
  */
2124
2158
  enableResizeUI?: boolean;
2125
2159
  /**
@@ -2389,6 +2423,29 @@ export declare type SpreadsheetProps = {
2389
2423
  className?: string;
2390
2424
  };
2391
2425
 
2426
+ /**
2427
+ * Which controls of the grid's two scrollbars respond to the pointer (`SpreadsheetProps["scrollBarControls"]`): the
2428
+ * members of the engine's `scrollBarOptions` a host may set. It is declared as an explicit structural type for the same
2429
+ * api-extractor reason as `ScrollToCellOptions`; the type parity guard of scrollBarControlsPassthrough.spec.tsx pins it to
2430
+ * the engine's members both ways and key for key under tsc. Every member reaches the vertical and the horizontal bar
2431
+ * alike, and an absent member keeps the engine's default (`true`). The bars stay pointer-only either way (the grid
2432
+ * scrolls by keyboard itself), which is what lets a host leave the arrows out — under a coarse pointer, for instance,
2433
+ * where a finger drags the cells and the bar only shows the position.
2434
+ * グリッドの 2 本のスクロールバーの部品のうちポインタに応えるもの (`SpreadsheetProps["scrollBarControls"]`)。エンジンの
2435
+ * `scrollBarOptions` のうちホストが決めてよい項目。`ScrollToCellOptions` と同じ api-extractor の訳で明示構造型とし、
2436
+ * scrollBarControlsPassthrough.spec.tsx の型パリティガードがエンジンの項目と双方向・キーごとの一致を tsc で固定する。どの項目も
2437
+ * 縦と横のバーへ同じく届き、無い項目はエンジンの既定 (`true`) のまま。バーはどちらでもポインタ専用 (キーボードのスクロールは
2438
+ * グリッド自身が持つ) で、それがホストに矢印を外させる根拠 (例えば粗いポインタ。指はセルをドラッグし、バーは位置を見せるだけ)。
2439
+ */
2440
+ export declare type SpreadsheetScrollBarControls = {
2441
+ /** Whether the bars draw their arrow buttons; without them the track runs the bar's whole length. / バーが矢印ボタンを描くか (描かなければトラックがバーの長さを全て取る)。 */
2442
+ readonly showArrowButtons?: boolean;
2443
+ /** Whether dragging the thumb scrolls. / つまみのドラッグでスクロールするか。 */
2444
+ readonly enableThumbDrag?: boolean;
2445
+ /** Whether pressing the track scrolls there. / トラックの押下でそこへスクロールするか。 */
2446
+ readonly enableTrackClick?: boolean;
2447
+ };
2448
+
2392
2449
  /**
2393
2450
  * Test-only seam props (NOT part of the public v0.1.0 contract — §8.2 counter injection).
2394
2451
  * テスト専用シーム props (公開 v0.1.0 契約外 — §8.2 カウンタ注入)。
package/dist/index.d.ts CHANGED
@@ -1895,6 +1895,23 @@ export declare type SpreadsheetProps = {
1895
1895
  * 宣言の不在信号 (エンジン既定) で、本パッケージでの値フォールバックなし。
1896
1896
  */
1897
1897
  tapScrollCircleOptions?: ScrollBarTapCircleOptions;
1898
+ /**
1899
+ * Which controls of the grid's two scrollbars respond to the pointer (LIVE prop): whether the bars draw their arrow
1900
+ * buttons, and whether dragging the thumb and pressing the track scroll ({@link SpreadsheetScrollBarControls} — each
1901
+ * member reaches both bars alike; an absent member, or an absent prop, keeps the engine's default `true`). The grid
1902
+ * reads the three members by value, so an inline object literal is fine: a render with equal values redraws nothing
1903
+ * below the grid's memo boundary, and keys outside the three are not read. The bar width and the bars' pointer-only
1904
+ * declaration stay the grid's own. A host turns all three off under a coarse pointer, where a finger drags the cells
1905
+ * instead. A prop that is not an object, or a member that is neither `true`, `false` nor absent (a JS host's `null`,
1906
+ * `0` or `""`, which the engine would read as off), throws a RangeError at render.
1907
+ * グリッドの 2 本のスクロールバーの部品のうちポインタに応えるもの (ライブ prop)。バーが矢印ボタンを描くか、つまみのドラッグと
1908
+ * トラックの押下がスクロールするか ({@link SpreadsheetScrollBarControls} — どの項目も両バーへ同じく届き、無い項目も prop の
1909
+ * 省略もエンジンの既定 `true` のまま)。グリッドは 3 項目を値で読むので、インラインの object literal でよい (値の等しい描画は
1910
+ * グリッドの memo 境界より下を描き直さず、3 項目の外のキーは読まない)。バーの幅とバーのポインタ専用の宣言はグリッド自身のもの。
1911
+ * 粗いポインタ (指がセルをドラッグする) では、ホストが 3 つとも切る想定。オブジェクトでない prop と、`true`・`false`・無しの
1912
+ * どれでもない項目 (JS のホストの `null`・`0`・`""`。エンジンは切ったと読む) は、描画で RangeError を投げる。
1913
+ */
1914
+ scrollBarControls?: SpreadsheetScrollBarControls;
1898
1915
  /**
1899
1916
  * Row-axis overscan pass-through (the VirtualGrid `overscanRows` knob; LIVE prop): rows
1900
1917
  * rendered beyond each vertical viewport edge. This slack is the only thing absorbing the
@@ -1988,19 +2005,29 @@ export declare type SpreadsheetProps = {
1988
2005
  renderCell?: (ctx: RenderCellContext) => ReactNode;
1989
2006
  /**
1990
2007
  * Fires on every confirmed SelectionState change (press replace, extend confirm, cycling,
1991
- * paste replace, Ctrl+A, ...). Never during a drag (state frozen — one fire at pointerup),
1992
- * with ONE documented in-drag firing point: the header subtract reservation converts to a
1993
- * real press on the first movement, firing the deferred press replace mid-drag (total fire
1994
- * count matches v0.1 — conversion 1 + up 1). Never for the initial A1 mount. ONE host-driven
1995
- * fire point outside gestures (ADR-33): a same-adapter rowCount / colCount shrink that moved
1996
- * the selection fires once from a layout effect of that commit — not a user gesture.
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.
1997
2020
  * Independent of the live region's 200ms debounce (firing point: the §6.9-1 setSelection
1998
2021
  * wrapper).
1999
- * 確定 SelectionState が変わるたびに発火。ドラッグ中と初期マウントでは発火しない。明文の
2000
- * ドラッグ中発火点が 1 つ: ヘッダー減算予約の実 press 変換 (初動 move) は遅延 press 置換を
2001
- * ドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。ジェスチャ外のホスト起点発火点が
2002
- * 1 つ (ADR-33): 同一 adapter の rowCount / colCount 縮小で選択が動いたとき、その commit の
2003
- * layout effect から 1 回発火する (ユーザー操作ではない)。
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 が無い) になる切替と縮小は、空グリッドの状態をラッパーを通さずに書き、発火なし。
2004
2031
  */
2005
2032
  onSelectionChange?: (selection: SelectionState) => void;
2006
2033
  /** Consumer context menu (§6.4.3-4 / §6.6.1 Shift+F10); keyboard origin carries the active cell viewport rect. / consumer コンテキストメニュー。 */
@@ -2113,13 +2140,20 @@ export declare type SpreadsheetProps = {
2113
2140
  */
2114
2141
  enableFillHandle?: boolean;
2115
2142
  /**
2116
- * §11 opt-out (default true): false suppresses the resize strip / unhide marker DOM
2117
- * entirely (track children, not resident nodes) and inerts the band listeners. NOTE:
2118
- * false also removes the unhide markers — a consumer with hidden tracks loses the
2119
- * in-package restore affordance (imperative resize API only).
2120
- * §11 の opt-out (既定 true)。false はストリップ / マーカーの DOM 生成ごと抑止 + 帯リスナー
2121
- * 不活性。注意: unhide マーカーも消える — 非表示トラックを持つ consumer はパッケージ内の
2122
- * 復元手段を失う (命令 API のみ)。
2143
+ * §11 opt-out (default true): false closes every way the user changes track sizes. The
2144
+ * resize strip / unhide marker DOM is suppressed entirely (track children, not resident
2145
+ * nodes) and the band listeners are inert; the keyboard resize commands and the hide /
2146
+ * unhide commands are unavailable (their chords pass through, `executeCommand` returns
2147
+ * false); a paste writes no column widths or row heights (a copy still carries them, and
2148
+ * a `columnWidths` paste resolves `"empty"`). Sizes then change only through the
2149
+ * imperative API (`resizeRow` / `resizeColumn` / `autoFitColumns`), which is also the
2150
+ * only restore path for hidden tracks.
2151
+ * §11 の opt-out (既定 true)。false は利用者が寸法を変える道を全て閉じる。ストリップ /
2152
+ * unhide マーカーの DOM 生成ごと抑止 + 帯リスナー不活性、寸法のキーのコマンドと非表示・
2153
+ * 再表示のコマンドは使えず (チョードは素通し、`executeCommand` は false)、貼り付けは列幅・
2154
+ * 行高を書かない (copy は運び、`columnWidths` の貼り付けは `"empty"`)。寸法を変えるのは
2155
+ * 命令 API (`resizeRow` / `resizeColumn` / `autoFitColumns`) だけで、非表示トラックの
2156
+ * 復元もこの API だけ。
2123
2157
  */
2124
2158
  enableResizeUI?: boolean;
2125
2159
  /**
@@ -2389,6 +2423,29 @@ export declare type SpreadsheetProps = {
2389
2423
  className?: string;
2390
2424
  };
2391
2425
 
2426
+ /**
2427
+ * Which controls of the grid's two scrollbars respond to the pointer (`SpreadsheetProps["scrollBarControls"]`): the
2428
+ * members of the engine's `scrollBarOptions` a host may set. It is declared as an explicit structural type for the same
2429
+ * api-extractor reason as `ScrollToCellOptions`; the type parity guard of scrollBarControlsPassthrough.spec.tsx pins it to
2430
+ * the engine's members both ways and key for key under tsc. Every member reaches the vertical and the horizontal bar
2431
+ * alike, and an absent member keeps the engine's default (`true`). The bars stay pointer-only either way (the grid
2432
+ * scrolls by keyboard itself), which is what lets a host leave the arrows out — under a coarse pointer, for instance,
2433
+ * where a finger drags the cells and the bar only shows the position.
2434
+ * グリッドの 2 本のスクロールバーの部品のうちポインタに応えるもの (`SpreadsheetProps["scrollBarControls"]`)。エンジンの
2435
+ * `scrollBarOptions` のうちホストが決めてよい項目。`ScrollToCellOptions` と同じ api-extractor の訳で明示構造型とし、
2436
+ * scrollBarControlsPassthrough.spec.tsx の型パリティガードがエンジンの項目と双方向・キーごとの一致を tsc で固定する。どの項目も
2437
+ * 縦と横のバーへ同じく届き、無い項目はエンジンの既定 (`true`) のまま。バーはどちらでもポインタ専用 (キーボードのスクロールは
2438
+ * グリッド自身が持つ) で、それがホストに矢印を外させる根拠 (例えば粗いポインタ。指はセルをドラッグし、バーは位置を見せるだけ)。
2439
+ */
2440
+ export declare type SpreadsheetScrollBarControls = {
2441
+ /** Whether the bars draw their arrow buttons; without them the track runs the bar's whole length. / バーが矢印ボタンを描くか (描かなければトラックがバーの長さを全て取る)。 */
2442
+ readonly showArrowButtons?: boolean;
2443
+ /** Whether dragging the thumb scrolls. / つまみのドラッグでスクロールするか。 */
2444
+ readonly enableThumbDrag?: boolean;
2445
+ /** Whether pressing the track scrolls there. / トラックの押下でそこへスクロールするか。 */
2446
+ readonly enableTrackClick?: boolean;
2447
+ };
2448
+
2392
2449
  /**
2393
2450
  * Test-only seam props (NOT part of the public v0.1.0 contract — §8.2 counter injection).
2394
2451
  * テスト専用シーム props (公開 v0.1.0 契約外 — §8.2 カウンタ注入)。