@ishibashi0112/spreadsheet-grid 0.14.0 → 0.16.0

package/README.md

@@ -17,6 +17,8 @@ A high-performance, virtualized spreadsheet / data grid for **React 19**, writte
 - Three-pane pinned columns (left / center / right) via sticky positioning.
 - 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.
 - 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`.
@@ -114,6 +116,52 @@ export function Example() {
 
 `rows` and `onRowsChange` make the grid a controlled component. A column needs at least `key` and `width`.
 
+## Cell editors & validation
+
+Pick an editor per column with `column.editor`, and validate values with `column.validate`:
+
+```tsx
+const columns: GridColumn<Row>[] = [
+  {
+    key: 'name', title: 'Name', width: 200,
+    // 'reject' refuses invalid writes: the editor keeps editing with an error
+    // bubble; paste / Delete skip the offending cells.
+    validate: ({ value }) => (String(value ?? '').length > 0 ? true : 'Name is required'),
+    validationMode: 'reject',
+  },
+  {
+    key: 'qty', title: 'Qty', width: 120, align: 'right',
+    editor: { type: 'number', min: 0, step: 1 },
+    // Default 'mark' mode: invalid values are accepted but flagged on the cell
+    // (background + corner marker + tooltip message on hover).
+    validate: ({ value }) =>
+      typeof value === 'number' && value >= 0 ? true : 'Enter a number ≥ 0',
+  },
+  {
+    key: 'status', title: 'Status', width: 140,
+    editor: { type: 'select', options: [
+      { value: 'active', label: 'Active' },
+      { value: 'hold', label: 'On hold' },
+    ] },
+  },
+  { key: 'shippedAt', title: 'Shipped', width: 140, editor: { type: 'date' } },
+  // Direct toggle by click / Space — no edit session. Values default to true / false;
+  // map them with checkedValue / uncheckedValue (e.g. '1' / '0').
+  { key: 'done', title: 'Done', width: 90, align: 'center', editor: { type: 'checkbox' } },
+  // Bring your own editor: render anything, call ctx.commit(value) / ctx.cancel().
+  // Committing a non-string value bypasses parsing and writes the domain value as-is.
+  { key: 'amount', title: 'Amount', width: 140,
+    editor: { type: 'custom', render: (ctx) => <MyAmountEditor ctx={ctx} /> } },
+]
+```
+
+Before saving, collect every invalid cell (client-side row model):
+
+```ts
+const invalid = gridRef.current?.getInvalidCells()
+// -> [{ rowKey, sourceRowIndex, columnKey, message }, ...]
+```
+
 ## 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:
@@ -250,6 +298,8 @@ The full prop and type reference lives in [`src/components/spreadsheet-grid/API_
 - `position: sticky` による 3 ペイン固定列（左 / 中央 / 右）。
 - ソート、列ごとのフィルター（`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()` で保存前の全行チェックができます。
 - グリッド編集の 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`。
@@ -347,6 +397,52 @@ export function Example() {
 
 `rows` と `onRowsChange` でグリッドは controlled になります。列には最低限 `key` と `width` が必要です。
 
+### セルエディタとバリデーション
+
+列ごとに `column.editor` でエディタ種別を選び、`column.validate` で値を検証できます:
+
+```tsx
+const columns: GridColumn<Row>[] = [
+  {
+    key: 'name', title: '品名', width: 200,
+    // 'reject' は不正な書き込み自体を拒否: エディタはエラーバブル表示で編集継続、
+    // 貼り付け / Delete は該当セルのみスキップされます。
+    validate: ({ value }) => (String(value ?? '').length > 0 ? true : '品名は必須です'),
+    validationMode: 'reject',
+  },
+  {
+    key: 'qty', title: '数量', width: 120, align: 'right',
+    editor: { type: 'number', min: 0, step: 1 },
+    // 既定の 'mark' モード: 不正値も一旦入り、セルに invalid 表示
+    // (背景 + 右上マーカー + ホバーでメッセージ)が付きます。
+    validate: ({ value }) =>
+      typeof value === 'number' && value >= 0 ? true : '0 以上の数値を入力してください',
+  },
+  {
+    key: 'status', title: '状態', width: 140,
+    editor: { type: 'select', options: [
+      { value: '有効', label: '有効' },
+      { value: '保留', label: '保留' },
+    ] },
+  },
+  { key: 'shippedAt', title: '出荷日', width: 140, editor: { type: 'date' } },
+  // クリック / Space の直接トグル(編集セッションなし)。値は既定 true / false、
+  // checkedValue / uncheckedValue でマッピング可(例: '1' / '0')。
+  { key: 'done', title: '完了', width: 90, align: 'center', editor: { type: 'checkbox' } },
+  // 自作エディタ: 任意の UI を描画し、ctx.commit(value) / ctx.cancel() を呼びます。
+  // 非 string の commit はパースをバイパスしてドメイン値をそのまま書き込みます。
+  { key: 'amount', title: '金額', width: 140,
+    editor: { type: 'custom', render: (ctx) => <MyAmountEditor ctx={ctx} /> } },
+]
+```
+
+保存前に invalid セルを一括取得できます(クライアントサイド行モデル):
+
+```ts
+const invalid = gridRef.current?.getInvalidCells()
+// -> [{ rowKey, sourceRowIndex, columnKey, message }, ...]
+```
+
 ### サイズ（高さ）
 
 既定ではグリッドの高さは `480px`（`max-height`）で頭打ちになり、中身がそれより高いとスクロールします。`height` を渡すと高さを明示制御できます。`height="100%"` で親要素の高さに追従、`number` で px 指定です:

package/dist/CellEditorLayer.d.ts

@@ -1,19 +1,30 @@
-export type EditorCommitDirection = 'down' | 'right' | 'left';
+import type { EditorCommitDirection, EditorCommitResult, GridColumn, GridColumnEditor } from './model/gridTypes';
+export type { EditorCommitDirection };
 type CellEditorRect = {
     left: number;
     top: number;
     width: number;
     height: number;
 };
-type CellEditorLayerProps = {
+export type CellEditorSession<T> = {
+    row: T;
+    rowIndex: number;
+    colIndex: number;
+    column: GridColumn<T>;
+    value: unknown;
+};
+type CellEditorLayerProps<T> = {
     rect: CellEditorRect | null;
     headerHeight: number;
     leadingWidth: number;
     baseOffset?: number;
     initialValue: string;
-    onCommit: (value: string, direction?: EditorCommitDirection) => void;
+    editor?: GridColumnEditor<T>;
+    editorSession?: CellEditorSession<T> | null;
+    themeClassName?: string;
+    onCommit: (value: unknown, direction?: EditorCommitDirection) => EditorCommitResult | void;
     onCancel: () => void;
     align?: 'left' | 'center' | 'right';
 };
-export declare function CellEditorLayer({ rect, headerHeight, leadingWidth, baseOffset, initialValue, onCommit, onCancel, align, }: CellEditorLayerProps): import("react").JSX.Element | null;
+export declare function CellEditorLayer<T>({ rect, headerHeight, leadingWidth, baseOffset, initialValue, editor, editorSession, themeClassName, onCommit, onCancel, align, }: CellEditorLayerProps<T>): import("react").JSX.Element | null;
 export default CellEditorLayer;

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, 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, 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;

package/dist/editors/CellEditorErrorBubble.d.ts

@@ -0,0 +1,4 @@
+export declare function CellEditorErrorBubble({ message }: {
+    message: string;
+}): import("react").JSX.Element;
+export default CellEditorErrorBubble;

package/dist/editors/CheckboxCell.d.ts

@@ -0,0 +1,7 @@
+type CheckboxCellProps = {
+    checked: boolean;
+    readOnly: boolean;
+    onToggle: () => void;
+};
+export declare function CheckboxCell({ checked, readOnly, onToggle }: CheckboxCellProps): import("react").JSX.Element;
+export default CheckboxCell;

package/dist/editors/CustomCellEditor.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+import type { CellEditorContext } from '../model/gridTypes';
+type CustomCellEditorProps<T> = {
+    render: (ctx: CellEditorContext<T>) => ReactNode;
+    context: CellEditorContext<T>;
+};
+export declare function CustomCellEditor<T>({ render, context, }: CustomCellEditorProps<T>): import("react").JSX.Element;
+export default CustomCellEditor;

package/dist/editors/DateCellEditor.d.ts

@@ -0,0 +1,9 @@
+import type { EditorCommitDirection, EditorCommitResult } from '../model/gridTypes';
+type DateCellEditorProps = {
+    initialValue: string;
+    onCommit: (value: unknown, direction?: EditorCommitDirection) => EditorCommitResult | void;
+    onCancel: () => void;
+    align?: 'left' | 'center' | 'right';
+};
+export declare function DateCellEditor({ initialValue, onCommit, onCancel, align, }: DateCellEditorProps): import("react").JSX.Element;
+export default DateCellEditor;

package/dist/editors/NumberCellEditor.d.ts

@@ -0,0 +1,12 @@
+import type { EditorCommitDirection, EditorCommitResult } from '../model/gridTypes';
+type NumberCellEditorProps = {
+    initialValue: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    onCommit: (value: unknown, direction?: EditorCommitDirection) => EditorCommitResult | void;
+    onCancel: () => void;
+    align?: 'left' | 'center' | 'right';
+};
+export declare function NumberCellEditor({ initialValue, min, max, step, onCommit, onCancel, align, }: NumberCellEditorProps): import("react").JSX.Element;
+export default NumberCellEditor;

package/dist/editors/SelectCellEditor.d.ts

@@ -0,0 +1,11 @@
+import type { EditorCommitDirection, EditorCommitResult, GridSelectEditorOption } from '../model/gridTypes';
+type SelectCellEditorProps = {
+    options: GridSelectEditorOption[];
+    value: unknown;
+    onCommit: (value: unknown, direction?: EditorCommitDirection) => EditorCommitResult | void;
+    onCancel: () => void;
+    align?: 'left' | 'center' | 'right';
+    themeClassName?: string;
+};
+export declare function SelectCellEditor({ options, value, onCommit, onCancel, align, themeClassName, }: SelectCellEditorProps): import("react").JSX.Element;
+export default SelectCellEditor;

package/dist/editors/TextCellEditor.d.ts

@@ -0,0 +1,9 @@
+import type { EditorCommitDirection, EditorCommitResult } from '../model/gridTypes';
+type TextCellEditorProps = {
+    initialValue: string;
+    onCommit: (value: unknown, direction?: EditorCommitDirection) => EditorCommitResult | void;
+    onCancel: () => void;
+    align?: 'left' | 'center' | 'right';
+};
+export declare function TextCellEditor({ initialValue, onCommit, onCancel, align, }: TextCellEditorProps): import("react").JSX.Element;
+export default TextCellEditor;

package/dist/editors/editorKeyBindings.d.ts

@@ -0,0 +1,10 @@
+import type { KeyboardEvent } from 'react';
+import type { EditorCommitDirection, EditorCommitResult } from '../model/gridTypes';
+type CreateEditorKeyDownHandlerArgs = {
+    value: unknown;
+    onCommit: (value: unknown, direction?: EditorCommitDirection) => EditorCommitResult | void;
+    onCancel: () => void;
+    onRejected?: (message: string) => void;
+};
+export declare const createEditorKeyDownHandler: ({ value, onCommit, onCancel, onRejected }: CreateEditorKeyDownHandlerArgs) => (event: KeyboardEvent<HTMLInputElement>) => void;
+export {};

package/dist/hooks/useGridEditController.d.ts

@@ -1,7 +1,6 @@
 import { type Dispatch, type RefObject } from 'react';
 import { type GridUiAction } from '../model/gridActions';
-import type { CellCoord, GridColumn, GridUiState, RowModel } from '../model/gridTypes';
-import type { EditorCommitDirection } from '../CellEditorLayer';
+import type { CellCoord, EditorCommitDirection, EditorCommitResult, GridColumn, GridUiState, RowModel } from '../model/gridTypes';
 type UseGridEditControllerArgs<T extends object> = {
     uiState: GridUiState;
     rows: T[];
@@ -17,7 +16,7 @@ type UseGridEditControllerArgs<T extends object> = {
 export declare const useGridEditController: <T extends object>({ uiState, rows, visibleColumns, rowModel, setEditorInitialValue, onRowsChange, dispatch, getMovedCell, gridRootRef, editorActionGuardRef, }: UseGridEditControllerArgs<T>) => {
     activateSingleCell: (cell: CellCoord) => void;
     startEditWithValue: (cell: CellCoord, initialValue: string) => void;
-    commitEdit: (committedValue: string, direction?: EditorCommitDirection) => void;
+    commitEdit: (committedValue: unknown, direction?: EditorCommitDirection) => EditorCommitResult;
     cancelEdit: () => void;
 };
 export default useGridEditController;

package/dist/hooks/useGridKeyboardInteractions.d.ts

@@ -16,8 +16,9 @@ type UseGridKeyboardInteractionsArgs<T> = {
     onUndo: () => void;
     onRedo: () => void;
     onClearSelection: () => void;
+    onToggleCheckboxCell: (cell: CellCoord) => void;
 };
-export declare const useGridKeyboardInteractions: <T>({ uiState, rowModel, visibleColumns, readOnly, canEditCell, setEditorInitialValue, dispatch, handleCopy, handleCellDoubleClick, isWholeGridSelected, selectEntireGrid, onUndo, onRedo, onClearSelection, }: UseGridKeyboardInteractionsArgs<T>) => {
+export declare const useGridKeyboardInteractions: <T>({ uiState, rowModel, visibleColumns, readOnly, canEditCell, setEditorInitialValue, dispatch, handleCopy, handleCellDoubleClick, isWholeGridSelected, selectEntireGrid, onUndo, onRedo, onClearSelection, onToggleCheckboxCell, }: UseGridKeyboardInteractionsArgs<T>) => {
     getMovedCell: (baseCell: CellCoord, deltaRow: number, deltaCol: number) => CellCoord;
     handleKeyDown: (event: KeyboardEvent<HTMLDivElement>) => Promise<void>;
 };

package/dist/hooks/useServerSideRowModel.d.ts

@@ -1,16 +1,23 @@
-import type { GridRowKey, RowModel, ServerSideDataSource, ServerSideQuery } from '../model/gridTypes';
+import type { GridRowKey, RowModel, ServerSideDataSource, ServerSideLoadErrorParams, ServerSideQuery } from '../model/gridTypes';
 export type UseServerSideRowModelParams<T> = {
     dataSource?: ServerSideDataSource<T>;
     rowKeyGetter: (row: T, index: number) => GridRowKey;
     query: ServerSideQuery;
     queryKey: string;
     refreshToken?: number;
+    onLoadError?: (error: unknown, params: ServerSideLoadErrorParams) => void;
     debounceMs?: number;
 };
+export type ServerSideLoadErrorState = {
+    failedBlockCount: number;
+};
 export type UseServerSideRowModelResult<T> = {
     rowModel: RowModel<T>;
     rowCount: number;
     isRowLoaded: (viewIndex: number) => boolean;
     requestRange: (startIndex: number, endIndex: number) => void;
+    refresh: () => void;
+    loadError: ServerSideLoadErrorState | null;
+    retryFailedBlocks: () => void;
 };
 export declare function useServerSideRowModel<T>(params: UseServerSideRowModelParams<T>): UseServerSideRowModelResult<T>;