Add ViewAnnotationOptions.priority (#2398)

CHANGELOG.md

@@ -22,6 +22,10 @@ CircleAnnotationGroup {}
   // new
   .slot(.middle)
 ```
+* Introduce `ViewAnnotation.priority`, deprecate `ViewAnnotation.selected`.
+Use this property to define view annotation sort order.
+* Introduce `ViewAnnotation.minZoom` and `ViewAnnotation.maxZoom`. Use these properties to configure zoom-level specific view annotations.
+* Update CoreMaps to 11.10.0-beta.2 and Common to 24.10.0-beta.2.
 
 ## 11.9.0 - 18 December, 2024
 

Examples.xcodeproj/project.xcworkspace/xcshareddata/swiftpm/Package.resolved

@@ -14,17 +14,17 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/mapbox/mapbox-common-ios.git",
       "state" : {
-        "revision" : "480f648b20b87a3a55f30bb6d76d6dc7d8412ec4",
-        "version" : "24.9.0"
+        "revision" : "94a111e4e8b0f7f8d5f79cc84c832757fadd280d",
+        "version" : "24.10.0-beta.2"
       }
     },
     {
       "identity" : "mapbox-core-maps-ios",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/mapbox/mapbox-core-maps-ios.git",
       "state" : {
-        "revision" : "9fdb574d24d4a012a051d6a875e1c2753796de07",
-        "version" : "11.9.0"
+        "revision" : "2324ba61b603fd73f9b4b913437c910bb33bc405",
+        "version" : "11.10.0-beta.2"
       }
     },
     {

MapboxMaps.podspec

@@ -21,8 +21,8 @@ Pod::Spec.new do |m|
   m.source_files = 'Sources/MapboxMaps/**/*.{swift,h}'
   m.resource_bundles = { 'MapboxMapsResources' => ['Sources/**/*.{xcassets,strings}', 'Sources/MapboxMaps/MapboxMaps.json', 'Sources/MapboxMaps/PrivacyInfo.xcprivacy'] }
 
-  m.dependency 'MapboxCoreMaps', '11.9.0'
-  m.dependency 'MapboxCommon', '24.9.0'
+  m.dependency 'MapboxCoreMaps', '11.10.0-beta.2'
+  m.dependency 'MapboxCommon', '24.10.0-beta.2'
   m.dependency 'Turf', '4.0.0'
 
 end

Package.resolved

@@ -5,17 +5,17 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/mapbox/mapbox-common-ios.git",
       "state" : {
-        "revision" : "480f648b20b87a3a55f30bb6d76d6dc7d8412ec4",
-        "version" : "24.9.0"
+        "revision" : "94a111e4e8b0f7f8d5f79cc84c832757fadd280d",
+        "version" : "24.10.0-beta.2"
       }
     },
     {
       "identity" : "mapbox-core-maps-ios",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/mapbox/mapbox-core-maps-ios.git",
       "state" : {
-        "revision" : "9fdb574d24d4a012a051d6a875e1c2753796de07",
-        "version" : "11.9.0"
+        "revision" : "2324ba61b603fd73f9b4b913437c910bb33bc405",
+        "version" : "11.10.0-beta.2"
       }
     },
     {

Package.swift

@@ -4,9 +4,9 @@
 import PackageDescription
 import Foundation
 
-let coreMaps = MapsDependency.coreMaps(version: "11.9.0")
+let coreMaps = MapsDependency.coreMaps(version: "11.10.0-beta.2")
 
-let common = MapsDependency.common(version: "24.9.0")
+let common = MapsDependency.common(version: "24.10.0-beta.2")
 
 let mapboxMapsPath: String? = nil
 

Sources/Examples/All Examples/Annotations/DynamicViewAnnotationExample.swift

@@ -79,10 +79,12 @@ final class DynamicViewAnnotationExample: UIViewController, ExampleProtocol {
 
         addParkingAnnotation(
             coordinate: CLLocationCoordinate2D(latitude: 37.445, longitude: -122.1704),
-            text: "$6.99/hr")
+            text: "$6.99/hr",
+            minZoom: 12)
         addParkingAnnotation(
             coordinate: CLLocationCoordinate2D(latitude: 37.4441, longitude: -122.1691),
-            text: "$5.99/hr")
+            text: "$5.99/hr",
+            minZoom: 10)
     }
 
     private func loadRoutes() {
@@ -161,16 +163,17 @@ final class DynamicViewAnnotationExample: UIViewController, ExampleProtocol {
         }
     }
 
-    private func addParkingAnnotation(coordinate: CLLocationCoordinate2D, text: String) {
+    private func addParkingAnnotation(coordinate: CLLocationCoordinate2D, text: String, minZoom: Double) {
         let view = ParkingAnnotationView(text: text)
 
         let annotation = ViewAnnotation(coordinate: coordinate, view: view)
         annotation.allowOverlap = true
+        annotation.minZoom = minZoom
         mapView.viewAnnotations.add(annotation)
 
         view.onTap = { [unowned view, unowned annotation] in
-            annotation.selected.toggle()
-            view.selected = annotation.selected
+            view.selected.toggle()
+            annotation.priority = view.selected ? 1 : 0
             annotation.setNeedsUpdateSize()
         }
     }
@@ -261,6 +264,7 @@ private final class Route {
             etaView.anchor = config.anchor
         }
         etaAnnotation.variableAnchors = .all
+        etaAnnotation.minZoom = 8
         etaView.onTap = { [weak self] in self?.onTap?() }
 
         self.etaAnnotation = etaAnnotation
@@ -290,7 +294,7 @@ private final class Route {
     }
 
     private func updateSelected() {
-        etaAnnotation?.selected = selected
+        etaAnnotation?.priority = selected ? 1 : 0
         etaView?.selected = selected
         mapView?.mapboxMap.setFeatureState(sourceId: layerId, featureId: name, state: ["selected": selected]) {_ in}
 

Sources/Examples/All Examples/Annotations/ViewAnnotationBasicExample.swift

@@ -35,7 +35,7 @@ final class ViewAnnotationBasicExample: UIViewController, ExampleProtocol {
         annotation.allowOverlap = true
         annotationView.onClose = { [weak annotation] in annotation?.remove() }
         annotationView.onSelect = { [weak annotation] selected in
-            annotation?.selected = selected
+            annotation?.priority = selected ? 1 : 0
             annotation?.setNeedsUpdateSize()
         }
         mapView.viewAnnotations.add(annotation)

Sources/Examples/All Examples/Annotations/ViewAnnotationMarkerExample.swift

@@ -7,6 +7,11 @@ final class ViewAnnotationMarkerExample: UIViewController, ExampleProtocol {
     private var pointList: [Feature] = []
     private var markerId = 0
     private var annotations = [String: ViewAnnotation]()
+    private var _topPriority = 0
+    private var topPriority: Int {
+        _topPriority += 1
+        return _topPriority
+    }
 
     private let image = UIImage(named: "intermediate-pin")!
     private lazy var markerHeight: CGFloat = image.size.height
@@ -68,7 +73,7 @@ final class ViewAnnotationMarkerExample: UIViewController, ExampleProtocol {
         guard case let .string(id) = feature.identifier else { return false }
 
         if let annotation = annotations[id] {
-            annotation.visible.toggle()
+            annotation.priority = topPriority
             return true
         }
         return addViewAnnotation(to: feature)
@@ -141,8 +146,9 @@ final class ViewAnnotationMarkerExample: UIViewController, ExampleProtocol {
             annotation?.remove()
             self?.annotations.removeValue(forKey: id)
         }
-        annotationView.onSelect = { [weak annotation] selected in
-            annotation?.selected = selected
+        annotationView.onSelect = { [weak annotation, weak self] _ in
+            guard let self else { return }
+            annotation?.priority = self.topPriority
             annotation?.setNeedsUpdateSize()
         }
 

Sources/Examples/All Examples/Annotations/ViewAnnotationWithPointAnnotationExample.swift

@@ -70,8 +70,7 @@ final class ViewAnnotationWithPointAnnotationExample: UIViewController, ExampleP
             annotation?.remove()
             self?.annotation = nil
         }
-        annotationView.onSelect = { [weak annotation] selected in
-            annotation?.selected = selected
+        annotationView.onSelect = { [weak annotation] _ in
             annotation?.setNeedsUpdateSize()
         }
         self.annotation = annotation

Sources/Examples/SwiftUI Examples/ViewAnnotationsExample.swift

@@ -28,7 +28,7 @@ struct ViewAnnotationsExample: View {
                     }
             }
             .allowOverlap(allowOverlap)
-            .selected(selected)
+            .priority(1)
 
             // Dynamic view annotations, appeared on tap.
             // The anchor can point to bottom, top, left, or right direction.
@@ -48,6 +48,8 @@ struct ViewAnnotationsExample: View {
                     guard let idx = taps.firstIndex(where: { $0.id == tap.id }) else { return }
                     taps[idx].selectedAnchor = config
                 }
+                .priority(-1)
+                .minZoom(5)
             }
 
             // A Dynamic View Annotation annotation, that is attached to the Polyline annotation.
@@ -78,7 +80,8 @@ struct ViewAnnotationsExample: View {
             .allowZElevate(allowZElevate)
             .variableAnchors(.all) // Allow all directions for anchor
             .onAnchorChanged { self.etaAnnotationAnchor = $0.anchor }
-            .selected(true)
+            .priority(2)
+            .minZoom(5)
         }
         .onMapTapGesture { context in
             taps.append(Tap(coordinate: context.coordinate))

Sources/MapboxMaps/Annotations/ViewAnnotation.swift

@@ -108,11 +108,27 @@ public final class ViewAnnotation {
     /// Specifies if this view annotation is selected meaning it should be placed on top of others.
     ///
     /// The property is `false` by default.
+    @available(*, deprecated, message: "Use priority instead.")
     public var selected: Bool {
         get { property(\.selected, default: false) }
         set { setProperty(\.selected, value: newValue, oldValue: selected) }
     }
 
+    /// Sorts annotations in descending order based on this value.
+    ///
+    /// A replacement for the deprecated `selected` field.
+    /// Simultaneous use of `priority` and `selected` fileds should be avoided.
+    /// Annotations with higher priority keys are drawn and placed first.
+    /// When equal priorities, less-anchor-options and least-recently-added sequentially used for annotations placement order.
+    /// `priority` field defaults to 0 when not set explicitly.
+    /// Negative, 0, positive values could be used in `priority` field.
+    ///
+    /// When updating existing annotations, if `priority` is not explicitly set, the current value will be retained.
+    public var priority: Int? {
+        get { options.priority }
+        set { setProperty(\.priority, value: newValue, oldValue: priority)}
+    }
+
     /// A list of anchor configurations available.
     ///
     /// The annotation will automatically pick the first best anchor position depending on position
@@ -181,6 +197,21 @@ public final class ViewAnnotation {
         }
     }
 
+    /// Minimum zoom value in range [0, 22] to display View Annotation.
+    /// If not provided or is out of range, defaults to 0.
+    public var minZoom: Double {
+        get { property(\.minZoom, default: 0) }
+        set { setProperty(\.minZoom, value: newValue, oldValue: minZoom) }
+    }
+
+    /// Maximum zoom value in range [0, 22] to display View Annotation.
+    /// Should be greater than or equal to minZoom.
+    /// If not provided or is out of range, defaults to 22.
+    public var maxZoom: Double {
+        get { property(\.maxZoom, default: 22) }
+        set { setProperty(\.maxZoom, value: newValue, oldValue: maxZoom) }
+    }
+
     let id = UUID().uuidString
     var isHidden = true {
         didSet {