@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.
@@ -45,6 +45,12 @@
45
45
  * forwarded to VirtualGrid, which localizes the embedded vertical bar, the horizontal bar and the
46
46
  * degenerate-band "No items" — no lang attribute, no new data-* hook.
47
47
  *
48
+ * Sort and filter controls (v0.20.3, `sortFilter`): with a resolved `sortFilter`, every header cell of the last header
49
+ * row whose column sorts or filters carries `data-aqsp-column-controls` (the stylesheet keeps its text clear of the
50
+ * button), the sorted one `aria-sort` and `data-aqsp-sort`, a filtered one `data-aqsp-filtered`, and its content is the
51
+ * cell renderer followed by the column menu button (`HeaderControls`, named after the cell's shown text). Without it no
52
+ * attribute and no button is added — the cell DOM is the v0.20.2 one.
53
+ *
48
54
  * グリッド本体。VirtualGrid 結線 (両軸) とセルレンダラーを所有する。v0.4 から横軸は VirtualGrid
49
55
  * の所有 (量子化列アンカー + 残差 transform + 横バー) — v0.3 の列スタック (useColumnWindow /
50
56
  * --aqsp-hx CSS 変数 / 軸原点絶対 left / 自前 HScrollBar) は設計計画 §7-1 に従い削除。
@@ -81,6 +87,11 @@
81
87
  *
82
88
  * UI クロームロケール: 解決済み `locale` と値安定なエンジン部分集合 `scrollLabels` を VirtualGrid へ
83
89
  * 素通しし、埋込み縦バー・横バー・退化帯の "No items" を現地化する (lang 属性・新規 data-* フックなし)。
90
+ *
91
+ * 並べ替えと絞り込みの操作 (v0.20.3、`sortFilter`): 解いた `sortFilter` があれば、見出しの最後の行のうち並べ替えできるか絞り込める列の
92
+ * マスに `data-aqsp-column-controls` (スタイルが字をボタンから離す)、並べ替えている列に `aria-sort` と `data-aqsp-sort`、絞り込んでいる列に
93
+ * `data-aqsp-filtered` を付け、中身はセルの描き手の後に列の品書きのボタン (`HeaderControls`。名前はマスの見せる字から) を置く。無ければ
94
+ * 属性もボタンも足さない (マスの DOM は v0.20.2 と同じ)。
84
95
  */
85
96
 
86
97
  import { type ScrollBarTapCircleOptions, VirtualGrid, type VirtualGridHandle, type VirtualGridRange, type VirtualScrollLabels, type VirtualScrollScrollBarOptions } from "@aiquants/virtualscroll"
@@ -94,6 +105,8 @@ import { isReadOnlyCell, lazyCellText, resolveCellAlign, resolveCellAttributes,
94
105
  import { isVisiblyInvalid } from "../model/dataValidation.ts"
95
106
  import type { SpreadsheetLocale } from "../model/labels.ts"
96
107
  import type { ViewStore } from "../model/viewStore.ts"
108
+ import { HeaderControls } from "../sortFilter/HeaderControls.tsx"
109
+ import { controlsColumnOf, headerColumnName, type ResolvedSortFilter } from "../sortFilter/sortFilterModel.ts"
97
110
  import { SPREADSHEET_SCROLLBAR_SIZE_PX } from "../view.ts"
98
111
  import { CellView, type RenderCellContext } from "./CellView.tsx"
99
112
 
@@ -300,6 +313,15 @@ export const resolveRichCellProps = (adapter: SpreadsheetDataAdapter, rowAxis: A
300
313
  return { attrs, style, value }
301
314
  }
302
315
 
316
+ /**
317
+ * What the column menu buttons need besides the resolved `sortFilter` (v0.20.3): the column whose menu is open, the two
318
+ * resolved label strings of the button's name and the identity-stable toggle. The root memoizes it, so it changes only
319
+ * when one of these does.
320
+ * 解いた `sortFilter` のほかに列の品書きのボタンが要る物 (v0.20.3)。品書きが開いている列・ボタンの名前の解いた言葉 2 つ・同一性の安定した
321
+ * 開閉。root が memo するので、どれかが変わった時だけ替わる。
322
+ */
323
+ export type GridColumnMenu = { readonly openCol: number | null; readonly menuLabel: string; readonly filteredLabel: string; readonly onToggle: (col: number) => void }
324
+
303
325
  type GridBodyProps = {
304
326
  adapter: SpreadsheetDataAdapter
305
327
  rowAxis: AxisModel
@@ -417,6 +439,13 @@ type GridBodyProps = {
417
439
  * identity が変わる — さもなくば shell 再レンダー毎に memo 境界を貫通)。
418
440
  */
419
441
  scrollLabels: VirtualScrollLabels
442
+ /**
443
+ * v0.20.3 capability: the resolved `sortFilter` (null or absent = no column controls, the v0.20.2 cell DOM).
444
+ * v0.20.3 能力: 解いた `sortFilter` (null か無しなら列の操作は無く、マスの DOM は v0.20.2 と同じ)。
445
+ */
446
+ sortFilter?: ResolvedSortFilter | null
447
+ /** v0.20.3: the column menu buttons' inputs (null or absent = no button). / v0.20.3: 列の品書きのボタンへの入力 (null か無しならボタンは無い)。 */
448
+ columnMenu?: GridColumnMenu | null
420
449
  }
421
450
 
422
451
  /**
@@ -461,6 +490,8 @@ const GridBodyInner = ({
461
490
  onRenderTruncated,
462
491
  locale,
463
492
  scrollLabels,
493
+ sortFilter,
494
+ columnMenu,
464
495
  }: GridBodyProps): ReactNode => {
465
496
  const internalBodyRef = useRef<HTMLDivElement | null>(null)
466
497
  // 外部 ref (エンジン結線用) と内部 ref の合成
@@ -527,6 +558,14 @@ const GridBodyInner = ({
527
558
  // 宣言ホストは塗りセル毎 1 述語読み (ADR-31 の登記コスト)
528
559
  ...(isReadOnlyCell(adapter, row, col) ? { "aria-readonly": "true", "data-aqsp-readonly": "" } : {}),
529
560
  ...(isHeader ? { "data-aqsp-header-row": "" } : {}),
561
+ // v0.20.3: 操作の列の見出しのマス (並べ替えている列だけが aria-sort を持つ — 並べ替えの表の作法)
562
+ ...(sortFilter === undefined || sortFilter === null || row !== sortFilter.headerRow || controlsColumnOf(sortFilter, col) === null
563
+ ? {}
564
+ : {
565
+ "data-aqsp-column-controls": "",
566
+ ...(sortFilter.sort !== null && sortFilter.sort.col === col ? { "aria-sort": sortFilter.sort.direction === "asc" ? "ascending" : "descending", "data-aqsp-sort": sortFilter.sort.direction } : {}),
567
+ ...(sortFilter.filteredColumns.has(col) ? { "data-aqsp-filtered": "" } : {}),
568
+ }),
530
569
  }
531
570
  // v0.12 ホスト属性の継ぎ目: resolveCellAttributes が予約キー (data-aqsp* / data-row /
532
571
  // data-col) と非 data-* を fail-fast 済みなのでパッケージ属性と衝突しない。未宣言は
@@ -544,7 +583,7 @@ const GridBodyInner = ({
544
583
  }
545
584
  return (rich.style === null ? { ...stamped, ...rich.attrs } : { ...stamped, ...rich.attrs, style: rich.style }) as HTMLAttributes<HTMLDivElement>
546
585
  },
547
- [adapter, rowAxis, colAxis, cf, headerRows],
586
+ [adapter, rowAxis, colAxis, cf, headerRows, sortFilter],
548
587
  )
549
588
  /** Row attribute surface — carries the engine event gate (data-aqsp-cells §6.4.3-1). / 行属性面 — エンジンのイベントゲート (data-aqsp-cells) を運ぶ。 */
550
589
  const getRowProps = useCallback(
@@ -579,9 +618,28 @@ const GridBodyInner = ({
579
618
  if (adapter.getCellFormat !== undefined) {
580
619
  display = formatCellValue(text, takeLatchedValue(displayLatchRef.current, row, col))
581
620
  }
582
- return <CellView row={row} col={col} text={text} display={display} renderCell={renderCell} __onCellRender={__onCellRender} />
621
+ const content = <CellView row={row} col={col} text={text} display={display} renderCell={renderCell} __onCellRender={__onCellRender} />
622
+ // v0.20.3: 操作の列の見出しのマスだけ、中身の後に列の品書きのボタン (CellView は字と描き手でしか描き直さないので中に入れない)
623
+ if (sortFilter === undefined || sortFilter === null || columnMenu === undefined || columnMenu === null || row !== sortFilter.headerRow || controlsColumnOf(sortFilter, col) === null) {
624
+ return content
625
+ }
626
+ return (
627
+ <>
628
+ {content}
629
+ <HeaderControls
630
+ col={col}
631
+ direction={sortFilter.sort !== null && sortFilter.sort.col === col ? sortFilter.sort.direction : null}
632
+ filtered={sortFilter.filteredColumns.has(col)}
633
+ expanded={columnMenu.openCol === col}
634
+ columnName={headerColumnName(display)}
635
+ menuLabel={columnMenu.menuLabel}
636
+ filteredLabel={columnMenu.filteredLabel}
637
+ onToggle={columnMenu.onToggle}
638
+ />
639
+ </>
640
+ )
583
641
  },
584
- [renderVersion, renderCell, __onCellRender, adapter],
642
+ [renderVersion, renderCell, __onCellRender, adapter, sortFilter, columnMenu],
585
643
  )
586
644
 
587
645
  return (
package/src/index.ts CHANGED
@@ -136,3 +136,13 @@ export {
136
136
  type SpreadsheetScrollBarControls,
137
137
  } from "./Spreadsheet.tsx"
138
138
  export type { SelectionState } from "./selection/selectionState.ts"
139
+ // 見出しの並べ替えと列ごとの絞り込み (v0.20.3) — props `sortFilter` の型と、その項目が到達する型の全て
140
+ export type {
141
+ SpreadsheetColumnFilter,
142
+ SpreadsheetColumnSortFilterOptions,
143
+ SpreadsheetFilterValue,
144
+ SpreadsheetMatchMode,
145
+ SpreadsheetSortDirection,
146
+ SpreadsheetSortFilter,
147
+ SpreadsheetSortFilterState,
148
+ } from "./sortFilter/sortFilterModel.ts"
@@ -9,7 +9,7 @@
9
9
  * Contract (each clause is pinned by labels.spec.ts):
10
10
  * - `SpreadsheetLocale` is the engine's locale set (`VirtualScrollLocale`); it is the UI chrome
11
11
  * language and a different axis from `formats.locale` (BCP-47 value formatting).
12
- * - `SpreadsheetLabels` is the closed key set (every engine key + the 21 own keys);
12
+ * - `SpreadsheetLabels` is the closed key set (every engine key + the 39 own keys);
13
13
  * `SPREADSHEET_LABEL_CATALOGS` supplies a frozen catalog per locale. Count-aware keys are typed
14
14
  * `string | ((n: number) => string)`.
15
15
  * - `resolveLabels(locale, overrides)` is the single fold point: the locale is resolved by
@@ -33,7 +33,7 @@
33
33
  * 矢印、端スクロールピル、"No items" など) を加える。エンジン文言は `VIRTUAL_SCROLL_LABEL_CATALOGS` を
34
34
  * 再利用し、ここでは再記述しない。純関数・React 非依存。
35
35
  * 契約: `SpreadsheetLocale` はエンジンのロケール集合 (UI クローム言語で、値書式の `formats.locale`
36
- * とは別軸)。`SpreadsheetLabels` は閉じたキー集合 (エンジンキー全件 + 固有 21)、`SPREADSHEET_LABEL_CATALOGS`
36
+ * とは別軸)。`SpreadsheetLabels` は閉じたキー集合 (エンジンキー全件 + 固有 39)、`SPREADSHEET_LABEL_CATALOGS`
37
37
  * はロケール別の凍結カタログ、件数キーは `string | ((n: number) => string)`。`resolveLabels` が唯一の
38
38
  * 畳込み点 (ロケールは `resolveVirtualScrollLocale` で解決 — undefined は "en"、未知は RangeError。
39
39
  * override 未指定はカタログを identity で返却。それ以外は override を素の object (プロトタイプが
@@ -60,10 +60,10 @@ export type SpreadsheetLocale = VirtualScrollLocale
60
60
 
61
61
  /**
62
62
  * The closed label vocabulary: every engine chrome key of `@aiquants/virtualscroll`
63
- * (VIRTUAL_SCROLL_LABEL_KEYS) plus the 21 own keys of the spreadsheet. Every key has a value in
63
+ * (VIRTUAL_SCROLL_LABEL_KEYS) plus the 39 own keys of the spreadsheet. Every key has a value in
64
64
  * each SPREADSHEET_LABEL_CATALOGS entry;
65
65
  * consumers override any subset through the `labels` prop (SpreadsheetLabelOverrides).
66
- * 閉じたラベル語彙: `@aiquants/virtualscroll` のエンジンクロームキー全件 (VIRTUAL_SCROLL_LABEL_KEYS) とスプレッドシート固有の 21 キー。
66
+ * 閉じたラベル語彙: `@aiquants/virtualscroll` のエンジンクロームキー全件 (VIRTUAL_SCROLL_LABEL_KEYS) とスプレッドシート固有の 39 キー。
67
67
  * 全キーが SPREADSHEET_LABEL_CATALOGS の各ロケールに値を持ち、消費者は `labels` prop で任意の部分集合を上書き。
68
68
  */
69
69
  export type SpreadsheetLabels = VirtualScrollLabels & {
@@ -109,6 +109,42 @@ export type SpreadsheetLabels = VirtualScrollLabels & {
109
109
  messageTitle: string
110
110
  /** Close button of every popover. / ポップオーバー共通の閉じるボタン。 */
111
111
  popoverClose: string
112
+ /** Column menu (v0.20.3 `sortFilter`): the menu's name and the menu button's name after the column name. / 列の品書き (v0.20.3 `sortFilter`) — 品書きの名前と、列の名に続く品書きのボタンの名前。 */
113
+ columnMenu: string
114
+ /** Column menu: the suffix of the button's name while the column is filtered. / 列の品書き — 絞り込み中の列のボタンの名前の添え字。 */
115
+ columnMenuFiltered: string
116
+ /** Column menu: sort ascending. / 列の品書き — 昇順で並べ替え。 */
117
+ sortAscending: string
118
+ /** Column menu: sort descending. / 列の品書き — 降順で並べ替え。 */
119
+ sortDescending: string
120
+ /** Column menu: clear this column's sort. / 列の品書き — この列の並べ替えを外す。 */
121
+ sortClear: string
122
+ /** Column menu: the legend of the match-mode switch. / 列の品書き — 検索方法の切り替えの見出し。 */
123
+ filterMatchMode: string
124
+ /** Column menu: the exact-match mode. / 列の品書き — 完全一致の方法。 */
125
+ filterModeExact: string
126
+ /** Column menu: the fuzzy-search mode. / 列の品書き — あいまい検索の方法。 */
127
+ filterModeFuzzy: string
128
+ /** Column menu: the value search box. / 列の品書き — 値を探す欄。 */
129
+ filterSearchValues: string
130
+ /** Column menu: check every value the search matches. / 列の品書き — 探す語に当たる値に全て印を付ける。 */
131
+ filterSelectAll: string
132
+ /** Column menu: uncheck every value the search matches. / 列の品書き — 探す語に当たる値の印を全て外す。 */
133
+ filterSelectNone: string
134
+ /** Column menu: the text shown for a value with an empty label. / 列の品書き — 字が空の値に見せる字。 */
135
+ filterBlank: string
136
+ /** Column menu: the value list is loading. / 列の品書き — 値の一覧の読み込み中。 */
137
+ filterLoading: string
138
+ /** Column menu: the value list could not be loaded. / 列の品書き — 値の一覧を読めなかった。 */
139
+ filterLoadFailed: string
140
+ /** Column menu: the fuzzy-search query field. / 列の品書き — あいまい検索の語の欄。 */
141
+ filterQuery: string
142
+ /** Column menu: apply the filter. / 列の品書き — 絞り込みを当てる。 */
143
+ filterApply: string
144
+ /** Column menu: clear this column's filter. / 列の品書き — この列の絞り込みを外す。 */
145
+ filterClearColumn: string
146
+ /** Column menu: clear every column's filter. / 列の品書き — すべての列の絞り込みを外す。 */
147
+ filterClearAll: string
112
148
  }
113
149
 
114
150
  /**
@@ -120,9 +156,9 @@ export type SpreadsheetLabels = VirtualScrollLabels & {
120
156
  export type SpreadsheetLabelOverrides = { readonly [K in keyof SpreadsheetLabels]?: SpreadsheetLabels[K] }
121
157
 
122
158
  /**
123
- * The 21 own (non-engine) keys, in declaration order — the iteration source of the own-key fold and
159
+ * The 39 own (non-engine) keys, in declaration order — the iteration source of the own-key fold and
124
160
  * of assertLabels.
125
- * 固有 (エンジン外) の 21 キー (宣言順) — 固有キー畳込みと assertLabels の走査元。
161
+ * 固有 (エンジン外) の 39 キー (宣言順) — 固有キー畳込みと assertLabels の走査元。
126
162
  */
127
163
  const OWN_LABEL_KEYS = [
128
164
  "sinkAriaLabel",
@@ -146,14 +182,32 @@ const OWN_LABEL_KEYS = [
146
182
  "listMore",
147
183
  "messageTitle",
148
184
  "popoverClose",
185
+ "columnMenu",
186
+ "columnMenuFiltered",
187
+ "sortAscending",
188
+ "sortDescending",
189
+ "sortClear",
190
+ "filterMatchMode",
191
+ "filterModeExact",
192
+ "filterModeFuzzy",
193
+ "filterSearchValues",
194
+ "filterSelectAll",
195
+ "filterSelectNone",
196
+ "filterBlank",
197
+ "filterLoading",
198
+ "filterLoadFailed",
199
+ "filterQuery",
200
+ "filterApply",
201
+ "filterClearColumn",
202
+ "filterClearAll",
149
203
  ] as const satisfies readonly (keyof SpreadsheetLabels)[]
150
204
 
151
205
  /**
152
206
  * Every label key: every engine key (VIRTUAL_SCROLL_LABEL_KEYS, in engine order) followed by the
153
- * 21 own keys — the closed key set that overrides are validated against, and the census list for
207
+ * 39 own keys — the closed key set that overrides are validated against, and the census list for
154
208
  * docs / tests. Compile-time proofs below that it covers EVERY SpreadsheetLabels key and that the
155
209
  * own keys never shadow an engine key.
156
- * 全ラベルキー: エンジンキー全件 (VIRTUAL_SCROLL_LABEL_KEYS、エンジン順) に固有 21 キーを続けたもの —
210
+ * 全ラベルキー: エンジンキー全件 (VIRTUAL_SCROLL_LABEL_KEYS、エンジン順) に固有 39 キーを続けたもの —
157
211
  * override 検証の閉じたキー集合で docs / テストの census 表。直下で全キー網羅と、固有キーが
158
212
  * エンジンキーを覆い隠さないことを型水準で証明。
159
213
  */
@@ -168,10 +222,10 @@ const ownLabelKeysAreDisjointFromEngine: [Extract<(typeof OWN_LABEL_KEYS)[number
168
222
  void ownLabelKeysAreDisjointFromEngine
169
223
 
170
224
  /**
171
- * Per-locale values of the 21 own keys. `en` is byte-identical to the pre-i18n English defaults
225
+ * Per-locale values of the 39 own keys. `en` is byte-identical to the pre-i18n English defaults
172
226
  * (`sinkAriaLabel` / `rootAriaLabel` equal the v0.7 prop defaults, so the fold is DOM-identical);
173
227
  * `commentCount` / `listMore` pluralise in `en` and use the counter 件 in `ja`. Frozen.
174
- * 固有 21 キーのロケール別の値。`en` は i18n 化前の英語既定と byte 同一 (`sinkAriaLabel` /
228
+ * 固有 39 キーのロケール別の値。`en` は i18n 化前の英語既定と byte 同一 (`sinkAriaLabel` /
175
229
  * `rootAriaLabel` は v0.7 の prop 既定と同じで畳込みは DOM 恒等)、`commentCount` / `listMore` は
176
230
  * `en` で単複を区別し `ja` では助数詞「件」。凍結済み。
177
231
  */
@@ -198,6 +252,24 @@ const OWN_LABEL_CATALOGS: Readonly<Record<SpreadsheetLocale, Omit<SpreadsheetLab
198
252
  listMore: (n: number): string => (n === 1 ? "1 more value — keep typing to narrow" : `${n} more values — keep typing to narrow`),
199
253
  messageTitle: "Data validation",
200
254
  popoverClose: "Close",
255
+ columnMenu: "Sort and filter",
256
+ columnMenuFiltered: "filtered",
257
+ sortAscending: "Sort ascending",
258
+ sortDescending: "Sort descending",
259
+ sortClear: "Clear sort",
260
+ filterMatchMode: "Match",
261
+ filterModeExact: "Exact match",
262
+ filterModeFuzzy: "Fuzzy search",
263
+ filterSearchValues: "Search values",
264
+ filterSelectAll: "Select all",
265
+ filterSelectNone: "Clear all",
266
+ filterBlank: "(Blanks)",
267
+ filterLoading: "Loading…",
268
+ filterLoadFailed: "Could not load the values",
269
+ filterQuery: "Search text",
270
+ filterApply: "Apply",
271
+ filterClearColumn: "Clear this column's filter",
272
+ filterClearAll: "Clear all filters",
201
273
  }),
202
274
  ja: Object.freeze({
203
275
  sinkAriaLabel: "スプレッドシートのグリッド。Escape キーでグリッドの外へフォーカスを移動します。",
@@ -221,6 +293,24 @@ const OWN_LABEL_CATALOGS: Readonly<Record<SpreadsheetLocale, Omit<SpreadsheetLab
221
293
  listMore: (n: number): string => `ほかに ${n} 件 — 入力して絞り込んでください`,
222
294
  messageTitle: "データの入力規則",
223
295
  popoverClose: "閉じる",
296
+ columnMenu: "並べ替えと絞り込み",
297
+ columnMenuFiltered: "絞り込み中",
298
+ sortAscending: "昇順で並べ替え",
299
+ sortDescending: "降順で並べ替え",
300
+ sortClear: "並べ替えを外す",
301
+ filterMatchMode: "検索方法",
302
+ filterModeExact: "完全一致",
303
+ filterModeFuzzy: "あいまい検索",
304
+ filterSearchValues: "値を探す",
305
+ filterSelectAll: "すべて選ぶ",
306
+ filterSelectNone: "すべて外す",
307
+ filterBlank: "(空白)",
308
+ filterLoading: "読み込み中…",
309
+ filterLoadFailed: "値を読めませんでした",
310
+ filterQuery: "探す語",
311
+ filterApply: "当てる",
312
+ filterClearColumn: "この列の絞り込みを外す",
313
+ filterClearAll: "すべての絞り込みを外す",
224
314
  }),
225
315
  })
226
316
 
@@ -23,6 +23,10 @@
23
23
  * DOM hooks: `[data-aqsp-popover-layer]`, `[data-aqsp-popover-anchor="interactive" | "tip"]`,
24
24
  * `[data-aqsp-popover-frame="<kind>"]`, `[data-aqsp-popover-open]` on an anchor holding a frame
25
25
  * (anchor open-state only — the link editor's Open button is `data-aqsp-link-open`).
26
+ * v0.20.3 (`sortFilter`): an inner `columnMenu` context renders the package's own `ColumnMenu`
27
+ * (never `renderPopover`, which receives the public union only) from the live resolution, state
28
+ * and state-change funnel the root hands in as `columnMenu`; the menu asks the layer to place its
29
+ * frame again when its content changes height (`relayout`).
26
30
  *
27
31
  * ポップオーバー層の DOM (v0.8 §4.1.15 — ADR-15)。`.aqsp-body-stack` 内で選択 overlay の兄弟と
28
32
  * して、overlay の repaintOverlay がここで渡す ref 経由で配置する 2 つの常設アンカー
@@ -42,10 +46,16 @@
42
46
  * compositionend 登録、Escape フォールバック (preventDefault されていない Escape は閉じる —
43
47
  * 既定コンポーネントは自前で prevent する)、初期フォーカス (`[data-aqsp-popover-autofocus]`、受動的な
44
48
  * `message` は省く)。`renderPopover` は文脈ごとに既定コンポーネントを置き換える。
49
+ * v0.20.3 (`sortFilter`): 内側の `columnMenu` の文脈は、root が `columnMenu` で渡す今の解き方・状態・状態を変える手順から
50
+ * 部品の `ColumnMenu` を描く (`renderPopover` は公開の和だけを受けるので見ない)。品書きは中身の高さが変わるとフレームを
51
+ * 置き直すよう層に頼む (`relayout`)。
45
52
  */
46
53
 
47
54
  import { type CompositionEvent, type KeyboardEvent, type ReactNode, type RefObject, useLayoutEffect, useRef } from "react"
55
+ import type { CellCoord } from "../model/cellCoord.ts"
48
56
  import type { SpreadsheetLabels } from "../model/labels.ts"
57
+ import { ColumnMenu } from "../sortFilter/ColumnMenu.tsx"
58
+ import { controlsColumnOf, type ResolvedSortFilter, type SpreadsheetSortFilter, type SpreadsheetSortFilterState } from "../sortFilter/sortFilterModel.ts"
49
59
  import { CommentPopover } from "./CommentPopover.tsx"
50
60
  import { LinkPopover } from "./LinkPopover.tsx"
51
61
  import { ListPopover } from "./ListPopover.tsx"
@@ -53,7 +63,22 @@ import { MessagePopover } from "./MessagePopover.tsx"
53
63
  import { NotePopover } from "./NotePopover.tsx"
54
64
  import { NoteTip } from "./NoteTip.tsx"
55
65
  import { placePopover, popoverWidth } from "./placement.ts"
56
- import type { PopoverContext, PopoverController } from "./usePopovers.ts"
66
+ import type { ColumnMenuContext, LayerContext, PopoverContext, PopoverController } from "./usePopovers.ts"
67
+
68
+ /**
69
+ * What the column menu reads from the root at every render (v0.20.3): the live resolution, the host's state and value
70
+ * loader, the state-change funnel, the column name of a header cell and the in-grid test of the blur rule.
71
+ * 列の品書きが描くたびに root から読む物 (v0.20.3)。今の解き方・利用側の状態と値の読み込み・状態を変える手順・見出しのマスの列の名・
72
+ * blur の決まりのグリッドの中の判定。
73
+ */
74
+ export type ColumnMenuLayerProps = {
75
+ readonly resolved: ResolvedSortFilter
76
+ readonly state: SpreadsheetSortFilterState
77
+ readonly getFilterValues: SpreadsheetSortFilter["getFilterValues"]
78
+ readonly changeState: (next: SpreadsheetSortFilterState) => boolean
79
+ readonly columnNameOf: (cell: CellCoord) => string
80
+ readonly isInsideGrid: (node: Node) => boolean
81
+ }
57
82
 
58
83
  export type PopoverLayerProps = {
59
84
  controller: PopoverController
@@ -64,6 +89,8 @@ export type PopoverLayerProps = {
64
89
  interactiveAnchorRef: RefObject<HTMLDivElement | null>
65
90
  /** The tip anchor node (positioned by the overlay). / tip アンカーノード (overlay が配置)。 */
66
91
  tipAnchorRef: RefObject<HTMLDivElement | null>
92
+ /** v0.20.3: the column menu's live inputs (null or absent = no column menu is drawn). / v0.20.3: 列の品書きの今の入力 (null か無しなら描かない)。 */
93
+ columnMenu?: ColumnMenuLayerProps | null
67
94
  }
68
95
 
69
96
  /** The default component per kind. / kind 毎の既定コンポーネント。 */
@@ -85,13 +112,13 @@ const renderDefault = (ctx: PopoverContext, labels: SpreadsheetLabels): ReactNod
85
112
  }
86
113
 
87
114
  /** Identity of a placement (kind + cell) — the frame key and the initial-focus once-guard; a rejected re-present keeps both (no remount / re-focus) but IS re-placed. / 配置の同一性 (kind + セル) — フレームキー兼初期フォーカスの既済ガード。拒否再提示はどちらも保つ (再マウント / 再フォーカスなし) が再配置はする。 */
88
- const placementKeyOf = (ctx: PopoverContext | null): string | null => (ctx === null ? null : `${ctx.kind}:${ctx.cell.row}:${ctx.cell.col}`)
115
+ const placementKeyOf = (ctx: LayerContext | null): string | null => (ctx === null ? null : `${ctx.kind}:${ctx.cell.row}:${ctx.cell.col}`)
89
116
 
90
117
  /**
91
118
  * Renders the layer, its two anchors and the lazily mounted frames.
92
119
  * 層・2 アンカー・遅延マウントされるフレームを描画する。
93
120
  */
94
- export const PopoverLayer = ({ controller, renderPopover, labels, interactiveAnchorRef, tipAnchorRef }: PopoverLayerProps): ReactNode => {
121
+ export const PopoverLayer = ({ controller, renderPopover, labels, interactiveAnchorRef, tipAnchorRef, columnMenu }: PopoverLayerProps): ReactNode => {
95
122
  const { context, tipContext } = controller
96
123
  const frameRef = useRef<HTMLDivElement | null>(null)
97
124
  const tipFrameRef = useRef<HTMLDivElement | null>(null)
@@ -163,6 +190,41 @@ export const PopoverLayer = ({ controller, renderPopover, labels, interactiveAnc
163
190
  }, [tipPlacementKey])
164
191
 
165
192
  const render = (ctx: PopoverContext): ReactNode => (renderPopover === undefined ? renderDefault(ctx, labels) : renderPopover(ctx))
193
+ /** Places the open frame again after its content changed height (the column menu's mode switch and value load). / 中身の高さが変わった後に開いているフレームを置き直す (列の品書きの方法の切り替えと値の読み込み)。 */
194
+ const relayout = (): void => {
195
+ const frame = frameRef.current
196
+ const ctx = controllerRef.current.context
197
+ if (frame !== null && ctx !== null) {
198
+ place(frame, ctx.anchorRect)
199
+ }
200
+ }
201
+ /**
202
+ * Renders the column menu from the live inputs; nothing when they are absent or the cell no longer carries controls
203
+ * (the root closes such a menu in the same commit).
204
+ * 今の入力から列の品書きを描く。入力が無いか、マスがもう操作を持たなければ何も描かない (そうした品書きは root が同じコミットで閉じる)。
205
+ */
206
+ const renderColumnMenu = (ctx: ColumnMenuContext): ReactNode => {
207
+ if (columnMenu === undefined || columnMenu === null || ctx.cell.row !== columnMenu.resolved.headerRow) {
208
+ return null
209
+ }
210
+ const column = controlsColumnOf(columnMenu.resolved, ctx.cell.col)
211
+ if (column === null) {
212
+ return null
213
+ }
214
+ return (
215
+ <ColumnMenu
216
+ column={column}
217
+ columnName={columnMenu.columnNameOf(ctx.cell)}
218
+ state={columnMenu.state}
219
+ getFilterValues={columnMenu.getFilterValues}
220
+ changeState={columnMenu.changeState}
221
+ close={controller.close}
222
+ isInsideGrid={columnMenu.isInsideGrid}
223
+ relayout={relayout}
224
+ labels={labels}
225
+ />
226
+ )
227
+ }
166
228
  const onKeyDownCapture = (event: KeyboardEvent<HTMLDivElement>): void => {
167
229
  // IME 由来の keydown は全 popover ハンドラより先に握り潰す (Escape / Enter が変換確定を壊さない)
168
230
  if (controller.isCompositionKey(event.nativeEvent)) {
@@ -187,7 +249,7 @@ export const PopoverLayer = ({ controller, renderPopover, labels, interactiveAnc
187
249
  {context === null ? null : (
188
250
  // フレームは autofocus 対象のない消費者レンダラのフォーカス着地点 (tabIndex -1 = プログラム的にだけ受ける)
189
251
  <div key={placementKey} ref={frameRef} className="aqsp-popover" data-aqsp-popover-frame={context.kind} tabIndex={-1}>
190
- {render(context)}
252
+ {context.kind === "columnMenu" ? renderColumnMenu(context) : render(context)}
191
253
  </div>
192
254
  )}
193
255
  </div>
@@ -28,6 +28,12 @@
28
28
  * preserved); G14b is the list commit's defense-in-depth; G14c refuses a list open PRE-open —
29
29
  * after the RangeError wiring check, BEFORE the commit gate (doomed-open: no force-commit).
30
30
  * Capability undeclared = contexts and conduct byte-identical to v0.9.
31
+ * v0.20.3 (`sortFilter`, the column menu): an INNER surface on the same interactive anchor —
32
+ * `openColumnMenu(cell)` builds the internal `ColumnMenuContext` (never a member of the public
33
+ * `PopoverContext`, so `renderPopover` never receives it and a host's exhaustive switch over the
34
+ * public union stays complete), after the same commit gate as an interactive kind and without any
35
+ * read-only refusal; the menu and an interactive popover replace each other (one anchor), and the
36
+ * layer is mounted when the `columnMenuAt` capability is declared. Undeclared = byte-identical.
31
37
  *
32
38
  * ポップオーバー状態機械 (v0.8 §1.8 / §4.1.15 — ADR-15 対話層)。6 種 (note エディタ / ホバー
33
39
  * note tip / コメントスレッド / ハイパーリンクエディタ / 検証リスト / 検証メッセージ) を overlay が
@@ -52,6 +58,10 @@
52
58
  * rejected false のまま + 下書き保持で再提示)、G14b = list commit の縦深防御、G14c = list の
53
59
  * pre-open 拒否 (RangeError 結線検査の後・commit ゲートの前 — doomed-open で force-commit なし)。
54
60
  * 能力未宣言は context も品行も v0.9 とバイト恒等。
61
+ * v0.20.3 (`sortFilter` の列の品書き): 同じ対話アンカーの上の**内側**の面 — `openColumnMenu(cell)` が内部の
62
+ * `ColumnMenuContext` を作る (公開の `PopoverContext` の和には入れないので `renderPopover` は受けず、公開の和を網羅する
63
+ * 利用側の switch は欠けない)。開く前の確定の関門は対話 kind と同じで、読むだけの断りは出さない。品書きと対話の
64
+ * ポップオーバーは互いに置き換わり (アンカーは 1 つ)、`columnMenuAt` 能力があれば層を描く。未宣言はバイト恒等。
55
65
  */
56
66
 
57
67
  import type { VirtualGridHandle } from "@aiquants/virtualscroll"
@@ -63,6 +73,7 @@ import { type CellCoord, clampCoord, coordEquals } from "../model/cellCoord.ts"
63
73
  import { type CellEdit, type EditRejection, isReadOnlyCell, type ReadOnlyRejection, readOnlyDeclared, type SpreadsheetDataAdapter } from "../model/dataAdapter.ts"
64
74
  import { colToViewportX, rowToViewportY, viewportXToCol, viewportYToRow } from "../model/frozenPartition.ts"
65
75
  import { resolveLabel, type SpreadsheetLabels } from "../model/labels.ts"
76
+ import type { ResolvedSortFilterColumn } from "../sortFilter/sortFilterModel.ts"
66
77
  import { NOTE_TIP_LEAVE_GRACE_MS, type PopoverRect, shouldShowNoteTip } from "./placement.ts"
67
78
 
68
79
  /** The six popover kinds (v0.8 §1.8). / 6 種のポップオーバー (v0.8 §1.8)。 */
@@ -106,6 +117,21 @@ export type MessagePopoverContext = { kind: "message"; cell: CellCoord; anchorRe
106
117
  /** The discriminated popover context handed to `renderPopover` / the default components (v0.8 §1.8). / renderPopover / 既定コンポーネントへ渡す判別文脈 (v0.8 §1.8)。 */
107
118
  export type PopoverContext = NotePopoverContext | NoteTipContext | CommentPopoverContext | LinkPopoverContext | ListPopoverContext | MessagePopoverContext
108
119
 
120
+ /**
121
+ * The column menu context (v0.20.3, internal — never part of the public `PopoverContext`): the header cell the menu is
122
+ * anchored to and the resolved column it was opened for (the root closes the menu when the live resolution of that cell
123
+ * no longer equals it). The live state, the labels and the state-change funnel reach the menu from the root at render.
124
+ * 列の品書きの文脈 (v0.20.3、内部 — 公開の `PopoverContext` には入れない)。品書きのアンカーの見出しのマスと、開いた時の解いた列 (そのマスの
125
+ * 今の解き方が等しくなくなれば root が閉じる)。今の状態・言葉・状態を変える手順は、描く時に root から品書きへ届く。
126
+ */
127
+ export type ColumnMenuContext = { kind: "columnMenu"; cell: CellCoord; anchorRect: PopoverRect; column: ResolvedSortFilterColumn }
128
+
129
+ /** Every context the layer renders: the public union plus the inner column menu. / 層が描く全ての文脈 (公開の和と内側の列の品書き)。 */
130
+ export type LayerContext = PopoverContext | ColumnMenuContext
131
+
132
+ /** Every kind the interactive anchor can hold. / 対話アンカーが持てる全ての種類。 */
133
+ export type LayerKind = PopoverKind | ColumnMenuContext["kind"]
134
+
109
135
  /** Extra inputs of `open` (list: typed prefix; message: an explicit text, e.g. a strict-rejection verdict). / `open` の追加入力 (list: 入力プレフィックス、message: 明示テキスト — strict 拒否の判定文など)。 */
110
136
  export type PopoverOpenOptions = { typed?: string; message?: string; rejected?: boolean }
111
137
 
@@ -122,8 +148,17 @@ export type PopoverController = {
122
148
  open: (kind: PopoverKind, options?: PopoverOpenOptions) => void
123
149
  /** Closes the interactive popover (idempotent) and returns focus to the sink — unless `{ restoreFocus: false }`, which the host-driven count-shrink seam passes while focus sits outside the grid (a filter input) so the host's keystrokes are not stolen; the sink is re-armed when idle either way. / 対話ポップオーバーを閉じ (冪等) シンクへフォーカスを返す — `{ restoreFocus: false }` なら返さない (ホスト起点の行数縮小シームが、フォーカスがグリッド外 (絞り込み入力欄) にある間に渡す — ホストの打鍵先を奪わない)。idle なら再武装はどちらでも行う。 */
124
150
  close: (options?: { restoreFocus: boolean }) => void
125
- /** The open interactive kind or null. / 開いている対話 kind か null。 */
126
- isOpen: () => PopoverKind | null
151
+ /** The open interactive kind (the column menu included) or null. / 開いている対話 kind (列の品書きを含む) か null。 */
152
+ isOpen: () => LayerKind | null
153
+ /**
154
+ * v0.20.3: opens the column menu on a header cell (the commit gate first — a refusal opens nothing; no read-only refusal);
155
+ * false when it did not open (no `columnMenuAt` capability, the cell carries no controls, or the commit was refused).
156
+ * v0.20.3: 見出しのマスで列の品書きを開く (確定の関門が先 — 断られたら開かない。読むだけの断りは出さない)。開かなかった時
157
+ * (`columnMenuAt` 能力が無い・マスが操作を持たない・確定が断られた) は false。
158
+ */
159
+ openColumnMenu: (cell: CellCoord) => boolean
160
+ /** v0.20.3: closes the column menu only (idempotent; other kinds stay) with the `close` focus rule. / v0.20.3: 列の品書きだけを閉じる (冪等。ほかの種類は残す)。焦点の決まりは `close` と同じ。 */
161
+ closeColumnMenu: (options?: { restoreFocus: boolean }) => void
127
162
  /** rAF-coalesced hover entry for the note tip by cell (null = pointer left the cells); the body's own pointermove path queues the client point and hit-tests inside the frame. / note tip のセル指定ホバー入口 (rAF 合流。null = セル領域から離脱)。body の pointermove 経路は client 座標を積みフレーム内でヒットテストする。 */
128
163
  onCellHover: (cell: CellCoord | null) => void
129
164
  /** Escape chain step 0: hides a visible tip (true; false when none) — it stays hidden until the pointer moves to ANOTHER cell (a re-show needs a cell change). / Escape チェーン step 0: 可視 tip を消灯 (true、無ければ false) — 再表示にはセル変化が要るので別セルへ移るまで消えたまま。 */
@@ -134,8 +169,8 @@ export type PopoverController = {
134
169
  onTipPointerLeave: () => void
135
170
  /** Re-evaluates the "sink aria-describedby while the hovered cell is active" invariant (bind when the visible tip's cell IS active, unbind own binding otherwise); the root calls it on every active-cell change. / 「ホバーセルが active の間シンクへ aria-describedby」不変条件の再評価 (可視 tip のセルが active なら結び、でなければ自分の結合だけ外す)。root が active セル変化のたびに呼ぶ。 */
136
171
  syncTipAriaDescribedBy: () => void
137
- /** The interactive popover context (React state — lazy mount) or null. / 対話ポップオーバー文脈 (React state — 遅延マウント) か null。 */
138
- context: PopoverContext | null
172
+ /** The interactive popover context, the column menu included (React state — lazy mount) or null. / 対話ポップオーバー文脈 (列の品書きを含む。React state — 遅延マウント) か null。 */
173
+ context: LayerContext | null
139
174
  /** The hover tip context or null. / ホバー tip 文脈か null。 */
140
175
  tipContext: NoteTipContext | null
141
176
  /** compositionend registration for the IME guard. / IME ガード用の compositionend 登録。 */
@@ -181,6 +216,13 @@ export type UsePopoversParams = {
181
216
  /** Root-owned anchor state the overlay positions. / root 所有のアンカー状態 (overlay が配置)。 */
182
217
  anchors: RefObject<PopoverAnchorState>
183
218
  repaintOverlay: () => void
219
+ /**
220
+ * v0.20.3 capability (`sortFilter`): the resolved column of a header cell that carries column controls, or null.
221
+ * Undefined = no column menu (the layer derivation is the v0.20.2 one).
222
+ * v0.20.3 能力 (`sortFilter`): 列の操作を持つ見出しのマスの解いた列 (無ければ null)。undefined なら列の品書きは無い
223
+ * (層の導出は v0.20.2 と同じ)。
224
+ */
225
+ columnMenuAt?: (cell: CellCoord) => ResolvedSortFilterColumn | null
184
226
  }
185
227
 
186
228
  /** The adapter capability each kind requires (the "cannot write what you cannot read" gate). / 各 kind が要するアダプタ能力 (「読めないものは書けない」ゲート)。 */
@@ -213,10 +255,10 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
213
255
  const paramsRef = useRef(params)
214
256
  paramsRef.current = params
215
257
 
216
- const [context, setContext] = useState<PopoverContext | null>(null)
258
+ const [context, setContext] = useState<LayerContext | null>(null)
217
259
  const [tipContext, setTipContext] = useState<NoteTipContext | null>(null)
218
260
  /** Imperative mirror of the open interactive kind (state reads inside callbacks would be stale). / 開いている対話 kind の命令読みミラー。 */
219
- const openKindRef = useRef<PopoverKind | null>(null)
261
+ const openKindRef = useRef<LayerKind | null>(null)
220
262
  /** The cell whose tip is visible (null = hidden). / tip を表示中のセル (null = 非表示)。 */
221
263
  const tipCellRef = useRef<CellCoord | null>(null)
222
264
  /** The last hovered cell (the predicate's `prev` — after hideTip the tip cannot re-show until this changes). / 直近のホバーセル (述語の prev — hideTip 後はこれが変わるまで再表示しない)。 */
@@ -481,7 +523,7 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
481
523
 
482
524
  /** Places `ctx` on the interactive anchor (replacing whatever was open). / ctx を対話アンカーへ載せる (開いていたものは置換)。 */
483
525
  const present = useCallback(
484
- (ctx: PopoverContext) => {
526
+ (ctx: LayerContext) => {
485
527
  openKindRef.current = ctx.kind
486
528
  setContext(ctx)
487
529
  writeAnchors({ interactive: ctx.cell })
@@ -675,6 +717,38 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
675
717
  [anchorRectOf, close, commitOrReject, hideTipNow, present, showTip, readOnlyKeyOf],
676
718
  )
677
719
 
720
+ /** v0.20.3: opens the column menu on a header cell (see the controller contract). / v0.20.3: 見出しのマスで列の品書きを開く (コントローラの契約)。 */
721
+ const openColumnMenu = useCallback(
722
+ (cell: CellCoord): boolean => {
723
+ const p = paramsRef.current
724
+ const column = p.columnMenuAt === undefined ? null : p.columnMenuAt(cell)
725
+ if (column === null) {
726
+ return false
727
+ }
728
+ // 入力中なら確定を通す (断られたら開かない — 品書きの後ろで入力が続いたまま行の並びが変わらないように)。並べ替えと
729
+ // 絞り込みは見た目の変更なので、読むだけのマスでも断らない
730
+ if (p.isEditing() && !p.requestCommit()) {
731
+ return false
732
+ }
733
+ // ホバーの tip は品書きに席を譲る。開く前にシンクへ焦点 (root の迷子の回収に品書きの初めの焦点を奪わせない — list と同じ)
734
+ hideTipNow()
735
+ p.focusSink({ preventScroll: true })
736
+ present({ kind: "columnMenu", cell, anchorRect: anchorRectOf(cell), column })
737
+ return true
738
+ },
739
+ [anchorRectOf, hideTipNow, present],
740
+ )
741
+
742
+ /** v0.20.3: closes the column menu only. / v0.20.3: 列の品書きだけを閉じる。 */
743
+ const closeColumnMenu = useCallback(
744
+ (options?: { restoreFocus: boolean }) => {
745
+ if (openKindRef.current === "columnMenu") {
746
+ close(options)
747
+ }
748
+ },
749
+ [close],
750
+ )
751
+
678
752
  const { enabled, bodyRef } = params
679
753
  useEffect(() => {
680
754
  const body = bodyRef.current
@@ -718,7 +792,9 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
718
792
  )
719
793
 
720
794
  const { adapter, popovers } = params
721
- const layerEnabled = useMemo(() => POPOVER_KINDS.some((kind) => kindEnabled(adapter, popovers, kind)), [adapter, popovers])
795
+ const columnMenuEnabled = params.columnMenuAt !== undefined
796
+ // 列の品書き (v0.20.3) も層に載る — 能力があれば、公開の kind が 1 つも無くても層を描く
797
+ const layerEnabled = useMemo(() => columnMenuEnabled || POPOVER_KINDS.some((kind) => kindEnabled(adapter, popovers, kind)), [adapter, popovers, columnMenuEnabled])
722
798
 
723
799
  return useMemo(
724
800
  () => ({
@@ -727,6 +803,8 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
727
803
  open,
728
804
  close,
729
805
  isOpen: () => openKindRef.current,
806
+ openColumnMenu,
807
+ closeColumnMenu,
730
808
  onCellHover,
731
809
  hideTip,
732
810
  onTipPointerEnter: () => {
@@ -753,6 +831,6 @@ export const usePopovers = (params: UsePopoversParams): PopoverController => {
753
831
  },
754
832
  tipId,
755
833
  }),
756
- [layerEnabled, open, close, onCellHover, hideTip, cancelGrace, startGrace, syncTipAriaDescribedBy, context, tipContext, tipId],
834
+ [layerEnabled, open, close, openColumnMenu, closeColumnMenu, onCellHover, hideTip, cancelGrace, startGrace, syncTipAriaDescribedBy, context, tipContext, tipId],
757
835
  )
758
836
  }