@svgrid/grid 3.0.2 → 3.0.4

package/src/keyboard-handlers.coverage.test.ts

@@ -54,6 +54,10 @@ function makeCtx(overrides: Partial<any> = {}) {
     extendSelection: vi.fn(),
     setSelection: vi.fn(),
     closeMenus: vi.fn(),
+    tabRunOrigin: null,
+    activeRangeRect: () => null,
+    isRowCollapsed: () => false,
+    collapsedColumns: {},
     ...overrides,
   }
   ctx._state = state
@@ -344,12 +348,32 @@ describe('onGridKeyDown / navigation', () => {
     expect(ctx.extendSelection).not.toHaveBeenCalled()
   })
 
-  it('Shift+ArrowRight extends the selection rectangle', () => {
-    const ctx = navCtx()
+  it('Shift+ArrowRight extends the selection rectangle and leaves the active cell', () => {
+    const ctx = navCtx({
+      selectionRange: { anchor: { rowIndex: 1, colIndex: 1 }, focus: { rowIndex: 1, colIndex: 1 } },
+    })
     const { onGridKeyDown } = createKeyboard(ctx)
     onGridKeyDown(rootKeyEvent({ key: 'ArrowRight', shiftKey: true }))
-    expect(ctx.setActiveCell).toHaveBeenCalledWith(1, 2)
+    expect(ctx.setActiveCell).not.toHaveBeenCalled()
     expect(ctx.extendSelection).toHaveBeenCalledWith(1, 2)
+    expect(ctx.scrollActiveCellIntoView).toHaveBeenCalledWith(1, 2)
+    expect(ctx.setSelection).not.toHaveBeenCalled()
+  })
+
+  it('Shift+Home, Shift+PageDown and Ctrl+Shift+Home grow the range to where the plain key goes', () => {
+    const ctx = navCtx({
+      selectionRange: { anchor: { rowIndex: 1, colIndex: 1 }, focus: { rowIndex: 3, colIndex: 2 } },
+    })
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'Home', shiftKey: true }))
+    expect(ctx.extendSelection).toHaveBeenLastCalledWith(3, 0)
+    onGridKeyDown(rootKeyEvent({ key: 'Home', shiftKey: true, ctrlKey: true }))
+    expect(ctx.extendSelection).toHaveBeenLastCalledWith(0, 0)
+    onGridKeyDown(rootKeyEvent({ key: 'PageDown', shiftKey: true }))
+    const [row, col] = ctx.extendSelection.mock.lastCall
+    expect(col).toBe(2)
+    expect(row).toBeGreaterThan(3)
+    expect(ctx.setActiveCell).not.toHaveBeenCalled()
     expect(ctx.setSelection).not.toHaveBeenCalled()
   })
 
@@ -364,13 +388,109 @@ describe('onGridKeyDown / navigation', () => {
     expect(ctx.setSelection).toHaveBeenCalledWith(1, 0)
   })
 
-  it('Shift+Enter (moveUp) DOES extend the selection (arrow-family intent)', () => {
+  it('Shift+Arrow grows from the far corner of the range, not from the active cell', () => {
+    const ctx = navCtx({
+      selectionRange: { anchor: { rowIndex: 1, colIndex: 1 }, focus: { rowIndex: 3, colIndex: 2 } },
+    })
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'ArrowDown', shiftKey: true }))
+    expect(ctx.extendSelection).toHaveBeenCalledWith(4, 2)
+    expect(ctx.setActiveCell).not.toHaveBeenCalled()
+  })
+
+  it('Shift+Arrow with nothing anchored anchors at the active cell first', () => {
+    const ctx = navCtx({ selectionRange: { anchor: null, focus: null } })
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'ArrowDown', shiftKey: true }))
+    expect(ctx.setSelection).toHaveBeenCalledWith(1, 1)
+    expect(ctx.extendSelection).toHaveBeenCalledWith(2, 1)
+  })
+
+  it('Shift+Arrow moves the active cell when cell selection is off', () => {
+    const ctx = navCtx({ enableCellSelectionEffective: false })
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'ArrowDown', shiftKey: true }))
+    expect(ctx.setActiveCell).toHaveBeenCalledWith(2, 1)
+    expect(ctx.extendSelection).not.toHaveBeenCalled()
+  })
+
+  it('Ctrl+V with onPasteClipboard leaves the key to the browser and arms the async fallback', () => {
+    const arm = vi.fn()
+    const ctx = navCtx({ props: { rowHeight: 30, onPasteClipboard: () => true }, armPasteFallback: arm, pasteFromClipboard: vi.fn() })
+    const { onGridKeyDown } = createKeyboard(ctx)
+    const ev = rootKeyEvent({ key: 'v', ctrlKey: true })
+    onGridKeyDown(ev)
+    expect(ev.defaultPrevented).toBe(false)
+    expect(arm).toHaveBeenCalledTimes(1)
+    expect(ctx.pasteFromClipboard).not.toHaveBeenCalled()
+  })
+
+  it('Shift+Enter moves up without extending the selection', () => {
+    // Shift+Enter shares the moveUp intent with Shift+ArrowUp, and used to
+    // grow the range like the arrow does. In Excel it only reverses Enter.
     const ctx = navCtx()
     const { onGridKeyDown } = createKeyboard(ctx)
     onGridKeyDown(rootKeyEvent({ key: 'Enter', shiftKey: true }))
-    // Enter+shift -> moveUp, which is in the extend set.
     expect(ctx.setActiveCell).toHaveBeenCalledWith(0, 1)
-    expect(ctx.extendSelection).toHaveBeenCalledWith(0, 1)
+    expect(ctx.setSelection).toHaveBeenCalledWith(0, 1)
+    expect(ctx.extendSelection).not.toHaveBeenCalled()
+  })
+
+  it('Enter after a run of Tabs goes down from the column the run began in', () => {
+    const ctx = navCtx({ state: { activeCell: { rowIndex: 0, colIndex: 0, cellId: null } } })
+    // The fake setActiveCell does what the real one does: forgets the run.
+    ctx.setActiveCell = vi.fn((r: number, c: number) => {
+      const prev = ctx._state.activeCell
+      if (!prev || prev.rowIndex !== r || prev.colIndex !== c) ctx.tabRunOrigin = null
+      ctx._state.activeCell = { rowIndex: r, colIndex: c, cellId: null }
+    })
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'Tab' }))
+    onGridKeyDown(rootKeyEvent({ key: 'Tab' }))
+    expect(ctx._state.activeCell).toMatchObject({ rowIndex: 0, colIndex: 2 })
+    expect(ctx.tabRunOrigin).toBe(0)
+    onGridKeyDown(rootKeyEvent({ key: 'Enter' }))
+    expect(ctx._state.activeCell).toMatchObject({ rowIndex: 1, colIndex: 0 })
+    expect(ctx.tabRunOrigin).toBe(null)
+    expect(ctx.setSelection).toHaveBeenLastCalledWith(1, 0)
+  })
+
+  it('an arrow between the Tabs ends the run', () => {
+    const ctx = navCtx({ state: { activeCell: { rowIndex: 0, colIndex: 0, cellId: null } } })
+    ctx.setActiveCell = vi.fn((r: number, c: number) => {
+      const prev = ctx._state.activeCell
+      if (!prev || prev.rowIndex !== r || prev.colIndex !== c) ctx.tabRunOrigin = null
+      ctx._state.activeCell = { rowIndex: r, colIndex: c, cellId: null }
+    })
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'Tab' }))
+    onGridKeyDown(rootKeyEvent({ key: 'ArrowRight' }))
+    expect(ctx.tabRunOrigin).toBe(null)
+    onGridKeyDown(rootKeyEvent({ key: 'Enter' }))
+    expect(ctx._state.activeCell).toMatchObject({ rowIndex: 1, colIndex: 2 })
+  })
+
+  it('Enter and Tab stay inside a selected block and keep the selection', () => {
+    const ctx = navCtx({
+      state: { activeCell: { rowIndex: 1, colIndex: 1, cellId: null } },
+      activeRangeRect: () => ({ minRow: 1, maxRow: 2, minCol: 1, maxCol: 2 }),
+    })
+    ctx.setActiveCell = vi.fn((r: number, c: number) => {
+      const prev = ctx._state.activeCell
+      if (!prev || prev.rowIndex !== r || prev.colIndex !== c) ctx.tabRunOrigin = null
+      ctx._state.activeCell = { rowIndex: r, colIndex: c, cellId: null }
+    })
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'Enter' }))
+    expect(ctx._state.activeCell).toMatchObject({ rowIndex: 2, colIndex: 1 })
+    onGridKeyDown(rootKeyEvent({ key: 'Enter' }))
+    expect(ctx._state.activeCell).toMatchObject({ rowIndex: 1, colIndex: 2 })
+    onGridKeyDown(rootKeyEvent({ key: 'Tab' }))
+    expect(ctx._state.activeCell).toMatchObject({ rowIndex: 2, colIndex: 1 })
+    onGridKeyDown(rootKeyEvent({ key: 'Tab', shiftKey: true }))
+    expect(ctx._state.activeCell).toMatchObject({ rowIndex: 1, colIndex: 2 })
+    expect(ctx.setSelection).not.toHaveBeenCalled()
+    expect(ctx.extendSelection).not.toHaveBeenCalled()
   })
 
   it('Tab moves right and wraps using getNextActiveCell', () => {

package/src/keyboard-handlers.ts

@@ -7,7 +7,11 @@ import {
 } from "./index";
 import "./sv-grid-scrollbar";
 
-import { getKeyboardIntent, getNextActiveCell } from "./keyboard";
+import { getKeyboardIntent, getNextActiveCell, getEntryStep, pastCollapsed } from "./keyboard";
+import { stepPastMerge } from "./merges";
+import { hasGridShortcuts, runGridShortcuts } from "./shortcut-registry";
+import { undoHistory, redoHistory } from "./history";
+import { buildCommandContext } from "./command-context";
 
 export function createKeyboard<
   TFeatures extends TableFeatures = TableFeatures,
@@ -16,7 +20,21 @@ export function createKeyboard<
   function onGridKeyDown(event: KeyboardEvent) {
     // Only the grid root drives navigation - keys on header buttons, menus,
     // or the cell editor are handled by those controls themselves.
+    //
+    // The command chain runs AFTER this guard, not before. Running it first
+    // meant a key typed into a filter-row input reached the sheet commands,
+    // so Ctrl+A or Ctrl+D while filtering mutated grid cells. The editor has
+    // its own chain call in editing.ts, which is what Alt+Enter needs.
     if (event.target !== event.currentTarget) return;
+
+    // Registered commands get the key BEFORE the grid interprets it. That is
+    // how @svgrid/enterprise binds Ctrl+Arrow, Ctrl+D and the rest without
+    // widening the closed GridKeyboardIntent union, which is public API. A
+    // grid with nothing registered pays one array-length read.
+    if (hasGridShortcuts() && runGridShortcuts(event, buildCommandContext(ctx, false))) {
+      return;
+    }
+
     if (ctx.editingCell) return;
 
     if ((event.ctrlKey || event.metaKey) && !event.altKey) {
@@ -27,6 +45,14 @@ export function createKeyboard<
         return;
       }
       if (lower === "v") {
+        // A consumer taking the paste over wants the browser's own `paste`
+        // event, which carries the clipboard's HTML unsanitised; the key is
+        // left alone and the async API is armed as the fallback for a
+        // browser that never delivers the event to a non-editable element.
+        if (ctx.props.onPasteClipboard) {
+          ctx.armPasteFallback();
+          return;
+        }
         // Secure context: read via the async Clipboard API and swallow the
         // key. Insecure context (no navigator.clipboard): DON'T preventDefault
         // so the browser delivers a native `paste` event to `onGridPaste`.
@@ -45,26 +71,12 @@ export function createKeyboard<
       // and Ctrl+Y both redo. Mirrors VSCode / Sheets / Excel.
       if (lower === "z" && !event.shiftKey) {
         event.preventDefault()
-        if (ctx.historyPtr >= 0) {
-          const step = ctx.history[ctx.historyPtr]
-          if (step) {
-            ctx.applyHistoryStep(step, 'undo')
-            ctx.historyPtr -= 1
-            ctx.historyVersion += 1
-          }
-        }
+        undoHistory(ctx)
         return
       }
       if ((lower === "z" && event.shiftKey) || lower === "y") {
         event.preventDefault()
-        if (ctx.historyPtr < ctx.history.length - 1) {
-          const step = ctx.history[ctx.historyPtr + 1]
-          if (step) {
-            ctx.applyHistoryStep(step, 'redo')
-            ctx.historyPtr += 1
-            ctx.historyVersion += 1
-          }
-        }
+        redoHistory(ctx)
         return
       }
       // Ctrl+F opens the find overlay.
@@ -204,25 +216,74 @@ export function createKeyboard<
       const usable = Math.max(0, clientHeight - headerHeight)
       return Math.max(1, Math.floor(usable / Math.max(rowHeight, 1)) - 1)
     }
-    const next = getNextActiveCell(current, intent, {
+    const bounds = {
       maxRow: Math.max(ctx.allRows.length - 1, 0),
       maxCol: Math.max(ctx.allColumns.length - 1, 0),
-      pageSize: pageStep(),
-    });
-    ctx.setActiveCell(next.rowIndex, next.colIndex);
-    ctx.scrollActiveCellIntoView(next.rowIndex, next.colIndex);
-    // Shift extends the selection ONLY for arrow keys (Excel-style).
-    // Shift+Enter / Shift+Tab just change direction; they don't grow the
-    // range, otherwise hammering Shift+Tab to backspace through a row
-    // would paint a creeping rectangle behind the cursor.
-    const shouldExtend =
+    };
+    // Collapsed rows and columns are stepped over, as a sheet's hidden ones.
+    const collapsed = {
+      isRowCollapsed: (i: number) => ctx.isRowCollapsed(i) as boolean,
+      isColumnCollapsed: (i: number) => !!ctx.collapsedColumns[ctx.allColumns[i]?.id],
+    };
+    // Enter and Tab are entry keys: they remember a Tab run and stay inside
+    // a selected block (getEntryStep). ArrowDown shares the moveDown intent
+    // and is a plain move, hence the key check.
+    if (
+      (event.key === "Enter" || event.key === "Tab") &&
+      (intent === "moveDown" || intent === "moveUp" || intent === "tabNext" || intent === "tabPrev")
+    ) {
+      const step = getEntryStep(current, intent, {
+        ...bounds,
+        tabOrigin: ctx.tabRunOrigin,
+        range: ctx.activeRangeRect(),
+        collapsed,
+      });
+      const landed = stepPastMerge(ctx.mergeIndex, current, step.cell, bounds);
+      ctx.setActiveCell(landed.rowIndex, landed.colIndex);
+      ctx.tabRunOrigin = step.tabOrigin;
+      ctx.scrollActiveCellIntoView(landed.rowIndex, landed.colIndex);
+      if (!step.withinRange) ctx.setSelection(landed.rowIndex, landed.colIndex);
+      return;
+    }
+    // Shift+Arrow grows the range from its far corner, and the active cell
+    // stays where it is, as in Excel: it is the cell the formula bar shows
+    // and the one the next keystroke edits. Shift+Home, Shift+End,
+    // Shift+PageUp / PageDown and Ctrl+Shift+Home / End grow it the same
+    // way, to where the plain key would have moved. Shift+Enter and
+    // Shift+Tab never come this way (they are entry keys, above), so
+    // hammering Shift+Tab back through a row cannot paint a creeping
+    // rectangle. A grid without cell selection has no range to grow and
+    // moves the active cell instead.
+    const extending =
       event.shiftKey &&
+      ctx.enableCellSelectionEffective !== false &&
       (intent === "moveLeft" ||
         intent === "moveRight" ||
         intent === "moveUp" ||
-        intent === "moveDown");
-    if (shouldExtend) ctx.extendSelection(next.rowIndex, next.colIndex);
-    else ctx.setSelection(next.rowIndex, next.colIndex);
+        intent === "moveDown" ||
+        intent === "rowStart" ||
+        intent === "rowEnd" ||
+        intent === "pageUp" ||
+        intent === "pageDown" ||
+        intent === "gridStart" ||
+        intent === "gridEnd");
+    if (extending) {
+      const anchored = !!ctx.selectionRange?.anchor;
+      if (!anchored) ctx.setSelection(current.rowIndex, current.colIndex);
+      const from = anchored ? ctx.selectionRange.focus ?? current : current;
+      const next = stepPastMerge(ctx.mergeIndex, from, pastCollapsed(from, getNextActiveCell(from, intent, { ...bounds, pageSize: pageStep() }), bounds, collapsed), bounds);
+      ctx.extendSelection(next.rowIndex, next.colIndex);
+      // Scroll along the axis of the key only, as Excel does: Shift+Right
+      // brings the new column into view without moving the rows, so a
+      // whole-column selection (its far corner on the last row) stays put.
+      const sideways = intent === "moveLeft" || intent === "moveRight" || intent === "rowStart" || intent === "rowEnd";
+      ctx.scrollActiveCellIntoView(sideways ? current.rowIndex : next.rowIndex, sideways ? next.colIndex : current.colIndex);
+      return;
+    }
+    const next = stepPastMerge(ctx.mergeIndex, current, pastCollapsed(current, getNextActiveCell(current, intent, { ...bounds, pageSize: pageStep() }), bounds, collapsed), bounds);
+    ctx.setActiveCell(next.rowIndex, next.colIndex);
+    ctx.scrollActiveCellIntoView(next.rowIndex, next.colIndex);
+    ctx.setSelection(next.rowIndex, next.colIndex);
   }
 
   function onWindowKeydown(event: KeyboardEvent) {

package/src/keyboard-shortcuts.seam.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it, beforeEach, vi } from 'vitest'
+import { createKeyboard } from './keyboard-handlers'
+import { getKeyboardIntent } from './keyboard'
+import { registerGridShortcuts, clearGridShortcuts } from './shortcut-registry'
+
+// Same harness shape as keyboard-handlers.coverage.test.ts: a fake controller
+// ctx that records side effects, and real jsdom KeyboardEvents so modifier
+// flags and target/currentTarget behave.
+function makeCtx(overrides: Partial<any> = {}) {
+  const state: any = { activeCell: { rowIndex: 2, colIndex: 1, cellId: null }, sorting: [] }
+  const ctx: any = {
+    editingCell: null,
+    findOpen: false,
+    history: [],
+    historyPtr: -1,
+    historyVersion: 0,
+    historyGroupId: undefined,
+    UNDO_LIMIT: 200,
+    headerHeight: 30,
+    scrollContainer: { clientHeight: 330 },
+    props: { rowHeight: 30 },
+    allRows: [{}, {}, {}, {}],
+    allColumns: [{ id: 'a' }, { id: 'b' }, { id: 'c' }],
+    grid: { getState: () => state, store: { setState: vi.fn() } },
+    buildApi: () => ({}),
+    getSelectionRects: () => [{ minRow: 2, minCol: 1, maxRow: 2, maxCol: 1 }],
+    readCellRaw: vi.fn(() => 'v'),
+    writeCellRaw: vi.fn(),
+    copySelectionToClipboard: vi.fn(),
+    pasteFromClipboard: vi.fn(() => Promise.resolve()),
+    cutSelectionToClipboard: vi.fn(() => Promise.resolve()),
+    applyHistoryStep: vi.fn(),
+    clearSelectedCells: vi.fn(() => false),
+    clearSelectedCellValues: vi.fn(),
+    onCellDoubleClick: vi.fn(),
+    startEditingWithChar: vi.fn(() => true),
+    toggleBooleanCell: vi.fn(),
+    setActiveCell: vi.fn(),
+    scrollActiveCellIntoView: vi.fn(),
+    extendSelection: vi.fn(),
+    setSelection: vi.fn(),
+    closeMenus: vi.fn(),
+    tabRunOrigin: null,
+    activeRangeRect: () => null,
+    isRowCollapsed: () => false,
+    collapsedColumns: {},
+    ...overrides,
+  }
+  return ctx
+}
+
+function rootKeyEvent(init: KeyboardEventInit) {
+  const el = document.createElement('div')
+  const event = new KeyboardEvent('keydown', { cancelable: true, ...init })
+  Object.defineProperty(event, 'target', { value: el })
+  Object.defineProperty(event, 'currentTarget', { value: el })
+  return event
+}
+
+beforeEach(() => clearGridShortcuts())
+
+describe('the shortcut chain inside onGridKeyDown', () => {
+  it('lets a handler claim a key the grid would otherwise interpret', () => {
+    registerGridShortcuts((e) => e.key === 'ArrowDown' && e.ctrlKey)
+    const ctx = makeCtx()
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'ArrowDown', ctrlKey: true }))
+    expect(ctx.setActiveCell).not.toHaveBeenCalled()
+  })
+
+  it('claims a key the grid DOES implement, so enterprise can reclaim it', () => {
+    // Ctrl+C is copy in the free grid. A registered handler taking it first is
+    // what lets a sheet put formulas and formats on the clipboard instead.
+    registerGridShortcuts(() => true)
+    const ctx = makeCtx()
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'c', ctrlKey: true }))
+    expect(ctx.copySelectionToClipboard).not.toHaveBeenCalled()
+  })
+
+  it('falls through to normal navigation when the handler declines', () => {
+    registerGridShortcuts(() => false)
+    const ctx = makeCtx()
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'ArrowDown' }))
+    expect(ctx.setActiveCell).toHaveBeenCalledWith(3, 1)
+  })
+
+  it('does NOT run for a key typed into a child element', () => {
+    // The chain used to run before the grid-root guard, so a Ctrl+A or Ctrl+D
+    // typed into a filter-row input reached the sheet commands and mutated
+    // grid cells.
+    const handler = vi.fn(() => true)
+    registerGridShortcuts(handler)
+    const ctx = makeCtx()
+    const root = document.createElement('div')
+    const input = document.createElement('input')
+    const event = new KeyboardEvent('keydown', { key: 'd', ctrlKey: true, cancelable: true })
+    Object.defineProperty(event, 'target', { value: input })
+    Object.defineProperty(event, 'currentTarget', { value: root })
+    createKeyboard(ctx).onGridKeyDown(event)
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it('runs before the editing bail, so a mid-edit key still reaches a handler', () => {
+    const handler = vi.fn(() => true)
+    registerGridShortcuts(handler)
+    const ctx = makeCtx({ editingCell: { rowId: 'r1', columnId: 'a' } })
+    const { onGridKeyDown } = createKeyboard(ctx)
+    onGridKeyDown(rootKeyEvent({ key: 'Enter', altKey: true }))
+    expect(handler).toHaveBeenCalledOnce()
+  })
+
+  it('hands the handler a context describing the active cell and selection', () => {
+    let seen: any = null
+    registerGridShortcuts((_e, cmd) => {
+      seen = {
+        active: cmd.activeCell,
+        ranges: cmd.ranges,
+        rowCount: cmd.rowCount,
+        colCount: cmd.colCount,
+        editing: cmd.editing,
+      }
+      return true
+    })
+    const ctx = makeCtx()
+    createKeyboard(ctx).onGridKeyDown(rootKeyEvent({ key: 'd', ctrlKey: true }))
+    expect(seen.active).toEqual({ rowIndex: 2, colIndex: 1, columnId: 'b' })
+    expect(seen.ranges).toEqual([[2, 1, 2, 1]])
+    expect(seen.rowCount).toBe(4)
+    expect(seen.colCount).toBe(3)
+    expect(seen.editing).toBe(false)
+  })
+
+  it('reads and writes cells by display index through the context', () => {
+    registerGridShortcuts((_e, cmd) => {
+      cmd.setCellValue(0, 2, cmd.getCellValue(1, 0))
+      return true
+    })
+    const ctx = makeCtx()
+    createKeyboard(ctx).onGridKeyDown(rootKeyEvent({ key: 'd', ctrlKey: true }))
+    expect(ctx.readCellRaw).toHaveBeenCalledWith(1, 'a')
+    expect(ctx.writeCellRaw).toHaveBeenCalledWith(0, 'c', 'v')
+  })
+
+  it('does not build a context when nothing is registered', () => {
+    const ctx = makeCtx()
+    // getSelectionRects is only reached through the command context.
+    ctx.getSelectionRects = vi.fn(() => [])
+    createKeyboard(ctx).onGridKeyDown(rootKeyEvent({ key: 'ArrowDown' }))
+    expect(ctx.getSelectionRects).not.toHaveBeenCalled()
+  })
+})
+
+describe('Ctrl / Cmd + arrow', () => {
+  it('is a noop intent rather than a single-cell move', () => {
+    for (const key of ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight']) {
+      expect(getKeyboardIntent(new KeyboardEvent('keydown', { key, ctrlKey: true }))).toBe('noop')
+      expect(getKeyboardIntent(new KeyboardEvent('keydown', { key, metaKey: true }))).toBe('noop')
+    }
+  })
+
+  it('leaves a plain arrow alone', () => {
+    expect(getKeyboardIntent(new KeyboardEvent('keydown', { key: 'ArrowDown' }))).toBe('moveDown')
+  })
+
+  it('leaves Alt combinations to the browser', () => {
+    expect(
+      getKeyboardIntent(new KeyboardEvent('keydown', { key: 'ArrowLeft', ctrlKey: true, altKey: true })),
+    ).toBe('moveLeft')
+  })
+
+  it('does not move the active cell when unclaimed', () => {
+    const ctx = makeCtx()
+    createKeyboard(ctx).onGridKeyDown(rootKeyEvent({ key: 'ArrowDown', ctrlKey: true }))
+    expect(ctx.setActiveCell).not.toHaveBeenCalled()
+  })
+
+  it('still does not start an edit, since the key is not printable', () => {
+    const ctx = makeCtx()
+    createKeyboard(ctx).onGridKeyDown(rootKeyEvent({ key: 'ArrowDown', ctrlKey: true }))
+    expect(ctx.startEditingWithChar).not.toHaveBeenCalled()
+  })
+})
+
+describe('grouped undo through the keyboard', () => {
+  it('walks a whole grouped action back on one Ctrl+Z', () => {
+    const g = 'g1'
+    const ctx = makeCtx({
+      history: [
+        { rowId: 'r1', columnId: 'a', field: 'a', before: 1, after: 2, groupId: g },
+        { rowId: 'r2', columnId: 'a', field: 'a', before: 3, after: 4, groupId: g },
+      ],
+      historyPtr: 1,
+    })
+    createKeyboard(ctx).onGridKeyDown(rootKeyEvent({ key: 'z', ctrlKey: true }))
+    expect(ctx.applyHistoryStep).toHaveBeenCalledTimes(2)
+    expect(ctx.historyPtr).toBe(-1)
+  })
+})

package/src/keyboard.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { getKeyboardIntent, getNextActiveCell } from './keyboard'
+import { getKeyboardIntent, getNextActiveCell, getEntryStep, pastCollapsed } from './keyboard'
+import type { ActiveCellState } from './core'
 
 describe('keyboard navigation engine', () => {
   it('maps keys to navigation intents', () => {
@@ -57,3 +58,125 @@ describe('keyboard navigation engine', () => {
     expect(pageDown.rowIndex).toBe(20)
   })
 })
+
+describe('getEntryStep', () => {
+  const at = (rowIndex: number, colIndex: number): ActiveCellState => ({ rowIndex, colIndex, cellId: null })
+  const open = { maxRow: 9, maxCol: 9, range: null }
+
+  it('a Tab starts a run at the column it leaves, and later Tabs keep it', () => {
+    const first = getEntryStep(at(0, 0), 'tabNext', { ...open, tabOrigin: null })
+    expect(first.cell).toMatchObject({ rowIndex: 0, colIndex: 1 })
+    expect(first.tabOrigin).toBe(0)
+    const second = getEntryStep(first.cell, 'tabNext', { ...open, tabOrigin: first.tabOrigin })
+    expect(second.cell).toMatchObject({ rowIndex: 0, colIndex: 2 })
+    expect(second.tabOrigin).toBe(0)
+    const back = getEntryStep(second.cell, 'tabPrev', { ...open, tabOrigin: second.tabOrigin })
+    expect(back.cell).toMatchObject({ rowIndex: 0, colIndex: 1 })
+    expect(back.tabOrigin).toBe(0)
+  })
+
+  it('Enter after a run goes down from the run\'s first column and ends it', () => {
+    const step = getEntryStep(at(0, 2), 'moveDown', { ...open, tabOrigin: 0 })
+    expect(step.cell).toMatchObject({ rowIndex: 1, colIndex: 0 })
+    expect(step.tabOrigin).toBe(null)
+    expect(step.withinRange).toBe(false)
+    const up = getEntryStep(at(3, 5), 'moveUp', { ...open, tabOrigin: 2 })
+    expect(up.cell).toMatchObject({ rowIndex: 2, colIndex: 2 })
+  })
+
+  it('Enter with no run is a plain move down', () => {
+    const step = getEntryStep(at(0, 2), 'moveDown', { ...open, tabOrigin: null })
+    expect(step.cell).toMatchObject({ rowIndex: 1, colIndex: 2 })
+    expect(step.tabOrigin).toBe(null)
+  })
+
+  it('walks a selected block: Enter down the columns, Tab along the rows, both wrapping', () => {
+    const range = { minRow: 1, maxRow: 2, minCol: 1, maxCol: 2 }
+    const opts = { maxRow: 9, maxCol: 9, tabOrigin: null, range }
+    const path = (start: ActiveCellState, intent: 'moveDown' | 'moveUp' | 'tabNext' | 'tabPrev', n: number) => {
+      const out: Array<[number, number]> = []
+      let cell = start
+      for (let i = 0; i < n; i++) {
+        const step = getEntryStep(cell, intent, opts)
+        expect(step.withinRange).toBe(true)
+        expect(step.tabOrigin).toBe(null)
+        cell = step.cell
+        out.push([cell.rowIndex, cell.colIndex])
+      }
+      return out
+    }
+    expect(path(at(1, 1), 'moveDown', 4)).toEqual([[2, 1], [1, 2], [2, 2], [1, 1]])
+    expect(path(at(1, 1), 'moveUp', 4)).toEqual([[2, 2], [1, 2], [2, 1], [1, 1]])
+    expect(path(at(1, 1), 'tabNext', 4)).toEqual([[1, 2], [2, 1], [2, 2], [1, 1]])
+    expect(path(at(1, 1), 'tabPrev', 4)).toEqual([[2, 2], [2, 1], [1, 2], [1, 1]])
+  })
+
+  it('a one-cell range and a cursor outside the range are not a block', () => {
+    const single = getEntryStep(at(1, 1), 'moveDown', { ...open, tabOrigin: null, range: { minRow: 1, maxRow: 1, minCol: 1, maxCol: 1 } })
+    expect(single.withinRange).toBe(false)
+    expect(single.cell).toMatchObject({ rowIndex: 2, colIndex: 1 })
+    const outside = getEntryStep(at(5, 5), 'tabNext', { ...open, tabOrigin: null, range: { minRow: 1, maxRow: 2, minCol: 1, maxCol: 2 } })
+    expect(outside.withinRange).toBe(false)
+    expect(outside.cell).toMatchObject({ rowIndex: 5, colIndex: 6 })
+    expect(outside.tabOrigin).toBe(5)
+  })
+
+  it('a Tab run inside a block does not start a run', () => {
+    const range = { minRow: 0, maxRow: 1, minCol: 0, maxCol: 1 }
+    const step = getEntryStep(at(0, 0), 'tabNext', { ...open, tabOrigin: null, range })
+    expect(step.tabOrigin).toBe(null)
+  })
+
+  it('steps over collapsed cells, on the open sheet and inside a block', () => {
+    const collapsed = { isRowCollapsed: (r: number) => r === 1, isColumnCollapsed: (c: number) => c === 1 }
+    const down = getEntryStep(at(0, 0), 'moveDown', { ...open, tabOrigin: null, collapsed })
+    expect(down.cell).toMatchObject({ rowIndex: 2, colIndex: 0 })
+    const tab = getEntryStep(at(0, 0), 'tabNext', { ...open, tabOrigin: null, collapsed })
+    expect(tab.cell).toMatchObject({ rowIndex: 0, colIndex: 2 })
+    expect(tab.tabOrigin).toBe(0)
+    // In a 3x3 block with its middle row and column hidden, Enter from the
+    // top-left goes to the bottom-left, then wraps to the top of column 3.
+    const range = { minRow: 0, maxRow: 2, minCol: 0, maxCol: 2 }
+    const first = getEntryStep(at(0, 0), 'moveDown', { ...open, tabOrigin: null, range, collapsed })
+    expect(first.cell).toMatchObject({ rowIndex: 2, colIndex: 0 })
+    expect(first.withinRange).toBe(true)
+    const second = getEntryStep(first.cell, 'moveDown', { ...open, tabOrigin: null, range, collapsed })
+    expect(second.cell).toMatchObject({ rowIndex: 0, colIndex: 2 })
+    // A block with nothing showing leaves the cursor where it is.
+    const dark = { isRowCollapsed: () => true, isColumnCollapsed: () => false }
+    const stuck = getEntryStep(at(0, 0), 'moveDown', { ...open, tabOrigin: null, range, collapsed: dark })
+    expect(stuck.cell).toMatchObject({ rowIndex: 0, colIndex: 0 })
+  })
+})
+
+describe('pastCollapsed', () => {
+  const at = (rowIndex: number, colIndex: number): ActiveCellState => ({ rowIndex, colIndex, cellId: null })
+  const bounds = { maxRow: 5, maxCol: 5 }
+  const collapsed = (rows: number[], cols: number[]) => ({
+    isRowCollapsed: (r: number) => rows.includes(r),
+    isColumnCollapsed: (c: number) => cols.includes(c),
+  })
+
+  it('goes on in the direction of travel to the next visible line', () => {
+    expect(pastCollapsed(at(0, 0), at(0, 1), bounds, collapsed([], [1, 2]))).toMatchObject({ rowIndex: 0, colIndex: 3 })
+    expect(pastCollapsed(at(3, 0), at(2, 0), bounds, collapsed([2, 1], []))).toMatchObject({ rowIndex: 0, colIndex: 0 })
+  })
+
+  it('comes back to the nearest visible line when the edge is hidden: End on a sheet whose last columns are hidden', () => {
+    expect(pastCollapsed(at(0, 0), at(0, 5), bounds, collapsed([], [4, 5]))).toMatchObject({ rowIndex: 0, colIndex: 3 })
+  })
+
+  it('stays put when everything in the direction of travel is hidden', () => {
+    expect(pastCollapsed(at(0, 3), at(0, 4), bounds, collapsed([], [4, 5]))).toMatchObject({ rowIndex: 0, colIndex: 3 })
+  })
+
+  it('leaves an axis the move did not touch alone', () => {
+    // The cursor sits on a row the user just hid; a sideways move keeps the row.
+    expect(pastCollapsed(at(2, 0), at(2, 1), bounds, collapsed([2], []))).toMatchObject({ rowIndex: 2, colIndex: 1 })
+  })
+
+  it('returns the landing itself when nothing is hidden', () => {
+    const next = at(1, 1)
+    expect(pastCollapsed(at(0, 0), next, bounds, collapsed([], []))).toBe(next)
+  })
+})