@maydon_tech/react-native-nitro-maps 0.1.0

package/ios/Providers/MapProviderProtocol.swift

@@ -0,0 +1,78 @@
+import Foundation
+import UIKit
+
+/// Protocol that all map providers must implement
+/// This allows the library to support multiple map backends (Google, Apple, Yandex)
+protocol MapProviderProtocol: AnyObject {
+  
+  // MARK: - View
+  
+  /// The underlying map view to be displayed
+  var mapView: UIView { get }
+  
+  // MARK: - Properties
+  
+  var initialRegion: Region? { get set }
+  var showsUserLocation: Bool? { get set }
+  var zoomEnabled: Bool? { get set }
+  var scrollEnabled: Bool? { get set }
+  var rotateEnabled: Bool? { get set }
+  var pitchEnabled: Bool? { get set }
+  var mapType: MapType? { get set }
+  var showsMyLocationButton: Bool? { get set }
+  var clusterConfig: ClusterConfig? { get set }
+  var customMapStyle: [MapStyleElement]? { get set }
+  var darkMode: Bool? { get set }
+  
+  // MARK: - Callbacks
+  
+  var onPress: ((MapPressEvent) -> Void)? { get set }
+  var onLongPress: ((MapPressEvent) -> Void)? { get set }
+  var onMapReady: (() -> Void)? { get set }
+  var onRegionChange: ((RegionChangeEvent) -> Void)? { get set }
+  var onRegionChangeComplete: ((RegionChangeEvent) -> Void)? { get set }
+  var onMarkerPress: ((MarkerPressEvent) -> Void)? { get set }
+  var onMarkerDragStart: ((MarkerDragEvent) -> Void)? { get set }
+  var onMarkerDrag: ((MarkerDragEvent) -> Void)? { get set }
+  var onMarkerDragEnd: ((MarkerDragEvent) -> Void)? { get set }
+  var onClusterPress: ((ClusterPressEvent) -> Void)? { get set }
+  var onError: ((MapError) -> Void)? { get set }
+  
+  // MARK: - Lifecycle
+  
+  func setup()
+  func updateSettings()
+  
+  // MARK: - Camera Methods
+  
+  func animateToRegion(_ region: Region, duration: Double?)
+  func fitToCoordinates(_ coordinates: [Coordinate], edgePadding: EdgePadding?, animated: Bool?)
+  func animateCamera(_ camera: Camera, duration: Double?)
+  func setCamera(_ camera: Camera)
+  func getCamera() -> Camera
+  func getMapBoundaries() -> MapBoundaries?
+  
+  // MARK: - Marker Management
+  
+  func addMarker(_ marker: MarkerData)
+  func addMarkers(_ markers: [MarkerData])
+  func updateMarker(_ marker: MarkerData)
+  func removeMarker(_ id: String)
+  func clearMarkers()
+  func selectMarker(_ id: String)
+  
+  // MARK: - Clustering
+  
+  func setClusteringEnabled(_ enabled: Bool)
+  func refreshClusters()
+  func performClustering()
+  
+  // MARK: - Map Style
+  
+  func setMapStyle(_ style: [MapStyleElement]?)
+  func setDarkMode(_ enabled: Bool)
+  
+  // MARK: - Region
+  
+  func getCurrentRegion() -> Region
+}

package/ios/Shared/ClusterConfig+Factory.swift

@@ -0,0 +1,58 @@
+import Foundation
+
+// MARK: - ClusterConfig Factory Extension
+
+extension ClusterConfig {
+  
+  /// Creates a copy with only the `enabled` field changed.
+  /// Eliminates boilerplate in each provider's `setClusteringEnabled()` (DRY).
+  static func withEnabled(
+    _ enabled: Bool,
+    existing: ClusterConfig?
+  ) -> ClusterConfig {
+    let strat: ClusterStrategy = existing?.strategy ?? .supercluster
+    let rad: Double = existing?.radius ?? 80
+    let minSize: Double = existing?.minimumClusterSize ?? 2
+    let mz: Double = existing?.maxZoom ?? 20
+    let bg: ColorValue = existing?.backgroundColor
+      ?? .second(MarkerColor(r: 0, g: 122, b: 255, a: 255))
+    let tc: ColorValue = existing?.textColor
+      ?? .second(MarkerColor(r: 255, g: 255, b: 255, a: 255))
+    let bw: Double = existing?.borderWidth ?? 2
+    let bc: ColorValue = existing?.borderColor
+      ?? .second(MarkerColor(r: 255, g: 255, b: 255, a: 255))
+    let anim: Bool = existing?.animatesClusters ?? true
+    let dur: Double = existing?.animationDuration ?? 0.3
+    let style: ClusterAnimationStyle = existing?.animationStyle ?? .default
+    let realtime: Bool = existing?.realtimeClustering ?? false
+    let vpPad: Double = existing?.renderBuffer ?? 0
+    let throttle: Double = existing?.throttleInterval ?? 150
+
+    return ClusterConfig(
+      enabled: enabled,
+      strategy: strat,
+      radius: rad,
+      minimumClusterSize: minSize,
+      maxZoom: mz,
+      backgroundColor: bg,
+      textColor: tc,
+      borderWidth: bw,
+      borderColor: bc,
+      animatesClusters: anim,
+      animationDuration: dur,
+      animationStyle: style,
+      realtimeClustering: realtime,
+      renderBuffer: vpPad,
+      throttleInterval: throttle
+    )
+  }
+}
+
+// MARK: - Cluster User Data
+
+/// User data attached to cluster markers for tap handling.
+/// Shared between NitroMap, GoogleMapDelegate, etc.
+struct ClusterUserData {
+  let markerIds: [String]
+  let count: Int
+}

package/ios/Shared/ClusteringManager.swift

@@ -0,0 +1,211 @@
+import Foundation
+import UIKit
+import CoreLocation
+
+// MARK: - Clustering Manager Protocol
+
+/// Protocol defining the clustering manager interface.
+/// Enables dependency injection and mocking for unit tests.
+///
+/// Usage:
+/// ```swift
+/// class GoogleMapProvider: MapProviderProtocol {
+///     private let clusteringManager: ClusteringManagerProtocol
+///
+///     init(clusteringManager: ClusteringManagerProtocol = ClusteringManager()) {
+///         self.clusteringManager = clusteringManager
+///     }
+/// }
+/// ```
+protocol ClusteringManagerProtocol: AnyObject {
+  
+  /// Current cluster configuration
+  var clusterConfig: ClusterConfig? { get set }
+  
+  /// Adds a marker to the clustering engine
+  func addMarker(_ marker: MarkerData)
+  
+  /// Removes a marker by ID
+  func removeMarker(_ id: String)
+  
+  /// Clears all markers from the engine
+  func clearMarkers()
+  
+  /// Clusters markers using bounds-based region
+  func cluster(
+    minLat: Double,
+    maxLat: Double,
+    minLon: Double,
+    maxLon: Double,
+    zoom: Double,
+    mapSize: CGSize
+  ) -> NitroClusterEngine.ClusteringResult
+  
+  
+  /// Executes a clustering action with debouncing to prevent rapid re-clustering
+  func debounce(_ action: @escaping () -> Void)
+  
+  /// Gets a cluster icon for the given count
+  func clusterIcon(forCount count: Int) -> UIImage?
+}
+
+// MARK: - Clustering Manager Implementation
+
+/// Production implementation of ClusteringManagerProtocol.
+/// Wraps the C++ NitroClusterEngine and provides a clean Swift interface.
+final class ClusteringManager: ClusteringManagerProtocol {
+  
+  // MARK: - Private Properties
+  
+  private let engine: NitroClusterEngine
+  private let iconGenerator: NitroClusterIconGenerator
+  private var debounceTimer: Timer?
+  private let debounceInterval: TimeInterval
+  
+  // MARK: - Protocol Properties
+  
+  var clusterConfig: ClusterConfig? {
+    didSet {
+      iconGenerator.updateConfig(clusterConfig)
+      if let config = clusterConfig {
+        engine.setClusterRadius(config.radius)
+        engine.setMinClusterSize(Int(config.minimumClusterSize))
+        engine.setMaxZoom(config.maxZoom)
+      }
+    }
+  }
+  
+  // MARK: - Initialization
+  
+  /// Creates a new clustering manager with default configuration
+  /// - Parameters:
+  ///   - clusterRadius: Radius for clustering in screen points (default: 80)
+  ///   - minClusterSize: Minimum markers to form a cluster (default: 2)
+  ///   - maxZoom: Maximum zoom level for clustering (default: 20)
+  ///   - debounceInterval: Debounce interval in seconds (default: 0.1)
+  init(
+    clusterRadius: Double = 80.0,
+    minClusterSize: Int = 2,
+    maxZoom: Double = 20.0,
+    debounceInterval: TimeInterval = 0.1
+  ) {
+    self.engine = NitroClusterEngine()
+    self.iconGenerator = NitroClusterIconGenerator()
+    self.debounceInterval = debounceInterval
+    
+    engine.setClusterRadius(clusterRadius)
+    engine.setMinClusterSize(minClusterSize)
+    engine.setMaxZoom(maxZoom)
+  }
+  
+  deinit {
+    debounceTimer?.invalidate()
+  }
+  
+  // MARK: - Marker Management
+  
+  func addMarker(_ marker: MarkerData) {
+    engine.addMarker(marker)
+  }
+  
+  func removeMarker(_ id: String) {
+    engine.removeMarker(id)
+  }
+  
+  func clearMarkers() {
+    engine.clearMarkers()
+  }
+  
+  // MARK: - Clustering
+  
+  func cluster(
+    minLat: Double,
+    maxLat: Double,
+    minLon: Double,
+    maxLon: Double,
+    zoom: Double,
+    mapSize: CGSize
+  ) -> NitroClusterEngine.ClusteringResult {
+    return engine.clusterWithBounds(
+      minLat: minLat,
+      maxLat: maxLat,
+      minLon: minLon,
+      maxLon: maxLon,
+      zoom: zoom,
+      mapSize: mapSize
+    )
+  }
+  
+  // MARK: - Debouncing
+  
+  func debounce(_ action: @escaping () -> Void) {
+    debounceTimer?.invalidate()
+    debounceTimer = Timer.scheduledTimer(
+      withTimeInterval: debounceInterval,
+      repeats: false
+    ) { _ in
+      action()
+    }
+  }
+  
+  // MARK: - Icon Generation
+  
+  func clusterIcon(forCount count: Int) -> UIImage? {
+    return iconGenerator.icon(forSize: UInt(count))
+  }
+}
+
+// MARK: - Mock for Unit Tests
+
+#if DEBUG
+/// Mock implementation for unit testing
+final class MockClusteringManager: ClusteringManagerProtocol {
+  
+  var clusterConfig: ClusterConfig?
+  
+  // Tracking for assertions
+  private(set) var addedMarkers: [MarkerData] = []
+  private(set) var removedMarkerIds: [String] = []
+  private(set) var clearMarkersCallCount = 0
+  private(set) var clusterCallCount = 0
+  
+  // Configurable return value
+  var mockClusterResult: NitroClusterEngine.ClusteringResult = NitroClusterEngine.ClusteringResult(
+    clusters: [],
+    singleMarkers: []
+  )
+  
+  func addMarker(_ marker: MarkerData) {
+    addedMarkers.append(marker)
+  }
+  
+  func removeMarker(_ id: String) {
+    removedMarkerIds.append(id)
+  }
+  
+  func clearMarkers() {
+    clearMarkersCallCount += 1
+    addedMarkers.removeAll()
+  }
+  
+  func cluster(
+    minLat: Double,
+    maxLat: Double,
+    minLon: Double,
+    maxLon: Double,
+    zoom: Double,
+    mapSize: CGSize
+  ) -> NitroClusterEngine.ClusteringResult {
+    clusterCallCount += 1
+    return mockClusterResult
+  }
+  
+  func debounce(_ action: @escaping () -> Void) {
+    action() // Execute immediately in tests
+  }
+  
+  func clusterIcon(forCount count: Int) -> UIImage? {
+    return nil
+  }
+}
+#endif

package/ios/Shared/MapStyleProvider.swift

@@ -0,0 +1,135 @@
+import Foundation
+import UIKit
+
+// MARK: - Map Style Protocol
+
+/// Protocol for map styling utilities.
+/// Provides zoom/altitude conversions and style constants.
+protocol MapStyleProviding {
+  
+  /// Converts lat/lon deltas to approximate zoom level
+  func zoomFromDeltas(latDelta: Double, lonDelta: Double) -> Double
+  
+  /// Converts zoom level to approximate altitude (meters)
+  func altitudeFromZoom(_ zoom: Double) -> Double
+  
+  /// Converts altitude to approximate zoom level
+  func zoomFromAltitude(_ altitude: Double) -> Double
+  
+  /// Gets the dark mode JSON style for Google Maps
+  var googleDarkModeStyle: String { get }
+}
+
+// MARK: - Implementation
+
+/// Production implementation of map styling utilities.
+/// All methods are pure functions - thread-safe and stateless.
+final class MapStyleProvider: MapStyleProviding {
+  
+  // MARK: - Singleton
+  
+  /// Shared instance for convenience (stateless, so safe to share)
+  static let shared = MapStyleProvider()
+  
+  // MARK: - Constants
+  
+  /// Earth's approximate circumference at equator in degrees
+  private let earthCircumferenceDegrees: Double = 360.0
+  
+  /// Approximate altitude at zoom level 0 (meters)
+  private let baseAltitude: Double = 40_000_000
+  
+  /// Maximum supported zoom level
+  private let maxZoom: Double = 21.0
+  
+  /// Minimum supported zoom level
+  private let minZoom: Double = 0.0
+  
+  // MARK: - Initialization
+  
+  init() {}
+  
+  // MARK: - MapStyleProviding
+  
+  func zoomFromDeltas(latDelta: Double, lonDelta: Double) -> Double {
+    let maxDelta = max(latDelta, lonDelta)
+    guard maxDelta > 0 else { return maxZoom }
+    
+    let zoom = log2(earthCircumferenceDegrees / maxDelta)
+    return clamp(zoom, min: minZoom, max: maxZoom)
+  }
+  
+  func altitudeFromZoom(_ zoom: Double) -> Double {
+    let clampedZoom = clamp(zoom, min: minZoom, max: maxZoom)
+    return baseAltitude / pow(2, clampedZoom)
+  }
+  
+  func zoomFromAltitude(_ altitude: Double) -> Double {
+    guard altitude > 0 else { return maxZoom }
+    
+    let zoom = log2(baseAltitude / altitude)
+    return clamp(zoom, min: minZoom, max: maxZoom)
+  }
+  
+  var googleDarkModeStyle: String {
+    return Self.darkModeJSON
+  }
+  
+  // MARK: - Private Helpers
+  
+  private func clamp(_ value: Double, min: Double, max: Double) -> Double {
+    return Swift.max(min, Swift.min(max, value))
+  }
+  
+  // MARK: - Dark Mode Style JSON
+  
+  private static let darkModeJSON = """
+  [
+    {"elementType": "geometry", "stylers": [{"color": "#242f3e"}]},
+    {"elementType": "labels.text.fill", "stylers": [{"color": "#746855"}]},
+    {"elementType": "labels.text.stroke", "stylers": [{"color": "#242f3e"}]},
+    {"featureType": "administrative.locality", "elementType": "labels.text.fill", "stylers": [{"color": "#d59563"}]},
+    {"featureType": "poi", "elementType": "labels.text.fill", "stylers": [{"color": "#d59563"}]},
+    {"featureType": "poi.park", "elementType": "geometry", "stylers": [{"color": "#263c3f"}]},
+    {"featureType": "poi.park", "elementType": "labels.text.fill", "stylers": [{"color": "#6b9a76"}]},
+    {"featureType": "road", "elementType": "geometry", "stylers": [{"color": "#38414e"}]},
+    {"featureType": "road", "elementType": "geometry.stroke", "stylers": [{"color": "#212a37"}]},
+    {"featureType": "road", "elementType": "labels.text.fill", "stylers": [{"color": "#9ca5b3"}]},
+    {"featureType": "road.highway", "elementType": "geometry", "stylers": [{"color": "#746855"}]},
+    {"featureType": "road.highway", "elementType": "geometry.stroke", "stylers": [{"color": "#1f2835"}]},
+    {"featureType": "road.highway", "elementType": "labels.text.fill", "stylers": [{"color": "#f3d19c"}]},
+    {"featureType": "transit", "elementType": "geometry", "stylers": [{"color": "#2f3948"}]},
+    {"featureType": "transit.station", "elementType": "labels.text.fill", "stylers": [{"color": "#d59563"}]},
+    {"featureType": "water", "elementType": "geometry", "stylers": [{"color": "#17263c"}]},
+    {"featureType": "water", "elementType": "labels.text.fill", "stylers": [{"color": "#515c6d"}]},
+    {"featureType": "water", "elementType": "labels.text.stroke", "stylers": [{"color": "#17263c"}]}
+  ]
+  """
+}
+
+// MARK: - Mock for Unit Tests
+
+#if DEBUG
+/// Mock implementation for unit testing
+final class MockMapStyleProvider: MapStyleProviding {
+  
+  var mockZoom: Double = 10.0
+  var mockAltitude: Double = 40000.0
+  
+  var googleDarkModeStyle: String {
+    return "[]" // Empty JSON for testing
+  }
+  
+  func zoomFromDeltas(latDelta: Double, lonDelta: Double) -> Double {
+    return mockZoom
+  }
+  
+  func altitudeFromZoom(_ zoom: Double) -> Double {
+    return mockAltitude
+  }
+  
+  func zoomFromAltitude(_ altitude: Double) -> Double {
+    return mockZoom
+  }
+}
+#endif

package/ios/Shared/MarkerSelectionHandler.swift

@@ -0,0 +1,116 @@
+import Foundation
+import UIKit
+
+// MARK: - Marker Selection Protocol
+
+/// Protocol for handling marker selection state changes.
+/// Enables dependency injection and clean separation of concerns.
+protocol MarkerSelectionHandling {
+  
+  /// Creates an updated MarkerData with the new selection state.
+  /// Returns nil if the marker type doesn't support visual selection (only priceMarker does).
+  ///
+  /// - Parameters:
+  ///   - markerData: The original marker data
+  ///   - selected: Whether the marker should be selected
+  /// - Returns: Updated marker data with new selection state, or nil if unsupported
+  func updateSelectionState(for markerData: MarkerData, selected: Bool) -> MarkerData?
+}
+
+// MARK: - Implementation
+
+/// Production implementation of marker selection handling.
+/// Thread-safe, pure function - can be used from any thread.
+final class MarkerSelectionHandler: MarkerSelectionHandling {
+  
+  // MARK: - Singleton
+  
+  /// Shared instance for convenience (stateless, so safe to share)
+  static let shared = MarkerSelectionHandler()
+  
+  // MARK: - Initialization
+  
+  init() {}
+  
+  // MARK: - MarkerSelectionHandling
+  
+  func updateSelectionState(for markerData: MarkerData, selected: Bool) -> MarkerData? {
+    // Only priceMarker style supports visual selection state
+    guard markerData.config.style == .pricemarker,
+          let priceConfig = markerData.config.priceMarker else {
+      return nil
+    }
+    
+    // Early exit if state hasn't changed
+    if priceConfig.selected == selected {
+      return nil
+    }
+    
+    // Create updated price config with new selection state
+    let updatedPriceConfig = PriceMarkerStyle(
+      price: priceConfig.price,
+      currency: priceConfig.currency,
+      selected: selected,
+      backgroundColor: priceConfig.backgroundColor,
+      selectedBackgroundColor: priceConfig.selectedBackgroundColor,
+      textColor: priceConfig.textColor,
+      selectedTextColor: priceConfig.selectedTextColor,
+      fontSize: priceConfig.fontSize,
+      paddingHorizontal: priceConfig.paddingHorizontal,
+      paddingVertical: priceConfig.paddingVertical,
+      shadowOpacity: priceConfig.shadowOpacity
+    )
+    
+    // Create updated config
+    let updatedConfig = MarkerConfig(
+      style: markerData.config.style,
+      image: markerData.config.image,
+      priceMarker: updatedPriceConfig
+    )
+    
+    // Return new marker data (immutable pattern)
+    return MarkerData(
+      id: markerData.id,
+      coordinate: markerData.coordinate,
+      title: markerData.title,
+      description: markerData.description,
+      draggable: markerData.draggable,
+      opacity: markerData.opacity,
+      rotation: markerData.rotation,
+      zIndex: markerData.zIndex,
+      anchor: markerData.anchor,
+      config: updatedConfig,
+      clusteringEnabled: markerData.clusteringEnabled,
+      animation: markerData.animation
+    )
+  }
+}
+
+// MARK: - Mock for Unit Tests
+
+#if DEBUG
+/// Mock implementation for unit testing
+final class MockMarkerSelectionHandler: MarkerSelectionHandling {
+  
+  // Tracking for assertions
+  private(set) var updateSelectionCallCount = 0
+  private(set) var lastMarkerData: MarkerData?
+  private(set) var lastSelectedValue: Bool?
+  
+  // Configurable behavior
+  var shouldReturnNil = false
+  
+  func updateSelectionState(for markerData: MarkerData, selected: Bool) -> MarkerData? {
+    updateSelectionCallCount += 1
+    lastMarkerData = markerData
+    lastSelectedValue = selected
+    
+    if shouldReturnNil {
+      return nil
+    }
+    
+    // Use real implementation for realistic behavior
+    return MarkerSelectionHandler.shared.updateSelectionState(for: markerData, selected: selected)
+  }
+}
+#endif

package/ios/Utils/ColorValueExtension.swift

@@ -0,0 +1,54 @@
+import Foundation
+import UIKit
+
+// MARK: - ColorValue Extension
+// Shared extension for converting ColorValue (hex string or MarkerColor) to MarkerColor
+extension ColorValue {
+  /// Extract MarkerColor from ColorValue, parsing hex string if needed
+  func toMarkerColor() -> MarkerColor {
+    switch self {
+    case .first(let hexString):
+      return ColorValue.parseHex(hexString)
+    case .second(let markerColor):
+      return markerColor
+    }
+  }
+
+  /// Parse hex color string to MarkerColor
+  private static func parseHex(_ hex: String) -> MarkerColor {
+    var hexSanitized = hex.trimmingCharacters(in: .whitespacesAndNewlines)
+    hexSanitized = hexSanitized.replacingOccurrences(of: "#", with: "")
+
+    var rgb: UInt64 = 0
+    Scanner(string: hexSanitized).scanHexInt64(&rgb)
+
+    let r, g, b: Double
+    if hexSanitized.count == 6 {
+      r = Double((rgb & 0xFF0000) >> 16)
+      g = Double((rgb & 0x00FF00) >> 8)
+      b = Double(rgb & 0x0000FF)
+    } else if hexSanitized.count == 3 {
+      r = Double((rgb & 0xF00) >> 8) * 17
+      g = Double((rgb & 0x0F0) >> 4) * 17
+      b = Double(rgb & 0x00F) * 17
+    } else {
+      r = 0; g = 0; b = 0
+    }
+
+    return MarkerColor(r: r, g: g, b: b, a: 255)
+  }
+}
+
+// MARK: - UIColor Helper
+extension ColorValue {
+  /// Convert ColorValue directly to UIColor
+  func toUIColor() -> UIColor {
+    let color = self.toMarkerColor()
+    return UIColor(
+      red: CGFloat(color.r) / 255,
+      green: CGFloat(color.g) / 255,
+      blue: CGFloat(color.b) / 255,
+      alpha: CGFloat(color.a) / 255
+    )
+  }
+}