@aiquants/spreadsheet 0.18.1 → 0.20.0

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 CHANGED
@@ -2,6 +2,106 @@
2
2
 
3
3
  All notable changes to `@aiquants/spreadsheet` are documented here.
4
4
 
5
+ ## 0.20.0 (2026-11-06)
6
+
7
+ ### Added
8
+
9
+ - **`scrollBarControls`** (prop, type `SpreadsheetScrollBarControls`): which controls of the grid's two scroll bars
10
+ answer the pointer — `showArrowButtons` (whether the bars draw their arrow buttons; without them the track runs the
11
+ bar's whole length), `enableThumbDrag` (whether dragging the thumb scrolls) and `enableTrackClick` (whether pressing
12
+ the track scrolls there). Each member reaches the vertical and the horizontal bar alike, and an absent member, or the
13
+ omitted prop, keeps the engine's default `true`, so a grid without the prop is unchanged. A host turns all three off
14
+ under a coarse pointer, where a finger drags the cells and the bars only show the position. The grid reads the three
15
+ members by value and hands them to its body one by one: an inline object literal is fine (a render with equal values
16
+ draws nothing below the grid's memo boundary), and keys outside the three are not read — the bar width
17
+ (`SPREADSHEET_SCROLLBAR_SIZE_PX`) and the bars' pointer-only declaration stay the grid's own, which is also what lets
18
+ the arrows go (the engine refuses a keyboard bar without arrows). A prop that is not an object, or a member that is
19
+ neither `true`, `false` nor absent (a JS host's `null`, `0` or `""`, which the engine would read as off), throws a
20
+ `RangeError` at render naming the member and the value. `SpreadsheetScrollBarControls` is an explicit structural
21
+ type; a type parity guard pins it to the engine's three `scrollBarOptions` members both ways and key for key.
22
+
23
+ ### Changed
24
+
25
+ - **Breaking (0.x): `@aiquants/virtualscroll` 3.24.0 or later.** The peer range rises from `^3.22.1` to `^3.24.0`, the
26
+ first engine whose bars can leave their arrow buttons out (`showArrowButtons`). The same engine lets a grid whose
27
+ rows fit its box take a finger's horizontal swipe over the rows (`touch-action: pan-y`, vertical swipes still scroll
28
+ the page), so under a coarse pointer, where the bars take no presses, a short, wide grid still scrolls sideways.
29
+ The range also takes in virtualscroll 3.23.0, which writes its bars' colours with `light-dark()` and so needs
30
+ Chrome / Edge 123, Firefox 120 or Safari 17.5: an older browser drops those declarations and draws the grid's bars
31
+ and thumbs transparent.
32
+ - **README**: "Accessibility model and trade-offs" (which bar controls answer the pointer), the props table
33
+ (`scrollBarControls`), "Installation" (the virtualscroll floor) and `onContentSizeChange` (a box that shows every row
34
+ still takes horizontal swipes while the columns are wider).
35
+ - **Spec 06**: the publish pipeline runs the peer-floor check after the publish leak guard (`prepublishOnly`, the
36
+ `publish:*` scripts, the dependency section and deviation row 9) — the scripts already ran it; the document now says
37
+ so.
38
+
39
+ ### Verification
40
+
41
+ - **公開面**: 公開面は `index.ts` の値 44 + 型 100 = 144 export (型 `SpreadsheetScrollBarControls` を追加)。DOM 属性は
42
+ 0.19.0 と同じ。
43
+ - **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **100 ファイル 4,331 テスト** 全緑 — 0.19.0 出荷時の
44
+ 99 ファイル 4,319 に v0.20 進行分 +12 (新規 `scrollBarControlsPassthrough` 11 — 省略・3 項目とも切る・1 項目ずつ・ライブの
45
+ 差し替え (3 項目まとめてと 1 項目ずつ)・memo 境界・値の検め・型の外のキー・型パリティガード、0.19.0 節の出荷時凍結ピンで `hxCensus` +1)。
46
+
47
+ ## 0.19.0 (2026-10-31)
48
+
49
+ ### Fixed
50
+
51
+ - **Ctrl+D / Ctrl+R pressed while a cell is being edited no longer reach the browser.** A command with no editing-column
52
+ row (`fillDown`, `fillRight`, `insertLink`, …) never runs during an edit session, and its chord used to pass through
53
+ untouched: Ctrl+D bookmarked the page and Ctrl+R reloaded it, losing the typed value (Cmd+D / Cmd+R on macOS alike).
54
+ The editing column now consumes such a chord when it types nothing in a text field — no Alt, and a function key or
55
+ Ctrl / Cmd with a letter, digit, punctuation or numpad key; by default Ctrl+D, Ctrl+R, Ctrl+K, Shift+F2,
56
+ Ctrl+Backslash / Ctrl+IntlYen / Ctrl+IntlRo and Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0. The keydown is
57
+ `preventDefault`ed, nothing runs, and the session and its typed value are left as they were. A chord with Alt (macOS
58
+ Option characters and word moves, AltGr characters) or with a text-editing key (arrows, Home / End, the page keys,
59
+ Enter, Tab, Space, Escape, Delete, Backspace, Insert, the context-menu key) keeps its meaning in the text and passes
60
+ through as before, and so do an unavailable command's chord and a chord unbound through `shortcuts`. The grid reads
61
+ Control and Cmd alike, so on macOS Control+D and Control+K (a text field's forward delete and delete to the end of the
62
+ line) are consumed as well.
63
+
64
+ ### Added
65
+
66
+ - **`onCommandBlockedWhileEditing({ command, chord })`**: the new optional prop is called each time the editing column
67
+ consumes such a chord (`chord` is the canonical chord, Cmd spelled `Ctrl`). To commit and run the command instead,
68
+ call `handle.executeCommand(command)` from it — it commits the session first, as it does from anywhere. When the prop
69
+ is omitted, the chord is still consumed.
70
+
71
+ ### Changed
72
+
73
+ - **Breaking (0.x): a read-only refusal of a fill names its gesture and carries its geometry.** In `ReadOnlyRejection`,
74
+ `{ kind: "operation", op: "fill" }` is now an arm of its own with three more required members: `gesture`
75
+ (`"fillDown"` / `"fillRight"` / `"fillSelection"` / `"fillHandle"`), `targets` (the rectangles the fill would write —
76
+ the cells the read-only check walks) and `sources` (the rectangles it copies from: for Ctrl+D / Ctrl+R each range's
77
+ first row / column, or the neighbouring row / column of a one-row / one-column range; for an idle Ctrl+Enter the
78
+ active cell; for a Ctrl+Enter that commits an edit session `[]`, since it copies the session's text; for the fill
79
+ handle the dragged block). A host can now tell which cells refused a fill without re-deriving the fill rules. Code
80
+ that builds a fill refusal itself (tests, mocks) has to add the three members; code that only reads `kind` / `op` /
81
+ `cellCount` compiles as before.
82
+ - **The `cellCount` of a fill refusal is the targets' total area.** For an idle Ctrl+Enter over overlapping ranges, a cell
83
+ covered by two ranges now counts once per range — the overlap-naive count the other producers and the limit channel
84
+ already use — instead of once.
85
+ - **README**: the keymap's editing columns, "Command shortcuts" (what a command chord does while a cell is being edited,
86
+ and that a chord unbound through `shortcuts` passes through while idle and while editing alike — unbinding `fillDown`
87
+ hands Ctrl+D back to the browser's bookmark) and the props table (`onCommandBlockedWhileEditing`, the fill refusal of
88
+ `onReadOnlyRejected`).
89
+
90
+ ### Verification
91
+
92
+ - **公開面**: 0.18.1 と同じ 143 export (新しい型は無い — 新しい prop の引数はインラインの型、fill の腕は既存の
93
+ `ReadOnlyRejection` の中)。DOM 属性も 0.18.1 と同じ。
94
+ - **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **99 ファイル 4,319 テスト** 全緑 — 0.18.1 出荷時の
95
+ 99 ファイル 4,285 に v0.19 進行分 +34 (`shortcuts` +11 — `resolveBinding` 4・`isConsumedWhileEditing` 7、`useGridKeyboard`
96
+ +9 — 編集列の消費と通知・素通しの境界、`cellCoord` +5 — `subtractCell`、`useCommands` +4 — 読み取り専用の fill の拒否の幾何、
97
+ `commands` +2 — 旧「ネイティブ素通し」1 件を消費・通知からの実行・未束縛の 3 件へ、`dataAdapter` +2 — fill の腕の型ガード、
98
+ 0.18.1 節の出荷時凍結ピンで `hxCensus` +1)。`tsc --noEmit` / biome 0。E2E は `editing` +1 (編集中の Ctrl+D / Ctrl+R と
99
+ Cmd+D / Cmd+R が `defaultPrevented`・ページは再読込されず・入力値はそのまま) で全 26 ファイル 299 テストになり、変更が届く
100
+ `editing` / `readonly` の 36 テストが全緑 (デモのビルドの型検査を含む)。0.18.1 の実装へ戻した確認: 単体は 9 ファイルで 34 件が
101
+ 赤 (新しい振る舞いのテストは全て。Alt を含むチョード・文字の編集キー・未束縛のチョードの素通しを守るピンは両方で緑)、E2E は
102
+ 4 チョードとも `prevented: false` で赤、デモの拒否文言の spec は 0.18.1 の型で tsc が赤。素通しのピンの変異: 消費の条件から
103
+ `isConsumedWhileEditing` を外すと単体 3 件が赤。
104
+
5
105
  ## 0.18.1 (2026-10-28)
6
106
 
7
107
  ### Fixed
@@ -898,7 +998,7 @@ v0.8 実装計画 (以下「計画 §N」)、横断仕様は
898
998
  文字列指数シフトで行い、丸め境界 (`decimals: 1` 指定時 `"1.45"` → `"1.5%"`) と 2^53 超の整数桁を正確に保つ。
899
999
  2. **interned フォーマッタ**: `Intl.NumberFormat` はオプションタプル毎にモジュール Map へインターンし
900
1000
  (JSON null 番兵キー)、**構築失敗も null でインターン** — 壊れた列の throw は組ごとに 1 回きり。
901
- 上限 256 到達で全消去の安全弁。1,200 セル級スライスの整形 ~50ms → ~2ms (約 25 倍)、autofit 2.5 万セル
1001
+ 上限 256 到達で全消去の安全弁。1,200 セル級スライスの整形 \~50ms → \~2ms (約 25 倍)、autofit 2.5 万セル
902
1002
  計測 1.45s → 32ms の実測改善。
903
1003
  3. **負ゼロ抑止は `signDisplay:"negative"`**: ゼロへ丸まる値は全 locale で符号を出さない
904
1004
  (`"-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 ~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
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.7.0 or later, whose label catalogs back the `locale` prop).
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+,
@@ -137,7 +137,7 @@ The host element must have a resolvable height — the grid fills its parent.
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, ~60 lines.
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
@@ -464,8 +464,11 @@ away while the band is visible; with every trailing track hidden the scroll-side
464
464
  `aria-colcount` count every row and column and each `role="row"` has the grid as an ancestor. The grid does not declare
465
465
  `aria-multiselectable`: no cell carries `aria-selected`, and the live region announces the selection instead
466
466
  (`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. The column-letter
468
- and row-number bands are visual chrome outside the grid (`aria-hidden`). Three props complete the structure:
467
+ scrolling, so they duplicate it, as native scroll bars do, and they never become children of the grid. Which of their
468
+ controls answer the pointer — the arrow buttons, the thumb drag and the track press — is the host's choice through
469
+ `scrollBarControls` (all three by default); a host turns them off under a coarse pointer, where a finger drags the
470
+ cells and the bars only show the position. The column-letter and row-number bands are visual chrome outside the grid
471
+ (`aria-hidden`). Three props complete the structure:
469
472
 
470
473
  - `headerRows` (default 0, at most `frozenRows`): the leading rows whose cells are column headers — `role="columnheader"`,
471
474
  painted by the stylesheet (`--aqsp-header-row-*`), so a screen reader names the column of every cell below them.
@@ -777,19 +780,19 @@ track, and paging moves by exact viewport-height pixel geometry, so page landing
777
780
  | Ctrl+Z / Y / Shift+Z | Relay to undo/redo callbacks | Native textarea undo | Native textarea undo | — |
778
781
  | Shift+F10 / ContextMenu | Context-menu callback | — | — | — |
779
782
  | Ctrl+B / Ctrl+I / Ctrl+U / Alt+Shift+Digit5 | Toggle on the selection (the active cell's state decides: on → clear, off → set) | Toggle on the session cell (editor repainted) | Same | `bold` / `italic` / `underline` / `strikethrough` |
780
- | Ctrl+Backslash / Ctrl+IntlYen / Ctrl+IntlRo | Clear every format key of the selection | Native | Native | `clearFormatting` |
783
+ | Ctrl+Backslash / Ctrl+IntlYen / Ctrl+IntlRo | Clear every format key of the selection | Consumed, not run (`onCommandBlockedWhileEditing`) | Same | `clearFormatting` |
781
784
  | Ctrl+Shift+L / Ctrl+Shift+E / Ctrl+Shift+R | Align left / center / right | Session cell | Same | `alignLeft` / `alignCenter` / `alignRight` |
782
785
  | Ctrl+Shift+Digit1 … Ctrl+Shift+Digit6 | Number (2 decimals, grouping) / time (`HH:mm:ss`) / date / currency (needs the `formats` prop) / percent / scientific value format | Session cell | Same | `formatNumber` / `formatTime` / `formatDate` / `formatCurrency` / `formatPercent` / `formatScientific` |
783
786
  | Alt+Shift+Digit7 / Alt+Shift+Digit6 | Outer borders of each range (inner borders kept) / clear borders | Native | Native | `bordersOuter` / `bordersClear` |
784
787
  | Alt+Shift+Digit1 … Alt+Shift+Digit4 | Top / right / bottom / left edge of each range (thin, `#000000`; other cells' borders kept) | Native | Native | `borderTop` / `borderRight` / `borderBottom` / `borderLeft` |
785
- | Ctrl+K | Link popover on the active cell | Native | Native | `insertLink` |
786
- | Shift+F2 | Note popover on the active cell | Native | Native | `insertNote` |
788
+ | Ctrl+K | Link popover on the active cell | Consumed, not run (`onCommandBlockedWhileEditing`) | Same | `insertLink` |
789
+ | Shift+F2 | Note popover on the active cell | Consumed, not run (`onCommandBlockedWhileEditing`) | Same | `insertNote` |
787
790
  | Ctrl+Alt+M | Comment thread popover on the active cell | Native | Native | `insertComment` |
788
791
  | Alt+ArrowDown | Validation list picker (cells with a `list` rule) | Native | Native | `openValidationList` |
789
- | 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) | Native | Native | `fillDown` / `fillRight` |
792
+ | 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
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` |
791
794
  | 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) | Native | Native | `hideRows` / `unhideRows` / `unhideColumns` |
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` |
793
796
  | 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
797
  | 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
798
  | 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` |
@@ -808,10 +811,28 @@ Rows with a **Command** are rebindable through the `shortcuts` prop (except `pas
808
811
  `handle.executeCommand(command)`; every command exists only while its capability is declared (`getCellFormat` for formats /
809
812
  borders / colours, `getCellNote` / `getCellComments` / `getCellHyperlink` / `getCellValidation` for the popover commands, the
810
813
  `formats` prop for `formatCurrency`, `getCellFormula` for `pasteFormulas`) — an unavailable command's chord passes through
811
- untouched and `executeCommand` returns `false`. The editing columns consult only the 16 **editing-column commands**
814
+ untouched and `executeCommand` returns `false`. The editing columns run only the 16 **editing-column commands**
812
815
  (`bold` / `italic` / `underline` / `strikethrough` / `alignLeft` / `alignCenter` / `alignRight` / `formatNumber` / `formatTime` /
813
- `formatDate` / `formatCurrency` / `formatPercent` / `formatScientific` / `fillSelection` / `insertDate` / `insertTime`); any other
814
- command chord pressed while editing is native. The exported `DEFAULT_SHORTCUTS` (`{ [command]: readonly string[] }`, `[]` =
816
+ `formatDate` / `formatCurrency` / `formatPercent` / `formatScientific` / `fillSelection` / `insertDate` / `insertTime`). The
817
+ chord of any other available command never runs while a cell is being edited, and what happens to it depends on whether it
818
+ types anything in a text field:
819
+
820
+ - **No Alt, and a function key or Ctrl / Cmd with a letter, digit, punctuation or numpad key** (by default `Ctrl+D`, `Ctrl+R`,
821
+ `Ctrl+K`, `Shift+F2`, `Ctrl+Backslash` / `Ctrl+IntlYen` / `Ctrl+IntlRo`, `Ctrl+Shift+Digit9` / `Ctrl+Shift+Digit0`): the chord
822
+ types nothing, so the grid consumes it (`preventDefault` — the browser's own shortcut, such as bookmarking on Ctrl+D or
823
+ reloading on Ctrl+R, which would lose the typed value, never fires), leaves the session and its value untouched and calls
824
+ `onCommandBlockedWhileEditing({ command, chord })` (`chord` is the canonical chord, Cmd spelled `Ctrl`). To commit and run the
825
+ command instead, call `handle.executeCommand(command)` from that callback — it commits the session first, exactly as the
826
+ imperative call does from anywhere. On macOS the Control key counts as Ctrl like Cmd does, so Control+D and Control+K, a text
827
+ field's forward-delete and kill-line keys, are consumed as well.
828
+ - **Alt, or a text-editing key** (arrows, Home / End, the page keys, Enter, Tab, Space, Escape, Delete, Backspace, Insert, the
829
+ context-menu key; by default `Ctrl+Alt+M`, `Ctrl+Alt+Digit9`, `Ctrl+Alt+V`, the Alt+Shift border and resize rows,
830
+ `Alt+ArrowDown`): the chord keeps its meaning in the text — macOS Option characters and word moves, AltGr characters, caret
831
+ moves — and passes through untouched. Shift with a character key types that character.
832
+
833
+ An unavailable command's chord and a chord unbound through `shortcuts` are not rows of either column: the keydown passes
834
+ through untouched while idle and while editing alike (unbinding `fillDown` hands Ctrl+D back to the browser's bookmark). To keep
835
+ such a chord inert, call `preventDefault` on it in a keydown listener of your own. The exported `DEFAULT_SHORTCUTS` (`{ [command]: readonly string[] }`, `[]` =
815
836
  unbound: 39 commands bound over 41 chords, 36 unbound) and `SPREADSHEET_RESERVED_SHORTCUTS` (the 63 exact chords of the
816
837
  non-rebindable built-in rows consulted while idle) are derived from the same `BUILTIN_ROWS` table.
817
838
 
@@ -937,6 +958,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
937
958
  | `labels` | `SpreadsheetLabelOverrides` (any subset of the `SpreadsheetLabels` keys) | v0.8 — replaces the `sinkAriaLabel` / `rootAriaLabel` props (folded in) and names every UI chrome string: the engine keys shared with `@aiquants/virtualscroll` (every entry of the installed engine's `VIRTUAL_SCROLL_LABEL_KEYS`, such as `scrollUp`, `scrollDown`, `scrollToTop`, `noItems` — they reach the grid scrollbars and the empty state) and the 21 package keys (`sinkAriaLabel`, `rootAriaLabel`, `noteTitle`, `noteSave`, `noteEscapeHint`, `noteRejectedHint`, `noteViewerHint` (v0.10 — the note hint in the read-only viewer mode, which never promises a save), `commentTitle`, `commentReply`, `commentPost`, `commentCount` (string or `(n) => string`), `linkTitle`, `linkTextField`, `linkUrlField`, `linkOpen`, `linkSave`, `listTitle`, `listEmpty`, `listMore` (string or `(n) => string` — the validation-list picker mounts at most 500 options and announces the hidden-match count on this row), `messageTitle`, `popoverClose`). Omitted / `undefined` keys keep the value of the `locale` catalog (`SPREADSHEET_LABEL_CATALOGS[locale]`); an unknown key (including the removed `validationRejected` / `indicatorNote` / `indicatorComment` / `indicatorInvalid`) or a blank / non-string value throws a `RangeError` during render; `sinkAriaLabel` must mention `Escape` (`RangeError` during render otherwise). |
938
959
  | `locale` | `SpreadsheetLocale` (`"en" \| "ja"`) | v0.13 — the UI chrome language, default `"en"`: selects the label catalog, the built-in validation messages (`onValidationRejected`'s `message` and the message popover) and the grid scrollbars' arrow names / empty state. Any other value (`"fr"`, `"ja-JP"`, `"EN"`, `""`, `null`) throws a `RangeError` during render, even on an empty grid — there is no language negotiation. Unrelated to `formats.locale`. See "Localization". |
939
960
  | `shortcuts` | `ShortcutOverrides` = `{ [command]?: readonly string[] \| null }` | v0.8 — rebinds command chords (array = replace the default list, `null` = unbind); validated during render with `RangeError`s (see "Command shortcuts"). Identity-stable — consulted through a ref. |
961
+ | `onCommandBlockedWhileEditing` | `(blocked: { command: SpreadsheetCommand; chord: string }) => void` | v0.19 — notice that a command chord was pressed while a cell is being edited and was consumed without running: the command has no editing-column row and the chord types nothing (no Alt; a function key, or Ctrl / Cmd with a character key), so the grid called `preventDefault` (the browser's bookmark / reload / search box never fires) and left the session and its typed value untouched. `chord` is the canonical chord (Cmd spelled `Ctrl`). Never fired for an unavailable or unbound command (its chord is not consumed) or for a chord with Alt or a text-editing key (it stays native). Call `handle.executeCommand(command)` from it to commit and run the command instead. Omit for silence — the chord is consumed either way. Read on every keydown (no remount). See "Command shortcuts". |
940
962
  | `colors` | `{ fill?: readonly string[]; font?: readonly string[] }` | v0.8 — the five `#rrggbb` slots of `fillColorCustom1..5` / `fontColorCustom1..5` (exactly 5 six-digit hex strings per axis, `RangeError` otherwise); an omitted axis uses `DEFAULT_CUSTOM_COLORS` (`#FF0000` / `#00FF00` / `#0000FF` / `#FFFF00` / `#FF00FF`, exported). |
941
963
  | `formats` | `{ currency: string; locale?: string }` | v0.8 — the host currency (ISO code) and rendering locale for `formatCurrency` and for recovering bare currency symbols (`$`, `¥`) in pasted Excel / Sheets HTML; undeclared ⇒ `formatCurrency` passes through and bare symbols are not recovered. `formats.locale` is a BCP-47 value-formatting locale (`"ja-JP"`, …) and is independent of the UI-chrome `locale` prop — changing one never changes the other. |
942
964
  | `highlight` / `defaultHighlight` / `onHighlightChange` | `HighlightState` = `{ row: boolean; column: boolean; intersection: boolean }` / same / `(h) => void` | v0.8 — active row / column / intersection highlight bands, controlled (`highlight` + `onHighlightChange`) or uncontrolled (`defaultHighlight`), the same two-phase contract as `zoom`. Default all off ⇒ zero band nodes (v0.7 DOM identity). Toggled by the `toggle*Highlight` commands. When exactly ONE family (row XOR column) is on and `intersection` is off, the cross node lights up tinted with that family's colour so the band runs unbroken through the selection (sheets-enhancer parity — with both families on the hole is kept). A whole-row / whole-column selection (row / column header press, Shift+Space / Ctrl+Space) draws no row / column bands — only the intersection — so the cross-axis band never tints the rest of the sheet. |
@@ -950,11 +972,12 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
950
972
  | `onClipboardUnavailable` | `(cause: "insecure-origin" \| "permission-denied" \| "empty" \| "unreadable") => void` | v0.8 — the menu path's refusal channel (`handle.paste`, `Ctrl+Alt+V` without a request handler, the `paste*` commands); whenever it fires the paste resolves `"rejected"`. `"unreadable"` also fires on the paste event when the detected source cannot be parsed (the package never slides to another reader). |
951
973
  | `now` | `() => number` | v0.8 — clock seam of `insertDate` / `insertTime` (declared default `Date.now`). |
952
974
  | `onPasteResolved` | `(outcome: PasteOutcome, channel: ClipChannel) => void` | v0.10 — paste-outcome summary. The menu channel mirrors `handle.paste(options)`’s resolve value 1:1 (read refusals and the write-time re-gate included); the event channel fires once per gesture that reaches the paste pipeline (incl. the image-only-clipboard `"empty"`). The drag-freeze consumption and a null `clipboardData` stay deliberately silent, and an empty grid attaches no paste listener at all (structurally unreachable). Cause-specific callbacks (`onClipboardUnavailable` / `onOperationRejected` / `onReadOnlyRejected`) fire FIRST — a `"rejected"` outcome can be the trailing summary of one of them. |
953
- | `onReadOnlyRejected` | `(rejection: ReadOnlyRejection) => void` | v0.10 — the single read-only refusal channel: fired once per refused gesture, the adapter was never called (neither an `EditRejection` nor an operation limit). The edit variant carries the cell and the required `editSession: "none" \| "kept" \| "discarded"` fate; the operation variant carries the explicit 7-literal `op` (`"cut"` has two producers — the Ctrl+X arming refusal and the move-time source re-check) and the producer’s overlap-naive `cellCount`. Never fired when `isCellReadOnly` is undeclared. |
975
+ | `onReadOnlyRejected` | `(rejection: ReadOnlyRejection) => void` | v0.10 — the single read-only refusal channel: fired once per refused gesture, the adapter was never called (neither an `EditRejection` nor an operation limit). The edit variant carries the cell and the required `editSession: "none" \| "kept" \| "discarded"` fate; the operation variant carries the explicit 7-literal `op` (`"cut"` has two producers — the Ctrl+X arming refusal and the move-time source re-check) and the producer’s overlap-naive `cellCount`. The `"fill"` operation (v0.19) also carries what was refused: `gesture` — `"fillDown"` / `"fillRight"` (Ctrl+D / Ctrl+R), `"fillSelection"` (Ctrl+Enter) or `"fillHandle"` (the fill-handle drag); `targets` — the rectangles that would have been written (`cellCount` is their summed area, overlap-naive); and `sources` — the rectangles copied from. Ctrl+D / Ctrl+R pair one source with each target in selection order (the range's first row / column, or the row above / the column to the left of a single-row / single-column range; a range with nothing to copy from is skipped); the fill handle has its one source range and one or two targets (a diagonal L-fill has two legs); idle Ctrl+Enter copies the active cell (`sources` is that cell, `targets` the selection without it); Ctrl+Enter committing an edit copies the session text, which is no cell (`sources` is `[]`, `targets` the whole selection). Never fired when `isCellReadOnly` is undeclared. |
954
976
  | `formatReadOnlyAnnouncement` | `(rejection: ReadOnlyRejection) => string` | v0.10 — opt-in live-region text for a read-only refusal (inherits the 200 ms announce debounce + rAF collapse, so autorepeat / IME refusal storms cannot spam the live region). Omit for silence (no built-in strings). |
955
977
  | `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 |
956
978
  | `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 |
957
979
  | `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. |
980
+ | `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. |
958
981
  | `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. |
959
982
  | `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. |
960
983
  | `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. |
@@ -1025,7 +1048,8 @@ ref.current?.autoFitColumns(Array.from({ length: colCount }, (_, col) => col))
1025
1048
  Round the height up and keep a pixel of slack: if a rounding leaves the rows a fraction taller than the box, the row
1026
1049
  list becomes scrollable and the grid takes vertical finger swipes for itself (`touch-action: none`), so a box taller
1027
1050
  than the window would trap a touch reader. A box that shows every row lets a vertical wheel and a vertical swipe over
1028
- the grid scroll the page instead.
1051
+ the grid scroll the page instead. While the columns are wider than the box, the grid still takes horizontal swipes
1052
+ over its rows (`touch-action: pan-y`), and a vertical one still scrolls the page.
1029
1053
  - **`autoFitColumns(columns)`** fits the listed columns to the widest text of **all** their rows (header rows
1030
1054
  included) — Alt+Shift+= fits the active column over the rows in view — with the same painted fonts, 9 px padding and
1031
1055
  10,000 px bound. A hidden or empty column keeps its width; more measured cells than `maxOperationCells` are refused
@@ -1160,7 +1184,7 @@ importers with the exact same Excel-compatible semantics the grid uses. `enumera
1160
1184
  `onOperationRejected` op), and `EditRejection` (the `onEditRejected` context — see "Editing, Undo, and rejection") are exported for
1161
1185
  consumer-side annotations.
1162
1186
 
1163
- v0.8 adds the rich-cell engines as public pure functions (all React-free; `src/index.ts` exports 44 values and 99 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):
1187
+ 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):
1164
1188
 
1165
1189
  - **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`),
1166
1190
  `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).