[maps-sdk] Fix view annotations not rendering under RTL layoutDirection (#16540)

GitOrigin-RevId: 58f02afe75d8c615da8f817bc3a9b845846055a2

Author: pengdev

CHANGELOG.md

@@ -9,6 +9,8 @@ Mapbox welcomes participation and contributions from everyone.
 * Expand the minimum camera field of view from 11 to 1 degrees.
 * Introduce `LineLayer.lineBorderGradient` API to color the border of a line feature with a gradient along its length. Takes precedence over `lineBorderColor` and requires `lineBorderWidth` to be greater than zero.
 
+## Bug fixes 🐞
+* Fix view annotations rendering incorrectly or not appearing when the host app's layout direction is RTL.
 
 # 11.27.0 July 24, 2026
 ## Features ✨ and improvements 🏁

app/src/main/java/com/mapbox/maps/testapp/examples/markersandcallouts/viewannotation/DynamicViewAnnotationActivity.kt

@@ -89,6 +89,10 @@ import kotlinx.coroutines.withContext
  *    annotations([ViewAnnotationOptions.allowOverlap]=true), and allow overlapping with the location
  *    puck([ViewAnnotationOptions.allowOverlapWithPuck]=true). This is useful for high priority labels
  *    that shouldn't be covered by anything.
+ *
+ * The "Layout direction" button toggles the MapView's [View.layoutDirection] between LTR and RTL,
+ * to check that view annotations (in particular the ETA / alternative ETA callouts) remain visible
+ * and correctly positioned regardless of the host view's layout direction.
  */
 class DynamicViewAnnotationActivity : AppCompatActivity() {
 
@@ -126,6 +130,7 @@ class DynamicViewAnnotationActivity : AppCompatActivity() {
 
   private var isMainActive = true
   private var isOverview = true
+  private var isLayoutDirectionRtl = false
 
   override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
@@ -154,6 +159,25 @@ class DynamicViewAnnotationActivity : AppCompatActivity() {
         }
       }
 
+      binding.btnLayoutDirection.setOnClickListener {
+        isLayoutDirectionRtl = !isLayoutDirectionRtl
+        val direction = if (isLayoutDirectionRtl) {
+          View.LAYOUT_DIRECTION_RTL
+        } else {
+          View.LAYOUT_DIRECTION_LTR
+        }
+        binding.mapView.layoutDirection = direction
+        // ViewAnnotationManagerImpl always resolves annotation content against
+        // View.LAYOUT_DIRECTION_LOCALE, which is what a real RTL system locale would produce.
+        // This device's locale is LTR, so mirror that resolved value directly on the existing
+        // DVAs here to verify the same mechanism (content mirrors, position stays correct because
+        // it's governed entirely by the parent viewAnnotationsLayout, not by this).
+        if (::etaView.isInitialized) etaView.layoutDirection = direction
+        if (::alternativeEtaView.isInitialized) alternativeEtaView.layoutDirection = direction
+        refreshLayoutDirectionButton(binding.btnLayoutDirection)
+      }
+      refreshLayoutDirectionButton(binding.btnLayoutDirection)
+
       loadAssets()
 
       mapView.mapboxMap.apply {
@@ -404,6 +428,13 @@ class DynamicViewAnnotationActivity : AppCompatActivity() {
     btnMode.text = getString(R.string.dynamic_mode, if (isOverview) "follow" else "overview")
   }
 
+  private fun refreshLayoutDirectionButton(btnLayoutDirection: Button) {
+    btnLayoutDirection.text = getString(
+      R.string.dynamic_layout_direction,
+      if (isLayoutDirectionRtl) "RTL" else "LTR"
+    )
+  }
+
   @OptIn(com.mapbox.maps.MapboxExperimental::class)
   private fun addViewAnnotations() {
     etaView = viewAnnotationManager.addViewAnnotation(

app/src/main/res/layout/activity_dynamic_view_annotations.xml

@@ -23,4 +23,17 @@
         tools:text="Mode : overview"
         tools:backgroundTint="@color/blue" />
 
+    <androidx.appcompat.widget.AppCompatButton
+        android:id="@+id/btn_layout_direction"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:layout_margin="16dp"
+        android:textColor="@color/white"
+        android:backgroundTint="@color/mapbox_blue"
+        app:layout_constraintBottom_toTopOf="@id/btn_mode"
+        app:layout_constraintEnd_toEndOf="parent"
+        app:layout_constraintStart_toStartOf="parent"
+        tools:text="Layout direction : LTR"
+        tools:backgroundTint="@color/blue" />
+
 </androidx.constraintlayout.widget.ConstraintLayout>

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

@@ -171,6 +171,7 @@
     <!--View Annotations-->
     <string name="content_description_close">Close callout</string>
     <string name="dynamic_mode">Mode: %1$s</string>
+    <string name="dynamic_layout_direction">Layout direction: %1$s</string>
     <string name="collision_debug">Collision debug</string>
     <string name="va_symbol_collision">Enable ViewAnnotation-Symbols collision</string>
     <string name="va_allow_overlap">Allow Overlap (view annotations)</string>

compose-app/src/main/java/com/mapbox/maps/compose/testapp/examples/annotation/DynamicViewAnnotationActivity.kt

@@ -9,6 +9,7 @@ import androidx.compose.foundation.Image
 import androidx.compose.foundation.background
 import androidx.compose.foundation.clickable
 import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
@@ -24,6 +25,7 @@ import androidx.compose.material.FloatingActionButton
 import androidx.compose.material.MaterialTheme
 import androidx.compose.material.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.key
 import androidx.compose.runtime.mutableStateOf
@@ -44,6 +46,7 @@ import androidx.compose.ui.graphics.Outline
 import androidx.compose.ui.graphics.Path
 import androidx.compose.ui.graphics.Shape
 import androidx.compose.ui.graphics.asAndroidPath
+import androidx.compose.ui.platform.LocalLayoutDirection
 import androidx.compose.ui.res.painterResource
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.tooling.preview.Preview
@@ -191,59 +194,86 @@ public class DynamicViewAnnotationActivity : ComponentActivity() {
         mutableStateOf(true)
       }
 
+      // Toggles the MapView's own layoutDirection between LTR/RTL to verify Compose-based
+      // view annotations remain visible and correctly positioned regardless of host layout
+      // direction (see ViewAnnotationManagerImpl - annotation views default to
+      // Gravity.START|TOP, which must resolve against a container pinned to LTR).
+      var isLayoutDirectionRtl by remember {
+        mutableStateOf(false)
+      }
+
       MapboxMapComposeTheme {
         ExampleScaffold(
           floatingActionButton = {
-            FloatingActionButton(
-              onClick = {
-                if ((viewportState.mapViewportStatus as? ViewportStatus.State)?.state is FollowPuckViewportState) {
-                  viewportState.transitionToOverviewState(overviewViewportStateOptions)
-                } else {
-                  viewportState.transitionToFollowPuckState(followPuckViewportStateOption)
-                }
-              },
-              shape = RoundedCornerShape(16.dp),
+            Column(
+              horizontalAlignment = Alignment.End,
+              verticalArrangement = Arrangement.spacedBy(8.dp)
             ) {
-              Text(
-                modifier = Modifier.padding(10.dp),
-                text = if ((viewportState.mapViewportStatus as? ViewportStatus.State)?.state is FollowPuckViewportState) "Overview" else "Follow puck"
-              )
+              FloatingActionButton(
+                onClick = { isLayoutDirectionRtl = !isLayoutDirectionRtl },
+                shape = RoundedCornerShape(16.dp),
+              ) {
+                Text(
+                  modifier = Modifier.padding(10.dp),
+                  text = "Layout direction: ${if (isLayoutDirectionRtl) "RTL" else "LTR"}"
+                )
+              }
+              FloatingActionButton(
+                onClick = {
+                  if ((viewportState.mapViewportStatus as? ViewportStatus.State)?.state is FollowPuckViewportState) {
+                    viewportState.transitionToOverviewState(overviewViewportStateOptions)
+                  } else {
+                    viewportState.transitionToFollowPuckState(followPuckViewportStateOption)
+                  }
+                },
+                shape = RoundedCornerShape(16.dp),
+              ) {
+                Text(
+                  modifier = Modifier.padding(10.dp),
+                  text = if ((viewportState.mapViewportStatus as? ViewportStatus.State)?.state is FollowPuckViewportState) "Overview" else "Follow puck"
+                )
+              }
             }
           }
         ) {
-          MapboxMap(
-            Modifier.fillMaxSize(),
-            mapViewportState = viewportState,
-            style = {
-              NavigationStyle(isMainActive)
-            }
+          CompositionLocalProvider(
+            LocalLayoutDirection provides
+              if (isLayoutDirectionRtl) LayoutDirection.Rtl else LayoutDirection.Ltr
           ) {
-            MapEffect(Unit) { mapView ->
-              mapView.location.apply {
-                setLocationProvider(
-                  SimulateRouteLocationProvider(
-                    featureRouteMain.geometry() as LineString
-                  )
-                )
-                locationPuck = LocationPuck2D(
-                  bearingImage = ImageHolder.from(R.drawable.mapbox_user_puck_icon),
-                )
-                enabled = true
-                puckBearingEnabled = true
-                puckBearing = PuckBearing.COURSE
+            MapboxMap(
+              Modifier.fillMaxSize(),
+              mapViewportState = viewportState,
+              style = {
+                NavigationStyle(isMainActive)
               }
-              // Only show view annotation and adjust location puck position after all the runtime layers
-              // are added.
-              mapView.mapboxMap.mapLoadedEvents.firstOrNull()?.let {
-                mapView.location.layerAbove = LAYER_CONSTRUCTION
-                showDynamicViewAnnotations = true
-                viewportState.transitionToOverviewState(overviewViewportStateOptions)
+            ) {
+              MapEffect(Unit) { mapView ->
+                mapView.location.apply {
+                  setLocationProvider(
+                    SimulateRouteLocationProvider(
+                      featureRouteMain.geometry() as LineString
+                    )
+                  )
+                  locationPuck = LocationPuck2D(
+                    bearingImage = ImageHolder.from(R.drawable.mapbox_user_puck_icon),
+                  )
+                  enabled = true
+                  puckBearingEnabled = true
+                  puckBearing = PuckBearing.COURSE
+                }
+                // Only show view annotation and adjust location puck position after all the runtime layers
+                // are added.
+                mapView.mapboxMap.mapLoadedEvents.firstOrNull()?.let {
+                  mapView.location.layerAbove = LAYER_CONSTRUCTION
+                  showDynamicViewAnnotations = true
+                  viewportState.transitionToOverviewState(overviewViewportStateOptions)
+                }
               }
-            }
 
-            if (showDynamicViewAnnotations) {
-              DynamicViewAnnotations(isMainActive) {
-                isMainActive = !isMainActive
+              if (showDynamicViewAnnotations) {
+                DynamicViewAnnotations(isMainActive, isLayoutDirectionRtl) {
+                  isMainActive = !isMainActive
+                }
               }
             }
           }
@@ -314,7 +344,11 @@ public class DynamicViewAnnotationActivity : ComponentActivity() {
 
   @Composable
   @MapboxMapComposable
-  private fun DynamicViewAnnotations(isMainActive: Boolean, toggleActiveRoute: () -> Unit) {
+  private fun DynamicViewAnnotations(
+    isMainActive: Boolean,
+    isLayoutDirectionRtl: Boolean,
+    toggleActiveRoute: () -> Unit
+  ) {
     var etaViewAnnotationAnchor by remember {
       mutableStateOf(ViewAnnotationAnchor.BOTTOM_LEFT)
     }
@@ -375,11 +409,22 @@ public class DynamicViewAnnotationActivity : ComponentActivity() {
         }
       }
     ) {
-      AlternativeDVAContent(
-        isInitial = !isMainActive,
-        alternativeEtaViewAnnotationAnchor = alternativeEtaViewAnnotationAnchor,
-        onClick = toggleActiveRoute
-      )
+      // ViewAnnotation hosts this content in its own ComposeView (see ViewAnnotation.kt), which
+      // maps-sdk pins to LAYOUT_DIRECTION_LOCALE - the nearest LocalLayoutDirection provider to
+      // this content, so it resolves against the real device locale regardless of any
+      // CompositionLocalProvider wrapped further up around the outer MapboxMap composable.
+      // Override LocalLayoutDirection directly here (Compose's nearest-provider-wins resolution)
+      // to verify content mirroring without changing the device's actual locale.
+      CompositionLocalProvider(
+        LocalLayoutDirection provides
+          if (isLayoutDirectionRtl) LayoutDirection.Rtl else LayoutDirection.Ltr
+      ) {
+        AlternativeDVAContent(
+          isInitial = !isMainActive,
+          alternativeEtaViewAnnotationAnchor = alternativeEtaViewAnnotationAnchor,
+          onClick = toggleActiveRoute
+        )
+      }
     }
 
     // parking view annotation 1

maps-sdk/src/main/java/com/mapbox/maps/viewannotation/ViewAnnotationManager.kt

@@ -24,6 +24,13 @@ import com.mapbox.maps.ViewAnnotationOptions
  * could be controlled by the user using update operation.
  *
  * View annotation manager instance is destroyed automatically when [MapView.onDestroy] is called.
+ *
+ * View annotations are always positioned assuming a left-to-right coordinate system, regardless
+ * of the host app's locale or the [MapView]'s own layout direction — this keeps positioning
+ * correct and predictable everywhere. Independent of that, each annotation view's own content
+ * (for example `Gravity.START`/`END`, `marginStart`/`marginEnd`) is automatically resolved
+ * against the device's actual system locale, so RTL languages continue to mirror correctly with
+ * no extra setup required.
  */
 interface ViewAnnotationManager {
 

maps-sdk/src/main/java/com/mapbox/maps/viewannotation/ViewAnnotationManagerImpl.kt

@@ -99,6 +99,14 @@ internal class ViewAnnotationManagerImpl(
         ViewGroup.LayoutParams.MATCH_PARENT,
       )
       clipChildren = false // Prevents view annotation shadows or bouncing animation clipping.
+      // Annotation views get an unset (default) Gravity, which FrameLayout resolves to
+      // Gravity.START|TOP; positionAnnotationViews() then applies translationX/Y computed by
+      // gl-native (via onDelegatingViewAnnotationPositionsUpdate) assuming a left-anchored (x=0)
+      // base position. If this layout inherits RTL from MapView, START mirrors to the right edge,
+      // so the same translationX lands on the wrong side (or fully off-screen). Pin LTR so the
+      // base position always matches gl-native's left-anchored coordinate system, regardless of
+      // the host app's locale/layoutDirection.
+      layoutDirection = View.LAYOUT_DIRECTION_LTR
     }
     // place the view annotations above the map (index 0) but below the compass, ruler and other plugin views
     mapView.addView(viewAnnotationsLayout, 1)
@@ -622,6 +630,12 @@ internal class ViewAnnotationManagerImpl(
   }
 
   private fun prepareViewAnnotation(inflatedView: View, options: ViewAnnotationOptions) {
+    // viewAnnotationsLayout is pinned to LTR (see init block) so Gravity.START-based positioning
+    // isn't affected by the host app's locale. That would also flatten this view's own content
+    // (Gravity.START/END, marginStart/End, etc.) to LTR by inheritance, so resolve it against the
+    // real system locale instead - positioning is governed entirely by the parent's layoutDirection,
+    // never the child's, so this has no effect on where the view ends up on the map.
+    inflatedView.layoutDirection = View.LAYOUT_DIRECTION_LOCALE
     measureView(inflatedView)
     val inflatedViewLayoutParams = inflatedView.layoutParams as ViewGroup.LayoutParams
     // If values in layout params are negative - view is wrap_content (assuming match_parent view annotations

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

@@ -67,6 +67,7 @@ class ViewAnnotationManagerAddTest(
     viewAnnotationsLayout = mockk()
     every { viewAnnotationsLayout.layoutParams = any() } just Runs
     every { viewAnnotationsLayout.setClipChildren(any()) } just Runs
+    every { viewAnnotationsLayout.layoutDirection = any() } just Runs
     every { viewAnnotationsLayout.addView(any()) } just Runs
     every { viewAnnotationsLayout.removeView(any()) } just Runs
     every { viewAnnotationsLayout.context } returns mockk()

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

@@ -54,6 +54,7 @@ class ViewAnnotationManagerTest {
     viewAnnotationsLayout = mockk()
     every { viewAnnotationsLayout.layoutParams = any() } just Runs
     every { viewAnnotationsLayout.setClipChildren(any()) } just Runs
+    every { viewAnnotationsLayout.layoutDirection = any() } just Runs
     every { viewAnnotationsLayout.removeView(any()) } just Runs
     every { mapboxMap.addViewAnnotation(any(), any()) } returns ExpectedFactory.createNone()
     val displayMetrics = DisplayMetrics().apply { density = 1f }
@@ -65,6 +66,7 @@ class ViewAnnotationManagerTest {
   }
 
   private fun mockView(): View = mockk<View>().also {
+    every { it.layoutDirection = any() } just Runs
     every { it.layoutParams } returns frameLayoutParams
     every { it.measuredWidth } returns 10
     every { it.measuredHeight } returns 10
@@ -85,6 +87,18 @@ class ViewAnnotationManagerTest {
     unmockkStatic(MeasureSpec::class)
   }
 
+  @Test
+  fun viewAnnotationsLayoutIsPinnedToLtr() {
+    // Annotation views get an unset (default) Gravity, resolved by FrameLayout to
+    // Gravity.START|TOP. If this container inherited RTL from a host MapView with
+    // layoutDirection = RTL, that default would mirror to the right edge, while
+    // positionAnnotationViews() still applies translationX/Y computed assuming a
+    // left-anchored (x=0) base - landing views off-screen or in the wrong corner.
+    // The container must be pinned to LTR so it always matches that left-anchored
+    // coordinate system, regardless of the host app's locale/layoutDirection.
+    verifyOnce { viewAnnotationsLayout.layoutDirection = View.LAYOUT_DIRECTION_LTR }
+  }
+
   @Test
   fun addViewAnnotationWithDuplicateView() {
     viewAnnotationManager.addViewAnnotation(
@@ -558,6 +572,7 @@ class ViewAnnotationManagerTest {
     childViews: List<View> = emptyList(),
     selfTag: Any? = null,
   ): FrameLayout = mockk<FrameLayout>().also { root ->
+    every { root.layoutDirection = any() } just Runs
     every { root.layoutParams } returns FrameLayout.LayoutParams(100, 100)
     every { root.measuredWidth } returns 100
     every { root.measuredHeight } returns 100