feat: add iOS support for CSS mask properties

Author: paradowstack

packages/react-native/React/Fabric/Mounting/ComponentViews/View/RCTViewComponentView.mm

@@ -104,6 +104,18 @@ static BOOL RCTViewIsInteractiveAccessibilityElement(UIView *view, const ViewPro
 }
 #endif
 
+// Core Animation supports a single mask per layer, so the border-radius
+// clipping shape is nested as the mask of the `mask-image` layer. Nested masks
+// multiply, which is exactly the intersection we want.
+static CALayer *RCTIntersectMaskLayers(CALayer *maskImageLayer, CALayer *clippingLayer)
+{
+  if (maskImageLayer == nil) {
+    return clippingLayer;
+  }
+  maskImageLayer.mask = clippingLayer;
+  return maskImageLayer;
+}
+
 @implementation RCTViewComponentView {
   UIColor *_backgroundColor;
   CALayer *_backgroundColorLayer;
@@ -662,6 +674,12 @@ - (void)updateProps:(const Props::Shared &)props oldProps:(const Props::Shared &
     needsInvalidateLayer = YES;
   }
 
+  // `mask`
+  if (oldViewProps.maskImage != newViewProps.maskImage || oldViewProps.maskSize != newViewProps.maskSize ||
+      oldViewProps.maskPosition != newViewProps.maskPosition || oldViewProps.maskRepeat != newViewProps.maskRepeat) {
+    needsInvalidateLayer = YES;
+  }
+
   // `boxShadow`
   if (oldViewProps.boxShadow != newViewProps.boxShadow) {
     needsInvalidateLayer = YES;
@@ -1396,7 +1414,8 @@ - (void)invalidateLayer
   }
 
   // clipping
-  self.currentContainerView.layer.mask = nil;
+  CALayer *maskImageLayer = [self createMaskImageLayer];
+  self.currentContainerView.layer.mask = maskImageLayer;
   if (self.currentContainerView.clipsToBounds) {
     BOOL clipToPaddingBox = ReactNativeFeatureFlags::enableIOSViewClipToPaddingBox();
     if (!clipToPaddingBox) {
@@ -1407,7 +1426,7 @@ - (void)invalidateLayer
             [self createMaskLayer:self.bounds
                      cornerInsets:RCTGetCornerInsets(
                                       RCTCornerRadiiFromBorderRadii(borderMetrics.borderRadii), UIEdgeInsetsZero)];
-        self.currentContainerView.layer.mask = maskLayer;
+        self.currentContainerView.layer.mask = RCTIntersectMaskLayers(maskImageLayer, maskLayer);
       }
 
       for (UIView *subview in self.currentContainerView.subviews) {
@@ -1428,7 +1447,7 @@ - (void)invalidateLayer
                                     cornerInsets:RCTGetCornerInsets(
                                                      RCTCornerRadiiFromBorderRadii(borderMetrics.borderRadii),
                                                      RCTUIEdgeInsetsFromEdgeInsets(borderMetrics.borderWidths))];
-      self.currentContainerView.layer.mask = maskLayer;
+      self.currentContainerView.layer.mask = RCTIntersectMaskLayers(maskImageLayer, maskLayer);
     } else {
       self.currentContainerView.layer.cornerRadius = borderMetrics.borderRadii.topLeft.horizontal;
     }
@@ -1464,6 +1483,98 @@ - (CAShapeLayer *)createMaskLayer:(CGRect)bounds cornerInsets:(RCTCornerInsets)c
   return maskLayer;
 }
 
+// Builds the layer used as `self.currentContainerView.layer.mask` for the
+// `mask-image` style, or nil when no mask is set. Each mask layer is painted
+// into a shared container so that multiple mask images composite together,
+// matching how `background-image` stacks its layers.
+// https://www.w3.org/TR/css-masking-1/#the-mask-image
+- (nullable CALayer *)createMaskImageLayer
+{
+  if (_props->maskImage.empty()) {
+    return nil;
+  }
+
+  // mask-origin: padding-box
+  CGRect positioningArea = RCTCGRectFromRect(_layoutMetrics.getPaddingFrame());
+  // mask-clip: border-box
+  CGRect paintingArea = self.layer.bounds;
+
+  CALayer *containerLayer = [CALayer layer];
+  containerLayer.frame = paintingArea;
+
+  size_t imageIndex = _props->maskImage.size() - 1;
+  // iterate in reverse to match CSS specification
+  for (const auto &maskImage : std::ranges::reverse_view(_props->maskImage)) {
+    BackgroundSize maskSize = BackgroundSizeLengthPercentage{};
+    if (!_props->maskSize.empty()) {
+      maskSize = _props->maskSize[imageIndex % _props->maskSize.size()];
+    }
+
+    BackgroundPosition maskPosition;
+    if (!_props->maskPosition.empty()) {
+      maskPosition = _props->maskPosition[imageIndex % _props->maskPosition.size()];
+    }
+
+    BackgroundRepeat maskRepeat;
+    if (!_props->maskRepeat.empty()) {
+      maskRepeat = _props->maskRepeat[imageIndex % _props->maskRepeat.size()];
+    }
+
+    CALayer *itemLayer = nil;
+
+    if (std::holds_alternative<LinearGradient>(maskImage)) {
+      CGSize itemSize = [RCTBackgroundImageUtils calculateBackgroundImageSize:positioningArea
+                                                            itemIntrinsicSize:positioningArea.size
+                                                               backgroundSize:maskSize
+                                                             backgroundRepeat:maskRepeat];
+      itemLayer = [RCTLinearGradient gradientLayerWithSize:itemSize gradient:std::get<LinearGradient>(maskImage)];
+    } else if (std::holds_alternative<RadialGradient>(maskImage)) {
+      CGSize itemSize = [RCTBackgroundImageUtils calculateBackgroundImageSize:positioningArea
+                                                            itemIntrinsicSize:positioningArea.size
+                                                               backgroundSize:maskSize
+                                                             backgroundRepeat:maskRepeat];
+      itemLayer = [RCTRadialGradient gradientLayerWithSize:itemSize gradient:std::get<RadialGradient>(maskImage)];
+    } else if (std::holds_alternative<URLBackgroundImage>(maskImage)) {
+      const auto &urlMaskImage = std::get<URLBackgroundImage>(maskImage);
+      NSString *uri = RCTNSStringFromString(urlMaskImage.uri);
+      // Loaded asynchronously by `RCTBackgroundImageURLLoader`, which triggers
+      // another `invalidateLayer` once the image is available.
+      UIImage *loadedImage = [_backgroundImageLoader loadedImageForUri:uri];
+      if (loadedImage != nil) {
+        CGSize itemSize = [RCTBackgroundImageUtils calculateBackgroundImageSize:positioningArea
+                                                              itemIntrinsicSize:loadedImage.size
+                                                                 backgroundSize:maskSize
+                                                               backgroundRepeat:maskRepeat];
+        CALayer *imageLayer = [CALayer layer];
+        imageLayer.frame = CGRectMake(0, 0, itemSize.width, itemSize.height);
+        imageLayer.contents = (__bridge id)loadedImage.CGImage;
+        // `itemSize` already resolves `mask-size`, so the image stretches to
+        // fill it rather than preserving its intrinsic aspect ratio.
+        imageLayer.contentsGravity = kCAGravityResize;
+        itemLayer = imageLayer;
+      }
+    }
+
+    if (itemLayer != nil) {
+      CALayer *maskImageLayer = [RCTBackgroundImageUtils createBackgroundImageLayerWithSize:positioningArea
+                                                                               paintingArea:paintingArea
+                                                                                   itemSize:itemLayer.frame.size
+                                                                         backgroundPosition:maskPosition
+                                                                           backgroundRepeat:maskRepeat
+                                                                                  itemLayer:itemLayer];
+      // The helper leaves the returned layer unpositioned; sizing it to the
+      // painting area is what applies `mask-clip: border-box`.
+      maskImageLayer.frame = paintingArea;
+      maskImageLayer.masksToBounds = YES;
+      [containerLayer addSublayer:maskImageLayer];
+    }
+
+    imageIndex--;
+  }
+
+  return containerLayer;
+}
+
 - (void)clearExistingBackgroundImageLayers
 {
   if (_backgroundImageLayers == nil) {