feat(virtualizer): refactor

Author: segunadebayo

e2e/virtualizer.e2e.ts

@@ -0,0 +1,83 @@
+import { expect, test } from "@playwright/test"
+import { Model } from "./models/model"
+
+/** Standalone virtualizer examples (see shared/src/routes.ts). */
+const virtualizerRoutes = [
+  "/virtualizer/list",
+  "/virtualizer/grid",
+  "/virtualizer/padding",
+  "/virtualizer/sticky",
+  "/virtualizer/window",
+] as const
+
+/** Heavy perf comparison pages (large item counts). */
+const virtualizerPerfRoutes = ["/virtualizer/perf", "/virtualizer/perf-variable", "/virtualizer/perf-dynamic"] as const
+
+/** Components integrating @zag-js/virtualizer. */
+const virtualizedComponentRoutes = [
+  "/select/virtualized",
+  "/combobox/virtualized",
+  "/listbox/virtualized",
+  "/gridlist/virtualized",
+  "/tree-view/virtualized",
+  "/dnd/virtualized",
+] as const
+
+test.describe("virtualizer examples", () => {
+  for (const path of virtualizerRoutes) {
+    test(`smoke ${path}`, async ({ page }) => {
+      const I = new Model(page)
+      await page.goto(path)
+      await page.waitForSelector("main", { state: "visible" })
+      await I.dontSeeInConsole("flushSync was called from inside a lifecycle method", 3000)
+      await I.checkAccessibility("main")
+
+      if (path === "/virtualizer/window") {
+        // Layout uses `main { overflow-y: auto }` — scroll the main element, not the window.
+        const main = page.locator("main")
+        await main.evaluate((el) => {
+          el.scrollTop = 400
+        })
+        await expect.poll(async () => main.evaluate((el) => el.scrollTop)).toBeGreaterThan(0)
+
+        // Verify a scroll-to button works (triggers smooth scroll on the real scroll target).
+        await page.getByRole("button", { name: "Scroll to top" }).click()
+        await expect.poll(async () => main.evaluate((el) => el.scrollTop), { timeout: 5000 }).toBeLessThan(10)
+      } else {
+        const overflow = page.locator("main").locator("div[style*='overflow']").first()
+        if ((await overflow.count()) > 0) {
+          await overflow.evaluate((el) => {
+            el.scrollTop = 400
+          })
+          await expect.poll(async () => overflow.evaluate((el) => (el as HTMLElement).scrollTop)).toBeGreaterThan(0)
+        }
+      }
+    })
+  }
+
+  test.describe("perf comparisons", () => {
+    test.describe.configure({ timeout: 120_000 })
+
+    for (const path of virtualizerPerfRoutes) {
+      test(`smoke ${path} — Zag and TanStack panels`, async ({ page }) => {
+        const I = new Model(page)
+        await page.goto(path)
+        await page.waitForSelector("main", { state: "visible" })
+        await I.dontSeeInConsole("flushSync was called from inside a lifecycle method", 3000)
+        await expect(page.getByRole("heading", { name: "@zag-js/virtualizer" })).toBeVisible()
+        await expect(page.getByRole("heading", { name: "@tanstack/react-virtual" })).toBeVisible()
+        await I.checkAccessibility("main")
+      })
+    }
+  })
+
+  for (const path of virtualizedComponentRoutes) {
+    test(`smoke ${path}`, async ({ page }) => {
+      const I = new Model(page)
+      await page.goto(path)
+      await page.waitForSelector("main", { state: "visible" })
+      await I.dontSeeInConsole("flushSync was called from inside a lifecycle method", 3000)
+      await I.checkAccessibility("main")
+    })
+  }
+})

examples/next-ts/components/client-only.tsx

@@ -0,0 +1,18 @@
+import { useEffect, useState, type ReactNode } from "react"
+
+type ClientOnlyProps = {
+  children: ReactNode
+  /** Shown until the client has mounted (SSR and first paint skip `children`). */
+  fallback?: ReactNode
+}
+
+/**
+ * Renders `children` only after mount so browser-only APIs (e.g. `window`, portals)
+ * and classes that depend on them are not executed during SSR.
+ */
+export function ClientOnly({ children, fallback = null }: ClientOnlyProps) {
+  const [mounted, setMounted] = useState(false)
+  useEffect(() => setMounted(true), [])
+  if (!mounted) return <>{fallback}</>
+  return <>{children}</>
+}

examples/next-ts/hooks/use-virtualizer.ts

@@ -1,64 +1,67 @@
 import {
   GridVirtualizer,
   ListVirtualizer,
+  WindowVirtualizer,
   type GridVirtualizerOptions,
   type ListVirtualizerOptions,
+  type WindowVirtualizerOptions,
 } from "@zag-js/virtualizer"
-import { useCallback, useEffect, useReducer, useState } from "react"
-import { flushSync } from "react-dom"
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react"
 
 export function useListVirtualizer(options: ListVirtualizerOptions) {
-  const [, rerender] = useReducer(() => ({}), {})
+  const [virtualizer] = useState(() => new ListVirtualizer(options))
+  useSyncExternalStore(virtualizer.subscribe, virtualizer.getSnapshot, () => 0)
 
-  const [virtualizer] = useState(
-    () =>
-      new ListVirtualizer({
-        ...options,
-        onRangeChange(...args) {
-          flushSync(rerender)
-          options.onRangeChange?.(...args)
-        },
-      }),
+  const ref = useCallback(
+    (el: HTMLElement | null) => {
+      if (!el) return
+      virtualizer.init(el)
+    },
+    [virtualizer],
   )
 
+  useEffect(() => {
+    return () => virtualizer.destroy()
+  }, [])
+
+  return { virtualizer, ref }
+}
+
+export function useWindowVirtualizer(options: WindowVirtualizerOptions) {
+  const [virtualizer] = useState(() => new WindowVirtualizer(options))
+  useSyncExternalStore(virtualizer.subscribe, virtualizer.getSnapshot, () => 0)
+
   const ref = useCallback(
     (el: HTMLElement | null) => {
       if (!el) return
       virtualizer.init(el)
-      rerender()
     },
     [virtualizer],
   )
 
-  useEffect(() => () => virtualizer.destroy(), [virtualizer])
+  useEffect(() => {
+    return () => virtualizer.destroy()
+  }, [virtualizer])
 
   return { virtualizer, ref }
 }
 
 export function useGridVirtualizer(options: GridVirtualizerOptions) {
-  const [, rerender] = useReducer(() => ({}), {})
+  const [virtualizer] = useState(() => new GridVirtualizer(options))
 
-  const [virtualizer] = useState(
-    () =>
-      new GridVirtualizer({
-        ...options,
-        onRangeChange(...args) {
-          flushSync(rerender)
-          options.onRangeChange?.(...args)
-        },
-      }),
-  )
+  useSyncExternalStore(virtualizer.subscribe, virtualizer.getSnapshot, () => 0)
 
   const ref = useCallback(
     (el: HTMLElement | null) => {
       if (!el) return
       virtualizer.init(el)
-      rerender()
     },
     [virtualizer],
   )
 
-  useEffect(() => () => virtualizer.destroy(), [virtualizer])
+  useEffect(() => {
+    return () => virtualizer.destroy()
+  }, [])
 
   return { virtualizer, ref }
 }

examples/next-ts/next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts"
+import "./.next/dev/types/routes.d.ts"
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/pages/api-reference/config/typescript for more information.

examples/next-ts/pages/virtualizer/grid.tsx

@@ -1,6 +1,5 @@
 import { GridVirtualizer } from "@zag-js/virtualizer"
-import { useCallback, useReducer, useState } from "react"
-import { flushSync } from "react-dom"
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react"
 
 // Grid configuration
 const TOTAL_ROWS = 1000
@@ -17,30 +16,32 @@ const generateCellData = (row: number, col: number) => ({
 
 export default function Page() {
   const [isSmooth, setIsSmooth] = useState(true)
-  const [, rerender] = useReducer(() => ({}), {})
-  const [virtualizer] = useState(() => {
-    return new GridVirtualizer({
-      rowCount: TOTAL_ROWS,
-      columnCount: TOTAL_COLUMNS,
-      estimatedRowSize: () => CELL_HEIGHT,
-      estimatedColumnSize: () => CELL_WIDTH,
-      overscan: 3,
-      gap: 0,
-      paddingStart: 0,
-      paddingEnd: 0,
-      observeScrollElementSize: true,
-      onRangeChange: () => {
-        flushSync(rerender)
-      },
-    })
-  })
+  const [virtualizer] = useState(
+    () =>
+      new GridVirtualizer({
+        rowCount: TOTAL_ROWS,
+        columnCount: TOTAL_COLUMNS,
+        estimatedRowSize: () => CELL_HEIGHT,
+        estimatedColumnSize: () => CELL_WIDTH,
+        overscan: 3,
+        gap: 0,
+        paddingStart: 0,
+        paddingEnd: 0,
+        observeScrollElementSize: true,
+      }),
+  )
+
+  useSyncExternalStore(virtualizer.subscribe, virtualizer.getSnapshot, () => 0)
+
+  const setScrollElementRef = useCallback(
+    (element: HTMLDivElement | null) => {
+      if (!element) return
+      virtualizer.init(element)
+    },
+    [virtualizer],
+  )
 
-  const setScrollElementRef = useCallback((element: HTMLDivElement | null) => {
-    if (!element) return
-    virtualizer.init(element)
-    rerender()
-    return () => virtualizer.destroy()
-  }, [])
+  useEffect(() => () => virtualizer.destroy(), [virtualizer])
 
   const virtualRows = virtualizer.getVirtualRows()
   const totalWidth = virtualizer.getTotalWidth()

examples/next-ts/pages/virtualizer/list.tsx

@@ -1,6 +1,5 @@
 import { ListVirtualizer } from "@zag-js/virtualizer"
-import { useCallback, useReducer, useState } from "react"
-import { flushSync } from "react-dom"
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react"
 
 const generateItems = (count: number) =>
   Array.from({ length: count }, (_, i) => ({
@@ -13,30 +12,30 @@ const items = generateItems(10000)
 
 export default function Page() {
   const [isSmooth, setIsSmooth] = useState(true)
-  const [virtualizer] = useState<ListVirtualizer | null>(() => {
-    return new ListVirtualizer({
-      count: items.length,
-      estimatedSize: () => 142,
-      overscan: 5,
-      gap: 0,
-      paddingStart: 0,
-      paddingEnd: 0,
-      onRangeChange: () => {
-        flushSync(rerender)
-      },
-    })
-  })
-  const [, rerender] = useReducer(() => ({}), {})
+  const [virtualizer] = useState(
+    () =>
+      new ListVirtualizer({
+        count: items.length,
+        estimatedSize: () => 142,
+        overscan: 5,
+        gap: 0,
+        paddingStart: 0,
+        paddingEnd: 0,
+      }),
+  )
+
+  useSyncExternalStore(virtualizer.subscribe, virtualizer.getSnapshot, () => 0)
 
   // Callback ref to measure when element mounts
-  const setScrollElementRef = useCallback((element: HTMLDivElement | null) => {
-    if (!element) return
-    if (virtualizer) {
+  const setScrollElementRef = useCallback(
+    (element: HTMLDivElement | null) => {
+      if (!element) return
       virtualizer.init(element)
-      rerender()
-      return () => virtualizer.destroy()
-    }
-  }, [])
+    },
+    [virtualizer],
+  )
+
+  useEffect(() => () => virtualizer.destroy(), [virtualizer])
 
   const virtualItems = virtualizer.getVirtualItems()
   const totalSize = virtualizer.getTotalSize()
@@ -53,18 +52,18 @@ export default function Page() {
         </label>
 
         <div style={{ display: "flex", gap: 8, flexWrap: "wrap", marginTop: 12 }}>
-          <button type="button" onClick={() => virtualizer?.scrollToIndex(0, { smooth: isSmooth })}>
+          <button type="button" onClick={() => virtualizer.scrollToIndex(0, { smooth: isSmooth })}>
             Scroll to Top
           </button>
           <button
             type="button"
             onClick={() =>
-              virtualizer?.scrollToIndex(Math.floor(items.length / 2), { align: "center", smooth: isSmooth })
+              virtualizer.scrollToIndex(Math.floor(items.length / 2), { align: "center", smooth: isSmooth })
             }
           >
             Scroll to Middle
           </button>
-          <button type="button" onClick={() => virtualizer?.scrollToIndex(items.length - 1, { smooth: isSmooth })}>
+          <button type="button" onClick={() => virtualizer.scrollToIndex(items.length - 1, { smooth: isSmooth })}>
             Scroll to Bottom
           </button>
         </div>

examples/next-ts/pages/virtualizer/perf-dynamic.tsx

@@ -1,7 +1,6 @@
 import { useVirtualizer } from "@tanstack/react-virtual"
 import { ListVirtualizer } from "@zag-js/virtualizer"
-import { useCallback, useEffect, useReducer, useRef, useState } from "react"
-import { flushSync } from "react-dom"
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react"
 
 const ITEM_COUNT = 100_000
 
@@ -102,26 +101,23 @@ function MetricsDisplay({ label, metrics }: { label: string; metrics: Metrics |
 
 function ZagVirtualizer({ onMetrics }: { onMetrics: (m: Metrics) => void }) {
   const scrollRef = useRef<HTMLDivElement>(null)
-  const [, rerender] = useReducer(() => ({}), {})
 
   const [virtualizer] = useState(
     () =>
       new ListVirtualizer({
         count: ITEM_COUNT,
         estimatedSize: (i) => getItemHeight(i),
         overscan: 5,
-        onRangeChange() {
-          flushSync(rerender)
-        },
       }),
   )
 
+  useSyncExternalStore(virtualizer.subscribe, virtualizer.getSnapshot, () => 0)
+
   const setRef = useCallback(
     (el: HTMLDivElement | null) => {
       if (!el) return
-      ;(scrollRef as any).current = el
+      scrollRef.current = el
       virtualizer.init(el)
-      rerender()
     },
     [virtualizer],
   )