PlatformColor lazy fallback: honor a raw-color fallback on Android (native) (#57655)

Summary:
Pull Request resolved: #57655

An implementation for the RFC in react-native-community/discussions-and-proposals#1008

Wires up the Android native color resolver (Fabric) to honor the lazy `{fallback}` carried by `PlatformColor(...)`. A later diff adds the JS argument that emits it, so on its own this change is a no-op for existing call sites.

To tell a genuine miss apart from a token that resolves to transparent black (ARGB 0):

- `FabricUIManager.getColor` now returns a boxed `Nullable Integer` — `null` means no resource path resolved. The Fabric C++ `PlatformColorParser.h` reads that boxed result over JNI, caches the explicit-miss signal, and on a miss parses the raw fallback string with the shared CSS color parser (`parseCSSProperty<CSSColor>`), matching the iOS Fabric path. The color object is now read as a `map<string, RawValue>` because it mixes an array (`resource_paths`) with an optional string (`fallback`).
- `NativeDrawable` carries an optional `colorFallback` alongside `resource_paths` so ripple drawables degrade to the fallback too.

Generated files (`ReactAndroid.api` and the `ReactAndroid*Cxx.api` snapshots) are regenerated to match the new public signatures.

Changelog:
[Internal] - PlatformColor: Android native support for a lazy raw-color fallback

Reviewed By: mdvacca, javache

Differential Revision: D113329136

fbshipit-source-id: ee15aea8dfed66364e99d427825e1b9ebcbdc483

Author: Abbondanzo

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

@@ -2252,7 +2252,7 @@ public class com/facebook/react/fabric/FabricUIManager : com/facebook/react/brid
 	public fun dispatchCommand (IILjava/lang/String;Lcom/facebook/react/bridge/ReadableArray;)V
 	public fun dispatchCommand (ILjava/lang/String;Lcom/facebook/react/bridge/ReadableArray;)V
 	public fun findNextFocusableElement (III)Ljava/lang/Integer;
-	public fun getColor (I[Ljava/lang/String;)I
+	public fun getColor (I[Ljava/lang/String;)Ljava/lang/Integer;
 	public fun getEventDispatcher ()Lcom/facebook/react/uimanager/events/EventDispatcher;
 	public fun getPerformanceCounters ()Ljava/util/Map;
 	public fun getRelativeAncestorList (II)[I

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/fabric/FabricUIManager.java

@@ -565,12 +565,12 @@ private NativeArray measureLines(
             mTextEffectRegistry);
   }
 
-  public int getColor(int surfaceId, String[] resourcePaths) {
+  public @Nullable Integer getColor(int surfaceId, String[] resourcePaths) {
     ThemedReactContext context =
         mMountingManager.getSurfaceManagerEnforced(surfaceId, "getColor").getContext();
     // Surface may have been stopped
     if (context == null) {
-      return 0;
+      return null;
     }
 
     for (String resourcePath : resourcePaths) {
@@ -579,7 +579,9 @@ public int getColor(int surfaceId, String[] resourcePaths) {
         return color;
       }
     }
-    return 0;
+    // Null (explicit miss), not 0, so native can tell an unresolved color from
+    // one that resolves to transparent black (ARGB 0).
+    return null;
   }
 
   /**

packages/react-native/ReactCommon/react/renderer/components/view/platform/android/react/renderer/components/view/HostPlatformViewProps.cpp

@@ -379,6 +379,10 @@ inline static void updateNativeDrawableProp(
         }
         folly::dynamic platformColorMap = folly::dynamic::object();
         platformColorMap["resource_paths"] = resourcePaths;
+        if (nativeDrawableValue.ripple.colorFallback.has_value()) {
+          platformColorMap["fallback"] =
+              nativeDrawableValue.ripple.colorFallback.value();
+        }
         nativeDrawableResult["color"] = platformColorMap;
       } else {
         nativeDrawableResult["color"] =

packages/react-native/ReactCommon/react/renderer/components/view/platform/android/react/renderer/components/view/NativeDrawable.h

@@ -25,14 +25,21 @@ struct NativeDrawable {
   struct Ripple {
     std::optional<SharedColor> color{};
     std::optional<std::vector<std::string>> colorResourcePaths{};
+    std::optional<std::string> colorFallback{};
     std::optional<Float> rippleRadius{};
     bool borderless{false};
     std::optional<Float> alpha{};
 
     bool operator==(const Ripple &rhs) const
     {
-      return std::tie(this->color, this->colorResourcePaths, this->borderless, this->rippleRadius, this->alpha) ==
-          std::tie(rhs.color, rhs.colorResourcePaths, rhs.borderless, rhs.rippleRadius, rhs.alpha);
+      return std::tie(
+                 this->color,
+                 this->colorResourcePaths,
+                 this->colorFallback,
+                 this->borderless,
+                 this->rippleRadius,
+                 this->alpha) ==
+          std::tie(rhs.color, rhs.colorResourcePaths, rhs.colorFallback, rhs.borderless, rhs.rippleRadius, rhs.alpha);
     }
   };
 
@@ -87,14 +94,25 @@ static inline void fromRawValue(const PropsParserContext &context, const RawValu
 
     std::optional<SharedColor> parsedColor{};
     std::optional<std::vector<std::string>> parsedColorResourcePaths{};
+    std::optional<std::string> parsedColorFallback{};
     if (color != map.end()) {
-      if (color->second.hasType<std::unordered_map<std::string, std::vector<std::string>>>()) {
-        auto colorMap = (std::unordered_map<std::string, std::vector<std::string>>)color->second;
+      // The color object mixes an array (`resource_paths`) with an optional
+      // string (`fallback`), so read it as a map of RawValue rather than a map
+      // of vector<string> (which would assert on the string value).
+      bool handledAsResourcePaths = false;
+      if (color->second.hasType<std::unordered_map<std::string, RawValue>>()) {
+        auto colorMap = (std::unordered_map<std::string, RawValue>)color->second;
         auto pathsIt = colorMap.find("resource_paths");
-        if (pathsIt != colorMap.end()) {
-          parsedColorResourcePaths = pathsIt->second;
+        if (pathsIt != colorMap.end() && pathsIt->second.hasType<std::vector<std::string>>()) {
+          parsedColorResourcePaths = (std::vector<std::string>)pathsIt->second;
+          auto fallbackIt = colorMap.find("fallback");
+          if (fallbackIt != colorMap.end() && fallbackIt->second.hasType<std::string>()) {
+            parsedColorFallback = (std::string)fallbackIt->second;
+          }
+          handledAsResourcePaths = true;
         }
-      } else {
+      }
+      if (!handledAsResourcePaths) {
         SharedColor resolved;
         fromRawValue(context, color->second, resolved);
         if (resolved) {
@@ -114,6 +132,7 @@ static inline void fromRawValue(const PropsParserContext &context, const RawValu
             NativeDrawable::Ripple{
                 .color = parsedColor,
                 .colorResourcePaths = parsedColorResourcePaths,
+                .colorFallback = parsedColorFallback,
                 .rippleRadius = rippleRadius != map.end() && rippleRadius->second.hasType<Float>()
                     ? (Float)rippleRadius->second
                     : std::optional<Float>{},

packages/react-native/ReactCommon/react/renderer/graphics/platform/android/react/renderer/graphics/PlatformColorParser.h

@@ -12,11 +12,14 @@
 #include <fbjni/fbjni.h>
 #include <folly/container/EvictingCacheMap.h>
 #include <react/renderer/core/RawValue.h>
+#include <react/renderer/css/CSSColor.h>
+#include <react/renderer/css/CSSValueParser.h>
 #include <react/renderer/graphics/Color.h>
 #include <react/renderer/graphics/fromRawValueShared.h>
 #include <react/utils/ContextContainer.h>
 #include <functional>
 #include <mutex>
+#include <optional>
 #include <string>
 #include <unordered_map>
 #include <vector>
@@ -36,39 +39,73 @@ inline SharedColor
 parsePlatformColor(const ContextContainer &contextContainer, int32_t surfaceId, const RawValue &value)
 {
   Color color = 0;
-  if (value.hasType<std::unordered_map<std::string, std::vector<std::string>>>()) {
-    auto map = (std::unordered_map<std::string, std::vector<std::string>>)value;
-    auto &resourcePaths = map["resource_paths"];
+  if (value.hasType<std::unordered_map<std::string, RawValue>>()) {
+    // Mixed array + string values, so read as a map of RawValue (a map of
+    // vector<string> would assert on the fallback string).
+    auto map = (std::unordered_map<std::string, RawValue>)value;
 
-    // JNI calls are time consuming. Let's cache results here to avoid
-    // unnecessary calls.
-    static std::mutex getColorCacheMutex;
-    static folly::EvictingCacheMap<size_t, Color> getColorCache(64);
+    std::vector<std::string> resourcePaths;
+    auto resourcePathsIt = map.find("resource_paths");
+    if (resourcePathsIt != map.end() && resourcePathsIt->second.hasType<std::vector<std::string>>()) {
+      resourcePaths = (std::vector<std::string>)resourcePathsIt->second;
+    }
+
+    bool resolved = false;
+    if (!resourcePaths.empty()) {
+      // Cache the (costly) JNI results. A cached nullopt is an explicit miss,
+      // distinct from a path that resolves to transparent (ARGB 0).
+      static std::mutex getColorCacheMutex;
+      static folly::EvictingCacheMap<size_t, std::optional<Color>> getColorCache(64);
 
-    // Listen for appearance changes, which should invalidate the cache
-    static std::once_flag setupCacheInvalidation;
-    std::call_once(setupCacheInvalidation, configurePlatformColorCacheInvalidationHook, [&] {
-      std::scoped_lock lock(getColorCacheMutex);
-      getColorCache.clear();
-    });
+      // Listen for appearance changes, which should invalidate the cache
+      static std::once_flag setupCacheInvalidation;
+      std::call_once(setupCacheInvalidation, configurePlatformColorCacheInvalidationHook, [&] {
+        std::scoped_lock lock(getColorCacheMutex);
+        getColorCache.clear();
+      });
 
-    auto hash = hashGetColourArguments(surfaceId, resourcePaths);
-    {
-      std::scoped_lock lock(getColorCacheMutex);
-      auto iterator = getColorCache.find(hash);
-      if (iterator != getColorCache.end()) {
-        color = iterator->second;
-      } else {
-        const auto &fabricUIManager = contextContainer.at<jni::global_ref<jobject>>("FabricUIManager");
-        static auto getColorFromJava =
-            fabricUIManager->getClass()->getMethod<jint(jint, jni::JArrayClass<jni::JString>)>("getColor");
-        auto javaResourcePaths = jni::JArrayClass<jni::JString>::newArray(resourcePaths.size());
+      auto hash = hashGetColourArguments(surfaceId, resourcePaths);
+      std::optional<Color> resolvedColor;
+      {
+        std::scoped_lock lock(getColorCacheMutex);
+        auto iterator = getColorCache.find(hash);
+        if (iterator != getColorCache.end()) {
+          resolvedColor = iterator->second;
+        } else {
+          const auto &fabricUIManager = contextContainer.at<jni::global_ref<jobject>>("FabricUIManager");
+          // Boxed Integer: null is an explicit miss; a non-null value may be 0
+          // (transparent black).
+          static auto getColorFromJava =
+              fabricUIManager->getClass()->getMethod<jni::JInteger::javaobject(jint, jni::JArrayClass<jni::JString>)>(
+                  "getColor");
+          auto javaResourcePaths = jni::JArrayClass<jni::JString>::newArray(resourcePaths.size());
+
+          for (int i = 0; i < resourcePaths.size(); i++) {
+            javaResourcePaths->setElement(i, *jni::make_jstring(resourcePaths[i]));
+          }
+          auto boxedColor = getColorFromJava(fabricUIManager, surfaceId, *javaResourcePaths);
+          if (boxedColor) {
+            resolvedColor = static_cast<Color>(boxedColor->value());
+          }
+          getColorCache.set(hash, resolvedColor);
+        }
+      }
+      if (resolvedColor.has_value()) {
+        color = *resolvedColor;
+        resolved = true;
+      }
+    }
 
-        for (int i = 0; i < resourcePaths.size(); i++) {
-          javaResourcePaths->setElement(i, *jni::make_jstring(resourcePaths[i]));
+    // No path resolved: parse the raw fallback with the shared CSS parser (the
+    // same parser iOS Fabric uses).
+    if (!resolved) {
+      auto fallbackIt = map.find("fallback");
+      if (fallbackIt != map.end() && fallbackIt->second.hasType<std::string>()) {
+        auto cssColor = parseCSSProperty<CSSColor>((std::string)fallbackIt->second);
+        if (std::holds_alternative<CSSColor>(cssColor)) {
+          const auto &c = std::get<CSSColor>(cssColor);
+          color = hostPlatformColorFromRGBA(c.r, c.g, c.b, c.a);
         }
-        color = getColorFromJava(fabricUIManager, surfaceId, *javaResourcePaths);
-        getColorCache.set(hash, color);
       }
     }
   }

scripts/cxx-api/api-snapshots/ReactAndroidDebugCxx.api

@@ -7562,6 +7562,7 @@ struct facebook::react::NativeDrawable::Ripple {
   public std::optional<facebook::react::Float> alpha;
   public std::optional<facebook::react::Float> rippleRadius;
   public std::optional<facebook::react::SharedColor> color;
+  public std::optional<std::string> colorFallback;
   public std::optional<std::vector<std::string>> colorResourcePaths;
 }
 

scripts/cxx-api/api-snapshots/ReactAndroidNewarchCxx.api

@@ -7323,6 +7323,7 @@ struct facebook::react::NativeDrawable::Ripple {
   public std::optional<facebook::react::Float> alpha;
   public std::optional<facebook::react::Float> rippleRadius;
   public std::optional<facebook::react::SharedColor> color;
+  public std::optional<std::string> colorFallback;
   public std::optional<std::vector<std::string>> colorResourcePaths;
 }
 

scripts/cxx-api/api-snapshots/ReactAndroidReleaseCxx.api

@@ -7553,6 +7553,7 @@ struct facebook::react::NativeDrawable::Ripple {
   public std::optional<facebook::react::Float> alpha;
   public std::optional<facebook::react::Float> rippleRadius;
   public std::optional<facebook::react::SharedColor> color;
+  public std::optional<std::string> colorFallback;
   public std::optional<std::vector<std::string>> colorResourcePaths;
 }