Skip to content

PlatformColor lazy fallback: honor a raw-color fallback on iOS and macOS (native) (#57556)#57556

Open
Abbondanzo wants to merge 1 commit into
react:mainfrom
Abbondanzo:export-D111837102
Open

PlatformColor lazy fallback: honor a raw-color fallback on iOS and macOS (native) (#57556)#57556
Abbondanzo wants to merge 1 commit into
react:mainfrom
Abbondanzo:export-D111837102

Conversation

@Abbondanzo

@Abbondanzo Abbondanzo commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Summary:

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

This is the first diff in a stack that adds an optional trailing {fallback: '<raw color string>'} argument to PlatformColor(...). The fallback is carried lazily to native and parsed only when every supplied color token fails to resolve. This diff wires up the iOS and macOS native color resolvers to honor that fallback; 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 distinguish a genuine miss (no token resolves) from a token that legitimately resolves to a transparent color, the semantic-color resolver gains an OrNil variant:

  • RCTPlatformColorFromSemanticItemsOrNil returns nil on a miss instead of collapsing to clearColor. RCTPlatformColorFromSemanticItems keeps its existing non-null contract by wrapping the OrNil variant.
  • On Fabric, Color::createSemanticColor returns the undefined-color sentinel (a null underlying UIColor) on a miss, so PlatformColorParser.mm can apply the fallback only on a true miss and otherwise render transparent exactly as before.
  • The fallback string is parsed with the shared CSS color parser (parseCSSProperty<CSSColor>), so transparent/rgba(0,0,0,0) are honored rather than mistaken for a parse failure.
  • On the iOS Paper (legacy) path, RCTConvert.mm parses the common hex forms (#RGB, #RGBA, #RRGGBB, #RRGGBBAA, alpha last) as the fallback when every semantic name misses.

This spans the xplat iOS/macOS graphics resolvers and the vendored third-party/react-native-macos copies.

Changelog:
[Internal] - PlatformColor: iOS/macOS native support for a lazy raw-color fallback

Differential Revision: D111837102

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Jul 15, 2026
@meta-codesync

meta-codesync Bot commented Jul 15, 2026

Copy link
Copy Markdown

@Abbondanzo has exported this pull request. If you are a Meta employee, you can view the originating Diff in D111837102.

@meta-codesync meta-codesync Bot changed the title Support a lazy raw color fallback for PlatformColor Support a lazy raw color fallback for PlatformColor (#57556) Jul 22, 2026
Abbondanzo added a commit to Abbondanzo/react-native that referenced this pull request Jul 22, 2026
Summary:
Pull Request resolved: react#57556

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(...)`. The fallback is carried lazily to the native layer as a raw, unprocessed string and is only parsed when every provided token fails to resolve. 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'})

The change spans the JS entry points (all platform `PlatformColorValueTypes.*` files plus the Flow and TypeScript type declarations), the iOS (Paper and Fabric) and Android (Paper and Fabric) native color resolvers, a new "Lazy Fallback Colors" section in the RNTester PlatformColor example, and the regenerated C++ API snapshots.

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

Differential Revision: D111837102
…cOS (native) (react#57556)

Summary:

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

This is the first diff in a stack that adds an optional trailing `{fallback: '<raw color string>'}` argument to `PlatformColor(...)`. The fallback is carried lazily to native and parsed only when every supplied color token fails to resolve. This diff wires up the iOS and macOS native color resolvers to honor that fallback; 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 distinguish a genuine miss (no token resolves) from a token that legitimately resolves to a transparent color, the semantic-color resolver gains an `OrNil` variant:

- `RCTPlatformColorFromSemanticItemsOrNil` returns `nil` on a miss instead of collapsing to `clearColor`. `RCTPlatformColorFromSemanticItems` keeps its existing non-null contract by wrapping the `OrNil` variant.
- On Fabric, `Color::createSemanticColor` returns the undefined-color sentinel (a null underlying `UIColor`) on a miss, so `PlatformColorParser.mm` can apply the fallback only on a true miss and otherwise render transparent exactly as before.
- The fallback string is parsed with the shared CSS color parser (`parseCSSProperty<CSSColor>`), so `transparent`/`rgba(0,0,0,0)` are honored rather than mistaken for a parse failure.
- On the iOS Paper (legacy) path, `RCTConvert.mm` parses the common hex forms (`#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`, alpha last) as the fallback when every semantic name misses.

This spans the `xplat` iOS/macOS graphics resolvers and the vendored `third-party/react-native-macos` copies.

Changelog:
[Internal] - PlatformColor: iOS/macOS native support for a lazy raw-color fallback

Differential Revision: D111837102
@meta-codesync meta-codesync Bot changed the title Support a lazy raw color fallback for PlatformColor (#57556) PlatformColor lazy fallback: honor a raw-color fallback on iOS and macOS (native) (#57556) Jul 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. meta-exported p: Facebook Partner: Facebook Partner

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant