@aiquants/spreadsheet 0.20.1 → 0.20.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,128 @@
1
+ /**
2
+ * @fileoverview The column menu button of a sort / filter header cell (`sortFilter`): one `button` placed at the cell's
3
+ * inline end, showing the sort direction (▲ ascending / ▼ descending) while the column is sorted and the menu glyph —
4
+ * a funnel while the column is filtered, a chevron otherwise — so a filtered column differs by shape, not by colour
5
+ * alone. Its accessible name is the column name, the `columnMenu` label and, while filtered, the `columnMenuFiltered`
6
+ * label; `aria-expanded` follows the menu. The button is out of the tab order (the grid keeps the focus; Alt+ArrowDown
7
+ * is the keyboard path). Its press must never reach the selection engine, which listens natively on the grid body —
8
+ * a React `stopPropagation` would come too late — so native listeners stop `pointerdown` (and its default focus move and
9
+ * text selection, for a finger or a pen too: the tap's compatibility mouse press would pull the focus out of an open
10
+ * menu, which then closes on blur and reopens on the click), `dblclick` (the edit entry) and `contextmenu` (the cell
11
+ * context menu) at the button;
12
+ * the toggle itself is the React `click`. Memoized on primitives: a re-slice of the row leaves it alone unless its own
13
+ * column's direction, filter, menu state, name or labels change. DOM hooks: `data-aqsp-column-menu-button`,
14
+ * `data-aqsp-glyph="asc" | "desc"` (the direction) and `data-aqsp-glyph="filter" | "menu"` (the menu glyph).
15
+ *
16
+ * 並べ替えと絞り込みの見出しのマスの列の品書きのボタン (`sortFilter`)。マスの終わりの側に置く `button` 1 つで、並べ替えている間は向き
17
+ * (▲ 昇順 / ▼ 降順) を、品書きの印は絞り込み中は漏斗・それ以外は山形を出す (絞り込み中は色だけでなく形で見分ける)。名前は列の名・
18
+ * 言葉 `columnMenu`・絞り込み中は言葉 `columnMenuFiltered`。`aria-expanded` は品書きに従う。Tab の順には入らない (焦点はグリッドが
19
+ * 持ち、キーボードの道は Alt+↓)。押下は選択のエンジンへ渡してはならない — エンジンはグリッドの本体で native に聞くので React の
20
+ * `stopPropagation` では遅い。そのためボタンの native の聞き手が `pointerdown` (既定の焦点の移りと字の選択も。指とペンでも止める —
21
+ * 叩きの互換のマウスの押下が焦点を開いた品書きから奪うと、品書きは blur で閉じて続く click で開き直す)・`dblclick`
22
+ * (入力の始まり)・`contextmenu` (マスの右押しの品書き) を止める。開閉そのものは React の `click`。素の値で memo し、行の再スライスでは、
23
+ * 自分の列の向き・絞り込み・品書きの開閉・名前・言葉が変わった時だけ描き直す。
24
+ */
25
+
26
+ import { memo, type ReactNode, useEffect, useRef } from "react"
27
+ import type { SpreadsheetSortDirection } from "./sortFilterModel.ts"
28
+
29
+ export type HeaderControlsProps = {
30
+ /** The column of the header cell. / 見出しのマスの列。 */
31
+ col: number
32
+ /** The column's sort direction, or null when another column (or none) is sorted. / 列の並べ替えの向き (ほかの列か無しなら null)。 */
33
+ direction: SpreadsheetSortDirection | null
34
+ /** Whether the column is filtered. / 列を絞り込んでいるか。 */
35
+ filtered: boolean
36
+ /** Whether this column's menu is open. / この列の品書きが開いているか。 */
37
+ expanded: boolean
38
+ /** The column name (the header cell's shown text, line breaks as spaces). / 列の名 (見出しのマスの見せる字。改行は空白)。 */
39
+ columnName: string
40
+ /** The resolved `columnMenu` label. / 解いた言葉 `columnMenu`。 */
41
+ menuLabel: string
42
+ /** The resolved `columnMenuFiltered` label. / 解いた言葉 `columnMenuFiltered`。 */
43
+ filteredLabel: string
44
+ /** Opens or closes the column's menu (identity-stable). / 列の品書きを開くか閉じる (同一性は安定)。 */
45
+ onToggle: (col: number) => void
46
+ }
47
+
48
+ /**
49
+ * The accessible name of the button: the column name (omitted when blank), the menu label and, while filtered, the
50
+ * filtered label in parentheses.
51
+ * ボタンの名前。列の名 (空なら省く)・品書きの言葉・絞り込み中は括弧で絞り込み中の言葉。
52
+ *
53
+ * @param columnName - The column name. 列の名。
54
+ * @param menuLabel - The menu label. 品書きの言葉。
55
+ * @param filteredLabel - The filtered label. 絞り込み中の言葉。
56
+ * @param filtered - Whether the column is filtered. 絞り込んでいるか。
57
+ * @returns The name. 名前。
58
+ */
59
+ export const columnMenuButtonName = (columnName: string, menuLabel: string, filteredLabel: string, filtered: boolean): string => {
60
+ const base = columnName.trim() === "" ? menuLabel : `${columnName} ${menuLabel}`
61
+ return filtered ? `${base} (${filteredLabel})` : base
62
+ }
63
+
64
+ /**
65
+ * Renders the column menu button of one header cell.
66
+ * 見出しのマス 1 つの列の品書きのボタンを描く。
67
+ */
68
+ const HeaderControlsInner = ({ col, direction, filtered, expanded, columnName, menuLabel, filteredLabel, onToggle }: HeaderControlsProps): ReactNode => {
69
+ const buttonRef = useRef<HTMLButtonElement | null>(null)
70
+ // DOM の native のイベントとの同期: 選択のエンジンは本体の native の聞き手なので、ボタンで native に止めないと押下・二度押し・右押しが
71
+ // 選択・入力・マスの品書きへ届く (React の合成の止め方は本体の聞き手より後に走る)
72
+ useEffect(() => {
73
+ const button = buttonRef.current
74
+ if (button === null) {
75
+ return
76
+ }
77
+ const onPointerDown = (event: PointerEvent) => {
78
+ event.stopPropagation()
79
+ // 焦点をボタンへ移さず字も選ばない (焦点は受け口か品書きに留める)。指とペンも止める — 叩きの互換のマウスの押下が焦点を
80
+ // 品書きからボタンへ移すと、blur で閉じた品書きを続く click が開き直し、2 度目の叩きで閉じられない (実の Chromium で確かめた)
81
+ event.preventDefault()
82
+ }
83
+ const stop = (event: Event) => {
84
+ event.stopPropagation()
85
+ }
86
+ button.addEventListener("pointerdown", onPointerDown)
87
+ button.addEventListener("dblclick", stop)
88
+ button.addEventListener("contextmenu", stop)
89
+ return () => {
90
+ button.removeEventListener("pointerdown", onPointerDown)
91
+ button.removeEventListener("dblclick", stop)
92
+ button.removeEventListener("contextmenu", stop)
93
+ }
94
+ }, [])
95
+ return (
96
+ <button
97
+ ref={buttonRef}
98
+ type="button"
99
+ className="aqsp-column-menu-button"
100
+ data-aqsp-column-menu-button=""
101
+ tabIndex={-1}
102
+ aria-haspopup="dialog"
103
+ aria-expanded={expanded}
104
+ aria-label={columnMenuButtonName(columnName, menuLabel, filteredLabel, filtered)}
105
+ onClick={() => onToggle(col)}>
106
+ {direction === null ? null : (
107
+ <svg className="aqsp-column-menu-glyph" data-aqsp-glyph={direction} viewBox="0 0 10 10" width="10" height="10" aria-hidden="true" focusable="false">
108
+ <path d={direction === "asc" ? "M5 1.5 9 8.5H1Z" : "M5 8.5 1 1.5h8Z"} fill="currentColor" />
109
+ </svg>
110
+ )}
111
+ {filtered ? (
112
+ <svg className="aqsp-column-menu-glyph" data-aqsp-glyph="filter" viewBox="0 0 10 10" width="10" height="10" aria-hidden="true" focusable="false">
113
+ <path d="M.5 1h9L6 5.25V9.5L4 8.25v-3Z" fill="currentColor" />
114
+ </svg>
115
+ ) : (
116
+ <svg className="aqsp-column-menu-glyph" data-aqsp-glyph="menu" viewBox="0 0 10 10" width="10" height="10" aria-hidden="true" focusable="false">
117
+ <path d="M1.5 3.25 5 6.75l3.5-3.5" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
118
+ </svg>
119
+ )}
120
+ </button>
121
+ )
122
+ }
123
+
124
+ /**
125
+ * Memo contract: every prop is a primitive except `onToggle`, which the root keeps identity-stable.
126
+ * memo の契約: `onToggle` 以外は素の値で、`onToggle` は root が同一性を保つ。
127
+ */
128
+ export const HeaderControls = memo(HeaderControlsInner)