@svgrid/grid 3.0.3 → 3.0.5

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)
+  })
+})

package/src/keyboard.ts

@@ -22,6 +22,20 @@ export function getKeyboardIntent(event: KeyboardEvent): GridKeyboardIntent {
   if (event.ctrlKey && event.key === 'Home') return 'gridStart'
   if (event.ctrlKey && event.key === 'End') return 'gridEnd'
 
+  // Ctrl/Cmd + arrow is Excel's "jump to the edge of the data region". The
+  // grid does not implement that itself - it is a paid command registered
+  // through `registerGridShortcuts`, which runs before this function is ever
+  // called. If we get here the key was NOT claimed, and the right answer is to
+  // do nothing: moving one cell is a silently wrong response to a shortcut
+  // every spreadsheet user presses. Alt is excluded so a browser or OS
+  // combination still falls through untouched.
+  if ((event.ctrlKey || event.metaKey) && !event.altKey) {
+    if (
+      event.key === 'ArrowLeft' || event.key === 'ArrowRight' ||
+      event.key === 'ArrowUp' || event.key === 'ArrowDown'
+    ) return 'noop'
+  }
+
   if (event.key === 'ArrowLeft') return 'moveLeft'
   if (event.key === 'ArrowRight') return 'moveRight'
   if (event.key === 'ArrowUp') return 'moveUp'
@@ -95,3 +109,131 @@ export function getNextActiveCell(
     cellId: current.cellId,
   }
 }
+
+export type Collapsed = {
+  isRowCollapsed: (rowIndex: number) => boolean
+  isColumnCollapsed: (colIndex: number) => boolean
+}
+
+/**
+ * Where a move lands once collapsed rows and columns are stepped over.
+ *
+ * A sheet's arrow keys never rest on a hidden row or column: the cursor
+ * goes on in the direction of travel to the next one that shows, and when
+ * nothing shows in that direction it comes back to the nearest one before
+ * the landing, which for End on a sheet whose last columns are hidden is the
+ * last visible column. An axis the move did not touch is left alone, so a
+ * cursor sitting on a row the user has just hidden still moves sideways.
+ * With every cell in the direction of travel hidden the cursor stays put.
+ */
+export function pastCollapsed(
+  from: ActiveCellState,
+  next: ActiveCellState,
+  bounds: { maxRow: number; maxCol: number },
+  collapsed: Collapsed,
+): ActiveCellState {
+  const axis = (fromIdx: number, nextIdx: number, max: number, isCollapsed: (i: number) => boolean) => {
+    if (nextIdx === fromIdx) return nextIdx
+    const dir = nextIdx > fromIdx ? 1 : -1
+    let i = nextIdx
+    while (i >= 0 && i <= max && isCollapsed(i)) i += dir
+    if (i >= 0 && i <= max) return i
+    i = nextIdx - dir
+    while (i !== fromIdx && isCollapsed(i)) i -= dir
+    return i
+  }
+  const rowIndex = axis(from.rowIndex, next.rowIndex, bounds.maxRow, collapsed.isRowCollapsed)
+  const colIndex = axis(from.colIndex, next.colIndex, bounds.maxCol, collapsed.isColumnCollapsed)
+  return rowIndex === next.rowIndex && colIndex === next.colIndex ? next : { rowIndex, colIndex, cellId: next.cellId }
+}
+
+export type EntryIntent = 'moveDown' | 'moveUp' | 'tabNext' | 'tabPrev'
+
+export type EntryRect = { minRow: number; maxRow: number; minCol: number; maxCol: number }
+
+export type EntryStep = {
+  cell: ActiveCellState
+  /** The move stayed inside a multi-cell selection, which is kept. */
+  withinRange: boolean
+  /** The column a run of Tabs began in, for the Enter that ends it. */
+  tabOrigin: number | null
+}
+
+/**
+ * Where Enter and Tab put the cursor, the way a sheet's data entry expects.
+ *
+ * Two rules on top of `getNextActiveCell`. A run of Tabs remembers the
+ * column it started in, and the Enter that ends the run goes down from
+ * THAT column, not from the last cell: type across A1, B1, C1 with Tab and
+ * Enter lands on A2, ready for the next record. Any other move clears the
+ * memory, which the callers do by resetting `tabOrigin` on every plain
+ * `setActiveCell`. And inside a selection of more than one cell the cursor
+ * stays inside it: Enter walks down a column and wraps to the top of the
+ * next, Tab walks along a row and wraps to the start of the next, both
+ * back to the first cell after the last, and the selection is left
+ * standing, so a block can be filled without ever reaching for the mouse.
+ * Arrow keys are not entry keys and never come here.
+ */
+export function getEntryStep(
+  current: ActiveCellState,
+  intent: EntryIntent,
+  opts: { maxRow: number; maxCol: number; tabOrigin: number | null; range: EntryRect | null; collapsed?: Collapsed },
+): EntryStep {
+  const step = entryStep(current, intent, opts)
+  const collapsed = opts.collapsed
+  if (!collapsed) return step
+  const hidden = (c: ActiveCellState) => collapsed.isRowCollapsed(c.rowIndex) || collapsed.isColumnCollapsed(c.colIndex)
+  if (!hidden(step.cell)) return step
+  if (!step.withinRange) return { ...step, cell: pastCollapsed(current, step.cell, opts, collapsed) }
+  // Walking a block: the same step again from the hidden cell, until one
+  // shows. A block with nothing showing leaves the cursor where it is.
+  let cell = step.cell
+  for (let guard = (opts.range!.maxRow - opts.range!.minRow + 1) * (opts.range!.maxCol - opts.range!.minCol + 1); guard > 0 && hidden(cell); guard -= 1) {
+    cell = entryStep(cell, intent, opts).cell
+  }
+  return { ...step, cell: hidden(cell) ? current : cell }
+}
+
+function entryStep(
+  current: ActiveCellState,
+  intent: EntryIntent,
+  opts: { maxRow: number; maxCol: number; tabOrigin: number | null; range: EntryRect | null },
+): EntryStep {
+  const range = opts.range
+  const inRange =
+    range !== null &&
+    (range.maxRow > range.minRow || range.maxCol > range.minCol) &&
+    current.rowIndex >= range.minRow && current.rowIndex <= range.maxRow &&
+    current.colIndex >= range.minCol && current.colIndex <= range.maxCol
+  if (inRange) {
+    let { rowIndex, colIndex } = current
+    if (intent === 'moveDown') {
+      rowIndex += 1
+      if (rowIndex > range.maxRow) { rowIndex = range.minRow; colIndex += 1 }
+      if (colIndex > range.maxCol) colIndex = range.minCol
+    } else if (intent === 'moveUp') {
+      rowIndex -= 1
+      if (rowIndex < range.minRow) { rowIndex = range.maxRow; colIndex -= 1 }
+      if (colIndex < range.minCol) colIndex = range.maxCol
+    } else if (intent === 'tabNext') {
+      colIndex += 1
+      if (colIndex > range.maxCol) { colIndex = range.minCol; rowIndex += 1 }
+      if (rowIndex > range.maxRow) rowIndex = range.minRow
+    } else {
+      colIndex -= 1
+      if (colIndex < range.minCol) { colIndex = range.maxCol; rowIndex -= 1 }
+      if (rowIndex < range.minRow) rowIndex = range.maxRow
+    }
+    return { cell: { rowIndex, colIndex, cellId: current.cellId }, withinRange: true, tabOrigin: null }
+  }
+  const bounds = { maxRow: opts.maxRow, maxCol: opts.maxCol }
+  if (intent === 'tabNext' || intent === 'tabPrev') {
+    return {
+      cell: getNextActiveCell(current, intent, bounds),
+      withinRange: false,
+      tabOrigin: opts.tabOrigin ?? current.colIndex,
+    }
+  }
+  const from = opts.tabOrigin === null ? current : { ...current, colIndex: opts.tabOrigin }
+  return { cell: getNextActiveCell(from, intent, bounds), withinRange: false, tabOrigin: null }
+}

package/src/menus.test.ts

@@ -621,6 +621,32 @@ describe('createMenus - contextMenuItems', () => {
     expect(ctx.clearSelectedCells).toHaveBeenCalled()
   })
 
+  it('an object on a built-in key with no action keeps the built-in, and carries the icon', () => {
+    const icon = { paths: [{ d: 'M2 2h12v12H2z' }] }
+    const ctx = makeCtx({
+      props: { contextMenu: [{ key: 'cut', icon }, { key: 'copy', label: 'Copy cells', icon: 'columns' }] },
+      contextMenuFor: { rowIndex: 0, colIndex: 0, columnId: 'name', rowId: 'r0', row: { id: 0 } },
+    })
+    const items = createMenus(ctx).contextMenuItems()
+    const cut = items.find((i) => i.key === 'cut')!
+    expect(cut.label).toBe('Cut')
+    expect(cut.icon).toBe(icon)
+    cut.run!()
+    expect(ctx.cutSelectionToClipboard).toHaveBeenCalled()
+    const copy = items.find((i) => i.key === 'copy')!
+    expect(copy.label).toBe('Copy cells')
+    expect(copy.icon).toBe('columns')
+  })
+
+  it('an unknown key with no action resolves to an inert item rather than throwing', () => {
+    const ctx = makeCtx({
+      props: { contextMenu: [{ key: 'nothing', label: 'Nothing' }] },
+      contextMenuFor: { rowIndex: 0, colIndex: 0, columnId: 'name', rowId: 'r0', row: { id: 0 } },
+    })
+    const item = createMenus(ctx).contextMenuItems()[0]!
+    expect(item.label).toBe('Nothing')
+    expect(item.run).toBeUndefined()
+  })
   it('row_above / row_below / remove_row mutate internalData', () => {
     const rowA = { id: 1 }
     const rowB = { id: 2 }

package/src/menus.ts

@@ -8,8 +8,10 @@ import {
 import "./sv-grid-scrollbar";
 import { untrack } from "svelte";
 import type {
+  ContextMenuIcon,
   FilterOperator,
 } from "./SvGrid.types";
+import type { GridIconName } from "./grid-icons";
 import {
   clampMenuX,
   cssEscape,
@@ -414,7 +416,7 @@ export function createMenus<
 
   // ---- Right-click context menu --------------------------------------
   type CtxTarget = { rowIndex: number; colIndex: number; columnId: string; rowId: string; row: TData | null };
-  type ResolvedItem = { key: string; label: string; separator?: boolean; disabled?: boolean; run?: () => void };
+  type ResolvedItem = { key: string; label: string; icon?: GridIconName | ContextMenuIcon; separator?: boolean; disabled?: boolean; run?: () => void };
 
   function insertRowAt(t: CtxTarget, offset: number) {
     const data = ctx.internalData.slice() as TData[];
@@ -543,11 +545,16 @@ export function createMenus<
         continue;
       }
       if (entry.hidden?.(target)) continue;
+      // An object on a built-in's key with no action of its own is that
+      // built-in with an icon (or a label) of the consumer's choosing.
+      const b = builtins[entry.key];
+      const builtinLabel = b ? ((b.msg && messages?.[b.msg]) || b.label) : entry.key;
       out.push({
         key: entry.key,
-        label: entry.label,
+        label: entry.label ?? builtinLabel,
+        icon: entry.icon,
         disabled: entry.disabled?.(target) ?? false,
-        run: () => entry.action(target),
+        run: entry.action ? () => entry.action(target) : b ? () => b.run(target) : undefined,
       });
     }
     // Drop leading/trailing/double separators.

package/src/merges.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildMergeIndex, mergeAt, isCovered, originOf, endOf, expandRectToMerges, stepPastMerge, mergeDrawAt,
+} from './merges'
+
+// A1:C1 (three across), B3:B5 (three down), E5:F6 (two by two).
+const index = buildMergeIndex([
+  { rowIndex: 0, colIndex: 0, rowSpan: 1, colSpan: 3 },
+  { rowIndex: 2, colIndex: 1, rowSpan: 3, colSpan: 1 },
+  { rowIndex: 4, colIndex: 4, rowSpan: 2, colSpan: 2 },
+])
+const bounds = { maxRow: 9, maxCol: 9 }
+
+describe('buildMergeIndex', () => {
+  it('is null for nothing, and drops 1x1 merges', () => {
+    expect(buildMergeIndex([])).toBeNull()
+    expect(buildMergeIndex(undefined)).toBeNull()
+    expect(buildMergeIndex([{ rowIndex: 0, colIndex: 0, rowSpan: 1, colSpan: 1 }])).toBeNull()
+  })
+
+  it('indexes every covered cell to its merge', () => {
+    expect(mergeAt(index, 0, 2)?.colSpan).toBe(3)
+    expect(mergeAt(index, 4, 1)?.rowSpan).toBe(3)
+    expect(mergeAt(index, 5, 5)).toMatchObject({ rowIndex: 4, colIndex: 4 })
+    expect(mergeAt(index, 1, 1)).toBeUndefined()
+    expect(isCovered(index, 0, 0)).toBe(false)
+    expect(isCovered(index, 0, 1)).toBe(true)
+    expect(originOf(index, 5, 5)).toEqual({ rowIndex: 4, colIndex: 4 })
+    expect(originOf(index, 7, 7)).toEqual({ rowIndex: 7, colIndex: 7 })
+    expect(endOf(index, 2, 1)).toEqual({ rowIndex: 4, colIndex: 1 })
+    expect(endOf(index, 7, 7)).toEqual({ rowIndex: 7, colIndex: 7 })
+  })
+})
+
+describe('expandRectToMerges', () => {
+  it('grows a rectangle to hold every merge it touches, to a fixed point', () => {
+    expect(expandRectToMerges(index, { minRow: 0, maxRow: 0, minCol: 1, maxCol: 1 })).toEqual({ minRow: 0, maxRow: 0, minCol: 0, maxCol: 2 })
+    // B4 alone pulls in B3:B5; a rectangle reaching E5 pulls in E5:F6.
+    expect(expandRectToMerges(index, { minRow: 3, maxRow: 3, minCol: 1, maxCol: 1 })).toEqual({ minRow: 2, maxRow: 4, minCol: 1, maxCol: 1 })
+    expect(expandRectToMerges(index, { minRow: 4, maxRow: 4, minCol: 1, maxCol: 4 })).toEqual({ minRow: 2, maxRow: 5, minCol: 1, maxCol: 5 })
+  })
+
+  it('hands the same object back when nothing grows', () => {
+    const rect = { minRow: 7, maxRow: 8, minCol: 7, maxCol: 8 }
+    expect(expandRectToMerges(index, rect)).toBe(rect)
+    expect(expandRectToMerges(null, rect)).toBe(rect)
+  })
+})
+
+describe('stepPastMerge', () => {
+  it('a step into a merge lands on its origin', () => {
+    expect(stepPastMerge(index, { rowIndex: 1, colIndex: 1 }, { rowIndex: 0, colIndex: 1 }, bounds)).toEqual({ rowIndex: 0, colIndex: 0 })
+    expect(stepPastMerge(index, { rowIndex: 5, colIndex: 3 }, { rowIndex: 5, colIndex: 4 }, bounds)).toEqual({ rowIndex: 4, colIndex: 4 })
+  })
+
+  it('a step inside the merge the move began in carries on past its far edge', () => {
+    // Right from A1 (A1:C1) reaches D1, not B1.
+    expect(stepPastMerge(index, { rowIndex: 0, colIndex: 0 }, { rowIndex: 0, colIndex: 1 }, bounds)).toEqual({ rowIndex: 0, colIndex: 3 })
+    // Down from B3 (B3:B5) reaches B6.
+    expect(stepPastMerge(index, { rowIndex: 2, colIndex: 1 }, { rowIndex: 3, colIndex: 1 }, bounds)).toEqual({ rowIndex: 5, colIndex: 1 })
+    // Up from E5 (E5:F6) reaches E4; left reaches D5.
+    expect(stepPastMerge(index, { rowIndex: 4, colIndex: 4 }, { rowIndex: 3, colIndex: 4 }, bounds)).toEqual({ rowIndex: 3, colIndex: 4 })
+    expect(stepPastMerge(index, { rowIndex: 4, colIndex: 4 }, { rowIndex: 4, colIndex: 3 }, bounds)).toEqual({ rowIndex: 4, colIndex: 3 })
+  })
+
+  it('stays on the merge at the sheet edge, and takes the origin of a merge it lands in', () => {
+    expect(stepPastMerge(index, { rowIndex: 0, colIndex: 0 }, { rowIndex: 0, colIndex: 1 }, { maxRow: 9, maxCol: 2 })).toEqual({ rowIndex: 0, colIndex: 0 })
+    const chain = buildMergeIndex([
+      { rowIndex: 0, colIndex: 0, rowSpan: 1, colSpan: 2 },
+      { rowIndex: 0, colIndex: 2, rowSpan: 1, colSpan: 2 },
+    ])
+    expect(stepPastMerge(chain, { rowIndex: 0, colIndex: 0 }, { rowIndex: 0, colIndex: 1 }, bounds)).toEqual({ rowIndex: 0, colIndex: 2 })
+  })
+
+  it('is a pass-through without merges or outside them', () => {
+    expect(stepPastMerge(null, { rowIndex: 0, colIndex: 0 }, { rowIndex: 0, colIndex: 1 }, bounds)).toEqual({ rowIndex: 0, colIndex: 1 })
+    expect(stepPastMerge(index, { rowIndex: 7, colIndex: 7 }, { rowIndex: 7, colIndex: 8 }, bounds)).toEqual({ rowIndex: 7, colIndex: 8 })
+  })
+})
+
+describe('mergeDrawAt', () => {
+  const all = { firstRow: 0, lastRow: 9, firstCol: 0, lastCol: 9 }
+
+  it('the origin draws with its spans and the covered cells are skipped', () => {
+    expect(mergeDrawAt(index, 0, 0, all)).toEqual({ kind: 'origin', merge: index!.list[0], rowSpan: 1, colSpan: 3 })
+    expect(mergeDrawAt(index, 0, 1, all)).toEqual({ kind: 'skip' })
+    expect(mergeDrawAt(index, 4, 5, all)).toEqual({ kind: 'skip' })
+    expect(mergeDrawAt(index, 1, 1, all)).toBeNull()
+  })
+
+  it('a merge whose origin is above the window continues from its first drawn row, spans clamped', () => {
+    const window = { firstRow: 3, lastRow: 9, firstCol: 0, lastCol: 9 }
+    // B3:B5 with rows 3.. shown: B4 draws the rest (two rows), B5 is skipped.
+    expect(mergeDrawAt(index, 3, 1, window)).toEqual({ kind: 'continuation', merge: index!.list[1], rowSpan: 2, colSpan: 1 })
+    expect(mergeDrawAt(index, 4, 1, window)).toEqual({ kind: 'skip' })
+  })
+
+  it('clamps to the window\'s last row and column', () => {
+    const window = { firstRow: 0, lastRow: 4, firstCol: 0, lastCol: 4 }
+    expect(mergeDrawAt(index, 2, 1, window)).toEqual({ kind: 'origin', merge: index!.list[1], rowSpan: 3, colSpan: 1 })
+    expect(mergeDrawAt(index, 4, 4, window)).toEqual({ kind: 'origin', merge: index!.list[2], rowSpan: 1, colSpan: 1 })
+  })
+
+  it('a merge starting in the frozen band draws its remainder in the body as a continuation', () => {
+    const frozen = { firstRow: 0, lastRow: 0, firstCol: 0, lastCol: 9 }
+    const body = { firstRow: 1, lastRow: 9, firstCol: 0, lastCol: 9 }
+    const tall = buildMergeIndex([{ rowIndex: 0, colIndex: 0, rowSpan: 3, colSpan: 1 }])
+    expect(mergeDrawAt(tall, 0, 0, frozen)).toEqual({ kind: 'origin', merge: tall!.list[0], rowSpan: 1, colSpan: 1 })
+    expect(mergeDrawAt(tall, 1, 0, body)).toEqual({ kind: 'continuation', merge: tall!.list[0], rowSpan: 2, colSpan: 1 })
+    expect(mergeDrawAt(tall, 2, 0, body)).toEqual({ kind: 'skip' })
+  })
+})