@svgrid/grid 3.0.7 → 3.0.9

package/src/svgrid.column-cell-recycling.test.ts

@@ -0,0 +1,120 @@
+/**
+ * DOM: body cells are recycled across the column window.
+ *
+ * With column virtualization on, the body cells' {#each} is keyed by a slot,
+ * not by the column id. A column keeps its <td> while it stays in the window;
+ * a column entering the window takes the <td> of one that left. A thumb drag
+ * that jumps far along a wide grid therefore updates the cells in place
+ * instead of destroying the window's cells and creating new ones.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { flushSync, mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import { renderComponent } from './render-component'
+import CountingCell from './counting-cell.test.svelte'
+
+const COLS = 400
+const ROWS = 10
+
+type Row = Record<string, number>
+
+function makeData(): Row[] {
+  return Array.from({ length: ROWS }, (_, r) => {
+    const row: Row = { id: r }
+    for (let c = 0; c < COLS; c += 1) row[`c${c}`] = r * 1000 + c
+    return row
+  })
+}
+
+let cleanup: (() => void) | null = null
+afterEach(() => {
+  cleanup?.()
+  cleanup = null
+})
+
+async function mountGrid(columns: unknown[]) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvGrid, {
+    target,
+    props: {
+      data: makeData(),
+      columns,
+      getRowId: (r: Row) => String(r.id),
+      containerHeight: 400,
+      containerWidth: 1000,
+    } as never,
+  })
+  flushSync()
+  await new Promise((r) => setTimeout(r, 30))
+  flushSync()
+  cleanup = () => {
+    unmount(app)
+    target.remove()
+  }
+  return target
+}
+
+async function scrollTo(root: HTMLElement, left: number) {
+  const container = root.querySelector<HTMLElement>('.sv-grid-container')!
+  container.scrollLeft = left
+  container.dispatchEvent(new Event('scroll'))
+  await new Promise((r) => setTimeout(r, 40))
+  flushSync()
+}
+
+const firstRowCells = (root: HTMLElement) =>
+  [...root.querySelector('tbody tr')!.querySelectorAll<HTMLElement>(':scope > td[data-col-id]')]
+
+const plainColumns = () => Array.from({ length: COLS }, (_, c) => ({ field: `c${c}`, header: `C${c}`, width: 100 }))
+
+describe('body cells recycled across the column window', { timeout: 30_000 }, () => {
+  it('reuses the <td>s on a far jump and every cell shows its own column', async () => {
+    const root = await mountGrid(plainColumns())
+    const before = firstRowCells(root)
+    expect(before[0]!.dataset.colId).toBe('c0')
+
+    await scrollTo(root, 200 * 100)
+    const after = firstRowCells(root)
+    const ids = after.map((td) => td.dataset.colId!)
+    // The window moved: none of the first columns are rendered any more.
+    expect(ids).not.toContain('c0')
+    expect(ids.some((id) => Number(id.slice(1)) >= 195)).toBe(true)
+    // ...and the cells are the same elements, now showing other columns.
+    const reused = after.filter((td) => before.includes(td)).length
+    expect(reused).toBeGreaterThanOrEqual(Math.min(before.length, after.length) - 2)
+    // Every cell's text is its own column's value (row 0: value = column index).
+    for (const td of after) expect(td.textContent!.trim()).toBe(td.dataset.colId!.slice(1))
+    // Ids stay unique.
+    expect(new Set(after.map((td) => td.id)).size).toBe(after.length)
+  })
+
+  it('keeps a column on the same <td> while it stays in the window', async () => {
+    const root = await mountGrid(plainColumns())
+    const byColumn = () => new Map(firstRowCells(root).map((td) => [td.dataset.colId!, td]))
+    const before = byColumn()
+    await scrollTo(root, 200)
+    const after = byColumn()
+    const kept = [...before.keys()].filter((id) => after.has(id))
+    expect(kept.length).toBeGreaterThan(0)
+    for (const id of kept) expect(after.get(id)).toBe(before.get(id))
+  })
+
+  it('re-creates an app cell component per column instead of re-propping it', async () => {
+    const columns = Array.from({ length: COLS }, (_, c) => ({
+      field: `c${c}`,
+      header: `C${c}`,
+      width: 100,
+      cell: (ctx: { getValue: () => unknown; column: { id: string } }) =>
+        renderComponent(CountingCell, { columnId: ctx.column.id, value: ctx.getValue() }),
+    }))
+    const root = await mountGrid(columns)
+    await scrollTo(root, 200 * 100)
+    // Each mounted instance records the column it was created for; a cell
+    // showing a column must be an instance created for that column.
+    for (const td of firstRowCells(root)) {
+      const el = td.querySelector<HTMLElement>('[data-counting-cell]')!
+      expect(el.dataset.createdFor).toBe(td.dataset.colId)
+    }
+  })
+})

package/src/svgrid.interaction.test.ts

@@ -320,7 +320,10 @@ describe('SvGrid interactions - cell pointer events', () => {
       if (!a || !c) return -1 // jsdom didn't lay the cells out; caller skips
       a.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, pointerId: 1, button: 0, pointerType }))
       await tick()
-      c.dispatchEvent(new PointerEvent('pointerenter', { bubbles: true, pointerId: 1, pointerType }))
+      // What a browser fires as the pointer moves into the cell: `pointerover`
+      // (bubbles, from the cell the pointer left), then `pointerenter`.
+      c.dispatchEvent(new PointerEvent('pointerover', { bubbles: true, pointerId: 1, pointerType, relatedTarget: a }))
+      c.dispatchEvent(new PointerEvent('pointerenter', { bubbles: false, pointerId: 1, pointerType, relatedTarget: a }))
       await tick()
       return target.querySelectorAll('[data-selected-range="true"]').length
     } finally {

package/src/svgrid.new-features.wrapper.test.ts

@@ -77,8 +77,9 @@ describe('SvGrid wrapper - cellClass + rowClass', () => {
     expect(source).toMatch(/function computeCellClass/)
     // The td that draws a merge shows the origin cell, so the class comes
     // from the cell that draws (cellRow / cellColumn): the row's own outside a merge.
-    expect(source).toMatch(/userCellClass = computeCellClass\(\s*cellRow,\s*cellColumn,?\s*\)/)
-    expect(source).toMatch(/class=\{`sv-grid-cell \$\{userCellClass\}`\}/)
+    // Computed once per cell in `bodyCellInfo`, which the td reads as `c`.
+    expect(source).toMatch(/userCellClass: computeCellClass\(\s*cellRow,\s*cellColumn,?\s*\)/)
+    expect(source).toMatch(/class=\{`sv-grid-cell \$\{c\.userCellClass\}`\}/)
   })
 })
 
@@ -99,12 +100,12 @@ describe('SvGrid wrapper - declarative cell validation (validate hook)', () => {
     // The virtualized window, the plain body and the frozen rows all render
     // `bodyRow`, so the class appears exactly once: the two copies the
     // render paths used to carry had drifted apart.
-    const hits = source.match(/class:sv-grid-cell-invalid=\{cellValidity\.invalid\}/g) ?? []
+    const hits = source.match(/class:sv-grid-cell-invalid=\{c\.cellValidity\.invalid\}/g) ?? []
     expect(hits.length).toBe(1)
     expect(source).toMatch(/\{#snippet bodyRow\(/)
     expect((source.match(/\{@render bodyRow\(/g) ?? []).length).toBe(3)
     // Message wins over the plain column tooltip when the cell is invalid.
-    expect(source).toMatch(/cellValidity\.invalid && cellValidity\.message/)
+    expect(source).toMatch(/c\.cellValidity\.invalid && c\.cellValidity\.message/)
   })
 
   it('forwards computeCellValidity through the controller so the wrapper can read it', () => {

package/src/svgrid.pinned-column-virtualization.test.ts

@@ -0,0 +1,162 @@
+/**
+ * DOM: pinned columns with column virtualization on (the default).
+ *
+ * Pinned cells are position: sticky, so they must stay in the DOM. The grid
+ * used to keep them there by rendering one contiguous run from column 0 (a
+ * left pin) to the last column (a right pin), so pinning either edge of a
+ * 1,000-column grid rendered every column. It now renders three runs - the
+ * pinned-left columns, the virtual window, the pinned-right columns - with a
+ * spacer cell for the columns between two runs.
+ *
+ * The table uses `table-layout: fixed`, so every row must give each column the
+ * same slot. The checks compare each row's total declared width (cells plus
+ * spacers) against the leaf header row.
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { flushSync, mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+
+const COLS = 120
+const ROWS = 20
+
+type Row = Record<string, number>
+
+function leafColumns() {
+  return Array.from({ length: COLS }, (_, c) => ({ field: `c${c}`, header: `C${c}`, width: 100 }))
+}
+
+function makeData(): Row[] {
+  return Array.from({ length: ROWS }, (_, r) => {
+    const row: Row = { id: r }
+    for (let c = 0; c < COLS; c += 1) row[`c${c}`] = r * COLS + c
+    return row
+  })
+}
+
+let cleanup: (() => void) | null = null
+afterEach(() => {
+  cleanup?.()
+  cleanup = null
+})
+
+async function mountGrid(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvGrid, {
+    target,
+    props: {
+      data: makeData(),
+      columns: leafColumns(),
+      getRowId: (r: Row) => String(r.id),
+      containerHeight: 400,
+      containerWidth: 1000,
+      ...props,
+    } as never,
+  })
+  flushSync()
+  // The column virtualizer learns its count and viewport in effects.
+  await new Promise((r) => setTimeout(r, 30))
+  flushSync()
+  cleanup = () => {
+    unmount(app)
+    target.remove()
+  }
+  return target
+}
+
+const px = (el: Element) => Number.parseFloat((el as HTMLElement).style.width) || 0
+const rowWidth = (tr: Element) => [...tr.children].reduce((sum, cell) => sum + px(cell), 0)
+const dataCells = (tr: Element) => [...tr.querySelectorAll<HTMLElement>('td[data-col-id]')]
+const firstBodyRow = (root: HTMLElement) => root.querySelector('tbody tr')!
+const leafHeaderRow = (root: HTMLElement) => [...root.querySelectorAll('thead tr')].pop()!
+
+describe('pinned columns with column virtualization', { timeout: 30_000 }, () => {
+  it('renders only the window when nothing is pinned (baseline)', async () => {
+    const root = await mountGrid({})
+    const ids = dataCells(firstBodyRow(root)).map((td) => td.dataset.colId)
+    expect(ids.length).toBeLessThan(40)
+    expect(ids).not.toContain(`c${COLS - 1}`)
+  })
+
+  it('renders the window plus the pinned columns, not every column', async () => {
+    const root = await mountGrid({ initialColumnPinning: { left: ['c0'], right: [`c${COLS - 1}`] } })
+    const ids = dataCells(firstBodyRow(root)).map((td) => td.dataset.colId)
+    // Before: pinning both ends rendered all 120 columns in every row.
+    expect(ids.length).toBeLessThan(40)
+    expect(ids[0]).toBe('c0')
+    expect(ids[ids.length - 1]).toBe(`c${COLS - 1}`)
+    // The columns between the window and the right pin are a spacer, not cells.
+    const spacers = firstBodyRow(root).querySelectorAll('td.sv-grid-cell-spacer')
+    expect(spacers.length).toBeGreaterThan(0)
+  })
+
+  it('gives every row the same slots as the leaf header row', async () => {
+    const root = await mountGrid({ initialColumnPinning: { left: ['c0'], right: [`c${COLS - 1}`] } })
+    const header = leafHeaderRow(root)
+    const body = firstBodyRow(root)
+    expect(slots(body)).toBe(slots(header))
+    // Fixed layout: cells plus spacers cover every column (plus the system
+    // columns, such as the row checkbox, that sit before them).
+    expect(rowWidth(header)).toBeGreaterThanOrEqual(COLS * 100)
+    expect(rowWidth(body)).toBeCloseTo(rowWidth(header), 0)
+  })
+
+  it('splits a column group that crosses a seam into one cell per run', async () => {
+    const columns = [
+      { id: 'all', header: 'Everything', columns: leafColumns() },
+    ]
+    const root = await mountGrid({ columns, initialColumnPinning: { left: ['c0'], right: [`c${COLS - 1}`] } })
+    const groupCells = [...root.querySelectorAll<HTMLElement>('th.sv-grid-group-header-cell')]
+    // One piece over the left pin + window, one over the right pin; distinct
+    // keys, or Svelte would have thrown on a duplicate key in the each block.
+    expect(groupCells.length).toBe(2)
+    expect(groupCells.every((th) => th.textContent?.includes('Everything'))).toBe(true)
+    const groupRow = groupCells[0]!.closest('tr')!
+    const header = leafHeaderRow(root)
+    expect(slots(groupRow)).toBe(slots(header))
+    expect(rowWidth(groupRow)).toBeCloseTo(rowWidth(header), 0)
+  })
+
+  it('clamps a merged cell to the run it starts in', async () => {
+    const root = await mountGrid({
+      initialColumnPinning: { left: ['c0'], right: [`c${COLS - 1}`] },
+      mergedCells: [{ rowIndex: 0, colIndex: 0, rowSpan: 1, colSpan: COLS }],
+    })
+    const header = leafHeaderRow(root)
+    const body = firstBodyRow(root)
+    // The merge covers every column, but no td may span across a spacer: the
+    // row keeps the header's slots, so each piece stays inside its run.
+    expect(slots(body)).toBe(slots(header))
+    expect(rowWidth(body)).toBeCloseTo(rowWidth(header), 0)
+  })
+})
+
+describe('the first render of a wide grid', { timeout: 30_000 }, () => {
+  it('draws a window of columns, not every column, before anything is measured', async () => {
+    const wide = 2000
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const columns = Array.from({ length: wide }, (_, c) => ({ field: `c${c}`, header: `C${c}`, width: 100 }))
+    const data = [Object.fromEntries([['id', 0], ...columns.map((c, i) => [c.field, i])])]
+    const app = mount(SvGrid, {
+      target,
+      props: { data, columns, getRowId: (r: Row) => String(r.id), containerHeight: 300 } as never,
+    })
+    flushSync()
+    cleanup = () => {
+      unmount(app)
+      target.remove()
+    }
+    // jsdom never lays out, so this is the pre-measure window: the columns
+    // that fit an estimated viewport, plus the overscan.
+    const cells = dataCells(firstBodyRow(target))
+    expect(cells.length).toBeGreaterThan(0)
+    expect(cells.length).toBeLessThan(40)
+    expect(target.querySelectorAll('td').length).toBeLessThan(200)
+  })
+})
+
+/** Table slots a row occupies: each cell counts its colspan. */
+function slots(tr: Element): number {
+  return [...tr.children].reduce((n, cell) => n + ((cell as HTMLTableCellElement).colSpan || 1), 0)
+}

package/src/svgrid.row-model-prop.svelte.test.ts

@@ -138,14 +138,26 @@ describe('the rowModel prop', () => {
     await tick()
 
     // The model was told; the grid did NOT reorder locally, because a model
-    // with `setSort` implies `externalSort`. (The grid also reports the
-    // empty initial sort on mount, as it does for any onSortingChange.)
-    expect(source.sorts.at(-1)).toEqual([{ id: 'name', desc: false }])
+    // with `setSort` implies `externalSort`. Mounting with no sort tells the
+    // model nothing - it used to get an empty sort, which made a server
+    // source refetch page 0 for no reason.
+    expect(source.sorts).toEqual([[{ id: 'name', desc: false }]])
     const firstRow = target.querySelector('tbody .sv-grid-row')!
     expect(firstRow.textContent).toContain('Zoe')
     destroy()
   })
 
+  it('hands initialSorting to the model once, since the model has no initial sort of its own', async () => {
+    const source = handWritten([
+      { id: 1, name: 'Zoe' },
+      { id: 2, name: 'Ada' },
+    ])
+    const { destroy } = await mountGrid({ rowModel: source.model, sortable: true, initialSorting: [{ id: 'name', desc: true }] })
+    await tick()
+    expect(source.sorts).toEqual([[{ id: 'name', desc: true }]])
+    destroy()
+  })
+
   it('lets an explicit prop win over the model', async () => {
     const source = handWritten([{ id: 1, name: 'Ada' }])
     const { target, destroy } = await mountGrid({

package/src/validate.test.ts

@@ -58,6 +58,22 @@ describe('unknown field', () => {
     expect(run({ data: [...loading, ...data], columns: [{ field: 'naem' }] })).toHaveLength(1)
   })
 
+  it('does not walk a million placeholders looking for the sample', () => {
+    // A row model scrolled to its middle: placeholders up to the loaded block.
+    const placeholder = createRowPlaceholder('loading', { index: 0 })
+    const big = new Array(1_000_000).fill(placeholder)
+    big.push({ name: 'x' })
+    let reads = 0
+    const counted = new Proxy(big, {
+      get(target, key, receiver) {
+        if (typeof key === 'string' && /^\d+$/.test(key)) reads += 1
+        return Reflect.get(target, key, receiver)
+      },
+    })
+    expect(run({ data: counted, columns: [{ field: 'naem' }] })).toEqual([])
+    expect(reads).toBeLessThanOrEqual(1000)
+  })
+
   it('looks through group columns', () => {
     const msgs = run({ columns: [{ header: 'Group', columns: [{ field: 'nope' }] }] })
     expect(msgs[0]).toContain('"nope" does not exist')
@@ -181,10 +197,10 @@ describe('gantt versus treeData', () => {
 })
 
 describe('pinning versus column virtualization', () => {
-  it('flags pinning while column virtualization is on by default', () => {
-    const msg = run({ initialColumnPinning: { left: ['name'] } })[0]!
-    expect(msg).toContain('will not stick')
-    expect(msg).toContain('columnVirtualization={false}')
+  // Pinned columns render as their own runs beside the virtual window, so
+  // pinning with column virtualization on (the default) is supported.
+  it('is silent for pinning with column virtualization on by default', () => {
+    expect(run({ initialColumnPinning: { left: ['name'], right: ['name'] } })).toEqual([])
   })
 
   it('is silent once column virtualization is off', () => {

package/src/validate.ts

@@ -24,6 +24,8 @@ import { rowPlaceholderState } from './server-block-cache'
 
 /** How many rows to sample when deciding whether a `field` exists. */
 const FIELD_SAMPLE_ROWS = 10
+/** How many rows to look through for that sample, placeholders included. */
+const FIELD_SCAN_ROWS = 1000
 
 const DOCS = 'https://svgrid.com/docs/getting-started/3-data-and-columns/'
 
@@ -79,9 +81,15 @@ export function validateGridConfig<
   // no data keys at all and say nothing about the columns.
   // Stops at the sample size: this runs on every data change, and a filter
   // over all the rows first was O(n) per tick on a live feed.
+  // The scan is bounded too: a row model scrolled to the middle of a million
+  // rows, or just purged by a sort, hands over a list that is placeholders
+  // up to the loaded block, and walking all of them for ten real rows was
+  // O(n) per block landing. Finding none means nothing to judge by.
   const sample: TData[] = []
-  for (const row of input.data ?? []) {
-    if (sample.length >= FIELD_SAMPLE_ROWS) break
+  const data = input.data ?? []
+  const scan = Math.min(data.length, FIELD_SCAN_ROWS)
+  for (let i = 0; i < scan && sample.length < FIELD_SAMPLE_ROWS; i += 1) {
+    const row = data[i]!
     if (!rowPlaceholderState(row)) sample.push(row)
   }
   // Under server-side grouping the first rows are group rows, which carry
@@ -220,20 +228,9 @@ export function validateGridConfig<
     )
   }
 
-  // ---- 7. Pinning that column virtualization will hide ----------------------
-  // Documented incompatibility: the virtualizer recycles column DOM nodes, so
-  // sticky pinning cannot survive it. `columnVirtualization` defaults to ON,
-  // which means the natural way to write this silently does nothing.
-  const pinned =
-    (input.initialColumnPinning?.left?.length ?? 0) +
-    (input.initialColumnPinning?.right?.length ?? 0)
-  if (pinned > 0 && input.columnVirtualization !== false) {
-    messages.push(
-      '[svgrid] `initialColumnPinning` is set while column virtualization is on ' +
-        '(its default), so the pinned columns will not stick - the virtualizer ' +
-        'recycles column nodes. Add `columnVirtualization={false}`.',
-    )
-  }
+  // (7. was "pinning versus column virtualization". Pinned columns now render
+  // as their own runs beside the virtual window, so the pair is supported and
+  // there is nothing to warn about.)
 
   // ---- 8. Server-mode contracts left half-wired -----------------------------
   // Each of these makes the grid hand control to the consumer. Miss the other

package/src/virtualization/column-virtualizer.ts

@@ -7,6 +7,10 @@ export function createColumnVirtualizer(input: {
   viewportWidth: number
   scrollOffset?: number
   overscan?: number
+  /** Columns kept behind the scroll direction; defaults to `overscan`. */
+  overscanBehind?: number
+  /** Fewest columns left ahead of a scroll before the window moves. */
+  overscanMin?: number
   /** Either a uniform size (number) or a per-column size function. */
   estimateSize?: number | ColumnSizeEstimator
 }) {
@@ -16,6 +20,8 @@ export function createColumnVirtualizer(input: {
     viewportHeight: input.viewportWidth,
     scrollOffset: input.scrollOffset ?? 0,
     overscan: input.overscan ?? 4,
+    overscanBehind: input.overscanBehind,
+    overscanMin: input.overscanMin,
   })
 
   return {

package/src/virtualization/types.ts

@@ -16,8 +16,28 @@ export type VirtualizerOptions = {
    */
   estimateSize: number | ((index: number) => number)
   overscan?: number
+  /**
+   * Items kept on the side the scroll is moving away from (`overscan` is kept
+   * ahead of it). Defaults to `overscan`, a symmetric window. Before the
+   * first scroll there is no direction and both sides get `overscan`.
+   */
+  overscanBehind?: number
+  /**
+   * Keep the rendered window while a scroll leaves at least this many items
+   * rendered ahead of it, and move the window only when the scroll runs past
+   * that: the window is then rebuilt with the full `overscan` ahead, so it
+   * moves `overscan - overscanMin + 1` items at a time instead of one. Each
+   * move costs about the same whether one item enters or several, so fewer,
+   * larger moves are less work, and the scroll frames in between change
+   * nothing. A window built at rest, or after a jump to items outside the
+   * rendered window, carries `overscanMin` instead of `overscan`. Undefined
+   * moves the window on every item boundary, always with `overscan`.
+   */
+  overscanMin?: number
   viewportHeight: number
   scrollOffset?: number
+  /** Internal: the sign of the last scroll movement (-1, 0, 1). */
+  scrollDirection?: number
 }
 
 export type VirtualizerState = {

package/src/virtualization/virtualizer.test.ts

@@ -89,3 +89,155 @@ describe('virtualizer', () => {
     expect(calls).toBe(afterBuild)
   })
 })
+
+describe('virtualizer: overscanBehind', () => {
+  // 1,000 items of 10px in a 100px viewport: items 0-9 visible at offset 0.
+  const make = () =>
+    createVirtualizer({ count: 1000, estimateSize: 10, viewportHeight: 100, overscan: 3, overscanBehind: 1 })
+
+  it('keeps the full overscan on both sides before any scroll', () => {
+    // Created at offset 500: no movement yet, so no direction.
+    const fresh = createVirtualizer({ count: 1000, estimateSize: 10, viewportHeight: 100, overscan: 3, overscanBehind: 1, scrollOffset: 500 })
+    const items = fresh.getVirtualItems()
+    expect(items[0]!.index).toBe(47)
+    expect(items.at(-1)!.index).toBe(50 + 10 + 3)
+  })
+
+  it('puts the overscan ahead of a forward scroll and one item behind it', () => {
+    const v = make()
+    v.setScrollOffset(500)
+    const items = v.getVirtualItems()
+    expect(items[0]!.index).toBe(50 - 1)
+    expect(items.at(-1)!.index).toBe(60 + 3)
+  })
+
+  it('flips when the scroll turns around', () => {
+    const v = make()
+    v.setScrollOffset(500)
+    v.setScrollOffset(400)
+    const items = v.getVirtualItems()
+    expect(items[0]!.index).toBe(40 - 3)
+    expect(items.at(-1)!.index).toBe(50 + 1)
+  })
+
+  it('defaults to a symmetric window', () => {
+    const v = createVirtualizer({ count: 1000, estimateSize: 10, viewportHeight: 100, overscan: 3 })
+    v.setScrollOffset(500)
+    const items = v.getVirtualItems()
+    expect(items[0]!.index).toBe(47)
+    expect(items.at(-1)!.index).toBe(63)
+  })
+})
+
+describe('virtualizer: overscanMin', () => {
+  // 1,000 items of 10px in a 100px viewport; at offset o the visible items
+  // are o/10 .. o/10 + 10.
+  const make = (estimateSize: number | ((i: number) => number) = 10) =>
+    createVirtualizer({ count: 1000, estimateSize, viewportHeight: 100, overscan: 3, overscanBehind: 1, overscanMin: 1 })
+
+  const range = (v: ReturnType<typeof make>) => {
+    const items = v.getVirtualItems()
+    return [items[0]!.index, items.at(-1)!.index]
+  }
+
+  it('renders overscanMin around the visible items at rest and after a jump', () => {
+    // At rest: one item on each side of visible 0..10.
+    const v = make()
+    expect(range(v)).toEqual([0, 11])
+    // Visible 50..60 shares nothing with the window: a jump, so one item
+    // ahead and one behind, as a thumb drag lands.
+    v.setScrollOffset(500)
+    expect(range(v)).toEqual([49, 61])
+    const fresh = createVirtualizer({ count: 1000, estimateSize: 10, viewportHeight: 100, overscan: 3, overscanBehind: 1, overscanMin: 1, scrollOffset: 500 })
+    expect(range(fresh)).toEqual([49, 61])
+  })
+
+  it('keeps the window while one item is left ahead, then moves it three at a time', () => {
+    const v = make()
+    let emits = 0
+    v.subscribe(() => (emits += 1))
+    // Visible end 11 leaves nothing ahead of [0, 11]: the window moves on
+    // with the full overscan ahead.
+    v.setScrollOffset(10)
+    const moved = v.getVirtualItems()
+    expect(range(v)).toEqual([0, 14])
+    expect(emits).toBe(1)
+
+    // Visible ends 12 and 13: item 14 is still rendered ahead of them.
+    v.setScrollOffset(20)
+    v.setScrollOffset(30)
+    expect(v.getVirtualItems()).toBe(moved)
+    expect(emits).toBe(1)
+
+    // Visible end 14 leaves nothing ahead: the window moves by three.
+    v.setScrollOffset(40)
+    expect(range(v)).toEqual([3, 17])
+    expect(emits).toBe(2)
+    v.setScrollOffset(50)
+    v.setScrollOffset(60)
+    expect(emits).toBe(2)
+    v.setScrollOffset(70)
+    expect(range(v)).toEqual([6, 20])
+    expect(emits).toBe(3)
+  })
+
+  it('works the same with per-item sizes', () => {
+    // The per-item path counts visible 0..9 at offset 0, not 0..10: an item
+    // starting exactly at the viewport's end is not in it.
+    const v = make(() => 10)
+    expect(range(v)).toEqual([0, 10])
+    v.setScrollOffset(10)
+    const moved = v.getVirtualItems()
+    expect(range(v)).toEqual([0, 13])
+    v.setScrollOffset(30)
+    expect(v.getVirtualItems()).toBe(moved)
+    v.setScrollOffset(40)
+    expect(range(v)).toEqual([3, 16])
+  })
+
+  it('keeps the window through a turn while it still covers the way back', () => {
+    const v = make()
+    v.setScrollOffset(500)
+    v.setScrollOffset(510)
+    const moved = v.getVirtualItems()
+    expect(range(v)).toEqual([50, 64])
+    v.setScrollOffset(530)
+    // Back up to visible 52..62 and 51..61: items 51 and 50 are one ahead.
+    v.setScrollOffset(520)
+    v.setScrollOffset(510)
+    expect(v.getVirtualItems()).toBe(moved)
+    // Visible start 50 with item 49 missing: the window moves with the full
+    // overscan before it and one item after.
+    v.setScrollOffset(500)
+    expect(range(v)).toEqual([47, 61])
+  })
+
+  it('always renders every visible item', () => {
+    const v = make((i) => 5 + (i % 7) * 3)
+    let seed = 7
+    const random = () => ((seed = (seed * 16807) % 2147483647) / 2147483647)
+    let offset = 0
+    for (let step = 0; step < 2000; step += 1) {
+      // Mostly small steps either way, now and then a jump.
+      offset = random() < 0.05 ? Math.floor(random() * 12_000) : Math.max(0, offset + Math.floor((random() - 0.4) * 60))
+      v.setScrollOffset(offset)
+      const state = v.getState()
+      const items = v.getVirtualItems()
+      const top = Math.min(offset, Math.max(state.totalSize - 100, 0))
+      const visible = items.filter((it) => it.end > top && it.start < top + 100)
+      expect(visible.length).toBeGreaterThan(0)
+      expect(items[0]!.start).toBeLessThanOrEqual(top)
+      expect(items.at(-1)!.end).toBeGreaterThanOrEqual(Math.min(top + 100, state.totalSize))
+    }
+  })
+
+  it('re-windows at once when the viewport or the sizes change', () => {
+    const v = make()
+    v.setScrollOffset(500)
+    v.setScrollOffset(510)
+    v.setViewportHeight(200)
+    expect(range(v)).toEqual([50, 51 + 20 + 1])
+    v.setOptions({ estimateSize: 20 })
+    expect(v.getVirtualItems()[0]!.start).toBe(v.getVirtualItems()[0]!.index * 20)
+  })
+})