@aiquants/spreadsheet 0.20.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 CHANGED
@@ -2,6 +2,57 @@
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
+
5
56
  ## 0.20.0 (2026-11-06)
6
57
 
7
58
  ### Added
package/README.md CHANGED
@@ -128,9 +128,9 @@ The host element must have a resolvable height — the grid fills its parent.
128
128
 
129
129
  - **Adapter identity is the sheet identity.** Replacing the adapter object means "sheet switch": selection resets to A1, any in-flight drag, editing session and open popover are terminated (value-discarding, exactly like Excel switching sheets — nothing is ever committed across a swap), an armed
130
130
  **copy** is discarded, and an armed **cut** is kept as a *foreign* clip (`onClipChange({ kind: "cut", range, foreign: true })`, its marquee hidden) so the next `Ctrl+V` on the new sheet is a **cross-sheet move** — the target sheet is written first, then the source sheet is cleared under the same
131
- transaction id (see "Cut matching rule").
131
+ transaction id (see "Cut matching rule"). The reset fires `onSelectionChange` once from a layout effect (host-driven, not a gesture) unless the selection already was the lone cell A1; a switch to an empty adapter (0 rows or 0 columns, so no A1) fires nothing.
132
132
  - **A count shrink keeps the identity.** When `rowCount` / `colCount` shrink under the SAME adapter (a filter, category or period change removes rows), the package clamps its own coordinates instead of resetting (ADR-33): every selection range, the anchor and the active cell are pulled onto the last row / column (a range entirely beyond the edge collapses onto it; one `onSelectionChange` when anything moved, none otherwise),
133
- an editing session, a popover or a note tip whose cell left the grid is cancelled / closed (those still inside are kept), an armed clip whose range left the grid is discarded (a foreign cut is untouched), in-flight drags are cancelled, and a shrink to zero rows / columns lands on the empty-grid state. Growth changes nothing. The engine's out-of-range fail-fast stays intact — the package clamps its state before anything is measured.
133
+ an editing session, a popover or a note tip whose cell left the grid is cancelled / closed (those still inside are kept), an armed clip whose range left the grid is discarded (a foreign cut is untouched), in-flight drags are cancelled, and a shrink to zero rows / columns lands on the empty-grid state without firing `onSelectionChange` (a grid with no rows or no columns has no A1). Growth changes nothing. The engine's out-of-range fail-fast stays intact — the package clamps its state before anything is measured.
134
134
  Traits to know: the fold fires `onSelectionChange` once from a layout effect (host-driven, not a gesture); closing a popover this way takes the popover's normal close path, which returns focus to the grid; a kept selection / session is index-based — after a filter, row r shows whichever item now occupies row r (your data model decides). A kept editing session whose formula token references a vanished row keeps working — keyboard reference pointing clamps the token-derived cursor onto the grid before it steps.
135
135
  A popover closed this way leaves your focus alone while it sits outside the grid (a filter input); only a close from inside the grid returns focus to the sink.
136
136
  - **External writes** (your toolbar Undo, collaborative updates) are published by incrementing the `dataVersion` prop. This re-renders visible cells, rebuilds the conditional-format index, **and cancels any armed clip** — otherwise a stale cut could "move" cells whose content has changed underneath.
@@ -379,10 +379,13 @@ Row autofit restores the default row height (cells render single-line clipped).
379
379
  > font or spacing than their pane, autofit will mismeasure — set them on the root, which the pane, the cells and the
380
380
  > header bands all inherit (the shipped stylesheets do).
381
381
 
382
- `enableResizeUI={false}` removes the strips **and the unhide markers** — a consumer with hidden tracks then has no
383
- in-package restore affordance (only the imperative API). The imperative `resizeRow` / `resizeColumn` calls bypass every UI
384
- gate (no 1px clamp, no hidden-row cap, no fan-out limit): mass-hiding rows through the API is your responsibility and falls
385
- outside the rendering guarantee.
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
 
@@ -792,11 +795,11 @@ track, and paging moves by exact viewport-height pixel geometry, so page landing
792
795
  | Ctrl+D / Ctrl+R | Fill down / right (first row / column of each range, or the neighbour above / left for a single row / column; formulas shift) | Consumed, not run (`onCommandBlockedWhileEditing`) — the browser's bookmark / reload never fires and the typed value stays | Same | `fillDown` / `fillRight` |
793
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` |
794
797
  | Ctrl+Semicolon / Ctrl+Shift+Semicolon | Write today's date (`YYYY-MM-DD`) / the current time (`HH:mm:ss`, local, `now` prop) into the **active cell only** | Insert at the caret | Same | `insertDate` / `insertTime` |
795
- | Ctrl+Alt+Digit9 / Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0 | Hide the selected rows / unhide rows / unhide columns (through the resize gates) | Ctrl+Alt+Digit9: native; Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0: consumed, not run (`onCommandBlockedWhileEditing`) | Same | `hideRows` / `unhideRows` / `unhideColumns` |
798
+ | Ctrl+Alt+Digit9 / Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0 | Hide the selected rows / unhide rows / unhide columns (through the resize gates); unavailable with `enableResizeUI={false}` | Ctrl+Alt+Digit9: native; Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0: consumed, not run (`onCommandBlockedWhileEditing`) | Same | `hideRows` / `unhideRows` / `unhideColumns` |
796
799
  | Alt+Shift+ArrowRight / Alt+Shift+ArrowLeft | Widen / narrow the active column by one step (× / ÷ 2^(1/4), whole px, at least 1 px of change, never below 1 px — a step never hides a column); with a full-span column selection every selected column takes the new size, as a strip drag does. Allowed under `readOnly` (a view change), unavailable with `enableResizeUI={false}` | Native | Native | `increaseColumnWidth` / `decreaseColumnWidth` |
797
800
  | Alt+Shift+ArrowDown / Alt+Shift+ArrowUp | Make the active row taller / shorter by one step (same rule and fan-out) | Native | Native | `increaseRowHeight` / `decreaseRowHeight` |
798
801
  | Alt+Shift+Equal (`=`) | Fit the active column to its content (the strip double-click's autofit; no-op while `renderCell` is set) | Native | Native | `autoFitColumnWidth` |
799
- | *(unbound by default)* | Hide the selected columns — bind it yourself, e.g. `shortcuts={{ hideColumns: ["Ctrl+Alt+Shift+Digit9"] }}` | — | — | `hideColumns` |
802
+ | *(unbound by default)* | Hide the selected columns — bind it yourself, e.g. `shortcuts={{ hideColumns: ["Ctrl+Alt+Shift+Digit9"] }}`; unavailable with `enableResizeUI={false}` | — | — | `hideColumns` |
800
803
  | *(unbound by default)* | General (no value format) / all four borders | — | — | `formatGeneral` / `bordersAll` |
801
804
  | *(unbound by default)* | Paste Special modes through the menu path (`handle.paste`) | — | — | `pasteFormats` / `pasteFormulas` / `pasteAdd` / `pasteSubtract` / `pasteMultiply` / `pasteDivide` |
802
805
  | *(unbound by default)* | Self-calc over the selection (exact decimal shift, formulas wrapped `=(…)*100`; non-numeric cells untouched) | — | — | `multiplyBy100` / `multiplyBy1000` / `divideBy100` / `divideBy1000` / `signReversal` |
@@ -940,13 +943,13 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
940
943
  | `frozenTrailingRows` | `number` | Freezes the **last** N rows at the bottom edge (v0.9; default 0, LIVE — the row-axis twin of `frozenTrailingColumns`; a pinned totals row is the canonical use). Same engine validation and leading-wins clamp; trailing rows stay visible at any vertical scroll (same overlap exception); keyboard ensure-visible treats them as vertical no-ops. |
941
944
  | `renderCell` | `(ctx: RenderCellContext) => ReactNode` — `RenderCellContext = { row; col; text; displayText }` (exported) | Custom cell rendering. **Must be identity-stable** (`useCallback`) — an inline arrow defeats the cell memo and re-renders every visible cell each pass. **Per-cell opt-out** (v0.12 — ADR-32): return `undefined` and that one cell falls back to the package default rendering, value-format engine included (only `undefined` opts out — `null`, `false` and any other ReactNode are custom output, i.e. an empty custom cell). `ctx.text` is the raw canonical string; `ctx.displayText` is the value-format display — the exact string the default rendering, announcements, the HTML clipboard and autofit share, so a custom cell that renders it can never drift from what gets copied. Autofit stays a whole-grid no-op while `renderCell` is set. |
942
945
  | `maxOperationCells` | `number` | Bulk-operation ceiling (default 100,000). Row fan-out resize gates at 1/10 of it and autofit at 1/4 — see "Operation limits". |
943
- | `enableResizeUI` | `boolean` | Default `true`. `false` removes resize strips **and unhide markers** — hidden tracks then have no in-package restore path (imperative API only). |
946
+ | `enableResizeUI` | `boolean` | Default `true`. `false` removes resize strips **and unhide markers**, makes the keyboard resize and hide / unhide commands unavailable, and keeps pastes from writing sizes (copies still carry them) — sizes then change, and hidden tracks come back, only through the imperative API. |
944
947
  | `headings` | `boolean` | v0.17 — default `true`: shows the column letters, the row numbers and the corner (Excel's "headings"; not `headerRows`). `false` draws none of the three and collapses their grid tracks to 0, so the cells start at the grid's top-left corner; the gestures that live only on them go with them (header presses, the corner's select-all, the resize strips and unhide markers) and their keyboard twins stay (Ctrl+Space, Shift+Space, Ctrl+A, Alt+Shift+Arrow, Alt+Shift+=). The bands are `aria-hidden`, so assistive technology meets the same grid. The root carries `data-aqsp-headings-hidden` while they are hidden. LIVE prop. |
945
948
  | `onContentSizeChange` | `(size: SpreadsheetContentSize) => void` | v0.17 — receives the size of the grid's content in CSS px: the bands (when shown), every column and row at its current size and the two scroll bars the grid always reserves, all scaled by the zoom (the scroll bars live inside the zoom wrapper, so they scale too). Called after the first layout and after every change of it — a track's size (a resize, an autofit, a hide or unhide, the imperative `resizeRow` / `resizeColumn`), the row or column count, the default sizes, the zoom or `headings` — never with an unchanged size. The bands count on whichever side of the cells they sit (a right-to-left grid too) and in a box smaller than them; a grid with no rows or no columns draws nothing and reports 0 × 0; a grid without a layout box (under a `display: none` ancestor) reports once it has one. See *Fitting a box to the grid*. |
946
949
  | `frame` | `CellRange` | v0.18 — draws a frame around a range of cells: a line of `--aqsp-frame-width` (2px by default) in `--aqsp-frame-color` (default `#1f2937`) just inside the outer edges of the range's cells, scrolling with them and scaled by the zoom like their lines. The part of the range inside the grid is framed; bounds that are not non-negative integers with each start at most its end throw a RangeError. Each pane frames the part it paints and leaves open a side the range continues past (`data-aqsp-frame-open`), so frozen panes join into one frame. The frame sits over the freeze dividers and the bands and under the active cell's frame; while it is set the bands, the dividers and the marquee's far headroom stop at the last painted cell, and the root carries `data-aqsp-framed`. See *Framing a range*. LIVE prop. |
947
950
  | `zoom` / `defaultZoom` / `onZoomChange` | `number` / `number` / `(zoom: number) => void` | Package zoom (v0.3): visual transform scale, logic stays in logical px. Controlled (`zoom`) or uncontrolled (`defaultZoom`, default 1). Gestures — Alt+Wheel and Ctrl+Alt+`=` / `+` / `-` / `0` (reset; the four keys match the produced character, Shift-agnostic; AltGraph-state chords are never claimed — legacy-shape defense in depth, see Keymap notes) — request via `onZoomChange`; Ctrl+Wheel is deliberately unbound (the browser owns it). Clamped to [`SPREADSHEET_ZOOM_MIN`, `SPREADSHEET_ZOOM_MAX`] (0.25–4, `clampSpreadsheetZoom` of `@aiquants/spreadsheet/view`); a non-finite value (NaN / ±Infinity) throws a `RangeError` (fail-fast — no silent substitution). |
948
951
  | `enableFillHandle` | `boolean` | Default `true`. Fill writes through `applyEdits` — disable for read-only adapters. |
949
- | `onSelectionChange` | `(selection: SelectionState) => void` | Fires on confirmed changes only — never on mount, and never mid-drag with one documented exception: the header subtract reservation converts to a real press on the first movement that both really changes the pointer coordinates and lands on a different header index (in-index jitter and synthetic same-position moves keep the reservation), firing the deferred press replace mid-drag (total fire count matches v0.1). |
952
+ | `onSelectionChange` | `(selection: SelectionState) => 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". |
950
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". |
951
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". |
952
955
  | `onCopyMultiRange` | `() => void` | Notice that a multi-range copy serialized only the tail range. |
@@ -1030,7 +1033,7 @@ ref.current?.focus({ preventScroll: true }) // focuses the hidden
1030
1033
  `navigator.clipboard` is `"insecure-origin"`, a refused read `"permission-denied"`, no readable item `"empty"`, and a detected source
1031
1034
  that fails to parse `"unreadable"` — each fires `onClipboardUnavailable` and resolves `"rejected"`. `"applied"` means the adapter was
1032
1035
  called; `"empty"` means nothing was written (an own payload whose identity was suppressed, every cell skipped, a mode without cell
1033
- aspects such as `columnWidths` — sizes may still have been applied).
1036
+ aspects such as `columnWidths` — sizes may still have been applied, unless `enableResizeUI` is `false`).
1034
1037
 
1035
1038
  ## Fitting a box to the grid (v0.17)
1036
1039
 
@@ -1250,7 +1253,7 @@ The `/utils` demo route exercises the v0.1 toolkit live; the `/styles` route dri
1250
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 |
1251
1254
  | `colspan` / `rowspan` in pasted tables | Anchor cell + blank unformatted cells | Merged cells | No merge model in the package |
1252
1255
  | Sheets compact JSON (`data-sheets-userformat` / text-style runs) | Not parsed (the CSS already carries the cell format) | — | No partial-format (run) model |
1253
- | Column widths / row heights on the clipboard | Carried only by whole-column / whole-row copies, pasted by `all` / `noBorders` / `columnWidths`, never by a transposed paste; 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 |
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 |
1254
1257
  | Paste Special ÷ 0 | Target untouched | `#DIV/0!` | No error-value vocabulary |
1255
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`) |
1256
1259
  | Transposed paste formulas | Only fully relative references rotate; mixed / absolute references stay | Same | A mixed reference cannot rotate without moving its anchor |