@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 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 21 package-owned keys, and the engine keys (every `VIRTUAL_SCROLL_LABEL_KEYS` entry) name the
501
+ popover strings and the 18 column-menu strings (v0.20.3) they are the 39 package-owned keys, and the engine keys (every `VIRTUAL_SCROLL_LABEL_KEYS` entry) name the
498
502
  grid scrollbars' chrome, such as the arrows and edge pills, and the empty state). The `locale` prop picks the catalog (`SPREADSHEET_LABEL_CATALOGS[locale]`), and an omitted or `undefined` key
499
503
  keeps that catalog's value. Switching `locale` localizes both names together; if you override them, **override both**, and a
500
504
  replacement `sinkAriaLabel` **must keep the Escape-exit notice** — the word `Escape` must appear, otherwise the grid throws a `RangeError` while rendering: Escape moves
@@ -607,7 +611,7 @@ mode uses system colours only). `src/styles/designTokens.spec.ts` pins all of th
607
611
  | `--aqsp-strong-text` | `#111827` | Comment authors |
608
612
  | `--aqsp-separator` | `#f3f4f6` | Lines between comments |
609
613
  | `--aqsp-button-surface` | `#f9fafb` | Popover buttons |
610
- | `--aqsp-hover-surface` | `#f3f4f6` | Hovered buttons, options and the close glyph |
614
+ | `--aqsp-hover-surface` | `#f3f4f6` | Hovered buttons, options, the column menu's value rows and the close glyph |
611
615
  | `--aqsp-hover-border` | `#9ca3af` | Hovered button border |
612
616
  | `--aqsp-primary-surface` | `#134dce` | Primary buttons (Save, Post) |
613
617
  | `--aqsp-primary-hover-surface` | `#173faf` | Hovered primary button |
@@ -650,7 +654,7 @@ formula; the three pairs below 7:1 before v0.16 were re-solved by changing light
650
654
  | `--aqsp-link` `#163ba5` on `--aqsp-surface` `#ffffff` (was `#1d4ed8`, 6.70) | 9.53 |
651
655
  | `--aqsp-link` on `--aqsp-header-row-surface` `#f3f4f6` / under the selection fill on the surface / on the header row | 8.66 / 7.74 / 7.05 |
652
656
  | `--aqsp-text` `#1f2937` on `--aqsp-surface` / `--aqsp-header-row-surface` / under the selection fill on each | 14.68 / 13.34 / 11.92 / 10.86 |
653
- | `--aqsp-muted-text` `#4e535e` on `--aqsp-surface` / `--aqsp-danger-surface` / `--aqsp-note-tip-surface` (was `#6b7280`, 4.83) | 7.71 / 7.05 / 7.44 |
657
+ | `--aqsp-muted-text` `#4e535e` on `--aqsp-surface` / `--aqsp-danger-surface` / `--aqsp-note-tip-surface` / `--aqsp-hover-surface` (the column menu's hovered value row) (was `#6b7280`, 4.83) | 7.71 / 7.05 / 7.44 / 7.01 |
654
658
  | `--aqsp-danger-text` `#a41919` on `--aqsp-surface` / `--aqsp-danger-surface` (was `#b91c1c`, 6.47) | 7.69 / 7.03 |
655
659
  | `--aqsp-primary-text` `#ffffff` on `--aqsp-primary-surface` `#134dce` / `--aqsp-primary-hover-surface` `#173faf` (was `#2563eb`, 5.17) | 7.05 / 8.87 |
656
660
  | `--aqsp-title-text` `#374151` / `--aqsp-strong-text` `#111827` on `--aqsp-surface` | 10.31 / 17.74 |
@@ -681,6 +685,9 @@ The grid's own resize affordances are small on purpose, and the grid does not tr
681
685
  needs them provides 44 × 44 controls that run those commands (a toolbar, for instance).
682
686
  - The column-letter band is 24 px tall (`SPREADSHEET_COLUMN_HEADER_HEIGHT_PX`) and the row-number band 64 px wide; cells and
683
687
  header labels are as large as the host's rows and columns, and the zoom ladder enlarges every target with the grid.
688
+ - **The ▼ of `sortFilter`** (v0.20.3) is sized for a finger: the full height of the header cell and 44 px wide (a header
689
+ row of 45 px or more makes it 44 × 44 — see "Sorting and filtering from the header"), and Alt+↓ on the header cell
690
+ opens the same menu.
684
691
 
685
692
  ## Context-menu constraint (right-click)
686
693
 
@@ -791,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 21 package keys (`sinkAriaLabel`, `rootAriaLabel`, `noteTitle`, `noteSave`, `noteEscapeHint`, `noteRejectedHint`, `noteViewerHint` (v0.10 — the note hint in the read-only viewer mode, which never promises a save), `commentTitle`, `commentReply`, `commentPost`, `commentCount` (string or `(n) => string`), `linkTitle`, `linkTextField`, `linkUrlField`, `linkOpen`, `linkSave`, `listTitle`, `listEmpty`, `listMore` (string or `(n) => string` — the validation-list picker mounts at most 500 options and announces the hidden-match count on this row), `messageTitle`, `popoverClose`). Omitted / `undefined` keys keep the value of the `locale` catalog (`SPREADSHEET_LABEL_CATALOGS[locale]`); an unknown key (including the removed `validationRejected` / `indicatorNote` / `indicatorComment` / `indicatorInvalid`) or a blank / non-string value throws a `RangeError` during render; `sinkAriaLabel` must mention `Escape` (`RangeError` during render otherwise). |
971
+ | `labels` | `SpreadsheetLabelOverrides` (any subset of the `SpreadsheetLabels` keys) | v0.8 — replaces the `sinkAriaLabel` / `rootAriaLabel` props (folded in) and names every UI chrome string: the engine keys shared with `@aiquants/virtualscroll` (every entry of the installed engine's `VIRTUAL_SCROLL_LABEL_KEYS`, such as `scrollUp`, `scrollDown`, `scrollToTop`, `noItems` — they reach the grid scrollbars and the empty state) and the 39 package keys (`sinkAriaLabel`, `rootAriaLabel`, `noteTitle`, `noteSave`, `noteEscapeHint`, `noteRejectedHint`, `noteViewerHint` (v0.10 — the note hint in the read-only viewer mode, which never promises a save), `commentTitle`, `commentReply`, `commentPost`, `commentCount` (string or `(n) => string`), `linkTitle`, `linkTextField`, `linkUrlField`, `linkOpen`, `linkSave`, `listTitle`, `listEmpty`, `listMore` (string or `(n) => string` — the validation-list picker mounts at most 500 options and announces the hidden-match count on this row), `messageTitle`, `popoverClose`, and the v0.20.3 column-menu keys `columnMenu`, `columnMenuFiltered`, `sortAscending`, `sortDescending`, `sortClear`, `filterMatchMode`, `filterModeExact`, `filterModeFuzzy`, `filterSearchValues`, `filterSelectAll`, `filterSelectNone`, `filterBlank`, `filterLoading`, `filterLoadFailed`, `filterQuery`, `filterApply`, `filterClearColumn`, `filterClearAll`). Omitted / `undefined` keys keep the value of the `locale` catalog (`SPREADSHEET_LABEL_CATALOGS[locale]`); an unknown key (including the removed `validationRejected` / `indicatorNote` / `indicatorComment` / `indicatorInvalid`) or a blank / non-string value throws a `RangeError` during render; `sinkAriaLabel` must mention `Escape` (`RangeError` during render otherwise). |
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 104 types in total — every named type an exported declaration reaches is exported too, so nothing has to be extracted with `Awaited<ReturnType<>>` / `Extract<>`; `src/index.spec.ts` pins it):
1329
+ v0.8 adds the rich-cell engines as public pure functions (all React-free; `src/index.ts` exports 44 values and 111 types in total — every named type an exported declaration reaches is exported too, so nothing has to be extracted with `Awaited<ReturnType<>>` / `Extract<>`; `src/index.spec.ts` pins it):
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 has no sort/filter feature (adapter-owned pull model); the footer-permutation trap is a consumer contract |
1431
+ | Trailing rows under consumer sorting | Trailing rows are positional (the last N of the same data) — a consumer implementing sorting must exempt its totals rows itself | — | The package reorders no rows: `sortFilter` (v0.20.3) draws the header controls and reports the state, and the host sorts and filters (adapter-owned pull model); the footer-permutation trap is a consumer contract |
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`. Ten routes, each an in-header-nav page AND an E2E fixture (`tests/e2e/`). The demo UI is English by
1437
+ `http://localhost:5179`. Twelve routes, each an in-header-nav page AND an E2E fixture (`tests/e2e/`). The demo UI is English by
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