@maydon_tech/react-native-nitro-maps 0.1.3 → 0.2.0

package/ios/Providers/Google/GoogleMapProvider+Clustering.swift

@@ -0,0 +1,541 @@
+import Foundation
+import GoogleMaps
+import GoogleMapsUtils
+import UIKit
+
+// MARK: - Clustering
+
+extension GoogleMapProvider {
+
+  /// A renderable item produced by the clustering pipeline.
+  /// Used by both `supercluster` and `hideOnOverlap` strategies.
+  struct RenderItem {
+    enum Kind {
+      case cluster(NitroClusterEngine.ClusterDataResult)
+      case single(markerId: String)
+    }
+    let coordinate: CLLocationCoordinate2D
+    let kind: Kind
+    let iconSize: CGSize
+    let priority: Int  // Higher = more important (clusters > singles)
+  }
+
+  // MARK: - Icon Load Notification
+
+  /// Listen for async icon load completion to update markers
+  func setupIconLoadNotification() {
+    NotificationCenter.default.addObserver(
+      self,
+      selector: #selector(handleIconLoaded(_:)),
+      name: GoogleMapProvider.markerIconLoadedNotification,
+      object: nil
+    )
+  }
+
+  @objc func handleIconLoaded(_ notification: Notification) {
+    guard notification.userInfo?["icon"] is UIImage else {
+      return
+    }
+
+    // The cache has already been updated, so just refresh visible markers
+    DispatchQueue.main.async { [weak self] in
+      self?.refreshVisibleMarkerIcons()
+    }
+  }
+
+  /// Refresh icons for visible markers (used after async icon load)
+  func refreshVisibleMarkerIcons() {
+    // Only refresh image-style markers as they use async loading
+    for (id, gmsMarker) in renderedSingleMarkers {
+      if let markerData = clusterableMarkerData[id],
+         markerData.config.style == MarkerStyle.image {
+        // Re-fetch icon from cache (now should have the loaded image)
+        if let icon = MarkerIconFactory.createIcon(for: markerData) {
+          gmsMarker.icon = icon
+        }
+      }
+    }
+
+    for (id, gmsMarker) in nonClusteredMarkers {
+      if let markerData = clusterableMarkerData[id],
+         markerData.config.style == MarkerStyle.image {
+        if let icon = MarkerIconFactory.createIcon(for: markerData) {
+          gmsMarker.icon = icon
+        }
+      }
+    }
+  }
+
+  // MARK: - Settings
+
+  func updateSettings() {
+    // Props are already applied via didSet. Just trigger clustering
+    // to reconcile any pending state.
+    performClustering()
+  }
+
+  // MARK: - Cluster Configuration
+
+  func updateClusterConfig() {
+    clusteringManager.clusterConfig = clusterConfig
+    performClustering()
+  }
+
+  // MARK: - Clustering Pipeline
+
+  /// Debounced clustering — fires after 100ms of silence (used on idle / config changes)
+  func performClustering() {
+    // FIX #4: Use the single debounce in ClusteringManager
+    // instead of a second timer here.
+    clusteringManager.debounce { [weak self] in
+      self?.performClusteringImmediate()
+    }
+  }
+
+  /// Throttled clustering — fires at most once per interval during continuous gestures.
+  /// Unlike debounce, throttle fires immediately then blocks subsequent calls for the interval.
+  func performClusteringThrottled() {
+    // If throttle timer is active, skip — we already have a pending call
+    guard throttleTimer == nil else { return }
+
+    // Fire immediately
+    performClusteringImmediate()
+
+    // Read interval from config (ms → seconds), default 150ms
+    let intervalMs = clusterConfig?.throttleInterval ?? 150
+    let intervalSec = intervalMs / 1000.0
+
+    // Block subsequent calls for the interval
+    throttleTimer = Timer.scheduledTimer(withTimeInterval: intervalSec, repeats: false) { [weak self] _ in
+      self?.throttleTimer = nil
+    }
+  }
+
+  // swiftlint:disable:next function_body_length
+  func performClusteringImmediate() {
+    guard gmsMapView.frame.size.width > 0 && gmsMapView.frame.size.height > 0
+    else {
+      return
+    }
+
+    let enabled = clusterConfig?.enabled ?? true
+    guard enabled else {
+      clearRenderedMarkersToPool()
+      renderAllMarkersIndividually()
+      return
+    }
+
+    // --- Phase 1: Spatial grouping (C++ Supercluster engine) ---
+    let visibleRegion = gmsMapView.projection.visibleRegion()
+    let zoom = gmsMapView.camera.zoom
+    let mapSize = gmsMapView.frame.size
+
+    let bounds = GMSCoordinateBounds(region: visibleRegion)
+
+    // Expand bounds by renderBuffer (fraction of viewport size)
+    let padding = clusterConfig?.renderBuffer ?? 0
+    let latSpan = bounds.northEast.latitude - bounds.southWest.latitude
+    let lonSpan = bounds.northEast.longitude - bounds.southWest.longitude
+    let queryMinLat = bounds.southWest.latitude - latSpan * padding
+    let queryMaxLat = bounds.northEast.latitude + latSpan * padding
+    let queryMinLon = bounds.southWest.longitude - lonSpan * padding
+    let queryMaxLon = bounds.northEast.longitude + lonSpan * padding
+
+    let result = clusteringManager.cluster(
+      minLat: queryMinLat,
+      maxLat: queryMaxLat,
+      minLon: queryMinLon,
+      maxLon: queryMaxLon,
+      zoom: Double(zoom),
+      mapSize: mapSize
+    )
+
+    let minClusterSize = Int(clusterConfig?.minimumClusterSize ?? 2)
+    let strategy = clusterConfig?.strategy ?? .supercluster
+
+    // Build the actual visible polygon from the 4 corners of the rotated viewport.
+    // When bearing ≠ 0, the axis-aligned GMSCoordinateBounds is larger than the
+    // actual visible area. Filter results against this polygon to exclude markers
+    // in the "corner excess" of the bounding box.
+    let bearing = gmsMapView.camera.bearing
+    let isRotated = bearing.truncatingRemainder(dividingBy: 360.0) != 0.0
+    let visiblePolygon: [CLLocationCoordinate2D]? = isRotated ? expandPolygon([
+      visibleRegion.nearLeft,
+      visibleRegion.nearRight,
+      visibleRegion.farRight,
+      visibleRegion.farLeft
+    ], fraction: padding) : nil
+
+    // --- Phase 2: Build renderable items from engine output ---
+    var renderItems: [RenderItem] = []
+    renderItems.reserveCapacity(result.clusters.count + result.singleMarkers.count)
+
+    // Process clusters
+    for cluster in result.clusters {
+      // When rotated, filter out clusters outside the actual visible polygon
+      if let poly = visiblePolygon,
+         !pointInConvexQuad(lat: cluster.coordinate.latitude, lon: cluster.coordinate.longitude, quad: poly) {
+        continue
+      }
+
+      let containsSelected = selectedMarkerId != nil && cluster.markerIds.contains(selectedMarkerId!)
+      let adjustedCount = containsSelected ? cluster.count - 1 : cluster.count
+      guard adjustedCount >= minClusterSize else { continue }
+
+      let adjustedCluster = containsSelected
+        ? NitroClusterEngine.ClusterDataResult(
+            coordinate: cluster.coordinate,
+            markerIds: cluster.markerIds.filter { $0 != selectedMarkerId },
+            count: adjustedCount,
+            iconSize: cluster.iconSize
+          )
+        : cluster
+
+      let icon = clusteringManager.clusterIcon(forCount: adjustedCount)
+      let size = icon?.size ?? CGSize(width: 44, height: 44)
+
+      renderItems.append(RenderItem(
+        coordinate: cluster.coordinate,
+        kind: .cluster(adjustedCluster),
+        iconSize: size,
+        priority: adjustedCount + 10000
+      ))
+    }
+
+    // Process single markers
+    for single in result.singleMarkers {
+      // When rotated, filter out singles outside the actual visible polygon
+      if let poly = visiblePolygon,
+         !pointInConvexQuad(lat: single.latitude, lon: single.longitude, quad: poly) {
+        continue
+      }
+
+      let id = single.markerId
+      if id == selectedMarkerId { continue }
+      if nonClusteredMarkers[id] != nil { continue }
+      guard let data = clusterableMarkerData[id] else { continue }
+
+      let icon = MarkerIconFactory.createIcon(for: data)
+      let size = icon?.size ?? CGSize(width: 27, height: 43)
+
+      renderItems.append(RenderItem(
+        coordinate: CLLocationCoordinate2D(
+          latitude: single.latitude,
+          longitude: single.longitude
+        ),
+        kind: .single(markerId: id),
+        iconSize: size,
+        priority: 0
+      ))
+    }
+
+    // --- Phase 2b: Apply strategy ---
+    var visibleItems = renderItems
+
+    if strategy == .hideonoverlap {
+      visibleItems = resolveOverlaps(
+        items: renderItems,
+        zoom: Double(zoom),
+        mapWidth: mapSize.width
+      )
+    }
+    // For .supercluster strategy: render all items as-is (overlaps tolerated)
+
+    // --- Phase 3: Render — add new markers BEFORE removing old ones ---
+    // This prevents the visual flash that occurs when markers are destroyed
+    // then recreated. By adding first, the map is never empty.
+    let isFirstRender = renderedClusterMarkers.isEmpty && renderedSingleMarkers.isEmpty
+
+    // Stash old markers for removal after new ones are on the map
+    let oldClusterMarkers = renderedClusterMarkers
+    let oldSingleMarkers = renderedSingleMarkers
+    renderedClusterMarkers = []
+    renderedSingleMarkers = [:]
+
+    // Preserve selected marker reference — it was excluded from the clustering
+    // engine, so it won't appear in the clustering output. Keep its GMSMarker
+    // in the dictionary so deselectCurrentMarker() can find it later.
+    if let selectedId = selectedMarkerId, let selectedMarker = oldSingleMarkers[selectedId] {
+      renderedSingleMarkers[selectedId] = selectedMarker
+    }
+
+    // Restore previously hidden non-clustered markers
+    for id in hiddenNonClusteredIds {
+      nonClusteredMarkers[id]?.map = gmsMapView
+    }
+    hiddenNonClusteredIds.removeAll()
+
+    // Render new items (add to map)
+    for (renderIndex, item) in visibleItems.enumerated() {
+      switch item.kind {
+      case .cluster(let clusterData):
+        let marker = GMSMarker()
+        marker.position = clusterData.coordinate
+        marker.groundAnchor = CGPoint(x: 0.5, y: 0.5)
+
+        if let icon = clusteringManager.clusterIcon(forCount: clusterData.count) {
+          marker.icon = icon
+        }
+
+        marker.userData = ClusterUserData(
+          markerIds: clusterData.markerIds,
+          count: clusterData.count
+        )
+
+        // Accessibility: announce cluster count to screen readers
+        marker.accessibilityLabel = "Cluster of \(clusterData.count) markers"
+
+        // Larger clusters render on top for consistent visual ordering
+        marker.zIndex = Int32(clusterData.count + 1000)
+
+        // Animate cluster icons when animatesClusters is enabled.
+        // Only animate when cluster structure actually changes:
+        // - First render (markers just appeared)
+        // - Zoom level changed (clusters restructure)
+        // - Markers added/removed (clusteringDirty)
+        // Skip on pure pan at same zoom (same clusters, just repositioned).
+        let zoomChanged = floor(zoom) != floor(lastClusteredZoom)
+        let structureChanged = isFirstRender || zoomChanged || clusteringDirty
+        let animateOnReappear = clusterConfig?.animateOnReappear ?? true
+        let shouldAnimate = (clusterConfig?.animatesClusters ?? true)
+          && (isFirstRender || (animateOnReappear && structureChanged))
+        if shouldAnimate {
+          applyClusterAnimation(marker)
+        }
+
+        marker.map = gmsMapView
+        renderedClusterMarkers.append(marker)
+
+      case .single(let markerId):
+        guard let data = clusterableMarkerData[markerId] else { continue }
+        // Reuse the existing GMSMarker if this markerId was already rendered.
+        // Skip full property update — the marker already has correct props
+        // from updateMarkerInPlace(). Only zIndex (render order) changes
+        // between clustering cycles. Re-setting icon was causing flicker
+        // on every camera idle (e.g. during user location tracking).
+        if let existing = oldSingleMarkers[markerId] {
+          existing.zIndex = Int32(renderIndex)
+          renderedSingleMarkers[markerId] = existing
+        } else {
+          let marker = GMSMarker()
+          configureGMSMarker(marker, from: data)
+          // Suppress appear animation in clustering pipeline when animateOnReappear is false
+          if !data.animateOnReappear {
+            marker.appearAnimation = .none
+          }
+          marker.zIndex = Int32(renderIndex)
+          marker.map = gmsMapView
+          renderedSingleMarkers[markerId] = marker
+        }
+      }
+    }
+
+    // NOW remove old markers (after new ones are visible)
+    for marker in oldClusterMarkers {
+      marker.map = nil
+    }
+    for (id, marker) in oldSingleMarkers {
+      // Skip markers that were reused in the new render
+      if renderedSingleMarkers[id] != nil { continue }
+      // Preserve the selected marker — excluded from clustering
+      if id == selectedMarkerId { continue }
+      marker.map = nil
+    }
+
+    // Handle non-clustered markers with hideOnOverlap
+    if strategy == .hideonoverlap {
+      hideOverlappingNonClusteredMarkers(
+        visibleItems: visibleItems,
+        zoom: Double(zoom),
+        mapWidth: mapSize.width
+      )
+    }
+
+    // Track state for next cycle's animation decisions
+    lastClusteredZoom = zoom
+    clusteringDirty = false
+
+  }
+
+  // MARK: - Overlap Resolution (hideOnOverlap strategy)
+
+  /// Removes lower-priority items that visually overlap higher-priority items.
+  /// Uses Mercator projection math — no GMSProjection dependency.
+  func resolveOverlaps(
+    items: [RenderItem],
+    zoom: Double,
+    mapWidth: CGFloat
+  ) -> [RenderItem] {
+    let sorted = items.sorted { $0.priority > $1.priority }
+    var visible: [RenderItem] = []
+    visible.reserveCapacity(sorted.count)
+
+    let worldSize = 256.0 * pow(2.0, zoom)
+
+    for item in sorted {
+      var hasOverlap = false
+      for existing in visible {
+        if itemsOverlap(item, existing, worldSize: worldSize) {
+          hasOverlap = true
+          break
+        }
+      }
+      if !hasOverlap {
+        visible.append(item)
+      }
+    }
+
+    return visible
+  }
+
+  /// Hides non-clustered markers that overlap with already-rendered items.
+  func hideOverlappingNonClusteredMarkers(
+    visibleItems: [RenderItem],
+    zoom: Double,
+    mapWidth: CGFloat
+  ) {
+    let worldSize = 256.0 * pow(2.0, zoom)
+
+    for (id, ncMarker) in nonClusteredMarkers {
+      let data = clusterableMarkerData[id]
+      let icon = data.flatMap { MarkerIconFactory.createIcon(for: $0) }
+      let size = icon?.size ?? CGSize(width: Self.defaultMarkerSize, height: Self.defaultMarkerSize)
+
+      let ncItem = RenderItem(
+        coordinate: ncMarker.position,
+        kind: .single(markerId: id),
+        iconSize: size,
+        priority: 0
+      )
+
+      var hasOverlap = false
+      for existing in visibleItems {
+        if itemsOverlap(ncItem, existing, worldSize: worldSize) {
+          hasOverlap = true
+          break
+        }
+      }
+
+      if hasOverlap {
+        ncMarker.map = nil
+        hiddenNonClusteredIds.insert(id)
+      }
+    }
+  }
+
+  /// Checks if two render items overlap in screen space using Mercator projection.
+  func itemsOverlap(_ a: RenderItem, _ b: RenderItem, worldSize: Double) -> Bool {
+    let dx: Double = mercatorX(a.coordinate.longitude, worldSize: worldSize)
+                   - mercatorX(b.coordinate.longitude, worldSize: worldSize)
+    let dy: Double = mercatorY(a.coordinate.latitude, worldSize: worldSize)
+                   - mercatorY(b.coordinate.latitude, worldSize: worldSize)
+    let minSepX: Double = Double(a.iconSize.width + b.iconSize.width) / 2.0
+    let minSepY: Double = Double(a.iconSize.height + b.iconSize.height) / 2.0
+    return Swift.abs(dx) < minSepX && Swift.abs(dy) < minSepY
+  }
+
+  // MARK: - Mercator Math Helpers
+
+  func mercatorX(_ longitude: Double, worldSize: Double) -> Double {
+    return (longitude + 180.0) / 360.0 * worldSize
+  }
+
+  func mercatorY(_ latitude: Double, worldSize: Double) -> Double {
+    let latRad = latitude * .pi / 180.0
+    return (1.0 - log(tan(latRad) + 1.0 / cos(latRad)) / .pi) / 2.0 * worldSize
+  }
+
+  // MARK: - Marker Pool Management
+
+  func clearRenderedMarkersToPool() {
+    for marker in renderedClusterMarkers {
+      marker.map = nil
+    }
+    renderedClusterMarkers.removeAll()
+
+    for (id, marker) in renderedSingleMarkers {
+      // Preserve the selected marker — it's excluded from clustering
+      // and must keep its GMSMarker object alive for the info window.
+      if id == selectedMarkerId { continue }
+      marker.map = nil
+    }
+    // Keep only the selected marker in the dictionary
+    if let selectedId = selectedMarkerId, let selectedMarker = renderedSingleMarkers[selectedId] {
+      renderedSingleMarkers.removeAll()
+      renderedSingleMarkers[selectedId] = selectedMarker
+    } else {
+      renderedSingleMarkers.removeAll()
+    }
+  }
+
+  func renderAllMarkersIndividually() {
+    for (_, markerData) in clusterableMarkerData {
+      if renderedSingleMarkers[markerData.id] == nil {
+        let marker = GMSMarker()
+        configureGMSMarker(marker, from: markerData)
+        marker.map = gmsMapView
+        renderedSingleMarkers[markerData.id] = marker
+      }
+    }
+  }
+
+  // MARK: - Clustering Control
+
+  func setClusteringEnabled(_ enabled: Bool) {
+    self.clusterConfig = ClusterConfig.withEnabled(enabled, existing: clusterConfig)
+    performClustering()
+  }
+
+  func refreshClusters() {
+    performClustering()
+  }
+
+  // MARK: - Viewport Polygon Helpers (rotation-aware visibility)
+
+  /// Point-in-convex-quadrilateral test using cross products.
+  /// Returns true if (lat, lon) is inside the quadrilateral.
+  /// For a convex polygon, a point is inside if it's on the same side of all edges.
+  private func pointInConvexQuad(
+    lat: Double, lon: Double,
+    quad: [CLLocationCoordinate2D]
+  ) -> Bool {
+    let n = quad.count
+    var positive = 0
+    var negative = 0
+
+    for i in 0..<n {
+      let x1 = quad[i].longitude
+      let y1 = quad[i].latitude
+      let x2 = quad[(i + 1) % n].longitude
+      let y2 = quad[(i + 1) % n].latitude
+
+      let cross = (x2 - x1) * (lat - y1) - (y2 - y1) * (lon - x1)
+
+      if cross > 0 { positive += 1 }
+      else if cross < 0 { negative += 1 }
+
+      if positive > 0 && negative > 0 { return false }
+    }
+    return true
+  }
+
+  /// Expands a convex polygon outward from its centroid by a fraction.
+  /// Used to account for renderBuffer so markers near viewport edges
+  /// aren't clipped prematurely.
+  private func expandPolygon(
+    _ polygon: [CLLocationCoordinate2D],
+    fraction: Double
+  ) -> [CLLocationCoordinate2D] {
+    guard fraction > 0 else { return polygon }
+
+    let cLat = polygon.reduce(0.0) { $0 + $1.latitude } / Double(polygon.count)
+    let cLon = polygon.reduce(0.0) { $0 + $1.longitude } / Double(polygon.count)
+
+    return polygon.map { p in
+      CLLocationCoordinate2D(
+        latitude: cLat + (p.latitude - cLat) * (1.0 + fraction),
+        longitude: cLon + (p.longitude - cLon) * (1.0 + fraction)
+      )
+    }
+  }
+}