refactor(ios): introduce RNMBXMapAndMapViewComponent protocol for type-safe mapView access

This commit addresses the issue raised in PR #3963 regarding the optional
mapView property access pattern that could lead to nil access crashes.

Key Changes:
- Created new RNMBXMapAndMapViewComponent protocol that guarantees non-nil
  MapView parameter in addToMap and removeFromMap methods
- Kept existing RNMBXMapComponent protocol for components that don't require
  direct MapView access
- Updated RNMBXMapView to handle both protocol types and validate mapView
  presence before calling RNMBXMapAndMapViewComponent methods
- Created RNMBXMapAndMapViewComponentBase as a base class for components
  requiring MapView

Components migrated to RNMBXMapAndMapViewComponent:
- RNMBXCustomLocationProvider: Needs mapView for location provider setup
- RNMBXCamera: Accesses mapView.viewport for status observers
- RNMBXViewport: Directly manages viewport state
- RNMBXNativeUserLocation: Configures location puck via mapView.location
- RNMBXInteractiveElement: Base class that accesses mapView.mapboxMap.style
- RNMBXSource: Manages sources via mapView.mapboxMap.style
- RNMBXPointAnnotation: Inherits from RNMBXInteractiveElement

Architecture Benefits:
- Type system enforces mapView availability at compile time
- Clear contract: components explicitly declare mapView requirement
- Eliminates defensive nil checks in component implementations
- Centralizes nil checking in RNMBXMapView with proper error logging
- Maintains invariant: if addedToMap is true, mapView must be non-nil

This approach is superior to PR #3963's defensive nil checks because:
1. It makes the requirement explicit via protocol
2. Failures are logged at the framework level, not silently ignored
3. Type safety prevents accidental nil access
4. Components can safely assume mapView is valid in lifecycle methods

Related: #3963

Author: claude

ios/RNMBX/RNMBXCamera.swift

@@ -18,7 +18,17 @@ public enum RemovalReason {
 public protocol RNMBXMapComponent: AnyObject {
   func addToMap(_ map: RNMBXMapView, style: Style)
   func removeFromMap(_ map: RNMBXMapView, reason: RemovalReason) -> Bool
-  
+
+  func waitForStyleLoad() -> Bool
+}
+
+/// Protocol for components that require a valid MapView instance for both add and remove operations.
+/// Use this protocol when your component needs to interact with the native MapView directly.
+/// The MapView parameter is guaranteed to be non-nil when these methods are called.
+public protocol RNMBXMapAndMapViewComponent: AnyObject {
+  func addToMap(_ map: RNMBXMapView, mapView: MapView, style: Style)
+  func removeFromMap(_ map: RNMBXMapView, mapView: MapView, reason: RemovalReason) -> Bool
+
   func waitForStyleLoad() -> Bool
 }
 
@@ -85,7 +95,7 @@ class CameraUpdateQueue {
 open class RNMBXMapComponentBase : UIView, RNMBXMapComponent {
   private weak var _map: RNMBXMapView! = nil
   private var _mapCallbacks: [(RNMBXMapView) -> Void] = []
-  
+
   weak var map : RNMBXMapView? {
     return _map;
   }
@@ -103,28 +113,70 @@ open class RNMBXMapComponentBase : UIView, RNMBXMapComponent {
       _mapCallbacks.append(callback)
     }
   }
-  
+
   public func waitForStyleLoad() -> Bool {
     return false
   }
-  
+
   public func addToMap(_ map: RNMBXMapView, style: Style) {
     _mapCallbacks.forEach { callback in
         callback(map)
     }
     _mapCallbacks = []
     _map = map
   }
-  
+
   public func removeFromMap(_ map: RNMBXMapView, reason: RemovalReason) -> Bool {
     _mapCallbacks = []
     _map = nil
     return true
   }
 }
 
+/// Base class for components that require MapView to be non-nil
+open class RNMBXMapAndMapViewComponentBase : UIView, RNMBXMapAndMapViewComponent {
+  private weak var _map: RNMBXMapView! = nil
+  private var _mapCallbacks: [(RNMBXMapView) -> Void] = []
+
+  weak var map : RNMBXMapView? {
+    return _map;
+  }
+
+  func withMapView(_ callback: @escaping (_ mapView: MapView) -> Void) {
+    withRNMBXMapView { mapView in
+      callback(mapView.mapView)
+    }
+  }
+
+  func withRNMBXMapView(_ callback: @escaping (_ map: RNMBXMapView) -> Void) {
+    if let map = _map {
+      callback(map)
+    } else {
+      _mapCallbacks.append(callback)
+    }
+  }
+
+  public func waitForStyleLoad() -> Bool {
+    return false
+  }
+
+  public func addToMap(_ map: RNMBXMapView, mapView: MapView, style: Style) {
+    _mapCallbacks.forEach { callback in
+        callback(map)
+    }
+    _mapCallbacks = []
+    _map = map
+  }
+
+  public func removeFromMap(_ map: RNMBXMapView, mapView: MapView, reason: RemovalReason) -> Bool {
+    _mapCallbacks = []
+    _map = nil
+    return true
+  }
+}
+
 @objc(RNMBXCamera)
-open class RNMBXCamera : RNMBXMapComponentBase {
+open class RNMBXCamera : RNMBXMapAndMapViewComponentBase {
   var cameraAnimator: BasicCameraAnimator?
   let cameraUpdateQueue = CameraUpdateQueue()
 
@@ -519,18 +571,18 @@ open class RNMBXCamera : RNMBXMapComponentBase {
     _updateCamera()
   }
 
-  public override func addToMap(_ map: RNMBXMapView, style: Style) {
-    super.addToMap(map, style: style)
+  public override func addToMap(_ map: RNMBXMapView, mapView: MapView, style: Style) {
+    super.addToMap(map, mapView: mapView, style: style)
     map.reactCamera = self
   }
-  
-  public override func removeFromMap(_ map: RNMBXMapView, reason: RemovalReason) -> Bool {
+
+  public override func removeFromMap(_ map: RNMBXMapView, mapView: MapView, reason: RemovalReason) -> Bool {
     if (reason == .StyleChange) {
       return false
     }
 
-    map.mapView.viewport.removeStatusObserver(self)
-    return super.removeFromMap(map, reason:reason)
+    mapView.viewport.removeStatusObserver(self)
+    return super.removeFromMap(map, mapView: mapView, reason: reason)
   }
 
   @objc public func moveBy(x: Double, y: Double, animationMode: NSNumber?, animationDuration: NSNumber?, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {

ios/RNMBX/RNMBXCustomLocationProvider.swift

@@ -3,70 +3,66 @@ import MapboxMaps
 let TAG = "RNMBXCustomLocationProvider"
 
 @objc
-public class RNMBXCustomLocationProvider: UIView, RNMBXMapComponent {
+public class RNMBXCustomLocationProvider: UIView, RNMBXMapAndMapViewComponent {
   var map: RNMBXMapView? = nil
-  
+
   let changes : PropertyChanges<RNMBXCustomLocationProvider> = PropertyChanges()
-  
+
   enum Property: String {
     case coordinate
     case heading
-    
+
     func apply(locationProvider: RNMBXCustomLocationProvider) {
       switch self {
         case .coordinate: locationProvider.applyCoordinate()
         case .heading: locationProvider.applyHeading()
       }
     }
   }
-  
+
   @objc
   public var coordinate: [Double] = [] {
     didSet { changed(.coordinate) }
   }
-    
+
   @objc
   public var heading: NSNumber = 0.0 {
     didSet { changed(.heading) }
   }
-  
+
   func changed(_ property: Property) {
     changes.add(name: property.rawValue, update: property.apply)
   }
-  
+
   @objc
   override public func didSetProps(_ props: [String]) {
     if customLocationProvider != nil {
       changes.apply(self)
     }
   }
-  
+
   var customLocationProvider: CustomLocationProvider? = nil
   #if RNMBX_11
   #else
   var defaultLocationProvider: LocationProvider?
   #endif
 
-  public func addToMap(_ map: RNMBXMapView, style: Style) {
+  public func addToMap(_ map: RNMBXMapView, mapView: MapView, style: Style) {
     self.map = map
-    if let mapView = map.mapView {
-      installCustomeLocationProviderIfNeeded(mapView: mapView)
-      changes.apply(self)
-    }
+    installCustomeLocationProviderIfNeeded(mapView: mapView)
+    changes.apply(self)
   }
-  
+
   private func applyCoordinate() {
     updateCoordinate(latitude: coordinate[1], longitude: coordinate[0])
   }
-  
+
   private func applyHeading() {
     updateHeading(heading: heading.doubleValue)
   }
-  
-  public func removeFromMap(_ map: RNMBXMapView, reason: RemovalReason) -> Bool {
-    if let mapView = map.mapView {
-      removeCustomLocationProvider(mapView: mapView)
-    }
+
+  public func removeFromMap(_ map: RNMBXMapView, mapView: MapView, reason: RemovalReason) -> Bool {
+    removeCustomLocationProvider(mapView: mapView)
     self.map = nil
     return true
   }

ios/RNMBX/RNMBXInteractiveElement.swift

@@ -1,63 +1,70 @@
 import MapboxMaps
 
 @objc
-public class RNMBXInteractiveElement : UIView, RNMBXMapComponent {
+public class RNMBXInteractiveElement : UIView, RNMBXMapAndMapViewComponent {
   weak var map : RNMBXMapView? = nil
+  weak var mapView : MapView? = nil
 
   static let hitboxDefault = 44.0
 
   @objc public var draggable: Bool = false
-  
+
   @objc public var hasPressListener: Bool = false
-  
+
   @objc public var hitbox : [String:NSNumber] = [
     "width": NSNumber(value: hitboxDefault),
     "height": NSNumber(value: hitboxDefault)
   ]
-  
+
   @objc public var id: String! = nil {
     willSet {
       if id != nil && newValue != id {
         Logger.log(level:.warn, message: "Changing id from: \(optional: id) to \(optional: newValue), changing of id is not supported")
-        if let map = map { removeFromMap(map, reason: .ComponentChange) }
+        if let map = map, let mapView = mapView {
+          removeFromMap(map, mapView: mapView, reason: .ComponentChange)
+        }
       }
     }
     didSet {
       if oldValue != nil && oldValue != id {
-        if let map = map { addToMap(map, style: map.mapboxMap.style) }
+        if let map = map, let mapView = mapView {
+          addToMap(map, mapView: mapView, style: mapView.mapboxMap.style)
+        }
       }
     }
   }
-  
+
   @objc public var onDragStart: RCTBubblingEventBlock? = nil
-  
+
   @objc public var onPress: RCTBubblingEventBlock? = nil
-  
+
   func getLayerIDs() -> [String] {
     return []
   }
 
   func isDraggable() -> Bool {
     return draggable
   }
-  
+
   func isTouchable() -> Bool {
     return hasPressListener
   }
-  
-  // MARK: - RNMBXMapComponent
-  public func addToMap(_ map: RNMBXMapView, style: Style) {
+
+  // MARK: - RNMBXMapAndMapViewComponent
+  public func addToMap(_ map: RNMBXMapView, mapView: MapView, style: Style) {
     if (self.id == nil) {
       Logger.log(level: .error, message: "id is required on \(self) but not specified")
     }
     self.map = map
+    self.mapView = mapView
   }
 
-  public func removeFromMap(_ map: RNMBXMapView, reason: RemovalReason) -> Bool {
+  public func removeFromMap(_ map: RNMBXMapView, mapView: MapView, reason: RemovalReason) -> Bool {
     self.map = nil
+    self.mapView = nil
     return true
   }
-  
+
   public func waitForStyleLoad() -> Bool {
     return true
   }