@aiquants/spreadsheet 0.18.0 → 0.19.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 +94 -0
- package/README.md +31 -12
- package/dist/index.cjs +8 -8
- package/dist/index.d.cts +78 -7
- package/dist/index.d.ts +78 -7
- package/dist/index.js +4006 -3985
- package/dist/styles/spreadsheet.css +1 -1
- package/dist/styles/spreadsheet.standalone.css +1 -1
- package/package.json +2 -2
- package/src/Spreadsheet.tsx +20 -0
- package/src/commands/useCommands.ts +33 -16
- package/src/keyboard/shortcuts.ts +74 -11
- package/src/keyboard/useGridKeyboard.ts +36 -11
- package/src/model/cellCoord.ts +31 -0
- package/src/model/dataAdapter.ts +53 -5
- package/src/overlay/SelectionOverlay.tsx +175 -95
- package/src/overlay/useFillHandle.ts +13 -12
- package/src/styles/spreadsheet.css +4 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,100 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `@aiquants/spreadsheet` are documented here.
|
|
4
4
|
|
|
5
|
+
## 0.19.0 (2026-10-31)
|
|
6
|
+
|
|
7
|
+
### Fixed
|
|
8
|
+
|
|
9
|
+
- **Ctrl+D / Ctrl+R pressed while a cell is being edited no longer reach the browser.** A command with no editing-column
|
|
10
|
+
row (`fillDown`, `fillRight`, `insertLink`, …) never runs during an edit session, and its chord used to pass through
|
|
11
|
+
untouched: Ctrl+D bookmarked the page and Ctrl+R reloaded it, losing the typed value (Cmd+D / Cmd+R on macOS alike).
|
|
12
|
+
The editing column now consumes such a chord when it types nothing in a text field — no Alt, and a function key or
|
|
13
|
+
Ctrl / Cmd with a letter, digit, punctuation or numpad key; by default Ctrl+D, Ctrl+R, Ctrl+K, Shift+F2,
|
|
14
|
+
Ctrl+Backslash / Ctrl+IntlYen / Ctrl+IntlRo and Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0. The keydown is
|
|
15
|
+
`preventDefault`ed, nothing runs, and the session and its typed value are left as they were. A chord with Alt (macOS
|
|
16
|
+
Option characters and word moves, AltGr characters) or with a text-editing key (arrows, Home / End, the page keys,
|
|
17
|
+
Enter, Tab, Space, Escape, Delete, Backspace, Insert, the context-menu key) keeps its meaning in the text and passes
|
|
18
|
+
through as before, and so do an unavailable command's chord and a chord unbound through `shortcuts`. The grid reads
|
|
19
|
+
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
|
|
20
|
+
line) are consumed as well.
|
|
21
|
+
|
|
22
|
+
### Added
|
|
23
|
+
|
|
24
|
+
- **`onCommandBlockedWhileEditing({ command, chord })`**: the new optional prop is called each time the editing column
|
|
25
|
+
consumes such a chord (`chord` is the canonical chord, Cmd spelled `Ctrl`). To commit and run the command instead,
|
|
26
|
+
call `handle.executeCommand(command)` from it — it commits the session first, as it does from anywhere. When the prop
|
|
27
|
+
is omitted, the chord is still consumed.
|
|
28
|
+
|
|
29
|
+
### Changed
|
|
30
|
+
|
|
31
|
+
- **Breaking (0.x): a read-only refusal of a fill names its gesture and carries its geometry.** In `ReadOnlyRejection`,
|
|
32
|
+
`{ kind: "operation", op: "fill" }` is now an arm of its own with three more required members: `gesture`
|
|
33
|
+
(`"fillDown"` / `"fillRight"` / `"fillSelection"` / `"fillHandle"`), `targets` (the rectangles the fill would write —
|
|
34
|
+
the cells the read-only check walks) and `sources` (the rectangles it copies from: for Ctrl+D / Ctrl+R each range's
|
|
35
|
+
first row / column, or the neighbouring row / column of a one-row / one-column range; for an idle Ctrl+Enter the
|
|
36
|
+
active cell; for a Ctrl+Enter that commits an edit session `[]`, since it copies the session's text; for the fill
|
|
37
|
+
handle the dragged block). A host can now tell which cells refused a fill without re-deriving the fill rules. Code
|
|
38
|
+
that builds a fill refusal itself (tests, mocks) has to add the three members; code that only reads `kind` / `op` /
|
|
39
|
+
`cellCount` compiles as before.
|
|
40
|
+
- **The `cellCount` of a fill refusal is the targets' total area.** For an idle Ctrl+Enter over overlapping ranges, a cell
|
|
41
|
+
covered by two ranges now counts once per range — the overlap-naive count the other producers and the limit channel
|
|
42
|
+
already use — instead of once.
|
|
43
|
+
- **README**: the keymap's editing columns, "Command shortcuts" (what a command chord does while a cell is being edited,
|
|
44
|
+
and that a chord unbound through `shortcuts` passes through while idle and while editing alike — unbinding `fillDown`
|
|
45
|
+
hands Ctrl+D back to the browser's bookmark) and the props table (`onCommandBlockedWhileEditing`, the fill refusal of
|
|
46
|
+
`onReadOnlyRejected`).
|
|
47
|
+
|
|
48
|
+
### Verification
|
|
49
|
+
|
|
50
|
+
- **公開面**: 0.18.1 と同じ 143 export (新しい型は無い — 新しい prop の引数はインラインの型、fill の腕は既存の
|
|
51
|
+
`ReadOnlyRejection` の中)。DOM 属性も 0.18.1 と同じ。
|
|
52
|
+
- **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **99 ファイル 4,319 テスト** 全緑 — 0.18.1 出荷時の
|
|
53
|
+
99 ファイル 4,285 に v0.19 進行分 +34 (`shortcuts` +11 — `resolveBinding` 4・`isConsumedWhileEditing` 7、`useGridKeyboard`
|
|
54
|
+
+9 — 編集列の消費と通知・素通しの境界、`cellCoord` +5 — `subtractCell`、`useCommands` +4 — 読み取り専用の fill の拒否の幾何、
|
|
55
|
+
`commands` +2 — 旧「ネイティブ素通し」1 件を消費・通知からの実行・未束縛の 3 件へ、`dataAdapter` +2 — fill の腕の型ガード、
|
|
56
|
+
0.18.1 節の出荷時凍結ピンで `hxCensus` +1)。`tsc --noEmit` / biome 0。E2E は `editing` +1 (編集中の Ctrl+D / Ctrl+R と
|
|
57
|
+
Cmd+D / Cmd+R が `defaultPrevented`・ページは再読込されず・入力値はそのまま) で全 26 ファイル 299 テストになり、変更が届く
|
|
58
|
+
`editing` / `readonly` の 36 テストが全緑 (デモのビルドの型検査を含む)。0.18.1 の実装へ戻した確認: 単体は 9 ファイルで 34 件が
|
|
59
|
+
赤 (新しい振る舞いのテストは全て。Alt を含むチョード・文字の編集キー・未束縛のチョードの素通しを守るピンは両方で緑)、E2E は
|
|
60
|
+
4 チョードとも `prevented: false` で赤、デモの拒否文言の spec は 0.18.1 の型で tsc が赤。素通しのピンの変異: 消費の条件から
|
|
61
|
+
`isConsumedWhileEditing` を外すと単体 3 件が赤。
|
|
62
|
+
|
|
63
|
+
## 0.18.1 (2026-10-28)
|
|
64
|
+
|
|
65
|
+
### Fixed
|
|
66
|
+
|
|
67
|
+
- **A range scrolled out under a frozen row leaves no piece of its frame behind.** A pane placed an open near side (one
|
|
68
|
+
the range continues past, into the frozen pane before it) at the quadrant's start and sized a closed far side from
|
|
69
|
+
there, so once the range's far edge scrolled above the quadrant's start the size came out negative. CSS drops a
|
|
70
|
+
negative size and the frame kept its last one: under a frozen header row, the rows of a framed range left a U-shaped
|
|
71
|
+
stub of the frame below the header until their edge passed a whole screen. An open near side now sits at the
|
|
72
|
+
margin's edge, a screen before the quadrant's start, where its missing line is out of view, so a closed far side's
|
|
73
|
+
size is never negative and the frame ends where the range does, outside the quadrant too.
|
|
74
|
+
- **A frame that starts past the cells' far edge stays out of view in a right-to-left page.** With its near side beyond
|
|
75
|
+
the quadrant's far edge and its far side open, the frame is over-constrained (`left`, `right: 0` and an auto width
|
|
76
|
+
that would be negative), and CSS drops `left` when the containing block is right-to-left: in a `dir="rtl"` page the
|
|
77
|
+
frame's left line showed at the quadrant's right edge. The overlay quadrants now keep a left-to-right direction —
|
|
78
|
+
their marks are all placed in physical px — so `right` is the value dropped and the frame stays outside its quadrant.
|
|
79
|
+
The text sink sits outside the quadrants and keeps the page's direction.
|
|
80
|
+
|
|
81
|
+
### Changed
|
|
82
|
+
|
|
83
|
+
- **A repaint that moves no frame allocates nothing for it.** The range cut to the grid is resolved again only when the
|
|
84
|
+
range or the grid's counts change, each quadrant resolves its frame into spans it keeps, and the CSS is built only for
|
|
85
|
+
an axis whose span changed; the quadrants' cell extents are kept as CSS strings, rebuilt with the split cache only.
|
|
86
|
+
- **Demo**: `/fit` gains a range select for the frame — every cell, or `D1:F4`, the first four rows of the last three
|
|
87
|
+
columns, which scrolls out under the frozen header row and, in a narrow box, starts past the cells' far edge.
|
|
88
|
+
|
|
89
|
+
### Verification
|
|
90
|
+
|
|
91
|
+
- **公開面**: 0.18.0 と同じ 143 export。DOM 属性も 0.18.0 と同じ。
|
|
92
|
+
- **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **99 ファイル 4,285 テスト** 全緑 — 0.18.0 出荷時の
|
|
93
|
+
99 ファイル 4,281 に v0.18.1 進行分 +4 (`frame` +3 — 凍結の行の下へ外れた範囲の軸の解き方・その範囲が古い箱を残さない
|
|
94
|
+
スクロール・象限の左から右の向きの CSS 契約、0.18.0 節の出荷時凍結ピンで `hxCensus` +1)。`tsc --noEmit` / biome 0。
|
|
95
|
+
E2E は `frame` +2 (見出しの行の下へ外れた範囲・右から左のページ) を加えた全 26 ファイル 298 テスト全緑 (2.7 分)。変異:
|
|
96
|
+
開いた近い辺を象限の端 (0) に置く元の形で単体 3 件と E2E の見出しの行の下の 1 件、象限の `direction: ltr` を外す形で E2E の
|
|
97
|
+
右から左のページの 1 件がどれも赤。
|
|
98
|
+
|
|
5
99
|
## 0.18.0 (2026-10-28)
|
|
6
100
|
|
|
7
101
|
### Added
|
package/README.md
CHANGED
|
@@ -777,19 +777,19 @@ track, and paging moves by exact viewport-height pixel geometry, so page landing
|
|
|
777
777
|
| Ctrl+Z / Y / Shift+Z | Relay to undo/redo callbacks | Native textarea undo | Native textarea undo | — |
|
|
778
778
|
| Shift+F10 / ContextMenu | Context-menu callback | — | — | — |
|
|
779
779
|
| 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 |
|
|
780
|
+
| Ctrl+Backslash / Ctrl+IntlYen / Ctrl+IntlRo | Clear every format key of the selection | Consumed, not run (`onCommandBlockedWhileEditing`) | Same | `clearFormatting` |
|
|
781
781
|
| Ctrl+Shift+L / Ctrl+Shift+E / Ctrl+Shift+R | Align left / center / right | Session cell | Same | `alignLeft` / `alignCenter` / `alignRight` |
|
|
782
782
|
| 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
783
|
| Alt+Shift+Digit7 / Alt+Shift+Digit6 | Outer borders of each range (inner borders kept) / clear borders | Native | Native | `bordersOuter` / `bordersClear` |
|
|
784
784
|
| 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 |
|
|
786
|
-
| Shift+F2 | Note popover on the active cell |
|
|
785
|
+
| Ctrl+K | Link popover on the active cell | Consumed, not run (`onCommandBlockedWhileEditing`) | Same | `insertLink` |
|
|
786
|
+
| Shift+F2 | Note popover on the active cell | Consumed, not run (`onCommandBlockedWhileEditing`) | Same | `insertNote` |
|
|
787
787
|
| Ctrl+Alt+M | Comment thread popover on the active cell | Native | Native | `insertComment` |
|
|
788
788
|
| 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) |
|
|
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) | Consumed, not run (`onCommandBlockedWhileEditing`) — the browser's bookmark / reload never fires and the typed value stays | Same | `fillDown` / `fillRight` |
|
|
790
790
|
| 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
791
|
| 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) |
|
|
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` |
|
|
793
793
|
| 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
794
|
| 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
795
|
| 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 +808,28 @@ Rows with a **Command** are rebindable through the `shortcuts` prop (except `pas
|
|
|
808
808
|
`handle.executeCommand(command)`; every command exists only while its capability is declared (`getCellFormat` for formats /
|
|
809
809
|
borders / colours, `getCellNote` / `getCellComments` / `getCellHyperlink` / `getCellValidation` for the popover commands, the
|
|
810
810
|
`formats` prop for `formatCurrency`, `getCellFormula` for `pasteFormulas`) — an unavailable command's chord passes through
|
|
811
|
-
untouched and `executeCommand` returns `false`. The editing columns
|
|
811
|
+
untouched and `executeCommand` returns `false`. The editing columns run only the 16 **editing-column commands**
|
|
812
812
|
(`bold` / `italic` / `underline` / `strikethrough` / `alignLeft` / `alignCenter` / `alignRight` / `formatNumber` / `formatTime` /
|
|
813
|
-
`formatDate` / `formatCurrency` / `formatPercent` / `formatScientific` / `fillSelection` / `insertDate` / `insertTime`)
|
|
814
|
-
command
|
|
813
|
+
`formatDate` / `formatCurrency` / `formatPercent` / `formatScientific` / `fillSelection` / `insertDate` / `insertTime`). The
|
|
814
|
+
chord of any other available command never runs while a cell is being edited, and what happens to it depends on whether it
|
|
815
|
+
types anything in a text field:
|
|
816
|
+
|
|
817
|
+
- **No Alt, and a function key or Ctrl / Cmd with a letter, digit, punctuation or numpad key** (by default `Ctrl+D`, `Ctrl+R`,
|
|
818
|
+
`Ctrl+K`, `Shift+F2`, `Ctrl+Backslash` / `Ctrl+IntlYen` / `Ctrl+IntlRo`, `Ctrl+Shift+Digit9` / `Ctrl+Shift+Digit0`): the chord
|
|
819
|
+
types nothing, so the grid consumes it (`preventDefault` — the browser's own shortcut, such as bookmarking on Ctrl+D or
|
|
820
|
+
reloading on Ctrl+R, which would lose the typed value, never fires), leaves the session and its value untouched and calls
|
|
821
|
+
`onCommandBlockedWhileEditing({ command, chord })` (`chord` is the canonical chord, Cmd spelled `Ctrl`). To commit and run the
|
|
822
|
+
command instead, call `handle.executeCommand(command)` from that callback — it commits the session first, exactly as the
|
|
823
|
+
imperative call does from anywhere. On macOS the Control key counts as Ctrl like Cmd does, so Control+D and Control+K, a text
|
|
824
|
+
field's forward-delete and kill-line keys, are consumed as well.
|
|
825
|
+
- **Alt, or a text-editing key** (arrows, Home / End, the page keys, Enter, Tab, Space, Escape, Delete, Backspace, Insert, the
|
|
826
|
+
context-menu key; by default `Ctrl+Alt+M`, `Ctrl+Alt+Digit9`, `Ctrl+Alt+V`, the Alt+Shift border and resize rows,
|
|
827
|
+
`Alt+ArrowDown`): the chord keeps its meaning in the text — macOS Option characters and word moves, AltGr characters, caret
|
|
828
|
+
moves — and passes through untouched. Shift with a character key types that character.
|
|
829
|
+
|
|
830
|
+
An unavailable command's chord and a chord unbound through `shortcuts` are not rows of either column: the keydown passes
|
|
831
|
+
through untouched while idle and while editing alike (unbinding `fillDown` hands Ctrl+D back to the browser's bookmark). To keep
|
|
832
|
+
such a chord inert, call `preventDefault` on it in a keydown listener of your own. The exported `DEFAULT_SHORTCUTS` (`{ [command]: readonly string[] }`, `[]` =
|
|
815
833
|
unbound: 39 commands bound over 41 chords, 36 unbound) and `SPREADSHEET_RESERVED_SHORTCUTS` (the 63 exact chords of the
|
|
816
834
|
non-rebindable built-in rows consulted while idle) are derived from the same `BUILTIN_ROWS` table.
|
|
817
835
|
|
|
@@ -937,6 +955,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
|
|
|
937
955
|
| `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
956
|
| `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
957
|
| `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. |
|
|
958
|
+
| `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
959
|
| `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
960
|
| `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
961
|
| `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,7 +969,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
|
|
|
950
969
|
| `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
970
|
| `now` | `() => number` | v0.8 — clock seam of `insertDate` / `insertTime` (declared default `Date.now`). |
|
|
952
971
|
| `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. |
|
|
972
|
+
| `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
973
|
| `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
974
|
| `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
975
|
| `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 |
|
|
@@ -1081,8 +1100,8 @@ range's cells:
|
|
|
1081
1100
|
overlay quadrant) and `[data-aqsp-band-clip]` (the bands' clip). Without `frame` the overlay's DOM and writes are those
|
|
1082
1101
|
of 0.17.3.
|
|
1083
1102
|
|
|
1084
|
-
The demo's `/fit` route has a frame switch
|
|
1085
|
-
and column bands to see it meet the dividers and the bands.
|
|
1103
|
+
The demo's `/fit` route has a frame switch and a range select (every cell, or `D1:F4`), with pins (a frozen header
|
|
1104
|
+
row, footer row and first column) and the row and column bands to see it meet the dividers and the bands.
|
|
1086
1105
|
|
|
1087
1106
|
## View geometry and zoom rules (`@aiquants/spreadsheet/view`)
|
|
1088
1107
|
|
|
@@ -1281,7 +1300,7 @@ covers the `?lang=ja` path and the live switch; every other E2E spec runs the En
|
|
|
1281
1300
|
| `/styles` | The v0.8 rich cells (`tests/e2e/styles.spec.ts`): a 300 × 26 sheet whose store declares all eight capabilities (a mini formula evaluator for `=A1+B1` / `SUM` / `AVERAGE` feeds `evaluateFormula` and the computed `getCellText`, `getCellFormula` returns the source), a patch-applying store with per-transaction inverse-patch Undo (a cross-sheet cut-move folds into one entry) and consumer-minted comment ids, a format toolbar driven by `handle.executeCommand` (every button keeps focus in the grid), colour pickers, border / number-format presets, link / note / comment / validation / conditional-format editors, a Paste Special menu opened by `onPasteSpecialRequest` (Excel accelerators — modes `A`ll / `F`ormulas / `V`alues / `T` formats / `C`omments and notes / `N` validation / `X` all except borders / `W`idths / `R` conditional formats, operations `O` none / `D` add / `S` subtract / `M` multiply / `I` divide, flags `B` skip blanks / `E` transpose / `J` inject formats → `handle.paste`), highlight-band settings, a shortcut rebinding table with reserved-chord warnings, a clip-info chip (`onClipChange`), a Sheet A / B toggle for cross-sheet paste and cut-move, and Excel / Sheets fixture buttons that write real interop HTML to the clipboard — and, since v0.9, the trailing freeze live by default: `frozenTrailingRows={1}` / `frozenTrailingColumns={1}` alongside the leading 1×1 (this nine-quadrant state is the ambient every `/styles` budget number is certified on) pin the sheet's grand-total row (the last row's `SUM` / `AVERAGE`, bold at the base font) to the bottom edge, with a `data-demo-trailing` checkbox to release it |
|
|
1282
1301
|
| `/huge` | The v0.4 deep-reach proof: 1,000,000 × 10,000,000 on a pure functional adapter — Ctrl+→ (and End) reach the rightmost column 9,999,999 and Ctrl+↓ the last row 999,999 in one press (uniform-block Excel semantics, unified with the `/` route; ±1px cell placement), a "deep jump" button (`scrollToCell` to the interior column 5,000,000 ≈ 5 億 px, past the 2^25 wall), zoom ×4 holds ±1 logical px — plus runtime freeze toggles (0 ↔ 3 frozen rows above 0 ↔ 3 frozen columns), a context menu (right-click / Shift+F10) that opens at static frozen-cell coordinates even mid-deep-scroll, and the drag-freshness and performance-budget E2E gates — plus the v0.9 trailing-freeze controls consumed by `tests/e2e/trailing-freeze.spec.ts`: trailing freeze toggles for 0 ↔ 2 last rows / columns (`data-demo-trailing-row-toggle` / `data-demo-trailing-col-toggle` — deliberately not the leading toggles' 0 ↔ 3), a row-axis deep jump to the last scroll row `rowCount − T − 1` (`data-demo-deep-jump-row`, reading the live toggle), and an overlap toggle (`data-demo-overlap-toggle` — 16 / 16 frozen rows and 8 / 8 frozen columns exceed the default E2E viewport on both axes) |
|
|
1283
1302
|
| `/tune` | Sizing knobs (`defaultRowHeight` / `defaultColumnWidth` / banded per-column widths via the imperative `resizeColumn` mount effect), hide / unhide (drag a boundary to 0, marker drag / dblclick restore, single-column dblclick autofit), a deliberately low LIVE `maxOperationCells` staging every rejection class (limit, row fan-out ÷10, autofit ÷4, bounds via the multi-cell corner recipe), live `enableResizeUI` / `enableFillHandle` opt-outs, an empty-grid staging toggle (rowCount 0 adapter swap), a data-reset button, and the zoom card (v0.3) — the controlled-mode reference wiring (`zoom` + `onZoomChange`, 50–200% select plus every zoom gesture) and the fixture for the zoom E2E gates |
|
|
1284
|
-
| `/fit` | v0.17 — a host that fits the grid's box to `onContentSizeChange` (`tests/e2e/host-fit.spec.ts`): a read-only 60 × 6 table in the page's flow whose box shows every row so the page scrolls instead, with the headings switch (`data-demo-fit-headings`), the zoom (`data-demo-fit-zoom`), the all-rows fit through `autoFitColumns` (`data-demo-fit-autofit`) and the content-size readout (`data-demo-fit-size`); arrow keys keep the active cell in the window; v0.18 adds the frame switch (`data-demo-fit-frame` — every cell
|
|
1303
|
+
| `/fit` | v0.17 — a host that fits the grid's box to `onContentSizeChange` (`tests/e2e/host-fit.spec.ts`): a read-only 60 × 6 table in the page's flow whose box shows every row so the page scrolls instead, with the headings switch (`data-demo-fit-headings`), the zoom (`data-demo-fit-zoom`), the all-rows fit through `autoFitColumns` (`data-demo-fit-autofit`) and the content-size readout (`data-demo-fit-size`); arrow keys keep the active cell in the window; v0.18 adds the frame switch (`data-demo-fit-frame`) with its range select (`data-demo-fit-frame-range` — every cell, or `D1:F4`, which scrolls out under the frozen header row and, in a narrow box, starts past the cells' far edge), the pins switch (`data-demo-fit-pins` — a frozen header row, footer row and first column) and the bands switch (`data-demo-fit-bands`), read from real pixels by `tests/e2e/frame.spec.ts` |
|
|
1285
1304
|
| `/a11y` | Locale-aware custom `formatCellAnnouncement` / `formatSelectionAnnouncement` (English by default, Japanese under `?lang=ja`) mirrored into visible readouts, per-locale overridden accessible names (Escape advisement kept), the WCAG 2.1.2 escape route |
|
|
1286
1305
|
| `/readonly` | The v0.10 read-only cells (`tests/e2e/readonly.spec.ts`): a 200 × 10 sheet whose adapter declares `isCellReadOnly` (one locked COLUMN plus scattered locked cells for mixed selections) alongside note / comment / link / validation reads — the whole-operation refusals live (edit entries, Delete, paste, cut, fill incl. the diagonal legs, annotation chords on empty cells), the content-aware viewers (the locked column carries a comment thread, a note and a hyperlink; their chords open viewer-mode popovers with the commit affordance disabled), a host-side tint on `[data-aqsp-readonly]` (the package ships no CSS), a refusal toast worded per `ReadOnlyRejection` (the three `editSession` fates told apart, the two-producer cut wording), and an `onPasteResolved` two-line log that sits beside the refusal toast so a read-only-refused paste shows BOTH callbacks |
|
|
1287
1306
|
| `/utils` | The exported pure functions live: TSV round-trip, paste-expansion rules, column-name converter (incl. its fail-fast `RangeError`), range algebra, and a clipboard inspector card (discloses the raw text/html payload, textContent-rendered) |
|