@trackunit/react-map-adapter-google 0.0.3

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@trackunit/react-map-adapter-google",
+  "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",
+    "@googlemaps/markerclusterer": "^2.6.2",
+    "@vis.gl/react-google-maps": "^1.7.1",
+    "es-toolkit": "^1.39.10",
+    "react-device-detect": "^2.2.3",
+    "zod": "^3.25.76"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "@types/google.maps": "^3.54.10"
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/src/GoogleApiProvider.d.ts

@@ -0,0 +1,29 @@
+import { type ReactElement, type ReactNode } from "react";
+type GoogleApiProviderProps = Readonly<{
+    /** Google Maps API key */
+    apiKey: string;
+    /** Language for map labels */
+    language?: string;
+    children: ReactNode;
+}>;
+/**
+ * Shared Google Maps API context for multi-map layouts.
+ *
+ * Wrap multiple `<Map>` instances in a single `GoogleApiProvider` to load the
+ * Google Maps JS API once and prevent zombie `google.maps.Map` instances that
+ * occur when multiple `APIProvider`s initialize concurrently with `mapId`
+ * (vector/cloud-styled maps).
+ *
+ * Each map should have a unique `mapInstanceId` in its adapter config so the
+ * vis.gl registry can distinguish them.
+ *
+ * @example
+ * ```tsx
+ * <GoogleApiProvider apiKey={API_KEY}>
+ *   <Map1 /> // googleMapsAdapter({ apiKey, mapInstanceId: "map-1" })
+ *   <Map2 /> // googleMapsAdapter({ apiKey, mapInstanceId: "map-2" })
+ * </GoogleApiProvider>
+ * ```
+ */
+export declare const GoogleApiProvider: ({ apiKey, language, children }: GoogleApiProviderProps) => ReactElement;
+export {};

package/src/GoogleMapsAdapterInstance.d.ts

@@ -0,0 +1,84 @@
+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 { GoogleMapsLayerPort } from "./GoogleMapsLayerPort";
+/**
+ * Configuration for Google Maps adapter
+ */
+export type GoogleMapsConfig = Readonly<BaseAdapterConfig & {
+    /** Google Maps API key */
+    apiKey: string;
+    /**
+     * Unique instance identifier for this map within a shared `APIProvider`.
+     * Required when multiple Google Maps coexist under a single `GoogleApiProvider`.
+     * If omitted, `GoogleMapsRenderer` auto-generates one via `useId()`.
+     */
+    mapInstanceId?: string;
+}>;
+/**
+ * Google Maps adapter instance implementation
+ * Manages the connection between our abstract interface and Google Maps API
+ */
+export declare class GoogleMapsAdapterInstance implements AdapterInstance {
+    private readonly config;
+    /** Layer rendering capabilities, provided via MapLayerContext to <Layers>. */
+    readonly layers: GoogleMapsLayerPort;
+    private map;
+    private isDestroyedFlag;
+    private state;
+    private cachedCameraState;
+    private cachedStatus;
+    private readonly cameraListeners;
+    private readonly statusListeners;
+    private readonly eventListeners;
+    private googleEventListeners;
+    /** Throttled pointermove channel shared by map mousemove and shape overlay mousemove. */
+    private pointerMoveRaf;
+    private lastPointerPosition;
+    /** Unified appearance state — theme, mapType, and showRoads in one place */
+    private appearance;
+    constructor(config: GoogleMapsConfig);
+    /**
+     * Connect to a Google Maps instance - called by GoogleMapsRenderer.
+     *
+     * Handles both first connection and reconnection (e.g. after a theme change
+     * causes vis.gl to create a new google.maps.Map instance for the new mapId).
+     * On reconnection the previous center, zoom, and map type are restored so
+     * the user doesn't see the viewport jump.
+     */
+    connect(map: google.maps.Map): void;
+    getConfig(): GoogleMapsConfig;
+    getCameraState(): CameraState;
+    getStatus(): MapStatus;
+    subscribeCamera(listener: () => void): () => void;
+    subscribeStatus(listener: () => void): () => void;
+    /**
+     * Returns the current theme.
+     * Used by GoogleMapsRenderer (via useSyncExternalStore) to reactively
+     * update the mapId prop on the <GoogleMap> component.
+     */
+    getTheme(): MapTheme;
+    setCenter(center: GeoJsonPosition): Promise<void>;
+    setZoom(zoomLevel: 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;
+    /** Detach all Google Maps native event listeners without clearing our own subscribers */
+    private removeGoogleEventListeners;
+    /** Emit a throttled pointermove event (map canvas + shape overlays). */
+    private reportPointerMove;
+    private setupEventListeners;
+    private updateState;
+    private mapTypeToGoogleMapTypeId;
+    private updateCameraCache;
+    private updateStatusCache;
+    private notifyCameraListeners;
+    private notifyStatusListeners;
+    private emitEvent;
+}
+export declare const createGoogleMapsInstance: (config: GoogleMapsConfig) => GoogleMapsAdapterInstance;

package/src/GoogleMapsLayerPort.d.ts

@@ -0,0 +1,255 @@
+import { type GeoJsonPosition } from "@trackunit/geo-json-utils";
+import { type DomPortalStore, type EntityInteractionHandler, type LayerPort, type LayerSnapshot, type MapTheme, type ShapeStyleDefaults } from "@trackunit/react-map-adapter-shared";
+/**
+ * Google Maps implementation of the LayerPort interface.
+ *
+ * Manages Google Maps objects to render map content.
+ * Each source type maps to appropriate Google Maps constructs:
+ * - Markers: Canvas OverlayView (symbol/adaptive mode), AdvancedMarkerElement (DOM mode)
+ * - Shapes: google.maps.Polygon / google.maps.Polyline
+ * - Routes: google.maps.Polyline with optional arrow symbols
+ * - Image overlays: google.maps.GroundOverlay
+ *
+ * Requires `connect(map)` to be called (by GoogleMapsAdapterInstance) before
+ * any sources can be rendered. Sources set before connect are queued.
+ */
+export declare class GoogleMapsLayerPort implements LayerPort {
+    private static readonly DBLCLICK_THRESHOLD_MS;
+    /**
+     * 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
+     * server-cluster DOM containers and any other cluster-class portals.
+     */
+    readonly clusterPortals: DomPortalStore;
+    private map;
+    private readonly interactionHandlers;
+    private readonly backgroundClickHandlers;
+    private entityClickedInTick;
+    private mapClickListener;
+    private readonly markerSources;
+    /** featureId → element, keyed by sourceId. Cleared when a source is removed. */
+    private readonly adaptiveMarkerIndex;
+    /** cluster featureId → element, 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 readonly markerHoverState;
+    private selectedShapeHandleId;
+    private selectedShapeFeatureId;
+    private hoveredShapeHandleId;
+    private hoveredShapeFeatureId;
+    private theme;
+    private lastShapeClickTime;
+    private lastShapeClickEntity;
+    /** Forwards geographic pointer position to the adapter (fill tiling settle channel). */
+    private pointerMoveReporter;
+    private holdNativeZoomTimer;
+    private mapDblClickListenerCleanup;
+    private _shapeStyleDefaults;
+    private get shapeStyleDefaults();
+    setShapeStyleDefaults(defaults: ShapeStyleDefaults): void;
+    /**
+     * Connect to a Google Maps instance.
+     * Called by GoogleMapsAdapterInstance.connect() when the map is ready.
+     * Flushes any sources that were set before the map was available.
+     */
+    connect(map: google.maps.Map): void;
+    setSnapshot(snapshot: LayerSnapshot): void;
+    /**
+     * Register a reporter for geographic pointer position. Google Maps does not
+     * emit map-level mousemove while the cursor is over clickable shape overlays;
+     * shape listeners call this so fill-tiling settle gets the correct position.
+     */
+    setPointerMoveReporter(reporter: ((position: GeoJsonPosition) => void) | null): 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(_sourceId: string, callback: () => void): () => void;
+    /** @internal */
+    destroy(): void;
+    private applySnapshot;
+    private syncMarkerSource;
+    private removeMarkerSourceInternal;
+    private syncShapeSource;
+    /** Deep equality for clipped fill overrides — map emissions create new Map refs every time. */
+    private fillOverrideEqual;
+    /**
+     * Patch only features whose fill-override or z-index changed (ADR-0021 Path B).
+     * Returns the number of features that were updated or re-rendered.
+     */
+    private syncShapeTilingOverrides;
+    /** Remove all map shapes (and their listeners) for a single feature id. */
+    private removeFeatureShapes;
+    /** Update z-index on fill-bearing polygons for one feature without a geometry rebuild. */
+    private updateFeatureShapeZIndex;
+    private removeShapeSourceInternal;
+    private applyShapeSelectionState;
+    private applyShapeHoverState;
+    private syncRouteSource;
+    private removeRouteSourceInternal;
+    private syncImageOverlay;
+    private removeImageOverlayInternal;
+    /** 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 and refresh portal
+     * descriptors so React re-renders with the latest render function.
+     * Avoids the remove-then-add cycle that causes a brief flash.
+     */
+    private patchDomMarkers;
+    /**
+     * 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;
+    private removeGoneAdaptiveAssetMarkers;
+    private removeGoneServerClusterMarkers;
+    private syncServerClusterMarkers;
+    /**
+     * Incrementally update adaptive DOM markers and the canvas symbol overlay
+     * when `adaptiveResolution` (or callbacks) changed but feature IDs are the same.
+     *
+     * Three phases:
+     * 1. DOM → symbol: detach DOM marker + remove portal for features leaving DOM mode.
+     * 2. Symbol → DOM: add DOM marker + portal for features entering DOM mode.
+     * 3. DOM → DOM: update portal renderFn (so the consumer's latest closure runs).
+     * 4. Update canvas symbol overlay to reflect the new DOM/symbol split.
+     */
+    private patchAdaptiveMarkers;
+    /**
+     * Repaint the canvas symbol overlay for a `mode: "symbol"` layer after the
+     * render function changed (e.g. activeState flip). Rebuilds `canvasMarkers`
+     * in-place so the draw closure reflects the new style, then triggers draw().
+     */
+    private updateSymbolCanvasMarkers;
+    /**
+     * Update the canvas symbol overlay for an adaptive marker layer by mutating
+     * the `canvasMarkers` array in-place (the canvas `draw()` closure captures
+     * the same array reference) and triggering an immediate redraw.
+     */
+    private updateAdaptiveCanvasMarkers;
+    private createMarkerForFeature;
+    private createClusterMarkerForFeature;
+    /**
+     * Create an AdvancedMarkerElement 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 a canvas-based OverlayView that draws all symbol markers in a
+     * single pass, replacing the per-element Data layer approach.
+     * For adaptive mode, DOM-rendered features are excluded (rendered as DOM overlays).
+     */
+    private setupCanvasSymbolOverlay;
+    /**
+     * Set up client-side clustering using @googlemaps/markerclusterer.
+     * Creates AdvancedMarkerElement instances for all point features and
+     * hands them to a MarkerClusterer which manages their visibility
+     * based on zoom level.
+     */
+    private setupClientClustering;
+    private pushToFeatureMap;
+    /**
+     * Re-apply all interaction-sensitive styles for every feature in the given
+     * shape source. Priority: selected > hovered > base.
+     *
+     * Called whenever hover, selection, or theme changes on the given handleId.
+     * When neither hover nor selection targets a feature, it reverts to its base style.
+     */
+    private applyGoogleShapeInteraction;
+    private createPolygon;
+    private createPolyline;
+    /**
+     * Fill-only polygon (no stroke) for ADR-0021 fill tiling: the fill comes from
+     * clipped geometry while the full outline is drawn separately as polylines.
+     * An optional `zIndex` controls the Google Maps rendering order for hover promotion.
+     */
+    private createFillOnlyPolygon;
+    /**
+     * Render a polygonal feature whose fill is tiled (ADR-0021): the visible
+     * outline is drawn from the feature's full geometry as polylines (so it stays
+     * complete through covering neighbours), and the fill is drawn from the
+     * clipped geometry as fill-only polygons. A fully covered loser yields no fill
+     * polygon — just its outline.
+     */
+    private renderTiledPolygonFeature;
+    /**
+     * Create invisible polylines tracing each ring of a polygon's paths.
+     * Used as hit targets for stroke-only interaction mode — Google natively
+     * shows pointer cursor on clickable polylines, giving correct cursor
+     * behaviour without manual hit-testing.
+     *
+     * `geodesic` must match the parent polygon so hit areas align with the
+     * visible stroke.
+     */
+    private createStrokeHitPolylines;
+    private createShapePointMarker;
+    private createRoutePolyline;
+    private attachMarkerInteractionListeners;
+    private attachClusterInteractionListeners;
+    private updateClusterMarkerEntity;
+    private attachShapeInteractionListeners;
+    private attachShapePointInteractionListeners;
+    private attachRouteInteractionListeners;
+    /**
+     * Attach a DOM-level dblclick listener on the map container.
+     * Google Maps overlay events suppress the second click and dblclick when
+     * disableDoubleClickZoom is true, so we rely on the browser's own dblclick
+     * on the container instead.
+     */
+    private setupMapClickListener;
+    private setupMapContainerDblClickListener;
+    /**
+     * On shape mousedown, temporarily hold native zoom disabled so the browser
+     * can complete its dblclick detection without the map moving the shape.
+     * Re-enables after the dblclick threshold elapses.
+     */
+    private holdNativeZoomForDblClick;
+    /**
+     * 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;
+    /**
+     * When the Google Maps instance is recreated (e.g. theme change), all
+     * existing Google Maps objects lose their reference to the old map.
+     * We need to re-create them on the new map.
+     *
+     * We collect the current source configs from tracked state and re-apply
+     * them. Since set*Source calls removeSource first, this cleanly replaces.
+     */
+    private reconnectAllSources;
+}

package/src/GoogleMapsRenderer.d.ts

@@ -0,0 +1,17 @@
+import { type AdapterRendererProps } from "@trackunit/react-map-adapter-shared";
+import { type ReactElement } from "react";
+/**
+ * Google Maps Renderer component
+ * Wraps the map with APIProvider. Loading/error UI is owned by `@trackunit/react-map` (`createMapComponent`);
+ * this module reports API load failure on the adapter and returns `null` until the script is loaded.
+ *
+ * Subscribes to the adapter's current theme via `useSyncExternalStore` so
+ * that when `setTheme()` is called, the component re-renders with the new
+ * `mapId` prop, causing `@vis.gl/react-google-maps` to create a fresh
+ * `google.maps.Map` instance styled with the correct cloud-based map style.
+ *
+ * When rendered inside an existing `APIProvider` (e.g. via `GoogleApiProvider`),
+ * the renderer skips creating its own `APIProvider`, sharing the Google Maps
+ * JS API context. Each map gets a unique `id` prop to avoid registry conflicts.
+ */
+export declare const GoogleMapsRenderer: (props: AdapterRendererProps) => ReactElement;

package/src/constants.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Google Cloud Map IDs for different themes
+ * These are configured in Google Cloud Console for custom styling
+ */
+export declare const GOOGLE_MAP_IDS: {
+    readonly light: "462dc96a2b3709ee";
+    readonly dark: "8676e1fb4a115a8a";
+};

package/src/google-maps.d.ts

@@ -0,0 +1,11 @@
+/**
+ * This library uses @types/google.maps (newer, maintained) instead of @types/googlemaps.
+ * This file is included only by react-map's tsconfig; the global Manager typings still use googlemaps.
+ */
+/// <reference types="google.maps" />
+
+declare global {
+  interface Window {
+    google: typeof google;
+  }
+}

package/src/googleMapsAdapter.d.ts

@@ -0,0 +1,39 @@
+import { type GoogleMapsConfig } from "./GoogleMapsAdapterInstance";
+/**
+ * Google Maps adapter factory
+ *
+ * Creates an adapter configuration for Google Maps that can be passed to useMap.
+ *
+ * @example
+ * ```tsx
+ * const map = useMap(googleMapsAdapter({
+ *   apiKey: process.env.GOOGLE_MAPS_API_KEY,
+ *   theme: "light",
+ *   language: "en",
+ * }));
+ *
+ * <map.Map className="h-full w-full">
+ *   {children}
+ * </map.Map>
+ * ```
+ */
+export declare const googleMapsAdapter: (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;
+}> & {
+    apiKey: string;
+    mapInstanceId?: 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;
+}> & {
+    apiKey: string;
+    mapInstanceId?: string;
+}>>;
+export type { GoogleMapsConfig };

package/src/googleTypeConverters.d.ts

@@ -0,0 +1,22 @@
+import type { GeoJsonBbox, GeoJsonPosition } from "@trackunit/react-map-adapter-shared";
+/**
+ * Convert GeoJSON Position [lng, lat] to Google Maps LatLngLiteral
+ */
+export declare const positionToLatLng: (position: Readonly<GeoJsonPosition>) => google.maps.LatLngLiteral;
+/**
+ * Convert Google Maps LatLng to GeoJSON Position [lng, lat]
+ * Uses Zod to distinguish between LatLngLiteral (plain object) and LatLng (class instance)
+ */
+export declare const latLngToPosition: (latLng: google.maps.LatLng | google.maps.LatLngLiteral) => GeoJsonPosition;
+/**
+ * Convert GeoJSON Bbox [minLon, minLat, maxLon, maxLat] to Google Maps LatLngBoundsLiteral
+ */
+export declare const bboxToLatLngBounds: (bbox: Readonly<GeoJsonBbox>) => google.maps.LatLngBoundsLiteral;
+/**
+ * Convert Google Maps LatLngBounds to GeoJSON Bbox [minLon, minLat, maxLon, maxLat]
+ */
+export declare const latLngBoundsToBbox: (bounds: google.maps.LatLngBounds) => GeoJsonBbox;
+/**
+ * Convert Google Maps LatLngBoundsLiteral to GeoJSON Bbox
+ */
+export declare const latLngBoundsLiteralToBbox: (bounds: google.maps.LatLngBoundsLiteral) => GeoJsonBbox;

package/src/index.d.ts

@@ -0,0 +1,4 @@
+export { GoogleApiProvider } from "./GoogleApiProvider";
+export { googleMapsAdapter, type GoogleMapsConfig } from "./googleMapsAdapter";
+export { GoogleMapsAdapterInstance } from "./GoogleMapsAdapterInstance";
+export { GoogleMapsRenderer } from "./GoogleMapsRenderer";