@aiquants/spreadsheet 0.20.1 → 0.20.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,155 @@
2
2
 
3
3
  All notable changes to `@aiquants/spreadsheet` are documented here.
4
4
 
5
+ ## 0.20.3 (2026-11-19)
6
+
7
+ ### Added
8
+
9
+ - **Header sorting and per-column filtering — the `sortFilter` prop** (`SpreadsheetSortFilter`). The host keeps the state
10
+ (`SpreadsheetSortFilterState`: at most one sorted column and one filter per column key, each `{ mode: "exact", values }`
11
+ or `{ mode: "fuzzy", query }`) and the rows: it matches and reorders its adapter when `onStateChange` reports a new
12
+ state, so the package never orders or drops a row and depends on no matching library. The package draws the controls
13
+ on the last header row and decides when the state may change.
14
+ - Pressing a sortable column's header cell cycles ascending → descending → unsorted (another column's header starts
15
+ at ascending): a mouse click — the primary button without Shift / Ctrl / Meta / Alt, after the press passed the
16
+ commit gate and selected the cell, released on the same cell before moving 6 px — or a finger / pen tap released on
17
+ the same cell before moving 6 px (the distance at which the scrolling pane starts a drag; a `pointercancel` or a
18
+ second press drops it). The tap's own press has its default prevented so the browser's compatibility mouse press
19
+ cannot pull the focus onto the frozen band, and the focus is on the grid after the tap.
20
+ - Every header cell with controls shows a ▼ button at its inline end (44 px wide over the cell's height inside its
21
+ 1 px grid line — a header row of 45 px or more gives a 44 px square target). Pressing it, or Alt+ArrowDown on that
22
+ cell (the `openValidationList` chord, so a rebinding moves it too; a read-only cell is not refused, sorting and
23
+ filtering change the view), opens the column menu: sort ascending / descending / clear, the match mode where the
24
+ column offers both, the exact value list or the fuzzy query, apply, clear this column, clear all filters. The press
25
+ on ▼ never reaches the selection.
26
+ - The exact value list comes from `getFilterValues(columnKey, state, signal)`, counted over the rows the other
27
+ columns' filters keep; it loads the first time the exact section shows, the signal aborts when the menu closes and
28
+ a late answer is dropped, a rejection or a malformed list (not `{ value, label, count }` rows, a negative or
29
+ fractional count, a repeated value) shows "Could not load the values". At most 500 rows mount and one row counts
30
+ the rest; a value search (NFKC, lower case, substring of the shown text) narrows it, and "Select all" / "Clear all"
31
+ act on the values it matches. An empty label shows `(Blanks)`. The first checks are the column's exact values, or
32
+ every value. Applying with every listed value checked lifts the column's filter; applying nothing is not possible; a
33
+ blank fuzzy query lifts the filter.
34
+ - Before any change the in-place edit is committed exactly as Enter commits it (an IME composition is confirmed
35
+ first); a refusal (`onEditRejected`, `onValidationRejected`, `onReadOnlyRejected`) changes nothing. Then the column
36
+ menu, the interactive popover and the note tip close, the copy / cut marquee is dropped (they all point at
37
+ positions), and `onStateChange` is called once — never with a state of the same shape. The selection keeps its
38
+ position; a host that wants the same row selected after reordering calls the handle's `setSelection`.
39
+ - Options: `defaults` (`SpreadsheetColumnSortFilterOptions` — `sortable`, `filterable`, `matchModes`,
40
+ `defaultMatchMode`) for every column and `getColumnOptions(columnKey)` for the members one column overrides;
41
+ `getColumnKey(col)` names each column (`null` = no controls). `getFilterValues` is required when a column offers
42
+ exact matching.
43
+ - A malformed prop, option or state is a `RangeError` during render: no header row, an unknown or mistyped member,
44
+ empty / unknown / repeated match modes, a default mode the column does not offer, an empty or repeated column key,
45
+ exact matching without `getFilterValues`, a state naming an unknown column, sorting a column that cannot sort,
46
+ filtering a column that cannot filter or using a mode the column does not offer. An empty grid (no row or no column)
47
+ draws no control and validates nothing until data arrives.
48
+ - The sorted header cell carries `aria-sort` (`ascending` / `descending`) and `data-aqsp-sort`, a filtered one
49
+ `data-aqsp-filtered` (and a funnel on its ▼, so a filtered column differs by shape), every header cell with controls
50
+ `data-aqsp-column-controls`; the ▼ is named after the column with `columnMenu`, plus `columnMenuFiltered` while
51
+ filtered. 18 labels in `en` and `ja`.
52
+ - Types `SpreadsheetSortFilter`, `SpreadsheetSortFilterState`, `SpreadsheetColumnFilter`,
53
+ `SpreadsheetColumnSortFilterOptions`, `SpreadsheetFilterValue`, `SpreadsheetMatchMode`, `SpreadsheetSortDirection`.
54
+
55
+ Without the prop the DOM and the behaviour are those of 0.20.2.
56
+
57
+ ### Verification
58
+
59
+ - **公開面**: 公開面は `index.ts` の値 44 + 型 111 = 155 export (`sortFilter` の型 7 つを追加)。
60
+ - **DOM 属性**: `data-aqsp-column-controls`・`data-aqsp-sort`・`data-aqsp-filtered`・`data-aqsp-column-menu-button`・
61
+ `data-aqsp-glyph`・`data-aqsp-column-menu-action`・`data-aqsp-column-menu-mode`・`data-aqsp-column-menu-input`・
62
+ `data-aqsp-column-menu-values`・`data-aqsp-column-menu-value`・`data-aqsp-column-menu-status` の 11 種を追加 — リテラル
63
+ census は 98 種 (dataset 直書きの同値抑止署名キー 4 種を加えた総数は 102。分冊 05 §10・分冊 00 §3.2)。渡さない表には
64
+ 1 つも付かない。
65
+ - **色の対**: `designTokens` の文字と面の対に 1 つ (品書きの値の件数 `--_aqsp-muted-text` をホバーした値の行の面
66
+ `--_aqsp-hover-surface` に — 7.01:1)、印と面の対に 1 つ (▼ の焦点の輪と見出しの行のマスの焦点の枠 `--_aqsp-accent` を
67
+ 見出しの行の面に — 4.70:1) を足した (21 対・19 対。試験の数は変わらない)。
68
+ - **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **106 ファイル 4,492 テスト** 全緑 — 0.20.2 出荷時の
69
+ 103 ファイル 4,384 に v0.20.3 進行分 +108 (新規 `sortFilterModel` 45 — 検めの全ての `RangeError`・全体と各列の指定の
70
+ 重なり・状態の純関数・同じ形の比べ・値の一覧の検め・探す欄の照合、新規 `ColumnMenu` 26 — 節の出し分け・初めの方法と印と
71
+ 焦点・読み込みと拒みと止まる signal・StrictMode の遅れた答え・500 件の上限・探す欄・当てる決まり・閉じ方・置き直し、
72
+ 新規 `sortFilter` 33 — 渡さない表・属性と ▼ の名前・マウスの押下と指とペンの叩き・▼・Alt+↓・手順・描く時の
73
+ `RangeError`・空の表・品書きを閉じる時、`labels` +2 (言葉 18 の en と ja)、`popoverStyles` +1 (品書きの CSS)、0.20.2 節の
74
+ 出荷時凍結ピンで `hxCensus` +1)。変異 16 件は全て赤: 手順の確定の関門を外す・断りでも変える・写しの印を捨てない・同じ形でも
75
+ 知らせる・▼ の押下を選択へ渡す・叩きの閾を外す・叩きの後に焦点を戻さない・Alt+↓ で読むだけの断りを通す・全部の印で
76
+ 外さない・止めた読み込みの答えを捨てない・修飾キーでも並べ替える・見出しの指の押下の既定を止めない・▼ の指の押下の
77
+ 既定を止めない・品書きの前の関門を外す・`aria-sort` を付けない・表の外へ移った焦点も戻す。
78
+ - **検証 — E2E**: 新規 `sort-filter` 9 (デモ `/sort-filter` — 打ちかけの入力と変換 (CDP の IME 経路) が並べ替えの前に
79
+ 打ち始めた行 (鍵で同じ行) へ確定すること、見出しの Alt+↓ と Escape で焦点が表へ戻ること、45 px の見出しの行で ▼ が
80
+ 44 px 四方、完全一致とあいまい検索の往復、指の叩きの並べ替えと焦点、指で ▼ を開いて 2 度目で閉じること、幅 320 px の窓で
81
+ 品書きが窓の外へ出ないこと)。実の Chromium で、叩きの互換のマウスの押下が `pointerup` の後に焦点を止めた帯の行の箱へ
82
+ 移すことと、▼ の当たりがマスの罫線の内側 (44 px の行で 43 px) であることを見つけ、叩きと ▼ の押下の既定を止め、見出しの
83
+ 行を 45 px とした (直す前は 3 件が赤)。E2E の総数は 27 ファイル 309 テスト。`tsc --noEmit` / biome / markdownlint 0。
84
+ - **触れていないこと**: 実機の指 (iOS Safari・Android Chrome) と実機の IME。読み上げ (`aria-sort` と ▼ の名前) は DOM の
85
+ 属性で確かめ、スクリーンリーダーでは聞いていない。
86
+
87
+ ## 0.20.2 (2026-11-18)
88
+
89
+ ### Added
90
+
91
+ - **The handle's `setSelection(selection, options?)`** places the selection — its ranges, anchor and active cell — where
92
+ the host decides: a row the page selects from its URL, the same month after the host moved the window a year, the row
93
+ a re-sort put elsewhere. It takes the shape `getSelection()` returns (at least one range, each start at most its end,
94
+ the anchor inside the last range, the active cell inside some range, every bound a whole number inside the grid) and
95
+ throws a `RangeError` for anything else, keeps a copy, accepts a hidden row or column, and goes through the gestures'
96
+ write path: `onSelectionChange` fires once (not for an equal selection), the announcement formatters run, the active
97
+ cell's input message shows and the next Arrow key moves from the placed active cell. It returns `false` and changes
98
+ nothing while a cell is being edited (the session is never closed for it) or a pointer drag is in flight.
99
+ `{ scroll: true }` brings the active cell into view with an Arrow key's minimal scroll; without it no scroll position
100
+ changes. Focus does not move. Option type `SetSelectionOptions`.
101
+ - **`onSelectionChange` passes the reason as its second argument** (`SelectionChangeReason`): `"user"` for gestures,
102
+ chords, commands and pastes (the commands and pastes a host runs through the handle included), `"setSelection"` for a
103
+ placement, `"sheetSwitch"` for the reset to A1 when the adapter identity changes, `"countShrink"` for the clamp after
104
+ the same adapter's `rowCount` / `colCount` shrank. A host no longer guesses which notices are the user's; a
105
+ one-parameter callback keeps working.
106
+ - **`onEditSessionChange(session)` and the handle's `getEditSession()`** report the in-place edit session (`EditSession`
107
+ = `{ cell, mode: "edit" | "replace" }`): the session right after it opens (F2, a double-click, a printable key, an IME
108
+ composition, `startEdit`) and `null` right after it closes — a commit (after `applyEdits` returned, before the Enter /
109
+ Tab that committed moves the active cell), a cancel, the focus leaving the grid, an adapter switch, a count shrink that
110
+ removed the cell, an editing Ctrl+Enter fill. A refused commit keeps the session open and reports nothing.
111
+ `getEditSession()` returns the object last reported, or `null`.
112
+ - **The handle's `commitEdit()`** (`CommitEditOutcome`) commits the open session exactly as Enter does — the strict
113
+ validation gate, the read-only re-check, `applyEdits` when the text changed — without moving the active cell, for a
114
+ host that saves from a key of its own while the focus stays in the grid: `"committed"` (the session closed),
115
+ `"rejected"` (refused through `onEditRejected`, `onValidationRejected` or `onReadOnlyRejected` as an Enter's would; the
116
+ session stays open with the typed text) or `"idle"` (no session). A composition in flight is confirmed first, as a
117
+ press elsewhere in the grid confirms it.
118
+
119
+ ### Fixed
120
+
121
+ - **Ctrl+Enter (`fillSelection`) pressed during an IME composition fills on the first press.** The composition guard
122
+ dropped every keydown of an open composition, so the first Ctrl+Enter only confirmed the composition and a second
123
+ press filled; a press within 50 ms after a confirmation was dropped too, as the window that skips Safari's confirming
124
+ Enter / Escape looked at the key only. Now the editing column's `fillSelection` chord — read from the physical key
125
+ (`event.code`), so a chord rebound through `shortcuts` too — is remembered while the composition is open and runs once
126
+ in the task after `compositionend`, with the confirmed text, when that text is not empty and the session is still
127
+ open; a chord arriving right after the composition ended (Safari fires `compositionend` before the confirming keydown,
128
+ and the 50 ms window) runs at once. A plain Enter during a composition still only confirms it, any other key during
129
+ the composition forgets the chord, a cancelled composition fills nothing (the session it opened starts empty, and
130
+ filling would clear every selected cell), and the IME keydown itself is still never `preventDefault`ed. Every other
131
+ chord pressed during a composition stays with the IME.
132
+
133
+ ### Verification
134
+
135
+ - **公開面**: 公開面は `index.ts` の値 44 + 型 104 = 148 export (型 `EditSession`・`CommitEditOutcome`・
136
+ `SelectionChangeReason`・`SetSelectionOptions` を追加)。DOM 属性は 0.20.1 と同じ。
137
+ - **検証 — 走行台帳 (census の錨は本未リリース節)**: 単体 / 統合 **103 ファイル 4,384 テスト** 全緑 — 0.20.1 出荷時の
138
+ 101 ファイル 4,341 に v0.20.2 進行分 +43 (新規 `hostControl` 24 — 置く口の置き方・写し・入力中とドラッグ中の断り・形の
139
+ 誤り・`scroll`・隠した行、通知の 4 つの理由、入力のセッションの開閉と `applyEdits`・Enter の移動との順、`commitEdit` の
140
+ idle・確定・同じ字・3 つの断り・変換中、新規 `imeFillSelection` 10 — Chromium と Safari の順・確定の直後の 50 ms の窓・
141
+ 素の Enter・取り消した変換・途中の別のキー・付け替えたチョード・閉じた入力・2 回押し・入力していない時、`selectionState`
142
+ +8 (`placedSelectionOf`)、0.20.1 節の出荷時凍結ピンで `hxCensus` +1)。`pointing` は件数を変えずに通知の理由を照らす。
143
+ 変異 11 件は全て赤: 変換中の keydown を扱わない (4 件)・取り消した変換でも埋める (1)・別のキーで覚えを捨てない (1)・閉じた
144
+ 入力でも埋める (2)・入力中でも置く (1)・ドラッグ中でも置く (1)・写しでなく渡された物を持つ (3)・`scroll` を無視する (1)・
145
+ 切り替えの理由を `"user"` にする (1)・閉じたことを知らせない (5)・断りを確定と言う (3)。
146
+ - **検証 — E2E**: `editing` +1 (23 テスト)。実の Chromium で CDP の IME 経路
147
+ (`Input.imeSetComposition` → IME が処理した Ctrl+Enter の `rawKeyDown` → `Input.insertText`) を通し、確定した字で選んだ
148
+ 3 マスが 1 回で埋まり、届いた keydown が key `Process`・keyCode 229・`isComposing: true` で既定を止めないことを確かめた
149
+ (`AQSP_E2E_PORT=5279 playwright test tests/e2e/editing.spec.ts` で 23 passed)。直しの要の行を外すと 1 マスも埋まらず赤。
150
+ E2E の総数は 26 ファイル 300 テスト。`tsc --noEmit` / biome / markdownlint 0。
151
+ - **触れていないこと**: 実機の IME (Windows の Microsoft IME と Chrome / Edge・macOS の Safari)。Safari の順
152
+ (`compositionend` が先) は jsdom の上で出来事の順を写して確かめた。
153
+
5
154
  ## 0.20.1 (2026-11-14)
6
155
 
7
156
  ### Fixed
package/README.md CHANGED
@@ -27,6 +27,10 @@ deep-reach proof route.
27
27
  `--aqsp-frame-width` (`2px`), scrolling with the cells and scaled by the zoom like their lines; frozen panes join into
28
28
  one seamless frame, and while it is set the highlight bands, the freeze dividers and the clip marquee stay inside it —
29
29
  see "Framing a range"
30
+ - 🔽 **Header sort and column filters** (v0.20.3 — ADR-35): `sortFilter` puts a sort press and a ▼ menu (sort, an
31
+ exact-match value list with a search box, fuzzy text, apply / clear) on the last header row. The host keeps the state
32
+ and the row order; the grid commits an open edit before every change and reports it once through `onStateChange` —
33
+ see "Sorting and filtering from the header"
30
34
  - 🔒 **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,
31
35
  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
32
36
  `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,
@@ -494,7 +498,7 @@ keyboard input — this is what makes IME composition, clipboard events, and 16M
494
498
  - `labels.sinkAriaLabel` labels the input surface (its catalog value explains the Escape hand-off — in English by default, in
495
499
  Japanese under `locale="ja"`); `labels.rootAriaLabel` names the grid's root (the Escape landing point) and the grid, unless `labelledBy` names both (`"Spreadsheet"` / `"スプレッドシート"`). Both
496
500
  live in the `labels` prop (v0.8 — the former `sinkAriaLabel` / `rootAriaLabel` props were folded into it; together with the 19
497
- popover strings they are the 21 package-owned keys, and the engine keys (every `VIRTUAL_SCROLL_LABEL_KEYS` entry) name the
501
+ popover strings and the 18 column-menu strings (v0.20.3) they are the 39 package-owned keys, and the engine keys (every `VIRTUAL_SCROLL_LABEL_KEYS` entry) name the
498
502
  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
499
503
  keeps that catalog's value. Switching `locale` localizes both names together; if you override them, **override both**, and a
500
504
  replacement `sinkAriaLabel` **must keep the Escape-exit notice** — the word `Escape` must appear, otherwise the grid throws a `RangeError` while rendering: Escape moves
@@ -607,7 +611,7 @@ mode uses system colours only). `src/styles/designTokens.spec.ts` pins all of th
607
611
  | `--aqsp-strong-text` | `#111827` | Comment authors |
608
612
  | `--aqsp-separator` | `#f3f4f6` | Lines between comments |
609
613
  | `--aqsp-button-surface` | `#f9fafb` | Popover buttons |
610
- | `--aqsp-hover-surface` | `#f3f4f6` | Hovered buttons, options and the close glyph |
614
+ | `--aqsp-hover-surface` | `#f3f4f6` | Hovered buttons, options, the column menu's value rows and the close glyph |
611
615
  | `--aqsp-hover-border` | `#9ca3af` | Hovered button border |
612
616
  | `--aqsp-primary-surface` | `#134dce` | Primary buttons (Save, Post) |
613
617
  | `--aqsp-primary-hover-surface` | `#173faf` | Hovered primary button |
@@ -650,7 +654,7 @@ formula; the three pairs below 7:1 before v0.16 were re-solved by changing light
650
654
  | `--aqsp-link` `#163ba5` on `--aqsp-surface` `#ffffff` (was `#1d4ed8`, 6.70) | 9.53 |
651
655
  | `--aqsp-link` on `--aqsp-header-row-surface` `#f3f4f6` / under the selection fill on the surface / on the header row | 8.66 / 7.74 / 7.05 |
652
656
  | `--aqsp-text` `#1f2937` on `--aqsp-surface` / `--aqsp-header-row-surface` / under the selection fill on each | 14.68 / 13.34 / 11.92 / 10.86 |
653
- | `--aqsp-muted-text` `#4e535e` on `--aqsp-surface` / `--aqsp-danger-surface` / `--aqsp-note-tip-surface` (was `#6b7280`, 4.83) | 7.71 / 7.05 / 7.44 |
657
+ | `--aqsp-muted-text` `#4e535e` on `--aqsp-surface` / `--aqsp-danger-surface` / `--aqsp-note-tip-surface` / `--aqsp-hover-surface` (the column menu's hovered value row) (was `#6b7280`, 4.83) | 7.71 / 7.05 / 7.44 / 7.01 |
654
658
  | `--aqsp-danger-text` `#a41919` on `--aqsp-surface` / `--aqsp-danger-surface` (was `#b91c1c`, 6.47) | 7.69 / 7.03 |
655
659
  | `--aqsp-primary-text` `#ffffff` on `--aqsp-primary-surface` `#134dce` / `--aqsp-primary-hover-surface` `#173faf` (was `#2563eb`, 5.17) | 7.05 / 8.87 |
656
660
  | `--aqsp-title-text` `#374151` / `--aqsp-strong-text` `#111827` on `--aqsp-surface` | 10.31 / 17.74 |
@@ -681,6 +685,9 @@ The grid's own resize affordances are small on purpose, and the grid does not tr
681
685
  needs them provides 44 × 44 controls that run those commands (a toolbar, for instance).
682
686
  - The column-letter band is 24 px tall (`SPREADSHEET_COLUMN_HEADER_HEIGHT_PX`) and the row-number band 64 px wide; cells and
683
687
  header labels are as large as the host's rows and columns, and the zoom ladder enlarges every target with the grid.
688
+ - **The ▼ of `sortFilter`** (v0.20.3) is sized for a finger: the full height of the header cell and 44 px wide (a header
689
+ row of 45 px or more makes it 44 × 44 — see "Sorting and filtering from the header"), and Alt+↓ on the header cell
690
+ opens the same menu.
684
691
 
685
692
  ## Context-menu constraint (right-click)
686
693
 
@@ -791,9 +798,9 @@ track, and paging moves by exact viewport-height pixel geometry, so page landing
791
798
  | Ctrl+K | Link popover on the active cell | Consumed, not run (`onCommandBlockedWhileEditing`) | Same | `insertLink` |
792
799
  | Shift+F2 | Note popover on the active cell | Consumed, not run (`onCommandBlockedWhileEditing`) | Same | `insertNote` |
793
800
  | Ctrl+Alt+M | Comment thread popover on the active cell | Native | Native | `insertComment` |
794
- | Alt+ArrowDown | Validation list picker (cells with a `list` rule) | Native | Native | `openValidationList` |
801
+ | Alt+ArrowDown | Validation list picker (cells with a `list` rule); on a `sortFilter` header cell with controls, the column menu (v0.20.3 — also in a read-only grid) | Native | Native | `openValidationList` |
795
802
  | 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` |
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` |
803
+ | 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. Pressed during an IME composition (the chord is read from the physical key, so a rebound chord too), it fills once the composition commits, with the confirmed text — one press; a cancelled composition (nothing confirmed) fills nothing, and a session closed before then (the focus left the grid) is not filled. Every other chord pressed during a composition stays with the IME | Same | `fillSelection` |
797
804
  | 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` |
798
805
  | 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` |
799
806
  | 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` |
@@ -912,6 +919,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
912
919
  | Popovers (note / comment / link / list / message, e.g. `noteTitle`, `commentCount(2)`, `messageTitle`, `popoverClose`) | `Note`, `2 comments`, `Data validation`, `Close` | `メモ`, `2 件のコメント`, `データの入力規則`, `閉じる` |
913
920
  | Grid scrollbars (engine keys `scrollUp` … `noItems`) | `Scroll up`, `Scroll left`, `No items` | `上へスクロール`, `左へスクロール`, `項目がありません` |
914
921
  | Built-in validation messages (rules without `errorMessage`) | `Value must be a number greater than 5.` | `5 より大きい数値を入力してください。` |
922
+ | Column menu of `sortFilter` (v0.20.3, e.g. `columnMenu`, `filterApply`, `filterBlank`) | `Sort and filter`, `Apply`, `(Blanks)` | `並べ替えと絞り込み`, `当てる`, `(空白)` |
915
923
 
916
924
  - **Catalogs**: `SPREADSHEET_LABEL_CATALOGS.en` / `.ja` are frozen and exported; the 7 scrollbar keys are the values of
917
925
  `VIRTUAL_SCROLL_LABEL_CATALOGS` from `@aiquants/virtualscroll`, reused rather than restated. `labels` overrides any subset on top
@@ -939,6 +947,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
939
947
  | `frozenColumns` | `number` | Freezes the first N columns at the left edge (v0.5; default 0, LIVE). Engine-validated (integer in [0, 128] — `RangeError` otherwise; values beyond `colCount` freeze every column). Frozen columns stay visible at any horizontal scroll; `scrollToCell` / keyboard ensure-visible treat them as horizontal no-ops. |
940
948
  | `frozenRows` | `number` | Freezes the first N rows at the top edge (v0.6; default 0, LIVE — the row-axis twin of `frozenColumns`). Engine-validated (integer in [0, 128] — `RangeError` otherwise; values beyond `rowCount` freeze every row). Frozen rows stay visible at any vertical scroll; keyboard ensure-visible treats them as vertical no-ops. |
941
949
  | `headerRows` | `number` | v0.16 — the leading rows whose cells are column headers (default 0): `role="columnheader"` and the stylesheet's header-row paint (`--aqsp-header-row-*`). An integer from 0 to `frozenRows`; anything else is a `RangeError` during render |
950
+ | `sortFilter` | `SpreadsheetSortFilter` = `{ state; onStateChange; getColumnKey; defaults; getColumnOptions?; getFilterValues? }` | v0.20.3 — header sort and per-column filters on the last header row (see "Sorting and filtering from the header"). The host owns the state and the row order; the grid draws the sort press, the ▼ and the column menu, commits an open edit before any change and calls `onStateChange` once. A malformed `sortFilter` throws a `RangeError` during render (an empty grid checks nothing); omitted ⇒ the v0.20.2 DOM and behavior. |
942
951
  | `frozenTrailingColumns` | `number` | Freezes the **last** N columns at the right edge (v0.9; default 0, LIVE). Engine-validated pass-through, no second validation layer (integer in [0, 128] — `RangeError` otherwise); the effective count is clamped so the leading freeze wins the count space (`min(N, colCount − effectiveFrozenColumns)`). Trailing columns stay visible at any horizontal scroll — **except** when the leading + trailing extent exceeds the viewport: occluded trailing cells cannot be scrolled into view and keyboard focus draws no visible frame there (registered overlap consequence). `scrollToCell` / keyboard ensure-visible treat trailing targets as horizontal no-ops. An in-flight change of any of the four freeze props cancels every drag without restore. |
943
952
  | `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. |
944
953
  | `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. |
@@ -949,7 +958,8 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
949
958
  | `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. |
950
959
  | `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). |
951
960
  | `enableFillHandle` | `boolean` | Default `true`. Fill writes through `applyEdits` — disable for read-only adapters. |
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". |
961
+ | `onSelectionChange` | `(selection: SelectionState, reason: SelectionChangeReason) => 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". v0.20.2 — the second argument names the cause: `"user"` (gestures, chords, commands and pastes, the handle-run ones included), `"setSelection"` (the handle's `setSelection`), `"sheetSwitch"` (the reset to A1) and `"countShrink"` (the shrink clamp). See *Placing the selection and following the edit session*. |
962
+ | `onEditSessionChange` | `(session: EditSession \| null) => void` | v0.20.2 — the new `EditSession` (`{ cell; mode: "edit" \| "replace" }`) right after a session opens (F2, a double-click, a printable key, an IME composition, `startEdit`) and `null` right after it closes: a commit (after `applyEdits` returned, before the Enter / Tab that committed moves the active cell), a cancel, the focus leaving the grid, an adapter switch, a count shrink that removed the cell, an editing Ctrl+Enter fill. A refused commit keeps the session open and reports nothing; never called on unmount. Read when it fires (no remount). See *Placing the selection and following the edit session*. |
953
963
  | `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". |
954
964
  | `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". |
955
965
  | `onCopyMultiRange` | `() => void` | Notice that a multi-range copy serialized only the tail range. |
@@ -958,7 +968,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
958
968
  | `formatCellAnnouncement` / `formatSelectionAnnouncement` | formatter | Opt-in screen-reader announcements (see above). |
959
969
  | `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. |
960
970
  | `formatResizeAnnouncement` | `(ctx: { command: SpreadsheetCommand; axis: "row" \| "column"; index: number; size: number }) => string` | v0.16 — opt-in live-region text after a keyboard resize (`increaseColumnWidth` / `decreaseColumnWidth` / `increaseRowHeight` / `decreaseRowHeight` / `autoFitColumnWidth`): the active track's axis, index and new size in CSS px. Omit for silence (no built-in strings); shares the announcement debounce |
961
- | `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). |
971
+ | `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 39 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`, and the v0.20.3 column-menu keys `columnMenu`, `columnMenuFiltered`, `sortAscending`, `sortDescending`, `sortClear`, `filterMatchMode`, `filterModeExact`, `filterModeFuzzy`, `filterSearchValues`, `filterSelectAll`, `filterSelectNone`, `filterBlank`, `filterLoading`, `filterLoadFailed`, `filterQuery`, `filterApply`, `filterClearColumn`, `filterClearAll`). 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). |
962
972
  | `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". |
963
973
  | `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. |
964
974
  | `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". |
@@ -1024,6 +1034,9 @@ await ref.current?.paste({ mode: "values" }) // menu path: Promise<
1024
1034
  ref.current?.getBaseFormat(cell) // the adapter's format (toolbar state)
1025
1035
  ref.current?.getPaintedFormat(cell) // base ⊕ conditional formats (what the user sees)
1026
1036
  ref.current?.getSelection()
1037
+ ref.current?.setSelection(selection, { scroll: true }) // places ranges / anchor / active; false while editing or dragging (v0.20.2)
1038
+ ref.current?.getEditSession() // { cell, mode } while a cell is being edited, else null (v0.20.2)
1039
+ ref.current?.commitEdit() // commits the open session like Enter, without moving: "committed" | "rejected" | "idle" (v0.20.2)
1027
1040
  ref.current?.startEdit("edit") // opens the editor without the virtual-keyboard invitation
1028
1041
  ref.current?.openPopover("note") // RangeError when the kind is disabled / its capability undeclared
1029
1042
  ref.current?.focus({ preventScroll: true }) // focuses the hidden input and re-arms it when idle
@@ -1111,6 +1124,132 @@ range's cells:
1111
1124
  The demo's `/fit` route has a frame switch and a range select (every cell, or `D1:F4`), with pins (a frozen header
1112
1125
  row, footer row and first column) and the row and column bands to see it meet the dividers and the bands.
1113
1126
 
1127
+ ## Placing the selection and following the edit session (v0.20.2)
1128
+
1129
+ A host that keeps its own state beside the grid — a row the page selects from its URL, changes from other people that
1130
+ must not land on the cell being typed into, a save button or a Ctrl+S of its own — has four seams:
1131
+
1132
+ ```tsx
1133
+ const ref = useRef<SpreadsheetHandle>(null)
1134
+ <Spreadsheet
1135
+ ref={ref}
1136
+ adapter={adapter}
1137
+ onSelectionChange={(selection, reason) => { if (reason === "user") followTheUser(selection) }}
1138
+ onEditSessionChange={(session) => setEditingCell(session === null ? null : session.cell)}
1139
+ />
1140
+ ref.current?.setSelection({ ranges: [{ startRow: 8, startCol: 0, endRow: 8, endCol: 4 }], anchor: { row: 8, col: 0 }, active: { row: 8, col: 0 } }, { scroll: true })
1141
+ if (ref.current?.commitEdit() !== "rejected") save()
1142
+ ```
1143
+
1144
+ - **`setSelection(selection, options?)`** places the ranges, the anchor and the active cell. It takes the shape
1145
+ `getSelection()` returns: at least one range, each start at most its end, the anchor inside the last range and the
1146
+ active cell inside some range, every bound a whole number inside the grid — anything else is a `RangeError` (a grid
1147
+ without rows or columns has no cell, so every placement throws there). The grid keeps a copy, so the object may be
1148
+ reused; a hidden row or column is a valid place. It goes through the same write path as a gesture:
1149
+ `onSelectionChange` fires once with `"setSelection"` (not for a selection equal to the current one), the announcement
1150
+ formatters run, the active cell's input message shows, and the next Arrow key moves from the placed active cell. It
1151
+ returns `false` and changes nothing while a cell is being edited (the session is never closed for it — the editor
1152
+ belongs to the cell being typed into) or a pointer drag is in flight. `{ scroll: true }` brings the active cell into
1153
+ view with an Arrow key's minimal scroll; without it no scroll position changes — pair it with `scrollToCell` for an
1154
+ alignment of your own. Focus does not move (call `focus()`), and an open popover keeps its cell.
1155
+ - **The `reason` of `onSelectionChange`** tells the user's moves apart from the others: `"user"` for gestures, chords,
1156
+ commands and pastes (also the commands and pastes the host runs through the handle for the user — `executeCommand`,
1157
+ `paste`), `"setSelection"` for a placement, `"sheetSwitch"` for the reset to A1 when the adapter identity changes,
1158
+ and `"countShrink"` for the clamp after the same adapter's `rowCount` / `colCount` shrank. A one-parameter callback
1159
+ keeps working.
1160
+ - **`onEditSessionChange(session)` and `getEditSession()`** report the in-place edit session — `{ cell, mode }` with
1161
+ `mode` `"edit"` (F2, a double-click, `startEdit("edit")`) or `"replace"` (a printable key, an IME composition,
1162
+ `startEdit("replace")`). The callback gets the session right after it opens and `null` right after it closes, whatever
1163
+ closes it: a commit (after `applyEdits` returned, before the Enter / Tab that committed moves the active cell), a
1164
+ cancel, the focus leaving the grid, an adapter switch, a count shrink that removed the cell, an editing Ctrl+Enter
1165
+ fill. A refused commit keeps the session open, so nothing is reported. `getEditSession()` returns the object last
1166
+ reported (or `null`); the callback is read when it fires and is not called on unmount.
1167
+ - **`commitEdit()`** commits the open session exactly as Enter does — the strict validation gate, the read-only
1168
+ re-check, `applyEdits` when the text changed (an unchanged text just closes the session) — but leaves the active cell
1169
+ where it is. `"committed"`: the session closed; `"rejected"`: refused, the session stays open with the typed text, and
1170
+ the refusal went through `onEditRejected` (`editSession: "kept"`), `onValidationRejected` or `onReadOnlyRejected` as
1171
+ an Enter's would; `"idle"`: no session was open. An IME composition in flight is confirmed first, as a press
1172
+ elsewhere in the grid confirms it (the hidden input blurs and takes the focus back). A save button that takes the
1173
+ focus has already committed through the focus leaving the grid, so it gets `"idle"`; a key listener that saves while
1174
+ the focus stays in the grid is what needs this call.
1175
+
1176
+ ## Sorting and filtering from the header (v0.20.3)
1177
+
1178
+ The grid draws the controls; the host keeps the state and the order of the rows. Pass `sortFilter` and the last header
1179
+ row (`headerRows - 1`, so `headerRows` must be 1 or more) gets the controls on every column that has a key and can sort
1180
+ or filter:
1181
+
1182
+ ```tsx
1183
+ const [state, setState] = useState<SpreadsheetSortFilterState>({ sort: null, filters: {} })
1184
+ const sortFilter = useMemo((): SpreadsheetSortFilter => ({
1185
+ state,
1186
+ onStateChange: (next) => {
1187
+ reorderRows(next) // match and reorder the rows your adapter reads (the grid sorts and drops nothing)
1188
+ setState(next)
1189
+ },
1190
+ getColumnKey: (col) => keyOfColumn(col), // a non-empty unique string, or null for a column without controls
1191
+ defaults: { sortable: true, filterable: true, matchModes: ["exact", "fuzzy"], defaultMatchMode: "exact" },
1192
+ getColumnOptions: (columnKey) => (columnKey === "memo" ? { filterable: false } : {}),
1193
+ getFilterValues: (columnKey, current, signal) => countValues(columnKey, current, signal),
1194
+ }), [state])
1195
+
1196
+ <Spreadsheet adapter={adapter} frozenRows={1} headerRows={1} sortFilter={sortFilter} />
1197
+ ```
1198
+
1199
+ - **The state and the options.** `state` is `{ sort: { columnKey, direction: "asc" | "desc" } | null, filters }`, where
1200
+ `filters` maps a column key to `{ mode: "exact", values }` or `{ mode: "fuzzy", query }` — keep it in your URL if you
1201
+ like. A column's options are `defaults` with the members `getColumnOptions(columnKey)` returns laid over them. The grid
1202
+ matches nothing: which rows an exact value list or a fuzzy text keeps, and how they compare, is yours.
1203
+ - **The header cells.** Every control column's cell on the last header row carries `data-aqsp-column-controls` and a ▼
1204
+ button (`data-aqsp-column-menu-button`, out of the Tab order) named after the column's displayed text; the sorted
1205
+ column's cell carries `aria-sort` and `data-aqsp-sort` (`asc` / `desc`), a filtered column's cell `data-aqsp-filtered`
1206
+ and a funnel glyph in its ▼ (shape, not only colour). Other columns carry no `aria-sort`.
1207
+ - **Sorting by a press.** On a sortable column's header cell, a mouse click (the primary button without Shift / Ctrl /
1208
+ Meta / Alt) or a tap of a finger or a pen cycles ascending → descending → no sort, when released on the same cell
1209
+ before moving 6 px. A mouse press still selects the header cell as before; a tap selects nothing and leaves the focus
1210
+ in the grid. A double-click is two presses (it cycles twice) and opens the editor on a writable header cell, so **make
1211
+ the header row read-only** (`isCellReadOnly: (row) => row < headerRows`, or `readOnly`).
1212
+ - **The column menu.** The ▼, or Alt+↓ on the header cell (even in a read-only grid — sorting and filtering change only
1213
+ the view), opens it: the sort buttons (sortable columns), the match-mode radios (a filterable column offering both
1214
+ modes), then for exact match a search box (a case- and width-insensitive substring, NFKC), Select all / Clear all for
1215
+ the values the search shows and the value list, or for fuzzy search a text box that Enter applies, and Apply / Clear
1216
+ this column's filter / Clear all filters. Escape closes it and returns the focus to the grid; the focus leaving it
1217
+ closes it (the focus returns only when it moved into the grid). The grid draws it itself — `renderPopover` and
1218
+ `popovers` never see it — and it and the other popovers replace each other.
1219
+ - **What Apply writes.** Exact match with every listed value checked removes the column's filter; some checked writes
1220
+ them in the list's order; none checked disables Apply. A value no longer listed (another column's filter removed it)
1221
+ is dropped by Apply. A blank fuzzy text removes the column's filter. A next state equal to the current one is not
1222
+ reported.
1223
+ - **When the state may change.** Every change — a press, a sort button, Apply, a clear — takes one path: an open cell
1224
+ edit is committed first as Enter would (an IME composition in flight is confirmed first; a refused commit changes
1225
+ nothing and is reported through `onEditRejected` / `onValidationRejected` / `onReadOnlyRejected` as usual), the menu,
1226
+ any open popover and the note tip close, the copy / cut marquee is discarded (it names positions, which will hold other
1227
+ rows), and `onStateChange(next)` fires once.
1228
+ - **The value list.** `getFilterValues(columnKey, state, signal)` is called once, when the exact-match list is first
1229
+ shown. Count the values over the rows the other columns' filters keep (taking the column's own filter out is yours —
1230
+ the grid passes the state as it is) and resolve `{ value, label, count }` rows: `value` unique, `count` a whole number
1231
+ of 0 or more, an empty `label` shown as `(Blanks)` (`filterBlank`). A rejection or a malformed answer shows
1232
+ `filterLoadFailed` (reopen the menu to read again). `signal` aborts when the menu closes — stop counting then; a late
1233
+ answer is dropped. The list mounts at most 500 values per render, and a `listMore` row counts the rest — the search
1234
+ box narrows it.
1235
+ - **Checked during render.** A malformed `sortFilter` throws a `RangeError` naming the member and the value: an unknown
1236
+ member (a typo), `headerRows` of 0, a key that is blank or repeated, `matchModes` empty or holding an unknown or
1237
+ repeated mode, a `defaultMatchMode` outside `matchModes`, exact match offered without `getFilterValues`, a state that
1238
+ names no column's key, sorts a column that cannot sort, filters a column that cannot filter or uses a mode the column
1239
+ does not offer. The functions are read at render and a new object re-reads every column's key and options, so keep
1240
+ the object identity-stable (`useMemo`). **An empty grid (no rows or no columns) checks nothing** — the check runs when
1241
+ the data arrives and the grid draws it.
1242
+ - **The selection keeps its position** after a sort or a filter (as in Excel), so it names another row now; a filter
1243
+ that removes rows clamps it (`onSelectionChange` with `"countShrink"`). To keep the same row selected, note the key
1244
+ of the row at `handle.getSelection().active.row` in `onStateChange` (before you reorder), and once the grid shows the
1245
+ new order — a layout effect after your state update — place it with `handle.setSelection(...)` at the row's new index
1246
+ (`{ scroll: true }` brings it into view). A row the filter removed has no new index; leave the clamp to it.
1247
+ - **An undo of your own that records positions** (row, col) points at other rows after a sort or a filter: record the
1248
+ rows by their keys, or map the positions through the order they were made in, before you replay them.
1249
+ - **Touch targets.** The ▼ is the full height of the header cell and 44 px wide; the cell's bottom grid line is outside
1250
+ it, so **a header row of 45 px or more** makes it a 44 × 44 target. It never reaches past the cell, which would take
1251
+ presses from the cells below.
1252
+
1114
1253
  ## View geometry and zoom rules (`@aiquants/spreadsheet/view`)
1115
1254
 
1116
1255
  `@aiquants/spreadsheet/view` publishes the grid's fixed geometry, its defaults and its zoom ladder without loading the grid
@@ -1187,7 +1326,7 @@ importers with the exact same Excel-compatible semantics the grid uses. `enumera
1187
1326
  `onOperationRejected` op), and `EditRejection` (the `onEditRejected` context — see "Editing, Undo, and rejection") are exported for
1188
1327
  consumer-side annotations.
1189
1328
 
1190
- 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):
1329
+ v0.8 adds the rich-cell engines as public pure functions (all React-free; `src/index.ts` exports 44 values and 111 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):
1191
1330
 
1192
1331
  - **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`),
1193
1332
  `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).
@@ -1275,6 +1414,9 @@ The `/utils` demo route exercises the v0.1 toolkit live; the `/styles` route dri
1275
1414
  | `clearFormatting` | Cells that are already unformatted produce no edit | — | Identity rule of `mergeFormat` — no no-op writes reach the adapter |
1276
1415
  | Colour toggles | Compare the active cell's base colour after normalisation (`#ffff00` = `#FFFF00`), write the configured spelling verbatim | — | The target spelling is the consumer's choice |
1277
1416
  | Validation list picker | Case-insensitive **prefix** filter; mounts at most 500 options per render — a larger match set appends one `listMore` row naming the hidden count | Sheets filters by substring and virtualises the list | A pasted foreign rule may carry an arbitrarily large values array; mounting it whole would freeze the tab, and the prefix filter reaches everything beyond the cap |
1417
+ | Header press sorts | A press on a sortable column's header cell cycles ascending → descending → no sort (`sortFilter`, v0.20.3) | Sorting runs from the filter menu or the ribbon; a header cell press selects | Requested by the host for the common sort; the ▼ menu and Alt+↓ carry the same sort for the keyboard |
1418
+ | Sort state | A view state the host applies — `sort: null` returns the rows to the host's own order | Sorting rewrites the order of the rows on the sheet (no unsorted state to return to) | The host owns the rows (adapter-owned pull model) |
1419
+ | Column filter value list | Mounts at most 500 values per render — a `listMore` row counts the rest; the search box (case- and width-insensitive substring) narrows it | Lists the column's distinct values with a search box | The validation list picker's cap and wording; the host counts the values (`getFilterValues`) |
1278
1420
  | 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` |
1279
1421
  | 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 |
1280
1422
  | 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 |
@@ -1286,13 +1428,13 @@ The `/utils` demo route exercises the v0.1 toolkit live; the `/styles` route dri
1286
1428
  | Ctrl+Home / Ctrl+End with freezes | Native pass-through (unchanged) | Land on the first / last unfrozen cell | Freeze-aware Ctrl+Home/End is a NEW feature — recorded future work, not part of the trailing-freeze release |
1287
1429
  | Trailing resize idiom | Near-edge one-sided strips; each strip controls its far-side track; the dragged edge is the moving edge (pinned-right); double-click autofits the same far-side track; T = 1 grow gestures pin the guide at the band edge; hidden trailing runs restore from band-side near-edge markers | Excel has no trailing freeze | Mirrors the shipped leading idiom under the pinned-right constraint |
1288
1430
  | Trailing autofit boundary side | An internal trailing boundary autofits the track **after** it (far side); the visually identical leading-side boundary autofits the track **before** it | — | Consequence of pinned-right control — the strip and its controlled track sit on opposite sides of the two idioms |
1289
- | Trailing rows under consumer sorting | Trailing rows are positional (the last N of the same data) — a consumer implementing sorting must exempt its totals rows itself | — | The package has no sort/filter feature (adapter-owned pull model); the footer-permutation trap is a consumer contract |
1431
+ | Trailing rows under consumer sorting | Trailing rows are positional (the last N of the same data) — a consumer implementing sorting must exempt its totals rows itself | — | The package reorders no rows: `sortFilter` (v0.20.3) draws the header controls and reports the state, and the host sorts and filters (adapter-owned pull model); the footer-permutation trap is a consumer contract |
1290
1432
  | Frozen-band shadow | None — the divider is the only boundary emphasis | Sheets adds a drop shadow while scrolled | Derivability is kept (`getFrozenSize()` trailing fields); a shadow is a recorded future path |
1291
1433
 
1292
1434
  ## Demo (feature showcase, doubles as the E2E fixture)
1293
1435
 
1294
1436
  Run `pnpm run demo:dev` from a source checkout (the `demo/` app is not in the npm tarball) and open
1295
- `http://localhost:5179`. Ten routes, each an in-header-nav page AND an E2E fixture (`tests/e2e/`). The demo UI is English by
1437
+ `http://localhost:5179`. Twelve routes, each an in-header-nav page AND an E2E fixture (`tests/e2e/`). The demo UI is English by
1296
1438
  default; `?lang=ja` (or the language switcher `[data-demo-locale-select]` at the end of the nav) switches every route's chrome and
1297
1439
  passes `locale` to every `<Spreadsheet>` without a reload — the URL keeps `?lang`, nav links carry it, `<html lang>` and the tab
1298
1440
  title follow, and an unsupported `?lang` value fails fast with a `RangeError` (blank page). Sample cell data (seeds, fixtures, the
@@ -1312,6 +1454,7 @@ covers the `?lang=ja` path and the live switch; every other E2E spec runs the En
1312
1454
  | `/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 |
1313
1455
  | `/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 |
1314
1456
  | `/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) |
1457
+ | `/sort-filter` | v0.20.3 — header sort and column filters (`tests/e2e/sort-filter.spec.ts`): a 120-row keyed list whose page plays the host — it keeps `sortFilter.state`, matches and reorders its rows on `onStateChange` (exact values, or a case- and width-insensitive substring for fuzzy search), counts the menu's values over the rows the other filters keep with a short abortable delay, and shows the state as JSON under the grid. Code sorts only, Name starts with fuzzy, Category is exact only (with blanks), Qty sorts numerically, Memo has no key; the header row is read-only and 45 px tall |
1315
1458
 
1316
1459
  Appending `?css=standalone` to any route swaps the source CSS pair for the built single-file
1317
1460
  artifact `dist/styles/spreadsheet.standalone.css` (artifact-parity verification path — run