feat: add Android support for CSS mask properties

Author: paradowstack

packages/react-native/ReactAndroid/api/ReactAndroid.api

@@ -3202,8 +3202,10 @@ public abstract interface class com/facebook/react/turbomodule/core/interfaces/T
 
 public final class com/facebook/react/uimanager/BackgroundStyleApplicator {
 	public static final field INSTANCE Lcom/facebook/react/uimanager/BackgroundStyleApplicator;
+	public static final fun beginMaskedDraw (Landroid/graphics/Canvas;Landroid/view/View;)I
 	public static final fun clipToPaddingBox (Landroid/view/View;Landroid/graphics/Canvas;)V
 	public static final fun clipToPaddingBoxWithAntiAliasing (Landroid/view/View;Landroid/graphics/Canvas;Lkotlin/jvm/functions/Function0;)V
+	public static final fun endMaskedDraw (Landroid/graphics/Canvas;Landroid/view/View;I)V
 	public static final fun getBackgroundColor (Landroid/view/View;)Ljava/lang/Integer;
 	public static final fun getBorderColor (Landroid/view/View;Lcom/facebook/react/uimanager/style/LogicalEdge;)Ljava/lang/Integer;
 	public static final fun getBorderRadius (Landroid/view/View;Lcom/facebook/react/uimanager/style/BorderRadiusProp;)Lcom/facebook/react/uimanager/LengthPercentage;
@@ -3223,6 +3225,10 @@ public final class com/facebook/react/uimanager/BackgroundStyleApplicator {
 	public static final fun setBoxShadow (Landroid/view/View;Lcom/facebook/react/bridge/ReadableArray;)V
 	public static final fun setBoxShadow (Landroid/view/View;Ljava/util/List;)V
 	public static final fun setFeedbackUnderlay (Landroid/view/View;Landroid/graphics/drawable/Drawable;)V
+	public static final fun setMaskImage (Landroid/view/View;Lcom/facebook/react/bridge/ReadableArray;)V
+	public static final fun setMaskPosition (Landroid/view/View;Lcom/facebook/react/bridge/ReadableArray;)V
+	public static final fun setMaskRepeat (Landroid/view/View;Lcom/facebook/react/bridge/ReadableArray;)V
+	public static final fun setMaskSize (Landroid/view/View;Lcom/facebook/react/bridge/ReadableArray;)V
 	public static final fun setOutlineColor (Landroid/view/View;Ljava/lang/Integer;)V
 	public static final fun setOutlineOffset (Landroid/view/View;F)V
 	public static final fun setOutlineStyle (Landroid/view/View;Lcom/facebook/react/uimanager/style/OutlineStyle;)V
@@ -3260,6 +3266,10 @@ public abstract class com/facebook/react/uimanager/BaseViewManager : com/faceboo
 	public fun setElevation (Landroid/view/View;F)V
 	public fun setFilter (Landroid/view/View;Lcom/facebook/react/bridge/ReadableArray;)V
 	public fun setImportantForAccessibility (Landroid/view/View;Ljava/lang/String;)V
+	public fun setMaskImage (Landroid/view/View;Lcom/facebook/react/bridge/ReadableArray;)V
+	public fun setMaskPosition (Landroid/view/View;Lcom/facebook/react/bridge/ReadableArray;)V
+	public fun setMaskRepeat (Landroid/view/View;Lcom/facebook/react/bridge/ReadableArray;)V
+	public fun setMaskSize (Landroid/view/View;Lcom/facebook/react/bridge/ReadableArray;)V
 	public fun setMixBlendMode (Landroid/view/View;Ljava/lang/String;)V
 	public fun setMoveShouldSetResponder (Landroid/view/View;Z)V
 	public fun setMoveShouldSetResponderCapture (Landroid/view/View;Z)V
@@ -4592,6 +4602,10 @@ public final class com/facebook/react/uimanager/ViewProps {
 	public static final field MARGIN_START Ljava/lang/String;
 	public static final field MARGIN_TOP Ljava/lang/String;
 	public static final field MARGIN_VERTICAL Ljava/lang/String;
+	public static final field MASK_IMAGE Ljava/lang/String;
+	public static final field MASK_POSITION Ljava/lang/String;
+	public static final field MASK_REPEAT Ljava/lang/String;
+	public static final field MASK_SIZE Ljava/lang/String;
 	public static final field MAX_FONT_SIZE_MULTIPLIER Ljava/lang/String;
 	public static final field MAX_HEIGHT Ljava/lang/String;
 	public static final field MAX_WIDTH Ljava/lang/String;

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/BackgroundStyleApplicator.kt

@@ -56,6 +56,14 @@ import com.facebook.react.uimanager.style.OutlineStyle
 @OptIn(UnstableReactNativeAPI::class)
 public object BackgroundStyleApplicator {
 
+  private const val NO_MASK_SAVE_COUNT: Int = -1
+
+  private val maskPaint: Paint =
+      Paint(Paint.ANTI_ALIAS_FLAG).apply {
+        xfermode = PorterDuffXfermode(PorterDuff.Mode.DST_IN)
+        isFilterBitmap = true
+      }
+
   /**
    * Sets the background color of the view.
    *
@@ -107,6 +115,137 @@ public object BackgroundStyleApplicator {
     ensureBackgroundImageDrawable(view).backgroundRepeat = backgroundRepeats
   }
 
+  /**
+   * Sets the `mask-image` layers for the view.
+   *
+   * `mask-image` accepts the same values as `background-image`, but instead of being painted
+   * underneath the view it is composited over the view's own rendering with
+   * [PorterDuff.Mode.DST_IN]: the view is visible where the mask is opaque and hidden where it is
+   * transparent. Views that support masking call [beginMaskedDraw] and [endMaskedDraw] around their
+   * drawing.
+   *
+   * @param view The view to apply the mask to
+   * @param maskImage The processed `mask-image` value, or null to remove the mask
+   * @see <a href="https://www.w3.org/TR/css-masking-1/#the-mask-image">CSS Masking Level 1</a>
+   */
+  @JvmStatic
+  public fun setMaskImage(view: View, maskImage: ReadableArray?): Unit {
+    if (maskImage == null || maskImage.size() == 0) {
+      val composite = getCompositeBackgroundDrawable(view) ?: return
+      if (composite.mask != null) {
+        view.background = composite.withNewMask(null)
+      }
+      return
+    }
+
+    val layers = ArrayList<BackgroundImageLayer>(maskImage.size())
+    for (i in 0 until maskImage.size()) {
+      BackgroundImageLayer.parse(maskImage.getMap(i), view.context)?.let { layers.add(it) }
+    }
+    ensureMaskDrawable(view).backgroundImageLayers = layers.ifEmpty { null }
+  }
+
+  /**
+   * Sets the `mask-size` value for the view. Has no effect until a `mask-image` is set.
+   *
+   * @param view The view to apply the mask size to
+   * @param maskSize The processed `mask-size` value, or null to reset to `auto`
+   */
+  @JvmStatic
+  public fun setMaskSize(view: View, maskSize: ReadableArray?): Unit {
+    val sizes =
+        maskSize?.let { array ->
+          val parsed = ArrayList<BackgroundSize>(array.size())
+          for (i in 0 until array.size()) {
+            BackgroundSize.parse(array.getDynamic(i))?.let { parsed.add(it) }
+          }
+          parsed.ifEmpty { null }
+        }
+    ensureMaskDrawable(view).backgroundSize = sizes
+  }
+
+  /**
+   * Sets the `mask-position` value for the view. Has no effect until a `mask-image` is set.
+   *
+   * @param view The view to apply the mask position to
+   * @param maskPosition The processed `mask-position` value, or null to reset to `0% 0%`
+   */
+  @JvmStatic
+  public fun setMaskPosition(view: View, maskPosition: ReadableArray?): Unit {
+    val positions =
+        maskPosition?.let { array ->
+          val parsed = ArrayList<BackgroundPosition>(array.size())
+          for (i in 0 until array.size()) {
+            BackgroundPosition.parse(array.getMap(i))?.let { parsed.add(it) }
+          }
+          parsed.ifEmpty { null }
+        }
+    ensureMaskDrawable(view).backgroundPosition = positions
+  }
+
+  /**
+   * Sets the `mask-repeat` value for the view. Has no effect until a `mask-image` is set.
+   *
+   * @param view The view to apply the mask repeat to
+   * @param maskRepeat The processed `mask-repeat` value, or null to reset to `repeat`
+   */
+  @JvmStatic
+  public fun setMaskRepeat(view: View, maskRepeat: ReadableArray?): Unit {
+    val repeats =
+        maskRepeat?.let { array ->
+          val parsed = ArrayList<BackgroundRepeat>(array.size())
+          for (i in 0 until array.size()) {
+            BackgroundRepeat.parse(array.getMap(i))?.let { parsed.add(it) }
+          }
+          parsed.ifEmpty { null }
+        }
+    ensureMaskDrawable(view).backgroundRepeat = repeats
+  }
+
+  /**
+   * Starts an offscreen layer that the view's `mask-image` will later be composited into.
+   *
+   * Must be paired with [endMaskedDraw]:
+   * ```
+   * override fun draw(canvas: Canvas) {
+   *   val saveCount = BackgroundStyleApplicator.beginMaskedDraw(canvas, this)
+   *   super.draw(canvas)
+   *   BackgroundStyleApplicator.endMaskedDraw(canvas, this, saveCount)
+   * }
+   * ```
+   *
+   * @return the canvas save count to hand back to [endMaskedDraw], or -1 if the view has no mask
+   */
+  @JvmStatic
+  public fun beginMaskedDraw(canvas: Canvas, view: View): Int {
+    val mask = getMaskDrawable(view) ?: return NO_MASK_SAVE_COUNT
+    if (view.width <= 0 || view.height <= 0) {
+      return NO_MASK_SAVE_COUNT
+    }
+    mask.setBounds(0, 0, view.width, view.height)
+    return canvas.saveLayer(0f, 0f, view.width.toFloat(), view.height.toFloat(), null)
+  }
+
+  /**
+   * Paints the view's `mask-image` over the layer started by [beginMaskedDraw] and restores the
+   * canvas. A no-op when [saveCount] is the sentinel returned for an unmasked view.
+   */
+  @JvmStatic
+  public fun endMaskedDraw(canvas: Canvas, view: View, saveCount: Int): Unit {
+    if (saveCount == NO_MASK_SAVE_COUNT) {
+      return
+    }
+    // Painting the mask into a nested layer applies DST_IN when that layer is restored, which
+    // keeps the content drawn since `beginMaskedDraw` only where the mask is opaque.
+    getMaskDrawable(view)?.let { mask ->
+      val maskSaveCount =
+          canvas.saveLayer(0f, 0f, view.width.toFloat(), view.height.toFloat(), maskPaint)
+      mask.draw(canvas)
+      canvas.restoreToCount(maskSaveCount)
+    }
+    canvas.restoreToCount(saveCount)
+  }
+
   /**
    * Gets the background color of the view.
    *
@@ -135,10 +274,12 @@ public object BackgroundStyleApplicator {
     ensureBorderDrawable(view).setBorderWidth(edge.toSpacingType(), width?.dpToPx() ?: Float.NaN)
     composite.background?.borderInsets = composite.borderInsets
     composite.backgroundImage?.borderInsets = composite.borderInsets
+    composite.mask?.borderInsets = composite.borderInsets
     composite.border?.borderInsets = composite.borderInsets
 
     composite.background?.invalidateSelf()
     composite.backgroundImage?.invalidateSelf()
+    composite.mask?.invalidateSelf()
     composite.border?.invalidateSelf()
 
     composite.borderInsets = composite.borderInsets ?: BorderInsets()
@@ -217,10 +358,12 @@ public object BackgroundStyleApplicator {
     compositeBackgroundDrawable.background?.borderRadius = compositeBackgroundDrawable.borderRadius
     compositeBackgroundDrawable.backgroundImage?.borderRadius =
         compositeBackgroundDrawable.borderRadius
+    compositeBackgroundDrawable.mask?.borderRadius = compositeBackgroundDrawable.borderRadius
     compositeBackgroundDrawable.border?.borderRadius = compositeBackgroundDrawable.borderRadius
 
     compositeBackgroundDrawable.background?.invalidateSelf()
     compositeBackgroundDrawable.backgroundImage?.invalidateSelf()
+    compositeBackgroundDrawable.mask?.invalidateSelf()
     compositeBackgroundDrawable.border?.invalidateSelf()
 
     if (Build.VERSION.SDK_INT >= MIN_OUTSET_BOX_SHADOW_SDK_VERSION) {
@@ -694,6 +837,27 @@ public object BackgroundStyleApplicator {
   private fun getBackgroundImage(view: View): BackgroundImageDrawable? =
       getCompositeBackgroundDrawable(view)?.backgroundImage
 
+  private fun ensureMaskDrawable(view: View): BackgroundImageDrawable {
+    val composite = ensureCompositeBackgroundDrawable(view)
+    composite.mask?.let {
+      return it
+    }
+
+    val mask =
+        BackgroundImageDrawable(view.context, composite.borderRadius, composite.borderInsets)
+    view.background = composite.withNewMask(mask)
+    return mask
+  }
+
+  /**
+   * The view's mask drawable, but only once it actually has something to paint. `mask-size` and
+   * friends can arrive before `mask-image`, and an empty mask must not hide the view.
+   */
+  private fun getMaskDrawable(view: View): BackgroundImageDrawable? =
+      getCompositeBackgroundDrawable(view)?.mask?.takeUnless {
+        it.backgroundImageLayers.isNullOrEmpty()
+      }
+
   private fun getBorder(view: View): BorderDrawable? = getCompositeBackgroundDrawable(view)?.border
 
   private fun ensureBorderDrawable(view: View): BorderDrawable {

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/BaseViewManager.java

@@ -873,6 +873,26 @@ public void setBoxShadow(T view, @Nullable ReadableArray shadows) {
     BackgroundStyleApplicator.setBoxShadow(view, shadows);
   }
 
+  @ReactProp(name = ViewProps.MASK_IMAGE, customType = "BackgroundImage")
+  public void setMaskImage(T view, @Nullable ReadableArray images) {
+    BackgroundStyleApplicator.setMaskImage(view, images);
+  }
+
+  @ReactProp(name = ViewProps.MASK_SIZE, customType = "BackgroundSize")
+  public void setMaskSize(T view, @Nullable ReadableArray sizes) {
+    BackgroundStyleApplicator.setMaskSize(view, sizes);
+  }
+
+  @ReactProp(name = ViewProps.MASK_POSITION, customType = "BackgroundPosition")
+  public void setMaskPosition(T view, @Nullable ReadableArray positions) {
+    BackgroundStyleApplicator.setMaskPosition(view, positions);
+  }
+
+  @ReactProp(name = ViewProps.MASK_REPEAT, customType = "BackgroundRepeat")
+  public void setMaskRepeat(T view, @Nullable ReadableArray repeats) {
+    BackgroundStyleApplicator.setMaskRepeat(view, repeats);
+  }
+
   private void logUnsupportedPropertyWarning(String propName) {
     FLog.w(ReactConstants.TAG, "%s doesn't support property '%s'", getName(), propName);
   }

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/BaseViewManagerDelegate.kt

@@ -88,6 +88,11 @@ public abstract class BaseViewManagerDelegate<
 
       ViewProps.MIX_BLEND_MODE -> mViewManager.setMixBlendMode(view, value as String?)
 
+      ViewProps.MASK_IMAGE -> mViewManager.setMaskImage(view, value as ReadableArray?)
+      ViewProps.MASK_SIZE -> mViewManager.setMaskSize(view, value as ReadableArray?)
+      ViewProps.MASK_POSITION -> mViewManager.setMaskPosition(view, value as ReadableArray?)
+      ViewProps.MASK_REPEAT -> mViewManager.setMaskRepeat(view, value as ReadableArray?)
+
       ViewProps.SHADOW_COLOR ->
           mViewManager.setShadowColor(view, ColorPropConverter.getColor(value, view.context, 0))
 

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/ViewProps.kt

@@ -84,6 +84,10 @@ public object ViewProps {
   public const val BACKGROUND_REPEAT: String = "backgroundRepeat"
   // Backwards-compatible alias for the original experimental_ prefixed prop name.
   public const val EXPERIMENTAL_BACKGROUND_REPEAT: String = "experimental_backgroundRepeat"
+  public const val MASK_IMAGE: String = "maskImage"
+  public const val MASK_SIZE: String = "maskSize"
+  public const val MASK_POSITION: String = "maskPosition"
+  public const val MASK_REPEAT: String = "maskRepeat"
   public const val FOREGROUND_COLOR: String = "foregroundColor"
   public const val COLOR: String = "color"
   public const val FONT_SIZE: String = "fontSize"

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/drawable/CompositeBackgroundDrawable.kt

@@ -58,6 +58,13 @@ internal class CompositeBackgroundDrawable(
 
     // Holder value for currently set border radius
     var borderRadius: BorderRadiusStyle? = null,
+
+    /**
+     * `mask-image` rendering layer. Unlike the layers above it is not part of the [LayerDrawable]
+     * stack: it is painted separately by [BackgroundStyleApplicator.beginMaskedDraw] to composite
+     * the view's own rendering, not to draw underneath it.
+     */
+    val mask: BackgroundImageDrawable? = null,
 ) :
     LayerDrawable(
         createLayersArray(
@@ -77,6 +84,12 @@ internal class CompositeBackgroundDrawable(
     // previous ones. E.g. an EditText style may set padding on a TextInput, but we don't want to
     // constrain background color to the area inside of the padding.
     setPaddingMode(LayerDrawable.PADDING_MODE_STACK)
+
+    // The mask is not one of our layers, so LayerDrawable does not adopt it. Routing its
+    // invalidations through us forwards them to the view, which lets asynchronously loaded
+    // `url()` masks repaint once they arrive. Re-parented on every copy so that the callback
+    // always points at the drawable the view actually holds.
+    mask?.callback = this
   }
 
   fun withNewBackgroundImage(
@@ -94,6 +107,7 @@ internal class CompositeBackgroundDrawable(
         outline,
         borderInsets,
         borderRadius,
+        mask,
     )
   }
 
@@ -110,6 +124,7 @@ internal class CompositeBackgroundDrawable(
         outline,
         borderInsets,
         borderRadius,
+        mask,
     )
   }
 
@@ -129,6 +144,7 @@ internal class CompositeBackgroundDrawable(
         outline,
         borderInsets,
         borderRadius,
+        mask,
     )
   }
 
@@ -145,6 +161,7 @@ internal class CompositeBackgroundDrawable(
         outline,
         borderInsets,
         borderRadius,
+        mask,
     )
   }
 
@@ -161,6 +178,24 @@ internal class CompositeBackgroundDrawable(
         outline,
         borderInsets,
         borderRadius,
+        mask,
+    )
+  }
+
+  fun withNewMask(mask: BackgroundImageDrawable?): CompositeBackgroundDrawable {
+    return CompositeBackgroundDrawable(
+        context,
+        originalBackground,
+        outerShadows,
+        background,
+        backgroundImage,
+        border,
+        feedbackUnderlay,
+        innerShadows,
+        outline,
+        borderInsets,
+        borderRadius,
+        mask,
     )
   }
 
@@ -177,6 +212,7 @@ internal class CompositeBackgroundDrawable(
         outline,
         borderInsets,
         borderRadius,
+        mask,
     )
   }