@aiquants/spreadsheet 0.19.0 → 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 +43 -1
- package/README.md +12 -7
- package/dist/index.cjs +8 -8
- package/dist/index.d.cts +40 -0
- package/dist/index.d.ts +40 -0
- package/dist/index.js +3498 -3478
- package/dist/styles/spreadsheet.standalone.css +1 -1
- package/package.json +6 -6
- package/src/Spreadsheet.tsx +95 -12
- package/src/grid/GridBody.tsx +32 -3
- package/src/index.ts +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,48 @@
|
|
|
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
|
+
|
|
5
47
|
## 0.19.0 (2026-10-31)
|
|
6
48
|
|
|
7
49
|
### Fixed
|
|
@@ -956,7 +998,7 @@ v0.8 実装計画 (以下「計画 §N」)、横断仕様は
|
|
|
956
998
|
文字列指数シフトで行い、丸め境界 (`decimals: 1` 指定時 `"1.45"` → `"1.5%"`) と 2^53 超の整数桁を正確に保つ。
|
|
957
999
|
2. **interned フォーマッタ**: `Intl.NumberFormat` はオプションタプル毎にモジュール Map へインターンし
|
|
958
1000
|
(JSON null 番兵キー)、**構築失敗も null でインターン** — 壊れた列の throw は組ごとに 1 回きり。
|
|
959
|
-
上限 256 到達で全消去の安全弁。1,200 セル級スライスの整形
|
|
1001
|
+
上限 256 到達で全消去の安全弁。1,200 セル級スライスの整形 \~50ms → \~2ms (約 25 倍)、autofit 2.5 万セル
|
|
960
1002
|
計測 1.45s → 32ms の実測改善。
|
|
961
1003
|
3. **負ゼロ抑止は `signDisplay:"negative"`**: ゼロへ丸まる値は全 locale で符号を出さない
|
|
962
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
|
|
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+,
|
|
@@ -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,
|
|
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.
|
|
468
|
-
|
|
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.
|
|
@@ -974,6 +977,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
|
|
|
974
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 |
|
|
975
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 |
|
|
976
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. |
|
|
977
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. |
|
|
978
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. |
|
|
979
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. |
|
|
@@ -1044,7 +1048,8 @@ ref.current?.autoFitColumns(Array.from({ length: colCount }, (_, col) => col))
|
|
|
1044
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
|
|
1045
1049
|
list becomes scrollable and the grid takes vertical finger swipes for itself (`touch-action: none`), so a box taller
|
|
1046
1050
|
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.
|
|
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.
|
|
1048
1053
|
- **`autoFitColumns(columns)`** fits the listed columns to the widest text of **all** their rows (header rows
|
|
1049
1054
|
included) — Alt+Shift+= fits the active column over the rows in view — with the same painted fonts, 9 px padding and
|
|
1050
1055
|
10,000 px bound. A hidden or empty column keeps its width; more measured cells than `maxOperationCells` are refused
|
|
@@ -1179,7 +1184,7 @@ importers with the exact same Excel-compatible semantics the grid uses. `enumera
|
|
|
1179
1184
|
`onOperationRejected` op), and `EditRejection` (the `onEditRejected` context — see "Editing, Undo, and rejection") are exported for
|
|
1180
1185
|
consumer-side annotations.
|
|
1181
1186
|
|
|
1182
|
-
v0.8 adds the rich-cell engines as public pure functions (all React-free; `src/index.ts` exports 44 values and
|
|
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):
|
|
1183
1188
|
|
|
1184
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`),
|
|
1185
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).
|