@svgrid/grid 2.6.6 → 2.6.8

package/src/virtual.test.ts

@@ -1,88 +1,88 @@
-/**
- * Tests for the fixed-row windowing helper and SvListBox `virtual` mode: a huge
- * option set renders only a small window (plus spacer rows), and itemTemplate
- * customizes the row.
- */
-import { describe, expect, it } from 'vitest'
-import { mount, unmount, flushSync, createRawSnippet } from 'svelte'
-import SvListBox from './SvListBox.svelte'
-import { virtualRange, scrollToIndex } from './virtual'
-
-describe('virtualRange', () => {
-  it('returns the visible window + spacer heights for a fixed-row list', () => {
-    const r = virtualRange({ scrollTop: 0, viewportHeight: 320, rowHeight: 32, count: 1000, overscan: 2 })
-    expect(r.start).toBe(0)
-    expect(r.totalHeight).toBe(32000)
-    expect(r.padTop).toBe(0)
-    // ~10 visible + 2 overscan.
-    expect(r.end).toBeLessThanOrEqual(14)
-    expect(r.padBottom).toBe((1000 - r.end) * 32)
-  })
-  it('scrolls the window when scrolled down', () => {
-    const r = virtualRange({ scrollTop: 3200, viewportHeight: 320, rowHeight: 32, count: 1000, overscan: 2 })
-    expect(r.start).toBe(98) // floor(3200/32)=100, minus overscan 2
-    expect(r.padTop).toBe(98 * 32)
-  })
-  it('handles empty + zero-height gracefully', () => {
-    expect(virtualRange({ scrollTop: 0, viewportHeight: 100, rowHeight: 32, count: 0 })).toMatchObject({ start: 0, end: 0, totalHeight: 0 })
-    expect(virtualRange({ scrollTop: 0, viewportHeight: 100, rowHeight: 0, count: 5 }).totalHeight).toBe(0)
-  })
-})
-
-describe('scrollToIndex', () => {
-  it('scrolls up to an item above and down to an item below the viewport', () => {
-    expect(scrollToIndex(2, 320, 320, 32)).toBe(64)          // item 2 above -> its top
-    expect(scrollToIndex(20, 0, 320, 32)).toBe(20 * 32 + 32 - 320) // item 20 below -> bottom-align
-    expect(scrollToIndex(5, 100, 320, 32)).toBe(100)         // already visible -> unchanged
-  })
-})
-
-describe('SvListBox virtual', () => {
-  it('renders only a small window of a huge list', () => {
-    const options = Array.from({ length: 5000 }, (_, i) => ({ value: i, label: `Item ${i}` }))
-    const target = document.createElement('div')
-    document.body.appendChild(target)
-    const app = mount(SvListBox, { target, props: { options, virtual: true } as any })
-    flushSync()
-    try {
-      const rendered = target.querySelectorAll('.sv-listbox__opt').length
-      expect(rendered).toBeGreaterThan(0)
-      expect(rendered).toBeLessThan(60) // nowhere near 5000
-      // Virtual mode is a JS-driven scroller: one clipped viewport holds the
-      // windowed rows (moved by `scrollOffset`, not native scroll) plus a custom
-      // scrollbar - so there is no native async-scroll gap to flash blank.
-      expect(target.querySelector('.sv-listbox__vp')).not.toBeNull()
-      expect(target.querySelector('.sv-listbox__sb')).not.toBeNull()
-    } finally { unmount(app); target.remove() }
-  })
-
-  it('windows a GROUPED list too (group headings render inside the window)', () => {
-    const roles = ['Eng', 'Design', 'Ops']
-    const options = Array.from({ length: 3000 }, (_, i) => ({ value: i, label: `User ${i}`, group: roles[i % 3] }))
-    const target = document.createElement('div')
-    document.body.appendChild(target)
-    const app = mount(SvListBox, { target, props: { options, virtual: true } as any })
-    flushSync()
-    try {
-      const rendered = target.querySelectorAll('.sv-listbox__opt').length
-      expect(rendered).toBeGreaterThan(0)
-      expect(rendered).toBeLessThan(60) // grouped list is windowed, not fully rendered
-      expect(target.querySelector('.sv-listbox__vp')).not.toBeNull()
-    } finally { unmount(app); target.remove() }
-  })
-
-  it('renders a custom itemTemplate per option', () => {
-    const options = [{ value: 'a', label: 'Apple' }, { value: 'b', label: 'Banana' }]
-    const itemTemplate = createRawSnippet((opt: () => { label: string }) => ({
-      render: () => `<span class="tpl">${opt().label.toUpperCase()}</span>`,
-    }))
-    const target = document.createElement('div')
-    document.body.appendChild(target)
-    const app = mount(SvListBox, { target, props: { options, itemTemplate } as any })
-    flushSync()
-    try {
-      const tpls = [...target.querySelectorAll('.tpl')].map((n) => n.textContent)
-      expect(tpls).toEqual(['APPLE', 'BANANA'])
-    } finally { unmount(app); target.remove() }
-  })
-})
+/**
+ * Tests for the fixed-row windowing helper and SvListBox `virtual` mode: a huge
+ * option set renders only a small window (plus spacer rows), and itemTemplate
+ * customizes the row.
+ */
+import { describe, expect, it } from 'vitest'
+import { mount, unmount, flushSync, createRawSnippet } from 'svelte'
+import SvListBox from './SvListBox.svelte'
+import { virtualRange, scrollToIndex } from './virtual'
+
+describe('virtualRange', () => {
+  it('returns the visible window + spacer heights for a fixed-row list', () => {
+    const r = virtualRange({ scrollTop: 0, viewportHeight: 320, rowHeight: 32, count: 1000, overscan: 2 })
+    expect(r.start).toBe(0)
+    expect(r.totalHeight).toBe(32000)
+    expect(r.padTop).toBe(0)
+    // ~10 visible + 2 overscan.
+    expect(r.end).toBeLessThanOrEqual(14)
+    expect(r.padBottom).toBe((1000 - r.end) * 32)
+  })
+  it('scrolls the window when scrolled down', () => {
+    const r = virtualRange({ scrollTop: 3200, viewportHeight: 320, rowHeight: 32, count: 1000, overscan: 2 })
+    expect(r.start).toBe(98) // floor(3200/32)=100, minus overscan 2
+    expect(r.padTop).toBe(98 * 32)
+  })
+  it('handles empty + zero-height gracefully', () => {
+    expect(virtualRange({ scrollTop: 0, viewportHeight: 100, rowHeight: 32, count: 0 })).toMatchObject({ start: 0, end: 0, totalHeight: 0 })
+    expect(virtualRange({ scrollTop: 0, viewportHeight: 100, rowHeight: 0, count: 5 }).totalHeight).toBe(0)
+  })
+})
+
+describe('scrollToIndex', () => {
+  it('scrolls up to an item above and down to an item below the viewport', () => {
+    expect(scrollToIndex(2, 320, 320, 32)).toBe(64)          // item 2 above -> its top
+    expect(scrollToIndex(20, 0, 320, 32)).toBe(20 * 32 + 32 - 320) // item 20 below -> bottom-align
+    expect(scrollToIndex(5, 100, 320, 32)).toBe(100)         // already visible -> unchanged
+  })
+})
+
+describe('SvListBox virtual', () => {
+  it('renders only a small window of a huge list', () => {
+    const options = Array.from({ length: 5000 }, (_, i) => ({ value: i, label: `Item ${i}` }))
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const app = mount(SvListBox, { target, props: { options, virtual: true } as any })
+    flushSync()
+    try {
+      const rendered = target.querySelectorAll('.sv-listbox__opt').length
+      expect(rendered).toBeGreaterThan(0)
+      expect(rendered).toBeLessThan(60) // nowhere near 5000
+      // Virtual mode is a JS-driven scroller: one clipped viewport holds the
+      // windowed rows (moved by `scrollOffset`, not native scroll) plus a custom
+      // scrollbar - so there is no native async-scroll gap to flash blank.
+      expect(target.querySelector('.sv-listbox__vp')).not.toBeNull()
+      expect(target.querySelector('.sv-listbox__sb')).not.toBeNull()
+    } finally { unmount(app); target.remove() }
+  })
+
+  it('windows a GROUPED list too (group headings render inside the window)', () => {
+    const roles = ['Eng', 'Design', 'Ops']
+    const options = Array.from({ length: 3000 }, (_, i) => ({ value: i, label: `User ${i}`, group: roles[i % 3] }))
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const app = mount(SvListBox, { target, props: { options, virtual: true } as any })
+    flushSync()
+    try {
+      const rendered = target.querySelectorAll('.sv-listbox__opt').length
+      expect(rendered).toBeGreaterThan(0)
+      expect(rendered).toBeLessThan(60) // grouped list is windowed, not fully rendered
+      expect(target.querySelector('.sv-listbox__vp')).not.toBeNull()
+    } finally { unmount(app); target.remove() }
+  })
+
+  it('renders a custom itemTemplate per option', () => {
+    const options = [{ value: 'a', label: 'Apple' }, { value: 'b', label: 'Banana' }]
+    const itemTemplate = createRawSnippet((opt: () => { label: string }) => ({
+      render: () => `<span class="tpl">${opt().label.toUpperCase()}</span>`,
+    }))
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const app = mount(SvListBox, { target, props: { options, itemTemplate } as any })
+    flushSync()
+    try {
+      const tpls = [...target.querySelectorAll('.tpl')].map((n) => n.textContent)
+      expect(tpls).toEqual(['APPLE', 'BANANA'])
+    } finally { unmount(app); target.remove() }
+  })
+})

package/src/virtualization/column-virtualizer.test.ts

@@ -1,27 +1,27 @@
-import { describe, expect, it } from 'vitest'
-import { createColumnVirtualizer } from './column-virtualizer'
-
-describe('column virtualizer', () => {
-  it('computes horizontal window', () => {
-    const v = createColumnVirtualizer({
-      count: 1000,
-      viewportWidth: 700,
-      overscan: 3,
-      estimateSize: () => 140,
-    })
-    const items = v.getVirtualItems()
-    expect(items[0]?.index).toBe(0)
-    expect(items.length).toBeGreaterThan(0)
-  })
-
-  it('updates indices on horizontal scroll', () => {
-    const v = createColumnVirtualizer({
-      count: 1000,
-      viewportWidth: 700,
-      estimateSize: () => 140,
-    })
-    v.setHorizontalOffset(2800)
-    const state = v.getState()
-    expect(state.startIndex).toBeGreaterThan(0)
-  })
-})
+import { describe, expect, it } from 'vitest'
+import { createColumnVirtualizer } from './column-virtualizer'
+
+describe('column virtualizer', () => {
+  it('computes horizontal window', () => {
+    const v = createColumnVirtualizer({
+      count: 1000,
+      viewportWidth: 700,
+      overscan: 3,
+      estimateSize: () => 140,
+    })
+    const items = v.getVirtualItems()
+    expect(items[0]?.index).toBe(0)
+    expect(items.length).toBeGreaterThan(0)
+  })
+
+  it('updates indices on horizontal scroll', () => {
+    const v = createColumnVirtualizer({
+      count: 1000,
+      viewportWidth: 700,
+      estimateSize: () => 140,
+    })
+    v.setHorizontalOffset(2800)
+    const state = v.getState()
+    expect(state.startIndex).toBeGreaterThan(0)
+  })
+})

package/src/virtualization/column-virtualizer.ts

@@ -1,30 +1,30 @@
-import { createVirtualizer } from './virtualizer'
-
-export type ColumnSizeEstimator = (index: number) => number
-
-export function createColumnVirtualizer(input: {
-  count: number
-  viewportWidth: number
-  scrollOffset?: number
-  overscan?: number
-  /** Either a uniform size (number) or a per-column size function. */
-  estimateSize?: number | ColumnSizeEstimator
-}) {
-  const virtualizer = createVirtualizer({
-    count: input.count,
-    estimateSize: input.estimateSize ?? 140,
-    viewportHeight: input.viewportWidth,
-    scrollOffset: input.scrollOffset ?? 0,
-    overscan: input.overscan ?? 4,
-  })
-
-  return {
-    ...virtualizer,
-    setViewportWidth(viewportWidth: number) {
-      virtualizer.setViewportHeight(viewportWidth)
-    },
-    setHorizontalOffset(scrollOffset: number) {
-      virtualizer.setScrollOffset(scrollOffset)
-    },
-  }
-}
+import { createVirtualizer } from './virtualizer'
+
+export type ColumnSizeEstimator = (index: number) => number
+
+export function createColumnVirtualizer(input: {
+  count: number
+  viewportWidth: number
+  scrollOffset?: number
+  overscan?: number
+  /** Either a uniform size (number) or a per-column size function. */
+  estimateSize?: number | ColumnSizeEstimator
+}) {
+  const virtualizer = createVirtualizer({
+    count: input.count,
+    estimateSize: input.estimateSize ?? 140,
+    viewportHeight: input.viewportWidth,
+    scrollOffset: input.scrollOffset ?? 0,
+    overscan: input.overscan ?? 4,
+  })
+
+  return {
+    ...virtualizer,
+    setViewportWidth(viewportWidth: number) {
+      virtualizer.setViewportHeight(viewportWidth)
+    },
+    setHorizontalOffset(scrollOffset: number) {
+      virtualizer.setScrollOffset(scrollOffset)
+    },
+  }
+}

package/src/virtualization/pre-measure.test.ts

@@ -0,0 +1,65 @@
+/**
+ * The pre-measurement window (`buildPreMeasureItems`).
+ *
+ * Both virtualizers learn their real `count` from an `$effect`, and effects do
+ * not run during SSR. Before this existed the server therefore rendered an
+ * empty `<tbody>`: the rows were in the row model, but the virtualizer still
+ * thought there were none, so `<SvGrid>` shipped an empty shell to crawlers and
+ * to no-JS clients while the docs claimed the markup arrived "already filled
+ * with data".
+ *
+ * Nothing tested SSR, which is why that survived. These lock the window's
+ * shape; `svgrid.ssr.test.ts` asserts the rendered HTML end to end.
+ */
+import { describe, expect, it } from 'vitest'
+import { buildPreMeasureItems } from './virtualizer'
+
+describe('buildPreMeasureItems', () => {
+  it('returns a window even with no viewport measurement', () => {
+    // viewportHeight 0 is what a server reports - the old behaviour was [].
+    const items = buildPreMeasureItems(100, 30, 0, 8)
+    expect(items.length).toBeGreaterThan(0)
+    expect(items[0]!.index).toBe(0)
+  })
+
+  it('covers the viewport plus overscan, not the whole dataset', () => {
+    // 400px / 40px = 10 visible, + 5 overscan = through index 15 => 16 items.
+    const items = buildPreMeasureItems(1000, 40, 400, 5)
+    expect(items).toHaveLength(16)
+    expect(items[items.length - 1]!.index).toBe(15)
+  })
+
+  it('never runs past the end of a short dataset', () => {
+    const items = buildPreMeasureItems(3, 30, 5000, 8)
+    expect(items).toHaveLength(3)
+    expect(items[2]!.index).toBe(2)
+  })
+
+  it('is empty for an empty dataset', () => {
+    expect(buildPreMeasureItems(0, 30, 500, 8)).toEqual([])
+  })
+
+  it('is deterministic - the server and first client render must agree', () => {
+    // Anchored at index 0 with no scroll offset, so both sides produce the
+    // same markup and hydration does not mismatch.
+    const a = buildPreMeasureItems(500, 30, 520, 8)
+    const b = buildPreMeasureItems(500, 30, 520, 8)
+    expect(a).toEqual(b)
+    expect(a[0]!.start).toBe(0)
+  })
+
+  it('lays items out contiguously so the spacers add up', () => {
+    const items = buildPreMeasureItems(10, 25, 100, 2)
+    for (let i = 0; i < items.length; i += 1) {
+      expect(items[i]!.start).toBe(i * 25)
+      expect(items[i]!.end).toBe(i * 25 + 25)
+      expect(items[i]!.size).toBe(25)
+    }
+  })
+
+  it('tolerates a zero or negative size rather than dividing by zero', () => {
+    const items = buildPreMeasureItems(5, 0, 100, 1)
+    expect(items.length).toBeGreaterThan(0)
+    expect(Number.isFinite(items[0]!.end)).toBe(true)
+  })
+})

package/src/virtualization/svelte-virtualizer.svelte.ts

@@ -1,26 +1,26 @@
-import { createVirtualizer } from './virtualizer'
-import type { VirtualizerOptions } from './types'
-
-export function createSvelteVirtualizer(options: VirtualizerOptions) {
-  const virtualizer = createVirtualizer(options)
-  let version = $state(0)
-
-  virtualizer.subscribe(() => {
-    version += 1
-  })
-
-  return {
-    get version() {
-      return version
-    },
-    setOptions: virtualizer.setOptions,
-    setScrollOffset: virtualizer.setScrollOffset,
-    setViewportHeight: virtualizer.setViewportHeight,
-    scrollToIndex: virtualizer.scrollToIndex,
-    getVirtualItems: virtualizer.getVirtualItems,
-    getTotalSize: virtualizer.getTotalSize,
-    getOffsetForIndex: virtualizer.getOffsetForIndex,
-    getSizeForIndex: virtualizer.getSizeForIndex,
-    getState: virtualizer.getState,
-  }
-}
+import { createVirtualizer } from './virtualizer'
+import type { VirtualizerOptions } from './types'
+
+export function createSvelteVirtualizer(options: VirtualizerOptions) {
+  const virtualizer = createVirtualizer(options)
+  let version = $state(0)
+
+  virtualizer.subscribe(() => {
+    version += 1
+  })
+
+  return {
+    get version() {
+      return version
+    },
+    setOptions: virtualizer.setOptions,
+    setScrollOffset: virtualizer.setScrollOffset,
+    setViewportHeight: virtualizer.setViewportHeight,
+    scrollToIndex: virtualizer.scrollToIndex,
+    getVirtualItems: virtualizer.getVirtualItems,
+    getTotalSize: virtualizer.getTotalSize,
+    getOffsetForIndex: virtualizer.getOffsetForIndex,
+    getSizeForIndex: virtualizer.getSizeForIndex,
+    getState: virtualizer.getState,
+  }
+}

package/src/virtualization/types.ts

@@ -1,30 +1,30 @@
-export type VirtualItem = {
-  index: number
-  start: number
-  size: number
-  end: number
-  key: string
-}
-
-export type VirtualizerOptions = {
-  count: number
-  /**
-   * Per-item size. Pass a number for a uniform layout (fast path) or a
-   * function for variable sizing - the virtualizer will build cumulative
-   * offsets and use binary lookup to find the visible window. The function
-   * receives the item index and must return its pixel size.
-   */
-  estimateSize: number | ((index: number) => number)
-  overscan?: number
-  viewportHeight: number
-  scrollOffset?: number
-}
-
-export type VirtualizerState = {
-  items: Array<VirtualItem>
-  totalSize: number
-  startIndex: number
-  endIndex: number
-  scrollOffset: number
-  viewportHeight: number
-}
+export type VirtualItem = {
+  index: number
+  start: number
+  size: number
+  end: number
+  key: string
+}
+
+export type VirtualizerOptions = {
+  count: number
+  /**
+   * Per-item size. Pass a number for a uniform layout (fast path) or a
+   * function for variable sizing - the virtualizer will build cumulative
+   * offsets and use binary lookup to find the visible window. The function
+   * receives the item index and must return its pixel size.
+   */
+  estimateSize: number | ((index: number) => number)
+  overscan?: number
+  viewportHeight: number
+  scrollOffset?: number
+}
+
+export type VirtualizerState = {
+  items: Array<VirtualItem>
+  totalSize: number
+  startIndex: number
+  endIndex: number
+  scrollOffset: number
+  viewportHeight: number
+}

package/src/virtualization/virtualizer.test.ts

@@ -1,47 +1,47 @@
-import { describe, expect, it } from 'vitest'
-import { createVirtualizer } from './virtualizer'
-
-describe('virtualizer', () => {
-  it('computes bounded virtual range with overscan', () => {
-    const v = createVirtualizer({
-      count: 100_000,
-      estimateSize: 36,
-      overscan: 8,
-      viewportHeight: 360,
-      scrollOffset: 0,
-    })
-
-    const items = v.getVirtualItems()
-    expect(items.length).toBeGreaterThan(0)
-    expect(items[0]?.index).toBe(0)
-    expect(items[items.length - 1]?.index).toBe(18)
-  })
-
-  it('updates range when scroll offset changes', () => {
-    const v = createVirtualizer({
-      count: 100_000,
-      estimateSize: 40,
-      overscan: 5,
-      viewportHeight: 400,
-      scrollOffset: 0,
-    })
-
-    v.setScrollOffset(4_000)
-    const state = v.getState()
-    expect(state.startIndex).toBeLessThanOrEqual(100)
-    expect(state.endIndex).toBeGreaterThanOrEqual(110)
-  })
-
-  it('scrollToIndex clamps target offset', () => {
-    const v = createVirtualizer({
-      count: 100,
-      estimateSize: 30,
-      overscan: 2,
-      viewportHeight: 300,
-      scrollOffset: 0,
-    })
-
-    v.scrollToIndex(9_999)
-    expect(v.getState().scrollOffset).toBe(2_700)
-  })
-})
+import { describe, expect, it } from 'vitest'
+import { createVirtualizer } from './virtualizer'
+
+describe('virtualizer', () => {
+  it('computes bounded virtual range with overscan', () => {
+    const v = createVirtualizer({
+      count: 100_000,
+      estimateSize: 36,
+      overscan: 8,
+      viewportHeight: 360,
+      scrollOffset: 0,
+    })
+
+    const items = v.getVirtualItems()
+    expect(items.length).toBeGreaterThan(0)
+    expect(items[0]?.index).toBe(0)
+    expect(items[items.length - 1]?.index).toBe(18)
+  })
+
+  it('updates range when scroll offset changes', () => {
+    const v = createVirtualizer({
+      count: 100_000,
+      estimateSize: 40,
+      overscan: 5,
+      viewportHeight: 400,
+      scrollOffset: 0,
+    })
+
+    v.setScrollOffset(4_000)
+    const state = v.getState()
+    expect(state.startIndex).toBeLessThanOrEqual(100)
+    expect(state.endIndex).toBeGreaterThanOrEqual(110)
+  })
+
+  it('scrollToIndex clamps target offset', () => {
+    const v = createVirtualizer({
+      count: 100,
+      estimateSize: 30,
+      overscan: 2,
+      viewportHeight: 300,
+      scrollOffset: 0,
+    })
+
+    v.scrollToIndex(9_999)
+    expect(v.getState().scrollOffset).toBe(2_700)
+  })
+})