Support a lazy raw color fallback for PlatformColor (#57701)

Summary:

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

`PlatformColor` previously had no way to specify what color to use when none of the supplied native color tokens resolve on the device. On a miss the behavior was inconsistent across platforms and architectures (transparent, nil, or a thrown error), giving apps no control over the rendered result.

This adds an optional trailing `{fallback: '<raw color string>'}` argument to `PlatformColor(...)` and updates the JS entry points to emit it. The fallback is carried lazily to native as a raw, unprocessed string and is only parsed when every provided token fails to resolve (the native side of that behavior landed earlier in this stack). When at least one token resolves the fallback is ignored, so existing call sites are completely unaffected and omitting the argument preserves today's exact behavior.

Example:

  PlatformColor('someSystemToken', {fallback: '#FF0000'})

Each platform entry point (`PlatformColorValueTypes.{android,ios,macos,windows}.js`, plus the vendored macOS/Windows copies) collects the leading string tokens and, when a trailing `{fallback}` object is present, attaches its raw string to the native color object. Non-string arguments in a non-trailing position are filtered out consistently rather than being forwarded to native. The Flow (`.js.flow`), TypeScript (`.d.ts`), and generated (`ReactNativeApi.d.ts`) declarations widen the signature to `Array<string | {fallback: string}>`, which is backward compatible.

Changelog:
[General][Added] - Support a lazy raw color fallback for PlatformColor when native tokens fail to resolve

Differential Revision: D113329139

Author: Abbondanzo

packages/react-native/Libraries/StyleSheet/PlatformColorValueTypes.android.js

@@ -11,15 +11,27 @@
 import type {ProcessedColorValue} from './processColor';
 import type {NativeColorValue} from './StyleSheet';
 
+import parsePlatformColorArgs from './parsePlatformColorArgs';
+
 /** The actual type of the opaque NativeColorValue on Android platform */
 type LocalNativeColorValue = {
   resource_paths?: Array<string>,
+  fallback?: string,
 };
 
-export const PlatformColor = (...names: Array<string>): NativeColorValue => {
+export const PlatformColor = (
+  ...args: Array<string | {fallback: string}>
+): NativeColorValue => {
+  const {names, fallback} = parsePlatformColorArgs(args);
+  // Raw fallback (when present) is passed to native untouched and only parsed
+  // on a token miss.
+  const color: LocalNativeColorValue =
+    fallback == null
+      ? {resource_paths: names}
+      : {resource_paths: names, fallback};
   /* $FlowExpectedError[incompatible-type]
    * LocalNativeColorValue is the actual type of the opaque NativeColorValue on Android platform */
-  return {resource_paths: names} as LocalNativeColorValue;
+  return color as LocalNativeColorValue;
 };
 
 export const normalizeColorObject = (

packages/react-native/Libraries/StyleSheet/PlatformColorValueTypes.d.ts

@@ -15,4 +15,6 @@ import {OpaqueColorValue} from './StyleSheet';
  *
  * @see https://reactnative.dev/docs/platformcolor#example
  */
-export function PlatformColor(...colors: string[]): OpaqueColorValue;
+export function PlatformColor(
+  ...colors: Array<string | {fallback: string}>
+): OpaqueColorValue;

packages/react-native/Libraries/StyleSheet/PlatformColorValueTypes.ios.js

@@ -11,9 +11,12 @@
 import type {ProcessedColorValue} from './processColor';
 import type {ColorValue, NativeColorValue} from './StyleSheet';
 
+import parsePlatformColorArgs from './parsePlatformColorArgs';
+
 /** The actual type of the opaque NativeColorValue on iOS platform */
 type LocalNativeColorValue = {
   semantic?: Array<string>,
+  fallback?: string,
   dynamic?: {
     light: ?(ColorValue | ProcessedColorValue),
     dark: ?(ColorValue | ProcessedColorValue),
@@ -22,9 +25,16 @@ type LocalNativeColorValue = {
   },
 };
 
-export const PlatformColor = (...names: Array<string>): NativeColorValue => {
+export const PlatformColor = (
+  ...args: Array<string | {fallback: string}>
+): NativeColorValue => {
+  const {names, fallback} = parsePlatformColorArgs(args);
+  // Raw fallback (when present) is passed to native untouched and only parsed
+  // on a token miss.
+  const color: LocalNativeColorValue =
+    fallback == null ? {semantic: names} : {semantic: names, fallback};
   // $FlowExpectedError[incompatible-type] LocalNativeColorValue is the iOS LocalNativeColorValue type
-  return {semantic: names} as LocalNativeColorValue;
+  return color as LocalNativeColorValue;
 };
 
 export type DynamicColorIOSTuplePrivate = {

packages/react-native/Libraries/StyleSheet/PlatformColorValueTypes.js.flow

@@ -18,7 +18,7 @@ import type {NativeColorValue} from './StyleSheet';
  * @see https://reactnative.dev/docs/platformcolor#example
  */
 declare export function PlatformColor(
-  ...names: Array<string>
+  ...names: Array<string | {fallback: string}>
 ): NativeColorValue;
 
 declare export function normalizeColorObject(

packages/react-native/Libraries/StyleSheet/__tests__/processColor-itest.js

@@ -109,6 +109,21 @@ describe('processColor', () => {
         const expectedColor = {dynamic: {light: 0xff000000, dark: 0xffffffff}};
         expect(processedColor).toEqual(expectedColor);
       });
+
+      // The macOS and Windows PlatformColor entry points carry the fallback with
+      // the same trailing-{fallback} detection as iOS and Android. This
+      // integration test harness only executes as iOS and Android, so that
+      // shared behavior is exercised by the iOS and Android cases here rather
+      // than duplicated for platforms the harness cannot run.
+      it('should carry an unprocessed fallback on iOS PlatformColor colors', () => {
+        const color = PlatformColorIOS('systemRedColor', {fallback: '#ff0000'});
+        const processedColor = processColor(color);
+        const expectedColor = {
+          semantic: ['systemRedColor'],
+          fallback: '#ff0000',
+        };
+        expect(processedColor).toEqual(expectedColor);
+      });
     }
   });
 
@@ -120,6 +135,18 @@ describe('processColor', () => {
         const expectedColor = {resource_paths: ['?attr/colorPrimary']};
         expect(processedColor).toEqual(expectedColor);
       });
+
+      it('should carry an unprocessed fallback on Android PlatformColor colors', () => {
+        const color = PlatformColorAndroid('?attr/colorPrimary', {
+          fallback: '#000000',
+        });
+        const processedColor = processColor(color);
+        const expectedColor = {
+          resource_paths: ['?attr/colorPrimary'],
+          fallback: '#000000',
+        };
+        expect(processedColor).toEqual(expectedColor);
+      });
     }
   });
 });

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

@@ -0,0 +1,55 @@
+/**
+ * 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
+ */
+
+/**
+ * Splits the variadic `PlatformColor(...)` arguments into the leading color
+ * token names and the optional trailing `{fallback}` options object. The
+ * per-platform `PlatformColor` implementations differ only in the native object
+ * they build from this result, so the argument parsing is shared here.
+ */
+export default function parsePlatformColorArgs(
+  args: Array<string | {fallback: string}>,
+): {names: Array<string>, fallback: ?string} {
+  const lastArg = args[args.length - 1];
+  if (__DEV__) {
+    args.forEach((arg, index) => {
+      if (typeof arg !== 'object' || arg == null) {
+        return;
+      }
+      if (index !== args.length - 1) {
+        console.error(
+          'PlatformColor: an options object is only honored as the final argument; one in any other position is ignored.',
+        );
+      } else if (typeof arg.fallback !== 'string') {
+        console.error(
+          'PlatformColor: the trailing options object must be of the form {fallback: string}; it is ignored.',
+        );
+      }
+    });
+  }
+  // The {fallback} options object is only honored as the trailing argument.
+  const fallback =
+    lastArg != null &&
+    typeof lastArg === 'object' &&
+    typeof lastArg.fallback === 'string'
+      ? lastArg.fallback
+      : null;
+  // Collect the leading string tokens; a non-string non-trailing arg (a lint
+  // error) is dropped.
+  const names: Array<string> = [];
+  const nameCount = fallback == null ? args.length : args.length - 1;
+  for (let i = 0; i < nameCount; i++) {
+    const arg = args[i];
+    if (typeof arg === 'string') {
+      names.push(arg);
+    }
+  }
+  return {names, fallback};
+}

packages/react-native/ReactNativeApi.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<d895833bed3d3c274a6647773deaa023>>
+ * @generated SignedSource<<53280bff7703ea0e9e912e22543fd568>>
  *
  * This file was generated by scripts/js-api/build-types/index.js.
  */
@@ -3491,7 +3491,14 @@ declare class PixelRatio {
   static startDetecting(): void
 }
 declare type Platform = typeof Platform
-declare function PlatformColor(...names: Array<string>): NativeColorValue
+declare function PlatformColor(
+  ...names: Array<
+    | string
+    | {
+        fallback: string
+      }
+  >
+): NativeColorValue
 declare type PlatformConfig = {}
 declare type PlatformOSType =
   "android" | "ios" | "macos" | "native" | "web" | "windows"
@@ -5866,7 +5873,7 @@ export {
   PermissionsAndroid, // 8a0bc8d8
   PixelRatio, // 10d9e32d
   Platform, // b73caa89
-  PlatformColor, // 8297ec62
+  PlatformColor, // d083d341
   PlatformOSType, // 0a17561e
   PlatformSelectSpec, // 09ed7758
   PointValue, // 69db075f