@trackunit/react-vite-test-setup 0.0.59 → 0.0.61

package/index.cjs.js

@@ -1061,67 +1061,123 @@ const setupReactVirtualizedAutoSizer = () => {
     vitest.vi.doMock("react-virtualized-auto-sizer", () => ({ children }) => children({ height: 600, width: 600, scaledWidth: 600, scaledHeight: 600 }));
 };
 
+const ITEM_SIZE = 40;
+// Module-level: explicit opt-in test controls, set from outside the React
+// tree by the test currently under test. Unlike `count`/instance identity
+// (which must be isolated per mounted virtualizer, see `useVirtualizer`
+// below), these are intentionally global since only one hook-under-test
+// exercises them at a time.
+let virtualItemsOverride;
+let stableInstance = false;
+const noop = () => {
+    /* noop */
+};
+const createVirtualItems = (count) => {
+    const result = [];
+    for (let i = 0; i < count; i++) {
+        result.push({
+            index: i,
+            start: i * ITEM_SIZE,
+            end: (i + 1) * ITEM_SIZE,
+            size: ITEM_SIZE,
+            lane: 0,
+            key: i,
+            measureRef: noop,
+        });
+    }
+    return result;
+};
+const createVirtualizer = (getCount) => ({
+    getVirtualItems: () => virtualItemsOverride ?? createVirtualItems(getCount()),
+    getTotalSize: () => getCount() * ITEM_SIZE,
+    // Callback ref exposed by TanStack Virtual's directDomUpdates mode. The
+    // real one positions rows/sizes the container directly; the mock is a
+    // no-op so consumers can attach it without the virtualizer running.
+    containerRef: noop,
+    scrollOffset: 0,
+    isScrolling: false,
+    scrollToIndex: noop,
+    scrollToOffset: noop,
+    scrollToAlign: noop,
+    scrollToItem: noop,
+    resetAfterIndex: noop,
+    resetAfterItem: noop,
+    scrollTo: noop,
+    measure: noop,
+    measureElement: () => 42,
+});
 /**
- * Mocks the `@tanstack/react-virtual` library for testing environments.
+ * Overrides the virtual items returned by every mocked virtualizer. Pass
+ * `undefined` to fall back to the deterministic full-window items derived
+ * from `count`.
+ */
+const setTanstackReactVirtualItems = (virtualItems) => {
+    virtualItemsOverride = virtualItems;
+};
+/**
+ * Controls whether `useVirtualizer` returns a referentially stable object
+ * across re-renders of the same mounted instance, mirroring the real
+ * virtualizer's in-place-update behaviour. Defaults to `false` (a new object
+ * every render).
+ */
+const setTanstackReactVirtualStableInstance = (isStableInstance) => {
+    stableInstance = isStableInstance;
+};
+/** Resets all mock test controls set via `setTanstackReactVirtualItems`/`setTanstackReactVirtualStableInstance`. */
+const resetTanstackReactVirtualMock = () => {
+    virtualItemsOverride = undefined;
+    stableInstance = false;
+};
+/**
+ * Builds the mock module object for `@tanstack/react-virtual`.
  *
- * Replaces `useVirtualizer` with a deterministic implementation that
- * returns every item (no real DOM virtualisation), so tests can assert on
- * the full rendered list without worrying about scroll-driven windowing.
+ * `useVirtualizer` is replaced with a deterministic implementation that
+ * returns every item (no real DOM virtualisation), so tests can assert on the
+ * full rendered list without worrying about scroll-driven windowing. The
+ * shape mirrors the fields consumed after the `directDomUpdates` migration
+ * (`containerRef`, `scrollOffset`, `isScrolling`, and item `size`/`end`/`lane`).
  *
- * Opt-in: the mock is registered via `vi.doMock` so it is
- * NOT hoisted and only takes effect once `setupTanstackReactVirtual()` is
- * called from a test setup file. Tests that need the real virtualizer (or
- * their own mock) are unaffected unless they explicitly call this.
+ * `count`/object-identity are tracked per mounted call site via `useRef` (the
+ * mock is invoked during render, so real hooks are safe to use here), so two
+ * simultaneously-rendered virtualized components don't stomp on each other's
+ * state the way a shared module-level variable would.
+ *
+ * Use this from a per-file `vi.mock` when a project-wide mock is not desirable
+ * (e.g. sibling specs render virtualized components through real pagination
+ * flows that would otherwise loop):
+ *
+ * @example
+ * vi.mock("@tanstack/react-virtual", async () => {
+ *   const { tanstackReactVirtualMock } = await import("@trackunit/react-vite-test-setup");
+ *   return tanstackReactVirtualMock();
+ * });
+ */
+const tanstackReactVirtualMock = async () => ({
+    ...(await vitest.vi.importActual("@tanstack/react-virtual")),
+    useVirtualizer: ({ count }) => {
+        const countRef = react$1.useRef(count);
+        countRef.current = count;
+        const instanceRef = react$1.useRef(null);
+        if (!stableInstance || instanceRef.current === null) {
+            instanceRef.current = createVirtualizer(() => countRef.current);
+        }
+        return instanceRef.current;
+    },
+});
+/**
+ * Mocks the `@tanstack/react-virtual` library for testing environments.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is NOT hoisted and only
+ * takes effect once `setupTanstackReactVirtual()` is called from a test setup
+ * file. Tests that need the real virtualizer (or their own mock) are
+ * unaffected unless they explicitly call this.
  *
  * @example
  * import { setupTanstackReactVirtual } from '@trackunit/react-vite-test-setup';
  * setupTanstackReactVirtual();
  */
 const setupTanstackReactVirtual = () => {
-    vitest.vi.doMock("@tanstack/react-virtual", () => ({
-        useVirtualizer: ({ count }) => ({
-            getVirtualItems: () => {
-                const result = [];
-                for (let i = 0; i < count; i++) {
-                    result.push({
-                        index: i,
-                        start: i * 40,
-                        key: i,
-                        measureRef: () => {
-                            /* noop */
-                        },
-                    });
-                }
-                return result;
-            },
-            getTotalSize: () => count,
-            scrollToIndex: () => {
-                /* noop */
-            },
-            scrollToOffset: () => {
-                /* noop */
-            },
-            scrollToAlign: () => {
-                /* noop */
-            },
-            scrollToItem: () => {
-                /* noop */
-            },
-            resetAfterIndex: () => {
-                /* noop */
-            },
-            resetAfterItem: () => {
-                /* noop */
-            },
-            scrollTo: () => {
-                /* noop */
-            },
-            measure: () => {
-                /* noop */
-            },
-            measureElement: () => 42,
-        }),
-    }));
+    vitest.vi.doMock("@tanstack/react-virtual", async () => tanstackReactVirtualMock());
 };
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -1360,6 +1416,9 @@ const setupTanstackReactRouter = () => {
 exports.configureReliableAsyncUtils = configureReliableAsyncUtils;
 exports.createMockClickEvent = createMockClickEvent;
 exports.createMockMapboxMap = createMockMapboxMap;
+exports.resetTanstackReactVirtualMock = resetTanstackReactVirtualMock;
+exports.setTanstackReactVirtualItems = setTanstackReactVirtualItems;
+exports.setTanstackReactVirtualStableInstance = setTanstackReactVirtualStableInstance;
 exports.setupAllMocks = setupAllMocks;
 exports.setupBasicMocks = setupBasicMocks;
 exports.setupCanvasMock = setupCanvasMock;
@@ -1379,3 +1438,4 @@ exports.setupTimeAndLanguage = setupTimeAndLanguage;
 exports.setupTimeZone = setupTimeZone;
 exports.setupTranslations = setupTranslations;
 exports.setupWebStreams = setupWebStreams;
+exports.tanstackReactVirtualMock = tanstackReactVirtualMock;

package/index.esm.js

@@ -5,7 +5,7 @@ import failOnConsole from 'vitest-fail-on-console';
 import { jsx, Fragment } from 'react/jsx-runtime';
 import '@testing-library/jest-dom/vitest';
 import { TextEncoder, TextDecoder } from 'util';
-import { isValidElement, cloneElement } from 'react';
+import { isValidElement, cloneElement, useRef } from 'react';
 import * as reactI18next from 'react-i18next';
 import { Temporal } from '@js-temporal/polyfill';
 import { Globals } from '@react-spring/web';
@@ -1040,67 +1040,123 @@ const setupReactVirtualizedAutoSizer = () => {
     vi.doMock("react-virtualized-auto-sizer", () => ({ children }) => children({ height: 600, width: 600, scaledWidth: 600, scaledHeight: 600 }));
 };
 
+const ITEM_SIZE = 40;
+// Module-level: explicit opt-in test controls, set from outside the React
+// tree by the test currently under test. Unlike `count`/instance identity
+// (which must be isolated per mounted virtualizer, see `useVirtualizer`
+// below), these are intentionally global since only one hook-under-test
+// exercises them at a time.
+let virtualItemsOverride;
+let stableInstance = false;
+const noop = () => {
+    /* noop */
+};
+const createVirtualItems = (count) => {
+    const result = [];
+    for (let i = 0; i < count; i++) {
+        result.push({
+            index: i,
+            start: i * ITEM_SIZE,
+            end: (i + 1) * ITEM_SIZE,
+            size: ITEM_SIZE,
+            lane: 0,
+            key: i,
+            measureRef: noop,
+        });
+    }
+    return result;
+};
+const createVirtualizer = (getCount) => ({
+    getVirtualItems: () => virtualItemsOverride ?? createVirtualItems(getCount()),
+    getTotalSize: () => getCount() * ITEM_SIZE,
+    // Callback ref exposed by TanStack Virtual's directDomUpdates mode. The
+    // real one positions rows/sizes the container directly; the mock is a
+    // no-op so consumers can attach it without the virtualizer running.
+    containerRef: noop,
+    scrollOffset: 0,
+    isScrolling: false,
+    scrollToIndex: noop,
+    scrollToOffset: noop,
+    scrollToAlign: noop,
+    scrollToItem: noop,
+    resetAfterIndex: noop,
+    resetAfterItem: noop,
+    scrollTo: noop,
+    measure: noop,
+    measureElement: () => 42,
+});
 /**
- * Mocks the `@tanstack/react-virtual` library for testing environments.
+ * Overrides the virtual items returned by every mocked virtualizer. Pass
+ * `undefined` to fall back to the deterministic full-window items derived
+ * from `count`.
+ */
+const setTanstackReactVirtualItems = (virtualItems) => {
+    virtualItemsOverride = virtualItems;
+};
+/**
+ * Controls whether `useVirtualizer` returns a referentially stable object
+ * across re-renders of the same mounted instance, mirroring the real
+ * virtualizer's in-place-update behaviour. Defaults to `false` (a new object
+ * every render).
+ */
+const setTanstackReactVirtualStableInstance = (isStableInstance) => {
+    stableInstance = isStableInstance;
+};
+/** Resets all mock test controls set via `setTanstackReactVirtualItems`/`setTanstackReactVirtualStableInstance`. */
+const resetTanstackReactVirtualMock = () => {
+    virtualItemsOverride = undefined;
+    stableInstance = false;
+};
+/**
+ * Builds the mock module object for `@tanstack/react-virtual`.
  *
- * Replaces `useVirtualizer` with a deterministic implementation that
- * returns every item (no real DOM virtualisation), so tests can assert on
- * the full rendered list without worrying about scroll-driven windowing.
+ * `useVirtualizer` is replaced with a deterministic implementation that
+ * returns every item (no real DOM virtualisation), so tests can assert on the
+ * full rendered list without worrying about scroll-driven windowing. The
+ * shape mirrors the fields consumed after the `directDomUpdates` migration
+ * (`containerRef`, `scrollOffset`, `isScrolling`, and item `size`/`end`/`lane`).
  *
- * Opt-in: the mock is registered via `vi.doMock` so it is
- * NOT hoisted and only takes effect once `setupTanstackReactVirtual()` is
- * called from a test setup file. Tests that need the real virtualizer (or
- * their own mock) are unaffected unless they explicitly call this.
+ * `count`/object-identity are tracked per mounted call site via `useRef` (the
+ * mock is invoked during render, so real hooks are safe to use here), so two
+ * simultaneously-rendered virtualized components don't stomp on each other's
+ * state the way a shared module-level variable would.
+ *
+ * Use this from a per-file `vi.mock` when a project-wide mock is not desirable
+ * (e.g. sibling specs render virtualized components through real pagination
+ * flows that would otherwise loop):
+ *
+ * @example
+ * vi.mock("@tanstack/react-virtual", async () => {
+ *   const { tanstackReactVirtualMock } = await import("@trackunit/react-vite-test-setup");
+ *   return tanstackReactVirtualMock();
+ * });
+ */
+const tanstackReactVirtualMock = async () => ({
+    ...(await vi.importActual("@tanstack/react-virtual")),
+    useVirtualizer: ({ count }) => {
+        const countRef = useRef(count);
+        countRef.current = count;
+        const instanceRef = useRef(null);
+        if (!stableInstance || instanceRef.current === null) {
+            instanceRef.current = createVirtualizer(() => countRef.current);
+        }
+        return instanceRef.current;
+    },
+});
+/**
+ * Mocks the `@tanstack/react-virtual` library for testing environments.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is NOT hoisted and only
+ * takes effect once `setupTanstackReactVirtual()` is called from a test setup
+ * file. Tests that need the real virtualizer (or their own mock) are
+ * unaffected unless they explicitly call this.
  *
  * @example
  * import { setupTanstackReactVirtual } from '@trackunit/react-vite-test-setup';
  * setupTanstackReactVirtual();
  */
 const setupTanstackReactVirtual = () => {
-    vi.doMock("@tanstack/react-virtual", () => ({
-        useVirtualizer: ({ count }) => ({
-            getVirtualItems: () => {
-                const result = [];
-                for (let i = 0; i < count; i++) {
-                    result.push({
-                        index: i,
-                        start: i * 40,
-                        key: i,
-                        measureRef: () => {
-                            /* noop */
-                        },
-                    });
-                }
-                return result;
-            },
-            getTotalSize: () => count,
-            scrollToIndex: () => {
-                /* noop */
-            },
-            scrollToOffset: () => {
-                /* noop */
-            },
-            scrollToAlign: () => {
-                /* noop */
-            },
-            scrollToItem: () => {
-                /* noop */
-            },
-            resetAfterIndex: () => {
-                /* noop */
-            },
-            resetAfterItem: () => {
-                /* noop */
-            },
-            scrollTo: () => {
-                /* noop */
-            },
-            measure: () => {
-                /* noop */
-            },
-            measureElement: () => 42,
-        }),
-    }));
+    vi.doMock("@tanstack/react-virtual", async () => tanstackReactVirtualMock());
 };
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -1336,4 +1392,4 @@ const setupTanstackReactRouter = () => {
     }));
 };
 
-export { configureReliableAsyncUtils, createMockClickEvent, createMockMapboxMap, setupAllMocks, setupBasicMocks, setupCanvasMock, setupDefaultMocks, setupFailOnConsole, setupGoogleMaps, setupHelmetMock, setupIntersectionObserver, setupMapbox, setupMatchMediaMock, setupReactTestingLibrary, setupReactVirtualizedAutoSizer, setupResizeObserver, setupTanstackReactRouter, setupTanstackReactVirtual, setupTimeAndLanguage, setupTimeZone, setupTranslations, setupWebStreams };
+export { configureReliableAsyncUtils, createMockClickEvent, createMockMapboxMap, resetTanstackReactVirtualMock, setTanstackReactVirtualItems, setTanstackReactVirtualStableInstance, setupAllMocks, setupBasicMocks, setupCanvasMock, setupDefaultMocks, setupFailOnConsole, setupGoogleMaps, setupHelmetMock, setupIntersectionObserver, setupMapbox, setupMatchMediaMock, setupReactTestingLibrary, setupReactVirtualizedAutoSizer, setupResizeObserver, setupTanstackReactRouter, setupTanstackReactVirtual, setupTimeAndLanguage, setupTimeZone, setupTranslations, setupWebStreams, tanstackReactVirtualMock };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@trackunit/react-vite-test-setup",
   "description": "Test setup utilities for React applications",
-  "version": "0.0.59",
+  "version": "0.0.61",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -23,6 +23,7 @@
     "@googlemaps/jest-mocks": "2.22.6",
     "@js-temporal/polyfill": "^0.5.1",
     "@react-spring/web": "9.7.5",
+    "@tanstack/react-virtual": "^3.14.3",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "16.2.0",
     "@vis.gl/react-google-maps": "^1.7.1",

package/src/setupTanstackReactVirtualize.d.ts

@@ -1,17 +1,85 @@
+export type TanstackReactVirtualMockItem = {
+    readonly index: number;
+    readonly start: number;
+    readonly end: number;
+    readonly size: number;
+    readonly lane: number;
+    readonly key: number;
+    readonly measureRef: () => void;
+};
+type TanstackReactVirtualMockVirtualizer = {
+    readonly getVirtualItems: () => ReadonlyArray<TanstackReactVirtualMockItem>;
+    readonly getTotalSize: () => number;
+    readonly containerRef: () => void;
+    readonly scrollOffset: number;
+    readonly isScrolling: boolean;
+    readonly scrollToIndex: () => void;
+    readonly scrollToOffset: () => void;
+    readonly scrollToAlign: () => void;
+    readonly scrollToItem: () => void;
+    readonly resetAfterIndex: () => void;
+    readonly resetAfterItem: () => void;
+    readonly scrollTo: () => void;
+    readonly measure: () => void;
+    readonly measureElement: () => number;
+};
+type UseVirtualizerOptions = {
+    readonly count: number;
+};
+type TanstackReactVirtualMockModule = {
+    readonly useVirtualizer: (options: UseVirtualizerOptions) => TanstackReactVirtualMockVirtualizer;
+};
 /**
- * Mocks the `@tanstack/react-virtual` library for testing environments.
+ * Overrides the virtual items returned by every mocked virtualizer. Pass
+ * `undefined` to fall back to the deterministic full-window items derived
+ * from `count`.
+ */
+export declare const setTanstackReactVirtualItems: (virtualItems: ReadonlyArray<TanstackReactVirtualMockItem> | undefined) => void;
+/**
+ * Controls whether `useVirtualizer` returns a referentially stable object
+ * across re-renders of the same mounted instance, mirroring the real
+ * virtualizer's in-place-update behaviour. Defaults to `false` (a new object
+ * every render).
+ */
+export declare const setTanstackReactVirtualStableInstance: (isStableInstance: boolean) => void;
+/** Resets all mock test controls set via `setTanstackReactVirtualItems`/`setTanstackReactVirtualStableInstance`. */
+export declare const resetTanstackReactVirtualMock: () => void;
+/**
+ * Builds the mock module object for `@tanstack/react-virtual`.
+ *
+ * `useVirtualizer` is replaced with a deterministic implementation that
+ * returns every item (no real DOM virtualisation), so tests can assert on the
+ * full rendered list without worrying about scroll-driven windowing. The
+ * shape mirrors the fields consumed after the `directDomUpdates` migration
+ * (`containerRef`, `scrollOffset`, `isScrolling`, and item `size`/`end`/`lane`).
  *
- * Replaces `useVirtualizer` with a deterministic implementation that
- * returns every item (no real DOM virtualisation), so tests can assert on
- * the full rendered list without worrying about scroll-driven windowing.
+ * `count`/object-identity are tracked per mounted call site via `useRef` (the
+ * mock is invoked during render, so real hooks are safe to use here), so two
+ * simultaneously-rendered virtualized components don't stomp on each other's
+ * state the way a shared module-level variable would.
+ *
+ * Use this from a per-file `vi.mock` when a project-wide mock is not desirable
+ * (e.g. sibling specs render virtualized components through real pagination
+ * flows that would otherwise loop):
+ *
+ * @example
+ * vi.mock("@tanstack/react-virtual", async () => {
+ *   const { tanstackReactVirtualMock } = await import("@trackunit/react-vite-test-setup");
+ *   return tanstackReactVirtualMock();
+ * });
+ */
+export declare const tanstackReactVirtualMock: () => Promise<TanstackReactVirtualMockModule>;
+/**
+ * Mocks the `@tanstack/react-virtual` library for testing environments.
  *
- * Opt-in: the mock is registered via `vi.doMock` so it is
- * NOT hoisted and only takes effect once `setupTanstackReactVirtual()` is
- * called from a test setup file. Tests that need the real virtualizer (or
- * their own mock) are unaffected unless they explicitly call this.
+ * Opt-in: the mock is registered via `vi.doMock` so it is NOT hoisted and only
+ * takes effect once `setupTanstackReactVirtual()` is called from a test setup
+ * file. Tests that need the real virtualizer (or their own mock) are
+ * unaffected unless they explicitly call this.
  *
  * @example
  * import { setupTanstackReactVirtual } from '@trackunit/react-vite-test-setup';
  * setupTanstackReactVirtual();
  */
 export declare const setupTanstackReactVirtual: () => void;
+export {};