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

@@ -14,6 +14,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.
 
 ## Bug fixes 🐞
 * Fix camera listener not unsubscribed when disabling ScaleBar via `updateSettings { enabled = false }`

app/src/main/java/com/mapbox/maps/testapp/examples/StandardStyleInteractionsActivity.kt

@@ -4,6 +4,8 @@ import android.annotation.SuppressLint
 import android.graphics.Color
 import android.os.Bundle
 import android.view.Gravity
+import android.view.Menu
+import android.view.MenuItem
 import android.view.ViewGroup
 import android.view.ViewGroup.LayoutParams.WRAP_CONTENT
 import android.widget.TextView
@@ -13,10 +15,14 @@ import com.mapbox.geojson.Point
 import com.mapbox.maps.ClickInteraction
 import com.mapbox.maps.MapInitOptions
 import com.mapbox.maps.MapView
+import com.mapbox.maps.MapboxDelicateApi
 import com.mapbox.maps.MapboxExperimental
+import com.mapbox.maps.MapboxMap
 import com.mapbox.maps.Style
 import com.mapbox.maps.ViewAnnotationAnchor
 import com.mapbox.maps.dsl.cameraOptions
+import com.mapbox.maps.extension.style.expressions.dsl.generated.boolean
+import com.mapbox.maps.interactions.standard.generated.StandardBuildings
 import com.mapbox.maps.interactions.standard.generated.StandardBuildingsState
 import com.mapbox.maps.interactions.standard.generated.StandardPlaceLabelsState
 import com.mapbox.maps.interactions.standard.generated.StandardPoiFeature
@@ -25,6 +31,7 @@ import com.mapbox.maps.interactions.standard.generated.StandardPoiStateKey
 import com.mapbox.maps.interactions.standard.generated.standardBuildings
 import com.mapbox.maps.interactions.standard.generated.standardPlaceLabels
 import com.mapbox.maps.interactions.standard.generated.standardPoi
+import com.mapbox.maps.testapp.R
 import com.mapbox.maps.viewannotation.annotationAnchor
 import com.mapbox.maps.viewannotation.geometry
 import com.mapbox.maps.viewannotation.viewAnnotationOptions
@@ -34,7 +41,9 @@ import com.mapbox.maps.viewannotation.viewAnnotationOptions
  */
 @OptIn(MapboxExperimental::class)
 class StandardStyleInteractionsActivity : AppCompatActivity() {
+  private lateinit var mapboxMap: MapboxMap
 
+  @OptIn(MapboxDelicateApi::class)
   @SuppressLint("SetTextI18n")
   override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
@@ -50,6 +59,7 @@ class StandardStyleInteractionsActivity : AppCompatActivity() {
       )
     )
     setContentView(mapView)
+    mapboxMap = mapView.mapboxMap
     val map = mapView.mapboxMap
     val selectedPoiList = mutableListOf<StandardPoiFeature>()
 
@@ -61,7 +71,7 @@ class StandardStyleInteractionsActivity : AppCompatActivity() {
         map.setFeatureState(
           selectedBuilding,
           StandardBuildingsState {
-            highlight(true)
+            select(true)
           }
         )
         return@standardBuildings true
@@ -146,14 +156,32 @@ class StandardStyleInteractionsActivity : AppCompatActivity() {
             StandardPoiStateKey.HIDE
           )
         }
+        map.resetFeatureStateExpressions()
         selectedPoiList.clear()
         mapView.viewAnnotationManager.removeAllViewAnnotations()
+
         Toast.makeText(this, "Map clicked, removing selected POIs if any", Toast.LENGTH_SHORT).show()
         true
       }
     )
   }
 
+  override fun onCreateOptionsMenu(menu: Menu): Boolean {
+    menuInflater.inflate(R.menu.menu_standard_style_interactions, menu)
+    return true
+  }
+
+  @OptIn(MapboxDelicateApi::class)
+  override fun onOptionsItemSelected(item: MenuItem): Boolean {
+    return when (item.itemId) {
+      R.id.menu_action_select_all -> {
+        mapboxMap.setFeatureStateExpression(1, StandardBuildings(), boolean { literal(true) }, StandardBuildingsState.Builder().select(true).build())
+        true
+      }
+      else -> super.onOptionsItemSelected(item)
+    }
+  }
+
   private companion object {
     private val HELSINKI = Point.fromLngLat(24.94180921290157, 60.171227338006844)
   }

app/src/main/res/menu/menu_standard_style_interactions.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<menu xmlns:android="http://schemas.android.com/apk/res/android">
+    <item
+        android:id="@+id/menu_action_select_all"
+        android:title="@string/select_all"/>
+</menu>

app/src/main/res/values/strings.xml

@@ -193,4 +193,7 @@
     <!-- Indoor -->
     <string name="activity_indoor">Indoor Manager</string>
     <string name="description_indoor">Example showcasing indoor floor selection and state updates</string>
+
+    <!-- Standard style interactions activity -->
+    <string name="select_all">Select All</string>
 </resources>

maps-sdk/api/Release/metalava.txt

@@ -277,6 +277,7 @@ package com.mapbox.maps {
 }));
     method @com.mapbox.maps.MapboxDelicateApi @com.mapbox.maps.MapboxExperimental public <FS extends com.mapbox.maps.interactions.FeatureState, FSK extends com.mapbox.maps.interactions.FeatureStateKey<FS>> com.mapbox.common.Cancelable removeFeatureState(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<FS,?> descriptor, com.mapbox.maps.FeaturesetFeatureId id, FSK? stateKey = null);
     method @com.mapbox.maps.MapboxDelicateApi @com.mapbox.maps.MapboxExperimental public <FS extends com.mapbox.maps.interactions.FeatureState, FSK extends com.mapbox.maps.interactions.FeatureStateKey<FS>> com.mapbox.common.Cancelable removeFeatureState(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<FS,?> descriptor, com.mapbox.maps.FeaturesetFeatureId id);
+    method @com.mapbox.maps.MapboxDelicateApi @com.mapbox.maps.MapboxExperimental public void removeFeatureStateExpression(int featureStateExpressionId, com.mapbox.maps.FeatureStateOperationCallback callback);
     method @Deprecated public void removeOnCameraChangeListener(com.mapbox.maps.plugin.delegates.listeners.OnCameraChangeListener onCameraChangeListener);
     method @Deprecated public void removeOnMapIdleListener(com.mapbox.maps.plugin.delegates.listeners.OnMapIdleListener onMapIdleListener);
     method @Deprecated public void removeOnMapLoadErrorListener(com.mapbox.maps.plugin.delegates.listeners.OnMapLoadErrorListener onMapLoadErrorListener);
@@ -290,6 +291,7 @@ package com.mapbox.maps {
     method @Deprecated public void removeOnStyleImageMissingListener(com.mapbox.maps.plugin.delegates.listeners.OnStyleImageMissingListener onStyleImageMissingListener);
     method @Deprecated public void removeOnStyleImageUnusedListener(com.mapbox.maps.plugin.delegates.listeners.OnStyleImageUnusedListener onStyleImageUnusedListener);
     method @Deprecated public void removeOnStyleLoadedListener(com.mapbox.maps.plugin.delegates.listeners.OnStyleLoadedListener onStyleLoadedListener);
+    method @com.mapbox.maps.MapboxDelicateApi @com.mapbox.maps.MapboxExperimental public void resetFeatureStateExpressions(com.mapbox.maps.FeatureStateOperationCallback callback);
     method public com.mapbox.common.Cancelable resetFeatureStates(String sourceId, String? sourceLayerId, com.mapbox.maps.FeatureStateOperationCallback callback);
     method public com.mapbox.common.Cancelable resetFeatureStates(String sourceId, com.mapbox.maps.FeatureStateOperationCallback callback);
     method public com.mapbox.common.Cancelable resetFeatureStates(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<?,?> descriptor, com.mapbox.maps.FeatureStateOperationCallback callback = FeatureStateOperationCallback({ var it: com.mapbox.bindgen.Expected<java.lang.String,com.mapbox.bindgen.None> ->
@@ -316,6 +318,7 @@ package com.mapbox.maps {
 
 }));
     method @com.mapbox.maps.MapboxDelicateApi @com.mapbox.maps.MapboxExperimental public <FS extends com.mapbox.maps.interactions.FeatureState> com.mapbox.common.Cancelable setFeatureState(com.mapbox.maps.interactions.TypedFeaturesetDescriptor<FS,?> descriptor, com.mapbox.maps.FeaturesetFeatureId id, FS state);
+    method @com.mapbox.maps.MapboxDelicateApi @com.mapbox.maps.MapboxExperimental public <FS extends com.mapbox.maps.interactions.FeatureState> void setFeatureStateExpression(int featureStateExpressionId, com.mapbox.maps.interactions.TypedFeaturesetDescriptor<FS,?> featureset, com.mapbox.bindgen.Value expression, FS state, com.mapbox.maps.FeatureStateOperationCallback callback);
     method public void setGestureInProgress(boolean inProgress);
     method public void setNorthOrientation(com.mapbox.maps.NorthOrientation northOrientation);
     method public void setPrefetchZoomDelta(byte delta);

maps-sdk/api/maps-sdk.api

@@ -283,6 +283,7 @@ public final class com/mapbox/maps/MapboxMap : com/mapbox/maps/MapboxStyleManage
 	public fun removeFeatureState (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcom/mapbox/maps/FeatureStateOperationCallback;)Lcom/mapbox/common/Cancelable;
 	public static synthetic fun removeFeatureState$default (Lcom/mapbox/maps/MapboxMap;Lcom/mapbox/maps/interactions/FeaturesetFeature;Lcom/mapbox/maps/interactions/FeatureStateKey;Lcom/mapbox/maps/FeatureStateOperationCallback;ILjava/lang/Object;)Lcom/mapbox/common/Cancelable;
 	public static synthetic fun removeFeatureState$default (Lcom/mapbox/maps/MapboxMap;Lcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;Lcom/mapbox/maps/FeaturesetFeatureId;Lcom/mapbox/maps/interactions/FeatureStateKey;Lcom/mapbox/maps/FeatureStateOperationCallback;ILjava/lang/Object;)Lcom/mapbox/common/Cancelable;
+	public fun removeFeatureStateExpression (ILcom/mapbox/maps/FeatureStateOperationCallback;)V
 	public fun removeOnCameraChangeListener (Lcom/mapbox/maps/plugin/delegates/listeners/OnCameraChangeListener;)V
 	public fun removeOnMapIdleListener (Lcom/mapbox/maps/plugin/delegates/listeners/OnMapIdleListener;)V
 	public fun removeOnMapLoadErrorListener (Lcom/mapbox/maps/plugin/delegates/listeners/OnMapLoadErrorListener;)V
@@ -296,6 +297,7 @@ public final class com/mapbox/maps/MapboxMap : com/mapbox/maps/MapboxStyleManage
 	public fun removeOnStyleImageMissingListener (Lcom/mapbox/maps/plugin/delegates/listeners/OnStyleImageMissingListener;)V
 	public fun removeOnStyleImageUnusedListener (Lcom/mapbox/maps/plugin/delegates/listeners/OnStyleImageUnusedListener;)V
 	public fun removeOnStyleLoadedListener (Lcom/mapbox/maps/plugin/delegates/listeners/OnStyleLoadedListener;)V
+	public fun resetFeatureStateExpressions (Lcom/mapbox/maps/FeatureStateOperationCallback;)V
 	public final fun resetFeatureStates (Lcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;)Lcom/mapbox/common/Cancelable;
 	public final fun resetFeatureStates (Lcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;Lcom/mapbox/maps/FeatureStateOperationCallback;)Lcom/mapbox/common/Cancelable;
 	public final fun resetFeatureStates (Ljava/lang/String;Lcom/mapbox/maps/FeatureStateOperationCallback;)Lcom/mapbox/common/Cancelable;
@@ -316,6 +318,7 @@ public final class com/mapbox/maps/MapboxMap : com/mapbox/maps/MapboxStyleManage
 	public fun setFeatureState (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lcom/mapbox/bindgen/Value;Lcom/mapbox/maps/FeatureStateOperationCallback;)Lcom/mapbox/common/Cancelable;
 	public static synthetic fun setFeatureState$default (Lcom/mapbox/maps/MapboxMap;Lcom/mapbox/maps/interactions/FeaturesetFeature;Lcom/mapbox/maps/interactions/FeatureState;Lcom/mapbox/maps/FeatureStateOperationCallback;ILjava/lang/Object;)Lcom/mapbox/common/Cancelable;
 	public static synthetic fun setFeatureState$default (Lcom/mapbox/maps/MapboxMap;Lcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;Lcom/mapbox/maps/FeaturesetFeatureId;Lcom/mapbox/maps/interactions/FeatureState;Lcom/mapbox/maps/FeatureStateOperationCallback;ILjava/lang/Object;)Lcom/mapbox/common/Cancelable;
+	public fun setFeatureStateExpression (ILcom/mapbox/maps/interactions/TypedFeaturesetDescriptor;Lcom/mapbox/bindgen/Value;Lcom/mapbox/maps/interactions/FeatureState;Lcom/mapbox/maps/FeatureStateOperationCallback;)V
 	public fun setGestureInProgress (Z)V
 	public fun setNorthOrientation (Lcom/mapbox/maps/NorthOrientation;)V
 	public final fun setPrefetchZoomDelta (B)V

maps-sdk/src/main/java/com/mapbox/maps/MapboxMap.kt

@@ -2928,6 +2928,81 @@ class MapboxMap :
     }
   }
 
+  /**
+   * 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.
+   *
+   * @param featureStateExpressionId Unique identifier for the state expression.
+   * @param featureset The featureset descriptor that specifies which featureset the expression applies to.
+   * @param expression The expression to evaluate for the state. Should return boolean.
+   * @param state The `state` object with properties to update with their respective new values.
+   * @param callback The `feature state operation callback` called when the operation completes.
+   *
+   */
+  @MapboxExperimental
+  @MapboxDelicateApi
+  override fun <FS : FeatureState> setFeatureStateExpression(
+    featureStateExpressionId: Int,
+    featureset: TypedFeaturesetDescriptor<FS, *>,
+    expression: Value,
+    state: FS,
+    callback: FeatureStateOperationCallback,
+  ) {
+    checkNativeMap("setFeatureStateExpression")
+    nativeMap.setFeatureStateExpression(
+      featureStateExpressionId,
+      featureset.toFeaturesetDescriptor(),
+      expression,
+      state.internalState,
+      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.
+   *
+   * @param featureStateExpressionId The unique identifier of the expression to remove.
+   * @param callback The `feature state operation callback` called when the operation completes.
+   */
+  @MapboxExperimental
+  @MapboxDelicateApi
+  override fun removeFeatureStateExpression(
+    featureStateExpressionId: Int,
+    callback: FeatureStateOperationCallback,
+  ) {
+    checkNativeMap("removeFeatureStateExpression")
+    nativeMap.removeFeatureStateExpression(featureStateExpressionId, 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.
+   *
+   * @param callback The `feature state operation callback` called when the operation completes.
+   */
+  @MapboxExperimental
+  @MapboxDelicateApi
+  override fun resetFeatureStateExpressions(
+    callback: FeatureStateOperationCallback,
+  ) {
+    checkNativeMap("resetFeatureStateExpressions")
+    nativeMap.resetFeatureStateExpressions(callback)
+  }
+
   /**
    * For internal usage only.
    */

maps-sdk/src/main/java/com/mapbox/maps/NativeMapImpl.kt

@@ -803,4 +803,27 @@ internal class NativeMapImpl(val map: Map) {
     return map.queryRenderedFeatures(geometry, targets, callback)
   }
   // ///// END INTERACTIONS /////////
+
+  @MapboxExperimental
+  @OptIn(com.mapbox.annotation.MapboxExperimental::class)
+  fun setFeatureStateExpression(
+    featureStateExpressionId: Int,
+    featureset: FeaturesetDescriptor,
+    expression: Value,
+    state: Value,
+    callback: FeatureStateOperationCallback,
+  ) = map.setFeatureStateExpression(featureStateExpressionId.toLong(), featureset, expression, state, callback)
+
+  @MapboxExperimental
+  @OptIn(com.mapbox.annotation.MapboxExperimental::class)
+  fun removeFeatureStateExpression(
+    featureStateExpressionId: Int,
+    callback: FeatureStateOperationCallback,
+  ) = map.removeFeatureStateExpression(featureStateExpressionId.toLong(), callback)
+
+  @MapboxExperimental
+  @OptIn(com.mapbox.annotation.MapboxExperimental::class)
+  fun resetFeatureStateExpressions(
+    callback: FeatureStateOperationCallback,
+  ) = map.resetFeatureStateExpressions(callback)
 }

maps-sdk/src/test/java/com/mapbox/maps/MapboxMapTest.kt

@@ -1321,6 +1321,53 @@ class MapboxMapTest {
     }
   }
 
+  @Test
+  @OptIn(MapboxDelicateApi::class)
+  fun setFeatureStateExpression() {
+    val featureExpressionId = 2345325
+    val layerId = "layerId"
+    val descriptor = TypedFeaturesetDescriptor.Layer(layerId)
+    val state = FeatureState { }
+    val expression = Value.nullValue()
+    mapboxMap.setFeatureStateExpression(featureExpressionId, descriptor, expression, state) {}
+
+    verify {
+      nativeMap.setFeatureStateExpression(
+        featureExpressionId,
+        FeaturesetDescriptor(/* featuresetId */ null, /* importId */ null, /* layerId */ layerId),
+        expression,
+        state.internalState,
+        /* callback */ any()
+        )
+    }
+  }
+
+  @Test
+  @OptIn(MapboxDelicateApi::class)
+  fun removeFeatureStateExpression() {
+    val featureExpressionId = 2643634
+    mapboxMap.removeFeatureStateExpression(featureExpressionId) {}
+
+    verify {
+      nativeMap.removeFeatureStateExpression(
+        featureExpressionId,
+        /* callback */ any()
+      )
+    }
+  }
+
+  @Test
+  @OptIn(MapboxDelicateApi::class)
+  fun resetFeatureStateExpressions() {
+    mapboxMap.resetFeatureStateExpressions() {}
+
+    verify {
+      nativeMap.resetFeatureStateExpressions(
+        /* callback */ any()
+      )
+    }
+  }
+
   @Test
   fun queryRenderedFeatures() {
     val geometry = mockk<RenderedQueryGeometry>()

maps-sdk/src/test/java/com/mapbox/maps/NativeMapTest.kt

@@ -829,6 +829,39 @@ class NativeMapTest {
     verify { map.resetFeatureStates(featuresetDescriptor, callback) }
   }
 
+  @Test
+  @OptIn(com.mapbox.maps.MapboxExperimental::class, MapboxExperimental::class)
+  fun setFeatureStateExpression() {
+    val expression = mockk<Value>()
+    val nativeMap = NativeMapImpl(map)
+
+    val featuresetDescriptor = mockk<FeaturesetDescriptor>()
+    val state = mockk<Value>()
+    val callback = mockk<FeatureStateOperationCallback>()
+    nativeMap.setFeatureStateExpression(3, featuresetDescriptor, state, expression, callback)
+    verify { map.setFeatureStateExpression(3, featuresetDescriptor, state, expression, callback) }
+  }
+
+  @Test
+  @OptIn(com.mapbox.maps.MapboxExperimental::class, MapboxExperimental::class)
+  fun removeFeatureStateExpression() {
+    val nativeMap = NativeMapImpl(map)
+
+    val callback = mockk<FeatureStateOperationCallback>()
+    nativeMap.removeFeatureStateExpression(3, callback)
+    verify { map.removeFeatureStateExpression(3, callback) }
+  }
+
+  @Test
+  @OptIn(com.mapbox.maps.MapboxExperimental::class, MapboxExperimental::class)
+  fun resetFeatureStateExpressions() {
+    val nativeMap = NativeMapImpl(map)
+
+    val callback = mockk<FeatureStateOperationCallback>()
+    nativeMap.resetFeatureStateExpressions(callback)
+    verify { map.resetFeatureStateExpressions(callback) }
+  }
+
   @Test
   fun reduceMemoryUse() {
     val nativeMap = NativeMapImpl(map)