@trackunit/react-map-adapter-mapbox 0.0.3

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@trackunit/react-map-adapter-mapbox",
+  "version": "0.0.3",
+  "repository": "https://github.com/Trackunit/manager",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "engines": {
+    "node": ">=24.x"
+  },
+  "dependencies": {
+    "@trackunit/react-map-adapter-shared": "0.0.16",
+    "@trackunit/geo-json-utils": "1.14.35",
+    "mapbox-gl": "^3.18.1",
+    "supercluster": "^8.0.1",
+    "es-toolkit": "^1.39.10",
+    "react-device-detect": "^2.2.3",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/src/MapboxAdapterInstance.d.ts

@@ -0,0 +1,75 @@
+import { type AdapterInstance, type BaseAdapterConfig, type CameraState, type FitBoundsOptions, type GeoJsonBbox, type GeoJsonPosition, type MapEvent, type MapEventHandler, type MapStatus, type MapTheme, type MapType } from "@trackunit/react-map-adapter-shared";
+import { MapboxLayerPort } from "./MapboxLayerPort";
+/**
+ * Configuration for Mapbox adapter
+ */
+export type MapboxConfig = Readonly<BaseAdapterConfig & {
+    /** Mapbox access token (required) */
+    accessToken: string;
+}>;
+/**
+ * Mapbox adapter instance implementation
+ * Manages the connection between our abstract interface and Mapbox GL API
+ */
+export declare class MapboxAdapterInstance implements AdapterInstance<MapboxConfig> {
+    private readonly config;
+    /** Layer rendering port -- manages markers, shapes, routes, and overlays on the map */
+    readonly layers: MapboxLayerPort;
+    private map;
+    private state;
+    private cachedCameraState;
+    private cachedStatus;
+    private readonly cameraListeners;
+    private readonly statusListeners;
+    private readonly eventListeners;
+    private mapboxEventCleanups;
+    private isDestroyedFlag;
+    /** Unified appearance state — theme, mapType, and showRoads in one place */
+    private appearance;
+    constructor(config: MapboxConfig);
+    /**
+     * Connect to a Mapbox map instance - called by MapboxRenderer
+     */
+    connect(map: mapboxgl.Map): void;
+    getConfig(): MapboxConfig;
+    getCameraState(): CameraState;
+    getStatus(): MapStatus;
+    subscribeCamera(listener: () => void): () => void;
+    subscribeStatus(listener: () => void): () => void;
+    setCenter(center: GeoJsonPosition): Promise<void>;
+    setZoom(zoom: number): Promise<void>;
+    zoomBy(delta: number): Promise<void>;
+    fitBounds(bounds: GeoJsonBbox, options?: FitBoundsOptions): Promise<void>;
+    panTo(center: GeoJsonPosition): Promise<void>;
+    panBy(deltaX: number, deltaY: number): Promise<void>;
+    setMapType(type: MapType): Promise<void>;
+    setTheme(theme: MapTheme): Promise<void>;
+    setShowRoads(showRoads: boolean): Promise<void>;
+    on<TEventType extends MapEvent["type"]>(event: TEventType, handler: MapEventHandler<TEventType>): () => void;
+    notifyInitializationFailed(): void;
+    destroy(): void;
+    private setupEventListeners;
+    private updateState;
+    /**
+     * Update camera position fields (center, zoom, bounds) without touching isIdle.
+     * Called during `move` events so that isIdle=false set by `movestart` is preserved
+     * until the map reaches the `idle` state.
+     */
+    private updatePositionOnly;
+    /**
+     * Explicitly set isIdle and notify camera subscribers if it changed.
+     * Used by movestart (false) and the idle path already calls updateState (true).
+     */
+    private setIdleState;
+    /**
+     * Resolves the effective Mapbox style key: when the user asks for "satellite"
+     * with roads enabled, we use "hybrid" (satellite + road labels).
+     */
+    private effectiveMapType;
+    private updateCameraCache;
+    private updateStatusCache;
+    private notifyCameraListeners;
+    private notifyStatusListeners;
+    private emitEvent;
+}
+export declare const createMapboxInstance: (config: MapboxConfig) => MapboxAdapterInstance;

package/src/MapboxLayerPort.d.ts

@@ -0,0 +1,236 @@
+import { type DomPortalStore, type EntityInteractionHandler, type LayerPort, type LayerSnapshot, type MapTheme, type ShapeStyleDefaults } from "@trackunit/react-map-adapter-shared";
+/**
+ * Mapbox implementation of the LayerPort interface.
+ *
+ * Manages Mapbox GL JS sources, layers, and Marker overlays to render map content.
+ * Each source type maps to appropriate Mapbox constructs:
+ * - Markers: `mapboxgl.Marker` DOM overlays (symbol: styled div, dom: portal container)
+ * - Shapes: GeoJSON source + fill/line layers
+ * - Routes: GeoJSON source + line layer (+ optional symbol layer for arrows)
+ * - Image overlays: Image source + raster layer
+ *
+ * Client-side clustering uses `supercluster` directly, managing marker
+ * visibility based on viewport and zoom level.
+ *
+ * Requires `connect(map)` to be called (by MapboxAdapterInstance) before
+ * any sources can be rendered. Sources set before connect are queued.
+ */
+export declare class MapboxLayerPort implements LayerPort {
+    /**
+     * Marker portal subscription compatible with `useSyncExternalStore`.
+     * `<Layers>` routes descriptors from this store to `markerRender`. Includes
+     * static DOM markers and adaptive markers resolved to the DOM medium.
+     */
+    readonly markerPortals: DomPortalStore;
+    /**
+     * Cluster portal subscription compatible with `useSyncExternalStore`.
+     * `<Layers>` routes descriptors from this store to `clusterRender`. Includes
+     * client-cluster DOM containers and any other cluster-class portals.
+     */
+    readonly clusterPortals: DomPortalStore;
+    private map;
+    private readonly interactionHandlers;
+    private readonly backgroundClickHandlers;
+    private entityClickedInTick;
+    private mapClickHandler;
+    private readonly markerSources;
+    /** featureId → DOM marker, keyed by sourceId. Cleared when a source is removed. */
+    private readonly adaptiveMarkerIndex;
+    /** featureId → cluster DOM marker, keyed by sourceId. Cleared when a source is removed. */
+    private readonly clusterMarkerIndex;
+    private readonly shapeSources;
+    private readonly routeSources;
+    private readonly overlaySources;
+    private pendingSnapshot;
+    private lastNonEmptySnapshot;
+    private markerPortalDescriptors;
+    private clusterPortalDescriptors;
+    private readonly markerPortalSubscribers;
+    private readonly clusterPortalSubscribers;
+    private readonly clusterEntitiesByMarker;
+    private styleLoadHandler;
+    /**
+     * Tracks whether the Mapbox style has loaded at least once.
+     * `map.isStyleLoaded()` returns false inside `style.load` callbacks,
+     * so we maintain our own flag set synchronously in the handler.
+     */
+    private styleReady;
+    private arrowImageAdded;
+    private readonly shapeClickHandlers;
+    private readonly shapeDblClickHandlers;
+    private readonly shapeMouseEnterHandlers;
+    private readonly shapeMouseLeaveHandlers;
+    private readonly routeClickHandlers;
+    private readonly routeDblClickHandlers;
+    private readonly routeMouseEnterHandlers;
+    private readonly routeMouseLeaveHandlers;
+    private readonly markerClickHandlers;
+    private readonly markerDblClickHandlers;
+    private readonly markerMouseMoveHandlers;
+    private readonly markerMouseLeaveHandlers;
+    private lastHoveredMarkerFeatureId;
+    /** Shared state for the active document-level pointermove watcher across all DOM markers. */
+    private readonly markerHoverState;
+    private selectedShapeHandleId;
+    private selectedShapeFeatureId;
+    private hoveredShapeHandleId;
+    private hoveredShapeFeatureId;
+    private theme;
+    private readonly sourceReadyCallbacks;
+    private sourcedataHandler;
+    private _shapeStyleDefaults;
+    private get shapeStyleDefaults();
+    setShapeStyleDefaults(defaults: ShapeStyleDefaults): void;
+    /**
+     * Connect to a Mapbox map instance.
+     * Called by MapboxAdapterInstance.connect() when the map is ready.
+     * Flushes any sources that were set before the map was available.
+     */
+    connect(map: mapboxgl.Map): void;
+    setSnapshot(snapshot: LayerSnapshot): void;
+    /**
+     * Update the theme used for interaction style resolution (hover color shifts).
+     * Called by the adapter instance when the map theme changes.
+     */
+    setTheme(theme: MapTheme): void;
+    onEntityInteraction(handler: EntityInteractionHandler): () => void;
+    onBackgroundClick(handler: () => void): () => void;
+    onSourceReady(configId: string, callback: () => void): () => void;
+    /** @internal */
+    destroy(): void;
+    private syncMarkerSource;
+    private removeMarkerSourceInternal;
+    private syncShapeSource;
+    private removeShapeSourceInternal;
+    private applyShapeSelectionState;
+    private applyShapeHoverState;
+    private syncRouteSource;
+    private removeRouteSourceInternal;
+    private syncImageOverlay;
+    private removeImageOverlayInternal;
+    /**
+     * Wrapper around `map.addLayer` that starts the layer at opacity 0 and
+     * animates to the target opacity via Mapbox's native paint transition system.
+     * Layer types without a known opacity key (e.g. `symbol`) are added normally.
+     */
+    private addLayerWithFadeIn;
+    /**
+     * Process all queued source configurations that arrived before the style
+     * was ready. Idempotent -- clears each queue after processing.
+     */
+    private applySnapshot;
+    private flushPending;
+    /** Add a portal descriptor to the marker store and notify subscribers */
+    private addMarkerPortalDescriptor;
+    /** Add a portal descriptor to the cluster store and notify subscribers */
+    private addClusterPortalDescriptor;
+    /** Remove all portal descriptors for `sourceId` from both stores and notify */
+    private removePortalDescriptorsForSource;
+    private notifyMarkerPortalSubscribers;
+    private notifyClusterPortalSubscribers;
+    /**
+     * Patch existing DOM markers in place: update positions via `setLngLat` and
+     * refresh portal descriptors so React re-renders with the latest render function.
+     * Avoids the remove-then-add cycle that causes a brief flash at (0,0).
+     */
+    private patchDomMarkers;
+    /**
+     * Incrementally update adaptive DOM markers and the WebGL circle source
+     * when `adaptiveResolution` (or callbacks) changed but feature IDs are the same.
+     *
+     * Three phases:
+     * 1. DOM → symbol: remove DOM marker + portal for features leaving DOM mode.
+     * 2. Symbol → DOM: add new DOM marker + portal for features entering DOM mode.
+     * 3. DOM → DOM: update portal renderFn (so the consumer's latest closure runs).
+     * 4. Update WebGL circle source to reflect the new DOM/symbol split.
+     */
+    private patchAdaptiveMarkers;
+    /**
+     * Incrementally sync adaptive markers and server-side clusters when a viewport
+     * refetch changes which feature IDs are visible, without tearing down unchanged DOM markers.
+     */
+    private patchAdaptiveViewportData;
+    /**
+     * Remove adaptive DOM markers whose feature IDs are no longer in the incoming config.
+     */
+    private removeGoneAdaptiveAssetMarkers;
+    /**
+     * Remove server-side cluster markers whose feature IDs are no longer in the incoming config.
+     */
+    private removeGoneServerClusterMarkers;
+    /**
+     * Add new server-side cluster markers for feature IDs not yet tracked,
+     * and update existing ones with fresh portal data.
+     */
+    private syncServerClusterMarkers;
+    /**
+     * Update the Mapbox GeoJSON circle source for an adaptive marker layer,
+     * excluding features that are currently rendered as DOM markers.
+     */
+    private updateAdaptiveCircleSource;
+    private createMarkerForFeature;
+    private createClusterMarkerForFeature;
+    /**
+     * Create a mapboxgl.Marker with an empty div as content.
+     * Registers a portal descriptor in the target store (`marker` or `cluster`)
+     * so `<Layers>` renders React content into the container via
+     * `createPortal()` and routes to the matching render config.
+     */
+    private createDomMarker;
+    /**
+     * Adaptive mode: DOM overlays for features whose resolved mode is not `"symbol"`.
+     */
+    private createAdaptiveDomOverlays;
+    /**
+     * Set up client-side clustering using supercluster.
+     * Creates mapboxgl.Marker instances and manages their visibility
+     * based on zoom level and viewport.
+     */
+    private setupClientClustering;
+    /**
+     * Re-render cluster markers based on the current viewport.
+     * Called on initial setup and whenever the viewport changes.
+     */
+    private renderClusters;
+    /**
+     * Create a cluster marker for the current viewport (client-side clustering).
+     */
+    private createClusterMarkerForViewport;
+    /**
+     * Ensure the arrow icon image is registered on the map for route direction arrows.
+     * Uses a simple triangle rendered via canvas and converted to ImageData.
+     */
+    private ensureArrowImage;
+    private attachMarkerInteractionListeners;
+    private attachClusterInteractionListeners;
+    private updateClusterMarkerEntity;
+    private attachMarkerCircleLayerListeners;
+    private detachMarkerCircleLayerListeners;
+    private attachShapeLayerInteractionListeners;
+    private detachShapeLayerInteractionListeners;
+    private attachRouteLayerInteractionListeners;
+    private detachRouteLayerInteractionListeners;
+    /**
+     * Temporarily disable the map's built-in double-click zoom so that our
+     * custom dblclick handler can call fitBounds without the native zoom
+     * overriding it. Re-enables on the next tick.
+     */
+    private suppressNativeZoom;
+    /** Emit entity interaction event to all subscribed handlers */
+    private emitEntityInteraction;
+    /**
+     * Sets all interaction-sensitive paint properties for a shape source,
+     * building nested `case` expressions with selected > hovered > base priority.
+     *
+     * Called whenever hover, selection, or theme changes on the given handleId.
+     * When neither hover nor selection is active, all properties revert to base.
+     */
+    private applyShapeInteractionPaint;
+    /**
+     * Called when the map style reloads (e.g. after setTheme / setMapType).
+     * mapboxgl.Marker objects persist across style changes (they are DOM overlays),
+     * but all GeoJSON sources and layers are removed by the style change.
+     * We need to re-add them.
+     */
+    private onStyleLoad;
+}

package/src/MapboxRenderer.d.ts

@@ -0,0 +1,8 @@
+import { type AdapterRendererProps } from "@trackunit/react-map-adapter-shared";
+import { type ReactElement } from "react";
+/**
+ * Mapbox Renderer component — mounts GL JS and connects {@link MapboxAdapterInstance}.
+ * Full-map loading/error UX is owned by `@trackunit/react-map` (`createMapComponent`); this file only
+ * gates layer children on adapter readiness and reports init-time failures via the adapter.
+ */
+export declare const MapboxRenderer: (props: AdapterRendererProps) => ReactElement;

package/src/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Mapbox style URLs for different map types
+ */
+export declare const MAPBOX_MAP_TYPE_STYLES: {
+    readonly roadmap: {
+        readonly light: "mapbox://styles/mapbox/streets-v12";
+        readonly dark: "mapbox://styles/mapbox/dark-v11";
+    };
+    readonly satellite: {
+        readonly light: "mapbox://styles/mapbox/satellite-v9";
+        readonly dark: "mapbox://styles/mapbox/satellite-v9";
+    };
+    readonly hybrid: {
+        readonly light: "mapbox://styles/mapbox/satellite-streets-v12";
+        readonly dark: "mapbox://styles/mapbox/satellite-streets-v12";
+    };
+};

package/src/index.d.ts

@@ -0,0 +1,3 @@
+export { mapboxAdapter, type MapboxConfig } from "./mapboxAdapter";
+export { MapboxAdapterInstance } from "./MapboxAdapterInstance";
+export { MapboxRenderer } from "./MapboxRenderer";

package/src/mapboxAdapter.d.ts

@@ -0,0 +1,37 @@
+import { type MapboxConfig } from "./MapboxAdapterInstance";
+/**
+ * Mapbox adapter factory
+ *
+ * Creates an adapter configuration for Mapbox GL JS that can be passed to useMap.
+ *
+ * @example
+ * ```tsx
+ * const map = useMap(mapboxAdapter({
+ *   accessToken: process.env.MAPBOX_ACCESS_TOKEN,
+ *   theme: "dark",
+ *   language: "en",
+ * }));
+ *
+ * <map.Map className="h-full w-full">
+ *   {children}
+ * </map.Map>
+ * ```
+ */
+export declare const mapboxAdapter: (config: Readonly<Readonly<{
+    language?: string;
+    region?: string;
+    theme?: import("@trackunit/react-map-adapter-shared").MapTheme;
+    initialViewport?: import("@trackunit/react-map-adapter-shared").InitialViewport;
+    restrictBounds?: import("@trackunit/geo-json-utils").GeoJsonBbox | null;
+}> & {
+    accessToken: string;
+}>) => import("@trackunit/react-map-adapter-shared").AdapterConfig<Readonly<Readonly<{
+    language?: string;
+    region?: string;
+    theme?: import("@trackunit/react-map-adapter-shared").MapTheme;
+    initialViewport?: import("@trackunit/react-map-adapter-shared").InitialViewport;
+    restrictBounds?: import("@trackunit/geo-json-utils").GeoJsonBbox | null;
+}> & {
+    accessToken: string;
+}>>;
+export type { MapboxConfig };

package/src/mapboxTypeConverters.d.ts

@@ -0,0 +1,26 @@
+import type { GeoJsonBbox, GeoJsonPosition } from "@trackunit/react-map-adapter-shared";
+/**
+ * Convert GeoJSON Position [lng, lat] to Mapbox LngLatLike
+ */
+export declare const positionToLngLat: (position: GeoJsonPosition) => mapboxgl.LngLatLike;
+/**
+ * Convert Mapbox LngLat to GeoJSON Position [lng, lat]
+ * Uses Zod to validate and extract lng/lat values safely
+ */
+export declare const lngLatToPosition: (lngLat: mapboxgl.LngLat | mapboxgl.LngLatLike) => GeoJsonPosition;
+/**
+ * Convert GeoJSON Bbox [minLng, minLat, maxLng, maxLat] to Mapbox LngLatBoundsLike.
+ *
+ * When the bbox crosses the antimeridian (RFC 7946: minLng > maxLng), the northeast
+ * longitude is unwrapped by +360° so both corners are in a continuous longitude range
+ * (west longitude less than east). Mapbox GL `fitBounds` / initial `bounds` use `cameraForBounds`,
+ * which builds an AABB from NW/SE in Mercator space; raw corners like (170, 10) and
+ * (-170, -10) span almost the whole world in x, while (170, 10) and (190, 10) span the
+ * intended Pacific strip.
+ */
+export declare const bboxToLngLatBounds: (bbox: Readonly<GeoJsonBbox>) => mapboxgl.LngLatBoundsLike;
+/**
+ * Convert Mapbox LngLatBounds to GeoJSON Bbox [minLng, minLat, maxLng, maxLat].
+ * Northeast longitudes above 180° (from unwrapped bounds) are converted back to [-180, 180].
+ */
+export declare const lngLatBoundsToBbox: (bounds: mapboxgl.LngLatBounds) => GeoJsonBbox;