@svgrid/grid 3.0.3 → 3.0.4

package/src/shortcut-registry.ts

@@ -0,0 +1,181 @@
+/**
+ * shortcut-registry - the injection seam for keyboard commands the free grid
+ * does not implement. `@svgrid/grid` owns cell navigation, copy/paste, undo and
+ * find; the Excel command set (Ctrl+Arrow to the edge of a data region, Ctrl+D
+ * fill down, Ctrl+Shift+V paste special, Alt+= autosum) is a paid feature in
+ * `@svgrid/enterprise`. This holder lets enterprise register a handler at
+ * import time; the grid runs the chain before it interprets a key itself.
+ *
+ * Same shape as `selection-bar-view`, `scheduler-view` and `board-view`, with
+ * one difference: those hold a single renderer, this holds a prioritised chain,
+ * because several packages may want a key and the first claim has to win
+ * deterministically.
+ *
+ * The chain runs BEFORE `getKeyboardIntent`, which is the whole point. The
+ * intent union in `keyboard.ts` is public API and closed, so there is no member
+ * that could mean "jump to the edge of the data region" and no way to add one
+ * without breaking a consumer that switches on it exhaustively. Running first
+ * sidesteps that: a registered handler claims `Ctrl+ArrowDown` and returns
+ * true, and the grid never computes an intent for that event at all.
+ *
+ * ```ts
+ * // in @svgrid/enterprise, at module load:
+ * import { registerGridShortcuts } from '@svgrid/grid'
+ * registerGridShortcuts(handleSheetKey, { id: 'sheet', priority: 100 })
+ * ```
+ */
+import type { SvGridApi } from './index'
+
+/** What a handler gets to read and write. A getter object over controller
+ *  state, built only when at least one handler is registered - a free grid
+ *  never pays to construct it. Indices are DISPLAY indices, matching
+ *  `SelectionPoint`, so they follow sort, filter and pagination. */
+export type GridCommandContext = {
+  /** The grid's public api. Identity is stable for the life of the grid, so
+   *  a handler can key per-grid state on it in a WeakMap. */
+  readonly api: SvGridApi<any, any>
+  /** True when the event came from the cell editor rather than the grid root.
+   *  Handlers that only make sense mid-edit (Alt+Enter) check this. */
+  readonly editing: boolean
+  /**
+   * The open inline editor's element, or null. A binding registered for
+   * `editing: true` reads and rewrites the text through it: F4 in a
+   * spreadsheet pins the reference under the caret.
+   */
+  readonly editor: HTMLInputElement | HTMLTextAreaElement | null
+  readonly activeCell: { rowIndex: number; colIndex: number; columnId: string | null } | null
+  /**
+   * The corner the active range grows from: the far end of a Shift+Arrow,
+   * Shift+click or drag, which need not be the active cell. Null while
+   * nothing is anchored. A command that extends the selection steps from
+   * here, not from the active cell, or Ctrl+Shift+Down twice would land
+   * on the same edge twice.
+   */
+  readonly selectionFocus: { rowIndex: number; colIndex: number } | null
+  readonly rowCount: number
+  readonly colCount: number
+  /** Every selected rectangle as [minRow, minCol, maxRow, maxCol], active last. */
+  readonly ranges: ReadonlyArray<readonly [number, number, number, number]>
+  columnIdAt(colIndex: number): string | null
+  getCellValue(rowIndex: number, colIndex: number): unknown
+  /** Write a cell and record it in the grid's undo history. Inside `batch`
+   *  every write joins one step, so a fill or a replace-all is one Ctrl+Z. */
+  setCellValue(rowIndex: number, colIndex: number, value: unknown): void
+  setActiveCell(rowIndex: number, colIndex: number): void
+  setSelection(rowIndex: number, colIndex: number): void
+  extendSelection(rowIndex: number, colIndex: number): void
+  scrollIntoView(rowIndex: number, colIndex: number): void
+  startEditing(rowIndex: number, colIndex: number, seed?: string): boolean
+  /** Run every write inside `fn` as ONE undo step. Returns what `fn` returns. */
+  batch<T>(fn: () => T): T
+  /**
+   * Put something that is not a cell write into the grid's undo history:
+   * a format kept in the caller's own store, a structural change the grid
+   * cannot see. `undo` and `redo` are what Ctrl+Z and Ctrl+Y will call.
+   * Inside `batch` the step joins the batch, so a command that writes cells
+   * AND formats is still one press.
+   */
+  recordUndo(undo: () => void, redo: () => void): void
+  /**
+   * Put keyboard focus back on the grid, without scrolling.
+   *
+   * A toolbar button takes focus when it is clicked and a dialog takes it
+   * when it opens, so the keystroke after either - Ctrl+Z to undo what the
+   * button did, typing into the cell the dialog changed - lands on the button
+   * or on `<body>` rather than on the grid. Excel returns focus to the sheet
+   * after every ribbon command and every dialog; a command that owns chrome
+   * calls this once it is done.
+   */
+  focus(): void
+  /**
+   * Paste the system clipboard at the active cell, the way Ctrl+V does:
+   * tab-separated text becomes a block of cells, one undo step. Resolves
+   * once the paste has been applied, or without doing anything when the
+   * clipboard cannot be read (an insecure context, or permission refused),
+   * which is the same silence Ctrl+V keeps there.
+   */
+  paste(): Promise<void>
+  /**
+   * Copy the selection the way Ctrl+C does: every selected rectangle as
+   * tab-separated text, each cell through `processCellForClipboard`. The
+   * api's `copyToClipboard` is the export: the displayed rows with their
+   * headers, whatever the selection.
+   */
+  copy(): void
+  /**
+   * Cut the selection the way Ctrl+X does: the copy above, then the cells
+   * cleared as one undo step.
+   */
+  cut(): Promise<void>
+  /**
+   * Whether a cell may be written: the column's `editable` predicate as
+   * the grid's own editor, fill handle and paste read it. `setCellValue`
+   * does not consult it (a command is trusted to know what it writes), so
+   * a command that fills or stamps a range asks here and skips the cells
+   * that say no. Optional for a context built by hand.
+   */
+  canEdit?(rowIndex: number, colIndex: number): boolean
+}
+
+/** Return true to consume the event. The grid stops there and does not
+ *  interpret the key itself. Return false to let it fall through. */
+export type GridShortcutHandler = (
+  event: KeyboardEvent,
+  cmd: GridCommandContext,
+) => boolean
+
+type Entry = { handler: GridShortcutHandler; id: string | undefined; priority: number }
+
+// Module-level, not $state: the chain is written at import time by whoever
+// installs a feature pack and read inside an event handler. Nothing renders
+// from it, so reactivity would cost a proxy for no benefit.
+let entries: Entry[] = []
+
+/**
+ * Register a keyboard handler. Higher `priority` runs first; ties keep
+ * registration order. Passing an `id` that is already registered replaces that
+ * entry rather than stacking a second copy, so an enable* function stays
+ * idempotent. Returns an unregister function.
+ */
+export function registerGridShortcuts(
+  handler: GridShortcutHandler,
+  opts?: { id?: string; priority?: number },
+): () => void {
+  const entry: Entry = {
+    handler,
+    id: opts?.id,
+    priority: opts?.priority ?? 0,
+  }
+  const next = entry.id ? entries.filter((e) => e.id !== entry.id) : entries.slice()
+  next.push(entry)
+  // Stable sort by descending priority: Array.prototype.sort is stable per
+  // spec, so equal priorities keep the order they were pushed in.
+  next.sort((a, b) => b.priority - a.priority)
+  entries = next
+  return () => {
+    entries = entries.filter((e) => e !== entry)
+  }
+}
+
+/** Run the chain. Returns true when a handler consumed the event. */
+export function runGridShortcuts(
+  event: KeyboardEvent,
+  cmd: GridCommandContext,
+): boolean {
+  for (const entry of entries) {
+    if (entry.handler(event, cmd)) return true
+  }
+  return false
+}
+
+/** Whether anything is registered. The grid checks this before building a
+ *  command context, so an unregistered grid pays one array-length read. */
+export function hasGridShortcuts(): boolean {
+  return entries.length > 0
+}
+
+/** Drop every handler. Tests use this; production code should keep the
+ *  unregister function `registerGridShortcuts` returns. */
+export function clearGridShortcuts(): void {
+  entries = []
+}

package/src/svgrid-wrapper.types.ts

@@ -3,8 +3,9 @@
 // type-level cycle. Backs the generic key/value typing of `setOption` / `getOption`.
 import type { FilterOperator, Props } from './SvGrid.types'
 import type { GridExportOptions, GridClipboardOptions } from './export-format'
-import type { ChartSpec, ChartType } from './chart'
+import type { ChartFormatState, ChartReducer, ChartSpec, ChartTimeBucket, ChartType, ChartZoomWindow } from './chart'
 import type { GridPredicateExpr } from './filtering/predicate-expr'
+import type { GridCommandContext } from './shortcut-registry'
 
 // Aliased to the core union rather than restated: the API surfaces below hand
 // back whatever the grid actually filtered with, so a hand-maintained subset
@@ -53,21 +54,70 @@ export type SvGridViewState = {
     reduce: 'sum' | 'avg' | 'count'
     stacked: boolean
   }
-  /** All charts in the tab strip (multi-chart), plus the active index. */
-  charts?: Array<{
+  /** All charts in the tab strip (multi-chart), plus the active index.
+   *  Every field the panel can change is here so a saved view restores the
+   *  chart exactly; `null` inherits the `charting` config. */
+  charts?: ChartTabSnapshot[]
+  chartActive?: number
+  /** The named charts kept with `api.saveChart`; present only when there is one. */
+  savedCharts?: SavedChart[]
+}
+
+/** One chart tab as the saved view carries it (`GridState.charts[i]`). */
+export type ChartTabSnapshot = {
     title: string
     type: ChartType
     dimension: string | null
     series: string | null
     measure: string | null
-    reduce: 'sum' | 'avg' | 'count'
+    /** Scatter's y measure, a range's high, a bullet's target. */
+    measure2?: string | null
+    reduce: ChartReducer
     stacked: boolean | null
+    stacked100?: boolean | null
+    orientation?: 'vertical' | 'horizontal' | null
+    donut?: boolean | null
+    palette?: string[] | null
     dataLabels: boolean | null
     logScale: boolean | null
     timeAxis: boolean | null
     valueFormat: 'number' | 'currency' | 'percent' | 'compact' | null
-  }>
-  chartActive?: number
+    bucket?: ChartTimeBucket | null
+    bins?: number | null
+    funnelShape?: 'trapezoid' | 'pyramid' | 'cone' | null
+    candleStyle?: 'classic' | 'hollow' | 'heikin-ashi' | null
+    /** The zoom window as category indices, or null for the whole chart. */
+    zoom?: ChartZoomWindow | null
+    ohlc?: { open: string | null; high: string | null; low: string | null; close: string | null; volume: string | null } | null
+    indicators?: string[]
+    format?: ChartFormatState | null
+    /** An unlinked chart carries the spec it was frozen with. */
+    frozen?: { spec: ChartSpec; at: string } | null
+}
+
+/** A chart configuration kept under a name (`api.saveChart`). */
+export type SavedChart = {
+  name: string
+  /** ISO timestamp of the save. */
+  savedAt: string
+  /** The tab's state at the time; `applySavedChart` puts it on the active tab. */
+  tab: ChartTabSnapshot
+}
+
+/** One cell, in the 0-based display coordinates every selection method uses. */
+export type SvGridCellCoords = { row: number; col: number }
+
+/**
+ * A selected rectangle with its orientation kept: `from` is where the
+ * selection was started (the anchor) and `to` where it ended (the focus),
+ * so a range dragged upwards has `from.row > to.row`. `highlight` is the
+ * active cell inside it. The same three fields as Handsontable's CellRange,
+ * so code written against `getSelectedRange()` there reads the same here.
+ */
+export type SvGridSelectedRange = {
+  from: SvGridCellCoords
+  to: SvGridCellCoords
+  highlight: SvGridCellCoords
 }
 
 /**
@@ -118,17 +168,44 @@ export type SvGridApi<
    * range is `[rowStart, colStart, rowEnd, colEnd]` in 0-indexed grid
    * coordinates. Pass an empty array to clear the selection.
    *
-   * The grid currently honours the FIRST range only (single-range
-   * engine); subsequent ranges are accepted for API forward compat
-   * but ignored. The grid's active cell jumps to the range's start
-   * corner.
+   * Every range is honoured: the last one becomes the active range and
+   * the others stay highlighted beside it, as after a Ctrl+drag. The
+   * active cell goes to the last range's start corner.
    */
   selectCells(ranges: ReadonlyArray<readonly [number, number, number, number]>): void
   /**
-   * Returns the current cell-selection rectangles in the same shape
-   * `selectCells` accepts. Empty array when no range is active.
+   * The current cell-selection rectangles in the same shape `selectCells`
+   * accepts, each normalised to `[minRow, minCol, maxRow, maxCol]`, in the
+   * order they were selected with the active one last. Empty array when no
+   * range is active.
+   *
+   * Handsontable's method of the same name. Two differences, both on
+   * purpose: an empty array rather than `undefined`, so `getSelected()[0]`
+   * never throws; and normalised corners, so a loop from the first row to
+   * the last cannot run zero times because the range was dragged upwards.
+   * For the orientation, and the active cell inside a range, use
+   * `getSelectedRange()`.
+   *
+   * With cell selection off (`selectable={false}`) no rectangle is ever
+   * recorded and this stays `[]`; the focused cell is `getActiveCell()`.
    */
   getSelected(): Array<[number, number, number, number]>
+  /**
+   * The most recently selected rectangle as `[startRow, startCol, endRow,
+   * endCol]`, start being where the selection began, or `undefined` when
+   * nothing is selected. Handsontable's `getSelectedLast()`, orientation
+   * included: a range dragged upwards has `startRow > endRow`.
+   */
+  getSelectedLast(): [number, number, number, number] | undefined
+  /**
+   * Every selected rectangle with its orientation and active cell, oldest
+   * first, or `undefined` when nothing is selected. Handsontable's
+   * `getSelectedRange()`.
+   */
+  getSelectedRange(): SvGridSelectedRange[] | undefined
+  /** The most recently selected rectangle, or `undefined`. Handsontable's
+   *  `getSelectedRangeLast()`. */
+  getSelectedRangeLast(): SvGridSelectedRange | undefined
 
   // ----- Integrated charting (requires the `charting` prop) -----
   /** Open the built-in chart panel. */
@@ -149,13 +226,47 @@ export type SvGridApi<
     dimension?: string | null
     series?: string | null
     measure?: string | null
-    reduce?: 'sum' | 'avg' | 'count'
+    reduce?: ChartReducer
     stacked?: boolean
     dataLabels?: boolean
     logScale?: boolean
     timeAxis?: boolean
     valueFormat?: 'number' | 'currency' | 'percent' | 'compact'
+    /** Group a date dimension by calendar unit; `null` returns to exact values. */
+    bucket?: ChartTimeBucket | null
+    /** Second measure: a scatter's Y, a range's high end, a bullet's target. */
+    measure2?: string | null
+    /** Histogram bin count; `null` for Sturges' rule. */
+    bins?: number | null
+    funnelShape?: 'trapezoid' | 'pyramid' | 'cone' | null
+    candleStyle?: 'classic' | 'hollow' | 'heikin-ashi' | null
+    /** Candlestick / OHLC: the price columns (ids or fields); `null` goes
+     *  back to guessing them from the column names. */
+    ohlc?: { open?: string | null; high?: string | null; low?: string | null; close?: string | null; volume?: string | null } | null
+    /** Indicator panes under a price chart (`volume`, `rsi`, `macd`,
+     *  `stochastic`, `atr`, `obv`) and overlays on it (`sma`, `ema`,
+     *  `bb`, `vwap`). */
+    indicators?: Array<'volume' | 'rsi' | 'macd' | 'stochastic' | 'atr' | 'obv' | 'sma' | 'ema' | 'bb' | 'vwap'>
+    /** The builder's format state (titles, axes, legend, per-series style);
+     *  `null` resets it. */
+    format?: ChartFormatState | null
+    /** `true` unlinks the chart from the grid (it keeps the spec it has),
+     *  `false` links it back. */
+    frozen?: boolean
+    /** Apply a saved chart (by name) to the active tab before the other keys. */
+    saved?: string
   }): void
+  /**
+   * Keep the active chart's whole configuration (type, columns, aggregate,
+   * switches, indicators, format, zoom) under a name. A same-named entry is
+   * replaced. Saved charts travel with `getState()` / `setState()` and show
+   * in the panel's Saved charts popover.
+   */
+  saveChart(name: string): void
+  /** Apply a saved chart to the active tab, which keeps its title. `false` when no chart has that name. */
+  applySavedChart(name: string): boolean
+  removeSavedChart(name: string): void
+  getSavedCharts(): SavedChart[]
   /**
    * Register a natural-language "chart this" handler. When set, the chart
    * panel shows an AI button. `@svgrid/enterprise`'s `enableAiCharting(api)`
@@ -164,6 +275,13 @@ export type SvGridApi<
   setChartAiHandler(
     handler: ((prompt: string) => Promise<Record<string, unknown> | null>) | null,
   ): void
+  /**
+   * Register an "explain this chart" handler. When set, the chart panel's AI
+   * row shows an Explain button that reads the active chart and shows the
+   * summary and insights it returns. `enableAiCharting(api)` fills this with
+   * `aiExplainChart`. Pass `null` to remove it.
+   */
+  setChartExplainHandler(handler: (() => Promise<{ summary: string; insights: string[] } | null>) | null): void
 
   // ----- Rows -----
   /** Add one row. `position` defaults to `'bottom'`. */
@@ -259,6 +377,13 @@ export type SvGridApi<
    * `editorOptions` returns a Promise - static lists are never refetched.
    */
   refreshEditorOptions(columnId?: string): void
+  /**
+   * Open the `contextMenu` at the pointer, for the cell at (rowIndex,
+   * colIndex), from an element of your own: a spreadsheet's column letters
+   * and row numbers offer the cell menu for the column or row they select.
+   * Does nothing without a `contextMenu` prop.
+   */
+  openContextMenu(event: MouseEvent, rowIndex: number, colIndex: number): void
   /**
    * Clear every active column filter (menu, filter-row, set-list, global, and
    * the advanced filter). Resets the grid to "no filtering" in a single call.
@@ -370,6 +495,38 @@ export type SvGridApi<
    * "Autosize" item.
    */
   autosizeColumn(columnId: string): void
+  /**
+   * The height of a row in px: the one it was dragged or set to, else the
+   * declared `rowHeight` (30 when none). `rowIndex` is a display index.
+   */
+  getRowHeight(rowIndex: number): number
+  /**
+   * Give a row its own height, the way dragging its grip does with
+   * `rowResize`; `null` takes it back to the declared height. The height
+   * belongs to the row (its id), so it follows the row through a sort and
+   * survives the data being replaced. Ignored under `autoRowHeight`, where
+   * the content decides.
+   */
+  setRowHeight(rowIndex: number, height: number | null): void
+  /**
+   * Fold a column to nothing, the way a spreadsheet hides one: it keeps
+   * its index, its cells and its width, and takes no room until it is
+   * unfolded. Unlike `setColumnVisible(id, false)`, which takes the
+   * column out of the model and shifts every index after it, references
+   * by index stay valid, so a sheet's formulas and formats are untouched.
+   * Arrow keys, Tab and Enter step over a collapsed column.
+   */
+  setColumnCollapsed(columnId: string, collapsed: boolean): void
+  isColumnCollapsed(columnId: string): boolean
+  /**
+   * Fold a row to nothing, the row-side twin of `setColumnCollapsed`.
+   * `rowIndex` is a display index; the fold belongs to the row (its id)
+   * and follows it through a sort.
+   */
+  setRowCollapsed(rowIndex: number, collapsed: boolean): void
+  isRowCollapsed(rowIndex: number): boolean
+  /** The `mergedCells` in force, copied: origins with their spans. */
+  getMergedCells(): Array<{ rowIndex: number; colIndex: number; rowSpan: number; colSpan: number }>
   /** Run `autosizeColumn` on every column. */
   autosizeAllColumns(): void
   /**
@@ -424,6 +581,20 @@ export type SvGridApi<
   /** Wipe both stacks (e.g. after a server save commits the buffer). */
   clearHistory(): void
 
+  // ----- Keyboard commands -----
+  /**
+   * The same `GridCommandContext` a registered shortcut handler receives.
+   *
+   * Keyboard commands are handed one on every keystroke, but a button in a
+   * ribbon or a toolbar has no keystroke to ride in on, and re-implementing
+   * "bold the selection" against the api would give the button and the key
+   * two code paths that drift. Both go through this instead.
+   *
+   * Live, not a snapshot: the object reads through to the grid, so one built
+   * once at mount still reports the current selection.
+   */
+  getCommandContext(): GridCommandContext
+
   // ----- Find in grid -----
   /** Open the built-in find overlay (Ctrl+F also opens it). */
   openFind(): void

package/src/svgrid.behavior.test.ts

@@ -704,6 +704,72 @@ describe('SvGrid - fitColumns', () => {
   })
 })
 
+describe('SvGrid - frozenRows', () => {
+  const frozen = (target: HTMLElement) => [...target.querySelectorAll<HTMLElement>('tr.sv-grid-row-frozen')]
+
+  it('marks the first N rows frozen with a sticky top under the header, and keeps them as the rows they are', async () => {
+    const { api, target, destroy } = await mountGrid({ frozenRows: 2, virtualization: true })
+    try {
+      await tick()
+      const rows = frozen(target)
+      expect(rows).toHaveLength(2)
+      expect(rows[0]!.querySelector('[data-svgrid-row]')?.getAttribute('data-svgrid-row')).toBe('0')
+      expect(rows[1]!.querySelector('[data-svgrid-row]')?.getAttribute('data-svgrid-row')).toBe('1')
+      // Under the header, then under each other: the second sits a row lower.
+      expect(rows[1]!.style.top).not.toBe(rows[0]!.style.top)
+      expect(rows[1]!.classList.contains('sv-grid-row-frozen-last')).toBe(true)
+      // Still numbered and still data rows: the body renders the rest once.
+      const bodyRows = [...target.querySelectorAll('tbody.sv-grid-body tr.sv-grid-row:not(.sv-grid-row-spacer)')]
+      const indices = bodyRows.map((tr) => tr.querySelector('[data-svgrid-row]')?.getAttribute('data-svgrid-row')).filter(Boolean)
+      expect(new Set(indices).size).toBe(indices.length)
+      expect(indices.slice(0, 3)).toEqual(['0', '1', '2'])
+      expect(api.getRowHeight(0)).toBe(36)
+    } finally {
+      destroy()
+    }
+  })
+
+  it('a row below the frozen band keeps its own height, not the height of the row N above it', async () => {
+    // The virtual loop used to draw item i as row i + N while the
+    // virtualizer had sized item i as row i, so under a freeze of two rows
+    // a taller row 3 was drawn 36px and row 1 got the 60px.
+    const { api, target, destroy } = await mountGrid({ frozenRows: 2, virtualization: true })
+    try {
+      await tick()
+      api.setRowHeight(3, 60)
+      await tick()
+      const tr = (index: number) => target.querySelector(`[data-svgrid-row="${index}"]`)?.closest('tr') as HTMLElement | null
+      expect(tr(3)?.style.height).toBe('60px')
+      expect(tr(1)?.style.height).toBe('36px')
+      expect(tr(2)?.style.height).toBe('36px')
+      // The last rows are still reachable: every row index renders once.
+      const indices = [...target.querySelectorAll('tbody.sv-grid-body tr.sv-grid-row:not(.sv-grid-row-spacer)')]
+        .map((row) => row.querySelector('[data-svgrid-row]')?.getAttribute('data-svgrid-row'))
+        .filter(Boolean)
+      expect(new Set(indices).size).toBe(indices.length)
+      expect(indices).toContain(String(api.getData().length - 1))
+    } finally {
+      destroy()
+    }
+  })
+
+  it('setOption frozenRows freezes and unfreezes at runtime', async () => {
+    const { api, target, destroy } = await mountGrid()
+    try {
+      await tick()
+      expect(frozen(target)).toHaveLength(0)
+      api.setOption('frozenRows', 1)
+      await tick()
+      expect(frozen(target)).toHaveLength(1)
+      api.setOption('frozenRows', undefined)
+      await tick()
+      expect(frozen(target)).toHaveLength(0)
+    } finally {
+      destroy()
+    }
+  })
+})
+
 describe('SvGrid - selectable shortcut (cell selection)', () => {
   // The gated path a user actually takes: pointerdown on a cell runs through
   // createSelection.setSelection, which bails on !enableCellSelectionEffective.
@@ -911,3 +977,72 @@ describe('SvGrid - homepage snippet (shortcuts only, no features import)', () =>
     }
   })
 })
+
+describe('SvGrid - mergedCells', () => {
+  const td = (target: HTMLElement, r: number, c: number) =>
+    target.querySelector(`td[data-svgrid-row="${r}"][data-svgrid-col="${c}"]`) as HTMLElement | null
+
+  it('draws a merge as one td with its spans and leaves the covered cells out', async () => {
+    const { api, target, destroy } = await mountGrid({
+      mergedCells: [
+        { rowIndex: 0, colIndex: 1, rowSpan: 1, colSpan: 2 },
+        { rowIndex: 2, colIndex: 0, rowSpan: 2, colSpan: 1 },
+      ],
+    })
+    try {
+      await tick()
+      const wide = td(target, 0, 1)
+      expect(wide?.getAttribute('colspan')).toBe('2')
+      expect(wide?.dataset.mergeOrigin).toBe('0:1')
+      expect(wide?.classList.contains('sv-grid-cell-merged')).toBe(true)
+      expect(td(target, 0, 2)).toBeNull()
+      const tall = td(target, 2, 0)
+      expect(tall?.getAttribute('rowspan')).toBe('2')
+      expect(td(target, 3, 0)).toBeNull()
+      // The wide td is as wide as the two columns it covers, read off a plain row.
+      const px = (el: HTMLElement | null) => parseFloat(el?.style.width ?? '0')
+      expect(px(wide)).toBe(px(td(target, 1, 1)) + px(td(target, 1, 2)))
+      // A plain cell is untouched.
+      expect(td(target, 1, 1)?.hasAttribute('colspan')).toBe(false)
+      expect(api.getMergedCells()).toEqual([
+        { rowIndex: 0, colIndex: 1, rowSpan: 1, colSpan: 2 },
+        { rowIndex: 2, colIndex: 0, rowSpan: 2, colSpan: 1 },
+      ])
+    } finally {
+      destroy()
+    }
+  })
+
+  it('the active cell inside a merge is its origin, a range grows to whole merges, and the arrows step over it', async () => {
+    const { api, target, destroy } = await mountGrid({
+      mergedCells: [{ rowIndex: 0, colIndex: 1, rowSpan: 1, colSpan: 2 }],
+    })
+    try {
+      await tick()
+      const ctx = api.getCommandContext()
+      ctx.setActiveCell(0, 2)
+      expect(ctx.activeCell).toMatchObject({ rowIndex: 0, colIndex: 1 })
+      ctx.setSelection(0, 2)
+      expect(api.getSelected()).toEqual([[0, 1, 0, 2]])
+      // A range from B2 up to C1 pulls in the whole of B1:C1.
+      ctx.setSelection(1, 1)
+      ctx.extendSelection(0, 1)
+      expect(api.getSelected()).toEqual([[0, 1, 1, 2]])
+      // Right from the merge lands past it; left from D1 lands on the origin.
+      ctx.setActiveCell(0, 1)
+      ctx.setSelection(0, 1)
+      // The grid listens on its table, and only for keys aimed at it.
+      const root = target.querySelector('table.sv-grid-table') as HTMLElement
+      root.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }))
+      await tick()
+      expect(ctx.activeCell).toMatchObject({ rowIndex: 0, colIndex: 3 })
+      root.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', bubbles: true }))
+      await tick()
+      expect(ctx.activeCell).toMatchObject({ rowIndex: 0, colIndex: 1 })
+      // The td that draws the merge carries the selection's right edge.
+      expect(td(target, 0, 1)?.dataset.rangeRight).toBe('true')
+    } finally {
+      destroy()
+    }
+  })
+})