@svgrid/grid 1.0.2 → 1.1.1

package/src/server-data-source.coverage.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createServerDataSource, type ServerDataSource, type ServerRequest } from './server-data-source'
+
+type Row = { id: number }
+
+const flush = () => new Promise((r) => setTimeout(r, 0))
+
+describe('createServerDataSource - request params', () => {
+  it('passes startRow/endRow/page/sort/filter through to getRows', async () => {
+    const getRows = vi.fn(async (_req: ServerRequest) => ({ rows: [], rowCount: 0 }))
+    const ctl = createServerDataSource<Row>({ getRows }, { pageSize: 20, onChange: () => {} })
+    ctl.setFilter({ global: 'abc', columns: { name: { operator: 'eq', value: 'x' } } })
+    await flush()
+    const req = getRows.mock.calls.at(-1)![0]
+    expect(req).toMatchObject({
+      startRow: 0,
+      endRow: 20,
+      pageIndex: 0,
+      pageSize: 20,
+      filterModel: { global: 'abc', columns: { name: { operator: 'eq', value: 'x' } } },
+    })
+  })
+
+  it('setFilter resets to page 0', async () => {
+    const getRows = vi.fn(async () => ({ rows: [], rowCount: 100 }))
+    const ctl = createServerDataSource<Row>({ getRows }, { pageSize: 10, onChange: () => {} })
+    ctl.setPage(3)
+    await flush()
+    ctl.setFilter({ global: 'q' })
+    await flush()
+    expect(ctl.getState().pageIndex).toBe(0)
+    const req = getRows.mock.calls.at(-1)![0]
+    expect(req.startRow).toBe(0)
+  })
+
+  it('uses the default page size of 50 when unspecified', () => {
+    const ctl = createServerDataSource<Row>(
+      { getRows: async () => ({ rows: [], rowCount: 0 }) },
+      { onChange: () => {} },
+    )
+    expect(ctl.getState().pageSize).toBe(50)
+  })
+})
+
+describe('createServerDataSource - setPage edge cases', () => {
+  it('clamps a negative page index to 0', async () => {
+    const getRows = vi.fn(async () => ({ rows: [], rowCount: 0 }))
+    const ctl = createServerDataSource<Row>({ getRows }, { pageSize: 10, onChange: () => {} })
+    ctl.setPage(5)
+    await flush()
+    getRows.mockClear()
+    ctl.setPage(-3)
+    await flush()
+    expect(ctl.getState().pageIndex).toBe(0)
+    expect(getRows).toHaveBeenCalledTimes(1)
+  })
+
+  it('does nothing when the page index is unchanged', async () => {
+    const getRows = vi.fn(async () => ({ rows: [], rowCount: 0 }))
+    const ctl = createServerDataSource<Row>({ getRows }, { pageSize: 10, onChange: () => {} })
+    await flush()
+    getRows.mockClear()
+    ctl.setPage(0) // already on page 0
+    await flush()
+    expect(getRows).not.toHaveBeenCalled()
+  })
+})
+
+describe('createServerDataSource - setPageSize', () => {
+  it('clamps page size to a minimum of 1, resets page, and re-fetches', async () => {
+    const getRows = vi.fn(async () => ({ rows: [], rowCount: 0 }))
+    const ctl = createServerDataSource<Row>({ getRows }, { pageSize: 10, onChange: () => {} })
+    ctl.setPage(2)
+    await flush()
+    getRows.mockClear()
+    ctl.setPageSize(0)
+    await flush()
+    expect(ctl.getState().pageSize).toBe(1)
+    expect(ctl.getState().pageIndex).toBe(0)
+    expect(getRows).toHaveBeenCalledTimes(1)
+  })
+
+  it('recomputes pageCount from total and page size', async () => {
+    const getRows = vi.fn(async () => ({ rows: [], rowCount: 95 }))
+    const ctl = createServerDataSource<Row>({ getRows }, { pageSize: 10, onChange: () => {} })
+    ctl.refresh()
+    await flush()
+    expect(ctl.getState().pageCount).toBe(10) // ceil(95/10)
+    ctl.setPageSize(20)
+    await flush()
+    expect(ctl.getState().pageCount).toBe(5) // ceil(95/20)
+  })
+})
+
+describe('createServerDataSource - error handling', () => {
+  it('captures a rejection into state.error and clears rows', async () => {
+    const boom = new Error('network down')
+    const ctl = createServerDataSource<Row>(
+      { getRows: async () => { throw boom } },
+      { pageSize: 10, onChange: () => {} },
+    )
+    ctl.refresh()
+    await flush()
+    const s = ctl.getState()
+    expect(s.error).toBe(boom)
+    expect(s.rows).toEqual([])
+    expect(s.loading).toBe(false)
+  })
+
+  it('clears a prior error on the next successful fetch', async () => {
+    let fail = true
+    const ctl = createServerDataSource<Row>(
+      {
+        getRows: async () => {
+          if (fail) throw new Error('x')
+          return { rows: [{ id: 1 }], rowCount: 1 }
+        },
+      },
+      { pageSize: 10, onChange: () => {} },
+    )
+    ctl.refresh()
+    await flush()
+    expect(ctl.getState().error).toBeInstanceOf(Error)
+    fail = false
+    ctl.refresh()
+    await flush()
+    expect(ctl.getState().error).toBe(null)
+    expect(ctl.getState().rows).toEqual([{ id: 1 }])
+  })
+
+  it('ignores a stale REJECTION when a newer request superseded it', async () => {
+    let call = 0
+    const src: ServerDataSource<Row> = {
+      getRows: vi.fn(async (req) => {
+        call += 1
+        if (call === 1) {
+          await new Promise((r) => setTimeout(r, 40))
+          throw new Error('stale failure')
+        }
+        await new Promise((r) => setTimeout(r, 5))
+        return { rows: [{ id: req.startRow }], rowCount: 100 }
+      }),
+    }
+    const ctl = createServerDataSource<Row>(src, { pageSize: 10, onChange: () => {} })
+    ctl.refresh() // slow + throws
+    ctl.setPage(2) // fast + wins
+    await new Promise((r) => setTimeout(r, 80))
+    const s = ctl.getState()
+    expect(s.error).toBe(null) // stale rejection did not land
+    expect(s.rows).toEqual([{ id: 20 }])
+  })
+})
+
+describe('createServerDataSource - dispose', () => {
+  it('refresh after dispose does not call getRows', async () => {
+    const getRows = vi.fn(async () => ({ rows: [], rowCount: 0 }))
+    const ctl = createServerDataSource<Row>({ getRows }, { pageSize: 10, onChange: () => {} })
+    ctl.dispose()
+    ctl.refresh()
+    await flush()
+    expect(getRows).not.toHaveBeenCalled()
+  })
+
+  it('a response resolving after dispose is ignored', async () => {
+    const onChange = vi.fn()
+    const ctl = createServerDataSource<Row>(
+      {
+        getRows: async () => {
+          await new Promise((r) => setTimeout(r, 30))
+          return { rows: [{ id: 1 }], rowCount: 1 }
+        },
+      },
+      { pageSize: 10, onChange },
+    )
+    ctl.refresh()
+    ctl.dispose()
+    await new Promise((r) => setTimeout(r, 60))
+    expect(ctl.getState().rows).toEqual([])
+  })
+})

package/src/spreadsheet.test.ts

@@ -0,0 +1,489 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { spreadsheetLayout, spansToMerges } from './spreadsheet'
+import type { SpreadsheetActionOptions, SpanColumn } from './spreadsheet'
+
+// jsdom does not implement the global `CSS` object, which `findCell` uses via
+// `CSS.escape`. Provide a minimal polyfill so the action's selector queries
+// run. (A real browser ships CSS.escape; this is purely an env gap.)
+if (typeof globalThis.CSS === 'undefined') {
+  // @ts-expect-error - minimal shim for the test environment
+  globalThis.CSS = { escape: (s: string) => s.replace(/["\\]/g, '\\$&') }
+} else if (typeof globalThis.CSS.escape !== 'function') {
+  // @ts-expect-error - augment partial CSS object
+  globalThis.CSS.escape = (s: string) => s.replace(/["\\]/g, '\\$&')
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Flush a queued requestAnimationFrame callback. The action batches its
+ *  work into one rAF, so tests must advance a frame to observe the effect. */
+function flushFrame(): Promise<void> {
+  return new Promise((resolve) => {
+    // Two rAFs: the first lets any already-queued callback run, the second
+    // guarantees we resolve AFTER that callback has executed.
+    requestAnimationFrame(() => requestAnimationFrame(() => resolve()))
+  })
+}
+
+/** Build a `<table>` with a header-less body of `rows` x `cols`. Each TD is
+ *  tagged with `data-svgrid-row` (display index) + `data-col-id` exactly the
+ *  way SvGrid emits them, which is what the layout helper queries on. */
+function buildGrid(
+  rows: number,
+  columnOrder: readonly string[],
+): { host: HTMLElement; cellAt: (r: number, colId: string) => HTMLTableCellElement } {
+  const host = document.createElement('div')
+  const table = document.createElement('table')
+  const tbody = document.createElement('tbody')
+  for (let r = 0; r < rows; r += 1) {
+    const tr = document.createElement('tr')
+    for (const colId of columnOrder) {
+      const td = document.createElement('td')
+      td.setAttribute('data-svgrid-row', String(r))
+      td.setAttribute('data-col-id', colId)
+      td.textContent = `${colId}-${r}`
+      tr.appendChild(td)
+    }
+    tbody.appendChild(tr)
+  }
+  table.appendChild(tbody)
+  host.appendChild(table)
+  document.body.appendChild(host)
+
+  const cellAt = (r: number, colId: string): HTMLTableCellElement => {
+    const el = host.querySelector<HTMLTableCellElement>(
+      `td[data-svgrid-row="${r}"][data-col-id="${colId}"]`,
+    )
+    if (!el) throw new Error(`no cell at row=${r} col=${colId}`)
+    return el
+  }
+  return { host, cellAt }
+}
+
+let hosts: HTMLElement[] = []
+function track(host: HTMLElement): HTMLElement {
+  hosts.push(host)
+  return host
+}
+
+beforeEach(() => {
+  hosts = []
+})
+afterEach(() => {
+  for (const h of hosts) h.remove()
+  document.body.innerHTML = ''
+})
+
+// ---------------------------------------------------------------------------
+// Merges
+// ---------------------------------------------------------------------------
+
+describe('spreadsheetLayout - merges', () => {
+  it('applies colspan + hides covered cells horizontally', async () => {
+    const cols = ['a', 'b', 'c']
+    const { host, cellAt } = buildGrid(2, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'a', colspan: 2 }],
+    })
+    await flushFrame()
+
+    const origin = cellAt(0, 'a')
+    expect(origin.getAttribute('colspan')).toBe('2')
+    expect(origin.hasAttribute('rowspan')).toBe(false)
+    expect(origin.getAttribute('data-svgrid-sheet')).toBe('')
+    // Covered neighbour to the right is hidden + marked.
+    expect(cellAt(0, 'b').style.display).toBe('none')
+    expect(cellAt(0, 'b').getAttribute('data-svgrid-sheet')).toBe('')
+    // Untouched cells stay visible.
+    expect(cellAt(0, 'c').style.display).toBe('')
+    expect(cellAt(1, 'a').style.display).toBe('')
+
+    action.destroy()
+  })
+
+  it('applies rowspan + hides covered cells vertically', async () => {
+    const cols = ['a', 'b']
+    const { host, cellAt } = buildGrid(3, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'a', rowspan: 2 }],
+    })
+    await flushFrame()
+
+    const origin = cellAt(0, 'a')
+    expect(origin.getAttribute('rowspan')).toBe('2')
+    expect(origin.hasAttribute('colspan')).toBe(false)
+    expect(cellAt(1, 'a').style.display).toBe('none')
+    expect(cellAt(2, 'a').style.display).toBe('') // outside the span
+    action.destroy()
+  })
+
+  it('handles a rectangular colspan + rowspan block', async () => {
+    const cols = ['a', 'b', 'c']
+    const { host, cellAt } = buildGrid(3, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'a', colspan: 2, rowspan: 2 }],
+    })
+    await flushFrame()
+
+    expect(cellAt(0, 'a').getAttribute('colspan')).toBe('2')
+    expect(cellAt(0, 'a').getAttribute('rowspan')).toBe('2')
+    // All covered cells except the origin are hidden.
+    expect(cellAt(0, 'b').style.display).toBe('none')
+    expect(cellAt(1, 'a').style.display).toBe('none')
+    expect(cellAt(1, 'b').style.display).toBe('none')
+    // c column + row 2 untouched.
+    expect(cellAt(0, 'c').style.display).toBe('')
+    expect(cellAt(2, 'a').style.display).toBe('')
+    action.destroy()
+  })
+
+  it('clamps zero/negative span to a minimum of 1 (no colspan/rowspan attr)', async () => {
+    const cols = ['a', 'b']
+    const { host, cellAt } = buildGrid(2, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'a', colspan: 0, rowspan: -5 }],
+    })
+    await flushFrame()
+    const origin = cellAt(0, 'a')
+    // Clamped to 1, so no span attributes are written, but it is still marked.
+    expect(origin.hasAttribute('colspan')).toBe(false)
+    expect(origin.hasAttribute('rowspan')).toBe(false)
+    expect(origin.getAttribute('data-svgrid-sheet')).toBe('')
+    expect(cellAt(0, 'b').style.display).toBe('') // nothing covered
+    action.destroy()
+  })
+
+  it('skips a merge whose columnId is not in columnOrder', async () => {
+    const cols = ['a', 'b']
+    const { host, cellAt } = buildGrid(1, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'ghost', colspan: 2 }],
+    })
+    await flushFrame()
+    expect(cellAt(0, 'a').hasAttribute('data-svgrid-sheet')).toBe(false)
+    expect(cellAt(0, 'b').style.display).toBe('')
+    action.destroy()
+  })
+
+  it('skips a merge whose origin cell is not rendered', async () => {
+    const cols = ['a', 'b']
+    const { host, cellAt } = buildGrid(1, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 99, columnId: 'a', colspan: 2 }],
+    })
+    await flushFrame()
+    // Nothing marked anywhere.
+    expect(host.querySelectorAll('[data-svgrid-sheet]').length).toBe(0)
+    expect(cellAt(0, 'a').style.display).toBe('')
+    action.destroy()
+  })
+
+  it('ignores covered cells that fall outside the columnOrder or render window', async () => {
+    const cols = ['a', 'b']
+    // Only 1 row rendered, but ask for a colspan that runs off the column
+    // list AND a rowspan that runs off the rendered rows.
+    const { host, cellAt } = buildGrid(1, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'b', colspan: 3, rowspan: 3 }],
+    })
+    await flushFrame()
+    const origin = cellAt(0, 'b')
+    expect(origin.getAttribute('colspan')).toBe('3')
+    expect(origin.getAttribute('rowspan')).toBe('3')
+    // No sibling to the right of b, and rows 1/2 don't exist - so the only
+    // marked cell is the origin itself.
+    expect(host.querySelectorAll('[data-svgrid-sheet]').length).toBe(1)
+    action.destroy()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Selection-edge inheritance
+// ---------------------------------------------------------------------------
+
+describe('spreadsheetLayout - selection edge inheritance', () => {
+  it('mirrors range-right / range-bottom / selected-range flags onto the origin', async () => {
+    const cols = ['a', 'b']
+    const { host, cellAt } = buildGrid(2, cols)
+    track(host)
+    // Mark the far covered cell with range edge flags BEFORE applying.
+    cellAt(1, 'b').setAttribute('data-range-right', 'true')
+    cellAt(1, 'b').setAttribute('data-range-bottom', 'true')
+    cellAt(0, 'b').setAttribute('data-selected-range', 'true')
+
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'a', colspan: 2, rowspan: 2 }],
+    })
+    await flushFrame()
+    const origin = cellAt(0, 'a')
+    expect(origin.classList.contains('sv-merge-edge-right')).toBe(true)
+    expect(origin.classList.contains('sv-merge-edge-bottom')).toBe(true)
+    expect(origin.classList.contains('sv-merge-in-range')).toBe(true)
+    action.destroy()
+  })
+
+  it('leaves edge classes off when no range flags are present', async () => {
+    const cols = ['a', 'b']
+    const { host, cellAt } = buildGrid(2, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'a', colspan: 2, rowspan: 2 }],
+    })
+    await flushFrame()
+    const origin = cellAt(0, 'a')
+    expect(origin.classList.contains('sv-merge-edge-right')).toBe(false)
+    expect(origin.classList.contains('sv-merge-edge-bottom')).toBe(false)
+    expect(origin.classList.contains('sv-merge-in-range')).toBe(false)
+    action.destroy()
+  })
+
+  it('treats the origin own selected-range flag as in-range', async () => {
+    const cols = ['a']
+    const { host, cellAt } = buildGrid(1, cols)
+    track(host)
+    cellAt(0, 'a').setAttribute('data-selected-range', 'true')
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'a' }],
+    })
+    await flushFrame()
+    expect(cellAt(0, 'a').classList.contains('sv-merge-in-range')).toBe(true)
+    action.destroy()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Borders
+// ---------------------------------------------------------------------------
+
+describe('spreadsheetLayout - borders', () => {
+  it('injects an overlay with the requested edge styles', async () => {
+    const cols = ['a']
+    const { host, cellAt } = buildGrid(1, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      borders: [
+        {
+          rowIndex: 0,
+          columnId: 'a',
+          top: { width: 3, style: 'dashed', color: 'red' },
+          bottom: {}, // defaults: 2px solid currentColor
+        },
+      ],
+    })
+    await flushFrame()
+    const td = cellAt(0, 'a')
+    const overlay = td.querySelector<HTMLElement>('.sv-cell-border-overlay')
+    expect(overlay).not.toBeNull()
+    expect(overlay!.style.borderTop).toBe('3px dashed red')
+    // jsdom's CSSOM drops the `currentColor` keyword from the border
+    // shorthand, but the width + style survive, confirming the default
+    // (2px solid) edge was emitted.
+    expect(overlay!.style.borderBottom).toContain('2px solid')
+    // No left/right set.
+    expect(overlay!.style.borderLeft).toBe('')
+    expect(td.getAttribute('data-svgrid-sheet')).toBe('')
+    // The TD becomes a positioning context.
+    expect(td.style.position).toBe('relative')
+    action.destroy()
+  })
+
+  it('skips a border spec with no edges set (no overlay injected)', async () => {
+    const cols = ['a']
+    const { host, cellAt } = buildGrid(1, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      borders: [{ rowIndex: 0, columnId: 'a' }],
+    })
+    await flushFrame()
+    expect(cellAt(0, 'a').querySelector('.sv-cell-border-overlay')).toBeNull()
+    expect(cellAt(0, 'a').hasAttribute('data-svgrid-sheet')).toBe(false)
+    action.destroy()
+  })
+
+  it('skips a border spec whose target cell is absent', async () => {
+    const cols = ['a']
+    const { host } = buildGrid(1, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      borders: [{ rowIndex: 5, columnId: 'a', top: { width: 1 } }],
+    })
+    await flushFrame()
+    expect(host.querySelectorAll('.sv-cell-border-overlay').length).toBe(0)
+    action.destroy()
+  })
+
+  it('does not override an already-positioned TD', async () => {
+    const cols = ['a']
+    const { host, cellAt } = buildGrid(1, cols)
+    track(host)
+    cellAt(0, 'a').style.position = 'absolute'
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      borders: [{ rowIndex: 0, columnId: 'a', left: { color: 'blue' } }],
+    })
+    await flushFrame()
+    expect(cellAt(0, 'a').style.position).toBe('absolute')
+    action.destroy()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Cleanup + update + destroy
+// ---------------------------------------------------------------------------
+
+describe('spreadsheetLayout - update + cleanup', () => {
+  it('clears prior decorations on the next apply (update path)', async () => {
+    const cols = ['a', 'b']
+    const { host, cellAt } = buildGrid(2, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'a', colspan: 2 }],
+      borders: [{ rowIndex: 1, columnId: 'a', top: { width: 1 } }],
+    })
+    await flushFrame()
+    expect(cellAt(0, 'a').getAttribute('colspan')).toBe('2')
+    expect(cellAt(1, 'a').querySelector('.sv-cell-border-overlay')).not.toBeNull()
+
+    // Update to an empty spec - everything from the previous run is removed.
+    action.update({ columnOrder: cols, merges: [], borders: [] })
+    await flushFrame()
+    expect(cellAt(0, 'a').hasAttribute('colspan')).toBe(false)
+    expect(cellAt(0, 'b').style.display).toBe('')
+    expect(cellAt(0, 'a').hasAttribute('data-svgrid-sheet')).toBe(false)
+    expect(cellAt(1, 'a').querySelector('.sv-cell-border-overlay')).toBeNull()
+    action.destroy()
+  })
+
+  it('re-applies decorations when the grid body mutates (MutationObserver)', async () => {
+    const cols = ['a', 'b']
+    const { host, cellAt } = buildGrid(1, cols)
+    track(host)
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 1, columnId: 'a', colspan: 2 }],
+    })
+    await flushFrame()
+    // Row 1 does not exist yet - nothing applied.
+    expect(host.querySelectorAll('[data-svgrid-sheet]').length).toBe(0)
+
+    // Simulate the grid rendering a new row -> observer schedules apply.
+    const tbody = host.querySelector('tbody')!
+    const tr = document.createElement('tr')
+    for (const colId of cols) {
+      const td = document.createElement('td')
+      td.setAttribute('data-svgrid-row', '1')
+      td.setAttribute('data-col-id', colId)
+      tr.appendChild(td)
+    }
+    tbody.appendChild(tr)
+    await flushFrame()
+    await flushFrame()
+    expect(cellAt(1, 'a').getAttribute('colspan')).toBe('2')
+    action.destroy()
+  })
+
+  it('destroy disconnects the observer and cancels a pending frame', async () => {
+    const cols = ['a', 'b']
+    const { host, cellAt } = buildGrid(1, cols)
+    track(host)
+    // Destroy immediately - the first scheduled frame is pending.
+    const action = spreadsheetLayout(host, {
+      columnOrder: cols,
+      merges: [{ rowIndex: 0, columnId: 'a', colspan: 2 }],
+    })
+    action.destroy()
+    await flushFrame()
+    await flushFrame()
+    // Frame was cancelled before apply ran.
+    expect(cellAt(0, 'a').hasAttribute('colspan')).toBe(false)
+
+    // After destroy, mutations no longer trigger apply.
+    const tbody = host.querySelector('tbody')!
+    tbody.appendChild(document.createElement('tr'))
+    await flushFrame()
+    await flushFrame()
+    expect(cellAt(0, 'a').hasAttribute('colspan')).toBe(false)
+  })
+
+  it('treats null merges / borders as empty (no throw)', async () => {
+    const cols = ['a']
+    const { host } = buildGrid(1, cols)
+    track(host)
+    const opts: SpreadsheetActionOptions = {
+      columnOrder: cols,
+      merges: null,
+      borders: null,
+    }
+    const action = spreadsheetLayout(host, opts)
+    await flushFrame()
+    expect(host.querySelectorAll('[data-svgrid-sheet]').length).toBe(0)
+    action.destroy()
+  })
+})
+
+describe('spansToMerges - declarative colSpan/rowSpan -> MergeSpec[]', () => {
+  type Row = { region: string; q: string; amt: number }
+  const rows: Row[] = [
+    { region: 'AMER', q: 'Q1', amt: 1 },
+    { region: 'AMER', q: 'Q2', amt: 2 },
+    { region: 'AMER', q: 'Q3', amt: 3 },
+    { region: 'EMEA', q: 'Q1', amt: 4 },
+    { region: 'EMEA', q: 'Q2', amt: 5 },
+  ]
+  // Merge each run of equal `region` values downward.
+  function regionRowSpan(): SpanColumn<Row>['rowSpan'] {
+    return ({ data, rowIndex }) => {
+      if (rowIndex > 0 && rows[rowIndex - 1]!.region === data.region) return 1 // covered
+      let n = 1
+      while (rows[rowIndex + n]?.region === data.region) n += 1
+      return n
+    }
+  }
+
+  it('emits a rowspan merge at each run origin and skips covered rows', () => {
+    const columns: SpanColumn<Row>[] = [{ id: 'region', field: 'region', rowSpan: regionRowSpan() }]
+    const merges = spansToMerges(rows, columns)
+    // AMER spans rows 0..2 (rowspan 3), EMEA spans rows 3..4 (rowspan 2).
+    expect(merges).toEqual([
+      { rowIndex: 0, columnId: 'region', colspan: undefined, rowspan: 3 },
+      { rowIndex: 3, columnId: 'region', colspan: undefined, rowspan: 2 },
+    ])
+  })
+
+  it('supports colSpan and marks covered columns', () => {
+    const columns: SpanColumn<Row>[] = [
+      { id: 'a', field: 'region', colSpan: ({ rowIndex }) => (rowIndex === 0 ? 2 : 1) },
+      { id: 'b', field: 'q' },
+      { id: 'c', field: 'amt' },
+    ]
+    const merges = spansToMerges(rows.slice(0, 1), columns)
+    expect(merges).toEqual([{ rowIndex: 0, columnId: 'a', colspan: 2, rowspan: undefined }])
+  })
+
+  it('returns no merges when no column defines spans', () => {
+    expect(spansToMerges(rows, [{ id: 'region', field: 'region' }])).toEqual([])
+  })
+})