@aiquants/spreadsheet 0.17.1 → 0.17.3

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,73 @@
2
2
 
3
3
  All notable changes to `@aiquants/spreadsheet` are documented here.
4
4
 
5
+ ## 0.17.3 (2026-10-27)
6
+
7
+ ### Changed
8
+
9
+ - **The freeze divider keeps its thickness on screen at every zoom.** The zoom wrapper scaled the divider with the
10
+ grid, so a 2px divider was 1.68 px at 84 % and 0.5 px at 25 %; on a screen with one device pixel per CSS pixel a
11
+ half-pixel line paints at half strength, about 1.7:1 against the white surface instead of 3.31:1. Where CSS
12
+ `round()` is supported, the width is now `--aqsp-divider-width` divided by the zoom, rounded up to a whole pixel of
13
+ the wrapper's coordinates: the browser paints a box on whole pixels there (Chromium snaps both edges), so an exact
14
+ quotient would paint as its floor or its ceiling depending on where the line sits (measured: 1.1 to 2.2 px at
15
+ 110 %). A 2px divider is now 2 px to under 2 px plus the zoom on screen (2 px at 25 %, 2.5 px at 125 %, 4 px at
16
+ 400 %), as Excel's and Sheets' dividers keep one thickness at every zoom; at low zooms it covers more of the scroll
17
+ band's edge cells (8 logical px at 25 %). A browser without `round()` keeps the logical width, which the zoom
18
+ scales, and `--aqsp-divider-width: 0px` still removes the line.
19
+
20
+ ### Verification
21
+
22
+ - **公開面・DOM 属性**: 0.17.2 と同じ (公開面 143 export、`data-aqsp-*` のリテラル census 83 種)。
23
+ - **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **98 ファイル 4,253 テスト** 全緑 —
24
+ 0.17.2 出荷時の 98 ファイル 4,252 に v0.17.3 進行分 +1 (0.17.2 節の出荷時凍結ピンで `hxCensus` +1。分割線の CSS の
25
+ 文字列ピン (`trailingFreeze`) は `@supports` の規則を加えて件数は同じ)。`tsc --noEmit` / biome 0。E2E は
26
+ `trailing-freeze` +1 (キーで辿る倍率の全部の段で、胴体と見出しの縦と横の分割線が見た目 2 px 以上の最小の整数の px、
27
+ 25 % で中央の画素が分割線の色そのもの、`--aqsp-divider-width: 3px` も倍率で割られる) を加えた全 25 ファイル 288 テスト。
28
+ 変更が届く 4 ファイル (`trailing-freeze`・`styles`・`frozen-columns`・`frozen-rows`) は 74 件全緑。0.17.2 の論理 px に
29
+ 戻す変異は倍率 0.84 の見た目 1.68 px で、割るだけで切り上げない変異は太さ 2.375 px (整数でない) で赤。
30
+
31
+ ## 0.17.2 (2026-10-27)
32
+
33
+ ### Fixed
34
+
35
+ - **A press into a grid without focus no longer scrolls the page back to the previous active cell.** A press moved the
36
+ focus to the hidden input before it moved the selection, while the input still sat on the previous active cell, and
37
+ the browser scrolled the page to it: in a grid taller than its page (a box that shows every row), the first press on
38
+ a row below the window's top sent the page back to A1. Every press (cells, headings, the corner, resize strips, the
39
+ fill handle, scroll-bar bands, a reference while pointing) now focuses without scrolling, since the pressed point is
40
+ on screen; focus that reaches the root from a touch tap does too, while a keyboard entry (`:focus-visible`) still
41
+ scrolls the page to the active cell.
42
+ - **PageUp and PageDown measure the part of the grid the reader sees with the browser's own hit test.** 0.17.1 cut the
43
+ viewport by the clipping boxes it found walking the DOM's ancestors, which miscounted in common pages: an `html`
44
+ with `overflow-x: hidden` (its overflow belongs to the viewport, yet its box moves as the page scrolls) shortened the
45
+ move or sent it to the last row; a modal dialog, a popover or full screen (the top layer, which no ancestor clips), a
46
+ fixed or absolutely positioned grid (clipped only along its containing blocks) and a shadow tree were cut by boxes
47
+ that do not clip them, or not by the ones that do. The seen part is now found by hit testing down the middle of the
48
+ body pane (samples, then the edges bisected to 1 px), so every clip, the top layer, shadow trees and anything painted
49
+ over the grid count as drawn. While no part of the body is seen, a page move goes a screenful of the window, and a
50
+ move shorter than the row it starts on still goes one visible row (inside a row taller than the viewport, PageDown
51
+ stayed on that row since 0.2).
52
+ - **`onContentSizeChange` counts the bands in a box smaller than the bands.** 0.17.1 read the bands as the zoom
53
+ wrapper's inner size less the body pane's, which in a box smaller than the bands (a host that starts its box at 0 × 0)
54
+ is the box's size, so the first report missed the bands until the body resized. The bands are now read from the
55
+ corner, which fills their crossing whatever the box's size or the page's direction.
56
+ - **Autofit measures each font with its own letter and word spacing.** 0.17.1 copied the body pane's computed spacing
57
+ to every font, but a reader's override is usually written in em (WCAG 1.4.12's `0.12em` / `0.16em`), so a cell drawn
58
+ at another size was measured with the wrong spacing and a fitted column cut its text. Each measured font now reads
59
+ the spacing a hidden sample inside the body pane computes for it.
60
+
61
+ ### Verification
62
+
63
+ - **公開面・DOM 属性**: 0.17.1 と同じ (公開面 143 export、`data-aqsp-*` のリテラル census 83 種)。
64
+ - **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **98 ファイル 4,252 テスト** 全緑 —
65
+ 0.17.1 出荷時の 98 ファイル 4,246 に v0.17.2 進行分 +6 (`hostFit` +5、0.17.1 節の出荷時凍結ピンで `hxCensus` +1)。
66
+ `tsc --noEmit` / biome 0。E2E は `host-fit` +2 (焦点の無い表の途中のセルの押下でページが跳び戻らない、根の要素が
67
+ `overflow-x: hidden` でもページ送りが窓の 1 画面) を加えた全 25 ファイル 287 テスト。押下のスクロールを戻す変異は 493 px
68
+ から 0 px への跳び戻りで、ページ送りを 0.17.1 の祖先のたどりに戻す変異は「49 行目のはずが 28 行目」で赤。全数実行
69
+ (load average 11〜12) は 286 passed / 1 failed で、落ちたのは `styles` の 1 本 (Ctrl+B の直後に computed を 1 回だけ読む
70
+ 競合。単独では 3 回とも合格)。操作の直後に 1 回だけ読む 15 か所を `expect.poll` に直し、`styles` の 41 件は全緑。
71
+
5
72
  ## 0.17.1 (2026-10-27)
6
73
 
7
74
  ### Fixed
package/README.md CHANGED
@@ -21,7 +21,7 @@ deep-reach proof route.
21
21
  - 🧊 **Frozen columns & rows** (v0.5 / v0.6): `frozenColumns` pins the first N columns as a static left band and `frozenRows` pins the first N rows as a static top band — two-band headers, a Cartesian-product 4-quadrant clipped selection overlay, partition-aware hit-testing and ensure-visible on both axes, all riding the engine's anchor-free frozen bands
22
22
  - 📌 **Trailing freeze & strong freeze dividers** (v0.9): `frozenTrailingColumns` / `frozenTrailingRows` pin the **last** N columns / rows (a fixed totals row is the canonical use) as static right / bottom bands over the **same data** (count-based, Glide-style — no extra-row API), with three-band headers,
23
23
  a {main, frozen, scroll, trailing}² clipped selection overlay, three-way partitioned hit-testing / ensure-visible, near-edge resize strips with pinned-right semantics, and band-side unhide markers; **every** freeze boundary (leading and trailing, both axes) draws a strong Excel / Sheets-style
24
- divider over the scroll band's edge pixels — 2px `#858e9d` by default (3:1 against the surface and the header band), consumer-tunable through the CSS variables `--aqsp-divider-color` / `--aqsp-divider-width` (no prop), `pointer-events: none` — see "Trailing freeze and the freeze divider"
24
+ divider over the scroll band's edge pixels — 2px `#858e9d` by default (3:1 against the surface and the header band, held on screen at every zoom), consumer-tunable through the CSS variables `--aqsp-divider-color` / `--aqsp-divider-width` (no prop), `pointer-events: none` — see "Trailing freeze and the freeze divider"
25
25
  - 🔒 **Read-only cells as a capability** (v0.10 — ADR-27..31): one optional adapter predicate `isCellReadOnly(row, col)` locks cells — no edit session can open on them (all six entries, the touch on-screen-keyboard invitation included), an open session's commit is live re-checked,
26
26
  and every write whose target set touches a read-only cell (Delete / paste / cut both walls / fill with diagonal L-legs decomposed / format / self-calc / annotations) refuses the **whole operation** before the adapter is reached (Excel-style, no per-cell skip); painted cells carry
27
27
  `aria-readonly="true"` + `data-aqsp-readonly` (style it yourself — no package CSS), refusals speak through the single sealed `onReadOnlyRejected` (+ opt-in `formatReadOnlyAnnouncement`), and copying or viewing notes / comments / links stays legal (content-aware chords,
@@ -367,9 +367,10 @@ Row autofit restores the default row height (cells render single-line clipped).
367
367
  > **Autofit measures with the cells' base font.** Text measurement composes its font from the **body pane's** computed
368
368
  > style (style / weight / size / family — the cells' parent, so the fit works whether `headings` shows the bands or not);
369
369
  > the cell's **painted** format (bold / italic from the base format and width-relevant conditional formats, `fontSize` in
370
- > pt × 4/3, `fontFamily`) overrides those parts per cell, bucketed so `ctx.font` is assigned once per distinct font. The
371
- > pane's letter and word spacing go to the canvas too (a canvas does not inherit CSS spacing), so a reader's text-spacing
372
- > override (WCAG 1.4.12) widens the fit instead of cutting the widest text. If your CSS gives the cells a different base
370
+ > pt × 4/3, `fontFamily`) overrides those parts per cell, bucketed so `ctx.font` is assigned once per distinct font.
371
+ > Each bucket's letter and word spacing go to the canvas too (a canvas does not inherit CSS spacing), read from a hidden
372
+ > sample inside the pane that takes the bucket's font, so a reader's text-spacing override (WCAG 1.4.12, usually in em)
373
+ > widens the fit of every font size instead of cutting the widest text. If your CSS gives the cells a different base
373
374
  > font or spacing than their pane, autofit will mismeasure — set them on the root, which the pane, the cells and the
374
375
  > header bands all inherit (the shipped stylesheets do).
375
376
 
@@ -421,7 +422,7 @@ two CSS custom properties — the only consumer surface (there is no prop):
421
422
  | Variable | Default | Meaning |
422
423
  | :--- | :--- | :--- |
423
424
  | `--aqsp-divider-color` | `#858e9d` (3:1 against the surface and the header band: the divider is a mark, not decoration) | Divider colour |
424
- | `--aqsp-divider-width` | `2px` (Sheets strength) | Divider thickness |
425
+ | `--aqsp-divider-width` | `2px` (Sheets strength) | Divider thickness on screen, at every zoom |
425
426
 
426
427
  ```css
427
428
  /* consumer stylesheet — any scope that contains the grid root */
@@ -433,8 +434,12 @@ two CSS custom properties — the only consumer surface (there is no prop):
433
434
 
434
435
  - Setting `--aqsp-divider-width: 0px` is the escape hatch: the per-quadrant fill-fragment seams at each freeze boundary
435
436
  re-appear (they are normally absorbed by the divider), and the forced-colors rule paints nothing either — intended.
436
- - The divider scales in **logical px** with the package zoom (at z = 0.25 a 2px divider renders 0.5 visual px —
437
- registered deviation).
437
+ - The divider keeps its thickness **on screen** at every package zoom, as Excel's and Sheets' dividers do. The zoom
438
+ wrapper scales it, so its width is `--aqsp-divider-width` divided by the zoom, rounded up to a whole pixel: the
439
+ browser paints a box on whole pixels of the wrapper's coordinates (Chromium snaps both edges), so an exact quotient
440
+ would paint as its floor or its ceiling depending on where the line sits (measured: 1.1 to 2.2 px at 110 %). A 2px
441
+ divider is 2 px to under 2 px plus the zoom on screen (2 px at 25 %, 2.5 px at 125 %, 4 px at 400 %). A browser
442
+ without CSS `round()` keeps the logical width, which the zoom scales.
438
443
  - The divider is **inert**: a drag on the bar starts a header selection; the resize strip sits immediately adjacent on
439
444
  the band side of the line (freeze-by-drag stays out of scope). Under forced colors the divider paints `CanvasText`.
440
445
  - Under full overlap (middle band collapsed) no divider renders at all — there are no scroll pixels to overlay — and the
@@ -490,7 +495,9 @@ keyboard input — this is what makes IME composition, clipboard events, and 16M
490
495
  - Keyboard reachability is complete for the keymap below: every listed operation works without a pointer, and `Escape` from
491
496
  the grid root returns focus to the page tab order (WCAG 2.1.2 — no keyboard trap). The grid never takes focus on mount
492
497
  (the hidden input is armed focus-neutrally — WCAG 3.2.1 / 2.4.3): keyboard entry is the page tab order (Tab / Shift+Tab)
493
- or a click, and re-entry always lands on the hidden input. Resizing has keyboard commands of its own (Alt+Shift+Arrow,
498
+ or a click, and re-entry always lands on the hidden input. A press focuses it without scrolling the page (the pressed
499
+ point is on screen, and the input still sits on the previous active cell until the press moves the selection), and so
500
+ does focus a touch tap sends to the root; a keyboard entry (`:focus-visible`) scrolls the page to the active cell. Resizing has keyboard commands of its own (Alt+Shift+Arrow,
494
501
  Alt+Shift+= — see "Resizing from the keyboard"), and filling has `fillDown` / `fillRight` / `fillSelection` (Ctrl+D / Ctrl+R /
495
502
  Ctrl+Enter).
496
503
  - The hidden input's `inputmode` is a **virtual-keyboard invitation**, not a mirror of the editing session — and not an idle
@@ -602,7 +609,7 @@ mode uses system colours only). `src/styles/designTokens.spec.ts` pins all of th
602
609
 
603
610
  The highlight bands resolve their aliases on the overlay element, where the `highlightColors` prop writes the public
604
611
  `--aqsp-band-*` names inline (so the prop wins over a host's value, and a host's value wins over the default);
605
- `--aqsp-divider-width` (default `2px`) sets the freeze dividers' thickness. The stylesheet declares no public `--aqsp-*`
612
+ `--aqsp-divider-width` (default `2px`) sets the freeze dividers' thickness on screen at every zoom. The stylesheet declares no public `--aqsp-*`
606
613
  name itself.
607
614
 
608
615
  **Non-text contrast (WCAG 1.4.11, 3:1).** The marks that carry meaning reach 3:1 against the default surface and the
@@ -749,7 +756,7 @@ track, and paging moves by exact viewport-height pixel geometry, so page landing
749
756
  | Home / End (+Ctrl) | First/last visible column / visible grid corner | Native | Native | — |
750
757
  | Shift+Home / Shift+End | Extend to the first / last visible column | Native | Native | — |
751
758
  | Ctrl+Shift+Home / End | Extend to the first / last visible grid corner | Native | Native | — |
752
- | PageUp / PageDown | Page move by one screenful, exact: the grid's viewport cut to the part of it the page shows (see *Fitting a box to the grid*) | Commit + page move | Commit + page move | — |
759
+ | PageUp / PageDown | Page move by one screenful, exact: the grid's viewport cut to the part of it the reader sees (see *Fitting a box to the grid*) | Commit + page move | Commit + page move | — |
753
760
  | Shift+PageUp / PageDown | Extend by one screenful | Native | Native | — |
754
761
  | Ctrl+Space / Shift+Space | Select whole columns / rows of **every** selected range (anchor/active stay) | Native | Native | — |
755
762
  | F2 | Start editing (edit) | Toggle the pointing arm — a session opens disarmed (Excel Edit mode: the first Arrow moves the caret), typing a trigger arms it, F2 is Excel's Edit ⇄ Enter (formula session with `getCellFormula`; otherwise native) | Toggle the pointing arm | — |
@@ -907,7 +914,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
907
914
  | `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". |
908
915
  | `enableResizeUI` | `boolean` | Default `true`. `false` removes resize strips **and unhide markers** — hidden tracks then have no in-package restore path (imperative API only). |
909
916
  | `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. |
910
- | `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); 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*. |
917
+ | `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*. |
911
918
  | `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). |
912
919
  | `enableFillHandle` | `boolean` | Default `true`. Fill writes through `applyEdits` — disable for read-only adapters. |
913
920
  | `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). |
@@ -1026,8 +1033,11 @@ ref.current?.autoFitColumns(Array.from({ length: colCount }, (_, col) => col))
1026
1033
  pointer selection does not scroll (the pressed cell is on screen). The reveal lands at once (`behavior: "instant"`),
1027
1034
  whatever the page's `scroll-behavior`, so a held arrow key does not leave the page behind.
1028
1035
  - **Page moves go by a screenful of the page.** PageUp / PageDown travel the grid's viewport cut to the part of the
1029
- body that the clipping boxes outside the grid and the window show — a box that shows every row holds every row in
1030
- the grid's own viewport, which would page from any row to the first or the last.
1036
+ body the reader sees — a box that shows every row holds every row in the grid's own viewport, which would page from
1037
+ any row to the first or the last. The seen part comes from the browser's own hit test down the middle of the body,
1038
+ so every clip (scroll containers, the window, an `html` whose overflow belongs to the viewport), the top layer (a
1039
+ modal dialog, a popover, full screen), shadow trees and anything painted over the grid count as drawn. While no part
1040
+ of the body is seen, a page move goes a screenful of the window; a move shorter than its starting row goes one row.
1031
1041
 
1032
1042
  The demo's `/fit` route is the reference wiring.
1033
1043
 
@@ -1198,7 +1208,7 @@ The `/utils` demo route exercises the v0.1 toolkit live; the `/styles` route dri
1198
1208
  | Self-calc | Writes canonical decimals (exponent-form inputs keep exponent form), flips `TRUE` / `FALSE` case-insensitively, leaves custom checkbox labels alone, treats an `=`-prefixed text as text unless `getCellFormula` is declared, and wraps compound formulas (`=(A1)/100+(B1)/100` × 100 ⇒ `=((A1)/100+(B1)/100)*100`) instead of peeling | The reference extension peels greedily | The greedy regex produces the broken `=A1)/100+(B1` |
1199
1209
  | Excel / Word HTML without a table | `mso-` paragraphs (Word / Outlook) paste as text, not as an unreadable Excel clip | — | No table reader can read them; ADR-14 forbids trying another reader |
1200
1210
  | Freeze divider interactivity | The divider is inert (`pointer-events: none`): a drag on the bar starts a header selection; the resize strip sits immediately adjacent on the band side of the line | In Sheets this exact visual is the freeze drag handle | Excel behaviour (static thin line) in Sheets clothing — freeze-by-drag would be its own freeze-UI feature, out of scope |
1201
- | Freeze divider under zoom | Logical px — scales with the package zoom (z = 0.25 renders a 2px divider at 0.5 visual px) | Excel / Sheets dividers are UI chrome, unaffected by sheet zoom | One coordinate space for all chrome; a zoom-compensating width var is a recorded future path, not added for this alone |
1211
+ | Freeze divider under zoom | At least `--aqsp-divider-width` on screen at every zoom, and less than one zoomed pixel more (a 2px divider: 2 px at 25 %, 2.5 px at 125 %, 4 px at 400 %) | Excel / Sheets dividers keep one thickness at every sheet zoom | The browser paints a box on whole pixels of the zoom wrapper's coordinates, so the divider takes the thinnest whole-pixel width that is not thinner than the variable on screen; an exact quotient would paint as its floor or its ceiling by position. At low zooms the line covers a larger share of the scroll band's edge cells (8 logical px at 25 %) |
1202
1212
  | `--aqsp-divider-width: 0px` | Escape hatch: per-quadrant fill-fragment seams re-appear at every freeze boundary, and forced-colors paints nothing | — | The divider is what absorbs those seams; removing it re-exposes the pre-v0.9 artefact — intended |
1203
1213
  | Occluded trailing cells (overlap) | When leading + trailing extent exceeds the viewport, occluded trailing cells cannot be scrolled into view and keyboard focus draws no visible frame; the count clamp gives leading the count space | Excel refuses to freeze past the viewport | Count-based trailing freeze is LIVE and viewport-independent; the degenerate state is registered, not guarded |
1204
1214
  | Overlap divider collapse | With the middle band fully collapsed no divider renders, and the leading / trailing fill fragments butt directly (seam re-exposed) | — | Divider pixels live only on scroll-band pixels (structural placement rule); a collapsed middle band has none |