@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/dist/index.d.cts CHANGED
@@ -1386,6 +1386,31 @@ export declare const SPREADSHEET_LABEL_CATALOGS: Readonly<Record<SpreadsheetLoca
1386
1386
  */
1387
1387
  export declare const SPREADSHEET_RESERVED_SHORTCUTS: readonly string[];
1388
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
+
1389
1414
  /**
1390
1415
  * @fileoverview Rebindable command table (v0.8 ADR-17 — plan §1.5 / §2.6 / §4.1.11). Pure,
1391
1416
  * React-free: the SpreadsheetCommand vocabulary, the canonical chord grammar
@@ -1701,6 +1726,17 @@ export declare type SpreadsheetDataAdapter = {
1701
1726
  */
1702
1727
  export declare type SpreadsheetDirection = "up" | "down" | "left" | "right";
1703
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
+
1704
1740
  /** Imperative surface (§6.9-8). / 命令 API (§6.9-8)。 */
1705
1741
  export declare type SpreadsheetHandle = {
1706
1742
  /** Row-height pair seam (§6.9-8). / 行高変更の対シーム。 */
@@ -1817,10 +1853,10 @@ export declare type SpreadsheetLabelOverrides = {
1817
1853
 
1818
1854
  /**
1819
1855
  * The closed label vocabulary: every engine chrome key of `@aiquants/virtualscroll`
1820
- * (VIRTUAL_SCROLL_LABEL_KEYS) plus the 21 own keys of the spreadsheet. Every key has a value in
1856
+ * (VIRTUAL_SCROLL_LABEL_KEYS) plus the 39 own keys of the spreadsheet. Every key has a value in
1821
1857
  * each SPREADSHEET_LABEL_CATALOGS entry;
1822
1858
  * consumers override any subset through the `labels` prop (SpreadsheetLabelOverrides).
1823
- * 閉じたラベル語彙: `@aiquants/virtualscroll` のエンジンクロームキー全件 (VIRTUAL_SCROLL_LABEL_KEYS) とスプレッドシート固有の 21 キー。
1859
+ * 閉じたラベル語彙: `@aiquants/virtualscroll` のエンジンクロームキー全件 (VIRTUAL_SCROLL_LABEL_KEYS) とスプレッドシート固有の 39 キー。
1824
1860
  * 全キーが SPREADSHEET_LABEL_CATALOGS の各ロケールに値を持ち、消費者は `labels` prop で任意の部分集合を上書き。
1825
1861
  */
1826
1862
  export declare type SpreadsheetLabels = VirtualScrollLabels & {
@@ -1866,6 +1902,42 @@ export declare type SpreadsheetLabels = VirtualScrollLabels & {
1866
1902
  messageTitle: string;
1867
1903
  /** Close button of every popover. / ポップオーバー共通の閉じるボタン。 */
1868
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;
1869
1941
  };
1870
1942
 
1871
1943
  /**
@@ -1879,6 +1951,42 @@ export declare type SpreadsheetLabels = VirtualScrollLabels & {
1879
1951
  */
1880
1952
  export declare type SpreadsheetLocale = VirtualScrollLocale;
1881
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
+
1882
1990
  /**
1883
1991
  * Bulk-operation kind for the ADR-12 rejection channel (public vocabulary). Serialize-only
1884
1992
  * gestures ("copy" / "cut"), grid geometry ("resize") and the WRITE gestures ("delete" /
@@ -1945,6 +2053,28 @@ export declare type SpreadsheetProps = {
1945
2053
  * を受け、支援技術は下の列の見出しとして読む。[0, frozenRows] の整数 (見出しの行は常に凍結行)。それ以外は描画中の RangeError。
1946
2054
  */
1947
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;
1948
2078
  /**
1949
2079
  * Freezes the LAST N columns at the right edge (v0.9 — the VirtualGrid frozenTrailingCols
1950
2080
  * pass-through; LIVE prop, default 0). Validation SSOT is the engine's fail-fast contract
@@ -2552,6 +2682,46 @@ export declare type SpreadsheetScrollBarControls = {
2552
2682
  readonly enableTrackClick?: boolean;
2553
2683
  };
2554
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
+
2555
2725
  /**
2556
2726
  * Test-only seam props (NOT part of the public v0.1.0 contract — §8.2 counter injection).
2557
2727
  * テスト専用シーム props (公開 v0.1.0 契約外 — §8.2 カウンタ注入)。
package/dist/index.d.ts CHANGED
@@ -1386,6 +1386,31 @@ export declare const SPREADSHEET_LABEL_CATALOGS: Readonly<Record<SpreadsheetLoca
1386
1386
  */
1387
1387
  export declare const SPREADSHEET_RESERVED_SHORTCUTS: readonly string[];
1388
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
+
1389
1414
  /**
1390
1415
  * @fileoverview Rebindable command table (v0.8 ADR-17 — plan §1.5 / §2.6 / §4.1.11). Pure,
1391
1416
  * React-free: the SpreadsheetCommand vocabulary, the canonical chord grammar
@@ -1701,6 +1726,17 @@ export declare type SpreadsheetDataAdapter = {
1701
1726
  */
1702
1727
  export declare type SpreadsheetDirection = "up" | "down" | "left" | "right";
1703
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
+
1704
1740
  /** Imperative surface (§6.9-8). / 命令 API (§6.9-8)。 */
1705
1741
  export declare type SpreadsheetHandle = {
1706
1742
  /** Row-height pair seam (§6.9-8). / 行高変更の対シーム。 */
@@ -1817,10 +1853,10 @@ export declare type SpreadsheetLabelOverrides = {
1817
1853
 
1818
1854
  /**
1819
1855
  * The closed label vocabulary: every engine chrome key of `@aiquants/virtualscroll`
1820
- * (VIRTUAL_SCROLL_LABEL_KEYS) plus the 21 own keys of the spreadsheet. Every key has a value in
1856
+ * (VIRTUAL_SCROLL_LABEL_KEYS) plus the 39 own keys of the spreadsheet. Every key has a value in
1821
1857
  * each SPREADSHEET_LABEL_CATALOGS entry;
1822
1858
  * consumers override any subset through the `labels` prop (SpreadsheetLabelOverrides).
1823
- * 閉じたラベル語彙: `@aiquants/virtualscroll` のエンジンクロームキー全件 (VIRTUAL_SCROLL_LABEL_KEYS) とスプレッドシート固有の 21 キー。
1859
+ * 閉じたラベル語彙: `@aiquants/virtualscroll` のエンジンクロームキー全件 (VIRTUAL_SCROLL_LABEL_KEYS) とスプレッドシート固有の 39 キー。
1824
1860
  * 全キーが SPREADSHEET_LABEL_CATALOGS の各ロケールに値を持ち、消費者は `labels` prop で任意の部分集合を上書き。
1825
1861
  */
1826
1862
  export declare type SpreadsheetLabels = VirtualScrollLabels & {
@@ -1866,6 +1902,42 @@ export declare type SpreadsheetLabels = VirtualScrollLabels & {
1866
1902
  messageTitle: string;
1867
1903
  /** Close button of every popover. / ポップオーバー共通の閉じるボタン。 */
1868
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;
1869
1941
  };
1870
1942
 
1871
1943
  /**
@@ -1879,6 +1951,42 @@ export declare type SpreadsheetLabels = VirtualScrollLabels & {
1879
1951
  */
1880
1952
  export declare type SpreadsheetLocale = VirtualScrollLocale;
1881
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
+
1882
1990
  /**
1883
1991
  * Bulk-operation kind for the ADR-12 rejection channel (public vocabulary). Serialize-only
1884
1992
  * gestures ("copy" / "cut"), grid geometry ("resize") and the WRITE gestures ("delete" /
@@ -1945,6 +2053,28 @@ export declare type SpreadsheetProps = {
1945
2053
  * を受け、支援技術は下の列の見出しとして読む。[0, frozenRows] の整数 (見出しの行は常に凍結行)。それ以外は描画中の RangeError。
1946
2054
  */
1947
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;
1948
2078
  /**
1949
2079
  * Freezes the LAST N columns at the right edge (v0.9 — the VirtualGrid frozenTrailingCols
1950
2080
  * pass-through; LIVE prop, default 0). Validation SSOT is the engine's fail-fast contract
@@ -2552,6 +2682,46 @@ export declare type SpreadsheetScrollBarControls = {
2552
2682
  readonly enableTrackClick?: boolean;
2553
2683
  };
2554
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
+
2555
2725
  /**
2556
2726
  * Test-only seam props (NOT part of the public v0.1.0 contract — §8.2 counter injection).
2557
2727
  * テスト専用シーム props (公開 v0.1.0 契約外 — §8.2 カウンタ注入)。