@svgrid/grid 3.0.2 → 3.0.4

package/src/clipboard.test.ts

@@ -77,6 +77,11 @@ function makeCtx(opts: FakeOptions = {}) {
     _rows: buildRows(),
     selectionRange: { anchor: null, focus: null },
     selectionRanges: [] as Array<{ anchor: any; focus: any }>,
+    history: [] as any[],
+    historyPtr: -1,
+    historyVersion: 0,
+    historyGroupId: undefined as string | undefined,
+    UNDO_LIMIT: 200,
     // Mirrors the real controller's getSelectionRects: committed ranges + active.
     getSelectionRects(): Array<{ minRow: number; maxRow: number; minCol: number; maxCol: number }> {
       const rects: Array<{ minRow: number; maxRow: number; minCol: number; maxCol: number }> = []
@@ -436,6 +441,77 @@ describe('onFillPointerUp / applyFillPattern', () => {
     expect(ctx.selectionRange.focus).toEqual({ rowIndex: 3, colIndex: 0 })
   })
 
+  it('records the drag as one grouped history entry, so Ctrl+Z takes it all back', () => {
+    // The fill used to write through writeCellRaw and push nothing: a drag
+    // over twenty rows was invisible to undo.
+    const ctx = makeCtx({
+      columns: [{ id: 'a', field: 'a', editable: true, editorType: 'number' }],
+      data: [{ a: 1 }, { a: 2 }, { a: 0 }, { a: 0 }],
+    })
+    ctx.fillDrag = { sourceMinRow: 0, sourceMaxRow: 1, sourceMinCol: 0, sourceMaxCol: 0, targetRow: 3, targetCol: 0 }
+    createClipboard(ctx).onFillPointerUp()
+    expect(ctx.history).toHaveLength(2)
+    expect(ctx.history[0]).toMatchObject({ rowId: '2', columnId: 'a', field: 'a', before: 0, after: 3 })
+    expect(ctx.history[1]).toMatchObject({ rowId: '3', columnId: 'a', field: 'a', before: 0, after: 4 })
+    expect(ctx.history[0].groupId).toBeDefined()
+    expect(ctx.history[0].groupId).toBe(ctx.history[1].groupId)
+  })
+
+  it('asks processCellForFill first and falls back to the pattern when it declines', () => {
+    // A spreadsheet moves a formula's references by the distance filled;
+    // the pattern rules would read "=A1+B1" as "Item 1" and write "=A1+B2".
+    const seen: Array<{ value: unknown; delta: { rows: number; cols: number } }> = []
+    const ctx = makeCtx({
+      columns: [{ id: 'a', field: 'a', editable: true, editorType: 'text' }],
+      data: [{ a: '=A1+B1' }, { a: '' }, { a: '' }],
+    })
+    ctx.props.processCellForFill = ({ value, delta }: { value: unknown; delta: { rows: number; cols: number } }) => {
+      seen.push({ value, delta })
+      return typeof value === 'string' && value.startsWith('=') ? `${value}@${delta.rows}` : undefined
+    }
+    ctx.fillDrag = { sourceMinRow: 0, sourceMaxRow: 0, sourceMinCol: 0, sourceMaxCol: 0, targetRow: 2, targetCol: 0 }
+    createClipboard(ctx).onFillPointerUp()
+    expect(ctx.internalData[1].a).toBe('=A1+B1@1')
+    expect(ctx.internalData[2].a).toBe('=A1+B1@2')
+    expect(seen.map((s) => s.delta.rows)).toEqual([1, 2])
+
+    // Declining leaves the series to the pattern.
+    const numeric = makeCtx({
+      columns: [{ id: 'a', field: 'a', editable: true, editorType: 'number' }],
+      data: [{ a: 1 }, { a: 2 }, { a: 0 }, { a: 0 }],
+    })
+    numeric.props.processCellForFill = () => undefined
+    numeric.fillDrag = { sourceMinRow: 0, sourceMaxRow: 1, sourceMinCol: 0, sourceMaxCol: 0, targetRow: 3, targetCol: 0 }
+    createClipboard(numeric).onFillPointerUp()
+    expect(numeric.internalData[2].a).toBe(3)
+    expect(numeric.internalData[3].a).toBe(4)
+  })
+
+  it('double-click fills down as far as the neighbouring column has data', () => {
+    const ctx = makeCtx({
+      columns: [
+        { id: 'a', field: 'a', editable: true, editorType: 'text' },
+        { id: 'b', field: 'b', editable: true, editorType: 'number' },
+      ],
+      data: [{ a: 'x', b: 1 }, { a: 'y', b: 0 }, { a: 'z', b: 0 }, { a: '', b: 0 }],
+    })
+    ctx.selectionRange = { anchor: { rowIndex: 0, colIndex: 1 }, focus: { rowIndex: 0, colIndex: 1 } }
+    createClipboard(ctx).fillDownToNeighbour()
+    // Column a runs to row 3 (index 2); the fill stops there.
+    expect(ctx.internalData.map((r: any) => r.b)).toEqual([1, 1, 1, 0])
+    expect(ctx.selectionRange.focus).toEqual({ rowIndex: 2, colIndex: 1 })
+  })
+
+  it('double-click with nothing beside the selection fills nothing', () => {
+    const ctx = makeCtx({
+      columns: [{ id: 'a', field: 'a', editable: true, editorType: 'number' }],
+      data: [{ a: 1 }, { a: 0 }, { a: 0 }],
+    })
+    ctx.selectionRange = { anchor: { rowIndex: 0, colIndex: 0 }, focus: { rowIndex: 0, colIndex: 0 } }
+    createClipboard(ctx).fillDownToNeighbour()
+    expect(ctx.internalData.map((r: any) => r.a)).toEqual([1, 0, 0])
+  })
+
   it('fills upward, reverse-extrapolating the pattern', () => {
     const ctx = makeCtx({
       columns: [{ id: 'a', field: 'a', editable: true, editorType: 'number' }],
@@ -617,6 +693,59 @@ describe('copySelectionToClipboard', () => {
     expect(writeText).toHaveBeenCalledWith('a\tb\na0\tb0\na1\tb1')
   })
 
+  it('writes text and HTML through the copy event when clipboardHtml supplies markup', () => {
+    // The copy event is the first path: execCommand('copy') fires it and the
+    // one-shot listener puts both types on it, attributes intact.
+    const ctx = makeCtx({ data: [{ a: 'a0', b: 'b0' }] })
+    ctx.props.clipboardHtml = ({ text }: { text: string }) => `<table data-x="1"><tr><td>${text}</td></tr></table>`
+    ctx.selectionRange = { anchor: { rowIndex: 0, colIndex: 0 }, focus: { rowIndex: 0, colIndex: 1 } }
+    const set = vi.fn()
+    // jsdom has no execCommand; this one fires the copy event the way a browser's does.
+    ;(document as unknown as { execCommand: (name: string) => boolean }).execCommand = () => {
+      const ev = new Event('copy', { cancelable: true }) as ClipboardEvent
+      Object.defineProperty(ev, 'clipboardData', { value: { setData: set } })
+      document.dispatchEvent(ev)
+      return true
+    }
+    try {
+      createClipboard(ctx).copySelectionToClipboard()
+      expect(set).toHaveBeenCalledWith('text/plain', 'a0\tb0')
+      expect(set).toHaveBeenCalledWith('text/html', '<table data-x="1"><tr><td>a0\tb0</td></tr></table>')
+      expect(writeText).not.toHaveBeenCalled()
+    } finally {
+      delete (document as unknown as { execCommand?: unknown }).execCommand
+    }
+  })
+
+  it('falls back to the async write with both types when the copy event is refused', () => {
+    const ctx = makeCtx({ data: [{ a: 'a0', b: 'b0' }] })
+    ctx.props.clipboardHtml = () => '<b>x</b>'
+    ctx.selectionRange = { anchor: { rowIndex: 0, colIndex: 0 }, focus: { rowIndex: 0, colIndex: 0 } }
+    const write = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { value: { writeText, write }, configurable: true })
+    ;(document as unknown as { execCommand: (name: string) => boolean }).execCommand = () => false
+    class FakeItem { constructor(public parts: Record<string, Blob>) {} }
+    ;(globalThis as Record<string, unknown>).ClipboardItem = FakeItem
+    try {
+      createClipboard(ctx).copySelectionToClipboard()
+      expect(write).toHaveBeenCalledTimes(1)
+      const item = write.mock.calls[0]![0][0] as FakeItem
+      expect(Object.keys(item.parts)).toEqual(['text/plain', 'text/html'])
+      expect(writeText).not.toHaveBeenCalled()
+    } finally {
+      delete (document as unknown as { execCommand?: unknown }).execCommand
+      delete (globalThis as Record<string, unknown>).ClipboardItem
+    }
+  })
+
+  it('writes text alone when clipboardHtml returns nothing', () => {
+    const ctx = makeCtx({ data: [{ a: 'a0', b: 'b0' }] })
+    ctx.props.clipboardHtml = () => null
+    ctx.selectionRange = { anchor: { rowIndex: 0, colIndex: 0 }, focus: { rowIndex: 0, colIndex: 0 } }
+    createClipboard(ctx).copySelectionToClipboard()
+    expect(writeText).toHaveBeenCalledWith('a0')
+  })
+
   it('runs each value through processCellForClipboard', () => {
     const ctx = makeCtx({
       data: [{ a: 'a0', b: 'b0' }],
@@ -738,6 +867,28 @@ describe('clearSelectedCells', () => {
     )
   })
 
+  it('records the clear in the history as one grouped step per cell', () => {
+    // Delete over a block used to leave no trace: the values were gone and
+    // Ctrl+Z skipped past them to whatever edit came before.
+    const ctx = makeCtx({
+      columns: [
+        { id: 'a', field: 'a', editable: true, editorType: 'text' },
+        { id: 'b', field: 'b', editable: true, editorType: 'text' },
+      ],
+      data: [{ a: 'x', b: 'y' }],
+    })
+    ctx.selectionRange = {
+      anchor: { rowIndex: 0, colIndex: 0 },
+      focus: { rowIndex: 0, colIndex: 1 },
+    }
+    createClipboard(ctx).clearSelectedCells()
+    expect(ctx.history).toHaveLength(2)
+    expect(ctx.history[0]).toMatchObject({ rowId: '0', columnId: 'a', field: 'a', before: 'x', after: '' })
+    expect(ctx.history[0].groupId).toBeDefined()
+    expect(ctx.history[1].groupId).toBe(ctx.history[0].groupId)
+    expect(ctx.historyPtr).toBe(1)
+  })
+
   it('clears a number cell via parseEditorValue coercion', () => {
     const ctx = makeCtx({
       columns: [{ id: 'a', field: 'a', editable: true, editorType: 'number' }],

package/src/clipboard.ts

@@ -18,6 +18,7 @@ import {
   isGroupRow,
   toolPanelHeaderLabel,
 } from "./cell-values";
+import { pushHistory, nextGroupId, runHistoryGroup, type HistoryStep } from "./history";
 
 export function createClipboard<
   TFeatures extends TableFeatures = TableFeatures,
@@ -84,7 +85,91 @@ export function createClipboard<
   /** Apply the pattern fill on pointerup. Each NEW row (or column) is
    *  filled from a pattern derived from the matching column (or row) of
    *  the source. Handles all four drag directions. */
+  /**
+   * Write one filled cell and remember it, so the drag undoes as a unit.
+   * `writeCellRaw` keeps no history of its own; the fill used to call it in
+   * a loop and push nothing, which left Ctrl+Z blind to a whole drag.
+   */
+  function writeFilled(steps: HistoryStep[], rowIndex: number, columnId: string, value: unknown) {
+    const row = ctx.allRows[rowIndex];
+    const column = ctx.findColumnById(columnId);
+    const field = column?.columnDef.field;
+    if (!row || field == null) return;
+    const before = readCellRaw(rowIndex, columnId);
+    writeCellRaw(rowIndex, columnId, value);
+    if (before !== value) steps.push({ rowId: row.id, columnId, field, before, after: value });
+  }
+
   function applyFillPattern() {
+    const steps: HistoryStep[] = [];
+    runHistoryGroup(ctx, () => applyFillCells(steps));
+    if (steps.length) pushHistory(ctx, steps, nextGroupId());
+  }
+
+  /**
+   * The value for the i-th filled cell: the consumer's, when its hook has
+   * one for the source cell the target cycles back to, else the pattern's.
+   * `sourceStart` is the row (or column) of the first source value and
+   * `targetStart` that of the first target; `step` is -1 filling upward.
+   */
+  function filledValue(
+    sources: unknown[],
+    pattern: unknown[],
+    i: number,
+    sourceStart: number,
+    targetStart: number,
+    step: 1 | -1,
+    axis: "rows" | "cols",
+    rowIndex: number,
+    columnId: string,
+  ): unknown {
+    const hook = ctx.props.processCellForFill;
+    if (hook && sources.length) {
+      const k = i % sources.length;
+      const distance = (targetStart + step * i) - (sourceStart + step * k);
+      const delta = axis === "rows" ? { rows: distance, cols: 0 } : { rows: 0, cols: distance };
+      const decided = hook({ value: sources[k], delta, rowIndex, columnId });
+      if (decided !== undefined) return decided;
+    }
+    return pattern[i];
+  }
+
+  /**
+   * Double-click on the fill handle: fill down as far as the column beside
+   * the selection has data, the way Excel's does. The column to the left
+   * decides; when it is blank below the selection (or there is none) the
+   * one to the right does. Nothing to follow, nothing filled.
+   */
+  function fillDownToNeighbour() {
+    const anchor = ctx.selectionRange.anchor ?? ctx.grid.getState().activeCell;
+    if (!anchor) return;
+    const focus = ctx.selectionRange.focus ?? anchor;
+    const minRow = Math.min(anchor.rowIndex, focus.rowIndex);
+    const maxRow = Math.max(anchor.rowIndex, focus.rowIndex);
+    const minCol = Math.min(anchor.colIndex, focus.colIndex);
+    const maxCol = Math.max(anchor.colIndex, focus.colIndex);
+    const filled = (r: number, c: number) => {
+      const col = ctx.allColumns[c];
+      if (!col) return false;
+      const v = readCellRaw(r, col.id);
+      return v != null && v !== "";
+    };
+    const extent = (c: number): number => {
+      let r = maxRow;
+      while (r + 1 < ctx.allRows.length && filled(r + 1, c)) r += 1;
+      return r;
+    };
+    let target = minCol > 0 ? extent(minCol - 1) : maxRow;
+    if (target === maxRow) target = extent(maxCol + 1);
+    if (target <= maxRow) return;
+    ctx.fillDrag = {
+      sourceMinRow: minRow, sourceMaxRow: maxRow, sourceMinCol: minCol, sourceMaxCol: maxCol,
+      targetRow: target, targetCol: maxCol,
+    };
+    applyFillPattern();
+  }
+
+  function applyFillCells(steps: HistoryStep[]) {
     const d = ctx.fillDrag;
     if (!d) return;
     // Clear fillDrag FIRST so a thrown error doesn't leave the grid
@@ -118,7 +203,8 @@ export function createClipboard<
           for (let i = 0; i < targetRows; i += 1) {
             const targetRow = d.sourceMaxRow + 1 + i;
             if (ctx.isCellEditableAt(targetRow, c))
-              writeCellRaw(targetRow, column.id, fills[i]);
+              writeFilled(steps, targetRow, column.id,
+                filledValue(sourceColValues, fills, i, d.sourceMinRow, d.sourceMaxRow + 1, 1, "rows", targetRow, column.id));
           }
         }
         if (newMinRow < d.sourceMinRow) {
@@ -129,7 +215,8 @@ export function createClipboard<
           for (let i = 0; i < targetRows; i += 1) {
             const targetRow = d.sourceMinRow - 1 - i;
             if (ctx.isCellEditableAt(targetRow, c))
-              writeCellRaw(targetRow, column.id, fills[i]);
+              writeFilled(steps, targetRow, column.id,
+                filledValue(reversed, fills, i, d.sourceMaxRow, d.sourceMinRow - 1, -1, "rows", targetRow, column.id));
           }
         }
       }
@@ -150,7 +237,8 @@ export function createClipboard<
             const targetCol = d.sourceMaxCol + 1 + i;
             const col = ctx.allColumns[targetCol];
             if (col && ctx.isCellEditableAt(r, targetCol))
-              writeCellRaw(r, col.id, fills[i]);
+              writeFilled(steps, r, col.id,
+                filledValue(sourceRowValues, fills, i, d.sourceMinCol, d.sourceMaxCol + 1, 1, "cols", r, col.id));
           }
         }
         if (newMinCol < d.sourceMinCol) {
@@ -161,7 +249,8 @@ export function createClipboard<
             const targetCol = d.sourceMinCol - 1 - i;
             const col = ctx.allColumns[targetCol];
             if (col && ctx.isCellEditableAt(r, targetCol))
-              writeCellRaw(r, col.id, fills[i]);
+              writeFilled(steps, r, col.id,
+                filledValue(reversed, fills, i, d.sourceMaxCol, d.sourceMinCol - 1, -1, "cols", r, col.id));
           }
         }
       }
@@ -618,17 +707,10 @@ export function createClipboard<
       }
     }
 
-    // One undo entry per changed cell, appended together so a single Ctrl+Z
-    // sequence walks the whole move back. Same shape and truncation rule as
-    // a whole-row commit.
-    if (steps.length) {
-      let hist = ctx.history.slice(0, ctx.historyPtr + 1);
-      for (const step of steps) hist.push(step);
-      if (hist.length > ctx.UNDO_LIMIT) hist = hist.slice(hist.length - ctx.UNDO_LIMIT);
-      ctx.history = hist;
-      ctx.historyPtr = ctx.history.length - 1;
-      ctx.historyVersion += 1;
-    }
+    // The whole move is ONE undo entry. It used to be one step per changed
+    // cell, so walking a 15x20 move back took 300 presses of Ctrl+Z and blew
+    // past UNDO_LIMIT, evicting every step behind it.
+    pushHistory(ctx, steps, nextGroupId());
 
     // Follow the values: the range stays selected where it landed, so a
     // second drag can chain off the first the way it does in a spreadsheet.
@@ -679,6 +761,40 @@ export function createClipboard<
     legacyCopyText(text);
   }
 
+  /**
+   * Text and HTML together. The `copy` event is the first path: a listener
+   * armed for this one call puts both types on the event's clipboardData
+   * while the legacy textarea copy runs, which works in a secure and an
+   * insecure context alike and keeps every attribute of the HTML. Only when
+   * the browser refuses that does the async `ClipboardItem` write run, and
+   * text alone after that.
+   */
+  function writeClipboard(text: string, html: string) {
+    if (typeof document !== "undefined") {
+      let armed = true;
+      const onCopy = (event: ClipboardEvent) => {
+        if (!armed || !event.clipboardData) return;
+        armed = false;
+        event.clipboardData.setData("text/plain", text);
+        event.clipboardData.setData("text/html", html);
+        event.preventDefault();
+      };
+      document.addEventListener("copy", onCopy, { once: true, capture: true });
+      const ok = legacyCopyText(text);
+      document.removeEventListener("copy", onCopy, { capture: true });
+      if (ok && !armed) return;
+    }
+    if (navigator.clipboard?.write && typeof ClipboardItem !== "undefined") {
+      const item = new ClipboardItem({
+        "text/plain": new Blob([text], { type: "text/plain" }),
+        "text/html": new Blob([html], { type: "text/html" }),
+      });
+      void navigator.clipboard.write([item]).catch(() => writeClipboardText(text));
+      return;
+    }
+    writeClipboardText(text);
+  }
+
   function legacyCopyText(text: string): boolean {
     if (typeof document === "undefined") return false;
     const active = document.activeElement as HTMLElement | null;
@@ -759,7 +875,13 @@ export function createClipboard<
       }
       blocks.push(lines.join("\n"));
     }
-    writeClipboardText(blocks.join("\n\n"));
+    const text = blocks.join("\n\n");
+    const toHtml = ctx.props.clipboardHtml as
+      | ((params: { rects: typeof rects; text: string }) => string | null | undefined)
+      | undefined;
+    const html = toHtml?.({ rects, text });
+    if (html) writeClipboard(text, html);
+    else writeClipboardText(text);
   }
 
   /**
@@ -786,6 +908,10 @@ export function createClipboard<
       newValue: unknown
       row: TData
     }> = [];
+    // One history step per cleared cell, grouped, so Delete over a block is
+    // one Ctrl+Z. Clearing used to record nothing at all: the values were
+    // gone and undo skipped straight past them to whatever came before.
+    const steps: HistoryStep[] = [];
     const dataIndexOf = createDataIndexLookup(next);
     for (let r = startRow; r <= endRow; r += 1) {
       const row = ctx.allRows[r];
@@ -813,6 +939,7 @@ export function createClipboard<
         const cleared = parseEditorValue(editorType, "");
         updated[field] = cleared;
         rowChanged = true;
+        steps.push({ rowId: row.id, columnId: column.id, field, before: oldValue, after: cleared });
         changes.push({
           rowIndex: dataIndex,
           columnId: column.id,
@@ -829,6 +956,7 @@ export function createClipboard<
     if (mutated) {
       ctx.internalData = next;
       ctx.grid.store.setState((prev: any) => ({ ...prev }));
+      pushHistory(ctx, steps, nextGroupId());
       // Fire onCellValueChange per cleared cell - same as paste's writeCellRaw -
       // so consumers (formula engines, autosave) recompute. Clear IS a value
       // change; without this, a HyperFormula-backed grid wouldn't re-evaluate.
@@ -857,6 +985,7 @@ export function createClipboard<
     startFillDrag,
     onFillPointerMove,
     onFillPointerUp,
+    fillDownToNeighbour,
     isOnMoveGrabStrip,
     startMoveDrag,
     onMovePointerMove,

package/src/column-resize.ts

@@ -27,6 +27,9 @@ export type ColumnResizeOptions = {
   getWidth: (columnId: string) => number
   /** Called on every animation frame of the drag, and once at the end. */
   onResize: (columnId: string, width: number) => void
+  /** Called once when a drag ends or an arrow key has resized, with the
+   *  width the gesture started from: what an undo puts back. */
+  onResizeEnd?: (columnId: string, width: number, startWidth: number) => void
   /** Accessible name for the handle. Defaults to the column id. */
   label?: (columnId: string) => string
   /**
@@ -90,6 +93,7 @@ export function columnResize(node: HTMLElement, opts: ColumnResizeOptions) {
     // Commit the final width even if the last frame was cancelled mid-flight.
     pendingWidth = Math.max(minWidth(), drag.startWidth + (e.clientX - drag.startX))
     commit()
+    current.onResizeEnd?.(drag.columnId, pendingWidth, drag.startWidth)
     drag.handle.classList.remove('is-resizing')
     syncAria(drag.handle, drag.columnId)
     try {
@@ -144,8 +148,10 @@ export function columnResize(node: HTMLElement, opts: ColumnResizeOptions) {
     if (!columnId || current.canResize?.(columnId) === false) return
     e.preventDefault()
     e.stopPropagation()
-    const next = Math.max(minWidth(), Math.round(current.getWidth(columnId) + delta))
+    const start = current.getWidth(columnId)
+    const next = Math.max(minWidth(), Math.round(start + delta))
     current.onResize(columnId, next)
+    current.onResizeEnd?.(columnId, next, start)
     syncAria(t, columnId)
   }
 

package/src/columns.ts

@@ -161,6 +161,8 @@ export function createColumns<
   }
 
   function getColumnWidth(columnId: string) {
+    // Collapsed: no room at all, whatever width it keeps for later.
+    if (ctx.collapsedColumns?.[columnId]) return 0;
     const fitted = ctx.fittedColumnWidths?.[columnId];
     if (fitted !== undefined && ctx.columnWidths[columnId] === undefined)
       return fitted;

package/src/command-context.test.ts

@@ -0,0 +1,200 @@
+/**
+ * The command context handed to registered keyboard shortcuts.
+ *
+ * The interesting part is `setCellValue`: it is the only writer a command
+ * touches, so if it does not record history then every sheet command ships
+ * un-undoable no matter how carefully `cmd.batch` groups. These tests hold
+ * that behaviour down, along with the index-space contract (display indices
+ * in, `readCellRaw` / `writeCellRaw` out) that the getters exist for.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { buildCommandContext } from './command-context'
+import { undoHistory, type HistoryStep } from './history'
+
+function makeCtx(values: Record<string, unknown> = {}) {
+  const store: Record<string, unknown> = { ...values }
+  const key = (r: number, columnId: string) => `${r}:${columnId}`
+  const ctx: any = {
+    allRows: [{ id: 'r1' }, { id: 'r2' }, { id: 'r3' }],
+    allColumns: [
+      { id: 'a', columnDef: { field: 'a' } },
+      { id: 'b', columnDef: { field: 'b' } },
+    ],
+    history: [] as HistoryStep[],
+    historyPtr: -1,
+    historyVersion: 0,
+    historyGroupId: undefined as string | undefined,
+    UNDO_LIMIT: 200,
+    grid: { getState: () => ({ activeCell: { rowIndex: 0, colIndex: 0 } }) },
+    getSelectionRects: () => [],
+    readCellRaw: (r: number, columnId: string) => store[key(r, columnId)],
+    writeCellRaw: vi.fn((r: number, columnId: string, value: unknown) => {
+      if (store[key(r, columnId)] === value) return
+      store[key(r, columnId)] = value
+    }),
+    applyHistoryStep: vi.fn((s: HistoryStep, direction: 'undo' | 'redo') => {
+      store[key(Number(s.rowId.slice(1)) - 1, s.columnId)] =
+        direction === 'undo' ? s.before : s.after
+    }),
+    setActiveCell: vi.fn(),
+    setSelection: vi.fn(),
+    extendSelection: vi.fn(),
+    scrollActiveCellIntoView: vi.fn(),
+    gridRootEl: { focus: vi.fn() },
+    pasteFromClipboard: vi.fn(async () => {}),
+    copySelectionToClipboard: vi.fn(),
+    cutSelectionToClipboard: vi.fn(async () => {}),
+    buildApi: () => ({}),
+  }
+  return { ctx, store, key }
+}
+
+describe('setCellValue records history', () => {
+  it('pushes one step per changed cell', () => {
+    const { ctx } = makeCtx({ '0:a': 1 })
+    const cmd = buildCommandContext(ctx, false)
+    cmd.setCellValue(0, 0, 9)
+    expect(ctx.history).toEqual([
+      { rowId: 'r1', columnId: 'a', field: 'a', before: 1, after: 9 },
+    ])
+    expect(ctx.historyPtr).toBe(0)
+  })
+
+  it('pushes nothing when the value is unchanged', () => {
+    const { ctx } = makeCtx({ '0:a': 1 })
+    const cmd = buildCommandContext(ctx, false)
+    cmd.setCellValue(0, 0, 1)
+    expect(ctx.history).toEqual([])
+    expect(ctx.historyPtr).toBe(-1)
+  })
+
+  it('pushes nothing for a column index that does not exist', () => {
+    const { ctx } = makeCtx()
+    const cmd = buildCommandContext(ctx, false)
+    cmd.setCellValue(0, 99, 'x')
+    expect(ctx.writeCellRaw).not.toHaveBeenCalled()
+    expect(ctx.history).toEqual([])
+  })
+
+  it('reads `before` from the cell rather than from the new value', () => {
+    const { ctx } = makeCtx({ '1:b': 'old' })
+    const cmd = buildCommandContext(ctx, false)
+    cmd.setCellValue(1, 1, 'new')
+    expect(ctx.history[0]).toMatchObject({ rowId: 'r2', before: 'old', after: 'new' })
+  })
+})
+
+describe('cmd.canEdit', () => {
+  it('asks the editing layer, in display index space', () => {
+    const { ctx } = makeCtx()
+    ctx.isCellEditableAt = vi.fn((r: number, c: number) => !(r === 1 && c === 0))
+    const cmd = buildCommandContext(ctx, false)
+    expect(cmd.canEdit!(0, 0)).toBe(true)
+    expect(cmd.canEdit!(1, 0)).toBe(false)
+    expect(ctx.isCellEditableAt).toHaveBeenCalledWith(1, 0)
+  })
+
+  it('says yes when the controller has no editing layer', () => {
+    const { ctx } = makeCtx()
+    expect(buildCommandContext(ctx, false).canEdit!(2, 1)).toBe(true)
+  })
+})
+
+describe('cmd.focus', () => {
+  it('focuses the grid root without scrolling it', () => {
+    const { ctx } = makeCtx()
+    buildCommandContext(ctx, false).focus()
+    expect(ctx.gridRootEl.focus).toHaveBeenCalledWith({ preventScroll: true })
+  })
+
+  it('is a no-op before the grid has mounted', () => {
+    const { ctx } = makeCtx()
+    ctx.gridRootEl = null
+    expect(() => buildCommandContext(ctx, false).focus()).not.toThrow()
+  })
+})
+
+describe('cmd.recordUndo', () => {
+  it('puts a non-cell step in the history that undo and redo call back', () => {
+    const { ctx } = makeCtx()
+    const cmd = buildCommandContext(ctx, false)
+    const undo = vi.fn()
+    const redo = vi.fn()
+    cmd.recordUndo(undo, redo)
+    expect(ctx.history).toHaveLength(1)
+    expect(ctx.history[0].custom).toEqual({ undo, redo })
+    undoHistory(ctx)
+    expect(ctx.applyHistoryStep).toHaveBeenCalledWith(expect.objectContaining({ custom: { undo, redo } }), 'undo')
+  })
+
+  it('joins the batch it is recorded inside, so cells and formats undo together', () => {
+    const { ctx } = makeCtx({ '0:a': 1 })
+    const cmd = buildCommandContext(ctx, false)
+    cmd.batch(() => {
+      cmd.setCellValue(0, 0, 2)
+      cmd.recordUndo(() => {}, () => {})
+    })
+    expect(ctx.history).toHaveLength(2)
+    expect(ctx.history[0].groupId).toBeDefined()
+    expect(ctx.history[1].groupId).toBe(ctx.history[0].groupId)
+  })
+})
+
+describe('cmd.editor', () => {
+  it('is the open inline editor element, and null when nothing is being edited', () => {
+    const { ctx } = makeCtx()
+    const root = document.createElement('div')
+    ctx.gridRootEl = root
+    expect(buildCommandContext(ctx, false).editor).toBeNull()
+    const input = document.createElement('input')
+    input.className = 'sv-grid-cell-editor'
+    root.appendChild(input)
+    expect(buildCommandContext(ctx, true).editor).toBe(input)
+  })
+})
+
+describe('cmd.paste', () => {
+  it('routes to the grid clipboard paste, the same path Ctrl+V takes', async () => {
+    const { ctx } = makeCtx()
+    await buildCommandContext(ctx, false).paste()
+    expect(ctx.pasteFromClipboard).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('cmd.copy and cmd.cut', () => {
+  it('route to the selection copy and cut, the paths Ctrl+C and Ctrl+X take', async () => {
+    const { ctx } = makeCtx()
+    const cmd = buildCommandContext(ctx, false)
+    cmd.copy()
+    expect(ctx.copySelectionToClipboard).toHaveBeenCalledTimes(1)
+    await cmd.cut()
+    expect(ctx.cutSelectionToClipboard).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('cmd.batch groups the steps it writes', () => {
+  it('makes a multi-cell command ONE undo', () => {
+    const { ctx, store } = makeCtx({ '0:a': 1, '1:a': 2, '2:a': 3 })
+    const cmd = buildCommandContext(ctx, false)
+    cmd.batch(() => {
+      cmd.setCellValue(0, 0, 'x')
+      cmd.setCellValue(1, 0, 'x')
+      cmd.setCellValue(2, 0, 'x')
+    })
+    const ids = ctx.history.map((s: HistoryStep) => s.groupId)
+    expect(ids).toHaveLength(3)
+    expect(new Set(ids).size).toBe(1)
+    expect(ids[0]).toBeTruthy()
+
+    expect(undoHistory(ctx)).toBe(true)
+    expect([store['0:a'], store['1:a'], store['2:a']]).toEqual([1, 2, 3])
+    expect(ctx.historyPtr).toBe(-1)
+  })
+
+  it('leaves a lone write outside a batch ungrouped', () => {
+    const { ctx } = makeCtx({ '0:a': 1 })
+    const cmd = buildCommandContext(ctx, false)
+    cmd.setCellValue(0, 0, 'x')
+    expect(ctx.history[0].groupId).toBeUndefined()
+  })
+})