feat: add JS support for CSS mask properties

Author: paradowstack

packages/react-native/Libraries/Components/View/ReactNativeStyleAttributes.js

@@ -60,6 +60,15 @@ export const backgroundRepeatAttribute: AnyAttributeType = nativeCSSParsing
   ? true
   : {process: processBackgroundRepeat};
 
+// The `mask-*` longhands accept the same values as their `background-*`
+// counterparts, so they reuse the same processing.
+// https://www.w3.org/TR/css-masking-1/#the-mask-image
+export const maskImageAttribute: AnyAttributeType = backgroundImageAttribute;
+export const maskSizeAttribute: AnyAttributeType = backgroundSizeAttribute;
+export const maskPositionAttribute: AnyAttributeType =
+  backgroundPositionAttribute;
+export const maskRepeatAttribute: AnyAttributeType = backgroundRepeatAttribute;
+
 export const transformAttribute: AnyAttributeType = nativeCSSParsing
   ? true
   : {process: processTransform};
@@ -223,6 +232,14 @@ const ReactNativeStyleAttributes: {[string]: AnyAttributeType, ...} = {
   /** @deprecated Use `backgroundRepeat` instead. */
   experimental_backgroundRepeat: backgroundRepeatAttribute,
 
+  /**
+   * Mask
+   */
+  maskImage: maskImageAttribute,
+  maskSize: maskSizeAttribute,
+  maskPosition: maskPositionAttribute,
+  maskRepeat: maskRepeatAttribute,
+
   /**
    * View
    */

packages/react-native/Libraries/Components/View/__tests__/View-mask-itest.js

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+import '@react-native/fantom/src/setUpDefaultReactNativeEnvironment';
+
+import type {ViewStyleProp} from 'react-native/Libraries/StyleSheet/StyleSheet';
+
+import * as Fantom from '@react-native/fantom';
+import * as React from 'react';
+import {View} from 'react-native';
+
+// `mask-image` reuses the `background-image` value syntax, so these tests check
+// that the style plumbing reaches the `maskImage` prop of the mounted view for
+// each accepted form. `collapsable={false}` is not needed here: a non-empty
+// `mask-image` makes the view form a stacking context on its own.
+function mountedMaskImage(style: ViewStyleProp): string {
+  const root = Fantom.createRoot();
+  Fantom.runTask(() => {
+    root.render(<View style={style} />);
+  });
+  return root.getRenderedOutput({props: ['maskImage']}).toJSONObject().props
+    .maskImage;
+}
+
+describe('<View> mask-image', () => {
+  it('accepts a linear-gradient() shorthand', () => {
+    const maskImage = mountedMaskImage({
+      maskImage: 'linear-gradient(#e66465, #9198e5)',
+    });
+    expect(maskImage).toContain('linear-gradient');
+    expect(maskImage).toContain('rgba(230, 100, 101, 1)');
+  });
+
+  it('accepts a radial-gradient() shorthand', () => {
+    expect(
+      mountedMaskImage({maskImage: 'radial-gradient(circle, black, white)'}),
+    ).toContain('radial-gradient');
+  });
+
+  it('accepts a url() shorthand', () => {
+    expect(
+      mountedMaskImage({maskImage: 'url(https://example.com/mask.png)'}),
+    ).toContain('https://example.com/mask.png');
+  });
+
+  it('accepts an array of layers', () => {
+    const maskImage = mountedMaskImage({
+      maskImage: [
+        {type: 'url', uri: 'https://example.com/mask.png'},
+        {
+          type: 'linear-gradient',
+          direction: 'to right',
+          colorStops: [{color: 'black'}, {color: 'white'}],
+        },
+      ],
+    });
+    expect(maskImage).toContain('https://example.com/mask.png');
+    expect(maskImage).toContain('linear-gradient');
+  });
+
+  it('is unset when no mask-image is given', () => {
+    const root = Fantom.createRoot();
+    Fantom.runTask(() => {
+      root.render(<View collapsable={false} />);
+    });
+    expect(
+      root.getRenderedOutput({props: ['maskImage']}).toJSONObject().props
+        .maskImage,
+    ).toBeUndefined();
+  });
+});

packages/react-native/Libraries/NativeComponent/BaseViewConfig.android.js

@@ -19,6 +19,10 @@ import {
   boxShadowAttribute,
   colorAttribute,
   filterAttribute,
+  maskImageAttribute,
+  maskPositionAttribute,
+  maskRepeatAttribute,
+  maskSizeAttribute,
 } from '../Components/View/ReactNativeStyleAttributes';
 import {DynamicallyInjectedByGestureHandler} from './ViewConfigIgnore';
 
@@ -219,6 +223,10 @@ const validAttributesForNonEventProps = {
   experimental_backgroundPosition: backgroundPositionAttribute,
   backgroundRepeat: backgroundRepeatAttribute,
   experimental_backgroundRepeat: backgroundRepeatAttribute,
+  maskImage: maskImageAttribute,
+  maskSize: maskSizeAttribute,
+  maskPosition: maskPositionAttribute,
+  maskRepeat: maskRepeatAttribute,
   boxShadow: boxShadowAttribute,
   filter: filterAttribute,
   mixBlendMode: true,

packages/react-native/Libraries/StyleSheet/StyleSheetTypes.js

@@ -908,6 +908,10 @@ export type ____ViewStyle_InternalBase = Readonly<{
     ReadonlyArray<BackgroundPositionValue> | string,
   backgroundRepeat?: ReadonlyArray<BackgroundRepeatValue> | string,
   experimental_backgroundRepeat?: ReadonlyArray<BackgroundRepeatValue> | string,
+  maskImage?: ReadonlyArray<BackgroundImageValue> | string,
+  maskSize?: ReadonlyArray<BackgroundSizeValue> | string,
+  maskPosition?: ReadonlyArray<BackgroundPositionValue> | string,
+  maskRepeat?: ReadonlyArray<BackgroundRepeatValue> | string,
   isolation?: 'auto' | 'isolate',
 }>;
 

packages/react-native/ReactCommon/react/renderer/components/view/BaseViewProps.cpp

@@ -247,6 +247,42 @@ BaseViewProps::BaseViewProps(
               sourceProps.backgroundRepeat,
               {}),
           {})),
+      maskImage(
+          ReactNativeFeatureFlags::enableCppPropsIteratorSetter()
+              ? sourceProps.maskImage
+              : convertRawProp(
+                    context,
+                    rawProps,
+                    "maskImage",
+                    sourceProps.maskImage,
+                    {})),
+      maskSize(
+          ReactNativeFeatureFlags::enableCppPropsIteratorSetter()
+              ? sourceProps.maskSize
+              : convertRawProp(
+                    context,
+                    rawProps,
+                    "maskSize",
+                    sourceProps.maskSize,
+                    {})),
+      maskPosition(
+          ReactNativeFeatureFlags::enableCppPropsIteratorSetter()
+              ? sourceProps.maskPosition
+              : convertRawProp(
+                    context,
+                    rawProps,
+                    "maskPosition",
+                    sourceProps.maskPosition,
+                    {})),
+      maskRepeat(
+          ReactNativeFeatureFlags::enableCppPropsIteratorSetter()
+              ? sourceProps.maskRepeat
+              : convertRawProp(
+                    context,
+                    rawProps,
+                    "maskRepeat",
+                    sourceProps.maskRepeat,
+                    {})),
       mixBlendMode(convertRawProp(
           context,
           rawProps,
@@ -384,6 +420,10 @@ void BaseViewProps::setProp(
     RAW_SET_PROP_SWITCH_CASE_BASIC(filter);
     RAW_SET_PROP_SWITCH_CASE_BASIC(boxShadow);
     RAW_SET_PROP_SWITCH_CASE_BASIC(mixBlendMode);
+    RAW_SET_PROP_SWITCH_CASE_BASIC(maskImage);
+    RAW_SET_PROP_SWITCH_CASE_BASIC(maskSize);
+    RAW_SET_PROP_SWITCH_CASE_BASIC(maskPosition);
+    RAW_SET_PROP_SWITCH_CASE_BASIC(maskRepeat);
     // events field
     VIEW_EVENT_CASE(PointerEnter);
     VIEW_EVENT_CASE(PointerEnterCapture);
@@ -609,6 +649,8 @@ SharedDebugStringConvertibleList BaseViewProps::getDebugProps() const {
               "backgroundImage",
               backgroundImage,
               defaultBaseViewProps.backgroundImage),
+          debugStringConvertibleItem(
+              "maskImage", maskImage, defaultBaseViewProps.maskImage),
       };
 }
 #endif

packages/react-native/ReactCommon/react/renderer/components/view/BaseViewProps.h

@@ -86,6 +86,12 @@ class BaseViewProps : public YogaStylableProps, public AccessibilityProps {
   // Background Repeat
   std::vector<BackgroundRepeat> backgroundRepeat{};
 
+  // Mask
+  std::vector<BackgroundImage> maskImage{};
+  std::vector<BackgroundSize> maskSize{};
+  std::vector<BackgroundPosition> maskPosition{};
+  std::vector<BackgroundRepeat> maskRepeat{};
+
   // MixBlendMode
   BlendMode mixBlendMode{BlendMode::Normal};
 

packages/react-native/ReactCommon/react/renderer/components/view/ViewShadowNode.cpp

@@ -61,6 +61,7 @@ void ViewShadowNode::initialize() noexcept {
       !viewProps.filter.empty() ||
       viewProps.mixBlendMode != BlendMode::Normal ||
       viewProps.isolation == Isolation::Isolate ||
+      !viewProps.maskImage.empty() ||
       HostPlatformViewTraitsInitializer::formsStackingContext(viewProps) ||
       !viewProps.accessibilityOrder.empty();
 
@@ -105,24 +106,30 @@ void ViewShadowNode::updateStateIfNeeded() {
   ensureUnsealed();
 
   const auto& viewProps = static_cast<const ViewProps&>(*props_);
-  const auto& backgroundImages = viewProps.backgroundImage;
 
   std::vector<BackgroundImageURLRequest> newRequests;
-  for (const auto& bgImage : backgroundImages) {
-    if (std::holds_alternative<URLBackgroundImage>(bgImage)) {
-      const auto& urlBgImage = std::get<URLBackgroundImage>(bgImage);
-      if (!urlBgImage.uri.empty()) {
-        BackgroundImageURLRequest request;
-        request.imageSource.uri = urlBgImage.uri;
-        if (urlBgImage.uri.find("__packager_asset") != std::string::npos) {
-          request.imageSource.type = ImageSource::Type::Local;
-        } else {
-          request.imageSource.type = ImageSource::Type::Remote;
-        }
-        newRequests.push_back(std::move(request));
+  auto collectRequests = [&](const std::vector<BackgroundImage>& images) {
+    for (const auto& image : images) {
+      if (!std::holds_alternative<URLBackgroundImage>(image)) {
+        continue;
       }
+      const auto& urlImage = std::get<URLBackgroundImage>(image);
+      if (urlImage.uri.empty()) {
+        continue;
+      }
+      BackgroundImageURLRequest request;
+      request.imageSource.uri = urlImage.uri;
+      request.imageSource.type =
+          urlImage.uri.find("__packager_asset") != std::string::npos
+          ? ImageSource::Type::Local
+          : ImageSource::Type::Remote;
+      newRequests.push_back(std::move(request));
     }
-  }
+  };
+
+  // `background-image` and `mask-image` share the same image loading pipeline.
+  collectRequests(viewProps.backgroundImage);
+  collectRequests(viewProps.maskImage);
 
   if (newRequests.empty()) {
     return;