@aiquants/spreadsheet 0.20.0 → 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/CHANGELOG.md +118 -0
- package/README.md +70 -14
- package/dist/index.cjs +8 -8
- package/dist/index.d.cts +142 -19
- package/dist/index.d.ts +142 -19
- package/dist/index.js +4578 -4485
- package/dist/styles/spreadsheet.standalone.css +1 -1
- package/package.json +2 -2
- package/src/Spreadsheet.tsx +226 -36
- package/src/clipboard/useClipboard.ts +22 -9
- package/src/commands/useCommands.ts +21 -8
- package/src/editor/useCellEditor.ts +38 -6
- package/src/index.ts +13 -1
- package/src/keyboard/useGridKeyboard.ts +101 -3
- package/src/selection/selectionState.ts +70 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,124 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `@aiquants/spreadsheet` are documented here.
|
|
4
4
|
|
|
5
|
+
## 0.20.2 (2026-11-18)
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **The handle's `setSelection(selection, options?)`** places the selection — its ranges, anchor and active cell — where
|
|
10
|
+
the host decides: a row the page selects from its URL, the same month after the host moved the window a year, the row
|
|
11
|
+
a re-sort put elsewhere. It takes the shape `getSelection()` returns (at least one range, each start at most its end,
|
|
12
|
+
the anchor inside the last range, the active cell inside some range, every bound a whole number inside the grid) and
|
|
13
|
+
throws a `RangeError` for anything else, keeps a copy, accepts a hidden row or column, and goes through the gestures'
|
|
14
|
+
write path: `onSelectionChange` fires once (not for an equal selection), the announcement formatters run, the active
|
|
15
|
+
cell's input message shows and the next Arrow key moves from the placed active cell. It returns `false` and changes
|
|
16
|
+
nothing while a cell is being edited (the session is never closed for it) or a pointer drag is in flight.
|
|
17
|
+
`{ scroll: true }` brings the active cell into view with an Arrow key's minimal scroll; without it no scroll position
|
|
18
|
+
changes. Focus does not move. Option type `SetSelectionOptions`.
|
|
19
|
+
- **`onSelectionChange` passes the reason as its second argument** (`SelectionChangeReason`): `"user"` for gestures,
|
|
20
|
+
chords, commands and pastes (the commands and pastes a host runs through the handle included), `"setSelection"` for a
|
|
21
|
+
placement, `"sheetSwitch"` for the reset to A1 when the adapter identity changes, `"countShrink"` for the clamp after
|
|
22
|
+
the same adapter's `rowCount` / `colCount` shrank. A host no longer guesses which notices are the user's; a
|
|
23
|
+
one-parameter callback keeps working.
|
|
24
|
+
- **`onEditSessionChange(session)` and the handle's `getEditSession()`** report the in-place edit session (`EditSession`
|
|
25
|
+
= `{ cell, mode: "edit" | "replace" }`): the session right after it opens (F2, a double-click, a printable key, an IME
|
|
26
|
+
composition, `startEdit`) and `null` right after it closes — a commit (after `applyEdits` returned, before the Enter /
|
|
27
|
+
Tab that committed moves the active cell), a cancel, the focus leaving the grid, an adapter switch, a count shrink that
|
|
28
|
+
removed the cell, an editing Ctrl+Enter fill. A refused commit keeps the session open and reports nothing.
|
|
29
|
+
`getEditSession()` returns the object last reported, or `null`.
|
|
30
|
+
- **The handle's `commitEdit()`** (`CommitEditOutcome`) commits the open session exactly as Enter does — the strict
|
|
31
|
+
validation gate, the read-only re-check, `applyEdits` when the text changed — without moving the active cell, for a
|
|
32
|
+
host that saves from a key of its own while the focus stays in the grid: `"committed"` (the session closed),
|
|
33
|
+
`"rejected"` (refused through `onEditRejected`, `onValidationRejected` or `onReadOnlyRejected` as an Enter's would; the
|
|
34
|
+
session stays open with the typed text) or `"idle"` (no session). A composition in flight is confirmed first, as a
|
|
35
|
+
press elsewhere in the grid confirms it.
|
|
36
|
+
|
|
37
|
+
### Fixed
|
|
38
|
+
|
|
39
|
+
- **Ctrl+Enter (`fillSelection`) pressed during an IME composition fills on the first press.** The composition guard
|
|
40
|
+
dropped every keydown of an open composition, so the first Ctrl+Enter only confirmed the composition and a second
|
|
41
|
+
press filled; a press within 50 ms after a confirmation was dropped too, as the window that skips Safari's confirming
|
|
42
|
+
Enter / Escape looked at the key only. Now the editing column's `fillSelection` chord — read from the physical key
|
|
43
|
+
(`event.code`), so a chord rebound through `shortcuts` too — is remembered while the composition is open and runs once
|
|
44
|
+
in the task after `compositionend`, with the confirmed text, when that text is not empty and the session is still
|
|
45
|
+
open; a chord arriving right after the composition ended (Safari fires `compositionend` before the confirming keydown,
|
|
46
|
+
and the 50 ms window) runs at once. A plain Enter during a composition still only confirms it, any other key during
|
|
47
|
+
the composition forgets the chord, a cancelled composition fills nothing (the session it opened starts empty, and
|
|
48
|
+
filling would clear every selected cell), and the IME keydown itself is still never `preventDefault`ed. Every other
|
|
49
|
+
chord pressed during a composition stays with the IME.
|
|
50
|
+
|
|
51
|
+
### Verification
|
|
52
|
+
|
|
53
|
+
- **公開面**: 公開面は `index.ts` の値 44 + 型 104 = 148 export (型 `EditSession`・`CommitEditOutcome`・
|
|
54
|
+
`SelectionChangeReason`・`SetSelectionOptions` を追加)。DOM 属性は 0.20.1 と同じ。
|
|
55
|
+
- **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **103 ファイル 4,384 テスト** 全緑 — 0.20.1 出荷時の
|
|
56
|
+
101 ファイル 4,341 に v0.20.2 進行分 +43 (新規 `hostControl` 24 — 置く口の置き方・写し・入力中とドラッグ中の断り・形の
|
|
57
|
+
誤り・`scroll`・隠した行、通知の 4 つの理由、入力のセッションの開閉と `applyEdits`・Enter の移動との順、`commitEdit` の
|
|
58
|
+
idle・確定・同じ字・3 つの断り・変換中、新規 `imeFillSelection` 10 — Chromium と Safari の順・確定の直後の 50 ms の窓・
|
|
59
|
+
素の Enter・取り消した変換・途中の別のキー・付け替えたチョード・閉じた入力・2 回押し・入力していない時、`selectionState`
|
|
60
|
+
+8 (`placedSelectionOf`)、0.20.1 節の出荷時凍結ピンで `hxCensus` +1)。`pointing` は件数を変えずに通知の理由を照らす。
|
|
61
|
+
変異 11 件は全て赤: 変換中の keydown を扱わない (4 件)・取り消した変換でも埋める (1)・別のキーで覚えを捨てない (1)・閉じた
|
|
62
|
+
入力でも埋める (2)・入力中でも置く (1)・ドラッグ中でも置く (1)・写しでなく渡された物を持つ (3)・`scroll` を無視する (1)・
|
|
63
|
+
切り替えの理由を `"user"` にする (1)・閉じたことを知らせない (5)・断りを確定と言う (3)。
|
|
64
|
+
- **検証 — E2E**: `editing` +1 (23 テスト)。実の Chromium で CDP の IME 経路
|
|
65
|
+
(`Input.imeSetComposition` → IME が処理した Ctrl+Enter の `rawKeyDown` → `Input.insertText`) を通し、確定した字で選んだ
|
|
66
|
+
3 マスが 1 回で埋まり、届いた keydown が key `Process`・keyCode 229・`isComposing: true` で既定を止めないことを確かめた
|
|
67
|
+
(`AQSP_E2E_PORT=5279 playwright test tests/e2e/editing.spec.ts` で 23 passed)。直しの要の行を外すと 1 マスも埋まらず赤。
|
|
68
|
+
E2E の総数は 26 ファイル 300 テスト。`tsc --noEmit` / biome / markdownlint 0。
|
|
69
|
+
- **触れていないこと**: 実機の IME (Windows の Microsoft IME と Chrome / Edge・macOS の Safari)。Safari の順
|
|
70
|
+
(`compositionend` が先) は jsdom の上で出来事の順を写して確かめた。
|
|
71
|
+
|
|
72
|
+
## 0.20.1 (2026-11-14)
|
|
73
|
+
|
|
74
|
+
### Fixed
|
|
75
|
+
|
|
76
|
+
- **`enableResizeUI={false}` closes every way the user changes track sizes.** The prop removed the resize strips and the
|
|
77
|
+
unhide markers and made the keyboard resize commands unavailable, but the hide / unhide commands (`hideRows` /
|
|
78
|
+
`hideColumns` / `unhideRows` / `unhideColumns`, by default Ctrl+Alt+Digit9 / unbound / Ctrl+Shift+Digit9 /
|
|
79
|
+
Ctrl+Shift+Digit0) still hid and restored rows and columns, and a paste still wrote the column widths and row heights
|
|
80
|
+
that a whole-column / whole-row copy, or a foreign HTML table (an Excel one) sizing every column or row, carries. With
|
|
81
|
+
the prop `false` the four commands are unavailable — their chords pass through, while a cell is being edited too, and
|
|
82
|
+
`executeCommand` returns `false` without committing a session — and a paste writes the cells only. A copy still
|
|
83
|
+
carries the sizes, so a grid with the resize UI can paste them, and a `columnWidths` paste resolves `"empty"` without
|
|
84
|
+
calling the adapter. Sizes then change only through the imperative API (`resizeRow` / `resizeColumn` /
|
|
85
|
+
`autoFitColumns`), which is also the only way back for a hidden track, as the README already said. The prop stays
|
|
86
|
+
live: a render with the other value takes effect at the next command or paste.
|
|
87
|
+
|
|
88
|
+
### Changed
|
|
89
|
+
|
|
90
|
+
- **README**: "Resize, hide/unhide, and autofit" (what `enableResizeUI={false}` closes), the keymap rows of the keyboard
|
|
91
|
+
resize and the hide / unhide commands, the props table (`enableResizeUI`), the handle's `paste` outcomes (an `"empty"`
|
|
92
|
+
paste writes no sizes under `enableResizeUI={false}`) and the sizes row of "Deviations from Excel".
|
|
93
|
+
- **Specs 00, 03, 04, 05 and 08**: the same contract — the clipboard's resize seam takes `resizeTracks` as an optional
|
|
94
|
+
write capability (absent: copies carry sizes, pastes write none), and the hide / unhide commands are available only
|
|
95
|
+
while the grid hands it over.
|
|
96
|
+
|
|
97
|
+
### Documentation
|
|
98
|
+
|
|
99
|
+
- **`onSelectionChange` names every source that fires it** (README, the prop's JSDoc, spec 00): a selection change run
|
|
100
|
+
by a handle call (the handle `paste` moves the selection to the written block) fires it like a gesture, and beside
|
|
101
|
+
gestures and handle calls it fires at two adapter-driven points — the reset to A1 when the adapter switches to a
|
|
102
|
+
non-empty one (not when the selection already was the lone cell A1) and a same-adapter `rowCount` / `colCount` shrink
|
|
103
|
+
that moved the selection. A switch or a shrink that leaves 0 rows or 0 columns fires nothing.
|
|
104
|
+
- **The command counts read 75 commands, 105 table rows and 41 default chords** in the source comments, the test names
|
|
105
|
+
and specs 04, 07 and 08 — the numbers the tests assert.
|
|
106
|
+
|
|
107
|
+
### Verification
|
|
108
|
+
|
|
109
|
+
- **公開面**: 0.20.0 と同じ 144 export。DOM 属性も 0.20.0 と同じ。
|
|
110
|
+
- **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **101 ファイル 4,341 テスト** 全緑 — 0.20.0 出荷時の
|
|
111
|
+
100 ファイル 4,331 に v0.20.1 進行分 +10 (新規 `resizeUiOptOut` 7 — 既定のグリッドの対照・false の 4 コマンドとチョードと
|
|
112
|
+
命令の API・prop の描き直し・自前の全列 / 全行の貼り付け・Excel のクリップ・`columnWidths` の貼り付け・false のグリッドの
|
|
113
|
+
copy が運ぶ寸法、`useCommands` +1 (書き口の無い 4 コマンド)、`useClipboard` +1 (書き口の無いシーム)、0.20.0 節の出荷時
|
|
114
|
+
凍結ピンで `hxCensus` +1)。`tsc --noEmit` / biome 0。変異: root が `enableResizeUI` に依らず書き口を渡す形で
|
|
115
|
+
`resizeUiOptOut` の 5 件が赤 (変異で変わらない既定のグリッドの対照と copy が運ぶ寸法の 2 件は緑)。E2E は流していない —
|
|
116
|
+
true の道は書き口が同じ関数で振る舞いが変わらず、E2E の opt-out の試験は帯の DOM の有無だけを見るため。
|
|
117
|
+
- **試験の記録**: `resizeBudget` (1 万行のファンアウトの予算) は、計測の 3 回の間だけ React の act 環境の旗を外す。旗が
|
|
118
|
+
立ったままだと act の外の更新ごとに警告が組み立てられ (計 89,925 回 — 0.20.0 でも同じ数)、その費用が計測の窓に入り、
|
|
119
|
+
スイートの記録を 34 MB にしていた。負荷のもとでは vitest のワーカーの 60 秒の RPC のタイマーが切れ
|
|
120
|
+
(`Timeout calling "onTaskUpdate"`)、全件が通っても終了コードが 1 になる。直した後の警告は 2 回で、単独の認証
|
|
121
|
+
(`AQSP_BENCH_SOLO=1`) の予算 300ms は保たれ、repaint を 1 件ごとへ戻す変異は中央値 510ms で赤のまま。
|
|
122
|
+
|
|
5
123
|
## 0.20.0 (2026-11-06)
|
|
6
124
|
|
|
7
125
|
### Added
|
package/README.md
CHANGED
|
@@ -128,9 +128,9 @@ The host element must have a resolvable height — the grid fills its parent.
|
|
|
128
128
|
|
|
129
129
|
- **Adapter identity is the sheet identity.** Replacing the adapter object means "sheet switch": selection resets to A1, any in-flight drag, editing session and open popover are terminated (value-discarding, exactly like Excel switching sheets — nothing is ever committed across a swap), an armed
|
|
130
130
|
**copy** is discarded, and an armed **cut** is kept as a *foreign* clip (`onClipChange({ kind: "cut", range, foreign: true })`, its marquee hidden) so the next `Ctrl+V` on the new sheet is a **cross-sheet move** — the target sheet is written first, then the source sheet is cleared under the same
|
|
131
|
-
transaction id (see "Cut matching rule").
|
|
131
|
+
transaction id (see "Cut matching rule"). The reset fires `onSelectionChange` once from a layout effect (host-driven, not a gesture) unless the selection already was the lone cell A1; a switch to an empty adapter (0 rows or 0 columns, so no A1) fires nothing.
|
|
132
132
|
- **A count shrink keeps the identity.** When `rowCount` / `colCount` shrink under the SAME adapter (a filter, category or period change removes rows), the package clamps its own coordinates instead of resetting (ADR-33): every selection range, the anchor and the active cell are pulled onto the last row / column (a range entirely beyond the edge collapses onto it; one `onSelectionChange` when anything moved, none otherwise),
|
|
133
|
-
an editing session, a popover or a note tip whose cell left the grid is cancelled / closed (those still inside are kept), an armed clip whose range left the grid is discarded (a foreign cut is untouched), in-flight drags are cancelled, and a shrink to zero rows / columns lands on the empty-grid state. Growth changes nothing. The engine's out-of-range fail-fast stays intact — the package clamps its state before anything is measured.
|
|
133
|
+
an editing session, a popover or a note tip whose cell left the grid is cancelled / closed (those still inside are kept), an armed clip whose range left the grid is discarded (a foreign cut is untouched), in-flight drags are cancelled, and a shrink to zero rows / columns lands on the empty-grid state without firing `onSelectionChange` (a grid with no rows or no columns has no A1). Growth changes nothing. The engine's out-of-range fail-fast stays intact — the package clamps its state before anything is measured.
|
|
134
134
|
Traits to know: the fold fires `onSelectionChange` once from a layout effect (host-driven, not a gesture); closing a popover this way takes the popover's normal close path, which returns focus to the grid; a kept selection / session is index-based — after a filter, row r shows whichever item now occupies row r (your data model decides). A kept editing session whose formula token references a vanished row keeps working — keyboard reference pointing clamps the token-derived cursor onto the grid before it steps.
|
|
135
135
|
A popover closed this way leaves your focus alone while it sits outside the grid (a filter input); only a close from inside the grid returns focus to the sink.
|
|
136
136
|
- **External writes** (your toolbar Undo, collaborative updates) are published by incrementing the `dataVersion` prop. This re-renders visible cells, rebuilds the conditional-format index, **and cancels any armed clip** — otherwise a stale cut could "move" cells whose content has changed underneath.
|
|
@@ -379,10 +379,13 @@ Row autofit restores the default row height (cells render single-line clipped).
|
|
|
379
379
|
> font or spacing than their pane, autofit will mismeasure — set them on the root, which the pane, the cells and the
|
|
380
380
|
> header bands all inherit (the shipped stylesheets do).
|
|
381
381
|
|
|
382
|
-
`enableResizeUI={false}`
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
382
|
+
`enableResizeUI={false}` closes every way the user changes track sizes: it removes the strips **and the unhide markers**,
|
|
383
|
+
makes the keyboard resize commands and the hide / unhide commands unavailable (their chords pass through and
|
|
384
|
+
`executeCommand` returns `false`), and keeps a paste from writing column widths or row heights (a copy still carries them,
|
|
385
|
+
so a grid with the resize UI can paste them; a `columnWidths` paste resolves `"empty"`). A consumer with hidden tracks then
|
|
386
|
+
has no in-package restore affordance (only the imperative API). The imperative `resizeRow` / `resizeColumn` calls bypass
|
|
387
|
+
every UI gate (no 1px clamp, no hidden-row cap, no fan-out limit): mass-hiding rows through the API is your responsibility
|
|
388
|
+
and falls outside the rendering guarantee.
|
|
386
389
|
|
|
387
390
|
## Fill handle (autofill)
|
|
388
391
|
|
|
@@ -790,13 +793,13 @@ track, and paging moves by exact viewport-height pixel geometry, so page landing
|
|
|
790
793
|
| Ctrl+Alt+M | Comment thread popover on the active cell | Native | Native | `insertComment` |
|
|
791
794
|
| Alt+ArrowDown | Validation list picker (cells with a `list` rule) | Native | Native | `openValidationList` |
|
|
792
795
|
| Ctrl+D / Ctrl+R | Fill down / right (first row / column of each range, or the neighbour above / left for a single row / column; formulas shift) | Consumed, not run (`onCommandBlockedWhileEditing`) — the browser's bookmark / reload never fires and the typed value stays | Same | `fillDown` / `fillRight` |
|
|
793
|
-
| Ctrl+Enter | Fill every selected cell with the active cell's content | Run the strict validation gate on every selected cell's own rule (the first strict rejection keeps the session open, exactly like Enter), then write the session text to every selected cell in one transaction and close the session | Same | `fillSelection` |
|
|
796
|
+
| Ctrl+Enter | Fill every selected cell with the active cell's content | Run the strict validation gate on every selected cell's own rule (the first strict rejection keeps the session open, exactly like Enter), then write the session text to every selected cell in one transaction and close the session. Pressed during an IME composition (the chord is read from the physical key, so a rebound chord too), it fills once the composition commits, with the confirmed text — one press; a cancelled composition (nothing confirmed) fills nothing, and a session closed before then (the focus left the grid) is not filled. Every other chord pressed during a composition stays with the IME | Same | `fillSelection` |
|
|
794
797
|
| Ctrl+Semicolon / Ctrl+Shift+Semicolon | Write today's date (`YYYY-MM-DD`) / the current time (`HH:mm:ss`, local, `now` prop) into the **active cell only** | Insert at the caret | Same | `insertDate` / `insertTime` |
|
|
795
|
-
| Ctrl+Alt+Digit9 / Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0 | Hide the selected rows / unhide rows / unhide columns (through the resize gates) | Ctrl+Alt+Digit9: native; Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0: consumed, not run (`onCommandBlockedWhileEditing`) | Same | `hideRows` / `unhideRows` / `unhideColumns` |
|
|
798
|
+
| Ctrl+Alt+Digit9 / Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0 | Hide the selected rows / unhide rows / unhide columns (through the resize gates); unavailable with `enableResizeUI={false}` | Ctrl+Alt+Digit9: native; Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0: consumed, not run (`onCommandBlockedWhileEditing`) | Same | `hideRows` / `unhideRows` / `unhideColumns` |
|
|
796
799
|
| Alt+Shift+ArrowRight / Alt+Shift+ArrowLeft | Widen / narrow the active column by one step (× / ÷ 2^(1/4), whole px, at least 1 px of change, never below 1 px — a step never hides a column); with a full-span column selection every selected column takes the new size, as a strip drag does. Allowed under `readOnly` (a view change), unavailable with `enableResizeUI={false}` | Native | Native | `increaseColumnWidth` / `decreaseColumnWidth` |
|
|
797
800
|
| Alt+Shift+ArrowDown / Alt+Shift+ArrowUp | Make the active row taller / shorter by one step (same rule and fan-out) | Native | Native | `increaseRowHeight` / `decreaseRowHeight` |
|
|
798
801
|
| Alt+Shift+Equal (`=`) | Fit the active column to its content (the strip double-click's autofit; no-op while `renderCell` is set) | Native | Native | `autoFitColumnWidth` |
|
|
799
|
-
| *(unbound by default)* | Hide the selected columns — bind it yourself, e.g. `shortcuts={{ hideColumns: ["Ctrl+Alt+Shift+Digit9"] }}` | — | — | `hideColumns` |
|
|
802
|
+
| *(unbound by default)* | Hide the selected columns — bind it yourself, e.g. `shortcuts={{ hideColumns: ["Ctrl+Alt+Shift+Digit9"] }}`; unavailable with `enableResizeUI={false}` | — | — | `hideColumns` |
|
|
800
803
|
| *(unbound by default)* | General (no value format) / all four borders | — | — | `formatGeneral` / `bordersAll` |
|
|
801
804
|
| *(unbound by default)* | Paste Special modes through the menu path (`handle.paste`) | — | — | `pasteFormats` / `pasteFormulas` / `pasteAdd` / `pasteSubtract` / `pasteMultiply` / `pasteDivide` |
|
|
802
805
|
| *(unbound by default)* | Self-calc over the selection (exact decimal shift, formulas wrapped `=(…)*100`; non-numeric cells untouched) | — | — | `multiplyBy100` / `multiplyBy1000` / `divideBy100` / `divideBy1000` / `signReversal` |
|
|
@@ -940,13 +943,14 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
|
|
|
940
943
|
| `frozenTrailingRows` | `number` | Freezes the **last** N rows at the bottom edge (v0.9; default 0, LIVE — the row-axis twin of `frozenTrailingColumns`; a pinned totals row is the canonical use). Same engine validation and leading-wins clamp; trailing rows stay visible at any vertical scroll (same overlap exception); keyboard ensure-visible treats them as vertical no-ops. |
|
|
941
944
|
| `renderCell` | `(ctx: RenderCellContext) => ReactNode` — `RenderCellContext = { row; col; text; displayText }` (exported) | Custom cell rendering. **Must be identity-stable** (`useCallback`) — an inline arrow defeats the cell memo and re-renders every visible cell each pass. **Per-cell opt-out** (v0.12 — ADR-32): return `undefined` and that one cell falls back to the package default rendering, value-format engine included (only `undefined` opts out — `null`, `false` and any other ReactNode are custom output, i.e. an empty custom cell). `ctx.text` is the raw canonical string; `ctx.displayText` is the value-format display — the exact string the default rendering, announcements, the HTML clipboard and autofit share, so a custom cell that renders it can never drift from what gets copied. Autofit stays a whole-grid no-op while `renderCell` is set. |
|
|
942
945
|
| `maxOperationCells` | `number` | Bulk-operation ceiling (default 100,000). Row fan-out resize gates at 1/10 of it and autofit at 1/4 — see "Operation limits". |
|
|
943
|
-
| `enableResizeUI` | `boolean` | Default `true`. `false` removes resize strips **and unhide markers
|
|
946
|
+
| `enableResizeUI` | `boolean` | Default `true`. `false` removes resize strips **and unhide markers**, makes the keyboard resize and hide / unhide commands unavailable, and keeps pastes from writing sizes (copies still carry them) — sizes then change, and hidden tracks come back, only through the imperative API. |
|
|
944
947
|
| `headings` | `boolean` | v0.17 — default `true`: shows the column letters, the row numbers and the corner (Excel's "headings"; not `headerRows`). `false` draws none of the three and collapses their grid tracks to 0, so the cells start at the grid's top-left corner; the gestures that live only on them go with them (header presses, the corner's select-all, the resize strips and unhide markers) and their keyboard twins stay (Ctrl+Space, Shift+Space, Ctrl+A, Alt+Shift+Arrow, Alt+Shift+=). The bands are `aria-hidden`, so assistive technology meets the same grid. The root carries `data-aqsp-headings-hidden` while they are hidden. LIVE prop. |
|
|
945
948
|
| `onContentSizeChange` | `(size: SpreadsheetContentSize) => void` | v0.17 — receives the size of the grid's content in CSS px: the bands (when shown), every column and row at its current size and the two scroll bars the grid always reserves, all scaled by the zoom (the scroll bars live inside the zoom wrapper, so they scale too). Called after the first layout and after every change of it — a track's size (a resize, an autofit, a hide or unhide, the imperative `resizeRow` / `resizeColumn`), the row or column count, the default sizes, the zoom or `headings` — never with an unchanged size. The bands count on whichever side of the cells they sit (a right-to-left grid too) and in a box smaller than them; a grid with no rows or no columns draws nothing and reports 0 × 0; a grid without a layout box (under a `display: none` ancestor) reports once it has one. See *Fitting a box to the grid*. |
|
|
946
949
|
| `frame` | `CellRange` | v0.18 — draws a frame around a range of cells: a line of `--aqsp-frame-width` (2px by default) in `--aqsp-frame-color` (default `#1f2937`) just inside the outer edges of the range's cells, scrolling with them and scaled by the zoom like their lines. The part of the range inside the grid is framed; bounds that are not non-negative integers with each start at most its end throw a RangeError. Each pane frames the part it paints and leaves open a side the range continues past (`data-aqsp-frame-open`), so frozen panes join into one frame. The frame sits over the freeze dividers and the bands and under the active cell's frame; while it is set the bands, the dividers and the marquee's far headroom stop at the last painted cell, and the root carries `data-aqsp-framed`. See *Framing a range*. LIVE prop. |
|
|
947
950
|
| `zoom` / `defaultZoom` / `onZoomChange` | `number` / `number` / `(zoom: number) => void` | Package zoom (v0.3): visual transform scale, logic stays in logical px. Controlled (`zoom`) or uncontrolled (`defaultZoom`, default 1). Gestures — Alt+Wheel and Ctrl+Alt+`=` / `+` / `-` / `0` (reset; the four keys match the produced character, Shift-agnostic; AltGraph-state chords are never claimed — legacy-shape defense in depth, see Keymap notes) — request via `onZoomChange`; Ctrl+Wheel is deliberately unbound (the browser owns it). Clamped to [`SPREADSHEET_ZOOM_MIN`, `SPREADSHEET_ZOOM_MAX`] (0.25–4, `clampSpreadsheetZoom` of `@aiquants/spreadsheet/view`); a non-finite value (NaN / ±Infinity) throws a `RangeError` (fail-fast — no silent substitution). |
|
|
948
951
|
| `enableFillHandle` | `boolean` | Default `true`. Fill writes through `applyEdits` — disable for read-only adapters. |
|
|
949
|
-
| `onSelectionChange` | `(selection: SelectionState) => void` | Fires on confirmed changes only — never on mount, and never mid-drag with one documented exception: the header subtract reservation converts to a real press on the first movement that both really changes the pointer coordinates and lands on a different header index (in-index jitter and synthetic same-position moves keep the reservation), firing the deferred press replace mid-drag (total fire count matches v0.1). |
|
|
952
|
+
| `onSelectionChange` | `(selection: SelectionState, reason: SelectionChangeReason) => void` | Fires on confirmed changes only — never on mount, and never mid-drag with one documented exception: the header subtract reservation converts to a real press on the first movement that both really changes the pointer coordinates and lands on a different header index (in-index jitter and synthetic same-position moves keep the reservation), firing the deferred press replace mid-drag (total fire count matches v0.1). A change run by a handle call fires the same way (the handle `paste` moves the selection to the written block, like the keyboard paste). Beside gestures and handle calls it fires at two adapter-driven points: the reset to A1 when the adapter switches to a non-empty one (not when the selection already was the lone cell A1) and a same-adapter `rowCount` / `colCount` shrink that moved the selection; a switch or a shrink that leaves 0 rows or 0 columns fires nothing — see "Adapter identity is the sheet identity" and "A count shrink keeps the identity". v0.20.2 — the second argument names the cause: `"user"` (gestures, chords, commands and pastes, the handle-run ones included), `"setSelection"` (the handle's `setSelection`), `"sheetSwitch"` (the reset to A1) and `"countShrink"` (the shrink clamp). See *Placing the selection and following the edit session*. |
|
|
953
|
+
| `onEditSessionChange` | `(session: EditSession \| null) => void` | v0.20.2 — the new `EditSession` (`{ cell; mode: "edit" \| "replace" }`) right after a session opens (F2, a double-click, a printable key, an IME composition, `startEdit`) and `null` right after it closes: a commit (after `applyEdits` returned, before the Enter / Tab that committed moves the active cell), a cancel, the focus leaving the grid, an adapter switch, a count shrink that removed the cell, an editing Ctrl+Enter fill. A refused commit keeps the session open and reports nothing; never called on unmount. Read when it fires (no remount). See *Placing the selection and following the edit session*. |
|
|
950
954
|
| `onOperationRejected` | `(op, cellCount, reason) => void` | `op: SpreadsheetOperation` (`"copy" \| "cut" \| "delete" \| "paste" \| "fill" \| "resize" \| "format" \| "calc" \| "annotate"` — the three v0.8 names widen the callback's parameter, a 0.x-breaking change for consumers that annotated a narrower `op`), `reason: "limit" \| "bounds"` — count definitions and per-op ceilings under "Operation limits". |
|
|
951
955
|
| `onEditRejected` | `(error: unknown, rejection: EditRejection) => void` | Fires once per rejected `applyEdits`. `rejection.source` names the refused write path (`"edit"`, or the `SpreadsheetOperation` write names `"paste"` / `"fill"` / `"delete"` / `"format"` / `"calc"` / `"annotate"` — the same vocabulary as `onOperationRejected`; a cut-move is the Ctrl+V gesture and reports `"paste"` in both callbacks, and the source-side clear of a cross-sheet move reports `"paste"` too while the target write stands); for `"edit"`, `rejection.editSession` is `"kept"` (in-grid commit — the editor is still open with focus, Escape cancels) or `"discarded"` (focus left the grid — the grid closes the session as this rejection completes: once the callback returns the typed value is gone and the hidden input is re-armed without moving focus — it stays wherever the focusout left it: on the element the user chose, or still on the hidden input after a window blur; do not advise Escape). See "Editing, Undo, and rejection". |
|
|
952
956
|
| `onCopyMultiRange` | `() => void` | Notice that a multi-range copy serialized only the tail range. |
|
|
@@ -1021,6 +1025,9 @@ await ref.current?.paste({ mode: "values" }) // menu path: Promise<
|
|
|
1021
1025
|
ref.current?.getBaseFormat(cell) // the adapter's format (toolbar state)
|
|
1022
1026
|
ref.current?.getPaintedFormat(cell) // base ⊕ conditional formats (what the user sees)
|
|
1023
1027
|
ref.current?.getSelection()
|
|
1028
|
+
ref.current?.setSelection(selection, { scroll: true }) // places ranges / anchor / active; false while editing or dragging (v0.20.2)
|
|
1029
|
+
ref.current?.getEditSession() // { cell, mode } while a cell is being edited, else null (v0.20.2)
|
|
1030
|
+
ref.current?.commitEdit() // commits the open session like Enter, without moving: "committed" | "rejected" | "idle" (v0.20.2)
|
|
1024
1031
|
ref.current?.startEdit("edit") // opens the editor without the virtual-keyboard invitation
|
|
1025
1032
|
ref.current?.openPopover("note") // RangeError when the kind is disabled / its capability undeclared
|
|
1026
1033
|
ref.current?.focus({ preventScroll: true }) // focuses the hidden input and re-arms it when idle
|
|
@@ -1030,7 +1037,7 @@ ref.current?.focus({ preventScroll: true }) // focuses the hidden
|
|
|
1030
1037
|
`navigator.clipboard` is `"insecure-origin"`, a refused read `"permission-denied"`, no readable item `"empty"`, and a detected source
|
|
1031
1038
|
that fails to parse `"unreadable"` — each fires `onClipboardUnavailable` and resolves `"rejected"`. `"applied"` means the adapter was
|
|
1032
1039
|
called; `"empty"` means nothing was written (an own payload whose identity was suppressed, every cell skipped, a mode without cell
|
|
1033
|
-
aspects such as `columnWidths` — sizes may still have been applied).
|
|
1040
|
+
aspects such as `columnWidths` — sizes may still have been applied, unless `enableResizeUI` is `false`).
|
|
1034
1041
|
|
|
1035
1042
|
## Fitting a box to the grid (v0.17)
|
|
1036
1043
|
|
|
@@ -1108,6 +1115,55 @@ range's cells:
|
|
|
1108
1115
|
The demo's `/fit` route has a frame switch and a range select (every cell, or `D1:F4`), with pins (a frozen header
|
|
1109
1116
|
row, footer row and first column) and the row and column bands to see it meet the dividers and the bands.
|
|
1110
1117
|
|
|
1118
|
+
## Placing the selection and following the edit session (v0.20.2)
|
|
1119
|
+
|
|
1120
|
+
A host that keeps its own state beside the grid — a row the page selects from its URL, changes from other people that
|
|
1121
|
+
must not land on the cell being typed into, a save button or a Ctrl+S of its own — has four seams:
|
|
1122
|
+
|
|
1123
|
+
```tsx
|
|
1124
|
+
const ref = useRef<SpreadsheetHandle>(null)
|
|
1125
|
+
<Spreadsheet
|
|
1126
|
+
ref={ref}
|
|
1127
|
+
adapter={adapter}
|
|
1128
|
+
onSelectionChange={(selection, reason) => { if (reason === "user") followTheUser(selection) }}
|
|
1129
|
+
onEditSessionChange={(session) => setEditingCell(session === null ? null : session.cell)}
|
|
1130
|
+
/>
|
|
1131
|
+
ref.current?.setSelection({ ranges: [{ startRow: 8, startCol: 0, endRow: 8, endCol: 4 }], anchor: { row: 8, col: 0 }, active: { row: 8, col: 0 } }, { scroll: true })
|
|
1132
|
+
if (ref.current?.commitEdit() !== "rejected") save()
|
|
1133
|
+
```
|
|
1134
|
+
|
|
1135
|
+
- **`setSelection(selection, options?)`** places the ranges, the anchor and the active cell. It takes the shape
|
|
1136
|
+
`getSelection()` returns: at least one range, each start at most its end, the anchor inside the last range and the
|
|
1137
|
+
active cell inside some range, every bound a whole number inside the grid — anything else is a `RangeError` (a grid
|
|
1138
|
+
without rows or columns has no cell, so every placement throws there). The grid keeps a copy, so the object may be
|
|
1139
|
+
reused; a hidden row or column is a valid place. It goes through the same write path as a gesture:
|
|
1140
|
+
`onSelectionChange` fires once with `"setSelection"` (not for a selection equal to the current one), the announcement
|
|
1141
|
+
formatters run, the active cell's input message shows, and the next Arrow key moves from the placed active cell. It
|
|
1142
|
+
returns `false` and changes nothing while a cell is being edited (the session is never closed for it — the editor
|
|
1143
|
+
belongs to the cell being typed into) or a pointer drag is in flight. `{ scroll: true }` brings the active cell into
|
|
1144
|
+
view with an Arrow key's minimal scroll; without it no scroll position changes — pair it with `scrollToCell` for an
|
|
1145
|
+
alignment of your own. Focus does not move (call `focus()`), and an open popover keeps its cell.
|
|
1146
|
+
- **The `reason` of `onSelectionChange`** tells the user's moves apart from the others: `"user"` for gestures, chords,
|
|
1147
|
+
commands and pastes (also the commands and pastes the host runs through the handle for the user — `executeCommand`,
|
|
1148
|
+
`paste`), `"setSelection"` for a placement, `"sheetSwitch"` for the reset to A1 when the adapter identity changes,
|
|
1149
|
+
and `"countShrink"` for the clamp after the same adapter's `rowCount` / `colCount` shrank. A one-parameter callback
|
|
1150
|
+
keeps working.
|
|
1151
|
+
- **`onEditSessionChange(session)` and `getEditSession()`** report the in-place edit session — `{ cell, mode }` with
|
|
1152
|
+
`mode` `"edit"` (F2, a double-click, `startEdit("edit")`) or `"replace"` (a printable key, an IME composition,
|
|
1153
|
+
`startEdit("replace")`). The callback gets the session right after it opens and `null` right after it closes, whatever
|
|
1154
|
+
closes it: a commit (after `applyEdits` returned, before the Enter / Tab that committed moves the active cell), a
|
|
1155
|
+
cancel, the focus leaving the grid, an adapter switch, a count shrink that removed the cell, an editing Ctrl+Enter
|
|
1156
|
+
fill. A refused commit keeps the session open, so nothing is reported. `getEditSession()` returns the object last
|
|
1157
|
+
reported (or `null`); the callback is read when it fires and is not called on unmount.
|
|
1158
|
+
- **`commitEdit()`** commits the open session exactly as Enter does — the strict validation gate, the read-only
|
|
1159
|
+
re-check, `applyEdits` when the text changed (an unchanged text just closes the session) — but leaves the active cell
|
|
1160
|
+
where it is. `"committed"`: the session closed; `"rejected"`: refused, the session stays open with the typed text, and
|
|
1161
|
+
the refusal went through `onEditRejected` (`editSession: "kept"`), `onValidationRejected` or `onReadOnlyRejected` as
|
|
1162
|
+
an Enter's would; `"idle"`: no session was open. An IME composition in flight is confirmed first, as a press
|
|
1163
|
+
elsewhere in the grid confirms it (the hidden input blurs and takes the focus back). A save button that takes the
|
|
1164
|
+
focus has already committed through the focus leaving the grid, so it gets `"idle"`; a key listener that saves while
|
|
1165
|
+
the focus stays in the grid is what needs this call.
|
|
1166
|
+
|
|
1111
1167
|
## View geometry and zoom rules (`@aiquants/spreadsheet/view`)
|
|
1112
1168
|
|
|
1113
1169
|
`@aiquants/spreadsheet/view` publishes the grid's fixed geometry, its defaults and its zoom ladder without loading the grid
|
|
@@ -1184,7 +1240,7 @@ importers with the exact same Excel-compatible semantics the grid uses. `enumera
|
|
|
1184
1240
|
`onOperationRejected` op), and `EditRejection` (the `onEditRejected` context — see "Editing, Undo, and rejection") are exported for
|
|
1185
1241
|
consumer-side annotations.
|
|
1186
1242
|
|
|
1187
|
-
v0.8 adds the rich-cell engines as public pure functions (all React-free; `src/index.ts` exports 44 values and
|
|
1243
|
+
v0.8 adds the rich-cell engines as public pure functions (all React-free; `src/index.ts` exports 44 values and 104 types in total — every named type an exported declaration reaches is exported too, so nothing has to be extracted with `Awaited<ReturnType<>>` / `Extract<>`; `src/index.spec.ts` pins it):
|
|
1188
1244
|
|
|
1189
1245
|
- **Clip payload** — `serializeClipPayload(payload)` / `parseClipPayload(json)` (the lossless wire format `{ v: 1, rows, cols, clipId, formats, validations, cells, colWidths?, rowHeights?, wholeRows, wholeCols, conditionalFormats }`; the parser is total and returns `null` on ANY malformed input, the serializer validates the same way and throws a `RangeError`),
|
|
1190
1246
|
`detectClipSource(flavours, channel)` (`"aqsp" | "sheets" | "excel" | "html" | "tsv" | "none"` — the ADR-14 detection over `{ types, getData }`), and the types `ClipPayload` / `ClipCell` / `ClipComment` / `ClipSource` / `ClipInfo` / `ClipFlavours` / `ClipChannel` (the `detectClipSource` parameter types).
|
|
@@ -1250,7 +1306,7 @@ The `/utils` demo route exercises the v0.1 toolkit live; the `/styles` route dri
|
|
|
1250
1306
|
| Paste Special of an armed cut | Copy semantics (the cut stays armed) | Paste Special is disabled after a cut | One paste channel; the cut is still the user's intent |
|
|
1251
1307
|
| `colspan` / `rowspan` in pasted tables | Anchor cell + blank unformatted cells | Merged cells | No merge model in the package |
|
|
1252
1308
|
| Sheets compact JSON (`data-sheets-userformat` / text-style runs) | Not parsed (the CSS already carries the cell format) | — | No partial-format (run) model |
|
|
1253
|
-
| Column widths / row heights on the clipboard | Carried only by whole-column / whole-row copies, pasted by `all` / `noBorders` / `columnWidths`, never by a transposed paste
|
|
1309
|
+
| Column widths / row heights on the clipboard | Carried only by whole-column / whole-row copies (a foreign HTML table carries them when its `<col>` elements give every column a width / its `<tr>` elements give every row a height), pasted by `all` / `noBorders` / `columnWidths`, never by a transposed paste or under `enableResizeUI={false}`; sizes are **non-undoable geometry** (no `applyEdits`), and every wire / HTML / gated size is capped at 10,000 px (`MAX_TRACK_SIZE_PX`) so a hostile pasted width can never wedge the grid | Pasted for any range incl. transposed | Sizes are outside the `applyEdits` vocabulary |
|
|
1254
1310
|
| Paste Special ÷ 0 | Target untouched | `#DIV/0!` | No error-value vocabulary |
|
|
1255
1311
|
| Paste Special results | 15 significant digits, no `-0`, non-finite results leave the target; non-numeric / `TRUE` / `FALSE` source cells are skipped | Excel display precision | No binary artefacts (`0.1 + 0.2` ⇒ `0.3`) |
|
|
1256
1312
|
| Transposed paste formulas | Only fully relative references rotate; mixed / absolute references stay | Same | A mixed reference cannot rotate without moving its anchor |
|