@trackunit/react-vite-test-setup 0.0.1

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@trackunit/react-vite-test-setup",
+  "description": "Test setup utilities for React applications",
+  "version": "0.0.1",
+  "repository": "https://github.com/Trackunit/manager",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "engines": {
+    "node": ">=24.x"
+  },
+  "exports": {
+    ".": {
+      "import": "./index.esm.js",
+      "require": "./index.cjs.js",
+      "types": "./index.esm.d.ts"
+    },
+    "./preset": {
+      "import": "./preset.esm.js",
+      "require": "./preset.cjs.js",
+      "types": "./preset.esm.d.ts"
+    }
+  },
+  "dependencies": {
+    "@googlemaps/jest-mocks": "2.22.6",
+    "@js-temporal/polyfill": "^0.5.1",
+    "@react-spring/web": "9.7.5",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "16.2.0",
+    "@vis.gl/react-google-maps": "^1.7.1",
+    "mapbox-gl": "^3.18.1",
+    "vitest-canvas-mock": "^1.1.4",
+    "vitest-fail-on-console": "^0.10.1",
+    "react-i18next": "^15.5.1",
+    "react-virtualized-auto-sizer": "^1.0.20",
+    "web-streams-polyfill": "^4.2.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "vitest": "^4.0.0"
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/preset.cjs.js

@@ -0,0 +1,101 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var fs = require('node:fs');
+var path = require('node:path');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
+
+/**
+ * Walk up from `process.cwd()` to the first directory containing
+ * `nx.json` (the workspace-root marker). Used so the stub-file path
+ * the preset returns is correct regardless of whether Vitest was
+ * invoked from the workspace root (the standard `nx run <p>:test`
+ * path) or from inside a project directory (e.g. `cd libs/foo && vitest`
+ * during local debugging). Falls back to `process.cwd()` if the
+ * marker is never found.
+ */
+const findWorkspaceRoot = () => {
+    let dir = process.cwd();
+    for (let i = 0; i < 16; i++) {
+        if (fs__namespace.existsSync(path.join(dir, "nx.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return process.cwd();
+};
+/**
+ * Repo-wide stub used to neutralise imports of CSS / SVG-sprite assets
+ * during tests. The Jest equivalent (`irisPreset`) used
+ * `jest-transform-stub` for the same purpose - this preset wires up
+ * `resolve.alias` instead so the same imports return an empty module
+ * under Vitest.
+ *
+ * Mirrors the `moduleNameMapper` keys from `jestPreset.ts`: any change
+ * there should be mirrored here.
+ */
+const STUB_FILE = path.resolve(findWorkspaceRoot(), "vitest.empty-stub.ts");
+const STUBBED_MODULES = [
+    /^@trackunit\/css-core$/,
+    /^@trackunit\/ui-icons\/icons-sprite-mini\.svg$/,
+    /^@trackunit\/ui-icons\/icons-sprite-outline\.svg$/,
+    /^@trackunit\/ui-icons\/icons-sprite-solid\.svg$/,
+    /^@trackunit\/ui-icons\/icons-sprite-micro\.svg$/,
+];
+/**
+ * Vitest preset for Trackunit applications.
+ *
+ * Provides the cross-cutting bits that all per-project vitest configs need:
+ *
+ *  - `resolve.alias` stubs for the design-system asset modules that have no
+ *    JS implementation at runtime (CSS files / SVG sprite manifests).
+ *  - `test.env.TZ = "UTC"` so date/time arithmetic is deterministic on every
+ *    machine, mirroring what `vitest.preset.js` did via
+ *    `process.env.TZ = "UTC"` at the top of the file. The same line is also
+ *    set inside `setupTimeAndLanguage.ts` for redundancy in libs that import
+ *    that helper directly without going through this preset.
+ *
+ * Per-project configs should `mergeConfig(vitestPreset, defineConfig({...}))`
+ * to layer their own `test.name`, `setupFiles`, `cacheDir`, etc. on top.
+ *
+ * Other Vitest-only concerns from `vitest.preset.js` are handled differently:
+ *  - `transformIgnorePatterns` is unnecessary - Vite transforms ESM
+ *    packages by default; if a CJS package needs forcing, add
+ *    `server.deps.inline` in the per-project config.
+ *  - `resolver: @nx/jest/plugins/resolver` is replaced by the
+ *    `nxViteTsPaths()` plugin in each per-project config.
+ */
+const vitestPreset = {
+    resolve: {
+        alias: STUBBED_MODULES.map(find => ({ find, replacement: STUB_FILE })),
+    },
+    test: {
+        env: {
+            TZ: "UTC",
+        },
+    },
+};
+
+exports.default = vitestPreset;
+exports.vitestPreset = vitestPreset;

package/preset.d.ts

@@ -0,0 +1,2 @@
+export * from "./src/preset";
+export { default } from "./src/preset";

package/preset.esm.js

@@ -0,0 +1,77 @@
+import * as fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Walk up from `process.cwd()` to the first directory containing
+ * `nx.json` (the workspace-root marker). Used so the stub-file path
+ * the preset returns is correct regardless of whether Vitest was
+ * invoked from the workspace root (the standard `nx run <p>:test`
+ * path) or from inside a project directory (e.g. `cd libs/foo && vitest`
+ * during local debugging). Falls back to `process.cwd()` if the
+ * marker is never found.
+ */
+const findWorkspaceRoot = () => {
+    let dir = process.cwd();
+    for (let i = 0; i < 16; i++) {
+        if (fs.existsSync(path.join(dir, "nx.json")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return process.cwd();
+};
+/**
+ * Repo-wide stub used to neutralise imports of CSS / SVG-sprite assets
+ * during tests. The Jest equivalent (`irisPreset`) used
+ * `jest-transform-stub` for the same purpose - this preset wires up
+ * `resolve.alias` instead so the same imports return an empty module
+ * under Vitest.
+ *
+ * Mirrors the `moduleNameMapper` keys from `jestPreset.ts`: any change
+ * there should be mirrored here.
+ */
+const STUB_FILE = path.resolve(findWorkspaceRoot(), "vitest.empty-stub.ts");
+const STUBBED_MODULES = [
+    /^@trackunit\/css-core$/,
+    /^@trackunit\/ui-icons\/icons-sprite-mini\.svg$/,
+    /^@trackunit\/ui-icons\/icons-sprite-outline\.svg$/,
+    /^@trackunit\/ui-icons\/icons-sprite-solid\.svg$/,
+    /^@trackunit\/ui-icons\/icons-sprite-micro\.svg$/,
+];
+/**
+ * Vitest preset for Trackunit applications.
+ *
+ * Provides the cross-cutting bits that all per-project vitest configs need:
+ *
+ *  - `resolve.alias` stubs for the design-system asset modules that have no
+ *    JS implementation at runtime (CSS files / SVG sprite manifests).
+ *  - `test.env.TZ = "UTC"` so date/time arithmetic is deterministic on every
+ *    machine, mirroring what `vitest.preset.js` did via
+ *    `process.env.TZ = "UTC"` at the top of the file. The same line is also
+ *    set inside `setupTimeAndLanguage.ts` for redundancy in libs that import
+ *    that helper directly without going through this preset.
+ *
+ * Per-project configs should `mergeConfig(vitestPreset, defineConfig({...}))`
+ * to layer their own `test.name`, `setupFiles`, `cacheDir`, etc. on top.
+ *
+ * Other Vitest-only concerns from `vitest.preset.js` are handled differently:
+ *  - `transformIgnorePatterns` is unnecessary - Vite transforms ESM
+ *    packages by default; if a CJS package needs forcing, add
+ *    `server.deps.inline` in the per-project config.
+ *  - `resolver: @nx/jest/plugins/resolver` is replaced by the
+ *    `nxViteTsPaths()` plugin in each per-project config.
+ */
+const vitestPreset = {
+    resolve: {
+        alias: STUBBED_MODULES.map(find => ({ find, replacement: STUB_FILE })),
+    },
+    test: {
+        env: {
+            TZ: "UTC",
+        },
+    },
+};
+
+export { vitestPreset as default, vitestPreset };

package/src/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./setupAllMocks";
+export * from "./setupBasicMocks";
+export * from "./setupCanvasMock";
+export * from "./setupDefaultMocks";
+export * from "./setupFailOnConsole";
+export * from "./setupGoogleMaps";
+export * from "./setupHelmetMock";
+export * from "./setupIntersectionObserver";
+export * from "./setupMapbox";
+export * from "./setupMatchMediaMock";
+export * from "./setupReactTestingLibrary";
+export * from "./setupReactVirtualizedAutoSizer";
+export * from "./setupResizeObserver";
+export * from "./setupTanstackReactRouter";
+export * from "./setupTanstackReactVirtualize";
+export * from "./setupTimeAndLanguage";
+export * from "./setupTranslations";
+export * from "./setupWebStreams";

package/src/preset/vitestPreset.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Minimal shape of the `mergeConfig`-friendly object we return.
+ *
+ * We intentionally don't pull in `UserConfig` from `vitest/config` or
+ * `vite` here: vitest 4 renames its re-export to `ViteUserConfig` and
+ * the `react-vite-test-setup` package doesn't list `vite` as a direct
+ * dependency, so threading the type through would force a real dep
+ * (and a corresponding `dependency-owner.json` entry) for nothing -
+ * `mergeConfig` accepts any object-shaped config at runtime.
+ */
+type VitestPresetShape = {
+    readonly resolve: {
+        readonly alias: ReadonlyArray<{
+            readonly find: RegExp;
+            readonly replacement: string;
+        }>;
+    };
+    readonly test: {
+        readonly env: {
+            readonly TZ: string;
+        };
+    };
+};
+/**
+ * Vitest preset for Trackunit applications.
+ *
+ * Provides the cross-cutting bits that all per-project vitest configs need:
+ *
+ *  - `resolve.alias` stubs for the design-system asset modules that have no
+ *    JS implementation at runtime (CSS files / SVG sprite manifests).
+ *  - `test.env.TZ = "UTC"` so date/time arithmetic is deterministic on every
+ *    machine, mirroring what `vitest.preset.js` did via
+ *    `process.env.TZ = "UTC"` at the top of the file. The same line is also
+ *    set inside `setupTimeAndLanguage.ts` for redundancy in libs that import
+ *    that helper directly without going through this preset.
+ *
+ * Per-project configs should `mergeConfig(vitestPreset, defineConfig({...}))`
+ * to layer their own `test.name`, `setupFiles`, `cacheDir`, etc. on top.
+ *
+ * Other Vitest-only concerns from `vitest.preset.js` are handled differently:
+ *  - `transformIgnorePatterns` is unnecessary - Vite transforms ESM
+ *    packages by default; if a CJS package needs forcing, add
+ *    `server.deps.inline` in the per-project config.
+ *  - `resolver: @nx/jest/plugins/resolver` is replaced by the
+ *    `nxViteTsPaths()` plugin in each per-project config.
+ */
+export declare const vitestPreset: VitestPresetShape;
+export {};

package/src/preset.d.ts

@@ -0,0 +1,3 @@
+import { vitestPreset } from "./preset/vitestPreset";
+export { vitestPreset };
+export default vitestPreset;

package/src/setupAllMocks.d.ts

@@ -0,0 +1,39 @@
+import { setupFailOnConsole } from "./setupFailOnConsole";
+export interface SetupAllMocksOptions {
+    failOnConsoleOptions?: Parameters<typeof setupFailOnConsole>[0];
+}
+/**
+ * Sets up all available testing mocks in a single function call.
+ *
+ * This convenience function sets up all the test mocks provided by the library:
+ * - Canvas API mocks
+ * - Console error reporting to fail tests (includes automatic CSS parser error suppression)
+ * - Google Maps API and components mocks
+ * - Mapbox GL JS mocks
+ * - React Helmet mocks
+ * - IntersectionObserver mocks
+ * - MatchMedia API mocks
+ * - React Testing Library and Okta authentication mocks
+ * - React Virtualized AutoSizer mocks
+ * - ResizeObserver mocks
+ * - Tanstack React Virtual mocks
+ * - Time and language related mocks (timezone, timers, etc.)
+ * - Translation mocks (i18n)
+ * - Web Streams API mocks
+ *
+ * Using this function is equivalent to calling each setup function individually.
+ *
+ * @param options Configuration options for individual mocks
+ * @param options.failOnConsoleOptions Options for setupFailOnConsole
+ * @example
+ * // In your jest setup file
+ * import { setupAllMocks } from '@trackunit/react-vite-test-setup';
+ *
+ * setupAllMocks();
+ *
+ * // Or with options for specific mocks:
+ * setupAllMocks({
+ *   failOnConsoleOptions: { shouldFailOnWarn: true }
+ * });
+ */
+export declare const setupAllMocks: (options?: SetupAllMocksOptions) => void;

package/src/setupBasicMocks.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Sets up essential testing mocks that don't have external library dependencies.
+ *
+ * This convenience function configures a minimal set of test mocks that are broadly
+ * applicable for most React testing scenarios without requiring specific external
+ * libraries. It includes:
+ *
+ * - Canvas API mocks
+ * - Console error reporting to fail tests
+ * - IntersectionObserver mocks
+ * - MatchMedia API mocks
+ * - ResizeObserver mocks
+ * - Timer mocks (setTimeout, setInterval)
+ * - Web Streams API mocks
+ *
+ * This is perfect for projects that want essential testing mocks without bringing
+ * in dependencies for libraries they don't use like Google Maps, React Virtual, etc.
+ *
+ * @param options Configuration options for individual mocks
+ * @param options.failOnConsoleOptions Options for setupFailOnConsole
+ * @example
+ * // In your jest setup file
+ * import { setupBasicMocks } from '@trackunit/react-vite-test-setup';
+ *
+ * setupBasicMocks();
+ *
+ * // Or with options for specific mocks:
+ * setupBasicMocks({
+ *   failOnConsoleOptions: { shouldFailOnWarn: true }
+ * });
+ */
+import { SetupAllMocksOptions } from "./setupAllMocks";
+/**
+ * Options for configuring the setupBasicMocks function.
+ * Currently shares the same options structure as SetupAllMocksOptions.
+ */
+export type SetupBasicMocksOptions = SetupAllMocksOptions;
+/**
+ * Sets up essential testing mocks with no external library dependencies.
+ *
+ * @param options Configuration options for the mocks
+ */
+export declare const setupBasicMocks: (options?: SetupBasicMocksOptions) => void;

package/src/setupCanvasMock.d.ts

@@ -0,0 +1,19 @@
+import "vitest-canvas-mock";
+/**
+ * Sets up a mock implementation for HTML Canvas API in testing environments.
+ *
+ * This function uses vitest-canvas-mock to provide a mock implementation of the
+ * HTML Canvas API, allowing tests to run without requiring a real DOM canvas.
+ * Useful for testing components that use canvas rendering.
+ *
+ * Importing vitest-canvas-mock at module load time has the side effect of
+ * patching HTMLCanvasElement.prototype.getContext globally; calling this
+ * function is a no-op kept for API compatibility with the previous Jest
+ * setup.
+ *
+ * @example
+ * import { setupCanvasMock } from '@trackunit/react-vite-test-setup';
+ *
+ * setupCanvasMock();
+ */
+export declare const setupCanvasMock: () => void;

package/src/setupDefaultMocks.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Sets up default testing mocks that cover most common React testing needs.
+ *
+ * This convenience function provides a balanced set of mocks that cover most React
+ * application testing needs. It includes all the basic mocks plus essential React
+ * testing utilities. Specifically, it includes:
+ *
+ * From setupBasicMocks:
+ * - Canvas API mocks
+ * - Console error reporting to fail tests
+ * - IntersectionObserver mocks
+ * - MatchMedia API mocks
+ * - ResizeObserver mocks
+ * - Timer mocks (setTimeout, setInterval)
+ * - Web Streams API mocks
+ *
+ * Plus these additional mocks:
+ * - React Testing Library and Okta authentication mocks
+ * - Translation mocks (i18n)
+ *
+ * This is ideal for most React applications that use i18n translations and need
+ * standard testing environment setup, without requiring specialized mocks for things
+ * like Google Maps or virtualized lists.
+ *
+ * @param options Configuration options for individual mocks
+ * @param options.failOnConsoleOptions Options for setupFailOnConsole
+ * @example
+ * // In your jest setup file
+ * import { setupDefaultMocks } from '@trackunit/react-vite-test-setup';
+ *
+ * setupDefaultMocks();
+ *
+ * // Or with options for specific mocks:
+ * setupDefaultMocks({
+ *   failOnConsoleOptions: { shouldFailOnWarn: true }
+ * });
+ */
+import { SetupBasicMocksOptions } from "./setupBasicMocks";
+/**
+ * Options for configuring the setupDefaultMocks function.
+ * Currently shares the same options structure as SetupBasicMocksOptions.
+ */
+export type SetupDefaultMocksOptions = SetupBasicMocksOptions;
+/**
+ * Sets up default testing mocks covering most common React testing scenarios.
+ *
+ * @param options Configuration options for the mocks
+ */
+export declare const setupDefaultMocks: (options?: SetupDefaultMocksOptions) => void;

package/src/setupFailOnConsole.d.ts

@@ -0,0 +1,19 @@
+import failOnConsole from "vitest-fail-on-console";
+type VitestFailOnConsoleOptions = NonNullable<Parameters<typeof failOnConsole>[0]>;
+/**
+ * This will make your tests fail if they log to console.error during the tests.
+ * See more details here: https://www.npmjs.com/package/vitest-fail-on-console
+ *
+ * This setup also automatically suppresses jsdom CSS parsing errors for modern CSS features
+ * that jsdom doesn't support (@container queries and :has() selector). Other CSS parsing
+ * errors will still cause tests to fail.
+ *
+ * If your tests logs to console.error on purpose, you should spy on the console like so:
+ * ```
+ * vi.spyOn(console, 'error').mockImplementation()
+ * // Do your logic ...
+ * expect(console.error).toHaveBeenCalledWith('your error message')
+ * ```
+ */
+export declare const setupFailOnConsole: (overrides?: VitestFailOnConsoleOptions) => void;
+export {};

package/src/setupGoogleMaps.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sets up mocks for Google Maps API and @vis.gl/react-google-maps components
+ * in testing environments.
+ *
+ * Replaces the `@vis.gl/react-google-maps` hooks/components (`APIProvider`,
+ * `useMap`, `Map`, `Marker`, `AdvancedMarker`, `InfoWindow`,
+ * `useApiIsLoaded`, `useApiLoadingStatus`) with deterministic fakes and
+ * registers a `beforeEach` hook that re-populates `global.window.google.maps`
+ * with mocked `Geocoder` / `geometry` / `AutocompleteService` implementations
+ * via `@googlemaps/jest-mocks`.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is
+ * NOT hoisted and only takes effect once `setupGoogleMaps()` is called from
+ * a test setup file. Tests that need the real `@vis.gl/react-google-maps`
+ * (or their own mock) are unaffected unless they explicitly call this.
+ *
+ * The factory body uses `require()` rather than `import` for
+ * `@vis.gl/react-google-maps` and `@googlemaps/jest-mocks` so neither
+ * package is evaluated until the factory actually runs (the latter still
+ * uses Jest globals internally, so a static import would crash any
+ * consumer that doesn't actually use the Google Maps mock).
+ *
+ * @example
+ * import { setupGoogleMaps } from '@trackunit/react-vite-test-setup';
+ * setupGoogleMaps();
+ */
+export declare const setupGoogleMaps: () => void;

package/src/setupHelmetMock.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Replaces `react-helmet-async`'s `Helmet` and `HelmetProvider` with no-op
+ * components so head-mutating components rendered under test do not touch
+ * the jsdom document.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is
+ * NOT hoisted and only takes effect once `setupHelmetMock()` is called from
+ * a test setup file. Tests that need the real `react-helmet-async` (or
+ * their own mock) are unaffected unless they explicitly call this.
+ *
+ * See more details here: https://www.npmjs.com/package/react-helmet-async
+ *
+ * @example
+ * import { setupHelmetMock } from '@trackunit/react-vite-test-setup';
+ * setupHelmetMock();
+ */
+export declare const setupHelmetMock: () => void;

package/src/setupIntersectionObserver.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Mocks the IntersectionObserver API for testing environments.
+ *
+ * This function adds a mock implementation of the IntersectionObserver API to the global window object.
+ * The mock implementation provides all the necessary methods (observe, unobserve, disconnect, takeRecords)
+ * but with empty implementations, allowing tests of components that use IntersectionObserver to run
+ * without errors in Jest's JSDOM environment.
+ *
+ * Useful for testing components that rely on:
+ * - Lazy loading
+ * - Infinite scrolling
+ * - Visibility-based rendering
+ * - Any other intersection-based functionality
+ *
+ * @example
+ * // In your jest setup file
+ * import { setupIntersectionObserver } from '@trackunit/react-vite-test-setup';
+ *
+ * setupIntersectionObserver();
+ */
+export declare const setupIntersectionObserver: () => typeof MockIntersectionObserver;
+declare class MockIntersectionObserver {
+    readonly root: Element | null;
+    readonly rootMargin: string;
+    readonly scrollMargin: string;
+    readonly thresholds: ReadonlyArray<number>;
+    constructor();
+    disconnect(): void;
+    observe(): void;
+    takeRecords(): Array<IntersectionObserverEntry>;
+    unobserve(): void;
+}
+export {};

package/src/setupMapbox.d.ts

@@ -0,0 +1,120 @@
+import type { LngLat, LngLatBounds, LngLatLike, MapMouseEvent } from "mapbox-gl";
+import { type Mock } from "vitest";
+/**
+ * Type for event handlers stored in our mock map's listener registry.
+ * Using a generic to avoid `as` assertions when retrieving handlers.
+ */
+type MapEventHandler<TEvent = unknown> = (event: TEvent) => void;
+/**
+ * Shape of the mock map returned by createMockMapboxMap.
+ * Extends the necessary parts of mapboxgl.Map for adapter testing.
+ */
+type MockMapboxMap = {
+    on: Mock<(event: string, handler: MapEventHandler) => MockMapboxMap>;
+    once: Mock<(event: string, handler: MapEventHandler) => MockMapboxMap>;
+    off: Mock<(event: string, handler: MapEventHandler) => MockMapboxMap>;
+    remove: Mock<() => void>;
+    getCenter: Mock<() => LngLat>;
+    getZoom: Mock<() => number>;
+    getBounds: Mock<() => LngLatBounds>;
+    setCenter: Mock<(center: LngLatLike) => MockMapboxMap>;
+    setZoom: Mock<(zoom: number) => MockMapboxMap>;
+    panTo: Mock<(lngLat: LngLatLike) => MockMapboxMap>;
+    panBy: Mock<(offset: [number, number]) => MockMapboxMap>;
+    fitBounds: Mock<(bounds: LngLatBounds, options: unknown) => MockMapboxMap>;
+    setStyle: Mock<(style: string) => MockMapboxMap>;
+    isStyleLoaded: Mock<() => boolean>;
+    isMoving: Mock<() => boolean>;
+    addSource: Mock;
+    removeSource: Mock;
+    getSource: Mock;
+    addLayer: Mock;
+    removeLayer: Mock;
+    getLayer: Mock;
+    setPaintProperty: Mock;
+    hasImage: Mock<() => boolean>;
+    addImage: Mock;
+    getCanvas: Mock;
+    getCanvasContainer: Mock;
+};
+/**
+ * Return type of createMockMapboxMap - provides both the mock map
+ * and a triggerEvent helper for simulating Mapbox events in tests.
+ */
+type MockMapboxMapResult = {
+    /**
+     * The mock map instance. Cast to mapboxgl.Map when passing to adapter.connect().
+     * We return MockMapboxMap to preserve access to jest mock methods in tests.
+     */
+    readonly map: MockMapboxMap;
+    /**
+     * Triggers an event on the mock map, calling all registered handlers.
+     * Handles both regular (on) and one-time (once) listeners.
+     */
+    readonly triggerEvent: <TEvent = unknown>(eventName: string, event?: TEvent) => void;
+};
+/**
+ * Creates a mock Mapbox map instance for unit testing adapter instances directly.
+ *
+ * Use this when you need fine-grained control over mock behavior, such as:
+ * - Testing adapter instance methods (connect, setCenter, etc.)
+ * - Simulating map events (idle, click, movestart)
+ * - Verifying method calls on the map
+ *
+ * @example
+ * ```typescript
+ * import { createMockMapboxMap } from "@trackunit/react-vite-test-setup";
+ *
+ * it("should connect to map", () => {
+ *   const { map, triggerEvent } = createMockMapboxMap();
+ *   const adapter = new MapboxAdapterInstance(config);
+ *
+ *   adapter.connect(map as unknown as mapboxgl.Map);
+ *   triggerEvent("idle");
+ *
+ *   expect(adapter.getState().isReady).toBe(true);
+ * });
+ * ```
+ */
+export declare const createMockMapboxMap: () => MockMapboxMapResult;
+/**
+ * Mock click event matching Mapbox GL's MapMouseEvent shape.
+ * Use with triggerEvent("click", createMockClickEvent(...))
+ *
+ * Note: The `point` property is intentionally omitted because:
+ * 1. It requires the full Point class from @mapbox/point-geometry with 30+ methods
+ * 2. No tests currently use the point property
+ * 3. Since this returns Partial<MapMouseEvent>, point is optional
+ */
+export declare const createMockClickEvent: (lng: number, lat: number) => Partial<MapMouseEvent>;
+/**
+ * Sets up mocks for Mapbox GL JS in testing environments.
+ *
+ * Replaces `mapbox-gl`'s `Map` and `Marker` constructors with deterministic
+ * fakes (the `Map` mock auto-fires the `load` event so renderer tests don't
+ * have to wait for it) and registers a `beforeEach` hook that clears mock
+ * call records between tests.
+ *
+ * Opt-in: the mock is registered via `vi.doMock` so it is
+ * NOT hoisted and only takes effect once `setupMapbox()` is called from a
+ * test setup file. Tests that need the real `mapbox-gl` (or their own mock)
+ * are unaffected unless they explicitly call this.
+ *
+ * @example
+ * ```typescript
+ * // In your test file
+ * import { setupMapbox } from "@trackunit/react-vite-test-setup";
+ *
+ * setupMapbox();
+ *
+ * describe("MapboxRenderer", () => {
+ *   it("renders map when loaded", async () => {
+ *     // The mock will auto-fire "load" event
+ *     render(<MapboxRenderer adapterInstance={instance} />);
+ *     await waitFor(() => expect(screen.getByRole("application")).toBeInTheDocument());
+ *   });
+ * });
+ * ```
+ */
+export declare const setupMapbox: () => void;
+export {};