はじめに

SpreadsheetGrid(@ishibashi0112/spreadsheet-grid)は、React 19 + TypeScript 製の仮想化データグリッドです。サーバーサイド行モデル(書き戻し付き)・行グルーピングと集計・Master/Detail・範囲選択とクリップボードなど、他社グリッドでは商用ライセンスの機能を MIT で提供します。スクロール空間の仮想化により 約 100 万行 までのデータを軽快に扱え、IME に強い Excel ライクなセル編集を備えています。

※ このデモは実際のライブラリが動いています。セルをダブルクリックすると編集できます。

主な特徴

• 仮想化 — 行・列ともに仮想化し、〜100 万行のデータをスムーズにスクロール
• 3 ペイン固定列 — 左右の列ピン留め(sticky ベース)
• ソート / フィルター — 列ごとのフィルター(text / number / date / select / set / custom)+ グローバルフィルター、フィルター管理パネル付き
• セル編集 — エディタ種別(text / number / select / date / checkbox / custom)、IME 対応(変換確定の Enter で誤コミットしない)、バリデーション(mark / reject)
• クリップボード — 範囲選択、コピー & ペースト、Delete / Backspace クリア
• フィルハンドル — fillHandle で選択範囲の右下の四角を引き、連続データ(数値 / 日付 / 曜日 / 末尾の数)かコピーで埋める。埋めたあとに選び直せる(Excel のオートフィル)
• undo / redo — Ctrl/Cmd+Z 系ショートカット + 命令的 API
• 行グルーピング + 集計 — rowGroup / aggFunc、自動グループ列、開閉 UI
• 合計行 — totalRow で表の下端に合計行を固定。列の aggFunc で集計し、フィルター後の行で計算し直す
• 選択範囲の集計 — 2 セル以上を選ぶと下部バーに平均 / データの個数 / 合計(Excel のステータスバーと同じ)
• 展開行(Master/Detail) — detailRow で行の直下に任意の React UI(サブグリッド / フォーム)を開く。行順を変えない全幅カード
• ラベル行(見出し / 区切り行) — labelRow で rows に混在させた見出し行を全幅の帯で描画。行数に数えず、ソートはセクション内に閉じ、sticky で見出しをヘッダー直下に固定
• 行ドラッグ並び替え — enableRowDrag でハンドル列(⋮⋮)を掴んで行を上下へ移動。onRowsChange に新配列が返り undo 対象
• サーバーサイド行モデル(SSRM) — クエリ転送(フィルター / ソート)、ソフトリフレッシュ、ロードエラーのリトライ UI、updateRows による書き戻し(楽観更新 + 失敗時ロールバック)
• CSV / Excel エクスポート — 組み込み CSV + ライブラリ非依存の getExportData()
• モーション — motion prop で一括制御(OS の「視差効果を減らす」を尊重)。アクティブセル枠の追従、ポップオーバーの出現、ソート / グループ開閉での行の移動、コピー範囲の動く点線、SSRM 書き戻しのセル単位の保存状態。opt-in でクロスヘア / 変更セルのフラッシュ / 行・列ドラッグの live 退避
• セル内検索 — find で Ctrl/Cmd+F の検索バー。仮想化された全行のヒットを強調して順送り(行は消さない)
• 条件付き書式 — column.conditionalFormat でデータバー / カラースケール / 状態チップ。min / max はビュー行から自動集計
• テーマ — CSS カスタムプロパティ(--ssg-*)、ダークテーマ(light / dark / auto)、テーマビルダーで CSS 変数を書き出し
• 共存前提の CSS 設計 — Tailwind(v3 / v4)・Mantine・HeroUI と衝突しない
• TypeScript ファースト — 完全な型定義、コントロールドな API

対応環境

• react / react-dom >= 19(peer dependencies)
• ランタイム依存は @tanstack/virtual-core のみ(自動でインストールされます)
• SSR(Next.js 等)でのサーバーレンダリングに対応