@svgrid/grid 3.0.0 → 3.0.2

package/src/icon-overrides.grid.test.ts

@@ -0,0 +1,188 @@
+/**
+ * DOM: the `icons` prop replaces the grid's own glyphs, one name at a time.
+ *
+ * The contract these lock in:
+ *   - per-name fallback. Overriding one icon must not blank the others; that
+ *     cliff is the whole reason `icons` is a map and not a single snippet.
+ *   - an override reaches the lazily-imported column menu, not just the parts
+ *     of the grid that render eagerly.
+ *   - overriding a filter operator does NOT repaint the pin menu, which shared
+ *     its glyphs before this feature.
+ *   - defaults are untouched when `icons` is absent.
+ *
+ * jsdom does not compute `transform`, so the rotation contract is asserted as
+ * the class hook the CSS keys off (`.sv-grid-icon` on the wrapper, as a direct
+ * child of the toggle) rather than as a computed style. The rotation itself is
+ * browser-only verification.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { createRawSnippet, flushSync, mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  createCoreRowModel,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  sortFns,
+  tableFeatures,
+  rowSortingFeature,
+} from './index'
+import type { ColumnDef } from './index'
+
+type Row = { id: number; name: string }
+const features = tableFeatures({ rowSortingFeature })
+const cols: ColumnDef<typeof features, Row>[] = [{ field: 'name', header: 'Name', width: 160 }]
+const data: Row[] = Array.from({ length: 12 }, (_, i) => ({ id: i, name: `n${i}` }))
+
+const tick = () => new Promise<void>((r) => queueMicrotask(r))
+
+/** A marker icon that is trivially findable in the DOM. */
+const mark = (id: string) =>
+  createRawSnippet(() => ({
+    render: () => `<svg data-icon="${id}"><path d="M0 0" /></svg>`,
+  }))
+
+function mountGrid(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvGrid, {
+    target,
+    props: {
+      data,
+      columns: cols,
+      features,
+      _rowModels: {
+        coreRowModel: createCoreRowModel(),
+        filteredRowModel: createFilteredRowModel(),
+        sortedRowModel: createSortedRowModel(sortFns),
+        paginatedRowModel: createPaginatedRowModel(),
+      },
+      containerHeight: 240,
+      virtualization: false,
+      ...props,
+    } as never,
+  })
+  return { target, app, destroy: () => { unmount(app); target.remove() } }
+}
+
+let cleanup: (() => void) | null = null
+afterEach(() => { cleanup?.(); cleanup = null })
+
+describe('icons prop', () => {
+  it('renders the built-in glyphs when no icons are passed', async () => {
+    const { target, destroy } = mountGrid({ showColumnMenu: true })
+    cleanup = destroy
+    await tick()
+    // The header menu button draws a real <svg> from the built-in catalogue.
+    const menuBtn = target.querySelector('.sv-grid-col-menu-btn')
+    expect(menuBtn).not.toBeNull()
+    expect(menuBtn!.querySelector('svg.sv-grid-icon')).not.toBeNull()
+    expect(target.querySelector('[data-icon]')).toBeNull()
+  })
+
+  it('replaces one icon and leaves the rest alone', async () => {
+    const { target, destroy } = mountGrid({
+      showColumnMenu: true,
+      showFilterRow: true,
+      icons: { menu: mark('m') },
+    })
+    cleanup = destroy
+    await tick()
+
+    const menuBtn = target.querySelector('.sv-grid-col-menu-btn')!
+    // The override is there...
+    expect(menuBtn.querySelector('[data-icon="m"]')).not.toBeNull()
+    // ...and the built-in it replaced is not drawn alongside it.
+    expect(menuBtn.querySelector('svg.sv-grid-icon')).toBeNull()
+    // An unset name still renders its built-in. This is the assertion that a
+    // single catch-all snippet could not satisfy.
+    expect(target.querySelectorAll('svg.sv-grid-icon').length).toBeGreaterThan(0)
+  })
+
+  it('wraps an override in the icon box the CSS keys off', async () => {
+    const { target, destroy } = mountGrid({ showColumnMenu: true, icons: { menu: mark('m') } })
+    cleanup = destroy
+    await tick()
+    const wrapper = target.querySelector('[data-icon="m"]')!.parentElement!
+    expect(wrapper.classList.contains('sv-grid-icon')).toBe(true)
+    expect(wrapper.classList.contains('sv-grid-icon-custom')).toBe(true)
+  })
+
+  it('reaches the lazily-imported column menu', async () => {
+    const { target, destroy } = mountGrid({
+      showColumnMenu: true,
+      icons: { 'sort-asc': mark('sa') },
+    })
+    cleanup = destroy
+    await tick()
+    ;(target.querySelector('.sv-grid-col-menu-btn') as HTMLElement).click()
+    // GridMenus arrives through a dynamic import(), so poll rather than
+    // guessing a tick count.
+    await vi.waitFor(() => {
+      expect(target.querySelector('[data-icon="sa"]')).not.toBeNull()
+    })
+  })
+
+  it('does not repaint the pin menu when a filter operator is overridden', async () => {
+    const { target, destroy } = mountGrid({
+      showColumnMenu: true,
+      // The pin section is hidden while columns are virtualized, and that
+      // defaults to on. This is COLUMN virtualization, not the row
+      // `virtualization: false` the shared helper sets.
+      columnVirtualization: false,
+      icons: { 'op-startsWith': mark('sw') },
+    })
+    cleanup = destroy
+    await tick()
+    ;(target.querySelector('.sv-grid-col-menu-btn') as HTMLElement).click()
+
+    // Assert the item is really there before asserting about its icon -
+    // a conditional check here would pass just as happily if the pin menu
+    // stopped rendering at all.
+    const pinLeft = await vi.waitFor(() => {
+      const el = [...target.querySelectorAll('.sv-grid-menu-item')].find((e) =>
+        e.textContent?.includes('Pin to left'),
+      )
+      expect(el).toBeTruthy()
+      return el!
+    })
+
+    // Pin borrowed `op-startsWith` before this feature; it must not follow
+    // that override now.
+    expect(pinLeft.querySelector('[data-icon="sw"]')).toBeNull()
+    expect(pinLeft.querySelector('svg.sv-grid-icon')).not.toBeNull()
+  })
+
+  it('overrides the pager arrows through GridFooter', async () => {
+    const { target, destroy } = mountGrid({
+      showPagination: true,
+      pageSize: 5,
+      icons: { 'page-next': mark('pn') },
+    })
+    cleanup = destroy
+    await tick()
+    const hit = target.querySelector('[data-icon="pn"]')
+    expect(hit).not.toBeNull()
+    // Still a real pager button, and its label is untouched: icons and
+    // localeText are independent axes.
+    const btn = hit!.closest('.sv-grid-pagination-btn')
+    expect(btn).not.toBeNull()
+    expect(btn!.getAttribute('aria-label')).toBe('Next page')
+  })
+
+  it('picks up icons set after mount through api.setOption', async () => {
+    let api: { setOption: (k: string, v: unknown) => void } | undefined
+    const { target, destroy } = mountGrid({
+      showColumnMenu: true,
+      onApiReady: (a: typeof api) => (api = a),
+    })
+    cleanup = destroy
+    await tick()
+    expect(target.querySelector('[data-icon="rt"]')).toBeNull()
+
+    api!.setOption('icons', { menu: mark('rt') })
+    flushSync()
+    await tick()
+    expect(target.querySelector('[data-icon="rt"]')).not.toBeNull()
+  })
+})

package/src/icon-seam.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Source scan: every chrome icon goes through the `icon` snippet.
+ *
+ * The `icons` prop is only worth having if it covers the chrome, and coverage
+ * is the kind of thing that rots one commit at a time - somebody adds a toolbar
+ * button with an inline `<svg>`, it works, nobody notices it ignores `icons`
+ * until a consumer reports a stray glyph in a re-skinned grid. This is the
+ * check that turns that into a red test instead.
+ *
+ * It reads source rather than DOM on purpose: a rendering test can only cover
+ * the states it happens to mount, and the icons most likely to be missed are
+ * the ones behind a rarely-exercised branch.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { GRID_ICON_GLYPHS, GRID_ICON_NAMES, type GridIconName } from './grid-icons'
+
+const SRC = join(process.cwd(), 'src')
+const read = (f: string) => readFileSync(join(SRC, f), 'utf8')
+
+/** Files that render grid chrome and therefore must go through the seam. */
+const CHROME = ['SvGrid.svelte', 'GridMenus.svelte', 'GridFooter.svelte', 'SvRowGroupPanel.svelte']
+
+/**
+ * Drop the regions allowed to contain raw icon markup: the `icon` snippet's own
+ * body (which IS the built-in set), the `ic` snippet in SvRowGroupPanel, and
+ * every `<script>` block.
+ */
+function stripAllowedRegions(src: string): string {
+  let out = src.replace(/<script[\s\S]*?<\/script>/g, '')
+  // The built-in catalogue: from the snippet header to its closing tag.
+  out = out.replace(/\{#snippet icon\(name: GridIconName\)\}[\s\S]*?\n\{\/snippet\}/g, '')
+  out = out.replace(/\{#snippet ic\(name: GridIconName\)\}[\s\S]*?\{\/snippet\}/g, '')
+  return out
+}
+
+describe('icon seam', () => {
+  it('leaves no inline <svg> outside the built-in catalogue', () => {
+    // Data visualisation is not chrome: these draw values, not affordances, and
+    // there is nothing for a consumer's icon set to say about them.
+    const ALLOWED = ['sv-grid-sparkline']
+
+    const offenders: string[] = []
+    for (const file of CHROME) {
+      const body = stripAllowedRegions(read(file))
+      for (const [i, line] of body.split('\n').entries()) {
+        if (!line.includes('<svg')) continue
+        if (ALLOWED.some((a) => body.split('\n').slice(i, i + 3).join(' ').includes(a))) continue
+        offenders.push(`${file}:${i + 1} ${line.trim().slice(0, 80)}`)
+      }
+    }
+    expect(
+      offenders,
+      `Inline <svg> outside the icon snippet - route it through {@render icon("...")} ` +
+        `and add a name to grid-icons.ts:\n  ${offenders.join('\n  ')}`,
+    ).toEqual([])
+  })
+
+  it('leaves no glyph character used as an icon', () => {
+    // Every character the catalogue owns. If one of these appears as an
+    // element's text content outside the snippet, it is an icon that bypassed
+    // the seam.
+    const glyphs = [...new Set(Object.values(GRID_ICON_GLYPHS))].filter((g) => g !== '#')
+    const offenders: string[] = []
+    for (const file of CHROME) {
+      const body = stripAllowedRegions(read(file))
+      for (const [i, line] of body.split('\n').entries()) {
+        for (const g of glyphs) {
+          // `>GLYPH<` is the shape of a glyph rendered as element content.
+          if (new RegExp(`>\\s*${escapeRe(g)}\\s*<`).test(line)) {
+            offenders.push(`${file}:${i + 1} ${JSON.stringify(g)} in ${line.trim().slice(0, 70)}`)
+          }
+        }
+      }
+    }
+    expect(
+      offenders,
+      `Glyph rendered directly instead of through the icon seam:\n  ${offenders.join('\n  ')}`,
+    ).toEqual([])
+  })
+
+  it('only renders names the catalogue defines', () => {
+    const unknown: string[] = []
+    for (const file of CHROME) {
+      const src = read(file)
+      for (const m of src.matchAll(/\{@render ic(?:on)?\(\s*["']([a-zA-Z-]+)["']\s*\)\}/g)) {
+        const name = m[1] as GridIconName
+        if (!GRID_ICON_NAMES.includes(name)) unknown.push(`${file}: ${name}`)
+      }
+    }
+    expect(unknown, `Icon names with no entry in grid-icons.ts:\n  ${unknown.join('\n  ')}`).toEqual(
+      [],
+    )
+  })
+})
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/src/index.ts

@@ -536,6 +536,12 @@ export {
   buildChart,
   formatChartValue,
   rowsToChartSpec,
+  rowsToBoxSpec,
+  rowsToDirectSpec,
+  boxStats,
+  sliceChartWindow,
+  chartScales,
+  ordinalDateTicks,
   niceScale,
   niceLogScale,
   linearTrend,
@@ -550,7 +556,13 @@ export {
   type ChartSpec,
   type ChartSeries,
   type ChartGeometry,
+  type ChartScales,
   type ChartBar,
+  type ChartCandle,
+  type ChartBox,
+  type ChartErrorBar,
+  type BoxStats,
+  type OhlcBar,
   type ChartLine,
   type ChartLinePoint,
   type ChartPieSlice,
@@ -581,6 +593,7 @@ export {
   downloadChartSvg,
   chartToPngBlob,
   downloadChartPng,
+  chartCsvExportable,
   chartSpecToCsv,
   downloadChartCsv,
   type ChartExportOptions,
@@ -693,6 +706,12 @@ export {
   resolveGridMessages,
   type GridMessages,
 } from './grid-messages'
+export {
+  GRID_ICON_GLYPHS,
+  GRID_ICON_NAMES,
+  type GridIconName,
+  type GridIcons,
+} from './grid-icons'
 export {
   insertGroupFooters,
   buildAutoGroupColumns,

package/src/js-scroller.svelte.ts

@@ -1,173 +1,173 @@
-/**
- * createJsScroller - a JS-driven vertical scroller for the virtualized selection
- * controls (SvListBox / SvDropDownList / SvTree).
- *
- * Native overflow scroll is composited off the main thread, so on a fast
- * scrollbar-thumb drag the browser paints the new (empty) scroll position a
- * frame before JS can re-window the virtualizer - the "blank flash while
- * scrolling". This helper removes that async gap the way Smart's list does: the
- * content does NOT use native scroll. A single `scrollOffset` state positions
- * the rows (`translateY`) AND drives the virtualizer window in the same reactive
- * flush, and a custom scrollbar + wheel/touch handlers set that offset directly.
- *
- * The component owns the markup (translated rows + the `sb`/`thumb` elements);
- * this owns the offset, the geometry, and the input handlers.
- */
-import { untrack } from 'svelte'
-
-type ScrollerVirtualizer = {
-  setScrollOffset: (offset: number) => void
-  getOffsetForIndex: (index: number) => number
-  getSizeForIndex: (index: number) => number
-}
-
-export type JsScrollerConfig = {
-  /** The shared virtualizer to drive. */
-  virtualizer: ScrollerVirtualizer
-  /** Full scrollable content height (px). */
-  totalSize: () => number
-  /** Visible viewport height (px). */
-  viewport: () => number
-  /** Row height used to convert line-mode wheel deltas to px. */
-  lineStep: () => number
-}
-
-export function createJsScroller(cfg: JsScrollerConfig) {
-  // The single source of truth for the scroll position.
-  let scrollOffset = $state(0)
-  const maxOffset = $derived(Math.max(0, cfg.totalSize() - cfg.viewport()))
-
-  // Push the offset into the virtualizer whenever it changes. `untrack` keeps
-  // the virtualizer's `version` write out of this effect's dependencies.
-  $effect(() => {
-    const o = scrollOffset
-    untrack(() => cfg.virtualizer.setScrollOffset(o))
-  })
-  // Re-clamp if the content shrinks under the current offset.
-  $effect(() => {
-    const m = maxOffset
-    if (untrack(() => scrollOffset) > m) scrollOffset = m
-  })
-
-  function scrollTo(offset: number) {
-    scrollOffset = Math.max(0, Math.min(maxOffset, offset))
-  }
-  function scrollByPx(delta: number) {
-    scrollTo(scrollOffset + delta)
-  }
-
-  function onWheel(e: WheelEvent) {
-    if (maxOffset <= 0) return
-    // deltaMode: 0 = pixels, 1 = lines, 2 = pages.
-    const step =
-      e.deltaMode === 1 ? e.deltaY * cfg.lineStep() : e.deltaMode === 2 ? e.deltaY * cfg.viewport() : e.deltaY
-    const before = scrollOffset
-    scrollByPx(step)
-    // Only swallow the wheel when it moved us, so the page can scroll once the
-    // list is pinned at its top/bottom edge.
-    if (scrollOffset !== before) e.preventDefault()
-  }
-
-  // --- Custom scrollbar geometry --------------------------------------------
-  const thumbH = $derived(
-    maxOffset > 0 && cfg.totalSize() > 0
-      ? Math.max(24, Math.min(cfg.viewport(), (cfg.viewport() / cfg.totalSize()) * cfg.viewport()))
-      : 0,
-  )
-  const trackRange = $derived(Math.max(0, cfg.viewport() - thumbH))
-  const thumbTop = $derived(maxOffset > 0 ? (scrollOffset / maxOffset) * trackRange : 0)
-
-  let dragging = $state(false)
-  let dragStartY = 0
-  let dragStartOffset = 0
-  function onThumbDown(e: PointerEvent) {
-    e.stopPropagation()
-    e.preventDefault()
-    dragging = true
-    dragStartY = e.clientY
-    dragStartOffset = scrollOffset
-    ;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId)
-  }
-  function onThumbMove(e: PointerEvent) {
-    if (!dragging) return
-    const dy = e.clientY - dragStartY
-    scrollTo(dragStartOffset + (trackRange > 0 ? (dy / trackRange) * maxOffset : 0))
-  }
-  function onThumbUp(e: PointerEvent) {
-    dragging = false
-    releaseCapture(e)
-  }
-  function onTrackDown(e: PointerEvent) {
-    const rect = (e.currentTarget as HTMLElement).getBoundingClientRect()
-    scrollByPx(e.clientY - rect.top < thumbTop ? -cfg.viewport() : cfg.viewport())
-  }
-
-  // --- Touch: drag the content to pan ---------------------------------------
-  let touchActive = false
-  let touchStartY = 0
-  let touchStartOffset = 0
-  function onContentDown(e: PointerEvent) {
-    if (e.pointerType !== 'touch') return
-    touchActive = true
-    touchStartY = e.clientY
-    touchStartOffset = scrollOffset
-    ;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId)
-  }
-  function onContentMove(e: PointerEvent) {
-    if (!touchActive) return
-    scrollTo(touchStartOffset - (e.clientY - touchStartY))
-  }
-  function onContentUp(e: PointerEvent) {
-    if (!touchActive) return
-    touchActive = false
-    releaseCapture(e)
-  }
-
-  function releaseCapture(e: PointerEvent) {
-    try {
-      ;(e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId)
-    } catch {
-      /* capture may already be gone */
-    }
-  }
-
-  /** Scroll the minimal amount to bring `[top, top+h]` fully into view. */
-  function ensureVisible(top: number, h: number) {
-    if (top < scrollOffset) scrollTo(top)
-    else if (top + h > scrollOffset + cfg.viewport()) scrollTo(top + h - cfg.viewport())
-  }
-  /** Bring a virtualizer row index into view (variable-height aware). */
-  function ensureIndexVisible(index: number) {
-    ensureVisible(cfg.virtualizer.getOffsetForIndex(index), cfg.virtualizer.getSizeForIndex(index))
-  }
-
-  return {
-    get scrollOffset() {
-      return scrollOffset
-    },
-    get maxOffset() {
-      return maxOffset
-    },
-    get thumbH() {
-      return thumbH
-    },
-    get thumbTop() {
-      return thumbTop
-    },
-    get dragging() {
-      return dragging
-    },
-    scrollTo,
-    scrollByPx,
-    ensureVisible,
-    ensureIndexVisible,
-    onWheel,
-    onThumbDown,
-    onThumbMove,
-    onThumbUp,
-    onTrackDown,
-    onContentDown,
-    onContentMove,
-    onContentUp,
-  }
-}
+/**
+ * createJsScroller - a JS-driven vertical scroller for the virtualized selection
+ * controls (SvListBox / SvDropDownList / SvTree).
+ *
+ * Native overflow scroll is composited off the main thread, so on a fast
+ * scrollbar-thumb drag the browser paints the new (empty) scroll position a
+ * frame before JS can re-window the virtualizer - the "blank flash while
+ * scrolling". This helper removes that async gap the way Smart's list does: the
+ * content does NOT use native scroll. A single `scrollOffset` state positions
+ * the rows (`translateY`) AND drives the virtualizer window in the same reactive
+ * flush, and a custom scrollbar + wheel/touch handlers set that offset directly.
+ *
+ * The component owns the markup (translated rows + the `sb`/`thumb` elements);
+ * this owns the offset, the geometry, and the input handlers.
+ */
+import { untrack } from 'svelte'
+
+type ScrollerVirtualizer = {
+  setScrollOffset: (offset: number) => void
+  getOffsetForIndex: (index: number) => number
+  getSizeForIndex: (index: number) => number
+}
+
+export type JsScrollerConfig = {
+  /** The shared virtualizer to drive. */
+  virtualizer: ScrollerVirtualizer
+  /** Full scrollable content height (px). */
+  totalSize: () => number
+  /** Visible viewport height (px). */
+  viewport: () => number
+  /** Row height used to convert line-mode wheel deltas to px. */
+  lineStep: () => number
+}
+
+export function createJsScroller(cfg: JsScrollerConfig) {
+  // The single source of truth for the scroll position.
+  let scrollOffset = $state(0)
+  const maxOffset = $derived(Math.max(0, cfg.totalSize() - cfg.viewport()))
+
+  // Push the offset into the virtualizer whenever it changes. `untrack` keeps
+  // the virtualizer's `version` write out of this effect's dependencies.
+  $effect(() => {
+    const o = scrollOffset
+    untrack(() => cfg.virtualizer.setScrollOffset(o))
+  })
+  // Re-clamp if the content shrinks under the current offset.
+  $effect(() => {
+    const m = maxOffset
+    if (untrack(() => scrollOffset) > m) scrollOffset = m
+  })
+
+  function scrollTo(offset: number) {
+    scrollOffset = Math.max(0, Math.min(maxOffset, offset))
+  }
+  function scrollByPx(delta: number) {
+    scrollTo(scrollOffset + delta)
+  }
+
+  function onWheel(e: WheelEvent) {
+    if (maxOffset <= 0) return
+    // deltaMode: 0 = pixels, 1 = lines, 2 = pages.
+    const step =
+      e.deltaMode === 1 ? e.deltaY * cfg.lineStep() : e.deltaMode === 2 ? e.deltaY * cfg.viewport() : e.deltaY
+    const before = scrollOffset
+    scrollByPx(step)
+    // Only swallow the wheel when it moved us, so the page can scroll once the
+    // list is pinned at its top/bottom edge.
+    if (scrollOffset !== before) e.preventDefault()
+  }
+
+  // --- Custom scrollbar geometry --------------------------------------------
+  const thumbH = $derived(
+    maxOffset > 0 && cfg.totalSize() > 0
+      ? Math.max(24, Math.min(cfg.viewport(), (cfg.viewport() / cfg.totalSize()) * cfg.viewport()))
+      : 0,
+  )
+  const trackRange = $derived(Math.max(0, cfg.viewport() - thumbH))
+  const thumbTop = $derived(maxOffset > 0 ? (scrollOffset / maxOffset) * trackRange : 0)
+
+  let dragging = $state(false)
+  let dragStartY = 0
+  let dragStartOffset = 0
+  function onThumbDown(e: PointerEvent) {
+    e.stopPropagation()
+    e.preventDefault()
+    dragging = true
+    dragStartY = e.clientY
+    dragStartOffset = scrollOffset
+    ;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId)
+  }
+  function onThumbMove(e: PointerEvent) {
+    if (!dragging) return
+    const dy = e.clientY - dragStartY
+    scrollTo(dragStartOffset + (trackRange > 0 ? (dy / trackRange) * maxOffset : 0))
+  }
+  function onThumbUp(e: PointerEvent) {
+    dragging = false
+    releaseCapture(e)
+  }
+  function onTrackDown(e: PointerEvent) {
+    const rect = (e.currentTarget as HTMLElement).getBoundingClientRect()
+    scrollByPx(e.clientY - rect.top < thumbTop ? -cfg.viewport() : cfg.viewport())
+  }
+
+  // --- Touch: drag the content to pan ---------------------------------------
+  let touchActive = false
+  let touchStartY = 0
+  let touchStartOffset = 0
+  function onContentDown(e: PointerEvent) {
+    if (e.pointerType !== 'touch') return
+    touchActive = true
+    touchStartY = e.clientY
+    touchStartOffset = scrollOffset
+    ;(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId)
+  }
+  function onContentMove(e: PointerEvent) {
+    if (!touchActive) return
+    scrollTo(touchStartOffset - (e.clientY - touchStartY))
+  }
+  function onContentUp(e: PointerEvent) {
+    if (!touchActive) return
+    touchActive = false
+    releaseCapture(e)
+  }
+
+  function releaseCapture(e: PointerEvent) {
+    try {
+      ;(e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId)
+    } catch {
+      /* capture may already be gone */
+    }
+  }
+
+  /** Scroll the minimal amount to bring `[top, top+h]` fully into view. */
+  function ensureVisible(top: number, h: number) {
+    if (top < scrollOffset) scrollTo(top)
+    else if (top + h > scrollOffset + cfg.viewport()) scrollTo(top + h - cfg.viewport())
+  }
+  /** Bring a virtualizer row index into view (variable-height aware). */
+  function ensureIndexVisible(index: number) {
+    ensureVisible(cfg.virtualizer.getOffsetForIndex(index), cfg.virtualizer.getSizeForIndex(index))
+  }
+
+  return {
+    get scrollOffset() {
+      return scrollOffset
+    },
+    get maxOffset() {
+      return maxOffset
+    },
+    get thumbH() {
+      return thumbH
+    },
+    get thumbTop() {
+      return thumbTop
+    },
+    get dragging() {
+      return dragging
+    },
+    scrollTo,
+    scrollByPx,
+    ensureVisible,
+    ensureIndexVisible,
+    onWheel,
+    onThumbDown,
+    onThumbMove,
+    onThumbUp,
+    onTrackDown,
+    onContentDown,
+    onContentMove,
+    onContentUp,
+  }
+}