@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/CHANGELOG.md +94 -1
- package/README.md +27 -19
- package/dist/index.cjs +8 -8
- package/dist/index.d.cts +75 -18
- package/dist/index.d.ts +75 -18
- package/dist/index.js +3592 -3564
- package/dist/styles/spreadsheet.standalone.css +1 -1
- package/package.json +6 -6
- package/src/Spreadsheet.tsx +138 -34
- package/src/clipboard/useClipboard.ts +22 -9
- package/src/commands/useCommands.ts +21 -8
- package/src/grid/GridBody.tsx +32 -3
- package/src/index.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,99 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `@aiquants/spreadsheet` are documented here.
|
|
4
4
|
|
|
5
|
+
## 0.20.1 (2026-11-14)
|
|
6
|
+
|
|
7
|
+
### Fixed
|
|
8
|
+
|
|
9
|
+
- **`enableResizeUI={false}` closes every way the user changes track sizes.** The prop removed the resize strips and the
|
|
10
|
+
unhide markers and made the keyboard resize commands unavailable, but the hide / unhide commands (`hideRows` /
|
|
11
|
+
`hideColumns` / `unhideRows` / `unhideColumns`, by default Ctrl+Alt+Digit9 / unbound / Ctrl+Shift+Digit9 /
|
|
12
|
+
Ctrl+Shift+Digit0) still hid and restored rows and columns, and a paste still wrote the column widths and row heights
|
|
13
|
+
that a whole-column / whole-row copy, or a foreign HTML table (an Excel one) sizing every column or row, carries. With
|
|
14
|
+
the prop `false` the four commands are unavailable — their chords pass through, while a cell is being edited too, and
|
|
15
|
+
`executeCommand` returns `false` without committing a session — and a paste writes the cells only. A copy still
|
|
16
|
+
carries the sizes, so a grid with the resize UI can paste them, and a `columnWidths` paste resolves `"empty"` without
|
|
17
|
+
calling the adapter. Sizes then change only through the imperative API (`resizeRow` / `resizeColumn` /
|
|
18
|
+
`autoFitColumns`), which is also the only way back for a hidden track, as the README already said. The prop stays
|
|
19
|
+
live: a render with the other value takes effect at the next command or paste.
|
|
20
|
+
|
|
21
|
+
### Changed
|
|
22
|
+
|
|
23
|
+
- **README**: "Resize, hide/unhide, and autofit" (what `enableResizeUI={false}` closes), the keymap rows of the keyboard
|
|
24
|
+
resize and the hide / unhide commands, the props table (`enableResizeUI`), the handle's `paste` outcomes (an `"empty"`
|
|
25
|
+
paste writes no sizes under `enableResizeUI={false}`) and the sizes row of "Deviations from Excel".
|
|
26
|
+
- **Specs 00, 03, 04, 05 and 08**: the same contract — the clipboard's resize seam takes `resizeTracks` as an optional
|
|
27
|
+
write capability (absent: copies carry sizes, pastes write none), and the hide / unhide commands are available only
|
|
28
|
+
while the grid hands it over.
|
|
29
|
+
|
|
30
|
+
### Documentation
|
|
31
|
+
|
|
32
|
+
- **`onSelectionChange` names every source that fires it** (README, the prop's JSDoc, spec 00): a selection change run
|
|
33
|
+
by a handle call (the handle `paste` moves the selection to the written block) fires it like a gesture, and beside
|
|
34
|
+
gestures and handle calls it fires at two adapter-driven points — the reset to A1 when the adapter switches to a
|
|
35
|
+
non-empty one (not when the selection already was the lone cell A1) and a same-adapter `rowCount` / `colCount` shrink
|
|
36
|
+
that moved the selection. A switch or a shrink that leaves 0 rows or 0 columns fires nothing.
|
|
37
|
+
- **The command counts read 75 commands, 105 table rows and 41 default chords** in the source comments, the test names
|
|
38
|
+
and specs 04, 07 and 08 — the numbers the tests assert.
|
|
39
|
+
|
|
40
|
+
### Verification
|
|
41
|
+
|
|
42
|
+
- **公開面**: 0.20.0 と同じ 144 export。DOM 属性も 0.20.0 と同じ。
|
|
43
|
+
- **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **101 ファイル 4,341 テスト** 全緑 — 0.20.0 出荷時の
|
|
44
|
+
100 ファイル 4,331 に v0.20.1 進行分 +10 (新規 `resizeUiOptOut` 7 — 既定のグリッドの対照・false の 4 コマンドとチョードと
|
|
45
|
+
命令の API・prop の描き直し・自前の全列 / 全行の貼り付け・Excel のクリップ・`columnWidths` の貼り付け・false のグリッドの
|
|
46
|
+
copy が運ぶ寸法、`useCommands` +1 (書き口の無い 4 コマンド)、`useClipboard` +1 (書き口の無いシーム)、0.20.0 節の出荷時
|
|
47
|
+
凍結ピンで `hxCensus` +1)。`tsc --noEmit` / biome 0。変異: root が `enableResizeUI` に依らず書き口を渡す形で
|
|
48
|
+
`resizeUiOptOut` の 5 件が赤 (変異で変わらない既定のグリッドの対照と copy が運ぶ寸法の 2 件は緑)。E2E は流していない —
|
|
49
|
+
true の道は書き口が同じ関数で振る舞いが変わらず、E2E の opt-out の試験は帯の DOM の有無だけを見るため。
|
|
50
|
+
- **試験の記録**: `resizeBudget` (1 万行のファンアウトの予算) は、計測の 3 回の間だけ React の act 環境の旗を外す。旗が
|
|
51
|
+
立ったままだと act の外の更新ごとに警告が組み立てられ (計 89,925 回 — 0.20.0 でも同じ数)、その費用が計測の窓に入り、
|
|
52
|
+
スイートの記録を 34 MB にしていた。負荷のもとでは vitest のワーカーの 60 秒の RPC のタイマーが切れ
|
|
53
|
+
(`Timeout calling "onTaskUpdate"`)、全件が通っても終了コードが 1 になる。直した後の警告は 2 回で、単独の認証
|
|
54
|
+
(`AQSP_BENCH_SOLO=1`) の予算 300ms は保たれ、repaint を 1 件ごとへ戻す変異は中央値 510ms で赤のまま。
|
|
55
|
+
|
|
56
|
+
## 0.20.0 (2026-11-06)
|
|
57
|
+
|
|
58
|
+
### Added
|
|
59
|
+
|
|
60
|
+
- **`scrollBarControls`** (prop, type `SpreadsheetScrollBarControls`): which controls of the grid's two scroll bars
|
|
61
|
+
answer the pointer — `showArrowButtons` (whether the bars draw their arrow buttons; without them the track runs the
|
|
62
|
+
bar's whole length), `enableThumbDrag` (whether dragging the thumb scrolls) and `enableTrackClick` (whether pressing
|
|
63
|
+
the track scrolls there). Each member reaches the vertical and the horizontal bar alike, and an absent member, or the
|
|
64
|
+
omitted prop, keeps the engine's default `true`, so a grid without the prop is unchanged. A host turns all three off
|
|
65
|
+
under a coarse pointer, where a finger drags the cells and the bars only show the position. The grid reads the three
|
|
66
|
+
members by value and hands them to its body one by one: an inline object literal is fine (a render with equal values
|
|
67
|
+
draws nothing below the grid's memo boundary), and keys outside the three are not read — the bar width
|
|
68
|
+
(`SPREADSHEET_SCROLLBAR_SIZE_PX`) and the bars' pointer-only declaration stay the grid's own, which is also what lets
|
|
69
|
+
the arrows go (the engine refuses a keyboard bar without arrows). A prop that is not an object, or a member that is
|
|
70
|
+
neither `true`, `false` nor absent (a JS host's `null`, `0` or `""`, which the engine would read as off), throws a
|
|
71
|
+
`RangeError` at render naming the member and the value. `SpreadsheetScrollBarControls` is an explicit structural
|
|
72
|
+
type; a type parity guard pins it to the engine's three `scrollBarOptions` members both ways and key for key.
|
|
73
|
+
|
|
74
|
+
### Changed
|
|
75
|
+
|
|
76
|
+
- **Breaking (0.x): `@aiquants/virtualscroll` 3.24.0 or later.** The peer range rises from `^3.22.1` to `^3.24.0`, the
|
|
77
|
+
first engine whose bars can leave their arrow buttons out (`showArrowButtons`). The same engine lets a grid whose
|
|
78
|
+
rows fit its box take a finger's horizontal swipe over the rows (`touch-action: pan-y`, vertical swipes still scroll
|
|
79
|
+
the page), so under a coarse pointer, where the bars take no presses, a short, wide grid still scrolls sideways.
|
|
80
|
+
The range also takes in virtualscroll 3.23.0, which writes its bars' colours with `light-dark()` and so needs
|
|
81
|
+
Chrome / Edge 123, Firefox 120 or Safari 17.5: an older browser drops those declarations and draws the grid's bars
|
|
82
|
+
and thumbs transparent.
|
|
83
|
+
- **README**: "Accessibility model and trade-offs" (which bar controls answer the pointer), the props table
|
|
84
|
+
(`scrollBarControls`), "Installation" (the virtualscroll floor) and `onContentSizeChange` (a box that shows every row
|
|
85
|
+
still takes horizontal swipes while the columns are wider).
|
|
86
|
+
- **Spec 06**: the publish pipeline runs the peer-floor check after the publish leak guard (`prepublishOnly`, the
|
|
87
|
+
`publish:*` scripts, the dependency section and deviation row 9) — the scripts already ran it; the document now says
|
|
88
|
+
so.
|
|
89
|
+
|
|
90
|
+
### Verification
|
|
91
|
+
|
|
92
|
+
- **公開面**: 公開面は `index.ts` の値 44 + 型 100 = 144 export (型 `SpreadsheetScrollBarControls` を追加)。DOM 属性は
|
|
93
|
+
0.19.0 と同じ。
|
|
94
|
+
- **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **100 ファイル 4,331 テスト** 全緑 — 0.19.0 出荷時の
|
|
95
|
+
99 ファイル 4,319 に v0.20 進行分 +12 (新規 `scrollBarControlsPassthrough` 11 — 省略・3 項目とも切る・1 項目ずつ・ライブの
|
|
96
|
+
差し替え (3 項目まとめてと 1 項目ずつ)・memo 境界・値の検め・型の外のキー・型パリティガード、0.19.0 節の出荷時凍結ピンで `hxCensus` +1)。
|
|
97
|
+
|
|
5
98
|
## 0.19.0 (2026-10-31)
|
|
6
99
|
|
|
7
100
|
### Fixed
|
|
@@ -956,7 +1049,7 @@ v0.8 実装計画 (以下「計画 §N」)、横断仕様は
|
|
|
956
1049
|
文字列指数シフトで行い、丸め境界 (`decimals: 1` 指定時 `"1.45"` → `"1.5%"`) と 2^53 超の整数桁を正確に保つ。
|
|
957
1050
|
2. **interned フォーマッタ**: `Intl.NumberFormat` はオプションタプル毎にモジュール Map へインターンし
|
|
958
1051
|
(JSON null 番兵キー)、**構築失敗も null でインターン** — 壊れた列の throw は組ごとに 1 回きり。
|
|
959
|
-
上限 256 到達で全消去の安全弁。1,200 セル級スライスの整形
|
|
1052
|
+
上限 256 到達で全消去の安全弁。1,200 セル級スライスの整形 \~50ms → \~2ms (約 25 倍)、autofit 2.5 万セル
|
|
960
1053
|
計測 1.45s → 32ms の実測改善。
|
|
961
1054
|
3. **負ゼロ抑止は `signDisplay:"negative"`**: ゼロへ丸まる値は全 locale で符号を出さない
|
|
962
1055
|
(`"-0"` → `"0"` — 非 ASCII 数字体系 ar-EG 等でも成立。追加整形コストゼロ)。
|
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@ deep-reach proof route.
|
|
|
6
6
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
9
|
-
- ⚡ **1M rows × 10M columns**: both axes virtualized by `VirtualGrid` (v0.4 — quantized column anchor + residual transform, so layout coordinates never approach the browser's
|
|
9
|
+
- ⚡ **1M rows × 10M columns**: both axes virtualized by `VirtualGrid` (v0.4 — quantized column anchor + residual transform, so layout coordinates never approach the browser's \~2^25 px LayoutUnit wall); DOM holds only visible cells + overscan, independent of selection size and data volume; a 10,000,000-column deep jump lands cells within ±1px
|
|
10
10
|
- 🖱️ **Excel selection semantics**: drag ranges, Shift/Ctrl extend & append, Ctrl+click/drag **subtraction** (deselect cells inside a selection), header row/column selection with Ctrl+click toggle-off, corner select-all, Ctrl/Shift+Space column/row banding, Tab/Enter cycling **across all selected ranges**, auto-scroll at viewport edges
|
|
11
11
|
- 📐 **Drag-to-resize headers, hide/unhide, autofit**: 6px boundary strips with a live guideline, drag-to-zero hides a track, 3px double-line markers restore hidden runs (including a hidden column A), double-click autofit, fan-out over full row/column selections
|
|
12
12
|
- 🖊️ **Fill handle (autofill)**: corner handle on single-range selections, bounding-box drag (single-axis bands or one-gesture diagonal L-fills) with dashed preview, Excel-compatible cyclic copy fill in one `applyEdits` transaction
|
|
@@ -55,7 +55,7 @@ deep-reach proof route.
|
|
|
55
55
|
pnpm add @aiquants/spreadsheet @aiquants/virtualscroll
|
|
56
56
|
```
|
|
57
57
|
|
|
58
|
-
`react` / `react-dom` (`^19.2`) and `@aiquants/virtualscroll` are peer dependencies (the ranges are `peerDependencies` in the published `package.json`; the code itself needs virtualscroll 3.
|
|
58
|
+
`react` / `react-dom` (`^19.2`) and `@aiquants/virtualscroll` are peer dependencies (the ranges are `peerDependencies` in the published `package.json`; the code itself needs virtualscroll 3.24.0 or later, whose bars can leave their arrow buttons out for `scrollBarControls`).
|
|
59
59
|
|
|
60
60
|
> **Browser floor**: the built-in cell display formats (v0.7) require `Intl.NumberFormat` v3
|
|
61
61
|
> (string mathematical-value input + `signDisplay: "negative"`) — **Chrome/Edge 106+, Firefox 116+,
|
|
@@ -128,16 +128,16 @@ 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.
|
|
137
137
|
|
|
138
138
|
## Editing, Undo, and rejection
|
|
139
139
|
|
|
140
|
-
The package owns no history. `Ctrl+Z` / `Ctrl+Y` (and `Ctrl+Shift+Z`) are **relayed** to `onUndoRequest` / `onRedoRequest`; apply the inverse patches to your store and bump `dataVersion`. The `/edit` route of the repository demo (`demo/src/EditApp.tsx` — source checkout only, not in the npm tarball) is the reference implementation: a `Map`-backed store with an inverse-patch undo/redo stack,
|
|
140
|
+
The package owns no history. `Ctrl+Z` / `Ctrl+Y` (and `Ctrl+Shift+Z`) are **relayed** to `onUndoRequest` / `onRedoRequest`; apply the inverse patches to your store and bump `dataVersion`. The `/edit` route of the repository demo (`demo/src/EditApp.tsx` — source checkout only, not in the npm tarball) is the reference implementation: a `Map`-backed store with an inverse-patch undo/redo stack, \~60 lines.
|
|
141
141
|
|
|
142
142
|
`applyEdits` may throw to reject an edit. Every rejection fires `onEditRejected(error, rejection)` exactly once, where `rejection` is an
|
|
143
143
|
`EditRejection` (exported) — a discriminated union naming the write path that was refused and, for an in-cell commit, what happened
|
|
@@ -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
|
|
|
@@ -464,8 +467,11 @@ away while the band is visible; with every trailing track hidden the scroll-side
|
|
|
464
467
|
`aria-colcount` count every row and column and each `role="row"` has the grid as an ancestor. The grid does not declare
|
|
465
468
|
`aria-multiselectable`: no cell carries `aria-selected`, and the live region announces the selection instead
|
|
466
469
|
(`formatSelectionAnnouncement`). The scroll bars are pointer-only (`aria-hidden`, no Tab stop): the grid owns keyboard
|
|
467
|
-
scrolling, so they duplicate it, as native scroll bars do, and they never become children of the grid.
|
|
468
|
-
|
|
470
|
+
scrolling, so they duplicate it, as native scroll bars do, and they never become children of the grid. Which of their
|
|
471
|
+
controls answer the pointer — the arrow buttons, the thumb drag and the track press — is the host's choice through
|
|
472
|
+
`scrollBarControls` (all three by default); a host turns them off under a coarse pointer, where a finger drags the
|
|
473
|
+
cells and the bars only show the position. The column-letter and row-number bands are visual chrome outside the grid
|
|
474
|
+
(`aria-hidden`). Three props complete the structure:
|
|
469
475
|
|
|
470
476
|
- `headerRows` (default 0, at most `frozenRows`): the leading rows whose cells are column headers — `role="columnheader"`,
|
|
471
477
|
painted by the stylesheet (`--aqsp-header-row-*`), so a screen reader names the column of every cell below them.
|
|
@@ -789,11 +795,11 @@ track, and paging moves by exact viewport-height pixel geometry, so page landing
|
|
|
789
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` |
|
|
790
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 | Same | `fillSelection` |
|
|
791
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` |
|
|
792
|
-
| 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` |
|
|
793
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` |
|
|
794
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` |
|
|
795
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` |
|
|
796
|
-
| *(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` |
|
|
797
803
|
| *(unbound by default)* | General (no value format) / all four borders | — | — | `formatGeneral` / `bordersAll` |
|
|
798
804
|
| *(unbound by default)* | Paste Special modes through the menu path (`handle.paste`) | — | — | `pasteFormats` / `pasteFormulas` / `pasteAdd` / `pasteSubtract` / `pasteMultiply` / `pasteDivide` |
|
|
799
805
|
| *(unbound by default)* | Self-calc over the selection (exact decimal shift, formulas wrapped `=(…)*100`; non-numeric cells untouched) | — | — | `multiplyBy100` / `multiplyBy1000` / `divideBy100` / `divideBy1000` / `signReversal` |
|
|
@@ -937,13 +943,13 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
|
|
|
937
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. |
|
|
938
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. |
|
|
939
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". |
|
|
940
|
-
| `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. |
|
|
941
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. |
|
|
942
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*. |
|
|
943
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. |
|
|
944
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). |
|
|
945
951
|
| `enableFillHandle` | `boolean` | Default `true`. Fill writes through `applyEdits` — disable for read-only adapters. |
|
|
946
|
-
| `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) => 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". |
|
|
947
953
|
| `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". |
|
|
948
954
|
| `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". |
|
|
949
955
|
| `onCopyMultiRange` | `() => void` | Notice that a multi-range copy serialized only the tail range. |
|
|
@@ -974,6 +980,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
|
|
|
974
980
|
| `readOnly` | `boolean` | v0.16 — the whole grid is read-only (default false): `aria-readonly="true"` on the grid and the hidden input; every cell is read-only whatever the adapter's `isCellReadOnly` says, so writes are refused through `onReadOnlyRejected` and the cell announcement's `readOnly` is true. Selection, copy, scrolling, zoom, resizing, hiding and highlighting stay available, and toggling it keeps the selection |
|
|
975
981
|
| `labelledBy` | `string` | v0.16 — the id of the element that names the grid: `aria-labelledby` on the `role="grid"` element and on the root, instead of the built-in `labels.rootAriaLabel` (which names both when it is omitted). A non-empty id without whitespace; anything else is a `RangeError` during render |
|
|
976
982
|
| `tapScrollCircleOptions` | `ScrollBarTapCircleOptions` | v0.10 — position / enable-disable tuning of the touch tap-scroll circle; an engine-validated pass-through onto VirtualGrid’s `scrollBarOptions.tapScrollCircleOptions` (the engine’s `resolveTapScrollCircleOptions` is the validation SSOT — no second layer here). LIVE prop. |
|
|
983
|
+
| `scrollBarControls` | `SpreadsheetScrollBarControls` = `{ showArrowButtons?; enableThumbDrag?; enableTrackClick? }` (each `boolean`) | v0.20 — which controls of both scroll bars answer the pointer: `showArrowButtons` (whether the bars draw their arrow buttons; without them the track runs the bar's whole length), `enableThumbDrag` (whether dragging the thumb scrolls) and `enableTrackClick` (whether pressing the track scrolls there). Each member reaches the vertical and the horizontal bar alike; an absent member, or the omitted prop, keeps the engine's default `true`. The grid reads the three members by value, so an inline object is fine (equal values redraw nothing below the grid's memo boundary) and other keys are not read: the bar width (`SPREADSHEET_SCROLLBAR_SIZE_PX`) and the bars' pointer-only declaration stay the grid's own. Turn all three off under a coarse pointer, where a finger drags the cells instead. A prop that is not an object, or a member that is neither `true`, `false` nor absent (a JS host's `null`, `0` or `""`, which the engine would read as off), throws a `RangeError` at render. Needs `@aiquants/virtualscroll` 3.24.0 or later. LIVE prop. |
|
|
977
984
|
| `overscanRows` / `overscanCols` | `number` | v0.11 — per-axis overscan pass-through onto VirtualGrid’s `overscanRows` / `overscanCols` (undefined ⇒ the engine default 3). This slack is what absorbs the engine’s one-frame rendering-window lag during fast scrolling — raise it when fast flicks show blank bands. Overscan counts rows / columns (hidden 0-size tracks consume slots too), so the px slack per edge is overscan × row height / column width only where tracks are uniform and visible. The engine does not validate overscan (a negative value silently shrinks the rendering window), so THIS surface fail-fasts: a non-integer, negative or non-finite value throws a RangeError at render. Cost multiplies across the two axes, and the engine truncates rather than bounds: a window beyond its per-axis row budget or its total cell cap keeps the leading side and drops the trailing side — the row-budget case has no callback (the engine only logs a warning), the cell-cap case reports dropped columns through `onRenderTruncated`. Keep overscan to the slack you need (hundreds per side approach the budget on tall viewports). LIVE props. |
|
|
978
985
|
| `background` | `ReactNode` | v0.11 — background layer rendered behind the scroll-band rows inside the engine content element (the VirtualGrid `background` pass-through). VIEWPORT-PINNED: the engine translates only its row wrapper, so this layer does not follow the scroll offset — periodic row ruling placed here slides against the real rows. Suited to a static “content still arriving” texture for the overscan-exhausted band, not to row-aligned gridlines. It spans the full width of the scroll rows (the frozen-column region included — frozen columns live inside the scroll rows) but not the frozen row bands. **Identity-stable** like `renderCell`: an inline element pierces the GridBody memo boundary on every host re-render — hoist it or `useMemo` it. LIVE prop. |
|
|
979
986
|
| `onRenderTruncated` | `(info: { renderedCells: number; droppedCols: number }) => void` | v0.12 — pass-through of the VirtualGrid truncation signal: fires when the engine drops trailing columns to stay under its total cell cap (`MAX_RENDERED_CELLS`); truncation is never silent in the engine, and an oversized `overscanCols` × row span is the typical cause. Undefined ⇒ no callback. |
|
|
@@ -1026,7 +1033,7 @@ ref.current?.focus({ preventScroll: true }) // focuses the hidden
|
|
|
1026
1033
|
`navigator.clipboard` is `"insecure-origin"`, a refused read `"permission-denied"`, no readable item `"empty"`, and a detected source
|
|
1027
1034
|
that fails to parse `"unreadable"` — each fires `onClipboardUnavailable` and resolves `"rejected"`. `"applied"` means the adapter was
|
|
1028
1035
|
called; `"empty"` means nothing was written (an own payload whose identity was suppressed, every cell skipped, a mode without cell
|
|
1029
|
-
aspects such as `columnWidths` — sizes may still have been applied).
|
|
1036
|
+
aspects such as `columnWidths` — sizes may still have been applied, unless `enableResizeUI` is `false`).
|
|
1030
1037
|
|
|
1031
1038
|
## Fitting a box to the grid (v0.17)
|
|
1032
1039
|
|
|
@@ -1044,7 +1051,8 @@ ref.current?.autoFitColumns(Array.from({ length: colCount }, (_, col) => col))
|
|
|
1044
1051
|
Round the height up and keep a pixel of slack: if a rounding leaves the rows a fraction taller than the box, the row
|
|
1045
1052
|
list becomes scrollable and the grid takes vertical finger swipes for itself (`touch-action: none`), so a box taller
|
|
1046
1053
|
than the window would trap a touch reader. A box that shows every row lets a vertical wheel and a vertical swipe over
|
|
1047
|
-
the grid scroll the page instead.
|
|
1054
|
+
the grid scroll the page instead. While the columns are wider than the box, the grid still takes horizontal swipes
|
|
1055
|
+
over its rows (`touch-action: pan-y`), and a vertical one still scrolls the page.
|
|
1048
1056
|
- **`autoFitColumns(columns)`** fits the listed columns to the widest text of **all** their rows (header rows
|
|
1049
1057
|
included) — Alt+Shift+= fits the active column over the rows in view — with the same painted fonts, 9 px padding and
|
|
1050
1058
|
10,000 px bound. A hidden or empty column keeps its width; more measured cells than `maxOperationCells` are refused
|
|
@@ -1179,7 +1187,7 @@ importers with the exact same Excel-compatible semantics the grid uses. `enumera
|
|
|
1179
1187
|
`onOperationRejected` op), and `EditRejection` (the `onEditRejected` context — see "Editing, Undo, and rejection") are exported for
|
|
1180
1188
|
consumer-side annotations.
|
|
1181
1189
|
|
|
1182
|
-
v0.8 adds the rich-cell engines as public pure functions (all React-free; `src/index.ts` exports 44 values and
|
|
1190
|
+
v0.8 adds the rich-cell engines as public pure functions (all React-free; `src/index.ts` exports 44 values and 100 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):
|
|
1183
1191
|
|
|
1184
1192
|
- **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`),
|
|
1185
1193
|
`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).
|
|
@@ -1245,7 +1253,7 @@ The `/utils` demo route exercises the v0.1 toolkit live; the `/styles` route dri
|
|
|
1245
1253
|
| 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 |
|
|
1246
1254
|
| `colspan` / `rowspan` in pasted tables | Anchor cell + blank unformatted cells | Merged cells | No merge model in the package |
|
|
1247
1255
|
| Sheets compact JSON (`data-sheets-userformat` / text-style runs) | Not parsed (the CSS already carries the cell format) | — | No partial-format (run) model |
|
|
1248
|
-
| 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
|
|
1256
|
+
| 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 |
|
|
1249
1257
|
| Paste Special ÷ 0 | Target untouched | `#DIV/0!` | No error-value vocabulary |
|
|
1250
1258
|
| 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`) |
|
|
1251
1259
|
| Transposed paste formulas | Only fully relative references rotate; mixed / absolute references stay | Same | A mixed reference cannot rotate without moving its anchor |
|