@trackunit/react-test-setup 1.8.60 → 1.8.62-alpha-c496ead6241.0

package/index.cjs.js

@@ -125,8 +125,10 @@ const setupGoogleMaps = () => {
         const InfoWindowMock = jest.fn(props => {
             return jsxRuntime.jsx("div", { "data-testid": "google-info-window", children: props.children });
         });
+        const APIProviderMock = jest.fn(props => jsxRuntime.jsx(jsxRuntime.Fragment, { children: props.children }));
         return {
             ...originalModule,
+            APIProvider: APIProviderMock,
             useApiLoadingStatus: () => APILoadingStatus.LOADED,
             useApiIsLoaded: () => true,
             useMap: () => map,
@@ -219,6 +221,227 @@ class MockIntersectionObserver {
     }
 }
 
+/**
+ * Creates a new listener registry for tracking event subscriptions.
+ */
+const createListenerRegistry = () => ({
+    regular: new Map(),
+    once: new Map(),
+});
+/**
+ * Mock LngLat class matching Mapbox GL's interface.
+ * Returns actual objects with lng/lat properties rather than class instances.
+ */
+const createMockLngLat = (lng, lat) => ({
+    lng,
+    lat,
+    wrap: () => createMockLngLat(lng, lat),
+    toArray: () => [lng, lat],
+    distanceTo: () => 0,
+    toBounds: () => createMockLngLatBounds(lng - 1, lat - 1, lng + 1, lat + 1),
+    toString: () => `LngLat(${lng}, ${lat})`,
+    toEcef: () => [0, 0, 0],
+});
+/**
+ * Mock LngLatBounds matching Mapbox GL's interface.
+ */
+const createMockLngLatBounds = (west, south, east, north) => {
+    const sw = createMockLngLat(west, south);
+    const ne = createMockLngLat(east, north);
+    const bounds = {
+        _sw: sw,
+        _ne: ne,
+        getSouthWest: () => sw,
+        getNorthEast: () => ne,
+        getNorthWest: () => createMockLngLat(west, north),
+        getSouthEast: () => createMockLngLat(east, south),
+        getWest: () => west,
+        getSouth: () => south,
+        getEast: () => east,
+        getNorth: () => north,
+        getCenter: () => createMockLngLat((west + east) / 2, (south + north) / 2),
+        toArray: () => [
+            [west, south],
+            [east, north],
+        ],
+        toString: () => `LngLatBounds(${sw.toString()}, ${ne.toString()})`,
+        isEmpty: () => false,
+        contains: () => true,
+        extend: () => bounds,
+        setNorthEast: () => bounds,
+        setSouthWest: () => bounds,
+    };
+    return bounds;
+};
+/**
+ * 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-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);
+ * });
+ * ```
+ */
+const createMockMapboxMap = () => {
+    const registry = createListenerRegistry();
+    const addListener = (store, event, handler) => {
+        const handlers = store.get(event);
+        if (handlers === undefined) {
+            store.set(event, new Set([handler]));
+        }
+        else {
+            handlers.add(handler);
+        }
+        return map;
+    };
+    const map = {
+        on: jest.fn((event, handler) => addListener(registry.regular, event, handler)),
+        once: jest.fn((event, handler) => addListener(registry.once, event, handler)),
+        off: jest.fn((event, handler) => {
+            registry.regular.get(event)?.delete(handler);
+            return map;
+        }),
+        remove: jest.fn(),
+        getCenter: jest.fn(() => createMockLngLat(0, 0)),
+        getZoom: jest.fn(() => 10),
+        getBounds: jest.fn(() => createMockLngLatBounds(-1, -1, 1, 1)),
+        setCenter: jest.fn((_center) => map),
+        setZoom: jest.fn((_zoom) => map),
+        panTo: jest.fn((_lngLat) => map),
+        panBy: jest.fn((_offset) => map),
+        fitBounds: jest.fn((_bounds, _options) => map),
+        setStyle: jest.fn((_style) => map),
+        isStyleLoaded: jest.fn(() => true),
+        isMoving: jest.fn(() => false),
+        addSource: jest.fn(),
+        removeSource: jest.fn(),
+        getSource: jest.fn(() => undefined),
+        addLayer: jest.fn(),
+        removeLayer: jest.fn(),
+        getLayer: jest.fn(() => undefined),
+        hasImage: jest.fn(() => false),
+        addImage: jest.fn(),
+        getCanvas: jest.fn(() => ({ style: {} })),
+    };
+    const triggerEvent = (eventName, event) => {
+        // Fire regular listeners
+        const regularHandlers = registry.regular.get(eventName);
+        if (regularHandlers !== undefined) {
+            regularHandlers.forEach((handler) => handler(event));
+        }
+        // Fire and clear once listeners
+        const onceHandlers = registry.once.get(eventName);
+        if (onceHandlers !== undefined) {
+            onceHandlers.forEach((handler) => handler(event));
+            registry.once.delete(eventName);
+        }
+    };
+    return { map, triggerEvent };
+};
+/**
+ * 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
+ */
+const createMockClickEvent = (lng, lat) => ({
+    lngLat: createMockLngLat(lng, lat),
+    originalEvent: new MouseEvent("click"),
+    type: "click",
+});
+/**
+ * Sets up mocks for Mapbox GL JS in testing environments.
+ *
+ * This function mocks the mapbox-gl module with functional mock implementations,
+ * allowing tests of map-dependent components to run without WebGL or actual
+ * network requests.
+ *
+ * Key features:
+ * - Mocks mapboxgl.Map constructor to return a trackable mock instance
+ * - Auto-fires the "load" event after map construction (for renderer tests)
+ * - Provides mock implementations for all common map methods
+ * - Resets mock state between tests via beforeEach
+ *
+ * @example
+ * ```typescript
+ * // In your test file
+ * import { setupMapbox } from "@trackunit/react-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());
+ *   });
+ * });
+ * ```
+ */
+const setupMapbox = () => {
+    jest.mock("mapbox-gl", () => {
+        const createMockMapWithAutoLoad = () => {
+            const result = createMockMapboxMap();
+            // Override "on" to auto-fire "load" event for renderer compatibility
+            const originalOn = result.map.on;
+            result.map.on = jest.fn((event, handler) => {
+                originalOn(event, handler);
+                // Auto-fire load event asynchronously to simulate real Mapbox behavior
+                if (event === "load") {
+                    setTimeout(() => handler(undefined), 0);
+                }
+                return result.map;
+            });
+            return result.map;
+        };
+        const createMockMarker = () => {
+            const el = document.createElement("div");
+            const marker = {
+                setLngLat: jest.fn(() => marker),
+                addTo: jest.fn(() => marker),
+                remove: jest.fn(),
+                getElement: jest.fn(() => el),
+                setOffset: jest.fn(() => marker),
+                getLngLat: jest.fn(() => createMockLngLat(0, 0)),
+                setPopup: jest.fn(() => marker),
+                getPopup: jest.fn(() => null),
+                togglePopup: jest.fn(() => marker),
+                setDraggable: jest.fn(() => marker),
+                isDraggable: jest.fn(() => false),
+            };
+            return marker;
+        };
+        return {
+            __esModule: true,
+            default: {
+                Map: jest.fn(createMockMapWithAutoLoad),
+                Marker: jest.fn(createMockMarker),
+                accessToken: "",
+            },
+        };
+    });
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+};
+
 /**
  * Mocks the window.matchMedia API for testing environments.
  *
@@ -737,6 +960,7 @@ const setupWebStreams = () => {
  * - 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
@@ -767,6 +991,7 @@ const setupAllMocks = (options = {}) => {
     setupCanvasMock();
     setupFailOnConsole(options.failOnConsoleOptions);
     setupGoogleMaps();
+    setupMapbox();
     setupHelmetMock();
     setupIntersectionObserver();
     setupMatchMediaMock();
@@ -898,6 +1123,8 @@ const setupTanstackReactRouter = () => {
     }));
 };
 
+exports.createMockClickEvent = createMockClickEvent;
+exports.createMockMapboxMap = createMockMapboxMap;
 exports.setupAllMocks = setupAllMocks;
 exports.setupBasicMocks = setupBasicMocks;
 exports.setupCanvasMock = setupCanvasMock;
@@ -906,6 +1133,7 @@ exports.setupFailOnConsole = setupFailOnConsole;
 exports.setupGoogleMaps = setupGoogleMaps;
 exports.setupHelmetMock = setupHelmetMock;
 exports.setupIntersectionObserver = setupIntersectionObserver;
+exports.setupMapbox = setupMapbox;
 exports.setupMatchMediaMock = setupMatchMediaMock;
 exports.setupReactTestingLibrary = setupReactTestingLibrary;
 exports.setupReactVirtualizedAutoSizer = setupReactVirtualizedAutoSizer;

package/index.esm.js

@@ -104,8 +104,10 @@ const setupGoogleMaps = () => {
         const InfoWindowMock = jest.fn(props => {
             return jsx("div", { "data-testid": "google-info-window", children: props.children });
         });
+        const APIProviderMock = jest.fn(props => jsx(Fragment, { children: props.children }));
         return {
             ...originalModule,
+            APIProvider: APIProviderMock,
             useApiLoadingStatus: () => APILoadingStatus.LOADED,
             useApiIsLoaded: () => true,
             useMap: () => map,
@@ -198,6 +200,227 @@ class MockIntersectionObserver {
     }
 }
 
+/**
+ * Creates a new listener registry for tracking event subscriptions.
+ */
+const createListenerRegistry = () => ({
+    regular: new Map(),
+    once: new Map(),
+});
+/**
+ * Mock LngLat class matching Mapbox GL's interface.
+ * Returns actual objects with lng/lat properties rather than class instances.
+ */
+const createMockLngLat = (lng, lat) => ({
+    lng,
+    lat,
+    wrap: () => createMockLngLat(lng, lat),
+    toArray: () => [lng, lat],
+    distanceTo: () => 0,
+    toBounds: () => createMockLngLatBounds(lng - 1, lat - 1, lng + 1, lat + 1),
+    toString: () => `LngLat(${lng}, ${lat})`,
+    toEcef: () => [0, 0, 0],
+});
+/**
+ * Mock LngLatBounds matching Mapbox GL's interface.
+ */
+const createMockLngLatBounds = (west, south, east, north) => {
+    const sw = createMockLngLat(west, south);
+    const ne = createMockLngLat(east, north);
+    const bounds = {
+        _sw: sw,
+        _ne: ne,
+        getSouthWest: () => sw,
+        getNorthEast: () => ne,
+        getNorthWest: () => createMockLngLat(west, north),
+        getSouthEast: () => createMockLngLat(east, south),
+        getWest: () => west,
+        getSouth: () => south,
+        getEast: () => east,
+        getNorth: () => north,
+        getCenter: () => createMockLngLat((west + east) / 2, (south + north) / 2),
+        toArray: () => [
+            [west, south],
+            [east, north],
+        ],
+        toString: () => `LngLatBounds(${sw.toString()}, ${ne.toString()})`,
+        isEmpty: () => false,
+        contains: () => true,
+        extend: () => bounds,
+        setNorthEast: () => bounds,
+        setSouthWest: () => bounds,
+    };
+    return bounds;
+};
+/**
+ * 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-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);
+ * });
+ * ```
+ */
+const createMockMapboxMap = () => {
+    const registry = createListenerRegistry();
+    const addListener = (store, event, handler) => {
+        const handlers = store.get(event);
+        if (handlers === undefined) {
+            store.set(event, new Set([handler]));
+        }
+        else {
+            handlers.add(handler);
+        }
+        return map;
+    };
+    const map = {
+        on: jest.fn((event, handler) => addListener(registry.regular, event, handler)),
+        once: jest.fn((event, handler) => addListener(registry.once, event, handler)),
+        off: jest.fn((event, handler) => {
+            registry.regular.get(event)?.delete(handler);
+            return map;
+        }),
+        remove: jest.fn(),
+        getCenter: jest.fn(() => createMockLngLat(0, 0)),
+        getZoom: jest.fn(() => 10),
+        getBounds: jest.fn(() => createMockLngLatBounds(-1, -1, 1, 1)),
+        setCenter: jest.fn((_center) => map),
+        setZoom: jest.fn((_zoom) => map),
+        panTo: jest.fn((_lngLat) => map),
+        panBy: jest.fn((_offset) => map),
+        fitBounds: jest.fn((_bounds, _options) => map),
+        setStyle: jest.fn((_style) => map),
+        isStyleLoaded: jest.fn(() => true),
+        isMoving: jest.fn(() => false),
+        addSource: jest.fn(),
+        removeSource: jest.fn(),
+        getSource: jest.fn(() => undefined),
+        addLayer: jest.fn(),
+        removeLayer: jest.fn(),
+        getLayer: jest.fn(() => undefined),
+        hasImage: jest.fn(() => false),
+        addImage: jest.fn(),
+        getCanvas: jest.fn(() => ({ style: {} })),
+    };
+    const triggerEvent = (eventName, event) => {
+        // Fire regular listeners
+        const regularHandlers = registry.regular.get(eventName);
+        if (regularHandlers !== undefined) {
+            regularHandlers.forEach((handler) => handler(event));
+        }
+        // Fire and clear once listeners
+        const onceHandlers = registry.once.get(eventName);
+        if (onceHandlers !== undefined) {
+            onceHandlers.forEach((handler) => handler(event));
+            registry.once.delete(eventName);
+        }
+    };
+    return { map, triggerEvent };
+};
+/**
+ * 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
+ */
+const createMockClickEvent = (lng, lat) => ({
+    lngLat: createMockLngLat(lng, lat),
+    originalEvent: new MouseEvent("click"),
+    type: "click",
+});
+/**
+ * Sets up mocks for Mapbox GL JS in testing environments.
+ *
+ * This function mocks the mapbox-gl module with functional mock implementations,
+ * allowing tests of map-dependent components to run without WebGL or actual
+ * network requests.
+ *
+ * Key features:
+ * - Mocks mapboxgl.Map constructor to return a trackable mock instance
+ * - Auto-fires the "load" event after map construction (for renderer tests)
+ * - Provides mock implementations for all common map methods
+ * - Resets mock state between tests via beforeEach
+ *
+ * @example
+ * ```typescript
+ * // In your test file
+ * import { setupMapbox } from "@trackunit/react-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());
+ *   });
+ * });
+ * ```
+ */
+const setupMapbox = () => {
+    jest.mock("mapbox-gl", () => {
+        const createMockMapWithAutoLoad = () => {
+            const result = createMockMapboxMap();
+            // Override "on" to auto-fire "load" event for renderer compatibility
+            const originalOn = result.map.on;
+            result.map.on = jest.fn((event, handler) => {
+                originalOn(event, handler);
+                // Auto-fire load event asynchronously to simulate real Mapbox behavior
+                if (event === "load") {
+                    setTimeout(() => handler(undefined), 0);
+                }
+                return result.map;
+            });
+            return result.map;
+        };
+        const createMockMarker = () => {
+            const el = document.createElement("div");
+            const marker = {
+                setLngLat: jest.fn(() => marker),
+                addTo: jest.fn(() => marker),
+                remove: jest.fn(),
+                getElement: jest.fn(() => el),
+                setOffset: jest.fn(() => marker),
+                getLngLat: jest.fn(() => createMockLngLat(0, 0)),
+                setPopup: jest.fn(() => marker),
+                getPopup: jest.fn(() => null),
+                togglePopup: jest.fn(() => marker),
+                setDraggable: jest.fn(() => marker),
+                isDraggable: jest.fn(() => false),
+            };
+            return marker;
+        };
+        return {
+            __esModule: true,
+            default: {
+                Map: jest.fn(createMockMapWithAutoLoad),
+                Marker: jest.fn(createMockMarker),
+                accessToken: "",
+            },
+        };
+    });
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+};
+
 /**
  * Mocks the window.matchMedia API for testing environments.
  *
@@ -716,6 +939,7 @@ const setupWebStreams = () => {
  * - 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
@@ -746,6 +970,7 @@ const setupAllMocks = (options = {}) => {
     setupCanvasMock();
     setupFailOnConsole(options.failOnConsoleOptions);
     setupGoogleMaps();
+    setupMapbox();
     setupHelmetMock();
     setupIntersectionObserver();
     setupMatchMediaMock();
@@ -877,4 +1102,4 @@ const setupTanstackReactRouter = () => {
     }));
 };
 
-export { setupAllMocks, setupBasicMocks, setupCanvasMock, setupDefaultMocks, setupFailOnConsole, setupGoogleMaps, setupHelmetMock, setupIntersectionObserver, setupMatchMediaMock, setupReactTestingLibrary, setupReactVirtualizedAutoSizer, setupResizeObserver, setupTanstackReactRouter, setupTanstackReactVirtual, setupTimeAndLanguage, setupTimeZone, setupTranslations, setupWebStreams };
+export { createMockClickEvent, createMockMapboxMap, setupAllMocks, setupBasicMocks, setupCanvasMock, setupDefaultMocks, setupFailOnConsole, setupGoogleMaps, setupHelmetMock, setupIntersectionObserver, setupMapbox, setupMatchMediaMock, setupReactTestingLibrary, setupReactVirtualizedAutoSizer, setupResizeObserver, setupTanstackReactRouter, setupTanstackReactVirtual, setupTimeAndLanguage, setupTimeZone, setupTranslations, setupWebStreams };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@trackunit/react-test-setup",
   "description": "Test setup utilities for React applications",
-  "version": "1.8.60",
+  "version": "1.8.62-alpha-c496ead6241.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -21,18 +21,19 @@
   },
   "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",
+    "jest": "30.0.5",
     "jest-canvas-mock": "^2.5.2",
     "jest-fail-on-console": "^3.1.2",
     "react": "19.0.0",
     "react-i18next": "^15.5.1",
     "react-virtualized-auto-sizer": "^1.0.20",
-    "web-streams-polyfill": "^4.2.0",
-    "jest": "30.0.5",
-    "@js-temporal/polyfill": "^0.5.1"
+    "web-streams-polyfill": "^4.2.0"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/preset.cjs.js

@@ -19,7 +19,7 @@ const irisPreset = {
         "@trackunit/ui-icons/icons-sprite-micro.svg": "jest-transform-stub",
     },
     transformIgnorePatterns: [
-        "/node_modules/(?!.*react-dnd.*|@tanstack[/-].*|.*dnd-core.*|.*react-calendar.*|.*get-user-locale.*|.*memoize.*|.*mimic-function.*|.*@wojtekmaj[/-]date-utils.*)",
+        "/node_modules/(?!.*react-dnd.*|@tanstack[/-].*|.*dnd-core.*|.*react-calendar.*|.*get-user-locale.*|.*memoize.*|.*mimic-function.*|.*@wojtekmaj[/-]date-utils.*|.*supercluster.*|.*kdbush.*)",
     ],
 };
 

package/preset.esm.js

@@ -15,7 +15,7 @@ const irisPreset = {
         "@trackunit/ui-icons/icons-sprite-micro.svg": "jest-transform-stub",
     },
     transformIgnorePatterns: [
-        "/node_modules/(?!.*react-dnd.*|@tanstack[/-].*|.*dnd-core.*|.*react-calendar.*|.*get-user-locale.*|.*memoize.*|.*mimic-function.*|.*@wojtekmaj[/-]date-utils.*)",
+        "/node_modules/(?!.*react-dnd.*|@tanstack[/-].*|.*dnd-core.*|.*react-calendar.*|.*get-user-locale.*|.*memoize.*|.*mimic-function.*|.*@wojtekmaj[/-]date-utils.*|.*supercluster.*|.*kdbush.*)",
     ],
 };
 

package/src/index.d.ts

@@ -6,6 +6,7 @@ export * from "./setupFailOnConsole";
 export * from "./setupGoogleMaps";
 export * from "./setupHelmetMock";
 export * from "./setupIntersectionObserver";
+export * from "./setupMapbox";
 export * from "./setupMatchMediaMock";
 export * from "./setupReactTestingLibrary";
 export * from "./setupReactVirtualizedAutoSizer";

package/src/setupAllMocks.d.ts

@@ -9,6 +9,7 @@ export interface SetupAllMocksOptions {
  * - 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

package/src/setupMapbox.d.ts

@@ -0,0 +1,117 @@
+import type { LngLat, LngLatBounds, LngLatLike, MapMouseEvent } from "mapbox-gl";
+/**
+ * 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: jest.Mock<MockMapboxMap, [string, MapEventHandler]>;
+    once: jest.Mock<MockMapboxMap, [string, MapEventHandler]>;
+    off: jest.Mock<MockMapboxMap, [string, MapEventHandler]>;
+    remove: jest.Mock<void, []>;
+    getCenter: jest.Mock<LngLat, []>;
+    getZoom: jest.Mock<number, []>;
+    getBounds: jest.Mock<LngLatBounds, []>;
+    setCenter: jest.Mock<MockMapboxMap, [LngLatLike]>;
+    setZoom: jest.Mock<MockMapboxMap, [number]>;
+    panTo: jest.Mock<MockMapboxMap, [LngLatLike]>;
+    panBy: jest.Mock<MockMapboxMap, [[number, number]]>;
+    fitBounds: jest.Mock<MockMapboxMap, [LngLatBounds, unknown]>;
+    setStyle: jest.Mock<MockMapboxMap, [string]>;
+    isStyleLoaded: jest.Mock<boolean, []>;
+    isMoving: jest.Mock<boolean, []>;
+    addSource: jest.Mock;
+    removeSource: jest.Mock;
+    getSource: jest.Mock;
+    addLayer: jest.Mock;
+    removeLayer: jest.Mock;
+    getLayer: jest.Mock;
+    hasImage: jest.Mock<boolean, []>;
+    addImage: jest.Mock;
+    getCanvas: jest.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-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.
+ *
+ * This function mocks the mapbox-gl module with functional mock implementations,
+ * allowing tests of map-dependent components to run without WebGL or actual
+ * network requests.
+ *
+ * Key features:
+ * - Mocks mapboxgl.Map constructor to return a trackable mock instance
+ * - Auto-fires the "load" event after map construction (for renderer tests)
+ * - Provides mock implementations for all common map methods
+ * - Resets mock state between tests via beforeEach
+ *
+ * @example
+ * ```typescript
+ * // In your test file
+ * import { setupMapbox } from "@trackunit/react-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 {};