Add support for MapViewProxy updates in realtime (#76)

* - adding support for realtime proxy updates
- improved documentation

* linting

* linting

* updating changelog

* update test

* Update CHANGELOG.md

---------

Co-authored-by: Ian Wagner <ianwagner+github@switzerlandmail.ch>

Author: hactar

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Version 0.8.0 - 2025-03-17
+
+- onMapViewProxyUpdate can now be set up to update in realtime or when animations/scrolling complete (default).
+
 ## Version 0.7.0 - 2025-02-02
 
 ### Added

Package.resolved

@@ -17,6 +17,7 @@ public struct MapView<T: MapViewHostViewController>: UIViewControllerRepresentab
 
     var onStyleLoaded: ((MLNStyle) -> Void)?
     var onViewProxyChanged: ((MapViewProxy) -> Void)?
+    var proxyUpdateMode: ProxyUpdateMode?
 
     var mapViewContentInset: UIEdgeInsets?
 
@@ -50,7 +51,8 @@ public struct MapView<T: MapViewHostViewController>: UIViewControllerRepresentab
         MapViewCoordinator<T>(
             parent: self,
             onGesture: { processGesture($0, $1) },
-            onViewProxyChanged: { onViewProxyChanged?($0) }
+            onViewProxyChanged: { onViewProxyChanged?($0) },
+            proxyUpdateMode: proxyUpdateMode ?? .onFinish
         )
     }
 

Sources/MapLibreSwiftUI/MapView.swift

@@ -2,7 +2,7 @@ import Foundation
 import MapLibre
 import MapLibreSwiftDSL
 
-public class MapViewCoordinator<T: MapViewHostViewController>: NSObject, MLNMapViewDelegate {
+public class MapViewCoordinator<T: MapViewHostViewController>: NSObject, @preconcurrency MLNMapViewDelegate {
     // This must be weak, the UIViewRepresentable owns the MLNMapView.
     weak var mapView: MLNMapView?
     var parent: MapView<T>
@@ -21,14 +21,17 @@ public class MapViewCoordinator<T: MapViewHostViewController>: NSObject, MLNMapV
     var onStyleLoaded: ((MLNStyle) -> Void)?
     var onGesture: (MLNMapView, UIGestureRecognizer) -> Void
     var onViewProxyChanged: (MapViewProxy) -> Void
+    var proxyUpdateMode: ProxyUpdateMode
 
     init(parent: MapView<T>,
          onGesture: @escaping (MLNMapView, UIGestureRecognizer) -> Void,
-         onViewProxyChanged: @escaping (MapViewProxy) -> Void)
+         onViewProxyChanged: @escaping (MapViewProxy) -> Void,
+         proxyUpdateMode: ProxyUpdateMode)
     {
         self.parent = parent
         self.onGesture = onGesture
         self.onViewProxyChanged = onViewProxyChanged
+        self.proxyUpdateMode = proxyUpdateMode
     }
 
     // MARK: Core UIView Functionality
@@ -376,6 +379,8 @@ public class MapViewCoordinator<T: MapViewHostViewController>: NSObject, MLNMapV
     public func mapView(_ mapView: MLNMapView, regionDidChangeWith reason: MLNCameraChangeReason, animated _: Bool) {
         // TODO: We could put this in regionIsChangingWith if we calculate significant change/debounce.
         MainActor.assumeIsolated {
+            // regionIsChangingWith is not called for the final update, so we need to call updateViewProxy
+            // in both modes here.
             updateViewProxy(mapView: mapView, reason: reason)
 
             guard !suppressCameraUpdatePropagation else {
@@ -386,6 +391,13 @@ public class MapViewCoordinator<T: MapViewHostViewController>: NSObject, MLNMapV
         }
     }
 
+    @MainActor
+    public func mapView(_ mapView: MLNMapView, regionIsChangingWith reason: MLNCameraChangeReason) {
+        if proxyUpdateMode == .realtime {
+            updateViewProxy(mapView: mapView, reason: reason)
+        }
+    }
+
     // MARK: MapViewProxy
 
     @MainActor private func updateViewProxy(mapView: MLNMapView, reason: MLNCameraChangeReason) {
@@ -396,3 +408,12 @@ public class MapViewCoordinator<T: MapViewHostViewController>: NSObject, MLNMapV
         onViewProxyChanged(calculatedViewProxy)
     }
 }
+
+public enum ProxyUpdateMode {
+    /// Causes the `MapViewProxy`to be updated in realtime, including during map view scrolling and animations.
+    /// This will cause multiple updates per seconds. Use only if you really need to run code in realtime while users
+    /// are changing the shown region.
+    case realtime
+    /// Default. Causes `MapViewProxy` to be only be updated when a map view scroll or animation completes.
+    case onFinish
+}

Sources/MapLibreSwiftUI/MapViewCoordinator.swift

@@ -130,9 +130,30 @@ public extension MapView {
         return result
     }
 
-    func onMapViewProxyUpdate(_ onViewProxyChanged: @escaping (MapViewProxy) -> Void) -> Self {
+    /// The view modifier recieves an instance of `MapViewProxy`, which contains read only information about the current
+    /// state of the
+    /// `MapView` such as its bounds, center and insets.
+    /// - Parameters:
+    ///   - updateMode: How frequently the `MapViewProxy` is updated. Per default this is set to `.onFinish`, so updates
+    /// are only sent when the map finally completes updating due to animations or scrolling. Can be set to `.realtime`
+    /// to recieve updates during the animations and scrolling too.
+    ///   - onViewProxyChanged: The closure containing the `MapViewProxy`. Use this to run code based on the current
+    /// mapView state.
+    ///
+    /// Example:
+    /// ```swift
+    ///          .onMapViewProxyUpdate() { proxy in
+    ///            print("The map zoom level is: \(proxy.zoomLevel)")
+    ///          }
+    /// ```
+    ///
+    func onMapViewProxyUpdate(
+        updateMode: ProxyUpdateMode = .onFinish,
+        onViewProxyChanged: @escaping (MapViewProxy) -> Void
+    ) -> Self {
         var result = self
         result.onViewProxyChanged = onViewProxyChanged
+        result.proxyUpdateMode = updateMode
         return result
     }
 

Sources/MapLibreSwiftUI/MapViewModifiers.swift

@@ -13,11 +13,11 @@ final class MapViewCoordinatorCameraTests: XCTestCase {
         maplibreMapView = MockMLNMapViewCameraUpdating()
         given(maplibreMapView).frame.willReturn(.zero)
         mapView = MapView(styleURL: URL(string: "https://maplibre.org")!)
-        coordinator = MapView.Coordinator(parent: mapView) { _, _ in
+        coordinator = MapView.Coordinator(parent: mapView, onGesture: { _, _ in
             // No action
-        } onViewProxyChanged: { _ in
+        }, onViewProxyChanged: { _ in
             // No action
-        }
+        }, proxyUpdateMode: .onFinish)
     }
 
     @MainActor func testUnchangedCamera() {