@ishibashi0112/spreadsheet-grid-core 0.41.0 → 0.41.1

package/dist/model/gridTypes.core.d.ts

@@ -255,14 +255,47 @@ export type DetailRowRenderContext<T> = {
     sourceRowIndex: number;
     collapse: () => void;
 };
+/**
+ * 展開行(Master/Detail)の設定です(`detailRow` prop)。指定したときだけ機能が有効になります。
+ *
+ * 各フィールドの説明は React 版パッケージ `@ishibashi0112/spreadsheet-grid` に同梱の `API_REFERENCE.md`
+ * の「展開行(Master/Detail)」節と同じ内容です。
+ */
 export type DetailRowOptions<T, F extends GridFrameworkTypes = GridFrameworkTypes> = {
+    /**
+     * 展開行の中身。`ctx = { row, rowKey, rowIndex, sourceRowIndex, collapse }`(`rowIndex` はビュー行
+     * index、`collapse()` はその展開行を閉じる)。帯の内側のカード要素(`.ssg-detail-card`、
+     * `data-ssg-detail` 属性つき)に描画される。
+     */
     render: (ctx: DetailRowRenderContext<T>) => F['node'];
+    /**
+     * 帯の高さ(px)。**固定高**で、中身が超えるとカード内でスクロールする(auto 高は非対応)。
+     *
+     * @defaultValue `200`
+     */
     height?: number;
+    /**
+     * 行ごとの展開可否。`false` の行はトグルが描画されず、命令的 API / `ctx.detail.toggle()`
+     * からの展開も no-op。
+     *
+     * @defaultValue 全行展開可
+     */
     isExpandable?: (row: T, ctx: {
         rowKey: GridRowKey;
         sourceRowIndex: number;
     }) => boolean;
+    /**
+     * 専用トグル列(幅 28px・タイトル無し、行ヘッダーの右隣 = 先頭列。左固定列があるときは左固定側)
+     * を自動挿入する。`false` にすると列は挿入されず、任意の列の `renderCell` から
+     * `ctx.detail.toggle()` でトグルを自前配置する(下記)。
+     *
+     * @defaultValue `true`
+     */
     showToggleColumn?: boolean;
+    /**
+     * カード要素へ追加する class(または `{ className, style }`。`classNames.detailCard`
+     * に加えて付与)。
+     */
     className?: GridSlotProps<F>;
 };
 export type LabelRowSortMode = 'section' | 'follow' | 'hide';
@@ -281,15 +314,58 @@ export type LabelRowRenderContext<T> = {
     label: string;
     sectionRowCount: number | undefined;
 };
+/**
+ * ラベル行(見出し / 区切り行)の設定です(`labelRow` prop)。指定したときだけ機能が有効になります。
+ *
+ * 各フィールドの説明は React 版パッケージ `@ishibashi0112/spreadsheet-grid` に同梱の `API_REFERENCE.md`
+ * の「ラベル行(見出し / 区切り行)」節と同じ内容です。
+ */
 export type LabelRowOptions<T, F extends GridFrameworkTypes = GridFrameworkTypes> = {
+    /**
+     * ラベル行の識別。`rows` / 本関数が変わったときに全行を 1 パス評価するため純粋・軽量であること。
+     */
     isLabelRow: (row: T, sourceIndex: number) => boolean;
+    /** 表示文字列。既定描画(`render` 未指定時)/ エクスポート / `aria-label` に使う。 */
     getLabel: (row: T) => string;
+    /**
+     * 中身の React 描画(装飾)。
+     * `ctx = { row, rowKey, rowIndex, sourceRowIndex, label, sectionRowCount }`(`sectionRowCount`
+     * はフィルター後のセクション内データ行数。serverSide では `undefined`)。
+     */
     render?: (ctx: LabelRowRenderContext<T>) => F['node'];
+    /**
+     * ラベル行の高さ(px)。行ごとに変えるときは関数。
+     *
+     * @defaultValue `rowHeight`
+     */
     height?: number | ((row: T) => number);
+    /** 行要素へ追加する class(または `{ className, style }`)。`classNames.labelRow` に加えて付与。 */
     className?: GridSlotProps<F> | ((row: T) => GridSlotProps<F> | undefined);
+    /**
+     * 縦スクロール中、現在セクションのラベル行を列ヘッダー直下に固定する。
+     * 次のラベル行が到達すると押し上げられて交代する(clientSide のみ)。
+     *
+     * @defaultValue `false`
+     */
     sticky?: boolean;
+    /**
+     * ソート / フィルター適用時の扱い(下記)。
+     *
+     * @defaultValue `'section'`
+     */
     sortMode?: LabelRowSortMode;
+    /**
+     * フィルターで中身が 0 件になったセクションのラベル行を残す。
+     *
+     * @defaultValue `false`
+     */
     keepEmptySections?: boolean;
+    /**
+     * エクスポート(`includeLabelRows: true`)時の出力値。文字列は先頭列(他列は空)、
+     * 配列は列順にそのまま。
+     *
+     * @defaultValue `getLabel` を先頭列へ
+     */
     exportText?: (row: T) => string | ReadonlyArray<string | number | null | undefined>;
 };
 export type RowDragContext = {
@@ -418,41 +494,200 @@ export type GridGroupRow = {
     leafCount: number;
     aggregates: Record<string, unknown>;
 };
+/**
+ * 列定義です(`columns` prop の要素)。
+ *
+ * 各フィールドの説明は React 版パッケージ `@ishibashi0112/spreadsheet-grid` に同梱の `API_REFERENCE.md`
+ * の「GridColumn props」表と同じ内容です。
+ * 説明中の「〜節」「下記」は同ファイル内の節を指します。
+ */
 export type GridColumn<T, F extends GridFrameworkTypes = GridFrameworkTypes> = {
+    /** 型推論用の内部マーカーです(実行時には存在しません)。指定しないでください。 */
     readonly __framework?: F;
+    /** 列の一意キー。 */
     key: string;
+    /**
+     * ヘッダーの表示ラベル。**未指定 / 空文字(`''`)のときは `key` を表示**(列メニュー /
+     * フィルターパネル / CSV ヘッダー等の列名表示も同じフォールバック)。
+     * ボタン専用列などで見出しを空にしたい場合は空白 1 文字(`' '`)等を指定する。
+     */
     title?: string;
+    /** 列幅(px)。 */
     width: number;
+    /** リサイズ時の下限幅。flex 配分時の下限クランプにも使用(flex 列で未指定なら内部既定 50px)。 */
     minWidth?: number;
+    /**
+     * 上限幅。**未指定なら上限なし**(autoSize は内容にぴったり合わせ、
+     * 手動リサイズも自由に広げられます。既定の上限は設けません)。指定すると autoSize / 手動リサイズ /
+     * flex 配分の上限クランプに使われます。
+     */
     maxWidth?: number;
+    /**
+     * 折り返し時(= `autoHeight` 列)の CSS `word-break`。`'auto-phrase'` は Chromium(Chrome / Edge)で
+     * BudouX による文節折り返し(Firefox / 一部 Safari 未対応)。**nowrap(非 `autoHeight`)
+     * 列では折り返し自体が起きないため効果なし**。既定(未指定)はブラウザ標準=禁則つき文字折り返し。
+     * 詳細は「日本語テキストの折り返し」節。
+     */
     wordBreak?: 'normal' | 'break-all' | 'keep-all' | 'break-word' | 'auto-phrase';
+    /**
+     * 折り返し時の CSS `line-break`(禁則処理の強さ)。`'strict'` で禁則を厳格化。`wordBreak` 同様、
+     * 折り返す列でのみ効果あり。
+     */
     lineBreak?: 'auto' | 'loose' | 'normal' | 'strict' | 'anywhere';
+    /**
+     * center 列(非 pinned)の伸縮比。余り幅(コンテナ幅 − 行ヘッダー − pinned 合計 − `width`
+     * 固定列の合計)を flex 比で配分し `minWidth`/`maxWidth` でクランプ。
+     * コンテナ追従でリアクティブに伸縮。手動リサイズで固定 px へ変化(`columns` 変化まで固定 → 以後
+     * flex 復帰)。pinned 列では無視。詳細は下記「flex と autoSize」節。
+     */
     flex?: number;
+    /**
+     * この列の手動リサイズ可否。`false` でヘッダーのリサイズハンドルを非表示。
+     * リサイズハンドルの**ダブルクリック**でその列を内容幅へ autoSize(`false`
+     * 時はハンドルが無いため不可。列メニューからの autoSize は引き続き可能)。
+     *
+     * @defaultValue グリッドの `enableColumnResize` を継承
+     */
     resizable?: boolean;
+    /**
+     * `true` で autoSize の対象外(列メニュー / 境界ダブルクリック /
+     * すべての列の自動調整すべてでスキップ)。consumer 指定の `width` を維持(固定幅優先)。
+     * テキストで測れないカスタムUI列や固定で見せたい列向けの per-column opt-in。
+     *
+     * @defaultValue `false`
+     */
     suppressAutoSize?: boolean;
+    /**
+     * autoSize の幅見積もり。指定列は「セル内容の content 幅(px・セルの padding/border を除く)」
+     * をこの関数から得て、**全行の最大 + セル枠**で確定します(テキスト/候補/実 DOM 計測を使わず、
+     * React mount もしません)。テキスト長が実描画幅と相関しない renderCell
+     * カスタムUI列(横並びバッジ等)向けの opt-in。返す値は `renderCell` の実描画幅と一致させること。
+     */
     estimateCellWidth?: (row: T, column: GridColumn<T, F>) => number;
+    /**
+     * この列が auto-height 行の高さを駆動(グリッドの `autoHeight` 有効時のみ)。**autoSize
+     * の対象外**(折り返し前提のため。下記「flex と autoSize」の制約を参照)。
+     */
     autoHeight?: boolean;
+    /** 列の表示/非表示。 */
     visible?: boolean;
+    /** この列の編集を許可。 */
     editable?: boolean;
+    /** この列を読み取り専用にする。 */
     readOnly?: boolean;
+    /**
+     * 列固定の方向。
+     *
+     * @defaultValue undefined = 中央スクロール
+     */
     pinned?: GridColumnPinned;
+    /**
+     * `true` でこの列を行グルーピングの対象にする(複数指定時は `columns` 配列の出現順が階層順)。
+     * 有効時はグループ元列が表示から外れ、先頭に自動グループ列(ツリー表示)が注入される。**clientSide
+     * 限定**(serverSide では無視 + 開発時警告)。詳細は「行グルーピング + 集計」節。
+     */
     rowGroup?: boolean;
+    /**
+     * グルーピング時のこの列の集計。組み込みは値駆動の数値集計(`Number()`
+     * で有限になる値のみ対象・空値除外、`count` は配下 leaf 行数)。
+     * 関数でカスタム集計可(返り値がグループ行に表示)。`rowGroup` 列がないときは無視。
+     */
     aggFunc?: GridAggFuncName | GridAggFunc<T, F>;
+    /**
+     * 値アクセサ。
+     *
+     * @defaultValue `row[key]`
+     */
     getValue?: (row: T) => unknown;
+    /** 値ライター(新しい行を返す)。 */
     setValue?: (row: T, value: unknown) => T;
+    /**
+     * カスタムセル描画。
+     *
+     * @defaultValue プレーン `<span>`
+     */
     renderCell?: (ctx: CellRenderContext<T, F>) => F['node'];
+    /**
+     * セルへ付与する追加 class(条件付きスタイル)。`GridSlotProps` = `string | { className?, style? }`
+     * で、StyleX の `stylex.props(...)` をそのまま返せる(`style` はセルへインライン付与。座標 /
+     * 寸法はグリッドが後勝ち)。関数版は値 / 状態に応じて返せる。`ctx` には view の `rowIndex` に加え
+     * source 基準の `sourceRowIndex` / `rowKey` が入る(ソート / フィルター ON でも source
+     * 行基準のデータと突き合わせ可能。「補助型」節参照)。基底 `.ssg-body-cell` は未レイヤー・特異度
+     * (0,1,0)。確実な上書きは `.ssg-body-cell.my-class` の連結を推奨。
+     */
     cellClassName?: GridSlotProps<F> | ((ctx: CellStyleContext<T, F>) => GridSlotProps<F> | undefined);
+    /**
+     * セル内容の水平寄せ(UI 表示のみ・元の値は不変)。セル表示と編集 input に反映。
+     *
+     * @defaultValue `'left'`
+     */
     align?: 'left' | 'center' | 'right';
+    /**
+     * セル表示値の整形(UI 表示のみ)。`renderCell` 未指定の既定セルが返り値を表示。組み込み
+     * `numberFormatter` 等を渡せる。元の値/編集/コピー/ソート/フィルターには影響しない。
+     */
     valueFormatter?: CellValueFormatter<T, F>;
+    /** カスタムヘッダー描画。 */
     renderHeader?: (ctx: HeaderRenderContext<T, F>) => F['node'];
+    /**
+     * フィルター UI の種別。`'auto'` は列の値から `numberSet` / `textSet` / `dateSet` を自動判定する
+     * opt-in(下記「filterType: 'auto'(自動判定)」節)。`'numberSet'` / `'textSet'` / `'dateSet'`
+     * は条件(演算子 + 値)と Set 一覧を 1 つの popover に縦に並べて **AND
+     * 結合**する複合フィルター(条件を適用すると Set 候補が連動して絞られる。
+     * 候補外になった値の選択は破棄せず保持)。numberSet の演算子は 以上 / より大きい / 以下 / 未満 /
+     * に等しい / に等しくない / 範囲 / 空白 / 空白でない、textSet は を含む / に等しい / で始まる /
+     * で終わる / 空白 / 空白でない(判定は大文字小文字無視)。dateSet は 範囲 / 以降 / 以前 / に等しい
+     * / に等しくない / 空白 / 空白でない + 相対プリセット(今日 / 今月 / 過去 30
+     * 日。**相対のまま保存され評価のたびに解決**)で、Set 部分は年 / 月 / 日の 3 階層ツリー(親は 3
+     * 状態チェック)になる。
+     */
     filterType?: ColumnFilterTypeOption;
+    /**
+     * select / set / numberSet / textSet / dateSet の候補(readonly / `as const` 配列も可)。
+     *
+     * @defaultValue rows から自動収集
+     */
     filterOptions?: readonly GridSelectFilterOption[];
+    /**
+     * dateSet の相対プリセットチップの構成。`false` / `[]` でチップ行を非表示(オプトアウト)。
+     * 配列はビルトイン ID(`'today'` / `'thisMonth'` / `'last30days'`)の再利用とカスタム定義
+     * `{ id, label, resolve }` を表示順のまま混在可。詳細は下記「dateSet
+     * の相対プリセット(dateFilterPresets)」節。
+     *
+     * @defaultValue ビルトイン 3 種
+     */
     dateFilterPresets?: false | readonly DateFilterPresetOption[];
+    /** カスタムフィルター述語。 */
     filterFn?: (row: T, filterValue: unknown) => boolean;
+    /**
+     * セルエディタ種別(判別共用体)。
+     * `{ type: 'text' | 'number' | 'select' | 'date' | 'checkbox' | 'custom', ... }`。
+     * 詳細は「セルエディタ」節。
+     *
+     * @defaultValue text 相当
+     */
     editor?: GridColumnEditor<T, F>;
+    /**
+     * セル値の検証。`true`=有効 / `false`=無効(既定メッセージ)/
+     * `string`・`{ message }`=無効+メッセージ。**純粋・軽量であること**(描画中の可視セルごとに毎レンダー評価。
+     * `cellClassName` 関数と同コスト階級)。詳細は「バリデーション」節。
+     */
     validate?: (ctx: CellValidationContext<T, F>) => CellValidationResult;
+    /**
+     * 検証 NG 時の動作。`'mark'`=値は入るがセルに invalid 表示 / `'reject'`=書き込み自体を拒否。
+     *
+     * @defaultValue `'mark'`
+     */
     validationMode?: GridValidationMode;
+    /**
+     * 「文字列 → セル値」のパーサ(貼り付け / クリア / エディタ commit
+     * で共通)。**明示指定が常に優先**。未指定で `editor` が number / date / checkbox
+     * のときは種別の既定パーサが自動供給されます(「セルエディタ」節の表参照)。
+     *
+     * @defaultValue editor 既定パーサ
+     */
     parseClipboardValue?: (raw: string, row: T) => unknown;
+    /** コピー時のフォーマッタ。 */
     formatClipboardValue?: (value: unknown, row: T) => string;
 };
 export type ColumnResizeDragState = {
@@ -541,12 +776,37 @@ export type GridContextMenuTarget<T, F extends GridFrameworkTypes = GridFramewor
     rowKey: GridRowKey;
     row: T;
 };
+/**
+ * `getContextMenuItems` / `onContextMenuOpen` へ渡る右クリックの文脈です。
+ *
+ * 各フィールドの説明は React 版パッケージ `@ishibashi0112/spreadsheet-grid` に同梱の `API_REFERENCE.md`
+ * の「コンテキストメニュー」節と同じ内容です。
+ */
 export type GridContextMenuParams<T, F extends GridFrameworkTypes = GridFrameworkTypes> = {
+    /**
+     * 右クリック対象。`{ type:'cell', rowIndex, colIndex, rowKey, row, column, value }` か
+     * `{ type:'rowHeader', rowIndex, rowKey, row }`(行NO ガター)。`rowIndex` はビュー行 index、
+     * `colIndex` は論理列 index(視覚順 左→中央→右 = `handle.selectCell` と同一空間)。
+     */
     target: GridContextMenuTarget<T, F>;
+    /**
+     * `clientX` / `clientY`: 右クリックのビューポート座標(メニュー配置に使用済み。
+     * 分岐の判断材料にも)。
+     */
     clientX: number;
+    /**
+     * `clientX` / `clientY`: 右クリックのビューポート座標(メニュー配置に使用済み。
+     * 分岐の判断材料にも)。
+     */
     clientY: number;
+    /** 現在のセル範囲選択。チェックボックス行選択は `handle.getRowSelection()` で別途取得。 */
     selection: GridSelection;
+    /** 現在のアクティブセル。 */
     activeCell: CellCoord | null;
+    /**
+     * 対象(cell はそのセル / rowHeader はその行)が `selection` に含まれるか。「選択範囲への操作」
+     * か「単一対象への操作」かを分岐する簡便値。
+     */
     isTargetSelected: boolean;
 };
 export type GridContextMenuActionItem<F extends GridFrameworkTypes = GridFrameworkTypes> = {
@@ -584,34 +844,110 @@ export type GridResolvedSlot<F extends GridFrameworkTypes = GridFrameworkTypes>
     style?: F['style'];
 };
 export type GridResolvedSlots<F extends GridFrameworkTypes = GridFrameworkTypes> = Partial<Record<keyof GridClassNames<F>, GridResolvedSlot<F>>>;
+/**
+ * パーツ別スロット(`classNames` prop)です。各値は class 文字列か `{ className, style }` です。
+ *
+ * 各スロットの付与先は React 版パッケージ `@ishibashi0112/spreadsheet-grid` に同梱の `API_REFERENCE.md`
+ * の「パーツ別スロット」節と同じ内容です。
+ */
 export type GridClassNames<F extends GridFrameworkTypes = GridFrameworkTypes> = {
+    /** 付与先: ルート要素 `.ssg-root`(`className` / `style` prop と同じ要素) */
     root?: GridSlotProps<F>;
+    /**
+     * `toolbar` / `statusBar`: 付与先: 既定トップバー `.ssg-bar--top` / 既定ボトムバー
+     * `.ssg-bar--bottom`(`renderTopBar` / `renderBottomBar` 指定時は対象外)
+     */
     toolbar?: GridSlotProps<F>;
+    /**
+     * `toolbar` / `statusBar`: 付与先: 既定トップバー `.ssg-bar--top` / 既定ボトムバー
+     * `.ssg-bar--bottom`(`renderTopBar` / `renderBottomBar` 指定時は対象外)
+     */
     statusBar?: GridSlotProps<F>;
+    /**
+     * `headerRow` / `headerCell`: 付与先: ヘッダー行 /
+     * 列ヘッダーセル(コーナー・行ヘッダーセルは含まない)
+     */
     headerRow?: GridSlotProps<F>;
+    /**
+     * `headerRow` / `headerCell`: 付与先: ヘッダー行 /
+     * 列ヘッダーセル(コーナー・行ヘッダーセルは含まない)
+     */
     headerCell?: GridSlotProps<F>;
+    /** `bodyRow` / `bodyCell`: 付与先: 本体行(データ / スケルトン / グループ行)/ データセル */
     bodyRow?: GridSlotProps<F>;
+    /** `bodyRow` / `bodyCell`: 付与先: 本体行(データ / スケルトン / グループ行)/ データセル */
     bodyCell?: GridSlotProps<F>;
+    /**
+     * `rowHeaderCell` / `cornerCell`: 付与先: 行ヘッダー「#」セルとコーナーセル(`rowHeaderCell`
+     * は両方、`cornerCell` はコーナーのみ)
+     */
     rowHeaderCell?: GridSlotProps<F>;
+    /** 付与先: ヘッダーのアイコンボタン `.ssg-icon-btn` */
     iconButton?: GridSlotProps<F>;
+    /**
+     * `rowHeaderCell` / `cornerCell`: 付与先: 行ヘッダー「#」セルとコーナーセル(`rowHeaderCell`
+     * は両方、`cornerCell` はコーナーのみ)
+     */
     cornerCell?: GridSlotProps<F>;
+    /**
+     * `groupRow` / `groupCell`: 付与先: グループ行 / グループ行のセル(`bodyRow` / `bodyCell`
+     * に加えて付与)
+     */
     groupRow?: GridSlotProps<F>;
+    /**
+     * `groupRow` / `groupCell`: 付与先: グループ行 / グループ行のセル(`bodyRow` / `bodyCell`
+     * に加えて付与)
+     */
     groupCell?: GridSlotProps<F>;
+    /**
+     * `detailBand` / `detailCard`: 付与先: 展開行の帯 / カード(`detailRow.className` に加えて付与)
+     */
     detailBand?: GridSlotProps<F>;
+    /**
+     * `detailBand` / `detailCard`: 付与先: 展開行の帯 / カード(`detailRow.className` に加えて付与)
+     */
     detailCard?: GridSlotProps<F>;
+    /**
+     * `labelRow` / `labelRowContent`: 付与先: ラベル行(見出し / 区切り行)の行要素
+     * `.ssg-body-row[data-ssg-label-row]`(`bodyRow` / `labelRow.className` に加えて付与。
+     * 縦固定の複製にも付く)/ 中身の器 `.ssg-label-row-content`
+     */
     labelRow?: GridSlotProps<F>;
+    /**
+     * `labelRow` / `labelRowContent`: 付与先: ラベル行(見出し / 区切り行)の行要素
+     * `.ssg-body-row[data-ssg-label-row]`(`bodyRow` / `labelRow.className` に加えて付与。
+     * 縦固定の複製にも付く)/ 中身の器 `.ssg-label-row-content`
+     */
     labelRowContent?: GridSlotProps<F>;
+    /**
+     * 付与先: ポータル系パネルの root(列メニュー / フィルター / コンテキストメニュー / select
+     * エディタ候補 / ツールパネル。`document.body` 直下)
+     */
     popover?: GridSlotProps<F>;
+    /** 付与先: メニュー項目 `.ssg-menu-item`(列メニュー / コンテキストメニュー) */
     menuItem?: GridSlotProps<F>;
+    /**
+     * 付与先: カスタムツールチップ `.ssg-tooltip`(body 直下のシングルトン。
+     * 複数グリッド同居時は最後に更新したグリッドの値)
+     */
     tooltip?: GridSlotProps<F>;
+    /** 付与先: 列 / 行ドラッグのゴースト `[data-grid-drag-ghost]` */
     dragGhost?: GridSlotProps<F>;
+    /** 付与先: 行選択 / checkbox 列のチェックボックス glyph `.ssg-row-checkbox` */
     checkbox?: GridSlotProps<F>;
+    /** 付与先: セルエディタの枠 `.ssg-cell-editor` */
     cellEditor?: GridSlotProps<F>;
+    /** 付与先: 0 行時の空状態 `.ssg-empty-state` */
     emptyState?: GridSlotProps<F>;
+    /** 付与先: フィルターチップバー `.ssg-filter-chip-bar` */
     filterChipBar?: GridSlotProps<F>;
+    /** 付与先: SSRM のエラーバー `.ssg-ssrm-error-bar` */
     errorBar?: GridSlotProps<F>;
+    /** 付与先: スクロール位置インジケーター `.ssg-scroll-hint` */
     scrollHint?: GridSlotProps<F>;
+    /** `activeCellOverlay` / `selectionOverlay`: 付与先: アクティブセル枠 / 範囲選択の塗り */
     activeCellOverlay?: GridSlotProps<F>;
+    /** `activeCellOverlay` / `selectionOverlay`: 付与先: アクティブセル枠 / 範囲選択の塗り */
     selectionOverlay?: GridSlotProps<F>;
 };
 export type ScrollAlign = 'auto' | 'start' | 'center' | 'end';
@@ -674,68 +1010,192 @@ export type GridState = {
     sort: GridSortState;
     columns?: GridColumnState[];
 };
+/**
+ * 命令的 API です(`ref` prop で受け取るハンドル)。状態は props で controlled のまま、props で表現しづらい
+ * 一発操作(スクロール / 選択 / エクスポート / 状態の保存・復元など)だけを提供します。
+ * `viewRowIndex` / `colIndex` はビュー座標(フィルター / ソート適用後の表示 index。`colIndex` は固定列を含む
+ * 左→中央→右の視覚順)です。
+ *
+ * 各メソッドの説明は React 版パッケージ `@ishibashi0112/spreadsheet-grid` に同梱の `API_REFERENCE.md`
+ * の「命令的 API」節の表と同じ内容です。
+ */
 export type SpreadsheetGridHandle<T> = {
+    /**
+     * 指定行を可視域へ。`align`(既定 `'auto'`): `'auto'`(最小スクロール) / `'start'` / `'center'` /
+     * `'end'`。
+     */
     scrollToRow: (viewRowIndex: number, options?: {
         align?: ScrollAlign;
     }) => void;
+    /** 指定セルを縦横とも可視域へ。固定列(左右ピン)は常に可視のため横スクロールしない。 */
     scrollToCell: (viewRowIndex: number, colIndex: number, options?: {
         align?: ScrollAlign;
     }) => void;
+    /** `scrollToTop()` / `scrollToBottom()`: 先頭 / 末尾へ。 */
     scrollToTop: () => void;
+    /** `scrollToTop()` / `scrollToBottom()`: 先頭 / 末尾へ。 */
     scrollToBottom: () => void;
+    /** 現在描画中の行ウィンドウ `{ startIndex, endIndex }`(end 排他)。空は `null`。 */
     getVisibleRowRange: () => {
         startIndex: number;
         endIndex: number;
     } | null;
+    /**
+     * 現在のスクロール位置 `{ top, left }`(px)。値はスクロールコンテナの生の `scrollTop` /
+     * `scrollLeft` で、`setScrollPosition` / `onScroll` と同一基準(往復で一貫)。未マウント時は
+     * `null`。
+     */
     getScrollPosition: () => GridScrollPosition | null;
+    /**
+     * スクロール位置の設定(px)。省略側は現状維持・スクロール可能範囲へクランプ。`behavior` は
+     * `'auto'`(既定・即時)/ `'smooth'`。2 グリッドの双方向同期では `'auto'` を推奨(`'smooth'`
+     * は途中フレームの `onScroll` が `source:'user'` になり得る)。
+     */
     setScrollPosition: (position: {
         top?: number;
         left?: number;
     }, options?: {
         behavior?: 'auto' | 'smooth';
     }) => void;
+    /** 現在のアクティブセル `{ row, col }`(なければ `null`)。 */
     getActiveCell: () => CellCoord | null;
+    /** アクティブセル設定(`null` で解除)。`scrollIntoView` で可視化も行う。 */
     setActiveCell: (cell: CellCoord | null, options?: {
         scrollIntoView?: boolean;
     }) => void;
+    /** 現在の選択状態(`GridSelection`)。 */
     getSelection: () => GridSelection;
+    /** 単一セル選択(クリック相当)。 */
     selectCell: (viewRowIndex: number, colIndex: number, options?: {
         scrollIntoView?: boolean;
     }) => void;
+    /** セル範囲選択(ドラッグ相当)。アンカーは `range.start`。 */
     selectRange: (range: CellRange, options?: {
         scrollIntoView?: boolean;
     }) => void;
+    /** 選択解除。 */
     clearSelection: () => void;
+    /** 選択に交差する行(distinct)を返す。serverSide はロード済み行のみ。 */
     getSelectedRows: () => T[];
+    /** CSV 文字列を返す(純粋・副作用なし)。 */
     exportCsv: (options?: CsvExportOptions) => string;
+    /**
+     * `exportCsv` の結果を `.csv` としてダウンロード(`filename` 既定 `'export.csv'`、`bom` 既定
+     * `true`)。
+     */
     downloadCsv: (filename?: string, options?: CsvExportOptions) => void;
+    /** 列メタ + 2 次元セルの、シリアライズ非依存な整形済みデータを返す(純粋・副作用なし)。 */
     getExportData: (options?: GridExportOptions) => GridExportData;
+    /**
+     * 永続化対象(手動リサイズ幅 / フィルター / ソート)のスナップショット `GridState`
+     * を返す(純粋・副作用なし)。新規オブジェクトなのでそのまま `JSON.stringify` して保存できる。
+     */
     getState: () => GridState;
+    /**
+     * `getState()` の値(または互換な部分形)を適用する。外部入力は内部で防御的に正規化され、幅 reset /
+     * フィルター一括 / ソート set の 3 dispatch(1 イベント = 1 再レンダー)で反映。clientSide /
+     * serverSide 双方に効く(SSRM は `filters`/`sort` 変化がクエリへ載り再取得)。
+     */
     applyState: (state: GridState) => void;
+    /** 現在の行選択記述子(`RowSelectionModel`)。 */
     getRowSelection: () => RowSelectionModel;
+    /**
+     * 行選択記述子を設定。controlled 時は `onRowSelectionChange` 経由で親へ委譲(内部 state
+     * は書かない)。
+     */
     setRowSelection: (model: RowSelectionModel) => void;
+    /**
+     * 選択中の行キー配列。`include` はそのまま O(選択数)、`exclude`
+     * は現在の全行から除外を差し引いて列挙(O(行数))。serverSide はロード済みキーのみ。
+     */
     getSelectedRowKeys: () => GridRowKey[];
+    /**
+     * 選択中の行データ。行の探索が要るため O(行数)。キーで足りるなら `getSelectedRowKeys()` を推奨。
+     * serverSide はロード済み行のみ。
+     */
     getSelectedRowData: () => T[];
+    /** 選択件数。`exclude` は 総行数 − 除外数 で一定コスト。 */
     getSelectedRowCount: () => number;
+    /** 指定キーが選択中かを O(1) 判定。 */
     isRowSelected: (rowKey: GridRowKey) => boolean;
+    /** 全行を選択(exclude モード=キーを列挙しない)。 */
     selectAllRows: () => void;
+    /** 行選択をすべて解除。 */
     clearRowSelection: () => void;
+    /** 直近のグリッド編集を取り消す(`Ctrl/Cmd+Z` 相当)。無効条件下・履歴が空のときは no-op。 */
     undo: () => void;
+    /**
+     * undo で取り消した編集をやり直す(`Ctrl/Cmd+Shift+Z` / `Ctrl/Cmd+Y` 相当)。undo
+     * 後に新しい編集が入った時点で redo 系譜は破棄される。
+     */
     redo: () => void;
+    /** `canUndo()` / `canRedo()`: undo / redo 可能かを返す(無効条件下では常に `false`)。 */
     canUndo: () => boolean;
+    /** `canUndo()` / `canRedo()`: undo / redo 可能かを返す(無効条件下では常に `false`)。 */
     canRedo: () => boolean;
+    /**
+     * 編集履歴を破棄する(rows は変更しない)。rows
+     * の外部差し替えはグリッド側でも自動検知して破棄するため、通常は呼ばなくてよい。
+     */
     clearUndoHistory: () => void;
+    /**
+     * 指定グループを開閉する(`collapsed: true` = 折りたたみ)。`groupKey` は `getGroupRows()`
+     * の記述子から取得。同一イベント内の連続呼び出しも正しく積み重なる。
+     */
     setGroupCollapsed: (groupKey: string, collapsed: boolean) => void;
+    /** `expandAllGroups()` / `collapseAllGroups()`: すべてのグループを展開 / 折りたたむ。 */
     expandAllGroups: () => void;
+    /** `expandAllGroups()` / `collapseAllGroups()`: すべてのグループを展開 / 折りたたむ。 */
     collapseAllGroups: () => void;
+    /** 全グループ行の記述子(`GridGroupRow[]`)を DFS 順(表示順)で返す。開閉状態に関わらず全件。 */
     getGroupRows: () => GridGroupRow[];
+    /**
+     * 指定行キー(`rowKeyGetter` の値)の展開行を開閉する。`isExpandable` が `false` の行は no-op。
+     * 行がまだロードされていない / フィルターで除外中でもキーは保持され、
+     * 表示可能になった時点で帯が出る。同一イベント内の連続呼び出しも正しく積み重なる。
+     */
     setDetailRowExpanded: (rowKey: GridRowKey, expanded: boolean) => void;
+    /** 展開中の行キーを返す(`GridRowKey[]`)。 */
     getExpandedDetailRowKeys: () => GridRowKey[];
+    /**
+     * すべての展開行を閉じる。「すべて開く」
+     * は提供しない(表示中の全行をまとめて開くと帯の合計高が大きくなりやすいため。必要なら
+     * `setDetailRowExpanded` を行ごとに呼ぶ)。
+     */
     collapseAllDetailRows: () => void;
+    /**
+     * 指定行キーの行を元 `rows` 配列の `toIndex` へ移動する(clientSide + `onRowsChange` 指定時のみ。
+     * `enableRowDrag` / ソート / フィルターの状態には依存しない)。`onRowsChange`(履歴ラッパ経由 =
+     * undo 対象)→ `onRowMove` の順に呼ばれる。未知のキー / 同一位置 / 範囲外は no-op。serverSide
+     * では開発時警告 + no-op。
+     */
     moveRow: (rowKey: GridRowKey, toIndex: number) => void;
+    /**
+     * `validate` 指定列 × 全ソース行をオンデマンドで全走査し、invalid セルの一覧(`GridInvalidCell[]`
+     * = `{ rowKey, sourceRowIndex, columnKey, message }`)を返す。保存前チェック用。invalid
+     * 表示は表示時導出のため状態を持たず、**呼ばれた時だけ計算**する(明示的な呼び出し =
+     * 明示的なコスト)。**`showValidationMarks`
+     * の表示状態と無関係に常に動作する**(マーク非表示中の送信前チェックに使える)。
+     * 非表示列も対象(見えない列の不正値も検出)。clientSide 専用で、serverSide
+     * は全行を保持しないため空配列 + `console.warn`。
+     */
     getInvalidCells: () => GridInvalidCell[];
+    /**
+     * serverSide(`dataSource`)のソフトリフレッシュ。クエリ(フィルター/ソート/グローバル)
+     * を変えずにキャッシュを破棄し、**スクロール位置を保ったまま現在の可視レンジを即時**(debounce
+     * なし)取り直す。件数は到着ブロックの `totalRowCount` で追従。宣言的に扱いたい場合は同挙動の
+     * `serverSideRefreshToken` prop もある(「serverSide モード」の節を参照)。clientSide(`rows`)
+     * では警告付き no-op。
+     */
     refreshServerSide: () => void;
+    /**
+     * フィルター管理パネル(適用中の列フィルターの一覧 / 該当列へジャンプして編集 / 個別・全クリア /
+     * 追加)を開く。`enableColumnFilter=false` のときは何もしない。列メニューの「フィルターを管理…」/
+     * 既定トップバーの **Filters chip クリック**(`enableColumnFilter=true` 時にクリック可能)
+     * と同じパネル。
+     */
     openFilterManager: () => void;
+    /** フィルター管理パネルを閉じる(開いていなければ何もしない)。 */
     closeFilterManager: () => void;
 };
 export type GridDensity = 'compact' | 'standard' | 'comfortable';
@@ -746,102 +1206,650 @@ export type ScrollHintRenderArgs<T> = {
     rowIndex: number;
     rowData: T | undefined;
 };
+/**
+ * スクロール位置インジケーターの設定です(`scrollHint` prop。`true` は全項目既定値と同義)。
+ *
+ * 各フィールドの説明は React 版パッケージ `@ishibashi0112/spreadsheet-grid` に同梱の `API_REFERENCE.md`
+ * の「スクロール位置インジケーター」節と同じ内容です。
+ */
 export type ScrollHintOptions<T = unknown, F extends GridFrameworkTypes = GridFrameworkTypes> = {
+    /**
+     * 行番号バブルの表示。
+     *
+     * @defaultValue `true`
+     */
     bubble?: boolean;
+    /**
+     * ルーラー + ジャンプ先プレビューの表示。
+     *
+     * @defaultValue `true`
+     */
     ruler?: boolean;
+    /**
+     * カスタム縦スクロールバー(専用ガター・常時表示)。`false`
+     * でネイティブバーのまま(バブル等は疑似サム位置に表示)。
+     *
+     * @defaultValue `true`
+     */
     scrollbar?: boolean;
+    /**
+     * バブル / ルーラーの表示トリガー(スクロールバー自体は常時表示)。`'scroll'` =
+     * スクロール中のみ(停止約 1 秒でフェードアウト)/ `'hover'` = グリッドホバー中 + スクロール中 /
+     * `'always'` = 常時。
+     *
+     * @defaultValue `'scroll'`
+     */
     trigger?: ScrollHintTrigger;
+    /**
+     * **データ量ゲート**。表示行数(フィルター / グルーピング適用後のビュー行数。SSRM
+     * はサーバー総行数)がこの値未満のあいだ、scrollHint 全体(カスタムスクロールバー含む)を自動 OFF
+     * にしてネイティブスクロールバー表示のままにする。`0` = 常時有効(従来挙動)。
+     *
+     * @defaultValue `0`
+     */
     minRows?: number;
+    /** 行番号に添えて表示する列 key(= 行オブジェクトのフィールド名)。 */
     hintColumn?: string;
+    /**
+     * 表示内容の完全カスタム(`hintColumn` より優先)。`null` / `undefined`
+     * を返すと行番号のみの既定表示。
+     */
     renderHint?: (args: ScrollHintRenderArgs<T>) => F['node'];
 };
+/**
+ * `SpreadsheetGrid` の props です(React 版では `ref` prop が加わります)。
+ *
+ * 各フィールドの説明は React 版パッケージ `@ishibashi0112/spreadsheet-grid` に同梱の `API_REFERENCE.md`
+ * の「SpreadsheetGrid props」表と同じ内容です。
+ * 説明中の「〜節」「下記」は同ファイル内の節を指します。
+ */
 export type SpreadsheetGridProps<T, F extends GridFrameworkTypes = GridFrameworkTypes> = {
+    /**
+     * 永続スライス(手動リサイズ幅 / フィルター / ソート)が**実際に変化したとき**に最新 `GridState`
+     * を渡して呼ばれる。保存タイミングの signal(例: localStorage 自動保存)。発火規約は「状態の保存 /
+     * 復元」節を参照。
+     */
     onStateChange?: (state: GridState) => void;
+    /**
+     * フィルター状態(`globalText` + `columnFilters`)が**実際に変化したとき**だけ、
+     * そのスライスの複製を渡して呼ばれる。`onStateChange` は列幅 / 列メタでも呼ばれるため、記述子から
+     * WHERE を組み立てるなどフィルターだけを追いたい用途向け。規約は `onStateChange`
+     * と同じ(初回非発火 / 同値非発火 / `applyState` でも発火)。
+     */
     onFiltersChange?: (filters: GridFilterState) => void;
+    /**
+     * ソート状態が**実際に変化したとき**だけ、その複製を渡して呼ばれる(ORDER BY の組み立てなど)。
+     * 規約は `onFiltersChange` と同じ。
+     */
     onSortChange?: (sort: GridSortState) => void;
+    /**
+     * スクロール位置の変化通知(rAF で 1 フレーム 1 回に間引き・縦横どちらの変化でも発火)。`params` は
+     * `{ top, left, source }`(px)。`source: 'api'` は `setScrollPosition` / `scrollTo*` 系由来、
+     * `'user'` はそれ以外。2 グリッドの双方向スクロール同期は `source === 'user'`
+     * のときだけ相手へ反映することでループを止められる。インライン関数可(latest-ref 経由)。
+     */
     onScroll?: (params: GridScrollEventParams) => void;
+    /**
+     * clientSide モードの行データ。readonly 配列も受け付ける(グリッドは入力配列を破壊的に変更しない。
+     * 編集結果は `onRowsChange` が新配列で返す)。`dataSource` を指定した場合は無視され serverSide
+     * モードになる(両者は排他)。
+     */
     rows?: readonly T[];
+    /**
+     * serverSide(SSRM)モードのデータ供給口。指定すると可視窓近傍のブロックだけを `getRows`
+     * で都度取得し、`rows` 系の clientSide パイプラインをバイパスする。`updateRows`(任意)
+     * を持たせるとセル編集の書き戻し(楽観更新つき)が有効になる(「セル編集の書き戻し」節)。
+     */
     dataSource?: ServerSideDataSource<T>;
+    /**
+     * serverSide のソフトリフレッシュ用トークン。値を増やすと、クエリ(フィルター/ソート/グローバル)
+     * を変えずにキャッシュを破棄して現在の可視レンジをサーバから取り直す。スクロール位置は保持し、
+     * 件数は到着ブロックの `totalRowCount` で追従する(clientSide では無視)。
+     * 命令的に呼びたい場合は同挙動のハンドル `refreshServerSide()` を使う。
+     */
     serverSideRefreshToken?: number;
+    /**
+     * serverSide の `getRows` が reject したときの通知(abort は正常キャンセルのため通知しない)。
+     * `params` は失敗した要求の view 空間レンジ `{ startIndex, endIndex }`。
+     * グリッド内蔵のエラーバー(再試行 UI)とは独立に呼ばれる(利用側トースト / ログ用)。
+     * インライン関数可(latest-ref 経由で読む)。
+     */
     onServerSideLoadError?: (error: unknown, params: ServerSideLoadErrorParams) => void;
+    /**
+     * serverSide の `dataSource.updateRows` が reject したときの通知。
+     * グリッド側は楽観更新をロールバック済みで、`params.updates` に失敗した行更新(`rowKey` /
+     * `changes` / `previousRow`)が入る(利用側トースト / リトライ導線用)。
+     * グリッド内蔵の保存失敗バーとは独立に呼ばれる。インライン関数可(latest-ref 経由で読む)。
+     * 詳細は「セル編集の書き戻し」節。
+     */
     onServerSideWriteError?: (error: unknown, params: ServerSideWriteErrorParams<T>) => void;
+    /** 列定義の配列。readonly 配列も受け付ける。 */
     columns: readonly GridColumn<T, F>[];
+    /** 行が変化したとき呼ばれる(rows を controlled にする)。 */
     onRowsChange?: (nextRows: T[]) => void;
+    /** 列が変化したとき呼ばれる。列メニューの固定切替はこれが指定されている場合のみ反映。 */
     onColumnsChange?: (nextColumns: GridColumn<T, F>[]) => void;
+    /**
+     * 安定した行キーを返す。
+     *
+     * @defaultValue index ベース
+     */
     rowKeyGetter?: (row: T, index: number) => GridRowKey;
+    /**
+     * コピー(`Ctrl/Cmd+C` の TSV)/ `exportCsv` / `getExportData` の対象行フィルタ。`false`
+     * の行は出力から**行ごと**除く(行単位のみ。全体選択かの判定と貼り付けには影響しない)。
+     * `ctx.viewRowIndex` はフィルター / ソート適用後のビュー行 index(scope `'raw'` のみ rows
+     * 配列のソース index)、`ctx.rowKey` は `rowKeyGetter` の値。用途:
+     * プレースホルダ行など表示上の詰め物を出力から除く。
+     *
+     * @defaultValue 全行 true
+     */
     isRowExportable?: (row: T, ctx: {
         viewRowIndex: number;
         rowKey: GridRowKey;
     }) => boolean;
+    /** 行追加時に使う新規行ファクトリ。 */
     createRow?: () => T;
+    /** 列追加時に使う列ファクトリ。 */
     createOverflowColumn?: (columnIndex: number) => GridColumn<T, F>;
+    /**
+     * uniform 行の行高(px)。未指定時は density プリセット(compact: `28` / comfortable: `44`)
+     * から解決。明示指定が常に優先。
+     *
+     * @defaultValue density 依存(standard: `36`)
+     */
     rowHeight?: number;
+    /**
+     * auto-height 行(可変行高)を有効化する**大本のスイッチ**。これに加えて**少なくとも1列に
+     * `column.autoHeight: true`** が必要(その列が折り返して行高を駆動)。両方 true かつ**行数 ≤ 50,
+     * 000**のとき有効(超過時は uniform `rowHeight` へフォールバック)。詳細は「auto-height 行」節。
+     *
+     * @defaultValue `false`
+     */
     autoHeight?: boolean;
+    /**
+     * 未測定行の推定行高(px)。
+     *
+     * @defaultValue `rowHeight`
+     */
     estimateRowHeight?: number;
+    /**
+     * ヘッダー行の高さ(px)。未指定時は density プリセット(compact: `32` / comfortable: `48`)
+     * から解決。明示指定が常に優先。
+     *
+     * @defaultValue density 依存(standard: `40`)
+     */
     headerHeight?: number;
+    /**
+     * 密度プリセット。rowHeight / headerHeight の既定値と寸法トークン(セル横 padding / バー padding /
+     * アイコンボタン寸法 / セル文字の相対拡縮)を一括切替。`'standard'` は従来と同値。
+     * 個別調整はトークン(`--ssg-cell-pad-x` 等)の上書きで可能。popover / menu 等のポータルは対象外。
+     *
+     * @defaultValue `'standard'`
+     */
     density?: GridDensity;
+    /**
+     * カラーテーマ。`'dark'` でダークプリセット(`.ssg-theme-dark` のトークン一括上書き。Mantine dark
+     * 系パレット)をグリッド本体・全ポータル(popover / menu / panel)
+     * ・ドラッグゴースト・ツールチップへ適用。`'auto'` は `prefers-color-scheme` へ追従(Mantine /
+     * HeroUI 等クラスベース dark 運用では、利用側カラースキームの解決値を `'light' | 'dark'`
+     * で渡す使い方を推奨)。個別の色調整はトークン(`--ssg-*`)の上書きで可能。
+     *
+     * @defaultValue `'light'`
+     */
     theme?: GridTheme;
+    /**
+     * 行番号列の幅(px)。
+     *
+     * @defaultValue `56`
+     */
     rowHeaderWidth?: number;
+    /**
+     * グリッドの明示高さ。**値の種類で何の高さかが変わる**。① `%` を含む文字列(`'100%'` / `'50%'` /
+     * `'calc(100% - 40px)'`):
+     * トップバー・フィルターチップバー・ボトムバーを含む**グリッド全体**の高さ。`'100%'`
+     * でグリッドが親要素に収まり、バーを除いた残りがスクロール領域になる(ルートに
+     * `ssg-root--fill-height` が付く)。親要素が確定高さを持つ前提で、親が高さ `auto`
+     * だと全行分まで伸びて仮想化が効かない。② `number`(px)/ `%` を含まない文字列(`'400px'` / `'50vh'`
+     * / `'calc(100vh - 120px)'`): **スクロール領域だけ**の高さ(グリッド全体はバーの分だけ高くなる)。③
+     * 未指定: スクロール領域は内容の高さで `maxHeight` によりクリップ。ルートへの
+     * `style={{ height }}` だけではスクロール領域は決まらないため、高さはこの prop で指定する。
+     */
     height?: number | string;
+    /**
+     * **スクロール領域**の高さ上限(バーは含まない。`height` の種類に関わらず同じ)。
+     * `height`・`maxHeight` が**共に未指定のときのみ**既定の 480px が効く（従来挙動）。数値の
+     * `height` と併用するとスクロール領域 = `min(height, maxHeight)`、`%` の `height` と併用すると
+     * `min(maxHeight, 親の高さ − バー)`(親が大きければグリッド全体はバー + `maxHeight` に縮む)。
+     *
+     * @defaultValue `—`（既定 480px）
+     */
     maxHeight?: number | string;
+    /**
+     * グリッド全体の編集を無効化。
+     *
+     * @defaultValue `false`
+     */
     readOnly?: boolean;
+    /**
+     * readonly セルの組み込み淡色表示(背景 + 文字色)を有効化。`false` でもセマンティッククラス
+     * `.ssg-body-cell--readonly` は常時付与され、利用側 CSS のフックに使える。
+     *
+     * @defaultValue `false`
+     */
     dimReadOnlyCells?: boolean;
+    /** セル単位の編集可否ゲート。 */
     canEditCell?: (rowIndex: number, colIndex: number, row: T, column: GridColumn<T, F>) => boolean;
+    /**
+     * グリッド編集(セル編集 / ペースト / `renderCell` の `setValue`)の取り消し/やり直し。`Ctrl/Cmd+Z`
+     * = undo、`Ctrl/Cmd+Shift+Z` / `Ctrl/Cmd+Y` = redo(ハンドルの `undo()` / `redo()` でも可)。
+     * clientSide(`rows` + `onRowsChange`)専用で、serverSide(`dataSource`)/ `readOnly` /
+     * `onRowsChange` 未指定時は無効。履歴は「変更前 rows 配列」
+     * の参照スナップショット(未変更行は構造共有されるため低コスト)。**`onRowsChange`
+     * で受け取った配列は参照そのまま `rows` へ戻すのが前提**(map 等で作り直すと毎回「外部変更」
+     * と見なされ履歴が消える)。rows が grid 起点以外(親の直接 setState 等)
+     * で差し替わると履歴は自動破棄。エディタ内の文字入力の取り消しは input のネイティブ undo
+     * に委譲(グリッドの undo は**確定済みの編集**が対象)。
+     *
+     * @defaultValue `true`
+     */
     enableUndoRedo?: boolean;
+    /**
+     * `Delete` / `Backspace` キーによる選択セル(なければアクティブセル)の値クリア。`false`
+     * でキーは何もしない(素通し)。ペースト・エディタでの上書き・undo/redo
+     * には影響しない(クリアのキーボード操作だけの opt-out)。
+     *
+     * @defaultValue `true`
+     */
     enableClearOnDelete?: boolean;
+    /**
+     * 組み込みエディタ(text / number / select / date)の `Enter`
+     * 確定後にアクティブセルをどこへ移すか(`'down'` | `'up'` | `'right'` | `'left'` | `'none'`。Excel
+     * の「Enter キーを押したら、セルを移動する(方向)」相当)。`'none'` は移動せずその場に留まる。`Tab`
+     * / `Shift+Tab`(右 / 左)と `Escape` には影響しない。custom エディタはキーバインドが consumer
+     * 責務のため対象外(`ctx.commit(value, direction)` の direction で指定)。
+     *
+     * @defaultValue `'down'`
+     */
     editorEnterMove?: EditorEnterMove;
+    /**
+     * 保持する undo ステップ数の上限。超過分は古い順に破棄。
+     *
+     * @defaultValue `100`
+     */
     undoHistoryLimit?: number;
+    /**
+     * undo / redo 可能状態が**変化したとき**に呼ばれる(ツールバーの undo/redo ボタンの disabled
+     * 表示などリアクティブな UI 用)。初回マウントでは発火せず、同値では再発火しない。
+     * 毎レンダーのインライン関数でも問題ない。
+     */
     onUndoRedoStateChange?: (state: UndoRedoState) => void;
+    /**
+     * 複数セル範囲選択。
+     *
+     * @defaultValue `true`
+     */
     enableRangeSelection?: boolean;
+    /**
+     * チェックボックス行選択の有効化(マスタースイッチ)。`true` で行ヘッダ(行NO)
+     * ガターが行選択のヒット領域になり、Excel 風のガター起点セル範囲選択は
+     * off(ボディ側セルのドラッグ範囲選択は不変)。判定は O(1)・全選択は除外集合でキーを列挙しない(1M
+     * 行でも一定コスト)。
+     *
+     * @defaultValue `false`
+     */
     enableRowSelection?: boolean;
+    /**
+     * 単一/複数の選択モード。single は常に 1 行。multiple はクリックでトグル、
+     * shift+クリック/ガタードラッグで範囲選択。
+     *
+     * @defaultValue `'multiple'`
+     */
     rowSelectionMode?: RowSelectionMode;
+    /**
+     * ヘッダ左上コーナーの全選択チェック(tri-state: none/some/all)の有効化。
+     *
+     * @defaultValue `enableRowSelection && multiple`
+     */
     enableSelectAllRows?: boolean;
+    /**
+     * **controlled** の行選択記述子。`{ type:'include', rowKeys }`=これらを選択 /
+     * `{ type:'exclude', rowKeys }`=全選択のうち除外。全選択をキー列挙せず表現できる。指定時は
+     * controlled(内部 state を使わない)。
+     */
     rowSelection?: RowSelectionModel;
+    /**
+     * controlled 簡易版(`{ type:'include', rowKeys }` の糖衣)。`rowSelection` と併用時は
+     * `rowSelection` を優先。全選択(exclude)は表現不可。
+     */
     selectedRowKeys?: GridRowKey[];
+    /** 行選択変化の通知(controlled/uncontrolled いずれでも発火)。 */
     onRowSelectionChange?: (model: RowSelectionModel) => void;
+    /**
+     * グローバルフィルター**機能**の有効化。`false` で機能が無効になり、
+     * 既定トップバーのフィルター入力欄も出ない(summary は `showTopBarSummary` に従う。
+     * トップバー自体を消すには `showTopBar=false`)。
+     *
+     * @defaultValue `true`
+     */
     enableGlobalFilter?: boolean;
+    /**
+     * 列ごとのフィルター。
+     *
+     * @defaultValue `true`
+     */
     enableColumnFilter?: boolean;
+    /**
+     * dateSet フィルター条件の日付入力を利用側コンポーネント(Mantine `DatePickerInput` 等)
+     * へ差し替えるスロット。既定は内製フィールド(自由入力 + ドリルアップカレンダー。下記「dateSet
+     * の日付入力(既定 UI)」節)。詳細は「日付入力の差し替え(renderFilterDateInput)」節。
+     *
+     * @defaultValue 内製の日付フィールド
+     */
     renderFilterDateInput?: (ctx: FilterDateInputContext) => F['node'];
+    /**
+     * set / select / 複合(numberSet / textSet / dateSet)列の候補を**非同期に供給**する(DB の DISTINCT
+     * など)。popover を開くたびに
+     * `{ columnKey, column, columnFilters(自列を除く他列の有効フィルター), globalText, signal }`
+     * で呼ばれ、閉じる / 列切替で `signal` が abort される(ライブラリはキャッシュしない)。読み込み中
+     * / 失敗(再試行)/ 打ち切り(`truncated`)の表示は popover が持つ。優先順位は
+     * `column.filterOptions`(静的)> `getFilterOptions` > rows 自動収集。非同期候補の列は反転(exclude)
+     * 可。clientSide / serverSide 両対応。詳細は「ソートとフィルター」ガイド。
+     */
     getFilterOptions?: (params: GetFilterOptionsParams<T, F>) => Promise<GetFilterOptionsResult>;
+    /**
+     * ヘッダークリックでのソート。
+     *
+     * @defaultValue `true`
+     */
     enableSorting?: boolean;
+    /**
+     * 列 / グローバルフィルターの**絞り込みをグリッドで行わない**(手動フィルターモード)。フィルター
+     * UI(popover / チップバー / フィルター管理 / フィルター中の印)と状態(`GridState.filters` /
+     * `onStateChange`)は従来どおり動き、`rows` は渡した件数・順のまま表示される(絞り込みはサーバ側
+     * WHERE 等の外部責務)。`rows` が 0 件でフィルターが載っているときは `noMatchingRowsText` を表示。
+     * serverSide(`dataSource`)では無視。詳細は「ソートとフィルター」ガイド。
+     *
+     * @defaultValue `false`
+     */
     manualFiltering?: boolean;
+    /**
+     * ソートの**並べ替えをグリッドで行わない**(手動ソートモード)。ソート UI と状態(`GridState.sort` /
+     * `onStateChange`)は従来どおり動き、`rows` は渡した順のまま。再マウントなしで切り替え可(`false`
+     * へ戻すと即座にクライアントソートが適用)。手動ソート中はラベル行の `sortMode` 連動 /
+     * 行ドラッグの無効化は起きない(並べ替えていない扱い)。serverSide では無視。
+     *
+     * @defaultValue `false`
+     */
     manualSorting?: boolean;
+    /**
+     * 列幅の手動リサイズ可否のグリッド既定。各列 `resizable`
+     * 未指定時に継承(`column.resizable ?? enableColumnResize`)。
+     *
+     * @defaultValue `true`
+     */
     enableColumnResize?: boolean;
+    /**
+     * データ投入時に全列幅を内容へ自動フィット。`'onMount'`=初回にデータが載った一度きり /
+     * `'onDataChange'`=`rows`(参照)が変わるたび(= データ差し替えのたび。手動リサイズは上書き) /
+     * `false`=無効。計測は列メニュー「すべての列の幅を自動調整」と同一エンジン(`suppressAutoSize` /
+     * `autoHeight` 列は除外)。フィルター / ソート / 列並べ替えでは再フィットしません。
+     * serverSide(`dataSource`)では無効。詳細は「flex と autoSize」節。
+     *
+     * @defaultValue `false`
+     */
     autoSizeColumns?: AutoSizeColumnsMode;
+    /**
+     * セル内容が省略(…)される列で、ホバー時に全文ツールチップを表示。
+     * 対象は既定テキストセルのみ(`renderCell` 列 / `autoHeight` 折り返し列は対象外)。表示はホバー時に
+     * `scrollWidth > clientWidth` を判定し、実際にクリップされているセルのみ。
+     * 既存のカスタムツールチップ(`data-ssg-tooltip`)を共有。詳細は「ツールチップ」節。
+     *
+     * @defaultValue `false`
+     */
     showCellOverflowTooltip?: boolean;
+    /**
+     * invalid マーク(背景 + 右上マーカー + ホバーツールチップ)の表示可否。`false` で非表示 +
+     * 可視セルの `validate` 評価スキップ。`getInvalidCells()` と `validationMode: 'reject'`
+     * の書き込み拒否には影響しない(独立経路)。「送信時にだけマークを出す」UX は利用側 state で本 prop
+     * を切り替えて実現(「バリデーション」節のレシピ参照)。
+     *
+     * @defaultValue `true`
+     */
     showValidationMarks?: boolean;
+    /**
+     * 行ホバー時に行全体を薄くハイライト。
+     *
+     * @defaultValue `true`
+     */
     enableRowHover?: boolean;
+    /**
+     * 行ホバーの controlled 値(ビュー行 index / `null` = ホバーなし)。指定時は内部 state
+     * を使わずこの値でハイライトし、pointer 由来の変化は `onHoveredRowChange` で通知のみ(optionally
+     * controlled)。`enableRowHover: false` のときは無視(ハイライトも通知もしない)。一時的な UI
+     * 状態のため `GridState` / ハンドルには載らない。
+     */
     hoveredRowIndex?: number | null;
+    /**
+     * 行ホバーが変わったときの通知(uncontrolled でも呼ばれる)。`viewRowIndex` はフィルター /
+     * ソート適用後のビュー行 index。同値では発火しない(pointerenter
+     * は同一行内のセル跨ぎでも来るため)。用途: 複数グリッド間のホバー同期など。
+     */
     onHoveredRowChange?: (viewRowIndex: number | null, ctx: {
         source: 'pointer';
     }) => void;
+    /**
+     * 列ヘッダーのホバー時にヘッダーセルを薄くハイライト。
+     *
+     * @defaultValue `true`
+     */
     enableColumnHeaderHover?: boolean;
+    /**
+     * 列メニュー(⋮ + ヘッダー右クリック)。
+     *
+     * @defaultValue `true`
+     */
     enableColumnMenu?: boolean;
+    /**
+     * フィルター結果 0 行時のオーバーレイ文言。
+     *
+     * @defaultValue `'一致する行がありません'`
+     */
     noMatchingRowsText?: string;
+    /**
+     * rows が 0 件のときの文言。
+     *
+     * @defaultValue `'表示する行がありません'`
+     */
     noRowsText?: string;
+    /**
+     * 上部バー(ツールバー)の表示有無。`false` で `renderTopBar` / `enableGlobalFilter`
+     * に関わらず一切描画しない(表示のマスタースイッチ。矛盾指定時は `renderTopBar` より優先)。
+     *
+     * @defaultValue `true`
+     */
     showTopBar?: boolean;
+    /**
+     * 既定トップバーの summary chips(件数/フィルター/ソート)の表示有無。`renderTopBar`
+     * 未指定時のみ有効。これと `showTopBarFilter`
+     * がともに非表示なら既定トップバーは描画されない(空バーを出さない)。
+     *
+     * @defaultValue `true`
+     */
     showTopBarSummary?: boolean;
+    /**
+     * 既定トップバーの Rows / Columns 件数 chips の表示有無。`showTopBarSummary=true`(かつ
+     * `renderTopBar` 未指定)のときのみ有効。Filter / Sort chips は対象外。
+     *
+     * @defaultValue `true`
+     */
     showTopBarCounts?: boolean;
+    /**
+     * 既定トップバーのグローバルフィルター入力欄の表示有無。`renderTopBar` 未指定時のみ有効。
+     * `enableGlobalFilter=false` のときは本値に関わらず非表示。
+     *
+     * @defaultValue `true`
+     */
     showTopBarFilter?: boolean;
+    /**
+     * 既定トップバーのグローバルフィルター入力の placeholder。`renderTopBar` 未指定時のみ有効。
+     *
+     * @defaultValue `'グローバルフィルター'`
+     */
     globalFilterPlaceholder?: string;
+    /**
+     * 既定トップバーのグローバルフィルター入力の左アイコン。`renderTopBar` 未指定時のみ有効。
+     * `undefined`=組み込みの検索(虫眼鏡)アイコン / `null`(など falsy)=アイコン無し / 任意
+     * `ReactNode`=差し替え。クリアボタンは入力枠の内側右に `×` で表示され、入力が空のときは出ない。
+     *
+     * @defaultValue 組み込み検索アイコン
+     */
     globalFilterIcon?: F['node'];
+    /**
+     * 下部バー(ステータスバー)の表示有無。`false` で `renderBottomBar`
+     * に関わらず一切描画しない(表示のマスタースイッチ。矛盾指定時は `renderBottomBar` より優先)。
+     *
+     * @defaultValue `true`
+     */
     showBottomBar?: boolean;
+    /**
+     * 既定ボトムバーの Rows / Columns 件数 chips(左側)の表示有無。`renderBottomBar`
+     * 未指定時のみ有効。右側の Active / Selection / 選択統計 / Cols は対象外。
+     *
+     * @defaultValue `true`
+     */
     showBottomBarCounts?: boolean;
+    /**
+     * フィルターチップバー(適用中の列フィルターをトップバー直下にチップで常時表示)
+     * の表示有無(opt-in)。有効フィルター 0 件時はバーごと非表示(空バーは出さない)。`showTopBar`
+     * とは独立。チップ本体クリックで対象列へジャンプしてフィルター popover を開き、× で個別クリア、
+     * 「すべてクリア」は列フィルターのみ対象(グローバルフィルターは対象外)。
+     *
+     * @defaultValue `false`
+     */
     showFilterChipBar?: boolean;
+    /**
+     * 上部バーの差し替え。未指定時は内蔵トップバー(summary chips + フィルター入力。内訳は
+     * `showTopBarSummary` / `showTopBarFilter` で制御。フィルター入力は `enableGlobalFilter=true`
+     * が前提)。`showTopBar=false` 時は本指定に関わらず描画されない。
+     *
+     * @defaultValue 内蔵トップバー
+     */
     renderTopBar?: (context: SpreadsheetGridSlotContext<T, F>) => F['node'];
+    /**
+     * 下部バーの差し替え。未指定時は内蔵ステータスバー。`showBottomBar=false`
+     * 時は本指定に関わらず描画されない。
+     *
+     * @defaultValue 内蔵ボトムバー
+     */
     renderBottomBar?: (context: SpreadsheetGridSlotContext<T, F>) => F['node'];
+    /** ルート要素の class。 */
     className?: string;
+    /**
+     * ルート要素(`.ssg-root`)のインライン style。`classNames.root` の style とマージされ、
+     * こちらが後勝ち。
+     */
     style?: F['style'];
+    /**
+     * パーツ別の追加スロット。各値は `GridSlotProps`(`string | { className?, style? }`)で、StyleX の
+     * `stylex.props(...)` の戻り値をそのまま渡せる。全 25
+     * スロット配線済み(一覧と規則は「パーツ別スロット」節)。
+     * レンダー毎に新しいオブジェクトを渡してもよい(内容の署名で memo)。基底 class
+     * は未レイヤー・特異度 (0,1,0)
+     * のため同特異度のクラスは読み込み順で決まる(確実な上書きは連結セレクタか `style.layer.css`)。
+     */
     classNames?: GridClassNames<F>;
+    /**
+     * 行ごとの追加 class(または `{ className, style }`)。行コンテナ + 行ヘッダー「#」セル +
+     * 各データセルに付与され、Tailwind / StyleX での行ハイライトに使える。`style`
+     * はインラインで付与され、座標 / 寸法はグリッドが後勝ち(返した style は内容比較で memo される)。
+     * 第 3 引数 `ctx` は `{ row, rowIndex, sourceRowIndex, rowKey, isSelected }`(「補助型」節参照)。
+     * 既存の 2 引数関数もそのまま動く(後方互換)。グループ行は対象外。
+     */
     getRowClassName?: (row: T, rowIndex: number, ctx: RowStyleContext<T>) => GridSlotProps<F> | undefined;
+    /**
+     * **展開行(Master/Detail)**。マスター行の直下に、行順(view index)を変えずに全幅の帯を差し込み、
+     * その中(カード)へ `render` の返す任意の React 要素(自前のサブグリッド / フォーム / 集計パネル等)
+     * を描画する。指定時のみ有効で、未指定なら既存の描画・状態・イベント経路は一切変わらない。
+     * `{ render, height?, isExpandable?, showToggleColumn?, className? }`。clientSide / serverSide
+     * の両方で使える(serverSide の制約は節内)。詳細は「展開行(Master/Detail)」節を参照。
+     *
+     * @defaultValue —(無効)
+     */
     detailRow?: DetailRowOptions<T, F>;
+    /**
+     * 展開中の展開行のマスター行キー集合が**変化したとき**に呼ばれる(開閉の永続化・外部同期用)。
+     * 初回マウントでは発火しない。インライン関数可(latest-ref 経由)。
+     */
     onExpandedDetailRowKeysChange?: (keys: GridRowKey[]) => void;
+    /**
+     * **ラベル行(見出し / 区切り行)**。`rows` の中で `isLabelRow(row)` が true
+     * の行を「行数に数えない見出し」として、3 ペインを跨ぐ全幅の帯で描画する(中身は `render` で任意の
+     * React 要素に差し替え可。横スクロールしても左端に留まる)。編集 / 選択 / コピー /
+     * エクスポートの既定対象外で、行番号も消費しない。ソート /
+     * フィルターは既定でラベル行から次のラベル行までの区間(セクション)に閉じる(`sortMode`)。
+     * `sticky: true` で現在セクションのラベルを列ヘッダー直下に固定。
+     * `{ isLabelRow, getLabel, render?, height?, className?, sticky?, sortMode?, keepEmptySections?, exportText? }`。
+     * 行グルーピング(`rowGroup`)とは別機能で併用不可。詳細は「ラベル行(見出し / 区切り行)」節。
+     *
+     * @defaultValue —(無効)
+     */
     labelRow?: LabelRowOptions<T, F>;
+    /**
+     * **行ドラッグ並び替え**。先頭にドラッグハンドル列(幅 28px・タイトル無しの合成列。
+     * 左固定列があれば左固定側)を挿入し、ハンドル(⋮⋮)を掴んで行を上下へ動かせる。確定時は
+     * `onRowsChange` へ移動後の**新配列**を渡し(履歴ラッパ経由 = undo/redo 対象)、続けて `onRowMove`
+     * を呼ぶ。clientSide(`rows` + `onRowsChange`)専用で、`dataSource`(serverSide)/ 行グルーピング中 /
+     * `onRowsChange` 未指定ではハンドル列を出さない。ソート / フィルター適用中はハンドルを淡色 +
+     * 理由ツールチップにして操作を無効化する(列は残る)。詳細は「行ドラッグ並び替え」節。
+     *
+     * @defaultValue `false`
+     */
     enableRowDrag?: boolean;
+    /**
+     * 行ごとのドラッグ可否。`false` の行にはハンドルを描画しない。
+     * `ctx = { rowKey, sourceRowIndex }`。
+     *
+     * @defaultValue 全行可
+     */
     isRowDraggable?: (row: T, ctx: RowDragContext) => boolean;
+    /**
+     * 行移動の確定後(`onRowsChange` の直後)に呼ばれる。
+     * `params = { rowKey, fromIndex, toIndex, rows }`(index は元 `rows` 配列基準、`rows` は
+     * `onRowsChange` と同じ新配列参照)。ハンドルの `moveRow()` による移動でも呼ばれる。
+     */
     onRowMove?: (params: RowMoveParams<T>) => void;
+    /**
+     * コンテキストメニュー機能の有効化(マスタースイッチ)。他機能の `enable*` と同じく**既定 OFF**。
+     * `false` のあいだは `getContextMenuItems` を渡しても発火せず、
+     * 右クリックはブラウザ標準メニューのまま。現状はまだ機能 / UI に改善余地があるため既定 OFF
+     * で提供する(利用側で明示 opt-in)。
+     *
+     * @defaultValue `false`
+     */
     enableContextMenu?: boolean;
+    /**
+     * セル/行の**完全カスタム**コンテキストメニュー。右クリック時のみ呼ばれ、
+     * 返した項目でメニューを描画する(ライブラリは固定の既定項目を持たない)。opt-in は
+     * `enableContextMenu={true}` かつ本コールバックの指定の両方。**未指定、または `[]`
+     * を返したときはブラウザ標準の右クリックメニューへフォールスルー**(空パネルは出さない)。SSRM
+     * 未ロード行では開かない。ヘッダー右クリックは列メニュー(`enableColumnMenu`)が担当し、
+     * 本メニューはボディ(セル / 行NO ガター)専用。詳細は「コンテキストメニュー」節を参照。
+     */
     getContextMenuItems?: (params: GridContextMenuParams<T, F>) => GridContextMenuItem<F>[];
+    /**  */
     onContextMenuOpen?: (params: GridContextMenuParams<T, F>) => void;
+    /**
+     * **スクロール位置インジケーター**。スクロール中にスクロールバー脇へ行番号バブル(「行 N /
+     * 総行数」+ 任意の列値)と行目盛りルーラーを表示し、スクロールバー帯のホバーで「行 N へ」
+     * のジャンプ先プレビューを出す。`true`
+     * は全既定(`{ bubble: true, ruler: true, scrollbar: true, trigger: 'scroll', minRows: 0 }`)
+     * と同義。`minRows` で「表示行数がしきい値以上のときだけ有効」のデータ量ゲートも掛けられる。
+     * 表示は総行数とスクロール位置のみで駆動されるため **clientSide / SSRM の全構成で動作**。
+     * オーバーレイは `pointer-events: none` で既存操作へ一切干渉しない。
+     * 詳細は「スクロール位置インジケーター」節を参照。
+     *
+     * @defaultValue —(無効)
+     */
     scrollHint?: boolean | ScrollHintOptions<T, F>;
 };