@ishibashi0112/spreadsheet-grid 0.16.0 → 0.18.0

package/README.md

@@ -18,14 +18,14 @@ A high-performance, virtualized spreadsheet / data grid for **React 19**, writte
 - Sorting, per-column filters (`text` / `number` / `date` / `select` / `set` / `custom`), and a global filter.
 - In-cell editing and clipboard copy / paste, with range selection, keyboard navigation, and Delete / Backspace to clear selected cells. Cell editing is IME-aware (composing Enter never commits the cell).
 - Built-in cell editor types via `column.editor` — `text` (default), `number` (`min` / `max` / `step`), `select` (dropdown with keyboard navigation & type-ahead; static or per-row options), `date` (native date picker), `checkbox` (direct toggle by click / Space, no edit session, custom checked/unchecked value mapping), and `custom` (render your own editor with `ctx.commit` / `ctx.cancel`; committing a non-string value bypasses parsing). Built-in editors auto-supply a default string→value parser (an explicit `parseClipboardValue` always wins) so paste and clear stay type-consistent.
-- Cell validation via `column.validate` — default `'mark'` mode accepts the value but flags the cell (background + corner marker + hover tooltip message, derived at render time so it always matches `rows`, including after undo or external replacement); opt-in `'reject'` mode (`validationMode: 'reject'`) refuses invalid writes: the editor keeps editing with an inline error bubble, paste / clear skip the offending cells. `getInvalidCells()` on the imperative handle scans all rows for a pre-save check.
+- Cell validation via `column.validate` — default `'mark'` mode accepts the value but flags the cell (background + corner marker + hover tooltip message, derived at render time so it always matches `rows`, including after undo or external replacement); opt-in `'reject'` mode (`validationMode: 'reject'`) refuses invalid writes: the editor keeps editing with an inline error bubble, paste / clear skip the offending cells. `getInvalidCells()` on the imperative handle scans all rows for a pre-save check. Mark visibility is controlled declaratively with the `showValidationMarks` prop (default `true`) — flip it from state to show marks only on submit; `getInvalidCells()` and `'reject'` keep working regardless.
 - Undo / redo for grid edits (cell edits, paste, clear) — `Ctrl/Cmd+Z`, `Ctrl/Cmd+Shift+Z` / `Ctrl/Cmd+Y`, plus `undo()` / `redo()` / `canUndo()` / `canRedo()` on the imperative handle and an `onUndoRedoStateChange` callback for toolbars. Restores the edited cell's active cell & selection and scrolls it back into view. History is snapshot-based with structural sharing, capped by `undoHistoryLimit` (default 100), and clears automatically when `rows` is replaced externally (client-side row model only).
 - Optional auto-height rows for wrapped, variable-height content.
 - Auto-fit column widths to content on data load — `autoSizeColumns="onMount"` (once, on first data) or `"onDataChange"` (every time `rows` changes, e.g. after a form submit). Same engine as the column menu's "Autosize All Columns"; opt individual columns out with `suppressAutoSize`.
 - Full-text tooltip on truncated cells — `showCellOverflowTooltip` shows the full value on hover, but only when the cell is actually clipped (…).
 - Japanese-aware line wrapping — per-column `wordBreak` / `lineBreak`, including `wordBreak: 'auto-phrase'` for phrase-based breaks on Chromium (BudouX). Cross-browser BudouX recipe in the API reference.
 - External height control via `height` / `maxHeight` (e.g. `height="100%"` to follow the parent's height).
-- Both **client-side** (`rows`) and **server-side** (`dataSource`, SSRM) row models.
+- Both **client-side** (`rows`) and **server-side** (`dataSource`, SSRM) row models — server-side includes query forwarding (filter / sort / global filter), soft refresh (`refreshServerSide()`), load-error retry UI, and cell-edit write-back via `dataSource.updateRows` with optimistic updates and automatic rollback on failure.
 - Themeable with CSS custom properties (`--ssg-*`, defined at zero specificity so your overrides always win). Base styles are plain unlayered CSS with single-class specificity, so they survive CSS resets such as Tailwind Preflight; a cascade-layers variant (`style.layer.css`) is also shipped. `className` / `classNames` slots are provided.
 - Styled tooltips out of the box — action hints and truncated-text previews use a custom dark-chip tooltip (no browser-default `title` look). Add `data-ssg-tooltip="text"` to your own elements (custom cells, headers) to get the same tooltip; colors are themeable via `--ssg-tooltip-*` tokens.
 - Built-in dark theme — `theme="light" | "dark" | "auto"` switches the grid, every popover / panel / menu, the drag ghost and tooltips through a single token preset. `"auto"` follows `prefers-color-scheme`; with class-based dark frameworks (Mantine / HeroUI / Tailwind) pass your resolved color scheme instead.
@@ -162,6 +162,8 @@ const invalid = gridRef.current?.getInvalidCells()
 // -> [{ rowKey, sourceRowIndex, columnKey, message }, ...]
 ```
 
+Marks are shown in real time by default. For the classic "validate on submit" flow, keep the rules on the columns and toggle mark visibility from state — `showValidationMarks={showErrors}` (default `true`). `getInvalidCells()` and `'reject'` are unaffected by the toggle. See the recipe in [`API_REFERENCE.md`](./src/components/spreadsheet-grid/API_REFERENCE.md).
+
 ## Sizing
 
 By default the grid caps its height at `480px` (`max-height`) and scrolls when the content is taller. Pass `height` to take explicit control — use `height="100%"` to follow the parent's height, or a pixel value:
@@ -220,11 +222,15 @@ Pass a `dataSource` instead of `rows` to switch to server-side mode. The grid ke
       const { rows, totalRowCount } = await fetchPage({ startIndex, endIndex, query, signal })
       return { rows, totalRowCount }
     },
+    // Optional: enables cell editing in server-side mode (optimistic update + rollback on failure).
+    async updateRows({ updates }) {
+      await patchRows(updates) // updates: [{ rowKey, rowIndex, row, previousRow, changes }]
+    },
   }}
 />
 ```
 
-Sorting, column filters, and the global filter stay enabled and are forwarded to the server through `query`. See the [API reference](./src/components/spreadsheet-grid/API_REFERENCE.md) for the full `getRows` contract, the filter wire format, and `serverSideRefreshToken`.
+Sorting, column filters, and the global filter stay enabled and are forwarded to the server through `query`. Cell edits (editor commit / paste / Delete-clear / checkbox) are written back through `updateRows` with optimistic updates — the grid rolls the cells back and shows a dismissible error bar if the write fails (`onServerSideWriteError` fires for toasts/logging). Without `updateRows`, server-side cells are read-only. Row add/remove has no write-back API; apply it on the server and call `refreshServerSide()`. See the [API reference](./src/components/spreadsheet-grid/API_REFERENCE.md) for the full `getRows` / `updateRows` contracts, the filter wire format, and `serverSideRefreshToken`.
 
 ## Styling & theming
 
@@ -299,14 +305,14 @@ The full prop and type reference lives in [`src/components/spreadsheet-grid/API_
 - ソート、列ごとのフィルター（`text` / `number` / `date` / `select` / `set` / `custom`）、グローバルフィルター。
 - セル内編集とクリップボードのコピー／貼り付け、範囲選択、キーボード操作、Delete / Backspace による選択セルのクリア。セル編集は IME 対応（変換確定の Enter でセルが確定されない）。
 - `column.editor` による組み込みエディタ種別 — `text`（既定）/ `number`（`min` / `max` / `step`）/ `select`（キーボード操作・タイプアヘッド付きドロップダウン。候補は静的配列 or 行依存関数）/ `date`（ネイティブ日付ピッカー）/ `checkbox`（クリック / Space の直接トグル。編集セッションなし、checked/unchecked の値マッピング可）/ `custom`（`ctx.commit` / `ctx.cancel` で自作エディタを差し込み。非 string の commit はパースをバイパス）。組み込みエディタは「文字列 → 値」の既定パーサを自動供給し（明示の `parseClipboardValue` が常に優先）、貼り付け・クリアでも型が揃います。
-- `column.validate` によるセル検証 — 既定の `'mark'` モードは値を受け入れつつセルへ invalid 表示（背景 + 右上マーカー + ホバーでメッセージ。表示時導出のため undo や外部差し替え後も常に `rows` と整合）。`validationMode: 'reject'` で不正な書き込み自体を拒否（エディタはエラーバブル表示で編集継続、貼り付け / クリアは該当セルのみスキップ）。ハンドルの `getInvalidCells()` で保存前の全行チェックができます。
+- `column.validate` によるセル検証 — 既定の `'mark'` モードは値を受け入れつつセルへ invalid 表示（背景 + 右上マーカー + ホバーでメッセージ。表示時導出のため undo や外部差し替え後も常に `rows` と整合）。`validationMode: 'reject'` で不正な書き込み自体を拒否（エディタはエラーバブル表示で編集継続、貼り付け / クリアは該当セルのみスキップ）。ハンドルの `getInvalidCells()` で保存前の全行チェックができます。マークの表示可否は `showValidationMarks` prop（既定 `true`）で宣言的に切り替えられ、「送信時にだけマークを出す」UX を state 1 つで実現できます（`getInvalidCells()` / `'reject'` は表示状態と無関係に機能）。
 - グリッド編集の undo / redo（セル編集・貼り付け・クリア）— `Ctrl/Cmd+Z`、`Ctrl/Cmd+Shift+Z` / `Ctrl/Cmd+Y` に加え、ハンドルの `undo()` / `redo()` / `canUndo()` / `canRedo()` とツールバー向けの `onUndoRedoStateChange` コールバック。編集時のアクティブセル・選択範囲まで復元し、画面外なら可視位置へスクロールで追従。履歴は構造共有のスナップショット方式で `undoHistoryLimit`（既定 100）まで保持し、`rows` が外部から差し替えられたときは自動破棄（クライアントサイド行モデル専用）。
 - 折り返し・可変行高に対応する auto-height 行（任意）。
 - データ投入時に列幅を内容へ自動フィット — `autoSizeColumns="onMount"`（初回にデータが載った一度きり）/ `"onDataChange"`（`rows` が変わるたび。フォーム送信結果の差し替え等）。列メニュー「すべての列の幅を自動調整」と同一エンジンで、列個別の除外は `suppressAutoSize`。
 - 省略（…）セルの全文ツールチップ — `showCellOverflowTooltip` でホバー時に全文表示（実際にクリップされているセルのみ）。
 - 日本語対応の折り返し — 列ごとの `wordBreak` / `lineBreak`。`wordBreak: 'auto-phrase'` で Chromium（Chrome / Edge）の文節折り返し（BudouX）。クロスブラウザの BudouX レシピは API リファレンス参照。
 - `height` / `maxHeight` によるスクロールコンテナ高さの外部制御（`height="100%"` で親要素の高さに追従）。
-- **クライアントサイド**（`rows`）と**サーバーサイド**（`dataSource`、SSRM）の両行モデル。
+- **クライアントサイド**（`rows`）と**サーバーサイド**（`dataSource`、SSRM）の両行モデル — サーバーサイドはクエリ送出（フィルター / ソート / グローバルフィルター）、ソフトリフレッシュ（`refreshServerSide()`）、取得失敗の再試行 UI に加え、`dataSource.updateRows` によるセル編集の書き戻し（楽観更新 + 失敗時の自動ロールバック）まで対応。
 - CSS カスタムプロパティ（`--ssg-*`。特異度 0 で定義され、利用側の上書きが常に勝ちます）によるテーマ設定。基底スタイルは未レイヤーの単一クラス特異度で、Tailwind Preflight などの CSS リセットに壊されません。カスケードレイヤー版（`style.layer.css`）も同梱。`className` / `classNames` スロットも用意。
 - スタイル付きツールチップを標準装備 — 操作ヒントや切り詰めテキストの全文表示は、ブラウザ標準の `title` ではなくダークチップのカスタムツールチップで表示。利用側の要素(カスタムセルやヘッダー)にも `data-ssg-tooltip="文言"` を付けるだけで同じ見た目になります。配色は `--ssg-tooltip-*` トークンで調整可。
 - ダークテーマを標準装備 — `theme="light" | "dark" | "auto"` で、グリッド本体・全ポップオーバー / パネル / メニュー・ドラッグゴースト・ツールチップをトークンプリセット 1 つで一括切替。`"auto"` は `prefers-color-scheme` に追従(Mantine / HeroUI / Tailwind のクラスベース dark 運用では、解決済みのカラースキームを渡す使い方を推奨)。
@@ -443,6 +449,8 @@ const invalid = gridRef.current?.getInvalidCells()
 // -> [{ rowKey, sourceRowIndex, columnKey, message }, ...]
 ```
 
+マークは既定でリアルタイム表示です。「送信時にまとめて検証」の定番フローは、ルールを列に定義したまま `showValidationMarks={showErrors}`(既定 `true`)を state で切り替えて実現します。`getInvalidCells()` と `'reject'` は表示状態の影響を受けません。完結したコード例は [`API_REFERENCE.md`](./src/components/spreadsheet-grid/API_REFERENCE.md) のレシピを参照してください。
+
 ### サイズ（高さ）
 
 既定ではグリッドの高さは `480px`（`max-height`）で頭打ちになり、中身がそれより高いとスクロールします。`height` を渡すと高さを明示制御できます。`height="100%"` で親要素の高さに追従、`number` で px 指定です:
@@ -501,11 +509,15 @@ const invalid = gridRef.current?.getInvalidCells()
       const { rows, totalRowCount } = await fetchPage({ startIndex, endIndex, query, signal })
       return { rows, totalRowCount }
     },
+    // 任意: serverSide のセル編集を有効化(楽観更新 + 失敗時ロールバック)。
+    async updateRows({ updates }) {
+      await patchRows(updates) // updates: [{ rowKey, rowIndex, row, previousRow, changes }]
+    },
   }}
 />
 ```
 
-ソート・列フィルター・グローバルフィルターは有効なまま `query` 経由でサーバへ送られます。`getRows` の契約、フィルターの wire format、`serverSideRefreshToken` の詳細は [API リファレンス](./src/components/spreadsheet-grid/API_REFERENCE.md) を参照してください。
+ソート・列フィルター・グローバルフィルターは有効なまま `query` 経由でサーバへ送られます。セル編集(エディタ確定 / ペースト / Delete クリア / checkbox)は `updateRows` で楽観更新つきの書き戻しになり、保存失敗時はセルが自動で元に戻って保存失敗バーが表示されます(`onServerSideWriteError` でトースト / ログ通知も可)。`updateRows` 未指定の serverSide セルは読み取り専用です。行の追加削除は書き戻し API を持たないため、サーバへ反映後に `refreshServerSide()` を呼ぶ運用にしてください。`getRows` / `updateRows` の契約、フィルターの wire format、`serverSideRefreshToken` の詳細は [API リファレンス](./src/components/spreadsheet-grid/API_REFERENCE.md) を参照してください。
 
 ### スタイリング / テーマ
 

package/dist/CellEditorLayer.d.ts

@@ -1,4 +1,4 @@
-import type { EditorCommitDirection, EditorCommitResult, GridColumn, GridColumnEditor } from './model/gridTypes';
+import type { EditorCommitDirection, EditorCommitResult, GridColumn, GridColumnEditor, GridRowKey } from './model/gridTypes';
 export type { EditorCommitDirection };
 type CellEditorRect = {
     left: number;
@@ -9,6 +9,8 @@ type CellEditorRect = {
 export type CellEditorSession<T> = {
     row: T;
     rowIndex: number;
+    sourceRowIndex: number;
+    rowKey: GridRowKey;
     colIndex: number;
     column: GridColumn<T>;
     value: unknown;

package/dist/SpreadsheetGrid.d.ts

@@ -1,3 +1,3 @@
 import './styles.css';
 import type { SpreadsheetGridProps } from './model/gridTypes';
-export declare function SpreadsheetGrid<T extends object>({ rows, dataSource, serverSideRefreshToken, onServerSideLoadError, columns, onRowsChange, onColumnsChange, rowKeyGetter, createRow, createOverflowColumn, rowHeight: rowHeightProp, autoHeight, estimateRowHeight, headerHeight: headerHeightProp, density, theme, rowHeaderWidth, height, maxHeight, readOnly, dimReadOnlyCells, canEditCell, enableUndoRedo, undoHistoryLimit, onUndoRedoStateChange, enableRangeSelection, enableRowSelection, rowSelectionMode, enableSelectAllRows: enableSelectAllRowsProp, rowSelection: rowSelectionProp, selectedRowKeys: selectedRowKeysProp, onRowSelectionChange, enableGlobalFilter, enableColumnFilter, enableSorting, enableColumnResize, autoSizeColumns, showCellOverflowTooltip, enableRowHover, enableColumnHeaderHover, enableColumnMenu, noMatchingRowsText, noRowsText, showTopBar, showBottomBar, showTopBarSummary, showTopBarFilter, globalFilterPlaceholder, globalFilterIcon, showTopBarCounts, showBottomBarCounts, showFilterChipBar, renderTopBar, renderBottomBar, className, classNames, getRowClassName, enableContextMenu, getContextMenuItems, onContextMenuOpen, ref, onStateChange, }: SpreadsheetGridProps<T>): import("react").JSX.Element;
+export declare function SpreadsheetGrid<T extends object>({ rows, dataSource, serverSideRefreshToken, onServerSideLoadError, onServerSideWriteError, columns, onRowsChange, onColumnsChange, rowKeyGetter, createRow, createOverflowColumn, rowHeight: rowHeightProp, autoHeight, estimateRowHeight, headerHeight: headerHeightProp, density, theme, rowHeaderWidth, height, maxHeight, readOnly, dimReadOnlyCells, canEditCell: canEditCellProp, enableUndoRedo, undoHistoryLimit, onUndoRedoStateChange, enableRangeSelection, enableRowSelection, rowSelectionMode, enableSelectAllRows: enableSelectAllRowsProp, rowSelection: rowSelectionProp, selectedRowKeys: selectedRowKeysProp, onRowSelectionChange, enableGlobalFilter, enableColumnFilter, enableSorting, enableColumnResize, autoSizeColumns, showCellOverflowTooltip, showValidationMarks, enableRowHover, enableColumnHeaderHover, enableColumnMenu, noMatchingRowsText, noRowsText, showTopBar, showBottomBar, showTopBarSummary, showTopBarFilter, globalFilterPlaceholder, globalFilterIcon, showTopBarCounts, showBottomBarCounts, showFilterChipBar, renderTopBar, renderBottomBar, className, classNames, getRowClassName, enableContextMenu, getContextMenuItems, onContextMenuOpen, ref, onStateChange, }: SpreadsheetGridProps<T>): import("react").JSX.Element;

package/dist/hooks/useGridClipboardController.d.ts

@@ -1,6 +1,7 @@
 import { type Dispatch } from 'react';
 import { type GridUiAction } from '../model/gridActions';
 import type { GridColumn, SpreadsheetGridProps, GridUiState, RowModel } from '../model/gridTypes';
+import type { ServerSideCellEditInput } from '../logic/serverSideEdits';
 type UseGridClipboardControllerArgs<T extends object> = {
     rows: T[];
     rowModel: RowModel<T>;
@@ -12,9 +13,10 @@ type UseGridClipboardControllerArgs<T extends object> = {
     createOverflowColumn?: (columnIndex: number) => GridColumn<T>;
     onRowsChange?: (nextRows: T[]) => void;
     onColumnsChange?: (nextColumns: GridColumn<T>[]) => void;
+    applyServerSideCellEdits?: (edits: ServerSideCellEditInput<T>[]) => number;
     dispatch: Dispatch<GridUiAction>;
 };
-export declare const useGridClipboardController: <T extends object>({ rows, rowModel, visibleColumns, uiState, readOnly, canEditCell, createRow, createOverflowColumn, onRowsChange, onColumnsChange, dispatch, }: UseGridClipboardControllerArgs<T>) => {
+export declare const useGridClipboardController: <T extends object>({ rows, rowModel, visibleColumns, uiState, readOnly, canEditCell, createRow, createOverflowColumn, onRowsChange, onColumnsChange, applyServerSideCellEdits, dispatch, }: UseGridClipboardControllerArgs<T>) => {
     isWholeGridSelected: boolean;
     handleCopy: () => Promise<void>;
     handlePaste: (event: React.ClipboardEvent<HTMLDivElement>) => void;

package/dist/hooks/useGridEditController.d.ts

@@ -1,6 +1,7 @@
 import { type Dispatch, type RefObject } from 'react';
 import { type GridUiAction } from '../model/gridActions';
 import type { CellCoord, EditorCommitDirection, EditorCommitResult, GridColumn, GridUiState, RowModel } from '../model/gridTypes';
+import type { ServerSideCellEditInput } from '../logic/serverSideEdits';
 type UseGridEditControllerArgs<T extends object> = {
     uiState: GridUiState;
     rows: T[];
@@ -8,12 +9,13 @@ type UseGridEditControllerArgs<T extends object> = {
     rowModel: RowModel<T>;
     setEditorInitialValue: (value: string) => void;
     onRowsChange?: (nextRows: T[]) => void;
+    applyServerSideCellEdits?: (edits: ServerSideCellEditInput<T>[]) => number;
     dispatch: Dispatch<GridUiAction>;
     getMovedCell: (baseCell: CellCoord, deltaRow: number, deltaCol: number) => CellCoord;
     gridRootRef: RefObject<HTMLDivElement | null>;
     editorActionGuardRef: RefObject<boolean>;
 };
-export declare const useGridEditController: <T extends object>({ uiState, rows, visibleColumns, rowModel, setEditorInitialValue, onRowsChange, dispatch, getMovedCell, gridRootRef, editorActionGuardRef, }: UseGridEditControllerArgs<T>) => {
+export declare const useGridEditController: <T extends object>({ uiState, rows, visibleColumns, rowModel, setEditorInitialValue, onRowsChange, applyServerSideCellEdits, dispatch, getMovedCell, gridRootRef, editorActionGuardRef, }: UseGridEditControllerArgs<T>) => {
     activateSingleCell: (cell: CellCoord) => void;
     startEditWithValue: (cell: CellCoord, initialValue: string) => void;
     commitEdit: (committedValue: unknown, direction?: EditorCommitDirection) => EditorCommitResult;

package/dist/hooks/useServerSideRowModel.d.ts

@@ -1,4 +1,5 @@
-import type { GridRowKey, RowModel, ServerSideDataSource, ServerSideLoadErrorParams, ServerSideQuery } from '../model/gridTypes';
+import type { GridRowKey, RowModel, ServerSideDataSource, ServerSideLoadErrorParams, ServerSideQuery, ServerSideWriteErrorParams } from '../model/gridTypes';
+import { type ServerSideCellEditInput } from '../logic/serverSideEdits';
 export type UseServerSideRowModelParams<T> = {
     dataSource?: ServerSideDataSource<T>;
     rowKeyGetter: (row: T, index: number) => GridRowKey;
@@ -6,11 +7,15 @@ export type UseServerSideRowModelParams<T> = {
     queryKey: string;
     refreshToken?: number;
     onLoadError?: (error: unknown, params: ServerSideLoadErrorParams) => void;
+    onWriteError?: (error: unknown, params: ServerSideWriteErrorParams<T>) => void;
     debounceMs?: number;
 };
 export type ServerSideLoadErrorState = {
     failedBlockCount: number;
 };
+export type ServerSideWriteErrorState = {
+    failedRowCount: number;
+};
 export type UseServerSideRowModelResult<T> = {
     rowModel: RowModel<T>;
     rowCount: number;
@@ -19,5 +24,8 @@ export type UseServerSideRowModelResult<T> = {
     refresh: () => void;
     loadError: ServerSideLoadErrorState | null;
     retryFailedBlocks: () => void;
+    canUpdateRows: boolean;
+    applyCellEdits: (edits: ServerSideCellEditInput<T>[]) => number;
+    writeError: ServerSideWriteErrorState | null;
 };
 export declare function useServerSideRowModel<T>(params: UseServerSideRowModelParams<T>): UseServerSideRowModelResult<T>;