[Backport release/v0.17] expose async method to set and update layer properties (#8170)

Backport 4526b93b9b0d42ecf003cfe209598f6413c0c3be from #8140.

cc @mapbox/sdk-ci
cc @mapbox/maps-ios

---------

Co-authored-by: Roman Laitarenko <[email protected]>
GitOrigin-RevId: aa17521fb2dad8c5b4ab28ca6aa1a55b6a7971ac

Author: 2 people

CHANGELOG.md

@@ -13,6 +13,7 @@ Mapbox welcomes participation and contributions from everyone.
 * Add `RasterArraySource.volatile` experimental property.
 * Make `line-emissive-strength` property data-driven.
 * Add experimental `MapboxMap.setFeatureStateExpression()`, `removeFeatureStateExpression()`, and `resetFeatureStateExpressions()` APIs to efficiently update feature state for multiple features at once using expressions.
+* Add experimental async variants of `MapboxMap.setLayerProperty()`, `setLayerProperties` and `updateLayer()`.
 
 ## 11.17.0-beta.1 - 05 November, 2025
 

Sources/MapboxMaps/Foundation/CoreAliases.swift

@@ -46,3 +46,4 @@ typealias CoreFeaturesetFeatureId = MapboxCoreMaps_Private.FeaturesetFeatureId
 typealias CoreFeaturesetQueryTarget = MapboxCoreMaps_Private.FeaturesetQueryTarget
 typealias CoreFeaturesetDescriptor = MapboxCoreMaps_Private.FeaturesetDescriptor
 typealias CoreColorTheme = MapboxCoreMaps_Private.ColorTheme
+typealias CoreAsyncOperationResultCallback = MapboxCoreMaps_Private.AsyncOperationResultCallback

Sources/MapboxMaps/Style/StyleManager.swift

@@ -193,6 +193,34 @@ public class StyleManager {
     public func updateLayer<T>(withId id: String,
                                type: T.Type,
                                update: (inout T) throws -> Void) throws where T: Layer {
+        let layerProperties = try resolveUpdatedLayerProperties(withId: id, update)
+        // Apply the changes to the layer properties to the style
+        try setLayerProperties(for: id, properties: layerProperties)
+    }
+
+    /// Updates a `layer` that exists in the `style` already
+    ///
+    /// - Parameters:
+    ///   - id: identifier of layer to update
+    ///   - type: Type of the layer
+    ///   - update: Closure that mutates a layer passed to it
+    ///
+    /// - Throws: ``TypeConversionError`` if there is a problem getting a layer data.
+    /// - Throws: ``StyleError`` if there is a problem updating the layer.
+    /// - Throws: An error when executing `update` block.
+    @_spi(Experimental)
+    public func updateLayer<T>(withId id: String,
+                               type: T.Type,
+                               update: (inout T) throws -> Void) async throws where T: Layer {
+        let layerProperties = try resolveUpdatedLayerProperties(withId: id, update)
+        // Apply the changes to the layer properties to the style
+        try await setLayerProperties(for: id, properties: layerProperties)
+    }
+
+    private func resolveUpdatedLayerProperties<T: Layer>(
+        withId id: String,
+        _ update: (inout T) throws -> Void
+    ) throws -> [String: Any] {
         let oldLayerProperties = try layerProperties(for: id)
         var layer = try T(jsonObject: oldLayerProperties)
 
@@ -222,9 +250,7 @@ public class StyleManager {
                     reduceStrategy(&result, element)
                 }
             })
-
-        // Apply the changes to the layer properties to the style
-        try setLayerProperties(for: id, properties: layerProperties)
+        return layerProperties
     }
 
     // MARK: - Sources
@@ -822,6 +848,22 @@ public class StyleManager {
         }
     }
 
+    /// Sets a JSON value to a style layer property.
+    ///
+    /// - Parameters:
+    ///   - layerId: Style layer identifier.
+    ///   - property: Style layer property name.
+    ///   - value: Style layer property value.
+    ///
+    /// - Throws:
+    ///     An error describing why the operation was unsuccessful.
+    @_spi(Experimental)
+    public func setLayerProperty(for layerId: String, property: String, value: Any) async throws {
+        try await handleExpected { callback in
+            return styleManager.__setStyleLayerPropertyAsyncForLayerId(layerId, property: property, value: value, callback: callback)
+        }
+    }
+
     /// Gets the default value of style layer property.
     ///
     /// - Parameters:
@@ -871,6 +913,29 @@ public class StyleManager {
         }
     }
 
+    /// Sets style layer properties.
+    ///
+    /// This method can be used to perform batch update for a style layer properties.
+    /// The structure of a provided `properties` value must conform to the
+    /// [format for a corresponding layer type](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/).
+    ///
+    /// Modification of a [layer identifier](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#id)
+    /// and/or [layer type](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers/#type)
+    /// is not allowed.
+    ///
+    /// - Parameters:
+    ///   - layerId: Style layer identifier.
+    ///   - properties: JSON dictionary representing the updated layer properties.
+    ///
+    /// - Throws:
+    ///     An error describing why the operation was unsuccessful.
+    @_spi(Experimental)
+    public func setLayerProperties(for layerId: String, properties: [String: Any]) async throws {
+        try await handleExpected { callback in
+            return styleManager.__setStyleLayerPropertiesAsyncForLayerId(layerId, properties: properties, callback: callback)
+        }
+    }
+
     // MARK: - Sources
 
     /// Adds a new style source.

Sources/MapboxMaps/Style/StyleManagerProtocol.swift

@@ -92,12 +92,23 @@ internal protocol StyleManagerProtocol {
         property: String,
         value: Any) -> Expected<NSNull, NSString>
 
+    func __setStyleLayerPropertyAsyncForLayerId(
+        _ layerId: String,
+        property: String,
+        value: Any,
+        callback: @escaping CoreAsyncOperationResultCallback) -> any Cancelable
+
     func getStyleLayerProperties(forLayerId layerId: String) -> Expected<AnyObject, NSString>
 
     func setStyleLayerPropertiesForLayerId(
         _ layerId: String,
         properties: Any) -> Expected<NSNull, NSString>
 
+    func __setStyleLayerPropertiesAsyncForLayerId(
+        _ layerId: String,
+        properties: Any,
+        callback: @escaping CoreAsyncOperationResultCallback) -> any Cancelable
+
     func addStyleSource(
         forSourceId sourceId: String,
         properties: Any) -> Expected<NSNull, NSString>

Tests/MapboxMapsTests/Foundation/Mocks/MockStyleManager.swift

@@ -415,6 +415,38 @@ class MockStyleManager: StyleManagerProtocol {
         )
     }
 
+    struct SetStyleLayerPropertyAsyncParameters {
+        let layerId: String
+        let property: String
+        let value: Any
+        let callback: CoreAsyncOperationResultCallback
+    }
+    let setStyleLayerPropertyAsyncStub = Stub<SetStyleLayerPropertyAsyncParameters, Cancelable>(
+        defaultReturnValue: AnyCancelable { }
+    )
+    func __setStyleLayerPropertyAsyncForLayerId(_ layerId: String, property: String, value: Any, callback: @escaping CoreAsyncOperationResultCallback) -> Cancelable {
+        let result = setStyleLayerPropertyAsyncStub.call(
+            with: SetStyleLayerPropertyAsyncParameters(layerId: layerId, property: property, value: value, callback: callback)
+        )
+        callback(.init(value: NSNull()))
+        return result
+    }
+    struct SetStyleLayerPropertiesAsyncParameters {
+        let layerId: String
+        let properties: Any
+        let callback: CoreAsyncOperationResultCallback
+    }
+    let setStyleLayerPropertiesAsyncStub = Stub<SetStyleLayerPropertiesAsyncParameters, Cancelable>(
+        defaultReturnValue: AnyCancelable { }
+    )
+    func __setStyleLayerPropertiesAsyncForLayerId(_ layerId: String, properties: Any, callback: @escaping CoreAsyncOperationResultCallback) -> Cancelable {
+        let result = setStyleLayerPropertiesAsyncStub.call(
+            with: SetStyleLayerPropertiesAsyncParameters(layerId: layerId, properties: properties, callback: callback)
+        )
+        callback(.init(value: NSNull()))
+        return result
+    }
+
     struct SetStyleSourceParameters {
         let sourceId: String
         let properties: Any

Tests/MapboxMapsTests/Foundation/Style/StyleTests.swift

@@ -541,6 +541,41 @@ final class StyleManagerTests: XCTestCase {
         XCTAssertEqual(layoutProperties["visibility"] as? String, "visible", "visibility is not reset and should keep old value")
     }
 
+    func testStyleCanUpdateLayerAsync() async throws {
+        styleManager.getStyleLayerPropertiesStub.defaultReturnValue = Expected(value: NSDictionary(dictionary: [
+            "id": "dummy-layer-id",
+            "type": "background",
+            "minzoom": 1,
+            "maxzoom": 10,
+            "paint": [
+                "background-opacity-transition": ["delay": 1, "duration": 100],
+            ],
+            "layout": [
+                "visibility": "visible",
+            ],
+        ]))
+        try await style.updateLayer(
+            withId: "dummy-layer-id",
+            type: BackgroundLayer.self) { layer in
+                layer.minZoom = nil
+                layer.maxZoom = 12
+                layer.backgroundOpacityTransition = nil
+                layer.backgroundOpacity = nil
+            }
+
+        let rootProperties = try XCTUnwrap(styleManager.setStyleLayerPropertiesAsyncStub.invocations.last!.parameters.properties as? [String: Any])
+        XCTAssertEqual(rootProperties["id"] as? String, "dummy-layer-id", "id should always be presented")
+        XCTAssertTrue(rootProperties.keys.contains("minzoom"), "minzoom is reset and should be presented")
+        XCTAssertEqual(rootProperties["maxzoom"] as? Double, 12, "maxzoom is updated and should be presented")
+
+        let paintProperties = try XCTUnwrap(rootProperties["paint"] as? [String: Any])
+        XCTAssertTrue(paintProperties.keys.contains("background-opacity-transition"), "background-opacity-transition is reset and should be presented")
+        XCTAssertFalse(paintProperties.keys.contains("background-opacity"), "background-opacity is newly added and should be presented")
+
+        let layoutProperties = try XCTUnwrap(rootProperties["layout"] as? [String: Any])
+        XCTAssertEqual(layoutProperties["visibility"] as? String, "visible", "visibility is not reset and should keep old value")
+    }
+
     func testAddImageWithStretches() throws {
         let image = UIImage.empty
         let id = UUID().uuidString