Add support for text-variable-anchor-offset property (#2921)

Co-authored-by: Yingfang Wang <junew@microsoft.com>
Co-authored-by: Alexey Kon <48697757+random3940@users.noreply.github.com>

platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/style/layers/PropertyFactory.java

@@ -2387,6 +2387,50 @@ The unit is in density-independent pixels only for SDF sprites that were created
     return new LayoutPropertyValue<>("text-variable-anchor", value);
   }
 
+  /**
+   * To increase the chance of placing high-priority labels on the map, you can provide an array of {@link Property.TEXT_ANCHOR} locations, each paired with an offset value. The renderer will attempt to place the label at each location, in order, before moving on to the next location+offset. Use `text-justify: auto` to choose justification based on anchor position. 
+
+ The length of the array must be even, and must alternate between enum and point entries. i.e., each anchor location must be accompanied by a point, and that point defines the offset when the corresponding anchor location is used. Positive offset values indicate right and down, while negative values indicate left and up. Anchor locations may repeat, allowing the renderer to try multiple offsets to try and place a label using the same anchor. 
+
+ When present, this property takes precedence over {@link Property.TEXT_ANCHOR}, {@link PropertyFactory#textVariableAnchor}, {@link PropertyFactory#textOffset}, and {@link PropertyFactory#textRadialOffset}. 
+
+ ```json 
+ { "text-variable-anchor-offset": ["top", [0, 4], "left", [3,0], "bottom", [1, 1]] } 
+ ``` 
+
+ When the renderer chooses the `top` anchor, `[0, 4]` will be used for {@link PropertyFactory#textOffset}; the text will be shifted down by 4 ems. 
+
+ When the renderer chooses the `left` anchor, `[3, 0]` will be used for {@link PropertyFactory#textOffset}; the text will be shifted right by 3 ems.
+   *
+   * @param value a Object[] value
+   * @return property wrapper around Object[]
+   */
+  public static PropertyValue<Object[]> textVariableAnchorOffset(Object[] value) {
+    return new LayoutPropertyValue<>("text-variable-anchor-offset", value);
+  }
+
+  /**
+   * To increase the chance of placing high-priority labels on the map, you can provide an array of {@link Property.TEXT_ANCHOR} locations, each paired with an offset value. The renderer will attempt to place the label at each location, in order, before moving on to the next location+offset. Use `text-justify: auto` to choose justification based on anchor position. 
+
+ The length of the array must be even, and must alternate between enum and point entries. i.e., each anchor location must be accompanied by a point, and that point defines the offset when the corresponding anchor location is used. Positive offset values indicate right and down, while negative values indicate left and up. Anchor locations may repeat, allowing the renderer to try multiple offsets to try and place a label using the same anchor. 
+
+ When present, this property takes precedence over {@link Property.TEXT_ANCHOR}, {@link PropertyFactory#textVariableAnchor}, {@link PropertyFactory#textOffset}, and {@link PropertyFactory#textRadialOffset}. 
+
+ ```json 
+ { "text-variable-anchor-offset": ["top", [0, 4], "left", [3,0], "bottom", [1, 1]] } 
+ ``` 
+
+ When the renderer chooses the `top` anchor, `[0, 4]` will be used for {@link PropertyFactory#textOffset}; the text will be shifted down by 4 ems. 
+
+ When the renderer chooses the `left` anchor, `[3, 0]` will be used for {@link PropertyFactory#textOffset}; the text will be shifted right by 3 ems.
+   *
+   * @param value a Object[] value
+   * @return property wrapper around Object[]
+   */
+  public static PropertyValue<Expression> textVariableAnchorOffset(Expression value) {
+    return new LayoutPropertyValue<>("text-variable-anchor-offset", value);
+  }
+
   /**
    * Part of the text placed closest to the anchor.
    *

platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/style/layers/SymbolLayer.java

@@ -505,6 +505,18 @@ public class SymbolLayer extends Layer {
     return (PropertyValue<String[]>) new PropertyValue("text-variable-anchor", nativeGetTextVariableAnchor());
   }
 
+  /**
+   * Get the TextVariableAnchorOffset property
+   *
+   * @return property wrapper value around Object[]
+   */
+  @NonNull
+  @SuppressWarnings("unchecked")
+  public PropertyValue<Object[]> getTextVariableAnchorOffset() {
+    checkThread();
+    return (PropertyValue<Object[]>) new PropertyValue("text-variable-anchor-offset", nativeGetTextVariableAnchorOffset());
+  }
+
   /**
    * Get the TextAnchor property
    *
@@ -1245,6 +1257,10 @@ public class SymbolLayer extends Layer {
   @Keep
   private native Object nativeGetTextVariableAnchor();
 
+  @NonNull
+  @Keep
+  private native Object nativeGetTextVariableAnchorOffset();
+
   @NonNull
   @Keep
   private native Object nativeGetTextAnchor();