@svgrid/grid 3.0.3 → 3.0.5

package/src/command-context.ts

@@ -0,0 +1,137 @@
+/**
+ * Builds the `GridCommandContext` handed to registered keyboard commands.
+ *
+ * Deliberately a getter object over the controller `ctx` rather than a
+ * snapshot: it is constructed on every keystroke that reaches a registered
+ * handler, so copying row and column arrays into it would put an allocation
+ * proportional to the grid in the hot path. Getters make construction O(1) and
+ * charge only for what a handler actually reads.
+ *
+ * Everything here is display-indexed, matching `SelectionPoint` and the rest of
+ * the selection model, so indices follow sort, filter and pagination. That is
+ * why `getCellValue` / `setCellValue` exist here rather than being left to
+ * `api.getCellValue`: the api pair indexes the DATA array, so handing a handler
+ * a selection index and an api that reads a different index space would give
+ * the wrong cell the moment the grid is sorted or filtered. `api.refresh()` has
+ * no index in it, so that one is left to the api.
+ */
+import type { GridCommandContext } from "./shortcut-registry";
+import { pushHistory, runHistoryGroup } from "./history";
+
+export function buildCommandContext(ctx: any, editing: boolean): GridCommandContext {
+  function columnIdAt(colIndex: number): string | null {
+    return ctx.allColumns[colIndex]?.id ?? null;
+  }
+
+  return {
+    get api() {
+      return ctx.buildApi();
+    },
+    editing,
+    get editor() {
+      const root: HTMLElement | null = ctx.gridRootEl ?? null;
+      const el = root?.querySelector<HTMLInputElement | HTMLTextAreaElement>(".sv-grid-cell-editor") ?? null;
+      return el;
+    },
+    get activeCell() {
+      const active = ctx.grid.getState().activeCell;
+      if (!active) return null;
+      return {
+        rowIndex: active.rowIndex,
+        colIndex: active.colIndex,
+        columnId: columnIdAt(active.colIndex),
+      };
+    },
+    get selectionFocus() {
+      const focus = ctx.selectionRange?.focus;
+      return focus ? { rowIndex: focus.rowIndex, colIndex: focus.colIndex } : null;
+    },
+    get rowCount() {
+      return ctx.allRows.length;
+    },
+    get colCount() {
+      return ctx.allColumns.length;
+    },
+    get ranges() {
+      // getSelectionRects() already normalises anchor/focus into rectangles
+      // and puts the active range last, which is the order a handler wants
+      // when it has to pick one.
+      return ctx.getSelectionRects().map(
+        (r: { minRow: number; minCol: number; maxRow: number; maxCol: number }) =>
+          [r.minRow, r.minCol, r.maxRow, r.maxCol] as const,
+      );
+    },
+    columnIdAt,
+    getCellValue(rowIndex: number, colIndex: number) {
+      const columnId = columnIdAt(colIndex);
+      return columnId == null ? undefined : ctx.readCellRaw(rowIndex, columnId);
+    },
+    setCellValue(rowIndex: number, colIndex: number, value: unknown) {
+      const columnId = columnIdAt(colIndex);
+      if (columnId == null) return;
+      // Record the write so Ctrl+Z walks it back. `writeCellRaw` is the raw
+      // writer and deliberately keeps no history of its own - the fill handle
+      // and paste call it in loops and push their own entries (or, today, none
+      // at all). A command has to push here or every multi-cell command it
+      // runs would be silently un-undoable.
+      //
+      // Both reads happen BEFORE the write: writeCellRaw swaps a fresh row
+      // object into `internalData`, so afterwards the id lookup would miss.
+      const field = ctx.allColumns[colIndex]?.columnDef?.field;
+      const rowId = ctx.allRows[rowIndex]?.id;
+      const before = ctx.readCellRaw(rowIndex, columnId);
+      ctx.writeCellRaw(rowIndex, columnId, value);
+      // Only when something actually changed: writeCellRaw no-ops on an equal
+      // value, and a step whose before and after match would make Ctrl+Z look
+      // like it had swallowed a press.
+      if (field != null && rowId != null && before !== value) {
+        pushHistory(ctx, [{ rowId, columnId, field, before, after: value }]);
+      }
+    },
+    setActiveCell(rowIndex: number, colIndex: number) {
+      ctx.setActiveCell(rowIndex, colIndex);
+    },
+    setSelection(rowIndex: number, colIndex: number) {
+      ctx.setSelection(rowIndex, colIndex);
+    },
+    extendSelection(rowIndex: number, colIndex: number) {
+      ctx.extendSelection(rowIndex, colIndex);
+    },
+    scrollIntoView(rowIndex: number, colIndex: number) {
+      ctx.scrollActiveCellIntoView(rowIndex, colIndex);
+    },
+    startEditing(rowIndex: number, colIndex: number, seed?: string) {
+      if (seed !== undefined) {
+        return ctx.startEditingWithChar(rowIndex, colIndex, seed) === true;
+      }
+      ctx.onCellDoubleClick(rowIndex, colIndex);
+      return true;
+    },
+    batch<T>(fn: () => T): T {
+      return runHistoryGroup(ctx, fn);
+    },
+    recordUndo(undo: () => void, redo: () => void) {
+      pushHistory(ctx, [
+        { rowId: "", columnId: "", field: "", before: undefined, after: undefined, custom: { undo, redo } },
+      ]);
+    },
+    focus() {
+      // preventScroll: the grid keeps its own scroll position, and a focus
+      // that yanked the viewport to the root's top edge would undo whatever
+      // scrollIntoView the command just asked for.
+      ctx.gridRootEl?.focus({ preventScroll: true });
+    },
+    async paste() {
+      await ctx.pasteFromClipboard?.();
+    },
+    copy() {
+      ctx.copySelectionToClipboard?.();
+    },
+    async cut() {
+      await ctx.cutSelectionToClipboard?.();
+    },
+    canEdit(rowIndex: number, colIndex: number) {
+      return ctx.isCellEditableAt?.(rowIndex, colIndex) ?? true;
+    },
+  };
+}

package/src/core.rowmodel-cache.test.ts

@@ -119,3 +119,54 @@ describe('row-model cache: selection', () => {
     expect(target.getIsSelected()).toBe(false)
   })
 })
+
+describe('base rows: reuse across a data swap', () => {
+  // The core reads `options.data` and `options.columns` off the object it was
+  // given (the component hands it a reactive one), so a swap is a write there.
+  const grid = () => {
+    const options = {
+      _features: tableFeatures({ rowSelectionFeature }),
+      _rowModels: { coreRowModel: createCoreRowModel<Row>() },
+      columns: COLUMNS as unknown as Array<ColumnDef<ReturnType<typeof tableFeatures>, Row>>,
+      data: makeRows(50),
+      getRowId: (r: Row) => String(r.id),
+    }
+    return { g: createSvGridCore<ReturnType<typeof tableFeatures>, Row>(options), options }
+  }
+
+  it('keeps the row object for a data object that stayed at its index, and rebuilds the rest', () => {
+    const { g, options } = grid()
+    const before = g.getRowModel().rows
+    const data = options.data.slice()
+    // A block landing: forty of fifty entries are the same objects, ten are new.
+    for (let i = 20; i < 30; i += 1) data[i] = { ...data[i]!, name: 'fresh' }
+    options.data = data
+    const after = g.getRowModel().rows
+    expect(after).toHaveLength(50)
+    for (let i = 0; i < 50; i += 1) {
+      if (i >= 20 && i < 30) expect(after[i]).not.toBe(before[i])
+      else expect(after[i]).toBe(before[i])
+    }
+    expect(after[25]!.getCellValueByColumnId('name')).toBe('fresh')
+  })
+
+  it('does not serve a memoised value after the object was changed in place', () => {
+    const { g, options } = grid()
+    const rows = g.getRowModel().rows
+    expect(rows[3]!.getCellValueByColumnId('score')).toBe((3 * 31) % 1000)
+    options.data[3]!.score = 4242
+    options.data = options.data.slice()
+    const again = g.getRowModel().rows
+    expect(again[3]).toBe(rows[3])
+    expect(again[3]!.getCellValueByColumnId('score')).toBe(4242)
+  })
+
+  it('rebuilds every row when the columns change', () => {
+    const { g, options } = grid()
+    const before = g.getRowModel().rows
+    options.columns = [...COLUMNS, { field: 'extra' }] as unknown as typeof options.columns
+    const after = g.getRowModel().rows
+    expect(after[0]).not.toBe(before[0])
+    expect(after[0]!.getAllCells()).toHaveLength(4)
+  })
+})

package/src/core.ts

@@ -468,6 +468,13 @@ export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> =
     | ((row: TData) => EditorOptionSource | Promise<EditorOptionSource>)
   /** When true, list/chips allow multiple selections. Cell value becomes an array. */
   editorMultiple?: boolean
+  /**
+   * The text editor accepts line breaks: Alt+Enter inserts one and the
+   * editor grows a line per break, while Enter still commits. What a
+   * spreadsheet cell with wrapped text wants; `editorType: 'textarea'` is
+   * the other shape, where Enter itself is the line break.
+   */
+  editorMultiline?: boolean
   /** Separator used when joining array values for the readonly cell display. Defaults to ', '. */
   editorSeparator?: string
   format?: CellFormatConfig
@@ -1538,6 +1545,7 @@ export function createSvGridCore<TFeatures extends TableFeatures, TData extends
   let cachedBaseRowsInput: ReadonlyArray<TData> | null = null
   let cachedBaseRowsColumns: Array<Column<TData>> | null = null
   let cachedBaseRows: Array<Row<TData>> = []
+  let cachedRowCtx: BaseRowCtx<TData> | null = null
   let cachedRowModel: RowModel<TData> | null = null
   let cachedRowModelBaseRows: Array<Row<TData>> | null = null
   let cachedPipeline = options._rowModels
@@ -1747,22 +1755,35 @@ export function createSvGridCore<TFeatures extends TableFeatures, TData extends
     getRowModel() {
       const columns = grid.getAllColumns()
       if (cachedBaseRowsInput !== options.data || cachedBaseRowsColumns !== columns) {
+        // Same columns as last time: the shared context still describes them,
+        // and a row whose data object sits at the same index can keep its
+        // row object. A row model that streams blocks hands the grid a new
+        // array of 60k entries per block where 100 changed; building 60k
+        // fresh row objects each time was most of the cost of a block
+        // landing. The reused row drops its memoised values and cells, since
+        // an app may have changed the object in place before passing a new
+        // array - that is the case the old rebuild covered by accident.
+        const previous = cachedBaseRowsColumns === columns && cachedRowCtx ? cachedBaseRows : null
         cachedBaseRowsInput = options.data
         cachedBaseRowsColumns = columns
         // O(1) column-id → index lookup so getCellValueByColumnId doesn't do
         // a linear `findIndex` on every cell read (was O(rows × cells × cols)).
-        const columnIndexById = new Map<string, number>()
-        for (let i = 0; i < columns.length; i++) columnIndexById.set(columns[i]!.id, i)
-        const columnCount = columns.length
-
-        // One shared context for every row in this table, so a row carries a
-        // pointer rather than a closure scope. See BASE_ROW_METHODS.
-        const rowCtx: BaseRowCtx<TData> = {
-          grid: grid as SvGrid<TData>,
-          store,
-          columns,
-          columnCount,
-          columnIndexById,
+        let rowCtx: BaseRowCtx<TData>
+        if (previous && cachedRowCtx) {
+          rowCtx = cachedRowCtx
+        } else {
+          const columnIndexById = new Map<string, number>()
+          for (let i = 0; i < columns.length; i++) columnIndexById.set(columns[i]!.id, i)
+          // One shared context for every row in this table, so a row carries a
+          // pointer rather than a closure scope. See BASE_ROW_METHODS.
+          rowCtx = {
+            grid: grid as SvGrid<TData>,
+            store,
+            columns,
+            columnCount: columns.length,
+            columnIndexById,
+          }
+          cachedRowCtx = rowCtx
         }
 
         cachedBaseRows = new Array(options.data.length)
@@ -1778,6 +1799,13 @@ export function createSvGridCore<TFeatures extends TableFeatures, TData extends
         }
         for (let index = 0; index < options.data.length; index++) {
           const original = options.data[index]!
+          const kept = previous?.[index] as BaseRowState<TData> | undefined
+          if (kept && kept.original === original) {
+            kept[ROW_VALUES] = null
+            kept[ROW_CELLS] = null
+            cachedBaseRows[index] = kept
+            continue
+          }
           // `_values` and `_cells` stay null until something reads them - a
           // 100k-row grid showing twenty rows must not materialise every row's
           // values or cell objects to paint.

package/src/editing.test.ts

@@ -77,6 +77,11 @@ function makeCtx(opts: FakeOptions = {}) {
     editorSelectAll: false,
     editedCellValues: {},
     selectionRange: { anchor: null, focus: null },
+    tabRunOrigin: null,
+    activeRangeRect: () => null,
+    isRowCollapsed: () => false,
+    collapsedColumns: {},
+    isCellInSelectedRange: () => false,
     gridRootEl: null,
     props: {},
     history: [] as any[],
@@ -551,9 +556,10 @@ describe('updateEditingCellValue', () => {
 })
 
 describe('onEditorKeyDown', () => {
-  function fakeEvent(key: string) {
+  function fakeEvent(key: string, init: Partial<KeyboardEvent> = {}) {
     return {
       key,
+      ...init,
       stopPropagation: vi.fn(),
       preventDefault: vi.fn(),
     } as unknown as KeyboardEvent
@@ -576,6 +582,74 @@ describe('onEditorKeyDown', () => {
     expect(focus).toHaveBeenCalledWith({ preventScroll: true })
   })
 
+  it('Enter saves and moves the active cell one row down, Shift+Enter one up', () => {
+    // Typing a column of values: Enter after each one lands on the next row,
+    // as in every spreadsheet, rather than leaving the cursor on the cell
+    // just committed. The last row is a wall, not a wrap.
+    const { ctx, ed } = editingFor({
+      columns: [{ id: 'a', field: 'a', editorType: 'text' }],
+      data: [{ a: 'a0' }, { a: 'a1' }, { a: 'a2' }],
+    })
+    ctx.gridRootEl = { focus: vi.fn() }
+    ed.onCellDoubleClick(0, 0)
+    ctx.editingCell = { ...ctx.editingCell, value: 'new' }
+    ed.onEditorKeyDown(fakeEvent('Enter'))
+    expect(ctx.internalData[0].a).toBe('new')
+    expect(ctx.activeCalls.at(-1)).toEqual([1, 0])
+
+    ed.onCellDoubleClick(1, 0)
+    const up = { ...fakeEvent('Enter'), shiftKey: true } as unknown as KeyboardEvent
+    ;(up as any).preventDefault = vi.fn()
+    ;(up as any).stopPropagation = vi.fn()
+    ed.onEditorKeyDown(up)
+    expect(ctx.activeCalls.at(-1)).toEqual([0, 0])
+
+    ed.onCellDoubleClick(2, 0)
+    ed.onEditorKeyDown(fakeEvent('Enter'))
+    expect(ctx.activeCalls.at(-1)).toEqual([2, 0])
+  })
+
+  it('Alt+Enter puts a line break into a multiline editor instead of committing', () => {
+    const { ctx, ed } = editingFor({
+      columns: [{ id: 'a', field: 'a', editorType: 'text' }],
+      data: [{ a: 'old' }],
+    })
+    ctx.gridRootEl = { focus: vi.fn() }
+    ctx.editingCell = { rowId: '0', columnId: 'a', editorType: 'text', value: 'ab' }
+    const area = document.createElement('textarea')
+    area.value = 'ab'
+    area.selectionStart = area.selectionEnd = 1
+    const ev = {
+      key: 'Enter', altKey: true, currentTarget: area,
+      stopPropagation: vi.fn(), preventDefault: vi.fn(),
+    } as unknown as KeyboardEvent
+    ed.onEditorKeyDown(ev)
+    expect(ev.preventDefault).toHaveBeenCalled()
+    expect(area.value).toBe('a\nb')
+    expect(area.selectionStart).toBe(2)
+    expect(ctx.editingCell?.value).toBe('a\nb')
+    // Still editing: nothing was saved.
+    expect(ctx.internalData[0].a).toBe('old')
+  })
+
+  it('Alt+Enter in a single-line input is just Enter', () => {
+    const { ctx, ed } = editingFor({
+      columns: [{ id: 'a', field: 'a', editorType: 'text' }],
+      data: [{ a: 'old' }, { a: 'next' }],
+    })
+    ctx.gridRootEl = { focus: vi.fn() }
+    ed.onCellDoubleClick(0, 0)
+    ctx.editingCell = { ...ctx.editingCell, value: 'new' }
+    const input = document.createElement('input')
+    const ev = {
+      key: 'Enter', altKey: true, currentTarget: input,
+      stopPropagation: vi.fn(), preventDefault: vi.fn(),
+    } as unknown as KeyboardEvent
+    ed.onEditorKeyDown(ev)
+    expect(ctx.internalData[0].a).toBe('new')
+    expect(ctx.editingCell).toBeNull()
+  })
+
   it('Escape cancels without saving and refocuses the grid root', () => {
     const { ctx, ed } = editingFor({
       columns: [{ id: 'a', field: 'a', editorType: 'text' }],
@@ -630,6 +704,89 @@ describe('onEditorKeyDown', () => {
     expect(ctx.activeCalls.at(-1)).toEqual([0, 1])
   })
 
+  it('Enter after a run of Tab commits returns to the column the run began in', () => {
+    const { ctx, ed } = editingFor({
+      columns: [
+        { id: 'a', field: 'a', editorType: 'text' },
+        { id: 'b', field: 'b', editorType: 'text' },
+        { id: 'c', field: 'c', editorType: 'text' },
+      ],
+      data: [{ a: '', b: '', c: '' }, { a: '', b: '', c: '' }],
+    })
+    ctx.gridRootEl = { focus: vi.fn() }
+    // The real setActiveCell forgets the run on a move to another cell;
+    // the fake must too, or the test would pass with the origin never
+    // being written back.
+    const plain = ctx.setActiveCell
+    ctx.setActiveCell = (r: number, c: number) => {
+      const prev = ctx.activeCell
+      if (!prev || prev.rowIndex !== r || prev.colIndex !== c) ctx.tabRunOrigin = null
+      plain(r, c)
+    }
+    ed.onCellDoubleClick(0, 0)
+    ctx.editingCell = { ...ctx.editingCell, value: 'one' }
+    ed.onEditorKeyDown(fakeEvent('Tab'))
+    ed.onCellDoubleClick(0, 1)
+    ctx.editingCell = { ...ctx.editingCell, value: 'two' }
+    ed.onEditorKeyDown(fakeEvent('Tab'))
+    expect(ctx.activeCalls.at(-1)).toEqual([0, 2])
+    expect(ctx.tabRunOrigin).toBe(0)
+    ed.onCellDoubleClick(0, 2)
+    ctx.editingCell = { ...ctx.editingCell, value: 'three' }
+    ed.onEditorKeyDown(fakeEvent('Enter'))
+    expect(ctx.internalData[0]).toMatchObject({ a: 'one', b: 'two', c: 'three' })
+    expect(ctx.activeCalls.at(-1)).toEqual([1, 0])
+    expect(ctx.tabRunOrigin).toBe(null)
+    expect(ctx.selectionCalls.at(-1)).toEqual([1, 0])
+  })
+
+  it('Ctrl+Enter writes the entry into every cell of the block, as one undo, and stays put', () => {
+    const { ctx, ed } = editingFor({
+      columns: [
+        { id: 'a', field: 'a', editorType: 'text' },
+        { id: 'b', field: 'b', editorType: 'text' },
+      ],
+      data: [{ a: '', b: '' }, { a: '', b: '' }, { a: 'keep', b: 'keep' }],
+    })
+    ctx.gridRootEl = { focus: vi.fn() }
+    ctx.activeRangeRect = () => ({ minRow: 0, maxRow: 1, minCol: 0, maxCol: 1 })
+    ctx.isCellInSelectedRange = () => true
+    ed.onCellDoubleClick(0, 0)
+    ctx.editingCell = { ...ctx.editingCell, value: 'x' }
+    const ev = fakeEvent('Enter', { ctrlKey: true })
+    ed.onEditorKeyDown(ev)
+    expect(ev.preventDefault).toHaveBeenCalled()
+    expect(ctx.internalData.slice(0, 2)).toEqual([{ a: 'x', b: 'x' }, { a: 'x', b: 'x' }])
+    expect(ctx.internalData[2]).toEqual({ a: 'keep', b: 'keep' })
+    // The cursor did not move.
+    expect(ctx.activeCalls.at(-1)).toEqual([0, 0])
+    expect(ctx.editingCell).toBeNull()
+    // Four steps, one group.
+    const groups = new Set(ctx.history.map((s: any) => s.groupId))
+    expect(ctx.history.length).toBe(4)
+    expect(groups.size).toBe(1)
+    expect([...groups][0]).toBeTruthy()
+  })
+
+  it('a commit inside a selected block keeps the block and moves within it', () => {
+    const { ctx, ed } = editingFor({
+      columns: [
+        { id: 'a', field: 'a', editorType: 'text' },
+        { id: 'b', field: 'b', editorType: 'text' },
+      ],
+      data: [{ a: '', b: '' }, { a: '', b: '' }],
+    })
+    ctx.gridRootEl = { focus: vi.fn() }
+    ctx.activeRangeRect = () => ({ minRow: 0, maxRow: 1, minCol: 0, maxCol: 1 })
+    ctx.isCellInSelectedRange = () => true
+    ed.onCellDoubleClick(1, 0)
+    ctx.editingCell = { ...ctx.editingCell, value: 'x' }
+    ed.onEditorKeyDown(fakeEvent('Enter'))
+    // Past the block's last row: the top of the next column.
+    expect(ctx.activeCalls.at(-1)).toEqual([0, 1])
+    expect(ctx.selectionCalls).toEqual([])
+  })
+
   it('Shift+Tab moves back a column and wraps to the previous row (#48)', () => {
     const { ctx, ed } = editingFor({
       columns: [
@@ -841,10 +998,131 @@ describe('onCellDoubleClick', () => {
   })
 })
 
+describe('applyPastedText reports and records what it wrote', () => {
+  function pasteReady(text: string) {
+    Object.defineProperty(navigator, 'clipboard', {
+      value: { readText: vi.fn().mockResolvedValue(text) },
+      configurable: true,
+    })
+    const { ctx, ed } = editingFor({
+      columns: [
+        { id: 'a', field: 'a', editable: true, editorType: 'text' },
+        { id: 'b', field: 'b', editable: true, editorType: 'text' },
+      ],
+      data: [{ a: 'a0', b: 'b0' }, { a: 'a1', b: 'b1' }, { a: 'a2', b: 'b2' }],
+    })
+    ctx.setActiveCell(1, 0)
+    ctx.selectionRange = { anchor: { rowIndex: 1, colIndex: 0 }, focus: { rowIndex: 1, colIndex: 0 } }
+    return { ctx, ed }
+  }
+
+  it('fires onCellValueChange for every cell a block paste changed', async () => {
+    // A formula engine behind the grid only sees a value through this hook;
+    // a paste that skipped it left the engine holding the old cells.
+    const { ctx, ed } = pasteReady('x\ty\nz\tb2')
+    const onCellValueChange = vi.fn()
+    ctx.props.onCellValueChange = onCellValueChange
+    await ed.pasteFromClipboard()
+    expect(ctx.internalData[1]).toEqual({ a: 'x', b: 'y' })
+    expect(ctx.internalData[2]).toEqual({ a: 'z', b: 'b2' })
+    // b2 was already b2: no event for a cell that did not change.
+    expect(onCellValueChange).toHaveBeenCalledTimes(3)
+    expect(onCellValueChange).toHaveBeenCalledWith(
+      expect.objectContaining({ rowIndex: 1, columnId: 'a', oldValue: 'a1', newValue: 'x' }),
+    )
+    expect(onCellValueChange).toHaveBeenCalledWith(
+      expect.objectContaining({ rowIndex: 2, columnId: 'a', oldValue: 'a2', newValue: 'z' }),
+    )
+  })
+
+  it('records the paste as one grouped history entry', async () => {
+    const { ctx, ed } = pasteReady('x\ty\nz\tw')
+    await ed.pasteFromClipboard()
+    expect(ctx.history).toHaveLength(4)
+    const groups = new Set(ctx.history.map((s: { groupId?: string }) => s.groupId))
+    expect(groups.size).toBe(1)
+    expect([...groups][0]).toBeDefined()
+    expect(ctx.history[0]).toMatchObject({ rowId: '1', columnId: 'a', field: 'a', before: 'a1', after: 'x' })
+  })
+
+  it('writes nothing, records nothing, when the paste changes nothing', async () => {
+    const { ctx, ed } = pasteReady('a1\tb1')
+    const onCellValueChange = vi.fn()
+    ctx.props.onCellValueChange = onCellValueChange
+    const before = ctx.internalData
+    await ed.pasteFromClipboard()
+    expect(ctx.internalData).toBe(before)
+    expect(ctx.history).toHaveLength(0)
+    expect(onCellValueChange).not.toHaveBeenCalled()
+  })
+})
+
+describe('onPasteClipboard', () => {
+  const grid = () => editingFor({
+    columns: [
+      { id: 'a', field: 'a', editorType: 'text', editable: true },
+      { id: 'b', field: 'b', editorType: 'text', editable: true },
+    ],
+    data: [{ a: '', b: '' }, { a: '', b: '' }],
+  })
+
+  it('hands the native paste event\'s text and HTML to the handler and applies nothing itself when it returns true', () => {
+    Object.defineProperty(navigator, 'clipboard', { value: { readText: vi.fn() }, configurable: true })
+    const { ctx, ed } = grid()
+    const seen: unknown[] = []
+    ctx.props.onPasteClipboard = (payload: unknown) => { seen.push(payload); return true }
+    const ev = {
+      clipboardData: { getData: (type: string) => (type === 'text/html' ? '<table><tr><td x:fmla="=A1">1</td></tr></table>' : '1') },
+      preventDefault: vi.fn(),
+    } as unknown as ClipboardEvent
+    ed.onGridPaste(ev)
+    expect(ev.preventDefault).toHaveBeenCalled()
+    expect(seen).toEqual([{ text: '1', html: '<table><tr><td x:fmla="=A1">1</td></tr></table>', source: 'event' }])
+    expect(ctx.internalData[0]).toMatchObject({ a: '', b: '' })
+  })
+
+  it('falls through to the plain paste when the handler declines', () => {
+    Object.defineProperty(navigator, 'clipboard', { value: undefined, configurable: true })
+    const { ctx, ed } = grid()
+    ctx.props.onPasteClipboard = () => undefined
+    ctx.selectionRange = { anchor: { rowIndex: 0, colIndex: 0 }, focus: { rowIndex: 0, colIndex: 0 } }
+    const ev = {
+      clipboardData: { getData: (type: string) => (type === 'text/plain' ? 'X\tY' : '') },
+      preventDefault: vi.fn(),
+    } as unknown as ClipboardEvent
+    ed.onGridPaste(ev)
+    expect(ctx.internalData[0]).toMatchObject({ a: 'X', b: 'Y' })
+  })
+
+  it('reads both types through navigator.clipboard.read on the async path', async () => {
+    const blob = (text: string) => ({ text: async () => text })
+    const read = vi.fn().mockResolvedValue([
+      { types: ['text/plain', 'text/html'], getType: async (t: string) => blob(t === 'text/html' ? '<b>h</b>' : 'p') },
+    ])
+    Object.defineProperty(navigator, 'clipboard', { value: { read, readText: vi.fn() }, configurable: true })
+    const { ctx, ed } = grid()
+    const seen: unknown[] = []
+    ctx.props.onPasteClipboard = (payload: unknown) => { seen.push(payload); return true }
+    await ed.pasteFromClipboard()
+    expect(seen).toEqual([{ text: 'p', html: '<b>h</b>', source: 'async' }])
+  })
+
+  it('the paste is one history group even when the handler writes several cells', () => {
+    Object.defineProperty(navigator, 'clipboard', { value: undefined, configurable: true })
+    const { ctx, ed } = grid()
+    let groupSeen: unknown = 'unset'
+    ctx.props.onPasteClipboard = () => { groupSeen = ctx.historyGroupId; return true }
+    ed.onGridPaste({ clipboardData: { getData: () => 'x' }, preventDefault: vi.fn() } as unknown as ClipboardEvent)
+    // The handler ran inside an ambient group, and the group closed after it.
+    expect(groupSeen).toBeTruthy()
+    expect(ctx.historyGroupId).toBeUndefined()
+  })
+})
+
 describe('clipboard fallbacks (non-paste branches only)', () => {
   // onGridPaste and pasteFromClipboard guard on navigator.clipboard.readText.
-  // The actual paste transformation is covered by clipboard.test.ts; here we
-  // only assert the early-return guards so we do not duplicate that coverage.
+  // The transformation itself is covered just above; here we only assert
+  // the early-return guards.
 
   it('pasteFromClipboard returns early when the async API is unavailable', async () => {
     Object.defineProperty(navigator, 'clipboard', {