refactor(iOS): null safety for mapView addToMap, removeFromMap (#4079)

* 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

* refactor(ios): improve protocol hierarchy with inheritance and default implementations

Refinements to the RNMBXMapComponent protocol architecture:

1. Extracted common protocol requirement into base protocol:
   - Created RNMBXMapComponentProtocol with waitForStyleLoad() method
   - Both RNMBXMapComponent and RNMBXMapAndMapViewComponent inherit from it
   - Eliminates duplication of waitForStyleLoad() in both protocols

2. Added default implementation via Swift protocol extension:
   - RNMBXMapComponentProtocol extension provides default waitForStyleLoad() -> false
   - Components that need style load can override, others use default
   - Removed redundant implementations from:
     * RNMBXMapComponentBase
     * RNMBXMapAndMapViewComponentBase
     * RNMBXCustomLocationProvider
     * RNMBXImages

Benefits:
- DRY: Single definition of waitForStyleLoad() requirement
- Convenience: Default implementation reduces boilerplate
- Clarity: Explicit protocol inheritance shows relationship
- Type safety: Compiler enforces common interface

This follows Swift best practices for protocol-oriented programming.

* refactor(ios): make RNMBXMapAndMapViewComponent inherit from RNMBXMapComponent

Changed RNMBXMapAndMapViewComponent to inherit from RNMBXMapComponent instead
of RNMBXMapComponentProtocol, establishing a proper subtype relationship.

Key Changes:
1. Protocol Inheritance:
   - RNMBXMapAndMapViewComponent now extends RNMBXMapComponent
   - This makes semantic sense: "a component that needs MapView IS A map component"
   - Ensures compatibility with existing code that checks for RNMBXMapComponent

2. Default Implementation Safety Guard:
   - Added protocol extension with default implementations of base protocol methods
   - These implementations log errors and trigger assertions if called
   - Forces developers to use the mapView-aware versions
   - Catches mistakes at runtime (or compile time in debug builds)

3. Updated RNMBXSource to Handle Both Protocols:
   - Changed components array type to RNMBXMapComponentProtocol (base protocol)
   - Check for more specific protocol first (RNMBXMapAndMapViewComponent)
   - Then fallback to RNMBXMapComponent for components that don't need mapView
   - Applied this pattern to insertReactSubviewInternal, removeReactSubviewInternal,
     addToMap, and removeFromMap methods

Benefits:
- Type system correctly models the relationship (MapAndMapViewComponent IS A MapComponent)
- Existing code that checks "as? RNMBXMapComponent" still works (matches both types)
- Safety: Can't accidentally call wrong method signature due to default implementations
- Future-proof: New code can store both types in arrays typed as RNMBXMapComponent

RNMBXMapView already checks for the more specific protocol first, so no changes
needed there - the inheritance makes the code more correct without breaking anything.

* ios: build fix

* Update ios/RNMBX/RNMBXCamera.swift

* Update ios/RNMBX/RNMBXCamera.swift

* Update ios/RNMBX/RNMBXCamera.swift

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: mfazekas

ios/RNMBX/RNMBXCamera.swift

@@ -15,11 +15,46 @@ public enum RemovalReason {
     case ViewRemoval, StyleChange, OnDestroy, ComponentChange, Reorder
 }
 
-public protocol RNMBXMapComponent: AnyObject {
+/// Base protocol for all map components
+public protocol RNMBXMapComponentProtocol: AnyObject {
+  func waitForStyleLoad() -> Bool
+}
+
+/// Default implementation: most components don't need to wait for style load
+extension RNMBXMapComponentProtocol {
+  public func waitForStyleLoad() -> Bool {
+    return false
+  }
+}
+
+/// Protocol for components that can work without direct MapView access
+public protocol RNMBXMapComponent: RNMBXMapComponentProtocol {
   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.
+///
+/// This protocol inherits from RNMBXMapComponent to ensure compatibility with existing code,
+/// but provides default implementations of the base protocol methods that throw errors,
+/// forcing implementers to use the mapView-aware versions.
+public protocol RNMBXMapAndMapViewComponent: RNMBXMapComponent {
+  func addToMap(_ map: RNMBXMapView, mapView: MapView, style: Style)
+  func removeFromMap(_ map: RNMBXMapView, mapView: MapView, reason: RemovalReason) -> Bool
+}
+
+/// Default implementations for RNMBXMapAndMapViewComponent that prevent accidental use of base protocol methods
+extension RNMBXMapAndMapViewComponent {
+  public func addToMap(_ map: RNMBXMapView, style: Style) {
+    Logger.error("CRITICAL: addToMap(_:style:) called on RNMBXMapAndMapViewComponent. Use addToMap(_:mapView:style:) instead. Component: \(type(of: self))")
+  }
+
+  public func removeFromMap(_ map: RNMBXMapView, reason: RemovalReason) -> Bool {
+    Logger.error("CRITICAL: removeFromMap(_:reason:) called on RNMBXMapAndMapViewComponent. Use removeFromMap(_:mapView:reason:) instead. Component: \(type(of: self))")
+    return false
+  }
 }
 
 enum CameraMode: Int {
@@ -85,7 +120,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 +138,64 @@ 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)
+    }
+  }
+
+  // Uses default implementation from RNMBXMapComponentProtocol extension
+
+  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 +590,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,77 +3,71 @@ 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
   }
 
-  public func waitForStyleLoad() -> Bool {
-    false
-  }
+  // Uses default implementation from RNMBXMapComponentProtocol extension (returns false)
 }
 
 #if RNMBX_11

ios/RNMBX/RNMBXImages.swift

@@ -74,11 +74,8 @@ open class RNMBXImages : UIView, RNMBXMapComponent {
   }
 
   // MARK: - RNMBXMapComponent
+  // Uses default implementation from RNMBXMapComponentProtocol extension (returns false)
 
-  public func waitForStyleLoad() -> Bool {
-    return false
-  }
-  
   public func addToMap(_ map: RNMBXMapView, style: Style) {
     self.style = style
     imageManager = map.imageManager

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
   }