@aiquants/spreadsheet 0.20.1 → 0.20.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +149 -0
- package/README.md +153 -10
- package/dist/index.cjs +8 -8
- package/dist/index.d.cts +301 -25
- package/dist/index.d.ts +301 -25
- package/dist/index.js +6320 -5670
- package/dist/styles/spreadsheet.css +1 -1
- package/dist/styles/spreadsheet.standalone.css +1 -1
- package/package.json +2 -2
- package/src/Spreadsheet.tsx +379 -39
- package/src/commands/useCommands.ts +27 -0
- package/src/editor/useCellEditor.ts +38 -6
- package/src/grid/GridBody.tsx +61 -3
- package/src/index.ts +23 -1
- package/src/keyboard/useGridKeyboard.ts +101 -3
- package/src/model/labels.ts +100 -10
- package/src/popover/PopoverLayer.tsx +66 -4
- package/src/popover/usePopovers.ts +87 -9
- package/src/selection/selectionState.ts +70 -0
- package/src/selection/useSelectionEngine.ts +141 -2
- package/src/sortFilter/ColumnMenu.tsx +380 -0
- package/src/sortFilter/HeaderControls.tsx +128 -0
- package/src/sortFilter/sortFilterModel.ts +648 -0
- package/src/styles/spreadsheet.css +148 -2
package/dist/index.d.cts
CHANGED
|
@@ -423,6 +423,17 @@ export declare type CommentPopoverProps = {
|
|
|
423
423
|
labels: SpreadsheetLabels;
|
|
424
424
|
};
|
|
425
425
|
|
|
426
|
+
/**
|
|
427
|
+
* What the handle's `commitEdit` did: `"committed"` — the open session closed (its text written through `applyEdits`, or
|
|
428
|
+
* closed without a write when the text was unchanged); `"rejected"` — the commit was refused and the session stays open
|
|
429
|
+
* with the typed text (the refusal went through `onEditRejected`, `onValidationRejected` or `onReadOnlyRejected`, as an
|
|
430
|
+
* Enter's would); `"idle"` — no session was open and nothing happened.
|
|
431
|
+
* handle の `commitEdit` の結果: `"committed"` — 開いていたセッションが閉じた (字を `applyEdits` で書いた、または字が変わらず書かずに
|
|
432
|
+
* 閉じた)。`"rejected"` — 確定が断られ、打った字のままセッションが続く (断りは Enter と同じく `onEditRejected`・`onValidationRejected`・
|
|
433
|
+
* `onReadOnlyRejected` で知らせた)。`"idle"` — セッションが無く、何もしなかった。
|
|
434
|
+
*/
|
|
435
|
+
export declare type CommitEditOutcome = "committed" | "rejected" | "idle";
|
|
436
|
+
|
|
426
437
|
/** Ordered comparison vocabulary of `cellValue` (the same eight words as the validation engine); between / notBetween include both bounds. / cellValue の比較語彙 (検証エンジンと同じ 8 語)。between / notBetween は両端含み。 */
|
|
427
438
|
export declare type CompareOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "between" | "notBetween";
|
|
428
439
|
|
|
@@ -555,6 +566,20 @@ export declare type EditRejection = {
|
|
|
555
566
|
source: "paste" | "fill" | "delete" | "format" | "calc" | "annotate";
|
|
556
567
|
};
|
|
557
568
|
|
|
569
|
+
/**
|
|
570
|
+
* The open in-place edit session (§6.7.1): the cell it writes to, captured when it opened, and how it opened — `"edit"`
|
|
571
|
+
* (F2, a double-click, `startEdit("edit")`: the cell's text with the caret in it) or `"replace"` (a printable key, an IME
|
|
572
|
+
* composition, `startEdit("replace")`: an empty editor). Reported by `onEditSessionChange` and read by the handle's
|
|
573
|
+
* `getEditSession`; the grid replaces the object, never mutates it.
|
|
574
|
+
* 開いているその場の入力のセッション (§6.7.1): 開いた時に捉えた書き込み先のマスと、開き方 — `"edit"` (F2・ダブルクリック・
|
|
575
|
+
* `startEdit("edit")`。マスの字にキャレット) か `"replace"` (印字キー・IME の変換・`startEdit("replace")`。空の入力欄)。
|
|
576
|
+
* `onEditSessionChange` が知らせ、handle の `getEditSession` が読む。グリッドは物を差し替え、書き換えない。
|
|
577
|
+
*/
|
|
578
|
+
export declare type EditSession = {
|
|
579
|
+
readonly cell: CellCoord;
|
|
580
|
+
readonly mode: "edit" | "replace";
|
|
581
|
+
};
|
|
582
|
+
|
|
558
583
|
/**
|
|
559
584
|
* Every write path of the grid (the union of the two EditContext arms' `source`; equal to
|
|
560
585
|
* `EditRejection["source"]`, sealed in dataAdapter.spec.ts): the editor commit ("edit" — also
|
|
@@ -1221,6 +1246,19 @@ export declare type ScrollToCellOptions = {
|
|
|
1221
1246
|
offsetY?: number;
|
|
1222
1247
|
};
|
|
1223
1248
|
|
|
1249
|
+
/**
|
|
1250
|
+
* Why a confirmed selection changed — the second argument of `onSelectionChange`. `"user"`: a gesture, a chord, a command
|
|
1251
|
+
* or a paste moved it, including a command or paste the host runs through the handle (`executeCommand`, `paste`) for the
|
|
1252
|
+
* user; `"setSelection"`: the host placed it through the handle's `setSelection`; `"sheetSwitch"`: the adapter identity
|
|
1253
|
+
* changed to a non-empty adapter and the selection reset to A1; `"countShrink"`: the same adapter's `rowCount` /
|
|
1254
|
+
* `colCount` shrank and the selection was pulled onto the grid.
|
|
1255
|
+
* 確定選択が変わった理由 — `onSelectionChange` の 2 つ目の引数。`"user"`: ジェスチャ・チョード・コマンド・貼り付けが動かした (利用側が
|
|
1256
|
+
* 利用者の代わりに handle で走らせるコマンドと貼り付け — `executeCommand`・`paste` — も含む)。`"setSelection"`: 利用側が handle の
|
|
1257
|
+
* `setSelection` で置いた。`"sheetSwitch"`: アダプタの同一性が空でないアダプタへ替わり、選択が A1 へ戻った。`"countShrink"`: 同じ
|
|
1258
|
+
* アダプタの `rowCount` / `colCount` が縮み、選択をグリッドの中へ畳んだ。
|
|
1259
|
+
*/
|
|
1260
|
+
export declare type SelectionChangeReason = "user" | "setSelection" | "sheetSwitch" | "countShrink";
|
|
1261
|
+
|
|
1224
1262
|
/** Selection state (tail of ranges = the "current range"). / 選択状態 (末尾が現在レンジ)。 */
|
|
1225
1263
|
export declare type SelectionState = {
|
|
1226
1264
|
/** Non-contiguous range list; the tail is the "current range". / 非連続選択のレンジ列 (末尾が現在レンジ)。 */
|
|
@@ -1282,6 +1320,17 @@ export declare const serializeHtmlTable: (payload: ClipPayload, clipJson: string
|
|
|
1282
1320
|
*/
|
|
1283
1321
|
export declare const serializeTsv: (matrix: readonly (readonly string[])[]) => string;
|
|
1284
1322
|
|
|
1323
|
+
/**
|
|
1324
|
+
* Options of the handle's `setSelection`. `scroll: true` brings the placed active cell into view with the keyboard's
|
|
1325
|
+
* minimal scroll (the grid's own viewport, then the page); absent or `false` leaves every scroll position alone — pair it
|
|
1326
|
+
* with `scrollToCell` for an alignment of your own.
|
|
1327
|
+
* handle の `setSelection` の選択肢。`scroll: true` は、置いたアクティブなマスをキーの移動と同じ最小の送りで見せる (グリッド自身の
|
|
1328
|
+
* 表示域、続けてページ)。無しか `false` はどのスクロール位置も変えない — 揃えを選ぶなら `scrollToCell` と組み合わせる。
|
|
1329
|
+
*/
|
|
1330
|
+
export declare type SetSelectionOptions = {
|
|
1331
|
+
scroll?: boolean;
|
|
1332
|
+
};
|
|
1333
|
+
|
|
1285
1334
|
/**
|
|
1286
1335
|
* Shifts the relative parts of every reference by (dRow, dCol) — the paste-offset transform.
|
|
1287
1336
|
* Absolute (`$`) parts stay; a reference shifted below row / column 0 becomes `#REF!` (behind
|
|
@@ -1337,6 +1386,31 @@ export declare const SPREADSHEET_LABEL_CATALOGS: Readonly<Record<SpreadsheetLoca
|
|
|
1337
1386
|
*/
|
|
1338
1387
|
export declare const SPREADSHEET_RESERVED_SHORTCUTS: readonly string[];
|
|
1339
1388
|
|
|
1389
|
+
/**
|
|
1390
|
+
* One column's filter: the checked values of an exact match (the rows whose value is one of them stay), or the query of a
|
|
1391
|
+
* fuzzy search.
|
|
1392
|
+
* 1 つの列の絞り込み。完全一致で印を付けた値 (どれかと同じ値の行が残る)、またはあいまい検索の語。
|
|
1393
|
+
*/
|
|
1394
|
+
export declare type SpreadsheetColumnFilter = {
|
|
1395
|
+
readonly mode: "exact";
|
|
1396
|
+
readonly values: readonly string[];
|
|
1397
|
+
} | {
|
|
1398
|
+
readonly mode: "fuzzy";
|
|
1399
|
+
readonly query: string;
|
|
1400
|
+
};
|
|
1401
|
+
|
|
1402
|
+
/**
|
|
1403
|
+
* What a column offers: whether it sorts, whether it filters, the match modes it offers (at least one) and the mode its menu
|
|
1404
|
+
* starts with (one of them).
|
|
1405
|
+
* 列が持つ操作。並べ替えできるか・絞り込めるか・使える検索方法 (1 つ以上)・品書きの初めの方法 (使える方法のどれか)。
|
|
1406
|
+
*/
|
|
1407
|
+
export declare type SpreadsheetColumnSortFilterOptions = {
|
|
1408
|
+
readonly sortable: boolean;
|
|
1409
|
+
readonly filterable: boolean;
|
|
1410
|
+
readonly matchModes: readonly SpreadsheetMatchMode[];
|
|
1411
|
+
readonly defaultMatchMode: SpreadsheetMatchMode;
|
|
1412
|
+
};
|
|
1413
|
+
|
|
1340
1414
|
/**
|
|
1341
1415
|
* @fileoverview Rebindable command table (v0.8 ADR-17 — plan §1.5 / §2.6 / §4.1.11). Pure,
|
|
1342
1416
|
* React-free: the SpreadsheetCommand vocabulary, the canonical chord grammar
|
|
@@ -1652,6 +1726,17 @@ export declare type SpreadsheetDataAdapter = {
|
|
|
1652
1726
|
*/
|
|
1653
1727
|
export declare type SpreadsheetDirection = "up" | "down" | "left" | "right";
|
|
1654
1728
|
|
|
1729
|
+
/**
|
|
1730
|
+
* One row of an exact-match value list: the value the filter stores, the text the menu shows (an empty label shows the
|
|
1731
|
+
* `filterBlank` label) and the number of rows holding it.
|
|
1732
|
+
* 完全一致の値の一覧の 1 行。絞り込みが持つ値、品書きが見せる字 (空の字は言葉 `filterBlank` で出す)、その値を持つ行の数。
|
|
1733
|
+
*/
|
|
1734
|
+
export declare type SpreadsheetFilterValue = {
|
|
1735
|
+
readonly value: string;
|
|
1736
|
+
readonly label: string;
|
|
1737
|
+
readonly count: number;
|
|
1738
|
+
};
|
|
1739
|
+
|
|
1655
1740
|
/** Imperative surface (§6.9-8). / 命令 API (§6.9-8)。 */
|
|
1656
1741
|
export declare type SpreadsheetHandle = {
|
|
1657
1742
|
/** Row-height pair seam (§6.9-8). / 行高変更の対シーム。 */
|
|
@@ -1706,6 +1791,46 @@ export declare type SpreadsheetHandle = {
|
|
|
1706
1791
|
paste: (options: PasteOptions) => Promise<PasteOutcome>;
|
|
1707
1792
|
/** The confirmed selection (imperative read). / 確定選択の命令読み。 */
|
|
1708
1793
|
getSelection: () => SelectionState;
|
|
1794
|
+
/**
|
|
1795
|
+
* Places the selection — its ranges, anchor and active cell — where the host decides (a row the page chose from its
|
|
1796
|
+
* URL, the same month after the host moved the window a year). It goes through the same write path as a gesture:
|
|
1797
|
+
* `onSelectionChange` fires once with reason `"setSelection"` (never for a selection equal to the current one), the
|
|
1798
|
+
* announcement formatters run, the active cell's input message shows, and the next Arrow key moves from the placed
|
|
1799
|
+
* active cell. The grid keeps a copy, so the host may reuse its object. A hidden row or column is a valid place.
|
|
1800
|
+
* Focus does not move (call `focus()` for that), and an open popover keeps its cell.
|
|
1801
|
+
* 選択 (レンジ・anchor・アクティブなマス) を利用側が決めた所へ置く (ページが URL から選んだ行・利用側が窓を 1 年送った後の同じ月)。
|
|
1802
|
+
* ジェスチャと同じ書き込みの道を通る: `onSelectionChange` が理由 `"setSelection"` で 1 回発火 (今と等しい選択では発火しない)、読み上げの
|
|
1803
|
+
* 整形が走り、アクティブなマスの入力メッセージが出て、次の矢印キーは置いたアクティブなマスから動く。グリッドは写しを持つので、利用側は
|
|
1804
|
+
* 自分の物を使い回してよい。隠した行・列の上にも置ける。焦点は動かさず (要るなら `focus()`)、開いているポップオーバーは自分のマスを保つ。
|
|
1805
|
+
*
|
|
1806
|
+
* @param selection - The ranges (at least one, each start at most its end), the anchor (inside the last range) and the active cell (inside some range), all inside the grid. レンジ (1 つ以上、始まりは終わり以下)・anchor (末尾のレンジの中)・アクティブなマス (どれかのレンジの中)。どれもグリッドの中。
|
|
1807
|
+
* @param options - `scroll: true` brings the active cell into view as an Arrow key does; absent or `false` leaves the scroll alone. `scroll: true` は矢印キーと同じくアクティブなマスを見せる。無しか `false` は送らない。
|
|
1808
|
+
* @returns True when the selection is placed (or already was); false — nothing changed — while a cell is being edited (the session stays open) or a pointer drag is in flight. 置けた (または既にその選択だった) なら true。セルの入力中 (セッションは続く) とポインタのドラッグの途中は false で何も変えない。
|
|
1809
|
+
* @throws {RangeError} When the selection is not a valid selection of the grid (no range, a bound that is not a whole number inside the grid, a range whose start is after its end, the anchor outside the last range, the active cell outside every range — a grid without rows or columns throws for any selection), or `options.scroll` is neither `true`, `false` nor absent. 選択がグリッドの正しい選択でないとき (レンジが無い・境がグリッドの中の整数でない・始まりが終わりより後のレンジ・末尾のレンジの外の anchor・どのレンジの外のアクティブなマス — 行か列の無いグリッドではどの選択も投げる)、または `options.scroll` が `true`・`false`・無しのどれでもないとき。
|
|
1810
|
+
*/
|
|
1811
|
+
setSelection: (selection: SelectionState, options?: SetSelectionOptions) => boolean;
|
|
1812
|
+
/**
|
|
1813
|
+
* The open in-place edit session — the cell it writes to and how it opened — or null when no cell is being edited
|
|
1814
|
+
* (the same object `onEditSessionChange` last reported).
|
|
1815
|
+
* 開いているその場の入力のセッション (書き込み先のマスと開き方)。入力中のセルが無ければ null (`onEditSessionChange` が最後に知らせた物と同じ)。
|
|
1816
|
+
*
|
|
1817
|
+
* @returns The session, or null. セッション、または null。
|
|
1818
|
+
*/
|
|
1819
|
+
getEditSession: () => EditSession | null;
|
|
1820
|
+
/**
|
|
1821
|
+
* Commits the open session as Enter does, without moving the active cell — for a host that saves from outside the
|
|
1822
|
+
* grid's keys (a Ctrl+S listener) and must not lose the typed text. The text is validated and written through
|
|
1823
|
+
* `applyEdits` when it changed; an unchanged text just closes the session. A refused commit keeps the session open
|
|
1824
|
+
* with the typed text and reports the refusal through the same callback as an Enter. An IME composition in flight is
|
|
1825
|
+
* confirmed first, as a press elsewhere in the grid confirms it (the hidden input blurs and takes the focus back).
|
|
1826
|
+
* 開いているセッションを Enter と同じく確定する (アクティブなマスは動かさない) — グリッドのキーの外で保存する利用側 (Ctrl+S の聞き手)
|
|
1827
|
+
* が、打った字を失わないため。字が変わっていれば検めて `applyEdits` で書き、変わっていなければセッションを閉じるだけ。断られた確定は打った字の
|
|
1828
|
+
* ままセッションを続け、Enter と同じ口で断りを知らせる。IME の変換中なら、グリッドの中の押下と同じく先に変換を確定させる (隠れた入力欄を
|
|
1829
|
+
* blur して焦点を取り戻す)。
|
|
1830
|
+
*
|
|
1831
|
+
* @returns `"committed"` when the session closed, `"rejected"` when the commit was refused (the session stays), `"idle"` when no session was open. セッションが閉じたら `"committed"`、断られたら `"rejected"` (セッションは続く)、開いていなければ `"idle"`。
|
|
1832
|
+
*/
|
|
1833
|
+
commitEdit: () => CommitEditOutcome;
|
|
1709
1834
|
/** The adapter's BASE format of a cell (toolbar state) — the getCellFormat capability branch. / セルの base 書式 (getCellFormat の能力分岐)。 */
|
|
1710
1835
|
getBaseFormat: (cell: CellCoord) => CellFormat | undefined;
|
|
1711
1836
|
/** base ⊕ conditional formats of a cell (the paint the user sees). / base ⊕ 条件付き書式 (描画される書式)。 */
|
|
@@ -1728,10 +1853,10 @@ export declare type SpreadsheetLabelOverrides = {
|
|
|
1728
1853
|
|
|
1729
1854
|
/**
|
|
1730
1855
|
* The closed label vocabulary: every engine chrome key of `@aiquants/virtualscroll`
|
|
1731
|
-
* (VIRTUAL_SCROLL_LABEL_KEYS) plus the
|
|
1856
|
+
* (VIRTUAL_SCROLL_LABEL_KEYS) plus the 39 own keys of the spreadsheet. Every key has a value in
|
|
1732
1857
|
* each SPREADSHEET_LABEL_CATALOGS entry;
|
|
1733
1858
|
* consumers override any subset through the `labels` prop (SpreadsheetLabelOverrides).
|
|
1734
|
-
* 閉じたラベル語彙: `@aiquants/virtualscroll` のエンジンクロームキー全件 (VIRTUAL_SCROLL_LABEL_KEYS) とスプレッドシート固有の
|
|
1859
|
+
* 閉じたラベル語彙: `@aiquants/virtualscroll` のエンジンクロームキー全件 (VIRTUAL_SCROLL_LABEL_KEYS) とスプレッドシート固有の 39 キー。
|
|
1735
1860
|
* 全キーが SPREADSHEET_LABEL_CATALOGS の各ロケールに値を持ち、消費者は `labels` prop で任意の部分集合を上書き。
|
|
1736
1861
|
*/
|
|
1737
1862
|
export declare type SpreadsheetLabels = VirtualScrollLabels & {
|
|
@@ -1777,6 +1902,42 @@ export declare type SpreadsheetLabels = VirtualScrollLabels & {
|
|
|
1777
1902
|
messageTitle: string;
|
|
1778
1903
|
/** Close button of every popover. / ポップオーバー共通の閉じるボタン。 */
|
|
1779
1904
|
popoverClose: string;
|
|
1905
|
+
/** Column menu (v0.20.3 `sortFilter`): the menu's name and the menu button's name after the column name. / 列の品書き (v0.20.3 `sortFilter`) — 品書きの名前と、列の名に続く品書きのボタンの名前。 */
|
|
1906
|
+
columnMenu: string;
|
|
1907
|
+
/** Column menu: the suffix of the button's name while the column is filtered. / 列の品書き — 絞り込み中の列のボタンの名前の添え字。 */
|
|
1908
|
+
columnMenuFiltered: string;
|
|
1909
|
+
/** Column menu: sort ascending. / 列の品書き — 昇順で並べ替え。 */
|
|
1910
|
+
sortAscending: string;
|
|
1911
|
+
/** Column menu: sort descending. / 列の品書き — 降順で並べ替え。 */
|
|
1912
|
+
sortDescending: string;
|
|
1913
|
+
/** Column menu: clear this column's sort. / 列の品書き — この列の並べ替えを外す。 */
|
|
1914
|
+
sortClear: string;
|
|
1915
|
+
/** Column menu: the legend of the match-mode switch. / 列の品書き — 検索方法の切り替えの見出し。 */
|
|
1916
|
+
filterMatchMode: string;
|
|
1917
|
+
/** Column menu: the exact-match mode. / 列の品書き — 完全一致の方法。 */
|
|
1918
|
+
filterModeExact: string;
|
|
1919
|
+
/** Column menu: the fuzzy-search mode. / 列の品書き — あいまい検索の方法。 */
|
|
1920
|
+
filterModeFuzzy: string;
|
|
1921
|
+
/** Column menu: the value search box. / 列の品書き — 値を探す欄。 */
|
|
1922
|
+
filterSearchValues: string;
|
|
1923
|
+
/** Column menu: check every value the search matches. / 列の品書き — 探す語に当たる値に全て印を付ける。 */
|
|
1924
|
+
filterSelectAll: string;
|
|
1925
|
+
/** Column menu: uncheck every value the search matches. / 列の品書き — 探す語に当たる値の印を全て外す。 */
|
|
1926
|
+
filterSelectNone: string;
|
|
1927
|
+
/** Column menu: the text shown for a value with an empty label. / 列の品書き — 字が空の値に見せる字。 */
|
|
1928
|
+
filterBlank: string;
|
|
1929
|
+
/** Column menu: the value list is loading. / 列の品書き — 値の一覧の読み込み中。 */
|
|
1930
|
+
filterLoading: string;
|
|
1931
|
+
/** Column menu: the value list could not be loaded. / 列の品書き — 値の一覧を読めなかった。 */
|
|
1932
|
+
filterLoadFailed: string;
|
|
1933
|
+
/** Column menu: the fuzzy-search query field. / 列の品書き — あいまい検索の語の欄。 */
|
|
1934
|
+
filterQuery: string;
|
|
1935
|
+
/** Column menu: apply the filter. / 列の品書き — 絞り込みを当てる。 */
|
|
1936
|
+
filterApply: string;
|
|
1937
|
+
/** Column menu: clear this column's filter. / 列の品書き — この列の絞り込みを外す。 */
|
|
1938
|
+
filterClearColumn: string;
|
|
1939
|
+
/** Column menu: clear every column's filter. / 列の品書き — すべての列の絞り込みを外す。 */
|
|
1940
|
+
filterClearAll: string;
|
|
1780
1941
|
};
|
|
1781
1942
|
|
|
1782
1943
|
/**
|
|
@@ -1790,6 +1951,42 @@ export declare type SpreadsheetLabels = VirtualScrollLabels & {
|
|
|
1790
1951
|
*/
|
|
1791
1952
|
export declare type SpreadsheetLocale = VirtualScrollLocale;
|
|
1792
1953
|
|
|
1954
|
+
/**
|
|
1955
|
+
* @fileoverview The model of header sorting and per-column filtering (`sortFilter`): the seven public types, the
|
|
1956
|
+
* render-time validation `resolveSortFilter` and the pure state transitions the header press and the column menu use.
|
|
1957
|
+
* The package never orders or drops rows itself — the host owns the state (a controlled prop), matches the rows and
|
|
1958
|
+
* reorders its adapter; this module only decides which columns carry the controls, which state is well formed and
|
|
1959
|
+
* what the next state is. Every function is pure and React-free.
|
|
1960
|
+
*
|
|
1961
|
+
* Contract:
|
|
1962
|
+
* - `resolveSortFilter(sortFilter, colCount, headerRows)` reads every column key and option once and throws a
|
|
1963
|
+
* `RangeError` (message prefix `[spreadsheet] sortFilter`) on a malformed prop, options or state: no header row to
|
|
1964
|
+
* hold the controls, an unknown or mistyped member, empty / unknown / repeated match modes, a default mode the
|
|
1965
|
+
* column cannot use, an empty or repeated column key, exact matching without `getFilterValues`, and a state naming
|
|
1966
|
+
* an unknown column, sorting a column that cannot sort, filtering a column that cannot filter, or using a mode the
|
|
1967
|
+
* column does not offer.
|
|
1968
|
+
* - The transitions (`cycleSort`, `withSort`, `withExactFilter`, `withFuzzyFilter`, `withoutFilter`,
|
|
1969
|
+
* `withoutFilters`) return a new state and never mutate their input; `withExactFilter` lifts the filter when every
|
|
1970
|
+
* listed value is checked (it then keeps the same rows) and `withFuzzyFilter` lifts it for a blank query.
|
|
1971
|
+
* - `sameSortFilterState` compares two states by shape, so an action that would hand the host the state it already
|
|
1972
|
+
* has is dropped.
|
|
1973
|
+
* - `validateFilterValues` checks the host's value list (strings, a non-negative integer count, no repeated value)
|
|
1974
|
+
* and `filterValueMatches` is the value search of the column menu (NFKC, lower case, substring).
|
|
1975
|
+
*
|
|
1976
|
+
* 見出しの並べ替えと列ごとの絞り込み (`sortFilter`) のモデル。公開の型 7 つ、描く時の検め `resolveSortFilter`、見出しの押下と列の
|
|
1977
|
+
* 品書きが使う状態の純関数。部品は行を並べ替えも落としもしない — 状態は利用側が持ち (制御された props)、行の照合とアダプタの並べ直しも
|
|
1978
|
+
* 利用側。このモジュールは、操作を持つ列・状態の形の正しさ・次の状態だけを決める。全て純関数で React に依らない。
|
|
1979
|
+
* 契約: `resolveSortFilter` は全ての列の鍵と指定を 1 回ずつ読み、誤った props・指定・状態を `RangeError` (文の頭は
|
|
1980
|
+
* `[spreadsheet] sortFilter`) で止める (操作を置く見出しの行が無い・知らない項目や型の誤り・空や知らない名や重なる検索方法・使えない
|
|
1981
|
+
* 初めの方法・空や重なる列の鍵・`getFilterValues` 無しの完全一致・知らない列や並べ替えできない列や絞り込めない列や使えない方法を名指す
|
|
1982
|
+
* 状態)。状態の関数は新しい状態を返し、入力を変えない。`withExactFilter` は一覧の全ての値に印があれば絞り込みを外し (残る行が同じ)、
|
|
1983
|
+
* `withFuzzyFilter` は空白だけの語で外す。`sameSortFilterState` は形で比べ、利用側が既に持つ状態を知らせない。
|
|
1984
|
+
* `validateFilterValues` は利用側の値の一覧 (文字列・0 以上の整数の件数・値の重なり無し) を検め、`filterValueMatches` は品書きの値の
|
|
1985
|
+
* 探す欄の照合 (NFKC・小文字・部分一致)。
|
|
1986
|
+
*/
|
|
1987
|
+
/** A match mode of a column filter: exact values or a fuzzy query (the host does the matching). / 列の絞り込みの検索方法。完全一致か、あいまい検索 (照合は利用側)。 */
|
|
1988
|
+
export declare type SpreadsheetMatchMode = "exact" | "fuzzy";
|
|
1989
|
+
|
|
1793
1990
|
/**
|
|
1794
1991
|
* Bulk-operation kind for the ADR-12 rejection channel (public vocabulary). Serialize-only
|
|
1795
1992
|
* gestures ("copy" / "cut"), grid geometry ("resize") and the WRITE gestures ("delete" /
|
|
@@ -1856,6 +2053,28 @@ export declare type SpreadsheetProps = {
|
|
|
1856
2053
|
* を受け、支援技術は下の列の見出しとして読む。[0, frozenRows] の整数 (見出しの行は常に凍結行)。それ以外は描画中の RangeError。
|
|
1857
2054
|
*/
|
|
1858
2055
|
headerRows?: number;
|
|
2056
|
+
/**
|
|
2057
|
+
* Header sorting and per-column filtering (v0.20.3). The host owns the state (a controlled prop) and the rows: it
|
|
2058
|
+
* matches and reorders its adapter when `onStateChange` reports a new state. The package draws the controls on the
|
|
2059
|
+
* last header row (`headerRows - 1`) — pressing a sortable column's header cell (a mouse click, a finger or pen tap)
|
|
2060
|
+
* cycles ascending → descending → unsorted, and the cell's ▼ button or Alt+ArrowDown opens the column menu (sort,
|
|
2061
|
+
* match mode, exact value list or fuzzy query, apply, clear) — and decides when the state may change: the in-place
|
|
2062
|
+
* edit is committed first (Enter's commit; a refusal changes nothing), then the column menu, the interactive popover
|
|
2063
|
+
* and the note tip close and the copy / cut marquee is dropped, then `onStateChange` is called once (never with a state
|
|
2064
|
+
* of the same shape). The selection keeps its position. Every member is read at render and the whole object is
|
|
2065
|
+
* validated again whenever its identity changes (memoize it); a malformed prop, option or state is a RangeError during
|
|
2066
|
+
* render. An empty grid (no row or no column) draws no control and validates nothing (the check runs once data
|
|
2067
|
+
* arrives). Absent = no control, the v0.20.2 DOM and behaviour.
|
|
2068
|
+
* 見出しの並べ替えと列ごとの絞り込み (v0.20.3)。状態 (制御された props) と行は利用側が持ち、`onStateChange` が知らせた新しい状態で
|
|
2069
|
+
* アダプタの行を照らして並べ直す。部品は見出しの最後の行 (`headerRows - 1`) に操作を描き (並べ替えできる列の見出しのマスの押下 —
|
|
2070
|
+
* マウスのクリック・指とペンの叩き — は昇順 → 降順 → 無しと巡り、マスの ▼ と Alt+↓ は列の品書き — 並べ替え・検索方法・完全一致の
|
|
2071
|
+
* 値の一覧かあいまい検索の語・当てる・外す — を開く)、状態を変えてよい時を見極める: その場の入力は先に確定し (Enter と同じ確定。
|
|
2072
|
+
* 断られたら何も変えない)、次に列の品書き・対話のポップオーバー・メモの吹き出しを閉じて写しの印を捨て、`onStateChange` を 1 回呼ぶ
|
|
2073
|
+
* (同じ形の状態では呼ばない)。選択は位置を保つ。全ての項目を描く時に読み、物が替わるたびに全体を検め直す (memo して渡す)。誤った
|
|
2074
|
+
* props・指定・状態は描く時の RangeError。空の表 (行か列が 0) は操作を描かず、何も検めない (データが来て描いた時に検める)。無ければ
|
|
2075
|
+
* 操作は無く、DOM と動きは v0.20.2 と同じ。
|
|
2076
|
+
*/
|
|
2077
|
+
sortFilter?: SpreadsheetSortFilter;
|
|
1859
2078
|
/**
|
|
1860
2079
|
* Freezes the LAST N columns at the right edge (v0.9 — the VirtualGrid frozenTrailingCols
|
|
1861
2080
|
* pass-through; LIVE prop, default 0). Validation SSOT is the engine's fail-fast contract
|
|
@@ -2005,31 +2224,48 @@ export declare type SpreadsheetProps = {
|
|
|
2005
2224
|
renderCell?: (ctx: RenderCellContext) => ReactNode;
|
|
2006
2225
|
/**
|
|
2007
2226
|
* Fires on every confirmed SelectionState change (press replace, extend confirm, cycling,
|
|
2008
|
-
* paste replace, Ctrl+A, ...),
|
|
2009
|
-
*
|
|
2010
|
-
*
|
|
2011
|
-
*
|
|
2012
|
-
*
|
|
2013
|
-
*
|
|
2014
|
-
*
|
|
2015
|
-
*
|
|
2016
|
-
*
|
|
2017
|
-
*
|
|
2018
|
-
*
|
|
2019
|
-
*
|
|
2227
|
+
* paste replace, Ctrl+A, ...), with the reason as the second argument
|
|
2228
|
+
* ({@link SelectionChangeReason}): `"user"` for gestures, chords, commands and pastes — one
|
|
2229
|
+
* run by a handle call too (the handle `paste` moves the selection to the written block and
|
|
2230
|
+
* fires like the keyboard paste) — and `"setSelection"` for the handle's `setSelection`. Never
|
|
2231
|
+
* during a drag (state frozen — one fire at pointerup), with ONE documented in-drag firing
|
|
2232
|
+
* point: the header subtract reservation converts to a real press on the first movement,
|
|
2233
|
+
* firing the deferred press replace mid-drag (total fire count matches v0.1 — conversion 1 +
|
|
2234
|
+
* up 1). Never for the initial A1 mount. TWO adapter-driven fire points, each firing from a
|
|
2235
|
+
* layout effect of the commit that brings the new adapter or counts (neither a gesture nor a
|
|
2236
|
+
* handle call): a sheet switch (a new adapter identity) to a non-empty adapter resets the
|
|
2237
|
+
* selection to A1 through the wrapper and fires once with `"sheetSwitch"`, unless the
|
|
2238
|
+
* selection already was the lone cell A1; and a same-adapter rowCount / colCount shrink that
|
|
2239
|
+
* moved the selection fires once with `"countShrink"` (ADR-33). A switch or a shrink that
|
|
2240
|
+
* leaves 0 rows or 0 columns (so no A1) writes the empty-grid state directly and never fires.
|
|
2020
2241
|
* Independent of the live region's 200ms debounce (firing point: the §6.9-1 setSelection
|
|
2021
2242
|
* wrapper).
|
|
2022
|
-
* 確定 SelectionState
|
|
2023
|
-
* `
|
|
2024
|
-
*
|
|
2025
|
-
*
|
|
2026
|
-
*
|
|
2027
|
-
*
|
|
2028
|
-
*
|
|
2029
|
-
*
|
|
2030
|
-
*
|
|
2031
|
-
|
|
2032
|
-
|
|
2243
|
+
* 確定 SelectionState が変わるたびに発火し、2 つ目の引数で理由を渡す ({@link SelectionChangeReason}):
|
|
2244
|
+
* ジェスチャ・チョード・コマンド・貼り付けは `"user"` (handle の呼び出しが走らせた変化も — handle の
|
|
2245
|
+
* `paste` は選択を書いた範囲へ動かし、キーボードの貼り付けと同じく発火)、handle の `setSelection` は
|
|
2246
|
+
* `"setSelection"`。ドラッグ中と初期マウントでは発火しない。明文のドラッグ中発火点が 1 つ: ヘッダー減算
|
|
2247
|
+
* 予約の実 press 変換 (初動 move) は遅延 press 置換をドラッグ中に発火する (発火総数は v0.1 と同一 —
|
|
2248
|
+
* 変換 1 + up 1)。adapter 起点の発火点は 2 つで、どちらも新しい adapter や行数・列数を運んだ commit の
|
|
2249
|
+
* layout effect から発火 (ジェスチャでも handle の呼び出しでもない): 空でない adapter へのシート切替
|
|
2250
|
+
* (adapter の同一性の変化) は、ラッパー経由の A1 へのリセットで `"sheetSwitch"` を 1 回発火 (選択が
|
|
2251
|
+
* 既に A1 の 1 マスだけなら発火なし)。同一 adapter の rowCount / colCount 縮小で選択が動いたときは
|
|
2252
|
+
* `"countShrink"` を 1 回発火 (ADR-33)。0 行または 0 列 (A1 が無い) になる切替と縮小は、空グリッドの
|
|
2253
|
+
* 状態をラッパーを通さずに書き、発火なし。
|
|
2254
|
+
*/
|
|
2255
|
+
onSelectionChange?: (selection: SelectionState, reason: SelectionChangeReason) => void;
|
|
2256
|
+
/**
|
|
2257
|
+
* Notice of the in-place edit session: the new {@link EditSession} right after a session opens (F2, a double-click,
|
|
2258
|
+
* a printable key, an IME composition, the handle's `startEdit`), `null` right after it closes — a commit (after
|
|
2259
|
+
* `applyEdits` returned, before the Enter / Tab that committed moves the active cell), a cancel, the focus leaving
|
|
2260
|
+
* the grid, an adapter switch, a count shrink that removed the cell, an editing Ctrl+Enter fill. A refused commit
|
|
2261
|
+
* keeps the session open and reports nothing here. Not called on unmount. Read when it fires (no remount). The
|
|
2262
|
+
* handle's `getEditSession` returns the same object.
|
|
2263
|
+
* その場の入力のセッションの知らせ: セッションが開いた直後 (F2・ダブルクリック・印字キー・IME の変換・handle の `startEdit`) に新しい
|
|
2264
|
+
* {@link EditSession}、閉じた直後に `null` — 確定 (`applyEdits` が戻った後、確定した Enter / Tab がアクティブなマスを動かす前)・取り消し・
|
|
2265
|
+
* 焦点のグリッドの外への離脱・アダプタの切り替え・マスを消した縮小・入力中の Ctrl+Enter の埋め。断られた確定はセッションを続け、ここでは
|
|
2266
|
+
* 何も知らせない。アンマウントでは呼ばない。発火の時に読む (再マウント不要)。handle の `getEditSession` は同じ物を返す。
|
|
2267
|
+
*/
|
|
2268
|
+
onEditSessionChange?: (session: EditSession | null) => void;
|
|
2033
2269
|
/** Consumer context menu (§6.4.3-4 / §6.6.1 Shift+F10); keyboard origin carries the active cell viewport rect. / consumer コンテキストメニュー。 */
|
|
2034
2270
|
onCellContextMenu?: (cell: CellCoord, origin: {
|
|
2035
2271
|
kind: "pointer";
|
|
@@ -2446,6 +2682,46 @@ export declare type SpreadsheetScrollBarControls = {
|
|
|
2446
2682
|
readonly enableTrackClick?: boolean;
|
|
2447
2683
|
};
|
|
2448
2684
|
|
|
2685
|
+
/** A sort direction. / 並べ替えの向き。 */
|
|
2686
|
+
export declare type SpreadsheetSortDirection = "asc" | "desc";
|
|
2687
|
+
|
|
2688
|
+
/**
|
|
2689
|
+
* The `sortFilter` prop. The package reads every member at render and validates the whole object again whenever its
|
|
2690
|
+
* identity changes, so a host passes a memoized object.
|
|
2691
|
+
* - `state` / `onStateChange`: the controlled state; `onStateChange` is called once per accepted action, after the
|
|
2692
|
+
* in-place edit has been committed, and never with a state equal in shape to `state`.
|
|
2693
|
+
* - `getColumnKey(col)`: the host's key of a column, or `null` for a column without controls; keys are unique.
|
|
2694
|
+
* - `defaults` / `getColumnOptions(key)`: the options of every column, and the members one column overrides.
|
|
2695
|
+
* - `getFilterValues(key, state, signal)`: the value list of an exact match, counted over the rows the OTHER columns'
|
|
2696
|
+
* filters keep; required when a column offers the exact mode; `signal` aborts when the menu closes.
|
|
2697
|
+
* props `sortFilter`。部品は描く時に全ての項目を読み、物が替わるたびに全体を検め直すので、利用側は memo した物を渡す。
|
|
2698
|
+
* `state` / `onStateChange` は制御された状態 (`onStateChange` は受けた操作ごとに 1 回、入力を確定した後に呼び、`state` と同じ形の状態では
|
|
2699
|
+
* 呼ばない)。`getColumnKey(col)` は列の利用側の鍵 (操作を持たない列は `null`。鍵は重ならない)。`defaults` / `getColumnOptions(key)` は
|
|
2700
|
+
* 全ての列の指定と、列ごとに差し替える項目。`getFilterValues(key, state, signal)` は完全一致の値の一覧 (ほかの列の絞り込みが残す行から
|
|
2701
|
+
* 数える。完全一致を使える列があれば必須。品書きを閉じると `signal` が止まる)。
|
|
2702
|
+
*/
|
|
2703
|
+
export declare type SpreadsheetSortFilter = {
|
|
2704
|
+
readonly state: SpreadsheetSortFilterState;
|
|
2705
|
+
readonly onStateChange: (next: SpreadsheetSortFilterState) => void;
|
|
2706
|
+
readonly getColumnKey: (col: number) => string | null;
|
|
2707
|
+
readonly defaults: SpreadsheetColumnSortFilterOptions;
|
|
2708
|
+
readonly getColumnOptions?: (columnKey: string) => Partial<SpreadsheetColumnSortFilterOptions>;
|
|
2709
|
+
readonly getFilterValues?: (columnKey: string, state: SpreadsheetSortFilterState, signal: AbortSignal) => Promise<readonly SpreadsheetFilterValue[]>;
|
|
2710
|
+
};
|
|
2711
|
+
|
|
2712
|
+
/**
|
|
2713
|
+
* The sort and filter state the host owns: at most one sorted column and one filter per column key (every filter must hold
|
|
2714
|
+
* for a row to stay).
|
|
2715
|
+
* 利用側が持つ並べ替えと絞り込みの状態。並べ替える列は 1 つまで、絞り込みは列の鍵ごとに 1 つ (行が残るには全ての絞り込みに当たる)。
|
|
2716
|
+
*/
|
|
2717
|
+
export declare type SpreadsheetSortFilterState = {
|
|
2718
|
+
readonly sort: {
|
|
2719
|
+
readonly columnKey: string;
|
|
2720
|
+
readonly direction: SpreadsheetSortDirection;
|
|
2721
|
+
} | null;
|
|
2722
|
+
readonly filters: Readonly<Record<string, SpreadsheetColumnFilter>>;
|
|
2723
|
+
};
|
|
2724
|
+
|
|
2449
2725
|
/**
|
|
2450
2726
|
* Test-only seam props (NOT part of the public v0.1.0 contract — §8.2 counter injection).
|
|
2451
2727
|
* テスト専用シーム props (公開 v0.1.0 契約外 — §8.2 カウンタ注入)。
|