SpreadsheetGrid props

SpreadsheetGrid props (SpreadsheetGridProps<T>)

バーの表示制御(top / bottom)

トップ / ボトムバーは次の優先順で解決される。

• showTopBar / showBottomBar(マスタースイッチ): false ならそのバーは一切描画されない(render* / enable* より優先)。
• renderTopBar / renderBottomBar(カスタム): 指定時はそのまま描画。トップバーの内訳 props(showTopBarSummary / showTopBarFilter)はカスタム側が中身を決めるため関与しない。
• 既定バー: render* 未指定時のフォールバック。

既定トップバーは summary chips(左) と グローバルフィルター入力(右) の 2 パートからなり、独立に出し分けできる。

showTopBarSummary と showTopBarFilter(実効は showTopBarFilter && enableGlobalFilter)がともに false の場合、既定トップバーは描画されない(空バーを出さない)。

ボトムバーは Rows / Columns 件数を showBottomBarCounts、選択範囲の集計を showSelectionAggregates で出し分けできる(右側の Active / Selection / 選択統計 / Cols は対象外)。それ以外の内訳を変えたい場合は renderBottomBar を使う。

選択範囲の集計(showSelectionAggregates)

2 セル以上を選ぶと、既定ボトムバーの右側に Excel のステータスバーと同じ 平均 / データの個数 / 合計 が出る(既定 ON)。

• 数えるのは選択範囲のうち表示中のデータ行 × データ列のセル。フィルターで隠れた行・グループ行・ラベル行・合成列(行ドラッグ / 展開トグル / 自動グループ列)は対象外。
• 合計 / 平均は数値と数値の文字列だけ(グループ集計の aggFunc と同じ判定。空白だけの文字列・boolean・Date は数えない)。データの個数は空でない(null / undefined / 空文字でない)セルの数。数値が 1 つも無いときはデータの個数だけ、空のセルだけのときは何も出さない。
• 値は getValue があればその値(表示用の valueFormatter は通さない)。表示は小数 4 桁まで・桁区切りあり。
• 走査するセルが 50,000 を超える選択(全選択など)は主スレッドを塞がないよう時間分割で計算し、その間は「集計中… N%」。編集で値が変わると計算し直す(そのあいだは前の結果を出したまま。行が頻繁に入れ替わっても、計算が終わるたびに新しい値になる)。
• 既定ボトムバーでは右グループ(Active / Selection …)の隣の空きに置き、バーの高さや他の項目の位置は変えない(入りきらないときは端から切れ、ポインタを重ねると全文)。
• 出す先(ボトムバー、または自前の renderTopBar)が無いときは計算しない。
• SSRM では読み込み済みの行だけで計算し、「読み込み済みの行のみ」と添える。
• 自前のバー(renderTopBar / renderBottomBar)では slotContext.selectionAggregates(GridSelectionAggregates。最小 / 最大も入る)で同じ値を使える。

renderBottomBar={(ctx) => {
  const agg = ctx.selectionAggregates;
  return (
    <div className="my-statusbar">
      {agg?.status === 'computing' && <span>集計中…</span>}
      {agg?.status === 'ready' && agg.sum !== undefined && (
        <span>合計 {agg.sum} / 最小 {agg.min} / 最大 {agg.max}</span>
      )}
    </div>
  );
}}

フィルハンドル(fillHandle)

fillHandle を指定すると、選択範囲(無ければアクティブセル)の右下に小さな四角(フィルハンドル)が出ます。引くと Excel のオートフィルと同じく、元の値の続き(連続データ)か元の値の繰り返し(セルのコピー)で埋めます。

<SpreadsheetGrid rows={rows} onRowsChange={setRows} columns={columns} fillHandle />
// 埋める値を差し替える(例: 「数量」列は 10 の倍数に丸める)
<SpreadsheetGrid
  rows={rows}
  onRowsChange={setRows}
  columns={columns}
  fillHandle={{
    getFillValue: ({ column, defaultValue }) =>
      column.key === 'qty' && typeof defaultValue === 'number' ? Math.round(defaultValue / 10) * 10 : defaultValue,
  }}
/>

FillHandleOptions<T>(fillHandle にオブジェクトで渡したとき):

GridFillValueParams<T>(getFillValue の引数):

• 操作: ハンドルを押して上下か左右へ引きます(元の範囲から遠く離れた向きを採る)。点線が埋める範囲、ポインタの近くの値がいちばん遠いセルへ入る値です。表の端へ寄せると自動でスクロールします。Ctrl(Mac は ⌘)を押しているあいだは埋め方が入れ替わり、Escape でやめます(ドラッグ中のキーはグリッドへ流しません)。離すと元の範囲 + 埋めた範囲が選ばれます(アクティブセルはそのまま)。
• 埋め方の既定: 列ごと(上下へ埋めるとき)/ 行ごと(左右へ埋めるとき)に決めます。続き方の分かる値は連続データ、数値 1 つ・数字だけの文字列 1 つ・続き方の無い値はコピーです。Ctrl / ⌘ はこれを入れ替えます(数値 1 つなら 1 ずつ増やす)。上 / 左へ引くと逆向きに続きます(1, 2, 3 の上は 0, -1 …。元の値が 1 つなら 1 ずつ戻り、日付は前の日)。
• 連続データの規則:
  • 数値: 2 つ以上なら最小二乗の直線で続けます(等差ならその差。1, 3 → 5, 7)。浮動小数の誤差は丸めます。数値の文字列('1.5')も同じ規則で文字列を返します。
  • 日付: Date と 'YYYY-MM-DD' / 'YYYY/MM/DD' の文字列(形式を保つ)。日が同じで月の差が一定なら月単位(2026-01-15, 2026-02-15 → 2026-03-15。その月に無い日は月末に丸める)、それ以外は日単位です(1 つだけなら 1 日ずつ)。
  • 曜日 / 月の名前: 日本語(月 / 月曜 / 月曜日、1月)と英語の短縮・正式(Mon / Monday、Jan / January)。英語は大文字小文字を最後の値に合わせます。
  • 末尾が数字の文字列(P-001、No.9): 前置きが同じとき末尾の数を進めます。0 埋めは最後の値が 0 で始まるときだけ桁数を保ちます。
  • 空のセルを含む元の値・型の混在・真偽値は常にコピーです(空のセルから引くと埋める範囲を空にする。Excel と同じ)。
• 埋めたあとのボタン: 埋めた範囲の右下に出ます。押すとメニュー(連続データ / セルのコピー)を開き、選び直すと埋める前の値から作り直します(履歴は 1 つのまま = 元に戻す 1 回で埋める前へ)。列 / 行ごとに埋め方が混ざるときに選ぶと、すべての列 / 行をその埋め方にします(続き方の無い値はコピーのまま)。連続データにできる値が無いときは「連続データ」を選べません。右下に余地が無い(表の下端・合計行・見えている範囲の下端にかかる)ときは角の上に出します。選択を変える・セルの値が外から変わる・列が変わる・ソート / フィルター / グループの開閉が変わる・編集を始めると消えます。
• ダブルクリック: ハンドル(見えている四角)のダブルクリックで、左隣(値が無ければ右隣)の列に値が続く行まで下へ埋めます。埋める列にすでに値があるセル・ラベル行 / グループ行・未読み込み行の手前で止まり、既存の値は上書きしません。
• 書き込みの規則: 貼り付けと同じです。readOnly / 列の editable: false / canEditCell で編集できないセルは飛ばし、validate で reject されたセルも書きません(mark は書いてエラー表示)。値は型を保って書きます(貼り付けのような文字列からの変換はしない)。clientSide は onRowsChange に 1 回で渡し、undo / redo の対象です。
• 飛ばすもの: ラベル行 / グループ行(位置にも数えない)/ 合成列(行ドラッグ / 展開トグル / 自動グループ列)/ 合計行。フィルター / ソート中は表示されている順に埋め、隠れた行には書きません。表の末尾より先へ行は増やしません。
• 出さないとき: readOnly、書き込み先が無い(clientSide で onRowsChange が無い / serverSide で dataSource.updateRows が無い)、編集中、範囲を選んでいる最中、行 / 列の選択中、選択範囲が合成列だけ / ラベル行・グループ行だけ(埋める元の値が無い)のとき。
• serverSide(dataSource): dataSource.updateRows があるときだけ使えます(楽観更新・失敗時のロールバックは編集と同じ)。読み込まれていない行には書かず、元の範囲に読み込まれていない行がある列 / 行は埋めません。undo / redo はありません(serverSide 共通)。ボタンでの選び直しは、行の並びが埋めたときと同じあいだだけできます。選び直しはそのときの行の上に書くため、validate の reject などで選び直しでは書かないセルには、最初に埋めた値が残ります。
• キーボード / 支援技術: ハンドルはポインタ操作の部品で、読み上げの対象外です(aria-hidden)。キーボードではコピー / 貼り付けで同じことができます。埋めたあとのボタンは aria-haspopup="menu"、メニューは role="menu" + role="menuitemradio"(↑ / ↓ で移動、Escape / Tab で閉じる)。
• 見た目: ハンドル .ssg-fill-handle、点線 .ssg-fill-preview、ドラッグ中のルート .ssg-root--filling、ボタン .ssg-fill-options、メニュー .ssg-menu-panel.ssg-fill-menu、値のツールチップ .ssg-tooltip.ssg-fill-tooltip。トークン --ssg-fill-line(点線の色。既定は文字色)/ --ssg-fill-handle-ring(ハンドルの縁取り。既定はセルの地色)。ハンドルの色は --ssg-accent。

セル操作の通知(onCellClick / onCellDoubleClick / onActiveCellChange)

データセルのクリック / ダブルクリック / アクティブセルの変化を受け取る通知口。3 つとも省略可で、指定しなければ従来どおり(グリッドの既定の動作は変わらない)。

• 渡るもの: GridCellRef<T> = { row, rowKey, rowIndex, sourceRowIndex, column, columnKey, colIndex, value }。行は index ではなく行データ row と rowKey を主に使う(rowIndex はフィルター / ソート後の表示位置 = handle.selectCell と同じ空間、sourceRowIndex は元 rows の index、colIndex は論理列 index)。value はセルの生値(getValue 指定列はその戻り値。valueFormatter 適用前)。クリック / ダブルクリックには event(DOM 標準の MouseEvent。React の合成イベントではない)が付く。修飾キー(ctrlKey / shiftKey / metaKey / altKey)はここから読む。
• 対象: データ行 × 利用側の列のセルだけ。列ヘッダー / 行番号「#」/ グループ行 / ラベル行 / 展開行の帯 / SSRM の未ロード行(スケルトン)/ 合成列(展開トグル列・行ドラッグハンドル列・自動グループ列)ではクリック / ダブルクリックを通知せず、アクティブセルがこれらへ移ったときの onActiveCellChange は null。
• クリックの判定: ブラウザの click イベントに従う。左ボタンのみで、押したセルと離したセルが違う(範囲選択のドラッグ)ときは呼ばれない。セル内に置いた自前の要素のクリックもそのセルのクリックとして届くため、セルの通知に含めたくない要素は自分で event.stopPropagation() する。
• 順番: マウスで別のセルをクリックすると onActiveCellChange(pointerdown でアクティブセルが移った分)→ onCellClick の順。ダブルクリックはブラウザの仕様どおり onCellClick × 2 → onCellDoubleClick の順。
• ダブルクリックの既定の動作: 編集可能セルなら編集開始、checkbox 列・読み取り専用セルは何もしない。params.preventDefault() でこれを止められる(F2 / Enter / 印字キーでの編集開始には影響しない)。

// 読み取り専用の一覧: 行をクリックしたら上の入力フォームへ写す。
<SpreadsheetGrid<Row>
  rows={rows}
  columns={columns}
  readOnly
  rowKeyGetter={(row) => row.id}
  onCellClick={({ row }) => form.setValues(row)}
/>

// 選択モーダル: ダブルクリックした行で確定して閉じる。
<SpreadsheetGrid<Row> rows={rows} columns={columns} readOnly onCellDoubleClick={({ row }) => onConfirm(row)} />

// 「件名」セルだけダブルクリックでモーダルを開き、他のセルは従来どおり編集を始める。
<SpreadsheetGrid<Row>
  rows={rows}
  columns={columns}
  onRowsChange={setRows}
  onCellDoubleClick={(params) => {
    if (params.columnKey === 'subject') {
      params.preventDefault();
      openSubjectPicker(params.rowKey);
    }
  }}
/>

// キー操作での移動も含めて、アクティブセルの行を詳細パネルへ出す。
<SpreadsheetGrid<Row> rows={rows} columns={columns} onActiveCellChange={(cell) => setDetail(cell?.row ?? null)} />

コンテキストメニュー(enableContextMenu / getContextMenuItems)

セル / 行の右クリックで開く完全カスタムメニュー。既定は OFF(enableContextMenu={false})で、他機能の enable* と同じくマスタースイッチで有効化する(現状はまだ機能 / UI に改善余地があるため既定 OFF)。ライブラリは固定項目を一切持たず、getContextMenuItems が返した項目配列だけを描画する。用意されるのは「窓」(パネル外装 + 右クリック座標配置 + 開閉 / Escape / 外側クリック / スクロール close)だけで、中身(ラベル / アイコン / onSelect)はすべて利用側が渡す。列メニューと同じ .ssg-menu-panel / .ssg-menu-item 外装を再利用する。

opt-in と標準メニューへのフォールスルー

• enableContextMenu 未設定 / false(既定)→ ブラウザ標準の右クリックメニュー(getContextMenuItems を渡していても発火しない)。
• enableContextMenu={true} かつ getContextMenuItems が項目を返した → その項目が並んだメニューを右クリック座標に表示。
• enableContextMenu={true} でも getContextMenuItems 未指定 / [] を返した(対象で項目なし)→ ブラウザ標準メニュー(空パネルは浮かせない)。

対象と挙動

• ヘッダー右クリックは対象外(列メニュー enableColumnMenu が担当)。本メニューはボディの データセルと 行NO ガター専用。
• SSRM 未ロード行(まだ取得できていない行)の上では開かない(標準メニューになる)。
• uncontrolled のみ。右クリックしてもセル選択は変化しない(対象セル/行の情報は params で受け取る)。
• close 契機: 項目選択 / 外側クリック / Escape / スクロール。項目間のキーボード移動(矢印キー)は持たない。

GridContextMenuParams<T>(コールバック引数)

GridContextMenuItem(判別共用体)

• action(既定): { kind?: 'action'; id?; label: ReactNode; icon?: ReactNode; disabled?; danger?; onSelect: () => void } — クリックで onSelect 実行後に自動で閉じる。icon 省略時も左 14px 枠が空スペーサになりラベル左端が揃う。danger は削除など危険操作の赤系強調(Mantine の color="red" 相当)。
• label(見出し): { kind: 'label'; id?; label: ReactNode } — 非インタラクティブなセクション見出し(Mantine の Menu.Label 相当)。項目群のグルーピング表示に使う。
• separator: { kind: 'separator'; id? } — 区切り線(Mantine の Menu.Divider 相当)。
• custom(レンダラ / エスケープハッチ): { kind: 'custom'; id?; render: (ctx: { close: () => void }) => ReactNode } — パネル内に任意 JSX を差し込む。close() で任意タイミングに閉じられる。

id は React key 用(省略時は配列 index)。項目は非ジェネリック: 行データは getContextMenuItems 内で params を通じてクロージャに閉じ込める。

例

<SpreadsheetGrid
  // …
  enableContextMenu // 既定 false。機能を使うにはこのマスタースイッチが必要
  getContextMenuItems={(params) => {
    const items: GridContextMenuItem[] = [];
    items.push({ kind: 'label', label: '操作' }); // セクション見出し
    if (params.target.type === 'cell') {
      const value = params.target.value; // narrowing はローカルへ退避してから onSelect で使う
      items.push({
        label: '値をコピー',
        icon: '📋',
        onSelect: () => navigator.clipboard?.writeText(String(value ?? '')),
      });
    }
    items.push({ kind: 'separator' });
    items.push({
      label: 'この行を削除',
      danger: true, // 赤系強調
      onSelect: () => deleteRow(params.target.rowKey),
    });
    items.push({ kind: 'separator' });
    items.push({
      label: '選択範囲を CSV 出力',
      disabled: !params.isTargetSelected,
      onSelect: () => gridRef.current?.downloadCsv('selection.csv', { scope: 'selection' }),
    });
    items.push({
      kind: 'custom',
      render: ({ close }) => (
        <div style={{ padding: '6px 8px' }}>
          行 {params.target.rowIndex}
          <button type="button" onClick={close}>閉じる</button>
        </div>
      ),
    });
    return items; // [] を返すと標準メニューへフォールスルー
  }}
  onContextMenuOpen={(params) => console.log('opened at', params.target)}
/>

レシピ: 右クリックからフィルター管理パネルを開く

適用中フィルターの一覧 / 編集 / クリアを行うフィルター管理パネル(列メニュー「フィルターを管理…」と同じもの)は、ハンドルの openFilterManager() で任意の場所から開ける。コンテキストメニューに載せる場合:

const gridRef = useRef<SpreadsheetGridHandle<Row>>(null);

<SpreadsheetGrid
  ref={gridRef}
  enableContextMenu
  getContextMenuItems={() => [
    {
      label: 'フィルターを管理…',
      onSelect: () => gridRef.current?.openFilterManager(),
    },
  ]}
/>;

スクロール位置インジケーター(scrollHint)

大量行(特に 100 万行級)ではスクロールバー 1px の移動が数百〜数千行に相当し、移動中に「今どの行にいるか」を見失う。scrollHint は次の 3 つのオーバーレイでこれに答える(既定は完全無効。opt-in)。

• 行番号バブル(bubble): スクロール中、スクロールバー脇(サム位置)に「行 N / 総行数」を表示。hintColumn / renderHint で任意の列値を添えられる。
• 行目盛りルーラー(ruler): ボディ右端に行数スケール(切りのよい刻み。刻みが 1 万の倍数のときは「10万」等の圧縮表記へ全目盛り統一)。スクロール中とスクロールバー帯ホバー中のみフェード表示。
• ジャンプ先プレビュー(ruler に含む): スクロールバー帯(右端)にポインタを置くと、スクロールバーのクリック / ドラッグと同じサム中心写像で「行 N へ」の点線 + ラベルを表示。
• カスタムスクロールバー(scrollbar): ヘッダー下から始まる専用ガターに常時表示のトラック + 最小 30px サムを自前描画(ドラッグ / クリックジャンプ / ホイール対応)。macOS のオーバーレイスクロールバーは自動で消え、大量行ではサムが極小になり「掴む場所」を見失うための置き換え。有効時はネイティブ縦スクロールバーを非表示化する(Chromium / WebKit。Firefox はネイティブ縦バーが残るがガター操作は有効)。

ScrollHintOptions<T>:

// 簡易: 行番号 + 品番
<SpreadsheetGrid scrollHint={{ hintColumn: 'partNo' }} />

// 完全カスタム: 品番 — 品名
<SpreadsheetGrid
  scrollHint={{
    trigger: 'scroll',
    renderHint: ({ rowData }) =>
      rowData ? `${rowData.partNo} — ${rowData.partName}` : null,
  }}
/>

データ量ゲート(minRows): 小規模データではバブル / ルーラー / カスタムスクロールバーがノイズになるため、minRows を指定すると「表示行数がしきい値以上のときだけ出る」挙動にできる(例: scrollHint={{ minRows: 100 }})。判定はバブルの「/ 総行数」と同じ行数(フィルター / グルーピング適用後のビュー行数。SSRM はサーバー総行数)で、フィルターで絞り込んでしきい値を割ればその間は自動 OFF になる。既定は 0(常時有効)。注意: scrollbar 有効時はしきい値またぎでガター余白が付け外しされるため、行数が変動する画面では僅かなレイアウトシフトが起きる(気になる場合は scrollbar: false と併用する)。

SSRM / グルーピングでの挙動: バブル / プレビューの対象行が SSRM の未ロード行(またはグルーピングのグループ行)の場合、rowData は undefined になり、hintColumn 指定時は自動的に行番号のみへフォールバックする(renderHint には undefined がそのまま渡るので利用側で分岐する)。総行数とスクロール位置だけで駆動されるため、インジケーター自体は SSRM を含む全構成で動作する。

実装ノート: 行番号は仮想化の縦ジオメトリ(1M 行の pixel scaling / auto-height の prefix-sum)と同一の写像で解決するため常に正確。バブル / ルーラー / プレビューのオーバーレイは pointer-events: none で、スクロール・セル操作へ一切干渉しない。カスタムスクロールバーのガターのみポインタ操作を受けるが、コンテンツのスクロール自体はネイティブのまま(ガターは scrollTop を書くだけの鏡映し)。全行が viewport に収まりスクロール不能のときは何も表示しない。配色はテーマトークン(--ssg-pill-* / --ssg-scrollhint-*)で light / dark 両対応。

展開行(Master/Detail)(detailRow)

detailRow prop を渡すと、各行を「展開」してマスター行の直下に消費側 UI(カード)を差し込めます(AG Grid の Master/Detail 相当)。行グルーピングが「ライブラリがグループ行を作る」機能なのに対し、展開行は「行の下に何を出すかを利用側が全面的に決める」動線です。両者は独立で併用もできます。

<SpreadsheetGrid
  rows={rows}
  columns={columns}
  rowKeyGetter={(row) => row.id}
  detailRow={{
    height: 220,
    isExpandable: (row) => row.lines.length > 0,
    render: ({ row, rowKey, collapse }) => (
      <OrderLinesPanel order={row} onClose={collapse} />
    ),
  }}
  onExpandedDetailRowKeysChange={(keys) => save(keys)}
/>

DetailRowOptions<T>:

• 表示: 帯はマスター行の直下・グリッド全幅(3 ペインとも背景を描画)で、カードは中央ペインに position: sticky で置かれ、横スクロールしてもビューポート左端(左固定ペインの右隣)に留まります。幅は中央ペインの可視幅です。展開しても行の順序・view index は変わらず(第 3 の行種は作らない)、後続行が帯の高さぶん下がります。展開時にスクロール位置は動かしません。
• 状態: 展開状態は rowKeyGetter の行キーで保持されるため、ソート / フィルター / 行の追加削除を跨いで同じ行に追従します(フィルターで除外中の行は帯が出ず、復帰すると再表示)。UI 状態で undo/redo・getState() の対象外。永続化は onExpandedDetailRowKeysChange + setDetailRowExpanded() で行います。
• マウント: カードは仮想化の描画窓に載っている間だけマウントされます(スクロールアウトでアンマウント、戻ると再マウント)。カード内で保持したい状態は消費側で rowKey をキーに持ってください。
• イベント境界: カード内のキーボード / クリップボード / 右クリック / ダブルクリック / ドラッグ開始はグリッド本体へ伝播しません(カード内の input で矢印キーを押してもアクティブセルは動かない)。カード内にフォーカスがある間は、グリッド側のフォーカス復帰(編集確定・popover close 後)がフォーカスを奪いません。カード内に別の SpreadsheetGrid をネストしても、外側の自動高さ実測 / 列ヘッダー検索は内側のセルを対象にしません。
• renderCell からの操作(ctx.detail): detailRow 有効時、CellRenderContext に detail: { expanded, expandable, toggle(), setExpanded(bool) } が入ります(無効時は undefined)。showToggleColumn: false と組み合わせて、商品名セルの横などにトグルを自前配置できます。
• 選択 / アクティブセル: 帯はセルではないため選択・アクティブセルの対象外です。帯を跨ぐ範囲選択のハイライトは帯を避けて分割描画されます。
• serverSide(dataSource): 使えますが、(1) クエリ(フィルター / ソート / グローバル)が変わると展開状態はすべて閉じます(結果セットが総入れ替えされ、未ロード行のキーを走査できないため)。(2) 未ロード行の帯は表示されません。
• 上限: 帯は auto-height 行と同じ可変行高ジオメトリで描画するため、rows × rowHeight + 展開中の帯の合計 が 15,000,000px(36px 行で約 41 万行)を超える構成では帯を描画しません(開発時警告。展開状態は保持され、行数を絞ると表示されます)。
• 行グルーピング併用: 展開できるのは leaf 行のみ(グループ行は対象外)。

ラベル行(見出し / 区切り行)(labelRow)

labelRow prop を渡すと、rows の中の特定の行を「見出し(区切り)行」として扱えます。Excel のシートに置く節見出しの行と同じもので、データ行の間に置いたその位置に全幅の帯として描画され、行数には数えません。行の型 T も rows / onRowsChange の型も変わらないため、Excel / CSV 取り込みデータの形そのままで使えます(ガイド)。

行グルーピングとの違い

type Row = { id: string; kind?: 'label'; code: string; name: string; qty: number };

<SpreadsheetGrid
  rows={rows}                       // ラベル行はデータ行と同じ配列に混在させる
  columns={columns}
  rowKeyGetter={(row) => row.id}
  labelRow={{
    isLabelRow: (row) => row.kind === 'label',
    getLabel: (row) => row.name,
    sticky: true,                     // 縦スクロール中も現在セクションの見出しをヘッダー直下に固定
    render: ({ label, sectionRowCount }) => (
      <>
        <strong>{label}</strong>
        <span className="text-gray-500">{sectionRowCount} 件</span>
      </>
    ),
  }}
/>

LabelRowOptions<T>:

• セクション: ラベル行から次のラベル行の直前までを 1 区間とみなします。最初のラベル行より前の行は「ラベル無しの区間」です。
• ソート / フィルター(sortMode): 'section'(既定)= 並べ替えは各セクションの中だけで行い、ラベル行の位置は動かない。フィルターで 0 件になったセクションはラベルごと消える(keepEmptySections で残せる)。'follow' = 全体を並べ替え、ラベル行は「元のセクションの先頭に来るデータ行」の直前に付いて移動する(元から中身の無いセクションのラベルは、続くセクションのラベルの直前に並ぶ。消えるのはフィルターで 0 件になったときだけで、keepEmptySections で残せる)。'hide' = ソート / フィルター中はラベル行を出さない。ソートもフィルターも無いときは 3 モードとも rows の並びそのものです。
• 表示: 帯は 3 ペインとも描き、中身(getLabel の文字列 / render の要素)は中央ペインに position: sticky で置かれ、横スクロールしてもビューポート左端(左固定ペインの右隣)に留まります(展開行カードと同じ機構)。行ヘッダー「#」は空欄で、データ行の行番号はラベル行を飛ばした通し番号になります。既定表示は左のアクセント線 + 太字(トークン --ssg-label-row-bg / --ssg-label-row-text / --ssg-label-row-accent)。
• 操作の対象外: ラベル行はセルを持たないため、セル選択 / 編集 / コピー / クリア / チェックボックス行選択 / ホバー / コンテキストメニューの対象になりません。矢印キー(↑ / ↓)はラベル行に止まらず読み飛ばし、貼り付けはラベル行を飛ばして次のデータ行へ続けます(行は落ちません)。件数表示(bar の Rows: X / Y・行選択件数)はデータ行のみを数えます。範囲選択の塗りはラベル行の上も通過して描かれます(グループ行と同じ)。
• 行ドラッグ併用: データ行はセクションを跨いで移動できます(移動先のセクションに所属が変わる)。ラベル行自体は掴めません。ソート / フィルター中に操作不可になる規則は従来どおりです。
• 展開行併用: 可。ラベル行は展開できません(データ行のみ)。
• serverSide(dataSource): サーバーが getRows の結果にラベル行を含めて返し(totalRowCount にも数える)、isLabelRow で識別します。セクションの並べ替え / sectionRowCount / 縦固定(sticky)/ ラベル行の height はサーバー行モデルでは適用されず、件数表示はサーバー総数のままです。
• エクスポート: 既定では出力に含みません(scope 'raw' でもデータ行として出ません)。exportCsv / getExportData の includeLabelRows: true で 1 行として出力し、getExportData は rowKinds で行種を返します(「Excel / スプレッドシート エクスポート」節のレシピ参照)。コピー(Ctrl/Cmd+C)には含まれません。
• 上限: height を指定した場合は可変行高ジオメトリで描画するため、論理全高が 15,000,000px を超える構成では上書きを諦めて rowHeight に戻ります。

ラベル行の記述子は GridLabelRow<T>({ kind: 'label', row, sourceIndex, label, sectionRowCount })としてバレルから公開されます(LabelRowOptions<T> / LabelRowRenderContext<T> / LabelRowSortMode も同様)。

合計行(totalRow)

totalRow prop で、表の下端に合計行を固定表示します。どの列を何で集計するかは列の aggFunc(行グルーピングと同じ組み込み集計 / カスタム関数)で決め、フィルターをかけると見えている行だけで計算し直します。

const columns: GridColumn<Order>[] = [
  { key: 'product', title: '商品', width: 160 },
  { key: 'qty', title: '数量', width: 90, align: 'right', aggFunc: 'sum' },
  { key: 'price', title: '単価', width: 110, align: 'right', aggFunc: 'avg', valueFormatter: yen },
  { key: 'amount', title: '金額', width: 120, align: 'right', aggFunc: 'sum', valueFormatter: yen },
];

<SpreadsheetGrid rows={rows} columns={columns} totalRow />
// 見出しを変える / 一部の列は値を渡す
<SpreadsheetGrid rows={rows} columns={columns} totalRow={{ label: '総計', values: { product: `${rows.length} 品目` } }} />

TotalRowOptions<T>(totalRow にオブジェクトで渡したとき):

• 集計の対象: フィルター / ソート後のデータ行です。ラベル行(labelRow)は数えず、行グルーピング中は折りたたんだグループの行も数えます。数値の判定は行グルーピングの集計と同じで(数値と数値の文字列だけ)、count は対象の行数です。数値対象が 0 件の sum / avg / min / max は空セルになります。
• 表示: 合計以外の組み込み集計(平均 / 最小 / 最大 / 個数)は値の前に小さく種類を出します。値の整形は列の valueFormatter を使います(グループ行と同じく合計行に元の行は無いため row は undefined。row を読む formatter の列は renderCell か values で整形してください)。文字列(カスタム集計 / values の文字列)はそのまま出します。count の件数と valueFormatter の無い列の数値は、下部バーの選択範囲の集計と同じ書式(桁区切りあり・小数は 4 桁まで・浮動小数の誤差は丸める)です。列の renderCell / cellClassName は合計行には使いません(行データが無いため)。中身の差し替えは totalRow.renderCell で行います。列幅の自動調整(列メニュー / 境界のダブルクリック / すべての列の自動調整)は合計行の表示(種類 + 値)も収まる幅にし、列幅で切れた値はポインタを乗せるとツールチップで全体を出します。
• 位置: 縦スクロール中は表の下端に留まり、行が少ないときは最後の行の直後に来ます。横スクロールと左右の固定列には通常の行と同じく付いていきます。最後までスクロールすると最終行は合計行のすぐ上に来て、キーボード操作 / scrollToRow で行を見せるときも合計行の裏に隠しません(最後までスクロールした状態で合計行を出したときも最終行を見せたまま)。範囲選択 / 行ドラッグ / フィルハンドルのドラッグで合計行の上へポインタを動かすと、本体の見えている最後の行として扱い、自動スクロールは合計行の上端から始まります。
• 表示専用: セル選択 / 編集 / 貼り付け / コピー / クリア / 行選択 / 右クリックメニューの対象外です(押しても選択は動きません)。件数表示(bar の Rows)やビュー行 index には数えません。
• エクスポート: 既定では含みません。exportCsv / getExportData の includeTotalRow: true で、scope 'view' のときだけ末尾に 1 行出します(値は生値。見出しは先頭列に値が無いときだけ先頭列へ)。getExportData は rowKinds の 'total' で判別できます。
• serverSide(dataSource): 全件を持たないため計算しません。サーバーで集計した値を values で渡してください。
• アクセシビリティ: 表の最後の行(role="row")として読み上げます(aria-rowcount に 1 行足す)。
• 見た目: 行は .ssg-total-row、セルは .ssg-body-cell.ssg-total-cell、種類の見出しは .ssg-total-caption。トークン --ssg-total-row-bg / --ssg-total-row-text / --ssg-total-row-border(上辺の区切り線)。

行ドラッグ並び替え(enableRowDrag)

enableRowDrag を付けると、先頭のハンドル列(⋮⋮)を掴んで行を上下へ動かせます(AG Grid の managed row dragging 相当)。並び替えの結果は通常の編集と同じく onRowsChange で新配列として返るため、消費側は rows を差し替えるだけです。

const [rows, setRows] = useState(initialRows);

<SpreadsheetGrid
  rows={rows}
  onRowsChange={setRows}
  columns={columns}
  rowKeyGetter={(row) => row.id}
  enableRowDrag
  isRowDraggable={(row) => !row.locked}
  onRowMove={({ rowKey, fromIndex, toIndex, rows }) => saveOrder(rows)}
/>

• 操作: ハンドルを押して上下へドラッグすると、挿入位置に水平のガイド線が出ます。ドロップで確定し、影響行が新しい位置へスライドします(prefers-reduced-motion では即時)。グリッドの枠外で離す / Escape でキャンセルします。上下端に近づくと自動スクロールします(仮想化された画面外の行へも運べます)。
• ゴースト: ドラッグ中はポインタ追従のピルに、先頭の(合成列でない)表示列の表示値(valueFormatter 適用後)を出します。空なら「行 N」。
• データ契約: 確定時は「1 要素を移動した新配列」(未変更行は参照共有)を onRowsChange に渡し、その直後に onRowMove を呼びます。掴んだ行の直上 / 直下(動かない位置)で離した場合はどちらも呼ばれません。履歴ラッパ経由のため Ctrl/Cmd+Z / undo() で戻せます。
• 有効条件: clientSide(rows + onRowsChange)専用です。dataSource(serverSide)/ 行グルーピング中 / onRowsChange 未指定ではハンドル列を挿入しません。readOnly は関係しません(並び替えはセル編集ではないため)。読み取り専用時に並べ替えも止めたい場合は enableRowDrag={!readOnly} を渡します。
• ソート / フィルター中: 表示順と rows の順が一致しないため、ハンドルは淡色(.ssg-row-drag-handle--disabled)+ 理由のツールチップになり操作できません(列はそのまま残るのでレイアウトは跳ねません)。解除すると復帰します。
• 展開行との併用: 展開中のマスター行は詳細パネルごと一緒に移動します。ドロップ位置の判定は詳細パネルの高さ込みで、パネルの上は「マスター行の下」として扱います。
• ハンドル列: 合成列のため、列メニュー / ソート / 列 DnD / autoSize / エクスポート / 並び替え管理パネルの対象外です。左固定列があるときは左固定側に、展開行トグル列よりさらに先頭に入ります。
• 命令的 API: moveRow(rowKey, toIndex) は表示状態(ソート / フィルター)に関わらず元配列上で移動します(onRowsChange → onRowMove の順)。
• 表示方式: rowDragMotion: 'live' で、ドラッグ中に掴んだ行がポインタに追従し、周囲の行がリアルタイムに退避する見せ方になります(スロット解決は 'ghost' と共通)。
• スタイル: .ssg-row-drag-handle(+ --disabled)/ .ssg-body-cell--row-drag-handle / .ssg-row-drop-indicator / ドラッグ中の行 .ssg-body-row[data-ssg-row-dragging]。色はトークン(--ssg-drop-indicator / --ssg-glyph-* / --ssg-ghost-*)です。

IME オンのままの直接入力(imeDirectInput)

既定では、セルを選んだ状態で IME をオンにしたまま文字を打つと、変換が始まらず打った文字が失われます(編集していないあいだのフォーカスが入力欄ではない要素にあるため。F2 / Enter / ダブルクリックで編集を始めた後の IME は問題ありません)。imeDirectInput を true にすると、Excel / SPREAD と同じく IME オンのまま打ち始められます。

<SpreadsheetGrid rows={rows} columns={columns} onRowsChange={setRows} imeDirectInput />

• 動き: 編集していないあいだ、グリッドのフォーカスはアクティブセルの上の透明な入力欄(入力受け)にあります。日本語を打ち始めると変換中の文字がセルの上にエディタと同じ見た目で表示され、変換を確定(Enter / 候補の確定)すると確定した文字列を初期値に編集が始まります。そのまま続けて入力でき、もう一度 Enter でセルを確定して移動します(移動先は editorEnterMove)。変換を取り消した(Escape で空にした)ときは編集を始めません。
• 対象: text エディタ(editor 未指定 / type: 'text')と number エディタの編集可能なデータセル。select / date / checkbox / custom の列、読み取り専用セル、グループ行 / ラベル行、SSRM の未ロード行では変換を捨てます(従来どおり何も入りません)。
• number 列: 変換を確定すると、全角の数字・符号・小数点・3 桁区切りを半角に直した値で編集が始まります(「１２．５」→ 12.5、「ー５」→ -5、「１，２３４」→ 1234。句読点の設定が「、。」の IME で入る「１２。５」も 12.5)。かなや漢字など数値として読めない変換は捨てます。IME そのものはオフにしません(ブラウザからは IME をオンへ戻せないため。Chrome / Edge は CSS の ime-mode にも対応していません)。
• 変わらないもの: 矢印 / Tab / Enter / F2 / Delete / Ctrl+C / 貼り付け / undo などのキー操作、IME を使わない文字キーでの編集開始(その 1 文字が初期値)、端の列の Tab でグリッド外へ出る動き。変換中のキー(候補の選択など)はグリッドでは扱いません。
• 変換中にクリックしたとき: 変換中に別のセルやグリッド外をクリックすると、変換中の文字は入力されません(確定してから移動してください)。クリックした先のフォーカスは奪いません。
• フォーカス: 有効中は document.activeElement が入力受け(input[data-ssg-ime-input])になります。グリッドにフォーカスがあるかを gridElement.contains(document.activeElement) で判定している場合は従来どおり動きますが、「入力欄にフォーカスがあるときは無効」になるショートカット(Mantine の useHotkeys の既定など)はグリッド上で効かなくなります。これが既定 OFF の理由です。
• タッチが主のデバイス(スマホ / タブレット): 入力受けに inputmode="none" を付け、セルのタップで仮想キーボードが開かないようにしています(従来どおり)。
• 確認状況: Chromium(Chrome / Edge / WebView2 と同じエンジン)で、DevTools Protocol の変換イベント(Input.imeSetComposition / Input.insertText)を使って確認しています。OS の IME そのもの(Windows の MS-IME など)での最終確認は実機で行ってください。

モーション(motion)

グリッドの動き(アクティブセル枠の追従、ポップオーバーの出現、ソート時の行移動、読み込み中のシマー等)は motion prop で一括制御する(既定 'auto')。

• 実装は CSS トークン: --ssg-motion-fast(140ms)/ --ssg-motion-base(260ms)/ --ssg-motion-slow(600ms)/ --ssg-motion-ease(イージング)。各効果はこのトークンだけを参照する。'off' では root と全ポータル root・ドラッグゴースト・ツールチップに .ssg-motion-off が付き、継続時間が 0 になる。
• 速さは利用側のトークン上書きで変えられる(.ssg-root { --ssg-motion-base: 180ms; })。.ssg-motion-off の値は :where(特異度 0)で定義しているため、停止中でも特定の効果だけ戻すことができる。
• SSR では 'auto' はいったん 'on' で描画し、ハイドレーション後にクライアント側で再解決する(theme='auto' と同じ)。
• 従来 prefers-reduced-motion を直接見ていた効果(ツールパネルのフラッシュ / フィルター候補のスピナー / スクロール位置インジケーターのフェード)も motion の実効値で判定するようになった('auto' では従来と同じ)。

効果の一覧

セル内検索(find)

find を付けると、グリッドにフォーカスがある状態の Ctrl/Cmd+F(または handle.openFind())でグリッド右上に検索バーが出る(既定は無効)。「絞り込み(フィルター)」とは別に、行を消さずに場所を探す操作で、ブラウザの Ctrl+F では探せない仮想化された行も対象になる。

<SpreadsheetGrid find ... />
// find={{ shortcut: false, caseSensitive: true }}

• 対象: ビュー行(フィルター / ソート適用後)× 可視列の表示文字列(valueFormatter 適用後 = 画面に見えている文字)。renderCell の列も表示文字列(valueFormatter または String(value))で検索されるが、<mark> の強調は既定セルだけ(カレントへの移動は同じ)。
• 走査: 時間分割(logic/chunkedLoop。1 チャンク 10ms)で入力・描画を止めない。走査中は件数が「検索中…」になる。クエリ / 大文字小文字 / rows(編集・差し替え)/ ソート / フィルター / 列が変わると再走査し、同じヒットが残っていればカレントを保つ(移動はしない)。
• 順送り: Enter / ↓ で次、Shift+Enter / ↑ で前(循環)。カレントのヒットへはクリック相当の単一選択 + 可視化スクロール(selectCell(row, col, { scrollIntoView: true }) と同じ)。クエリを打ち直すと先頭のヒットへ移動する。
• 閉じる: Esc / × でクエリとヒットが消え、フォーカスはグリッド本体へ戻る。find を false にすると開いていても閉じる。
• ヒット数の上限: 10,000 件で打ち切り(件数表示に +)。SSRM はロード済み範囲だけが対象(未ロード行は読み飛ばす)。
• スタイル: ヒットは .ssg-find-mark、カレントは .ssg-find-mark--current(トークン --ssg-find-mark-bg / --ssg-find-mark-current-bg)。バーは classNames.findBar。
• ショートカット: Ctrl/Cmd+F の横取りはグリッド本体にフォーカスがあるときだけ(フィルター入力 / エディタ内では効かない)。shortcut: false でブラウザ標準の検索に譲り、handle.openFind() だけで開く運用もできる。

キーボード操作

グリッド本体フォーカス中(編集中でない)の操作一覧。フィルター入力等のフォーム要素にフォーカス中は無効。

編集エディタ内: Enter = 確定して下へ(移動先は editorEnterMove で変更可。既定 'down')、Tab / Shift+Tab = 確定して右 / 左へ、Escape = キャンセル、フォーカスアウト = 確定。IME 変換中(isComposing)の Enter / Escape / Tab は IME の操作としてのみ扱われ、セル編集の確定 / キャンセルには使われない。

確定 / キャンセル後のフォーカス: Enter / Tab / Escape で確定・キャンセルしたときはグリッドへ戻る(imeDirectInput 有効時は入力受けへ)。フォーカスアウトで確定したときは、フォーカスの移り先がグリッド外の要素(グリッドの上のフォームの入力欄 / 上部バーのグローバルフィルター等)ならそこに残し、グリッドへ奪い返さない(クリックした入力欄へそのまま入力できる)。グリッド内の別のセルをクリックしたとき・移り先がないとき(フォーカスを取らない余白のクリック等)はグリッドへ戻る。展開行カード内のフォーカスは奪わない。

確定後のアクティブセル: 方向なしの確定(フォーカスアウト / select の候補クリック / custom エディタの commit(value) / editorEnterMove: 'none' の Enter)の後は、編集していたセルが単一選択になる。ただし確定のきっかけがグリッド内の別のセルや行・列ヘッダーの押下だった場合は、押した操作(そのセルのアクティブ化 / ドラッグでの範囲選択 / 行・列の選択)を優先し、編集していたセルへ戻さない。Enter / Tab など方向付きの確定は従来どおり隣のセルへ移る。

IME オンのまま(編集していないセルで)日本語を打ち始めるには imeDirectInput を有効にする(既定 OFF。無効時は変換が始まらず最初の入力が失われる。「IME オンのままの直接入力」節)。

確定後の移動先は「確定を反映した再レンダー後」の行数・列数でクランプされる。このため、onRowsChange で末尾に空行を追加する消費側(Excel 的な入力グリッドの定石パターン)では、最終行の Enter 確定で「増えた行」へそのまま移動できる。行が増えない場合は従来どおり最終行に留まる。

アクセシビリティ

WAI-ARIA の grid パターンに沿って、表・行・セルに役割と状態を付けている(支援技術向け。ariaLabel で表の名前を付けられる)。

• 仮想化で描画していない行・列は DOM に無いため、表全体の中の位置は aria-rowindex / aria-colindex / aria-rowcount / aria-colcount で伝える。
• 制約: 固定列(pinned)があると、1 つの行が左 / 中央 / 右のペインごとの role="row" に分かれる(どれも同じ aria-rowindex。読み上げの順は DOM 順でペインごと)。展開行(detailRow)の帯は aria-rowindex を持たない(データ行の番号をずらさないため)。縦固定で複製したラベル行(labelRow.sticky)は aria-hidden で、中のボタン等は tabindex="-1"(Tab で止まらない。マウスでは押せる。本物のラベル行はそのまま)。

パーツ別スロット(classNames / GridSlotProps)

className 系の受け口(classNames.* / cellClassName / getRowClassName / detailRow.className / labelRow.className / totalRow.className)はすべて GridSlotProps を受ける(バレルから GridSlotProps / GridClassNames を公開)。

type GridSlotProps = string | { className?: string; style?: CSSProperties };

• 文字列は従来どおり class として付与される。オブジェクト形は StyleX の stylex.props(...) の戻り値と同形で、そのまま渡せる(StyleX の動的スタイルは style 側の CSS 変数で届くため、この形が必要)。
• style は当該パーツのルート要素へインラインで付与される。グリッドが位置決めに使う座標 / 寸法(left / top / width / height / transform 等)はグリッド側が後勝ちで上書きするため、レイアウトは壊せない。
• インライン style は状態クラス(選択 / ホバー等の背景)にも勝つ。状態で切り替えたい装飾は className 側で行う。
• classNames はレンダー毎に新しいオブジェクトを渡してもよい(内容の署名で memo され、行 / ヘッダーの再レンダーは増えない)。getRowClassName が返す style も内容比較で memo される。
• tooltip / dragGhost は命令的 DOM(document.body 直下)のため、style の数値は単位なしのまま設定される(px が必要な値は '12px' のように文字列で)。

StyleX との併用

import * as stylex from '@stylexjs/stylex';
import { vars } from './tokens.stylex';   // stylex.defineVars({ accent: '#7c3aed', danger: '#dc2626' })

const s = stylex.create({
  grid: { '--ssg-accent': vars.accent, borderRadius: 8 },   // グリッドのトークンへ橋渡し
  cell: { fontVariantNumeric: 'tabular-nums' },
  negative: { color: vars.danger },
  width: (w: number) => ({ maxWidth: w }),                  // 動的スタイル(style 側で届く)
});

<SpreadsheetGrid
  classNames={{ root: stylex.props(s.grid), bodyCell: stylex.props(s.cell) }}
  columns={[{ key: 'amount', title: '金額', cellClassName: (ctx) => stylex.props(typeof ctx.value === 'number' && ctx.value < 0 && s.negative, s.width(120)) }]}
/>

• StyleX は子孫セレクタを書けない(要素自身のクラスでしか装飾できない)ため、上記スロットに無い内部要素(ポップオーバー内のボタン / 入力欄等)はデザイントークン(--ssg-*)で調整する。
• StyleX の atomic クラスとグリッドの基底クラスは同じ特異度 (0,1,0)。同じプロパティは後に読み込まれた方が勝つため、グリッド CSS を先に・StyleX の出力 CSS を後に読み込むか、style.layer.css(@layer ssg-base)を使う。StyleX 側で useLayers を有効にしている場合は、未レイヤーのグリッド CSS がレイヤー内に常に勝つため style.layer.css が必須。

スタイリング用の状態クラス(公開契約)

cellClassName / getRowClassName の返すクラスは、下記の内部付与クラスと連結セレクタで組み合わせて使える(例: .ssg-body-cell.my-diff で基底に勝たせ、.ssg-body-cell.my-diff.ssg-body-cell--row-hovered でホバー時色を切替)。以下は公開契約とし、変更時は breaking 扱いにする。

※上記以外の ssg-* クラス(内部構造クラス)は非公開の実装詳細で、予告なく変わり得る。セレクタで依存しないこと。

補助型(props で参照される shape)

• GridRowKey = string | number
• GridColumnPinned = 'left' | 'right'
• GridSelectFilterOption = { label: string; value: string }
• CellRenderContext<T> = { row, rowIndex, sourceRowIndex, rowKey, colIndex, value, column, isActive, isSelected, isEditing, readOnly, setValue, detail? }
  • setValue は readOnly / canEditCell を見ずに書き込む(検証 validate は通る)。読み取り専用時に無効化したい場合は readOnly を見て呼び分ける。readOnly 中は undo が無効なため、この書き込みは取り消せない。
  • detail?: CellDetailContext = { expanded, expandable, toggle, setExpanded } は detailRow prop 有効時のみ定義(「展開行(Master/Detail)」節)。
• DetailRowOptions<T> / DetailRowRenderContext<T> = { row, rowKey, rowIndex, sourceRowIndex, collapse } / CellDetailContext(展開行。バレルから公開)
• LabelRowOptions<T> / LabelRowRenderContext<T> = { row, rowKey, rowIndex, sourceRowIndex, label, sectionRowCount } / GridLabelRow<T> = { kind: 'label', row, sourceIndex, label, sectionRowCount } / LabelRowSortMode = 'section' | 'follow' | 'hide'(ラベル行。バレルから公開。「ラベル行(見出し / 区切り行)」節)
• FillHandleOptions<T> = { getFillValue? } / GridFillValueParams<T> = { column, row, rowIndex, sourceValues, index, direction, kind, defaultValue } / GridFillDirection = 'down' | 'up' | 'right' | 'left' / GridFillKind = 'series' | 'copy'(フィルハンドル。バレルから公開。「フィルハンドル」節)
• RowDragContext = { rowKey, sourceRowIndex }(isRowDraggable の第 2 引数)/ RowMoveParams<T> = { rowKey, fromIndex, toIndex, rows }(onRowMove の引数。いずれもバレルから公開)
• GridCellRef<T> = { row, rowKey, rowIndex, sourceRowIndex, column, columnKey, colIndex, value }(onActiveCellChange の引数)/ GridCellEventParams<T> = GridCellRef<T> & { event: MouseEvent }(onCellClick の引数。event は DOM 標準の MouseEvent)/ GridCellDoubleClickParams<T> = GridCellEventParams<T> & { preventDefault(): void }(onCellDoubleClick の引数。タッチのダブルタップでは event は離したときの PointerEvent)。いずれもバレルから公開。index の基準は CellStyleContext と同じ(「セル操作の通知」節)。
• CellStyleContext<T> = 上記から setValue を除いた読み取り専用版(cellClassName 関数へ渡る)。バレル(index.ts)から公開(import type { CellStyleContext } from '@ishibashi0112/spreadsheet-grid')
  • rowIndex はビュー行 index(ソート / フィルター適用後の表示位置)、sourceRowIndex は元 rows の index、rowKey は行キー(rowKeyGetter 由来、既定は source index)。ソート / フィルター ON の画面で「エラー行 index の集合」など source 基準のデータと突き合わせるときは sourceRowIndex / rowKey を使う(getInvalidCells() の返す sourceRowIndex / rowKey と同一基準)。serverSide では view 順が正準のため sourceRowIndex は view index と同値。
• CanEditCellContext = { sourceRowIndex, rowKey }(canEditCell の第 5 引数。基準は CellStyleContext と同一。バレルから公開)
• RowStyleContext<T> = { row, rowIndex, sourceRowIndex, rowKey, isSelected }(getRowClassName の第 3 引数。バレルから公開)
• GridSlotProps = string | { className?: string; style?: CSSProperties }(classNames.* / cellClassName / getRowClassName / detailRow.className の値。GridClassNames と共にバレルから公開)
• GridFrameworkTypes = { node: unknown; style: object } / ReactGridTypes = { node: ReactNode; style: CSSProperties }(バレルから公開)。公開型の本体は React 非依存の core(描画ノード / style の型を束ね型 F で受ける)で、利用者が普段使う GridColumn<T> 等は core を ReactGridTypes で固定したエイリアス。型引数の数・名前は従来どおりで、通常は意識不要。
  • rowIndex / sourceRowIndex / rowKey の基準は CellStyleContext と同一。isSelected はチェックボックス行選択(enableRowSelection)の選択状態(範囲選択とは別)。グループ行(grouping 有効時)は専用描画のため getRowClassName の対象外。
• GridScrollPosition = { top: number; left: number }(getScrollPosition の返り値 / setScrollPosition の基準)
• GridScrollEventParams = { top: number; left: number; source: 'user' | 'api' }(onScroll の引数。source の意味は props 表の onScroll 行を参照)
• HeaderRenderContext<T> = { colIndex, width, column, filterValue?, isFiltered? }
• SpreadsheetGridSlotContext<T> = { rows, filteredRows, columns, visibleColumns, globalFilterText, columnFilterValues, sortState, setGlobalFilterText, activeCell, selection, derivedSummary, globalFilterStatus, globalFilterProgress, selectionAggregates }
  • derivedSummary は SpreadsheetGridDerivedSummary(行/列/フィルター/ソートの summary 文字列・選択統計などを内包)。helper を import せずトップ/ボトムバーで使える。
  • 開発ビルドでの注意: ctx や rows / filteredRows を子コンポーネントの props にそのまま渡す(<MyBar ctx={ctx} /> / <MyBar {...ctx} /> / <MyBar rows={ctx.filteredRows} />)と、React 19.2 以降の開発ビルドは Performance Track 向けに props の差分を取るため大きな配列を走査し、100 万行規模ではソート 1 回に数十秒かかることがある。子へは使う値だけを渡す(件数なら ctx.filteredRows.length や derivedSummary)。本番ビルドには影響しない。内蔵のトップ / ボトムバーも必要な値だけを受け取る。
  • globalFilterStatus: GlobalFilterStatus('idle' | 'filtering' | 'ready')/ globalFilterProgress: number(0..1)。グローバルテキストフィルタは行数が大きい(しきい値 50,000 行・条件は rows.length > 50000)とき、入力を主スレッドを塞がず時間分割で適用する。適用中は status='filtering'・progress が進捗(0..1)になる。空/無効は 'idle'、確定は 'ready'(progress=1)。50,000 行以下は同期適用のため即 'ready'('filtering' を経由しない)。ローディング表示はグリッドが本体に重ねる組み込み overlay(autosize の計測中 overlay と同じ作法)で行うため、トップバーやカスタム UI 側で扱う必要は通常ない。 この 2 値は、入力の無効化や独自インジケータなどカスタム UI を出したい場合の参照用に公開している。serverSide では基本 'idle' / 'ready'(取得中表示は行スケルトンが担当)。
  • selectionAggregates?: GridSelectionAggregates | null(グリッドは常に入れる)。2 セル以上を選んでいるときの選択範囲の集計 { status: 'computing' | 'ready'; progress; cellCount; count; numericCount; sum; average; min; max; partial }(count = 空でないセル数、numericCount = 数値として数えたセル数、数値が無ければ sum / average / min / max は undefined、partial = SSRM で未読み込みの行を飛ばした)。1 セル以下の選択 / showSelectionAggregates={false} / 出す先が無い(ボトムバー非表示で、renderTopBar も無い)ときは null。走査セル数が 50,000 を超える選択は時間分割で計算し、その間は status: 'computing'(値は未確定、progress は 0..1 を 5% 刻み)。同じ選択のまま値だけ変わったときは、計算し直すあいだも前の結果(status: 'ready')のままで、終われば差し替わる。既定ボトムバーは平均 / データの個数 / 合計を出す(最小 / 最大はこの値でだけ参照できる)。