@svgrid/grid 1.0.2 → 1.1.0

package/src/svgrid.context-menu.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Right-click context menu (Track A). Mounts a grid with `contextMenu`,
+ * fires a synthetic `contextmenu` event on a cell, and asserts the menu
+ * opens with the expected items and that actions/close work.
+ */
+import { describe, expect, it } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  createCoreRowModel,
+  createFilteredRowModel,
+  createSortedRowModel,
+  rowSelectionFeature,
+  rowSortingFeature,
+  sortFns,
+  tableFeatures,
+} from './index'
+import type { ColumnDef, SvGridApi } from './index'
+import type { ContextMenuItem } from './SvGrid.types'
+
+type Row = { id: number; name: string; team: string }
+const features = tableFeatures({ rowSortingFeature, rowSelectionFeature })
+const rows: Row[] = Array.from({ length: 6 }, (_, i) => ({
+  id: i + 1,
+  name: `Person ${i + 1}`,
+  team: ['A', 'B'][i % 2]!,
+}))
+const cols: ColumnDef<typeof features, Row>[] = [
+  { field: 'name', header: 'Name', width: 200, editorType: 'text' },
+  { field: 'team', header: 'Team', width: 160, editorType: 'text' },
+]
+const tick = () => new Promise<void>((r) => queueMicrotask(r))
+
+function mountGrid(contextMenu: unknown) {
+  return new Promise<{ api: SvGridApi<typeof features, Row>; target: HTMLElement; destroy: () => void }>(
+    (res, rej) => {
+      const target = document.createElement('div')
+      document.body.appendChild(target)
+      const app = mount(SvGrid, {
+        target,
+        props: {
+          data: rows,
+          columns: cols,
+          features,
+          _rowModels: {
+            coreRowModel: createCoreRowModel(),
+            filteredRowModel: createFilteredRowModel(),
+            sortedRowModel: createSortedRowModel(sortFns),
+          },
+          rowHeight: 32,
+          containerHeight: 400,
+          virtualization: false,
+          enableCellSelection: true,
+          contextMenu,
+          onApiReady(api: SvGridApi<typeof features, Row>) {
+            res({ api, target, destroy: () => { unmount(app); target.remove() } })
+          },
+        } as any,
+      })
+      queueMicrotask(() => { if (!target.querySelector('[role="grid"]')) rej(new Error('no grid')) })
+    },
+  )
+}
+
+function rightClickFirstCell(target: HTMLElement) {
+  const cell = target.querySelector('.sv-grid-cell[data-svgrid-row]') as HTMLElement
+  const r = cell.getBoundingClientRect()
+  cell.dispatchEvent(
+    new MouseEvent('contextmenu', { bubbles: true, cancelable: true, clientX: r.x + 4, clientY: r.y + 4 }),
+  )
+  return cell
+}
+
+describe('SvGrid context menu', () => {
+  it('opens the default menu on right-click with the built-in items', async () => {
+    const { target, destroy } = await mountGrid(true)
+    await tick()
+    rightClickFirstCell(target)
+    await tick()
+    const menu = target.querySelector('.sv-grid-context-menu')
+    expect(menu).not.toBeNull()
+    const labels = [...menu!.querySelectorAll('.sv-grid-menu-item')].map((b) => b.textContent?.trim())
+    expect(labels).toContain('Copy')
+    expect(labels).toContain('Paste')
+    expect(labels).toContain('Remove row')
+    expect(labels).toContain('Remove column')
+    destroy()
+  })
+
+  it('does not open when contextMenu is omitted (native menu shows)', async () => {
+    const { target, destroy } = await mountGrid(undefined)
+    await tick()
+    const cell = target.querySelector('.sv-grid-cell[data-svgrid-row]') as HTMLElement
+    const ev = new MouseEvent('contextmenu', { bubbles: true, cancelable: true })
+    cell.dispatchEvent(ev)
+    await tick()
+    expect(target.querySelector('.sv-grid-context-menu')).toBeNull()
+    expect(ev.defaultPrevented).toBe(false)
+    destroy()
+  })
+
+  it('renders only the configured custom items and runs the action', async () => {
+    let ran = 0
+    const items: ContextMenuItem<Row>[] = [
+      'copy',
+      'separator',
+      { key: 'flag', label: 'Flag row', action: () => { ran += 1 } },
+    ]
+    const { target, destroy } = await mountGrid(items)
+    await tick()
+    rightClickFirstCell(target)
+    await tick()
+    const labels = [...target.querySelectorAll('.sv-grid-context-menu .sv-grid-menu-item')].map((b) =>
+      b.textContent?.trim(),
+    )
+    expect(labels).toEqual(['Copy', 'Flag row'])
+    const flag = [...target.querySelectorAll('.sv-grid-context-menu .sv-grid-menu-item')].find(
+      (b) => b.textContent?.trim() === 'Flag row',
+    ) as HTMLElement
+    flag.click()
+    expect(ran).toBe(1)
+    await tick()
+    expect(target.querySelector('.sv-grid-context-menu')).toBeNull()
+    destroy()
+  })
+})

package/src/svgrid.interaction.test.ts

@@ -309,6 +309,36 @@ describe('SvGrid interactions - cell pointer events', () => {
       destroy()
     }
   })
+
+  // issue #23: a mouse drag extends the cell range, but a touch drag must NOT -
+  // it should leave the single tapped cell selected so the finger-drag scrolls.
+  async function dragSelectCount(pointerType: 'mouse' | 'touch'): Promise<number> {
+    const { target, destroy } = await mountInteractive()
+    try {
+      const a = target.querySelector('[data-svgrid-row="0"][data-svgrid-col="0"]') as HTMLElement | null
+      const c = target.querySelector('[data-svgrid-row="0"][data-svgrid-col="2"]') as HTMLElement | null
+      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 }))
+      await tick()
+      return target.querySelectorAll('[data-selected-range="true"]').length
+    } finally {
+      destroy()
+    }
+  }
+
+  it('mouse drag extends the selection across cells', async () => {
+    const n = await dragSelectCount('mouse')
+    if (n < 0) return
+    expect(n).toBeGreaterThan(1) // (0,0) -> (0,2) selects the row's 3 cells
+  })
+
+  it('touch drag does not start a range selection (issue #23)', async () => {
+    const n = await dragSelectCount('touch')
+    if (n < 0) return
+    expect(n).toBeLessThanOrEqual(1) // only the tapped cell; finger-drag scrolls
+  })
 })
 
 describe('SvGrid interactions - copy', () => {

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

@@ -16,8 +16,34 @@ import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { describe, expect, it } from 'vitest'
 
-const sourcePath = resolve(__dirname, './SvGrid.svelte')
-const source = readFileSync(sourcePath, 'utf-8')
+// The wrapper implementation spans SvGrid.svelte plus its extracted
+// sibling modules (types + pure helpers). Concatenate them so these
+// "the wrapper declares/exposes X" assertions hold wherever the code
+// physically lives.
+const source = [
+  './SvGrid.svelte',
+  './SvGrid.controller.svelte.ts',
+  './GridMenus.svelte',
+  './GridFooter.svelte',
+  './SvGrid.types.ts',
+  './SvGrid.helpers.ts',
+  './filter-operators.ts',
+  './facet-buckets.ts',
+  './cell-values.ts',
+  './clipboard.ts',
+  './build-api.ts',
+  './columns.ts',
+  './selection.ts',
+  './editing.ts',
+  './cell-render.ts',
+  './menus.ts',
+  './summaries.ts',
+  './keyboard-handlers.ts',
+  './scroll-sync.ts',
+  './features.ts',
+]
+  .map((p) => readFileSync(resolve(__dirname, p), 'utf-8'))
+  .join('\n')
 const typesPath = resolve(__dirname, './svgrid-wrapper.types.ts')
 const types = readFileSync(typesPath, 'utf-8')
 
@@ -143,7 +169,7 @@ describe('SvGrid wrapper - multi-cell paste + cut + delete', () => {
 
   it('wires Ctrl/Cmd+X to cutSelectionToClipboard', () => {
     expect(source).toMatch(/lower === "x"/)
-    expect(source).toMatch(/void cutSelectionToClipboard\(\)/)
+    expect(source).toMatch(/void (?:ctx\.)?cutSelectionToClipboard\(\)/)
     expect(source).toMatch(/async function cutSelectionToClipboard/)
     // Confirm both calls live inside the cutSelectionToClipboard body
     // (copy first, then clear). A comment between them is fine.
@@ -159,6 +185,41 @@ describe('SvGrid wrapper - multi-cell paste + cut + delete', () => {
 
   it('wires Delete + Backspace to clearSelectedCells (without clipboard interaction)', () => {
     expect(source).toMatch(/event\.key === "Delete" \|\| event\.key === "Backspace"/)
-    expect(source).toMatch(/if \(clearSelectedCells\(\)\)\s*\{/)
+    expect(source).toMatch(/if \((?:ctx\.)?clearSelectedCells\(\)\)\s*\{/)
+  })
+
+  // Regression: the controller's ctx is an object literal of getters, and the
+  // copy/cut/paste handlers in keyboard-handlers + menus reach the functions
+  // via `ctx.<name>()`. A refactor once shipped the `ctx.cutSelectionToClipboard`
+  // / `ctx.pasteFromClipboard` CALLS but dropped their getters, so those threw
+  // "is not a function" at runtime - copy worked, cut + paste were dead. Assert
+  // every clipboard function called through ctx has a matching getter.
+  it('exposes a ctx getter for every clipboard command it calls through ctx', () => {
+    for (const fn of [
+      'copySelectionToClipboard',
+      'cutSelectionToClipboard',
+      'pasteFromClipboard',
+      'onGridPaste',
+      'clearSelectedCells',
+    ]) {
+      expect(source).toMatch(new RegExp(`get ${fn}\\(\\)\\s*\\{\\s*return ${fn};?\\s*\\}`))
+    }
+  })
+
+  it('copy/cut fall back to execCommand when navigator.clipboard is absent (insecure context)', () => {
+    expect(source).toMatch(/function writeClipboardText\(/)
+    expect(source).toMatch(/document\.execCommand\("copy"\)/)
+  })
+
+  it('paste falls back to a native paste event when the async API is unavailable', () => {
+    // keydown only preventDefaults (and uses the async API) in a secure context;
+    // otherwise it lets the browser deliver a native paste event to onGridPaste.
+    // Accept either the positive branch or the inverted early-return guard
+    // (`if (!navigator.clipboard?.readText) return`) - both gate on the async API.
+    expect(source).toMatch(/if \(!?navigator\.clipboard\?\.readText\)/)
+    expect(source).toMatch(/function onGridPaste\(event: ClipboardEvent\)/)
+    expect(source).toMatch(/clipboardData\?\.getData\("text\/plain"\)/)
+    // The grid root wires the handler.
+    expect(source).toMatch(/onpaste=\{onGridPaste\}/)
   })
 })

package/src/svgrid.wrapper.test.ts

@@ -9,7 +9,33 @@ describe('SvGrid wrapper', () => {
   })
 
   it('contains full-wrapper controls and aria-activedescendant wiring', () => {
-    const source = readFileSync(resolve(__dirname, './SvGrid.svelte'), 'utf-8')
+    // The wrapper spans SvGrid.svelte plus its extracted sibling modules
+    // (types + pure helpers); read them together so these "contains X"
+    // assertions hold wherever the code physically lives.
+    const source = [
+      './SvGrid.svelte',
+      './SvGrid.controller.svelte.ts',
+      './GridMenus.svelte',
+      './GridFooter.svelte',
+      './SvGrid.types.ts',
+      './SvGrid.helpers.ts',
+      './filter-operators.ts',
+      './facet-buckets.ts',
+      './cell-values.ts',
+      './clipboard.ts',
+      './build-api.ts',
+      './columns.ts',
+      './selection.ts',
+      './editing.ts',
+      './cell-render.ts',
+      './menus.ts',
+      './summaries.ts',
+      './keyboard-handlers.ts',
+      './scroll-sync.ts',
+      './features.ts',
+    ]
+      .map((p) => readFileSync(resolve(__dirname, p), 'utf-8'))
+      .join('\n')
     expect(source).toContain('Filter all rows')
     expect(source).toContain('Previous')
     expect(source).toContain('role="status"')

package/src/test-setup.ts

@@ -1,10 +1,15 @@
 // Vitest setup. jsdom doesn't ship ResizeObserver, IntersectionObserver,
 // or the layout APIs SvGrid touches inside its mount effects. Provide
 // minimal no-op stubs so component mounting completes without crashing.
+//
+// These assign to globals/prototypes the jsdom env doesn't fully type, so
+// the targets are cast to `any`. We deliberately avoid expect-error
+// suppression directives: when a stub happens to line up with the lib types,
+// such a directive becomes "unused" and svelte-check fails the build (an
+// unused expect-error directive is itself an error).
 
 if (typeof globalThis.ResizeObserver === 'undefined') {
-  // @ts-expect-error - assigning to a globalThis property the env doesn't ship
-  globalThis.ResizeObserver = class {
+  ;(globalThis as any).ResizeObserver = class {
     observe() {}
     unobserve() {}
     disconnect() {}
@@ -12,8 +17,7 @@ if (typeof globalThis.ResizeObserver === 'undefined') {
 }
 
 if (typeof globalThis.IntersectionObserver === 'undefined') {
-  // @ts-expect-error - same
-  globalThis.IntersectionObserver = class {
+  ;(globalThis as any).IntersectionObserver = class {
     observe() {}
     unobserve() {}
     disconnect() {}
@@ -26,8 +30,7 @@ if (typeof globalThis.IntersectionObserver === 'undefined') {
 // jsdom's HTMLElement.scrollIntoView is a no-op; some grid code calls it
 // during the first effect. Make sure the method exists on every element.
 if (typeof Element !== 'undefined' && !Element.prototype.scrollIntoView) {
-  // @ts-expect-error - patching a missing DOM method
-  Element.prototype.scrollIntoView = function () {}
+  ;(Element.prototype as any).scrollIntoView = function () {}
 }
 
 // jsdom returns 0 for offset* and getBoundingClientRect; the grid only uses

package/src/virtualization/scroll-scaling.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest'
+import { createRowScrollScaling, resolveMaxDomHeight } from './scroll-scaling'
+
+const VIEWPORT = 600
+const FALLBACK = 8_000_000
+
+describe('createRowScrollScaling - inert (content fits under the cap)', () => {
+  // 1M rows * 18px = 18M, under a 33.5M (Chrome) cap -> no scaling.
+  const s = createRowScrollScaling(18_000_000, 33_554_400, VIEWPORT)
+
+  it('is inactive and exposes the true height as the DOM height', () => {
+    expect(s.active).toBe(false)
+    expect(s.domTotal).toBe(18_000_000)
+  })
+
+  it('both maps are the identity', () => {
+    for (const v of [0, 1, 1234, 9_000_000, 17_999_400]) {
+      expect(s.domToLogical(v)).toBe(v)
+      expect(s.logicalToDom(v)).toBe(v)
+    }
+  })
+})
+
+describe('createRowScrollScaling - active (content exceeds the cap)', () => {
+  // 1M rows * 32px = 32M, over Firefox's ~17.9M cap -> scaling engages.
+  const trueTotal = 32_000_000
+  const maxDom = 17_895_697
+  const s = createRowScrollScaling(trueTotal, maxDom, VIEWPORT)
+  const domMax = s.domTotal - VIEWPORT
+  const logicalMax = trueTotal - VIEWPORT
+
+  it('caps the DOM height at the browser limit', () => {
+    expect(s.active).toBe(true)
+    expect(s.domTotal).toBe(maxDom)
+    expect(s.domTotal).toBeLessThanOrEqual(maxDom)
+  })
+
+  it('maps the endpoints exactly so the first and last rows are reachable', () => {
+    expect(s.domToLogical(0)).toBe(0)
+    // The bottom of the DOM scroll range reaches the bottom of the logical range.
+    expect(s.domToLogical(domMax)).toBeCloseTo(logicalMax, 3)
+    expect(s.logicalToDom(0)).toBe(0)
+    expect(s.logicalToDom(logicalMax)).toBeCloseTo(domMax, 3)
+  })
+
+  it('clamps out-of-range inputs instead of overshooting', () => {
+    expect(s.domToLogical(-100)).toBe(0)
+    expect(s.domToLogical(domMax + 10_000)).toBeCloseTo(logicalMax, 3)
+    expect(s.logicalToDom(-100)).toBe(0)
+    expect(s.logicalToDom(logicalMax + 10_000)).toBeCloseTo(domMax, 3)
+  })
+
+  it('logicalToDom is the inverse of domToLogical across the range', () => {
+    for (let i = 0; i <= 10; i += 1) {
+      const domTop = (domMax * i) / 10
+      const roundTrip = s.logicalToDom(s.domToLogical(domTop))
+      expect(roundTrip).toBeCloseTo(domTop, 2)
+    }
+  })
+
+  it('both maps are monotonic non-decreasing', () => {
+    let prevL = -1
+    let prevD = -1
+    for (let i = 0; i <= 20; i += 1) {
+      const domTop = (domMax * i) / 20
+      const logical = s.domToLogical(domTop)
+      expect(logical).toBeGreaterThanOrEqual(prevL)
+      prevL = logical
+
+      const logIn = (logicalMax * i) / 20
+      const dom = s.logicalToDom(logIn)
+      expect(dom).toBeGreaterThanOrEqual(prevD)
+      prevD = dom
+    }
+  })
+})
+
+describe('resolveMaxDomHeight - picks the smaller, real scrollable cap', () => {
+  it('keeps the desktop cap when both signals agree', () => {
+    // Chrome ~33.5M; offsetHeight and scrollHeight match. 0.5% safety shave.
+    const cap = resolveMaxDomHeight(33_554_400, 33_554_400, FALLBACK)
+    expect(cap).toBeLessThan(33_554_400)
+    expect(cap).toBeGreaterThan(33_000_000)
+  })
+
+  it('uses the SCROLL cap when a phone over-reports offsetHeight', () => {
+    // High-DPR mobile: layout says 24M, but the container only scrolls ~6M.
+    // Trusting offsetHeight is exactly what stranded the last rows.
+    const cap = resolveMaxDomHeight(24_000_000, 6_000_000, FALLBACK)
+    expect(cap).toBeLessThanOrEqual(6_000_000)
+    expect(cap).toBeGreaterThan(5_900_000)
+  })
+
+  it('shaves a safety margin so the spacer never sits at the exact edge', () => {
+    const cap = resolveMaxDomHeight(10_000_000, 10_000_000, FALLBACK)
+    expect(cap).toBeLessThan(10_000_000)
+  })
+
+  it('falls back when both readings are junk (jsdom returns 0)', () => {
+    expect(resolveMaxDomHeight(0, 0, FALLBACK)).toBe(FALLBACK)
+  })
+
+  it('falls back when the browser did not clamp (returned ~1e9)', () => {
+    expect(resolveMaxDomHeight(1_000_000_000, 1_000_000_000, FALLBACK)).toBe(FALLBACK)
+  })
+
+  it('ignores a junk signal but trusts the valid one', () => {
+    // offsetHeight unclamped/garbage, scrollHeight is the real cap.
+    const cap = resolveMaxDomHeight(1_000_000_000, 5_000_000, FALLBACK)
+    expect(cap).toBeLessThanOrEqual(5_000_000)
+    expect(cap).toBeGreaterThan(4_900_000)
+  })
+
+  it('feeds straight into the scaler so the last row stays reachable', () => {
+    const maxDom = resolveMaxDomHeight(24_000_000, 6_000_000, FALLBACK)
+    const trueTotal = 500_000 * 32 // 16M px of rows, over the phone cap
+    const s = createRowScrollScaling(trueTotal, maxDom, VIEWPORT)
+    expect(s.active).toBe(true)
+    expect(s.domTotal).toBeLessThanOrEqual(maxDom)
+    const domMax = s.domTotal - VIEWPORT
+    expect(s.domToLogical(domMax)).toBeCloseTo(trueTotal - VIEWPORT, 0)
+  })
+})
+
+describe('createRowScrollScaling - edge cases', () => {
+  it('handles an empty grid without dividing by zero', () => {
+    const s = createRowScrollScaling(0, 17_895_697, VIEWPORT)
+    expect(s.active).toBe(false)
+    expect(s.domTotal).toBe(0)
+    expect(s.domToLogical(0)).toBe(0)
+    expect(s.logicalToDom(0)).toBe(0)
+  })
+
+  it('handles content shorter than the viewport', () => {
+    const s = createRowScrollScaling(200, 17_895_697, VIEWPORT)
+    expect(s.active).toBe(false)
+    expect(s.domToLogical(0)).toBe(0)
+  })
+
+  it('extreme scale (100M rows) keeps the last row reachable', () => {
+    const trueTotal = 100_000_000 * 32 // 3.2 billion px
+    const s = createRowScrollScaling(trueTotal, 33_554_400, VIEWPORT)
+    expect(s.active).toBe(true)
+    expect(s.domTotal).toBe(33_554_400)
+    const domMax = s.domTotal - VIEWPORT
+    expect(s.domToLogical(domMax)).toBeCloseTo(trueTotal - VIEWPORT, 0)
+  })
+})

package/src/virtualization/scroll-scaling.ts

@@ -0,0 +1,121 @@
+// Pure math for "huge list" vertical scroll scaling.
+//
+// Browsers cap how tall a single element may be (Chrome/Safari ~33.5M px,
+// Firefox ~17.9M, mobile/high-DPR lower). Once a virtualized grid's true
+// content height (count * rowHeight) exceeds that cap the scroll container
+// silently clamps its scrollHeight and the tail rows become unreachable - a
+// 1,000,000-row grid that only scrolls to ~994,000 on a phone.
+//
+// The fix (the technique react-virtualized calls "scaling"): size the DOM
+// scroll spacer to a capped height the browser CAN render, and map between the
+// limited DOM scroll range and the full logical range the virtualizer works
+// in. This module is the pure, side-effect-free core of that mapping so the
+// invariants can be unit-tested independently of the Svelte controller.
+//
+// When the true height fits under the cap, scaling is INERT: every mapping is
+// the identity and callers behave exactly as before.
+
+export type RowScrollScaling = {
+  /** True when the true content height exceeds the cap and mapping applies. */
+  readonly active: boolean
+  /** Height (px) the DOM scroll spacer should occupy - capped at maxDomHeight. */
+  readonly domTotal: number
+  /** Map a DOM scrollTop into the virtualizer's logical scroll offset. */
+  domToLogical(domTop: number): number
+  /** Map a virtualizer logical offset back into a DOM scrollTop. */
+  logicalToDom(logical: number): number
+}
+
+function clamp01(value: number): number {
+  if (value <= 0) return 0
+  if (value >= 1) return 1
+  return value
+}
+
+/** Below this a reading is junk (0 from jsdom, a sub-cap layout quirk, etc). */
+const MAX_DOM_HEIGHT_SANITY_FLOOR = 100_000
+/** At/above this the browser didn't clamp (returned ~the 1e9 we asked for). */
+const MAX_DOM_HEIGHT_SANITY_CEIL = 900_000_000
+/**
+ * Shave a hair off the detected cap so the spacer never sits at the exact
+ * physical edge, where sub-pixel rounding could leave the final row a touch
+ * out of reach. 0.5% is invisible at desktop caps (~33.5M -> ~33.3M) yet
+ * keeps a safety gap proportional to the cap.
+ */
+const MAX_DOM_HEIGHT_SAFETY = 0.995
+
+/**
+ * Resolve the usable max element height from the two raw DOM signals.
+ *
+ * `layoutCap` is a tall probe's clamped `offsetHeight` - the height layout
+ * assigns the element. `scrollCap` is the `scrollHeight` a real `overflow:auto`
+ * container exposes for that same probe - the height the user can actually
+ * scroll through. They differ on mobile / high-DPR engines, which report a
+ * generous `offsetHeight` but then expose a SMALLER scrollable range (the
+ * physical limit is in device px, so a 3x-DPR phone has ~1/3 the CSS-px scroll
+ * cap). Trusting `offsetHeight` alone is exactly what strands the last rows of
+ * a huge grid on a phone, so we take the smaller of the two.
+ *
+ * A junk reading (<= the sanity floor, or so large the browser clearly didn't
+ * clamp) is dropped; if neither signal survives, the caller's conservative
+ * `fallback` is returned unchanged.
+ */
+export function resolveMaxDomHeight(
+  layoutCap: number,
+  scrollCap: number,
+  fallback: number,
+): number {
+  const usable = [layoutCap, scrollCap].filter(
+    (v) =>
+      Number.isFinite(v) &&
+      v > MAX_DOM_HEIGHT_SANITY_FLOOR &&
+      v < MAX_DOM_HEIGHT_SANITY_CEIL,
+  )
+  if (usable.length === 0) return fallback
+  return Math.floor(Math.min(...usable) * MAX_DOM_HEIGHT_SAFETY)
+}
+
+/**
+ * Build the scaling mapping for one axis.
+ *
+ * @param trueTotal     The real content height in logical px (count * rowH, or
+ *                      the cumulative offset total for variable rows).
+ * @param maxDomHeight  The browser's max element height (detected at runtime).
+ * @param viewport      The scroll viewport height in px.
+ *
+ * Invariants (verified in scroll-scaling.test.ts):
+ *  - Inert when `trueTotal <= maxDomHeight`: both maps are the identity.
+ *  - `domTotal <= maxDomHeight` always, so the spacer never exceeds the cap.
+ *  - Endpoints line up: domTop 0 -> logical 0, and the DOM max
+ *    (`domTotal - viewport`) -> the logical max (`trueTotal - viewport`), so
+ *    the very last row is always reachable.
+ *  - `logicalToDom` is the inverse of `domToLogical` across the range.
+ *  - Both maps are monotonic non-decreasing and clamp out-of-range inputs.
+ */
+export function createRowScrollScaling(
+  trueTotal: number,
+  maxDomHeight: number,
+  viewport: number,
+): RowScrollScaling {
+  const safeMax = Math.max(maxDomHeight, 1)
+  const domTotal = Math.min(Math.max(trueTotal, 0), safeMax)
+  const active = trueTotal > safeMax
+  // Scrollable ranges (content minus one viewport). Guard against zero so the
+  // ratios below never divide by zero on tiny / empty grids.
+  const domRange = Math.max(domTotal - viewport, 1)
+  const logicalRange = Math.max(trueTotal - viewport, 0)
+
+  return {
+    active,
+    domTotal,
+    domToLogical(domTop: number): number {
+      if (!active) return domTop
+      return clamp01(domTop / domRange) * logicalRange
+    },
+    logicalToDom(logical: number): number {
+      if (!active) return logical
+      const lr = Math.max(logicalRange, 1)
+      return clamp01(logical / lr) * Math.max(domTotal - viewport, 0)
+    },
+  }
+}

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

@@ -19,6 +19,8 @@ export function createSvelteVirtualizer(options: VirtualizerOptions) {
     scrollToIndex: virtualizer.scrollToIndex,
     getVirtualItems: virtualizer.getVirtualItems,
     getTotalSize: virtualizer.getTotalSize,
+    getOffsetForIndex: virtualizer.getOffsetForIndex,
+    getSizeForIndex: virtualizer.getSizeForIndex,
     getState: virtualizer.getState,
   }
 }

package/src/virtualization/virtualizer.ts

@@ -259,6 +259,32 @@ export function createVirtualizer(initial: VirtualizerOptions) {
     getTotalSize() {
       return state.totalSize
     },
+    /** Cumulative offset of row `index` from the top in px, regardless
+     *  of whether `estimateSize` is uniform or per-index. Uses the
+     *  cached offsets array under function-form sizing so the lookup
+     *  is O(1) instead of O(index). */
+    getOffsetForIndex(index: number): number {
+      if (index <= 0) return 0
+      const count = Math.max(options.count, 0)
+      const bounded = Math.min(index, count)
+      if (typeof options.estimateSize === 'function') {
+        const offsets = getOffsets()
+        if (offsets) return offsets[bounded] ?? 0
+        let acc = 0
+        const fn = options.estimateSize
+        for (let i = 0; i < bounded; i += 1) acc += Math.max(fn(i), 1)
+        return acc
+      }
+      return bounded * Math.max(options.estimateSize, 1)
+    },
+    /** Height of row `index` in px (whichever estimateSize provides). */
+    getSizeForIndex(index: number): number {
+      if (index < 0 || index >= options.count) return 0
+      if (typeof options.estimateSize === 'function') {
+        return Math.max(options.estimateSize(index), 1)
+      }
+      return Math.max(options.estimateSize, 1)
+    },
     getState() {
       return state
     },