feature state expression API (#8049)

This PR exposes feature state expression API for Maps SDK Android and
iOS.

https://mapbox.atlassian.net/browse/MAPSIOS-2032
https://mapbox.atlassian.net/browse/MAPSAND-2418

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

---------

Co-authored-by: Natig Babayev <[email protected]>
GitOrigin-RevId: bdcebd8d5c0e05d4c412d21f36be17e2e89d452a

Author: 2 people

CHANGELOG.md

@@ -10,6 +10,7 @@ Mapbox welcomes participation and contributions from everyone.
 * Add `GeoJSONSource.minZoom` property.
 * 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.
 
 ## 11.17.0-beta.1 - 05 November, 2025
 

Sources/Examples/SwiftUI Examples/StandardInteractiveBuildingsExample.swift

@@ -3,6 +3,7 @@ import SwiftUI
 
 struct StandardInteractiveBuildingsExample: View {
     @State var selectedBuildings = [StandardBuildingsFeature]()
+    @State var shouldSelectAllBuildings: Bool = false
     @State var lightPreset = StandardLightPreset.day
     @State var theme = StandardTheme.default
     @State var buildingSelectColor = StyleColor("hsl(214, 94%, 59%)") // default color
@@ -15,6 +16,10 @@ struct StandardInteractiveBuildingsExample: View {
                 FeatureState(building, .init(select: true))
             }
 
+            if shouldSelectAllBuildings {
+                FeatureState(.standardBuildings, expression: Exp(.boolean) { true }, state: .init(select: true))
+            }
+
             /// When the user taps the building, it is added to the list of selected buildings.
             TapInteraction(.standardBuildings) { building, _ in
                 self.selectedBuildings.append(building)
@@ -23,6 +28,7 @@ struct StandardInteractiveBuildingsExample: View {
 
             /// Tapping anywhere away from a 3D building will deselect previously selected buildings.
             TapInteraction { _ in
+                shouldSelectAllBuildings = false
                 selectedBuildings.removeAll()
                 return true
             }
@@ -41,6 +47,9 @@ struct StandardInteractiveBuildingsExample: View {
                         Text("Yellow").tag(StyleColor("yellow"))
                         Text("Red").tag(StyleColor(.red))
                     }.pickerStyle(.segmented)
+                    Button("Select all") {
+                        shouldSelectAllBuildings = true
+                    }
                 }
                 HStack {
                     Text("Light")

Sources/MapboxMaps/ContentBuilders/MapContent/MountedFeatureState.swift

@@ -10,13 +10,44 @@ final class MountedFeatureState<T: FeaturesetFeatureType>: MapContentMountedComp
     }
 
     func mount(with context: MapContentNodeContext) throws {
-        guard let featureId = state.featureId else {
-            return
+        if let featureId = state.featureId {
+            context.content?.mapboxMap.value?.setFeatureState(
+                featureset: state.featureset,
+                featureId: featureId,
+                state: state.state,
+                callback: { _ in }
+            )
+        }
+
+        if let expression = state.expression {
+            Task {
+                try await context.content?.mapboxMap.value?.setFeatureStateExpression(
+                    expressionId: UInt(bitPattern: expression.description.hashValue),
+                    featureset: state.featureset,
+                    expression: expression,
+                    state: state.state
+                )
+            }
         }
-        context.content?.mapboxMap.value?.setFeatureState(featureset: state.featureset, featureId: featureId, state: state.state, callback: { _ in })
     }
 
     func unmount(with context: MapContentNodeContext) throws {
+        try unmountSingleFeature(with: context)
+        try unmountExpression(with: context)
+    }
+
+    private func unmountExpression(with context: MapContentNodeContext) throws {
+        guard let expression = state.expression else {
+            return
+        }
+        Task {
+            try await context.content?.mapboxMap.value?.removeFeatureStateExpression(
+                expressionId: UInt(bitPattern: expression.description.hashValue)
+            )
+        }
+    }
+
+    private func unmountSingleFeature(with context: MapContentNodeContext) throws {
         guard let featureId = state.featureId else {
             return
         }

Sources/MapboxMaps/Foundation/MapboxMap.swift

@@ -78,6 +78,15 @@ protocol MapboxMapProtocol: AnyObject {
         stateKey: T.StateKey?,
         callback: ((Error?) -> Void)?
     ) -> Cancelable
+    @MainActor
+    func setFeatureStateExpression<T: FeaturesetFeatureType>(
+        expressionId: UInt,
+        featureset: FeaturesetDescriptor<T>,
+        expression: Exp,
+        state: T.State
+    ) async throws
+    @MainActor
+    func removeFeatureStateExpression(expressionId: UInt) async throws
     var screenCullingShape: [CGPoint] { get set }
 }
 
@@ -1666,6 +1675,75 @@ extension MapboxMap {
                                             concreteErrorType: MapError.self))
 
     }
+
+    /// Sets a feature state expression that applies to features within the specified featureset.
+    ///
+    /// All feature states with expressions that evaluate to true will be applied to the feature.
+    /// Feature states from later added feature state expressions have higher priority. Regular feature states have higher priority than feature state expressions.
+    /// The final feature state is determined by applying states in order from lower to higher priority. As a result, multiple expressions that set states with different keys can affect the same features simultaneously.
+    /// If an expression is added for a feature set, properties from that feature set are used, not the properties from original sources.
+    ///
+    /// Note that updates to feature state expressions are asynchronous, so changes made by this method might not be
+    /// immediately visible and will have some delay. The displayed data will not be affected immediately.
+    ///
+    /// - Parameters:
+    ///   - expressionId: Unique identifier for the state expression.
+    ///   - featureset: The featureset descriptor that specifies which featureset the expression applies to.
+    ///   - expression: The expression to evaluate for the state. Should return boolean.
+    ///   - state: The `state` object with properties to update with their respective new values.
+    @_spi(Experimental)
+    @MainActor
+    public func setFeatureStateExpression<T: FeaturesetFeatureType>(
+        expressionId: UInt,
+        featureset: FeaturesetDescriptor<T>,
+        expression: Exp,
+        state: T.State
+    ) async throws {
+        guard let stateJson = encodeState(state) else {
+            throw MapError(coreError: "Failed to encode feature state")
+        }
+        guard let expressionDict = expression.asCore else {
+            throw MapError(coreError: "Failed to encode expression")
+        }
+
+        try await handleExpectedOnMain { callback in
+            __map.__setFeatureStateExpressionForFeatureStateExpressionId(UInt64(expressionId),
+                                                                         featureset: featureset.core,
+                                                                         expression: expressionDict,
+                                                                         state: stateJson,
+                                                                         callback: callback)
+        }
+    }
+
+    /// Removes a specific feature state expression.
+    ///
+    /// Remove a specific expression from the feature state expressions based on the expression ID.
+    ///
+    /// Note that updates to feature state expressions are asynchronous, so changes made by this method might not be
+    /// immediately visible and will have some delay.
+    ///
+    /// - Parameters:
+    ///   - featureStateExpressionId: The unique identifier of the expression to remove.
+    @_spi(Experimental)
+    @MainActor
+    public func removeFeatureStateExpression(expressionId: UInt) async throws {
+        try await handleExpectedOnMain { callback in
+            __map.__removeFeatureStateExpression(forFeatureStateExpressionId: UInt64(expressionId),
+                                                 callback: callback)
+        }
+    }
+
+    /// Reset all feature state expressions.
+    ///
+    /// Note that updates to feature state expressions are asynchronous, so changes made by this method might not be
+    /// immediately visible and will have some delay.
+    @_spi(Experimental)
+    @MainActor
+    public func resetFeatureStateExpressions() async throws {
+        try await handleExpectedOnMain { callback in
+            __map.__resetFeatureStateExpressions(forCallback: callback)
+        }
+    }
 }
 
 // MARK: - View Annotations

Sources/MapboxMaps/Interactions/FeatureState.swift

@@ -2,6 +2,7 @@
 public struct FeatureState<T: FeaturesetFeatureType>: Equatable, MapContent, PrimitiveMapContent {
     var featureset: FeaturesetDescriptor<T>
     var featureId: FeaturesetFeatureId?
+    var expression: Exp?
     var state: T.State
 
     /// Sets the feature state using typed descriptor and feature id.
@@ -16,6 +17,12 @@ public struct FeatureState<T: FeaturesetFeatureType>: Equatable, MapContent, Pri
         self.state = state
     }
 
+    public init(_ featureset: FeaturesetDescriptor<T>, expression: Exp, state: T.State) {
+        self.featureset = featureset
+        self.expression = expression
+        self.state = state
+    }
+
     /// Sets the feature state using the feature.
     ///
     /// The feature should have a valid ``FeaturesetFeatureType/id``. Otherwise this call is no-op.

Sources/MapboxMaps/Style/StyleManager.swift

@@ -1606,6 +1606,112 @@ extension StyleManagerProtocol {
 
 // MARK: - Conversion helpers
 
+private actor ActorCancelable {
+    private var _isCanceled: Bool = false
+
+    var isCanceled: Bool {
+        _isCanceled
+    }
+
+    private func setCanceled() {
+        _isCanceled = true
+    }
+
+    nonisolated func markCanceled() {
+        Task { await setCanceled() }
+    }
+}
+
+// TODO: When Swift 6 actor isolation is available merge main and non-main variants into one
+
+// non cancelable variant
+@MainActor
+internal func handleExpectedOnMain<Value, Error>(closure: ((@escaping (Expected<Value, Error>) -> Void) -> Void)) async throws {
+    try await handleExpectedOnMain { wrapped in
+        closure(wrapped)
+        return AnyCancelable { }
+    }
+}
+
+@MainActor
+internal func handleExpectedOnMain<Value, Error>(closure: ((@escaping (Expected<Value, Error>) -> Void) -> Cancelable)) async throws {
+    let sendableCancelable = ActorCancelable()
+
+    return try await withTaskCancellationHandler {
+        return try await withCheckedThrowingContinuation { continuation in
+            if Task.isCancelled {
+                continuation.resume(throwing: CancellationError())
+                return
+            }
+
+            var cancelable: Cancelable!
+            cancelable = closure { expected in
+                Task { @MainActor in
+                    if await sendableCancelable.isCanceled {
+                        cancelable?.cancel()
+                        cancelable = nil
+                        continuation.resume(throwing: CancellationError())
+                        return
+                    }
+
+                    do {
+                        try handleExpected(closure: { expected })
+                        continuation.resume(with: .success(()))
+                    } catch {
+                        continuation.resume(throwing: error)
+                    }
+                }
+            }
+        }
+
+    } onCancel: {
+        sendableCancelable.markCanceled()
+    }
+}
+
+// non cancelable variant
+internal func handleExpected<Value, Error>(closure: ((@escaping (Expected<Value, Error>) -> Void) -> Void)) async throws {
+    try await handleExpected { wrapped in
+        closure(wrapped)
+        return AnyCancelable { }
+    }
+}
+
+internal func handleExpected<Value, Error>(closure: ((@escaping (Expected<Value, Error>) -> Void) -> Cancelable)) async throws {
+    let sendableCancelable = ActorCancelable()
+
+    return try await withTaskCancellationHandler {
+        return try await withCheckedThrowingContinuation { continuation in
+            if Task.isCancelled {
+                continuation.resume(throwing: CancellationError())
+                return
+            }
+
+            var cancelable: Cancelable!
+            cancelable = closure { expected in
+                Task {
+                    if await sendableCancelable.isCanceled {
+                        cancelable?.cancel()
+                        cancelable = nil
+                        continuation.resume(throwing: CancellationError())
+                        return
+                    }
+
+                    do {
+                        try handleExpected(closure: { expected })
+                        continuation.resume(with: .success(()))
+                    } catch {
+                        continuation.resume(throwing: error)
+                    }
+                }
+            }
+        }
+
+    } onCancel: {
+        sendableCancelable.markCanceled()
+    }
+}
+
 internal func handleExpected<Value, Error>(closure: () -> (Expected<Value, Error>)) throws {
     let expected = closure()
 

Tests/MapboxMapsTests/Foundation/FeaturesetsTests.swift

@@ -1,4 +1,4 @@
-@testable import MapboxMaps
+@testable @_spi(Experimental) import MapboxMaps
 import XCTest
 
 final class FeaturesetsTests: IntegrationTestCase {
@@ -178,6 +178,29 @@ final class FeaturesetsTests: IntegrationTestCase {
         wait(for: [resetStatesExp], timeout: 10)
     }
 
+    func testAsyncFeatureStateMethods() async throws {
+        let expressionId: UInt = 123
+
+        let map = await mapView.mapboxMap!
+        try await map.setFeatureStateExpression(
+            expressionId: expressionId,
+            featureset: .featureset("poi", importId: "nested"),
+            expression: Exp(.boolean) { true },
+            state: ["foo": "bar"]
+        )
+
+        try await map.setFeatureStateExpression(
+            expressionId: 1111111,
+            featureset: .featureset("poi", importId: "nested"),
+            expression: Exp(.boolean) { true },
+            state: ["one": "two"]
+        )
+
+        try await map.removeFeatureStateExpression(expressionId: expressionId)
+
+        try await map.resetFeatureStateExpressions()
+    }
+
     func testStateIsQueried() throws {
         let setStateExp = expectation(description: "set state exp")
 

Tests/MapboxMapsTests/Foundation/Mocks/MockMapboxMap.swift

@@ -238,6 +238,34 @@ final class MockMapboxMap: MapboxMapProtocol {
             ))
     }
 
+    struct FeatureStateParamsExpression {
+        var expressionId: UInt
+        var featureset: FeaturesetDescriptor<FeaturesetFeature>
+        var expression: Exp
+        var state: JSONObject?
+    }
+
+    var setFeatureStateExpressionStub = Stub<FeatureStateParamsExpression, Void>()
+    func setFeatureStateExpression<T: FeaturesetFeatureType>(
+        expressionId: UInt,
+        featureset: FeaturesetDescriptor<T>,
+        expression: Exp,
+        state: T.State
+    ) async throws {
+        setFeatureStateExpressionStub.call(
+            with: FeatureStateParamsExpression(
+                expressionId: expressionId,
+                featureset: featureset.converted(),
+                expression: expression,
+                state: encodeState(state).flatMap(JSONObject.init(turfRawValue:)))
+        )
+    }
+
+    var removeFeatureStateExpressionStub = Stub<UInt, Void>()
+    func removeFeatureStateExpression(expressionId: UInt) async throws {
+        removeFeatureStateExpressionStub.call(with: expressionId)
+    }
+
     let dispatchStub = Stub<CorePlatformEventInfo, Void>()
     func dispatch(event: CorePlatformEventInfo) {
         dispatchStub.call(with: event)