@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 +149 -0
- package/README.md +153 -10
- package/dist/index.cjs +8 -8
- package/dist/index.d.cts +301 -25
- package/dist/index.d.ts +301 -25
- package/dist/index.js +6320 -5670
- package/dist/styles/spreadsheet.css +1 -1
- package/dist/styles/spreadsheet.standalone.css +1 -1
- package/package.json +2 -2
- package/src/Spreadsheet.tsx +379 -39
- package/src/commands/useCommands.ts +27 -0
- package/src/editor/useCellEditor.ts +38 -6
- package/src/grid/GridBody.tsx +61 -3
- package/src/index.ts +23 -1
- package/src/keyboard/useGridKeyboard.ts +101 -3
- package/src/model/labels.ts +100 -10
- package/src/popover/PopoverLayer.tsx +66 -4
- package/src/popover/usePopovers.ts +87 -9
- package/src/selection/selectionState.ts +70 -0
- package/src/selection/useSelectionEngine.ts +141 -2
- package/src/sortFilter/ColumnMenu.tsx +380 -0
- package/src/sortFilter/HeaderControls.tsx +128 -0
- package/src/sortFilter/sortFilterModel.ts +648 -0
- package/src/styles/spreadsheet.css +148 -2
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
|
|
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
|
|
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
|
|
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
|
|
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`.
|
|
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
|