@aiquants/spreadsheet 0.20.2 → 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 +82 -0
- package/README.md +98 -8
- package/dist/index.cjs +8 -8
- package/dist/index.d.cts +172 -2
- package/dist/index.d.ts +172 -2
- package/dist/index.js +6297 -5732
- package/dist/styles/spreadsheet.css +1 -1
- package/dist/styles/spreadsheet.standalone.css +1 -1
- package/package.json +1 -1
- package/src/Spreadsheet.tsx +174 -3
- package/src/commands/useCommands.ts +27 -0
- package/src/grid/GridBody.tsx +61 -3
- package/src/index.ts +10 -0
- package/src/model/labels.ts +100 -10
- package/src/popover/PopoverLayer.tsx +66 -4
- package/src/popover/usePopovers.ts +87 -9
- 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,88 @@
|
|
|
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
|
+
|
|
5
87
|
## 0.20.2 (2026-11-18)
|
|
6
88
|
|
|
7
89
|
### Added
|
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,7 +798,7 @@ 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
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` |
|
|
@@ -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. |
|
|
@@ -959,7 +968,7 @@ The grid's own UI chrome ships in English (`"en"`, the default) and Japanese (`"
|
|
|
959
968
|
| `formatCellAnnouncement` / `formatSelectionAnnouncement` | formatter | Opt-in screen-reader announcements (see above). |
|
|
960
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. |
|
|
961
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 |
|
|
962
|
-
| `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). |
|
|
963
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". |
|
|
964
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. |
|
|
965
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". |
|
|
@@ -1164,6 +1173,83 @@ if (ref.current?.commitEdit() !== "rejected") save()
|
|
|
1164
1173
|
focus has already committed through the focus leaving the grid, so it gets `"idle"`; a key listener that saves while
|
|
1165
1174
|
the focus stays in the grid is what needs this call.
|
|
1166
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
|
+
|
|
1167
1253
|
## View geometry and zoom rules (`@aiquants/spreadsheet/view`)
|
|
1168
1254
|
|
|
1169
1255
|
`@aiquants/spreadsheet/view` publishes the grid's fixed geometry, its defaults and its zoom ladder without loading the grid
|
|
@@ -1240,7 +1326,7 @@ importers with the exact same Excel-compatible semantics the grid uses. `enumera
|
|
|
1240
1326
|
`onOperationRejected` op), and `EditRejection` (the `onEditRejected` context — see "Editing, Undo, and rejection") are exported for
|
|
1241
1327
|
consumer-side annotations.
|
|
1242
1328
|
|
|
1243
|
-
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):
|
|
1244
1330
|
|
|
1245
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`),
|
|
1246
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).
|
|
@@ -1328,6 +1414,9 @@ The `/utils` demo route exercises the v0.1 toolkit live; the `/styles` route dri
|
|
|
1328
1414
|
| `clearFormatting` | Cells that are already unformatted produce no edit | — | Identity rule of `mergeFormat` — no no-op writes reach the adapter |
|
|
1329
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 |
|
|
1330
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`) |
|
|
1331
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` |
|
|
1332
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 |
|
|
1333
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 |
|
|
@@ -1339,13 +1428,13 @@ The `/utils` demo route exercises the v0.1 toolkit live; the `/styles` route dri
|
|
|
1339
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 |
|
|
1340
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 |
|
|
1341
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 |
|
|
1342
|
-
| 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 |
|
|
1343
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 |
|
|
1344
1433
|
|
|
1345
1434
|
## Demo (feature showcase, doubles as the E2E fixture)
|
|
1346
1435
|
|
|
1347
1436
|
Run `pnpm run demo:dev` from a source checkout (the `demo/` app is not in the npm tarball) and open
|
|
1348
|
-
`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
|
|
1349
1438
|
default; `?lang=ja` (or the language switcher `[data-demo-locale-select]` at the end of the nav) switches every route's chrome and
|
|
1350
1439
|
passes `locale` to every `<Spreadsheet>` without a reload — the URL keeps `?lang`, nav links carry it, `<html lang>` and the tab
|
|
1351
1440
|
title follow, and an unsupported `?lang` value fails fast with a `RangeError` (blank page). Sample cell data (seeds, fixtures, the
|
|
@@ -1365,6 +1454,7 @@ covers the `?lang=ja` path and the live switch; every other E2E spec runs the En
|
|
|
1365
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 |
|
|
1366
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 |
|
|
1367
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 |
|
|
1368
1458
|
|
|
1369
1459
|
Appending `?css=standalone` to any route swaps the source CSS pair for the built single-file
|
|
1370
1460
|
artifact `dist/styles/spreadsheet.standalone.css` (artifact-parity verification path — run
|