@aiquants/spreadsheet 0.20.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@aiquants/spreadsheet",
3
- "version": "0.20.0",
3
+ "version": "0.20.1",
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"
@@ -471,19 +471,29 @@ export type SpreadsheetProps = {
471
471
  renderCell?: (ctx: RenderCellContext) => ReactNode
472
472
  /**
473
473
  * Fires on every confirmed SelectionState change (press replace, extend confirm, cycling,
474
- * paste replace, Ctrl+A, ...). Never during a drag (state frozen — one fire at pointerup),
475
- * with ONE documented in-drag firing point: the header subtract reservation converts to a
476
- * real press on the first movement, firing the deferred press replace mid-drag (total fire
477
- * count matches v0.1 — conversion 1 + up 1). Never for the initial A1 mount. ONE host-driven
478
- * fire point outside gestures (ADR-33): a same-adapter rowCount / colCount shrink that moved
479
- * the selection fires once from a layout effect of that commit — not a user gesture.
474
+ * paste replace, Ctrl+A, ...), including one run by a handle call (the handle `paste` moves
475
+ * the selection to the written block and fires like the keyboard paste). Never during a drag
476
+ * (state frozen — one fire at pointerup), with ONE documented in-drag firing point: the header
477
+ * subtract reservation converts to a real press on the first movement, firing the deferred
478
+ * press replace mid-drag (total fire count matches v0.1 — conversion 1 + up 1). Never for the
479
+ * initial A1 mount. TWO adapter-driven fire points, each firing from a layout effect of the
480
+ * commit that brings the new adapter or counts (neither a gesture nor a handle call): a sheet
481
+ * switch (a new adapter identity) to a non-empty adapter resets the selection to A1 through
482
+ * the wrapper and fires once, unless the selection already was the lone cell A1; and a
483
+ * same-adapter rowCount / colCount shrink that moved the selection fires once (ADR-33). A
484
+ * switch or a shrink that leaves 0 rows or 0 columns (so no A1) writes the empty-grid state
485
+ * directly and never fires.
480
486
  * Independent of the live region's 200ms debounce (firing point: the §6.9-1 setSelection
481
487
  * wrapper).
482
- * 確定 SelectionState が変わるたびに発火。ドラッグ中と初期マウントでは発火しない。明文の
483
- * ドラッグ中発火点が 1 つ: ヘッダー減算予約の実 press 変換 (初動 move) は遅延 press 置換を
484
- * ドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。ジェスチャ外のホスト起点発火点が
485
- * 1 つ (ADR-33): 同一 adapter の rowCount / colCount 縮小で選択が動いたとき、その commit の
486
- * layout effect から 1 回発火する (ユーザー操作ではない)。
488
+ * 確定 SelectionState が変わるたびに発火。handle の呼び出しが走らせた変化も含む (handle の
489
+ * `paste` は選択を書いた範囲へ動かし、キーボードの貼り付けと同じく発火)。ドラッグ中と初期マウント
490
+ * では発火しない。明文のドラッグ中発火点が 1 つ: ヘッダー減算予約の実 press 変換 (初動 move) は
491
+ * 遅延 press 置換をドラッグ中に発火する (発火総数は v0.1 と同一 — 変換 1 + up 1)。adapter 起点の
492
+ * 発火点は 2 つで、どちらも新しい adapter や行数・列数を運んだ commit の layout effect から発火
493
+ * (ジェスチャでも handle の呼び出しでもない): 空でない adapter へのシート切替 (adapter の同一性の
494
+ * 変化) は、ラッパー経由の A1 へのリセットで 1 回発火 (選択が既に A1 の 1 マスだけなら発火なし)。
495
+ * 同一 adapter の rowCount / colCount 縮小で選択が動いたときも 1 回発火 (ADR-33)。0 行または
496
+ * 0 列 (A1 が無い) になる切替と縮小は、空グリッドの状態をラッパーを通さずに書き、発火なし。
487
497
  */
488
498
  onSelectionChange?: (selection: SelectionState) => void
489
499
  /** Consumer context menu (§6.4.3-4 / §6.6.1 Shift+F10); keyboard origin carries the active cell viewport rect. / consumer コンテキストメニュー。 */
@@ -585,13 +595,20 @@ export type SpreadsheetProps = {
585
595
  */
586
596
  enableFillHandle?: boolean
587
597
  /**
588
- * §11 opt-out (default true): false suppresses the resize strip / unhide marker DOM
589
- * entirely (track children, not resident nodes) and inerts the band listeners. NOTE:
590
- * false also removes the unhide markers — a consumer with hidden tracks loses the
591
- * in-package restore affordance (imperative resize API only).
592
- * §11 の opt-out (既定 true)。false はストリップ / マーカーの DOM 生成ごと抑止 + 帯リスナー
593
- * 不活性。注意: unhide マーカーも消える — 非表示トラックを持つ consumer はパッケージ内の
594
- * 復元手段を失う (命令 API のみ)。
598
+ * §11 opt-out (default true): false closes every way the user changes track sizes. The
599
+ * resize strip / unhide marker DOM is suppressed entirely (track children, not resident
600
+ * nodes) and the band listeners are inert; the keyboard resize commands and the hide /
601
+ * unhide commands are unavailable (their chords pass through, `executeCommand` returns
602
+ * false); a paste writes no column widths or row heights (a copy still carries them, and
603
+ * a `columnWidths` paste resolves `"empty"`). Sizes then change only through the
604
+ * imperative API (`resizeRow` / `resizeColumn` / `autoFitColumns`), which is also the
605
+ * only restore path for hidden tracks.
606
+ * §11 の opt-out (既定 true)。false は利用者が寸法を変える道を全て閉じる。ストリップ /
607
+ * unhide マーカーの DOM 生成ごと抑止 + 帯リスナー不活性、寸法のキーのコマンドと非表示・
608
+ * 再表示のコマンドは使えず (チョードは素通し、`executeCommand` は false)、貼り付けは列幅・
609
+ * 行高を書かない (copy は運び、`columnWidths` の貼り付けは `"empty"`)。寸法を変えるのは
610
+ * 命令 API (`resizeRow` / `resizeColumn` / `autoFitColumns`) だけで、非表示トラックの
611
+ * 復元もこの API だけ。
595
612
  */
596
613
  enableResizeUI?: boolean
597
614
  /**
@@ -2261,6 +2278,10 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2261
2278
  },
2262
2279
  [rowAxis, colAxis, viewStore, repaintColHeaders, repaintHeaders, repaintOverlay, scheduleDividerHeal, reportContentSize],
2263
2280
  )
2281
+ // 非表示・再表示のコマンドと貼り付けの寸法へ渡す書き口。帯のドラッグと寸法のキーと同じく、enableResizeUI が false なら
2282
+ // 利用者は寸法を変えない — 渡さなければ両方の道が閉じ、寸法を変えるのは命令の API (resizeRow / resizeColumn /
2283
+ // autoFitColumns) だけになる
2284
+ const userResizeTracks = enableResizeUI ? resizeTracks : undefined
2264
2285
 
2265
2286
  /** Pointer contextmenu relay to onCellContextMenu (§6.4.3-4 sole channel). / pointer 起点の横流し。 */
2266
2287
  const onContextMenuSelect = useCallback(
@@ -2587,9 +2608,9 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2587
2608
  onCopyMultiRange,
2588
2609
  repaintOverlay,
2589
2610
  isDragging: isAnyDragging,
2590
- // v0.8 (§4.2.5): 寸法シーム (貼り付け寸法は gateResizeEntries を通り resizeTracks へ)、Ctrl+Shift+V の
2591
- // 武装 ref、通貨宣言、クリップ / 拒否 / 跨ぎ cut 元側の通知
2592
- resize: { rowAxis, colAxis, resizeTracks },
2611
+ // v0.8 (§4.2.5): 寸法シーム (貼り付け寸法は gateResizeEntries を通り resizeTracks へ。書き口が無ければ copy は
2612
+ // 寸法を運び、貼り付けは寸法を書かない)、Ctrl+Shift+V の武装 ref、通貨宣言、クリップ / 拒否 / 跨ぎ cut 元側の通知
2613
+ resize: { rowAxis, colAxis, resizeTracks: userResizeTracks },
2593
2614
  pendingPasteOptionsRef,
2594
2615
  formats,
2595
2616
  onClipChange,
@@ -2669,7 +2690,7 @@ export const Spreadsheet = forwardRef<SpreadsheetHandle, SpreadsheetProps & Spre
2669
2690
  paste: (options) => pasteRef.current(options),
2670
2691
  rowAxis,
2671
2692
  colAxis,
2672
- resizeTracks,
2693
+ resizeTracks: userResizeTracks,
2673
2694
  defaultRowHeight,
2674
2695
  defaultColumnWidth,
2675
2696
  now,
@@ -118,8 +118,16 @@ export type PasteOutcome = "applied" | "empty" | "rejected"
118
118
  /** The paste-only part of `PasteEditContext` the hook hands to the root's transaction seam. / フックがルートのトランザクションシームへ渡す `PasteEditContext` の貼り付け固有部。 */
119
119
  export type PasteSheet = { sameSheet: boolean; conditionalFormats: readonly ConditionalFormatRuleInput[] }
120
120
 
121
- /** The track-size seam (copy reads sizes of whole rows / columns, paste writes them through the gate). / トラック寸法シーム (copy は全行 / 全列の寸法を読み、paste はゲート経由で書く)。 */
122
- export type ClipboardResizeSeam = { rowAxis: AxisModel; colAxis: AxisModel; resizeTracks: (axis: "row" | "col", entries: readonly ResizeEntry[]) => void }
121
+ /**
122
+ * The track-size seam: copy reads the sizes of whole rows / columns through the axes, paste
123
+ * writes them through the gate and `resizeTracks`. `resizeTracks` is the write capability —
124
+ * absent ⇒ copies still carry sizes but pastes never resize (the root leaves it out under
125
+ * `enableResizeUI={false}`, where the user changes no sizes).
126
+ * トラック寸法シーム。copy は軸から全行 / 全列の寸法を読み、paste はゲートと `resizeTracks` で
127
+ * 書く。`resizeTracks` は書き込みの能力 — 無ければ copy は寸法を運び続け、paste は寸法を書かない
128
+ * (利用者が寸法を変えない `enableResizeUI={false}` では root が渡さない)。
129
+ */
130
+ export type ClipboardResizeSeam = { rowAxis: AxisModel; colAxis: AxisModel; resizeTracks?: (axis: "row" | "col", entries: readonly ResizeEntry[]) => void }
123
131
 
124
132
  /** Hook parameters (every v0.8 member is a capability declaration — absent ⇒ v0.7 branch). / フックのパラメータ (v0.8 の各メンバーは能力宣言 — 不在なら v0.7 分岐)。 */
125
133
  export type UseClipboardParams = {
@@ -145,7 +153,7 @@ export type UseClipboardParams = {
145
153
  repaintOverlay: () => void
146
154
  /** Drag-freeze probe — clipboard ops consume + no-op mid-drag (mirrors the keydown freeze). / ドラッグ凍結プローブ。 */
147
155
  isDragging: () => boolean
148
- /** Track sizes (v0.8): absent ⇒ copies carry no sizes and pastes never resize. / トラック寸法 (v0.8): 不在なら copy は寸法を運ばず paste は寸法を書かない。 */
156
+ /** Track sizes (v0.8): absent ⇒ copies carry no sizes and pastes never resize; a seam without `resizeTracks` ⇒ copies carry sizes and pastes never resize. / トラック寸法 (v0.8): 不在なら copy は寸法を運ばず paste は寸法を書かない。`resizeTracks` の無いシームなら copy は寸法を運び paste は寸法を書かない。 */
149
157
  resize?: ClipboardResizeSeam
150
158
  /** Ctrl+Shift+V arms `{ mode: "values" }` here; the next paste event consumes it once. Absent ⇒ every paste is `all`. / Ctrl+Shift+V がここへ `{ mode: "values" }` を武装し、次の paste イベントが 1 回で消費。不在なら常に `all`。 */
151
159
  pendingPasteOptionsRef?: RefObject<PasteOptions | null>
@@ -729,12 +737,13 @@ export const useClipboard = (params: UseClipboardParams): ClipboardController =>
729
737
  const commitPasteEdits = useCallback((edits: readonly CellEdit[], sheet: PasteSheet): boolean => paramsRef.current.commitPaste(edits, sheet) !== null, [])
730
738
 
731
739
  /**
732
- * Writes the sizes a paste carries (mode with `sizes`, resize seam present, payload sizes
733
- * present): one gated `resizeTracks` batch per axis over the paste rectangle, the payload's
734
- * pattern repeated per tile; a gate refusal reports `onOperationRejected("resize", …)`.
735
- * 貼り付けが運ぶ寸法を書く (`sizes` を持つモード、resize シームあり、payload に寸法あり):
736
- * 貼り付け矩形の軸毎にゲート済み `resizeTracks` 1 バッチ、payload のパターンをタイル毎に反復。
737
- * ゲート拒否は `onOperationRejected("resize", …)`。
740
+ * Writes the sizes a paste carries (mode with `sizes`, resize seam with its `resizeTracks`
741
+ * present, payload sizes present): one gated `resizeTracks` batch per axis over the paste
742
+ * rectangle, the payload's pattern repeated per tile; a gate refusal reports
743
+ * `onOperationRejected("resize", …)`.
744
+ * 貼り付けが運ぶ寸法を書く (`sizes` を持つモード、`resizeTracks` を持つ resize シームあり、
745
+ * payload に寸法あり): 貼り付け矩形の軸毎にゲート済み `resizeTracks` 1 バッチ、payload の
746
+ * パターンをタイル毎に反復。ゲート拒否は `onOperationRejected("resize", …)`。
738
747
  */
739
748
  const applyPasteSizes = useCallback((payload: ClipPayload, rect: CellRange, aspects: PasteAspects) => {
740
749
  const p = paramsRef.current
@@ -742,6 +751,10 @@ export const useClipboard = (params: UseClipboardParams): ClipboardController =>
742
751
  return
743
752
  }
744
753
  const { rowAxis, colAxis, resizeTracks } = p.resize
754
+ // 書き口の無いシームは寸法を読むだけ — 利用者が寸法を変えないグリッドでは、貼り付けも寸法を変えない
755
+ if (resizeTracks === undefined) {
756
+ return
757
+ }
745
758
  const gate = (axisKind: "row" | "col", axis: AxisModel, entries: readonly ResizeEntry[]) => {
746
759
  const result = gateResizeEntries(axis, entries, null, { maxOperationCells: p.maxOperationCells, rowHiddenLimit: ROW_HIDDEN_LIMIT, axisKind })
747
760
  if (!result.ok) {
@@ -1,5 +1,5 @@
1
1
  /**
2
- * @fileoverview The command runner (v0.8 §4.1.13 — ADR-17): `executeCommand` for all 70
2
+ * @fileoverview The command runner (v0.8 §4.1.13 — ADR-17): `executeCommand` for all 75
3
3
  * `SpreadsheetCommand` literals plus the handle's write group (`applyFormat` / `setBorders` /
4
4
  * `setHyperlink` / `setNote` / `addComment` / `setValidation`) and the capability gate
5
5
  * `isCommandAvailable`. One table (`COMMAND_SPECS`, exhaustive over the union — tsc proves every
@@ -29,7 +29,8 @@
29
29
  * rejection returns false without writing). Self-calc uses selfCalc.ts (formula cells only when
30
30
  * `getCellFormula` is declared; `null` ⇒ the cell is left alone). Fill copies text / formula
31
31
  * (shifted) / format / validation / hyperlink / note — comments excluded. Hide / unhide go
32
- * through `gateResizeEntries` and `resizeTracks` (non-undoable geometry). Paste commands go to
32
+ * through `gateResizeEntries` and `resizeTracks` (non-undoable geometry) and are available only
33
+ * while the root hands `resizeTracks` over (`enableResizeUI`). Paste commands go to
33
34
  * the menu path `paste(options)`; `pasteSpecial` prefers `onPasteSpecialRequest`. Popover
34
35
  * commands open the kind (the popover hook owns its own commit gate). Highlight toggles flip the
35
36
  * root-owned state through `setHighlight`.
@@ -49,7 +50,7 @@
49
50
  * open the viewer; content-absent and the list chord consume + refuse without force-committing).
50
51
  * Capability undeclared = every wall compiles to the previous behaviour byte-identically.
51
52
  *
52
- * コマンド実行器 (v0.8 §4.1.13 — ADR-17)。70 の SpreadsheetCommand 全件の executeCommand、handle の
53
+ * コマンド実行器 (v0.8 §4.1.13 — ADR-17)。75 の SpreadsheetCommand 全件の executeCommand、handle の
53
54
  * 書込群 (applyFormat / setBorders / setHyperlink / setNote / addComment / setValidation)、能力
54
55
  * ゲート isCommandAvailable。単一表 COMMAND_SPECS (union 全件の網羅を tsc が証明) が可用性と実行の
55
56
  * 両方を駆動する。契約: 全選択書込は gateSelectionWrite (ADR-12) → enumerateRangeCells → 1 回の
@@ -71,7 +72,8 @@
71
72
  * false)。自己計算は selfCalc.ts
72
73
  * (数式扱いは getCellFormula 宣言時のみ、null は不変)。fill は text / 数式 (shift) / format /
73
74
  * validation / hyperlink / note を複製し comments は除外。hide / unhide は gateResizeEntries →
74
- * resizeTracks (非 undo 幾何)。paste 系はメニュー経路 paste(options)、pasteSpecial は
75
+ * resizeTracks (非 undo 幾何) で、root が resizeTracks を渡すとき (enableResizeUI) だけ使える。
76
+ * paste 系はメニュー経路 paste(options)、pasteSpecial は
75
77
  * onPasteSpecialRequest 優先。popover 系は kind を開く (commit ゲートは popover フック自身)。強調
76
78
  * トグルは setHighlight。formatCommandAnnouncement (opt-in) は書式コマンド成功後に announce へ
77
79
  * (state はトグルの適用後状態、非トグルは null)。戻り値: true = commit 成功 (書くものが無い場合も)、
@@ -157,8 +159,12 @@ export type UseCommandsParams = {
157
159
  paste: (options: PasteOptions) => Promise<"applied" | "empty" | "rejected">
158
160
  rowAxis: AxisModel
159
161
  colAxis: AxisModel
160
- /** The batch resize seam (already-gated entries). / バッチリサイズシーム (ゲート済み entries)。 */
161
- resizeTracks: (axis: "row" | "col", entries: readonly ResizeEntry[]) => void
162
+ /**
163
+ * The batch resize seam of the hide / unhide commands (already-gated entries); absent ⇒ those four commands are
164
+ * unavailable (`enableResizeUI` false — the user changes no sizes).
165
+ * 非表示・再表示のコマンドのバッチリサイズシーム (ゲート済み entries)。無ければその 4 コマンドは使えない (`enableResizeUI` が false — 利用者は寸法を変えない)。
166
+ */
167
+ resizeTracks?: (axis: "row" | "col", entries: readonly ResizeEntry[]) => void
162
168
  defaultRowHeight: number
163
169
  defaultColumnWidth: number
164
170
  /** Clock seam for insertDate / insertTime. / insertDate / insertTime の時計シーム。 */
@@ -713,9 +719,14 @@ export const useCommands = (params: UseCommandsParams): CommandRunner => {
713
719
  return p.commitEdits(edits, { source: "calc" }) !== null
714
720
  }, [])
715
721
 
716
- /** hideRows / hideColumns / unhideRows / unhideColumns through the resize gates. / hide / unhide (リサイズゲート経由)。 */
722
+ /** hideRows / hideColumns / unhideRows / unhideColumns through the resize gates; false when the seam is absent, the gate refused, or the span is over the limit. / hide / unhide (リサイズゲート経由)。シームが無いとき、ゲートの拒否、上限超えは false。 */
717
723
  const runHide = useCallback((axisKind: "row" | "col", hide: boolean): boolean => {
718
724
  const p = paramsRef.current
725
+ const resizeTracks = p.resizeTracks
726
+ // 可否は isCommandAvailable が先に確かめている — 無いのは到達しない枝で、書き口の代わりは作らない
727
+ if (resizeTracks === undefined) {
728
+ return false
729
+ }
719
730
  const axis = axisKind === "row" ? p.rowAxis : p.colAxis
720
731
  const selection = p.getSelection()
721
732
  // 実体化前の保守カウント (レンジ跨ぎの重複は重複のまま数える — useHeaderResize の collectTargets と同じ規律)
@@ -753,7 +764,7 @@ export const useCommands = (params: UseCommandsParams): CommandRunner => {
753
764
  }
754
765
  // 対象トラックが無ければ幾何に触れない
755
766
  if (result.entries.length > 0) {
756
- p.resizeTracks(axisKind, result.entries)
767
+ resizeTracks(axisKind, result.entries)
757
768
  }
758
769
  return true
759
770
  }, [])
@@ -781,6 +792,8 @@ export const useCommands = (params: UseCommandsParams): CommandRunner => {
781
792
  switch (spec.kind) {
782
793
  case "resize":
783
794
  return p.trackResize !== undefined
795
+ case "hide":
796
+ return p.resizeTracks !== undefined
784
797
  case "toggle":
785
798
  case "patch":
786
799
  case "clear":