@aiquants/spreadsheet 0.13.1 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to `@aiquants/spreadsheet` are documented here.
 
+## 0.15.0 (2026-10-26)
+
+グリッドがコピーと貼り付けに使う TSV の符号化を、グリッドを読み込まない副パス `@aiquants/spreadsheet/tsv` として公開する。
+barrel も同じ関数を公開し続けるので、既存の import と描画・操作の動作は変わらない。
+
+- **新機能 — `@aiquants/spreadsheet/tsv`**: `parseTsv` と `serializeTsv` (barrel と同じ関数で、定義は 1 つ) を、React も
+  `@aiquants/virtualscroll` も読まない入口から公開する (約 1 KB)。グリッドを遅延で読み込むホストが、最初の描画の時点で表の文字を
+  読める (サーバーで描く代わりの表と、それと同じクライアントの最初の描画)。barrel から `parseTsv` だけを読むと、束ねる道具は
+  グリッドの大半を落とせない (約 260 KB と React・virtualscroll の import が残る) ため、別の入口にした。
+- **ビルド**: 入口は `index`・`view`・`tsv` の 3 つ。符号化のモジュールは `index` と `tsv` が共有する塊 (`tsv-<hash>.js` /
+  `.cjs`) に入り、どちらもそれを読む。
+- **peer**: `@aiquants/virtualscroll` の peer の範囲は `^3.22.0` のまま (0.14.0 と同じ)。
+- **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **94 ファイル 4,097 テスト** 全緑 —
+  0.14.0 出荷時の 93 ファイル 4,094 に v0.15 進行分 +3 (新規 `tsvEntry` 2、0.14.0 節の出荷時凍結ピンで `hxCensus` +1)。
+  barrel (`src/index.ts`) の export は変わらない。`tsc --noEmit` / biome 0。
+
+## 0.14.0 (2026-10-26)
+
+グリッドの固定の寸法と拡大率の規則を、グリッドを読み込まない副パス `@aiquants/spreadsheet/view` として公開する。グリッド自身も
+同じ定義を読むので、描画と操作の動作は変わらない。
+
+- **新機能 — `@aiquants/spreadsheet/view`**: 列見出しの帯の高さ `SPREADSHEET_COLUMN_HEADER_HEIGHT_PX` (24)、行見出しの帯の幅
+  `SPREADSHEET_ROW_HEADER_WIDTH_PX` (64)、スクロールバーの太さ `SPREADSHEET_SCROLLBAR_SIZE_PX` (12)、拡大率の範囲
+  `SPREADSHEET_ZOOM_MIN` / `SPREADSHEET_ZOOM_MAX` (0.25 / 4)、範囲へ切る `clampSpreadsheetZoom` (有限でない値は `RangeError`)、
+  操作と同じ 0.1 刻みの `stepSpreadsheetZoom` (範囲では切らない) を公開する。React も `@aiquants/virtualscroll` も読まないため、
+  グリッドを遅延で読み込むホストが、読み込む前に箱の大きさを決めたり (サーバー描画の代わりの表など)、自前の拡大縮小のボタンを
+  グリッドと同じ数で動かしたりできる。
+- **定義は 1 か所**: グリッドの拡大率の切り詰めと刻み、スクロールバーの太さ (内部の `SCROLLBAR_WIDTH` は廃止) は `view` の定義を
+  読む。列見出しの帯の高さと行見出しの帯の幅は、スタイルシートのカスタムプロパティ (`--aqsp-col-header-height` /
+  `--aqsp-row-header-width`) と同じ値であることを試験で確かめる。
+- **peer の下限が上がる**: `@aiquants/virtualscroll` の peer の範囲が `^3.22.0` になる (ワークスペースの版から公開時に展開する範囲。
+  0.13.1 は `^3.8.0`)。コードが 3.22 の機能を使うわけではないが、それより古い virtualscroll と組み合わせる利用者は peer の警告を
+  受けるので、virtualscroll を 3.22 へ上げる。
+- **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **93 ファイル 4,094 テスト** 全緑 —
+  0.13.0 出荷時の 92 ファイル 4,083 に v0.14 進行分 +11 (新規 `view` 10、既存 `viewStore` −1 (スクロールバーの太さの試験を
+  `view` へ移した)、0.13.0 / 0.13.1 節の出荷時凍結ピンで `hxCensus` +2)。barrel (`src/index.ts`) の export は変わらない。
+  `tsc --noEmit` / biome 0。
+
 ## 0.13.1 (2026-10-03)
 
 公開物から社内の作業資料への参照を除き、公開の経路に漏洩ガードを通す。API と描画の動作は変わらない。

package/README.md

@@ -50,7 +50,7 @@ deep-reach proof route.
 pnpm add @aiquants/spreadsheet @aiquants/virtualscroll
 ```
 
-`react` / `react-dom` (`^19.2`) and `@aiquants/virtualscroll` (`^3.7.0` — its label catalogs back the `locale` prop) are peer dependencies.
+`react` / `react-dom` (`^19.2`) and `@aiquants/virtualscroll` are peer dependencies (the ranges are `peerDependencies` in the published `package.json`; the code itself needs virtualscroll 3.7.0 or later, whose label catalogs back the `locale` prop).
 
 > **Browser floor**: the built-in cell display formats (v0.7) require `Intl.NumberFormat` v3
 > (string mathematical-value input + `signDisplay: "negative"`) — **Chrome/Edge 106+, Firefox 116+,
@@ -458,8 +458,8 @@ keyboard input — this is what makes IME composition, clipboard events, and 16M
 - `labels.sinkAriaLabel` labels the input surface (its catalog value explains the Escape hand-off — in English by default, in
   Japanese under `locale="ja"`); `labels.rootAriaLabel` labels the grid container (`"Spreadsheet"` / `"スプレッドシート"`). Both
   live in the `labels` prop (v0.8 — the former `sinkAriaLabel` / `rootAriaLabel` props were folded into it; together with the 19
-  popover strings they are the 21 package-owned keys, and the 7 engine keys name the grid scrollbars' arrows, edge pills and
-  empty state). The `locale` prop picks the catalog (`SPREADSHEET_LABEL_CATALOGS[locale]`), and an omitted or `undefined` key
+  popover strings they are the 21 package-owned keys, and the engine keys (every `VIRTUAL_SCROLL_LABEL_KEYS` entry) name the
+  grid scrollbars' chrome, such as the arrows and edge pills, and the empty state). The `locale` prop picks the catalog (`SPREADSHEET_LABEL_CATALOGS[locale]`), and an omitted or `undefined` key
   keeps that catalog's value. Switching `locale` localizes both names together; if you override them, **override both**, and a
   replacement `sinkAriaLabel` **must keep the Escape-exit notice** — the word `Escape` must appear, otherwise the grid throws a `RangeError` while rendering: Escape moves
   focus from the sink to the root, and without the notice (or with an unlabeled landing point) screen-reader users are stranded
@@ -574,7 +574,7 @@ the zoom keys shadow that chord (the zoom token space `Ctrl+Alt` and `Ctrl+Alt+S
 `preventDefault`ed are respected and ignored. In controlled mode, gestures step from the last *requested* value: a parent that rejects a
 request without re-rendering leaves the next detent continuing from the rejected value until any re-render re-syncs it —
 enforce a tighter range by clamping in `onZoomChange` and re-rendering with the clamped value. Wheel/key steps land on the nearest 0.1 detent in the travel direction
-(from the 0.25 bound the first step up is 0.3); Alt+Wheel with no vertical component (tilt wheel / horizontal pan) is
+(from the 0.25 bound the first step up is 0.3; the same step is `stepSpreadsheetZoom` of `@aiquants/spreadsheet/view`); Alt+Wheel with no vertical component (tilt wheel / horizontal pan) is
 passed through to the browser.
 
 Navigation is **visible-track aware**: arrows and Shift-arrows step to the next *visible* row/column (a hidden run is
@@ -734,7 +734,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
 | `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. |
 | `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". |
 | `enableResizeUI` | `boolean` | Default `true`. `false` removes resize strips **and unhide markers** — hidden tracks then have no in-package restore path (imperative API only). |
-| `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 [0.25, 4]; a non-finite value (NaN / ±Infinity) throws a `RangeError` (fail-fast — no silent substitution). |
+| `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). |
 | `enableFillHandle` | `boolean` | Default `true`. Fill writes through `applyEdits` — disable for read-only adapters. |
 | `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). |
 | `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". |
@@ -744,7 +744,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
 | `onUndoRequest` / `onRedoRequest` | `() => void` | `Ctrl+Z` / `Ctrl+Y` / `Ctrl+Shift+Z` relays. |
 | `formatCellAnnouncement` / `formatSelectionAnnouncement` | formatter | Opt-in screen-reader announcements (see above). |
 | `formatCommandAnnouncement` | `(ctx: { command: SpreadsheetCommand; state: boolean \| null }) => string` | Opt-in (v0.8) live-region text after a successful format command; `state` is the toggle's post-state (`bold` / `italic` / `underline` / `strikethrough` / colour toggles), `null` for non-toggle commands. Also makes the live region render on its own. |
-| `labels` | `SpreadsheetLabelOverrides` (any subset of the 28 `SpreadsheetLabels` keys) | v0.8 — replaces the `sinkAriaLabel` / `rootAriaLabel` props (folded in) and names every UI chrome string: the 7 engine keys shared with `@aiquants/virtualscroll` (`scrollUp`, `scrollDown`, `scrollLeft`, `scrollRight`, `scrollToTop`, `scrollToBottom`, `noItems` — they reach the grid scrollbars) 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). |
+| `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). |
 | `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". |
 | `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. |
 | `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). |
@@ -817,9 +817,55 @@ that fails to parse `"unreadable"` — each fires `onClipboardUnavailable` and r
 called; `"empty"` means nothing was written (an own payload whose identity was suppressed, every cell skipped, a mode without cell
 aspects such as `columnWidths` — sizes may still have been applied).
 
+## View geometry and zoom rules (`@aiquants/spreadsheet/view`)
+
+`@aiquants/spreadsheet/view` publishes the grid's fixed geometry and its zoom rules without loading the grid (no React, no
+`@aiquants/virtualscroll`): a host can size a box for the grid before the grid itself is loaded (a lazily imported grid, a
+server-rendered placeholder) and drive the zoom from its own controls with exactly the numbers the grid uses. The grid reads the
+same definitions.
+
+| Export | Value / contract |
+| :--- | :--- |
+| `SPREADSHEET_COLUMN_HEADER_HEIGHT_PX` | `24` — the column-header band (`--aqsp-col-header-height`) |
+| `SPREADSHEET_ROW_HEADER_WIDTH_PX` | `64` — the row-header band (`--aqsp-row-header-width`) |
+| `SPREADSHEET_SCROLLBAR_SIZE_PX` | `12` — each scroll bar, reserved on both axes whether or not the grid scrolls |
+| `SPREADSHEET_ZOOM_MIN` / `SPREADSHEET_ZOOM_MAX` | `0.25` / `4` — the bounds of `zoom` |
+| `clampSpreadsheetZoom(value)` | Clamps into the bounds without quantizing; a non-finite value throws a `RangeError` |
+| `stepSpreadsheetZoom(value, direction)` | The gestures' 0.1 detent step (`1` in, `-1` out), unclamped: from an off-grid value it lands on the nearest detent in the travel direction (0.25 → 0.3 / 0.2) |
+
+At zoom 1 with uniform rows, a box that shows `n` rows exactly is
+`SPREADSHEET_COLUMN_HEADER_HEIGHT_PX + n × defaultRowHeight + SPREADSHEET_SCROLLBAR_SIZE_PX` px tall. Zoom buttons of a host that
+controls `zoom` step the same way the gestures do:
+
+```tsx
+import { clampSpreadsheetZoom, stepSpreadsheetZoom } from "@aiquants/spreadsheet/view"
+
+const zoomIn = () => setZoom((zoom) => clampSpreadsheetZoom(stepSpreadsheetZoom(zoom, 1)))
+// <Spreadsheet zoom={zoom} onZoomChange={setZoom} … />
+```
+
+## TSV codec (`@aiquants/spreadsheet/tsv`)
+
+`@aiquants/spreadsheet/tsv` publishes `parseTsv` and `serializeTsv` — the codec the grid copies and pastes with — without
+loading the grid (no React, no `@aiquants/virtualscroll`; about 1 KB). A host that lazily imports the grid can still read
+the grid's text during the first render, for example to server-render a placeholder table of the rows the grid will show
+(the same markup on the client, so hydration matches). The barrel exports the same two functions (one definition), so
+code that already loads the grid keeps importing them from `@aiquants/spreadsheet`.
+
+| Export | Contract |
+| :--- | :--- |
+| `parseTsv(text)` | A rectangular `string[][]`: one trailing line terminator dropped, empty text read as one empty cell (`[[""]]`), ragged rows padded with `""`; a quoted field is unquoted only when its content holds a tab or a line break (a value merely wrapped in quotes is literal text, as Excel writes it) |
+| `serializeTsv(matrix)` | Rows joined with CRLF and a trailing CRLF; only a field with a tab or a line break is quoted (its quotes doubled) — every other field, quotes included, is written verbatim (Excel's behaviour) |
+
+```tsx
+import { parseTsv } from "@aiquants/spreadsheet/tsv"
+
+const rows = parseTsv(text) // ready before `import("@aiquants/spreadsheet")` resolves
+```
+
 ## Clipboard utilities (public)
 
-`parseTsv` / `serializeTsv` / `estimatePasteCellCount` / `expandPaste` are exported for building custom paste UIs and
+`parseTsv` / `serializeTsv` (also at `@aiquants/spreadsheet/tsv`) / `estimatePasteCellCount` / `expandPaste` are exported for building custom paste UIs and
 importers with the exact same Excel-compatible semantics the grid uses. `enumerateRangeCells`, `makeRange`,
 `rangeContains`, `rangeSize`, `columnIndexToName`, `columnNameToIndex` round out the toolkit. The named unions
 `SpreadsheetDirection` (`"up" | "down" | "left" | "right"` — the `findDataEdge` direction), `SpreadsheetOperation` (the