feat: linear gradient `px` and transition hint syntax support #48410

intergalacticspacehighway · 2024-12-30T06:45:29Z

Summary:

Adds support for color transition hint syntax in linear gradients. e.g. linear-gradient(red, 20%, green)
Adds px support. Combination of px and % also works.
Simplified color stops parsing.
The processColorTransitionHint and getFixedColorStops is moved to native code so it can support combination of px and % units as it requires gradient line length, which is derived from view dimensions and gradient line angle.
Follows CSS spec (Refer transition hint section) and implementation is referred from blink engine source.

Changelog:

[GENERAL] [ADDED] - Linear gradient color transition hint syntax and px unit support.

Test Plan:

Added testcase in processBackgroundImage-test.ts and example in LinearGradientExample.js

Todo

Add testcases for getFixedColorStops and processColorTransitionHint in native code for both platforms. That's the only downside of moving it out of JS 🤦

cipolleschi · 2024-12-30T12:53:16Z

@intergalacticspacehighway Thanks for the PR! I tagged the people that worked on the feature. Thanks for the patience in this slower time, due to holidays and end-of-the-year celebrations.

joevilches · 2025-01-02T22:22:24Z

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

+        const positions = colorStop.positions;
+        // Color transition hint syntax (red, 20%, blue)
+        if (
+          colorStop.color == null &&
+          Array.isArray(positions) &&
+          positions.length === 1
+        ) {
+          const position = positions[0];
+          if (typeof position === 'string' && position.endsWith('%')) {
+            processedColorStops.push({
+              color: null,
+              position: parseFloat(position) / 100,
+            });
+          } else {
+            // If a position is invalid, return an empty array and do not apply gradient. Same as web.
+            return [];


I think we can change this to share some code better. Do transition hints have to be percentages? Regardless we are doing a lot of the same things, can you try to get rid of the top level if/else here and share some of this logic?

Do transition hints have to be percentages?

They are actually length-percentage in the spec. But i only added % support for now in color stops. Linear gradient support mixing % and px units which require us to know the dimension, for this we'll have to move color stop parsing to native side. I wanted to avoid that change until the new css parser.

#48410 (comment)

can you try to get rid of the top level if/else here and share some of this logic?

i kinda prefer the explicit checks, also each branch has a tiny comment on top, but i will take another look!

joevilches · 2025-01-02T22:28:54Z

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

 type ParsedGradientValue = {
  type: 'linearGradient',
  direction: LinearGradientDirection,
  colorStops: $ReadOnlyArray<{
-    color: ProcessedColorValue,
+    color: ColorStopColor,


I would comment in what scenarios we can have a null color, or otherwise change the typing to make that super clear like

$ReadOnlyArray<{ colorStop | transitionHint }>

I think they are similar enough to just roll with the comment but it should be clear that that syntax is supported

Added a comment. Thanks!

joevilches · 2025-01-02T22:34:21Z

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

@@ -1331,7 +1331,13 @@ inline void fromRawValue(
                positionIt->second.hasType<Float>()) {
              ColorStop colorStop;
              colorStop.position = (Float)(positionIt->second);
-              fromRawValue(context, colorIt->second, colorStop.color);
+              if (colorIt->second.hasValue()) {


what is the default value of the color in ColorStop? Will we be able to detect that this is a transition hint vs something like the color black?

here if JS color is null, that only happens if user passed transition hint. Then the color in ColorStop gets default SharedColor value i.e. HostPlatformColor::UndefinedColor. So for black color it should be alright!

joevilches · 2025-01-02T22:42:11Z

packages/react-native/React/Fabric/Utils/RCTLinearGradient.mm

+    auto &colorStop = colorStops[i];
+    // Skip if not a color hint
+    if (colorStop.color) {
+      continue;


again, curious if a color like black breaks this? Regardless I feel like it would be more future proof and more obvious if you just changed the color in ColorStop to be a std::optional or such

color in ColorStop is SharedColor instance which defaults to HostPlatformColor::UndefinedColor and it has bool overload to check for undefined color. So i think black or such colors should be fine?

joevilches · 2025-01-02T22:56:34Z

packages/react-native/Libraries/StyleSheet/__tests__/processBackgroundImage-test.js

+      {color: null, position: 0.4},
+      {color: processColor('blue'), position: 1},
+    ]);
+  });


can you add some more? Hints that are invalid (> 100%, non percents, multiple in a row, etc). Some longer ones with more stops and more hints just to stress test things a bit, etc. The code has a lot of branching logic due to the complexity of the syntax we are allowing, so I think we should err on the side of excessive testing to raise our confidence level here

Agree, added.

* linear gradient px support * fix test cases * handle invalid transition hint * fix multiple transition hint * final fixes

intergalacticspacehighway · 2025-01-05T11:00:55Z

@joevilches i added the px support as well and updated the PR description. sorry it increased the review surface and changes. But it was needed for web parity. Let me know if you want to split it up! thanks 🙏

facebook-github-bot · 2025-01-06T19:11:52Z

@joevilches has imported this pull request. If you are a Meta employee, you can view this diff on Phabricator.

joevilches · 2025-01-08T17:45:13Z

...react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/LinearGradient.kt

+private enum class UnitType {
+  Point,
+  Percent,
+  Undefined
+}
+
+private data class ValueUnit(
+  val value: Float = 0.0f,
+  val unit: UnitType = UnitType.Undefined
+)
+
+private data class ColorStop(
+  var color: Int? = null,
+  val position: ValueUnit
+)


@intergalacticspacehighway got some internal comments mentioning we should use LengthPercentage here for position's type: https://github.com/facebook/react-native/blob/main/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/LengthPercentage.kt

Sure, updated. I missed checking that out. Thanks!

i had to add getter for value though, because color stop position need it's own resolver, which relies on gradient line length.

For consistency i also made similar changes to obj c.

jorge-cab · 2025-01-09T19:50:28Z

...ges/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/LengthPercentage.kt

+    private val _value: Float,
    public val type: LengthPercentageType,
 ) {
+  public val value: Float
+    get() = _value


I think we can just change value to be public. We don't have to worry about the setter since its a val

Cool. Updated. Thanks for reviewing.

jorge-cab · 2025-01-09T19:54:36Z

...react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/LinearGradient.kt

+      if (newPosition == null) {
        // Step 1:
        // If the first color stop does not have a position,
        // set its position to 0%. If the last color stop does not have a position,
        // set its position to 100%.
        when (i) {
-          0 -> newPosition = ValueUnit(0f, UnitType.Point)
-          colorStops.size - 1 -> newPosition = ValueUnit(1f, UnitType.Point)
+          0 -> newPosition = 0f
+          colorStops.size - 1 -> newPosition = 1f


nit:

newPosition = newPosition ?: when (i) { 0 -> 0f colorStops.size - 1 -> 1f }

facebook-github-bot · 2025-01-10T22:37:30Z

@joevilches has imported this pull request. If you are a Meta employee, you can view this diff on Phabricator.

joevilches

A few more things with the new length percentage!

joevilches · 2025-01-13T22:33:12Z

...react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/LinearGradient.kt

+    return when (position.type) {
+      LengthPercentageType.POINT -> PixelUtil.toPixelFromDIP(position.value) / gradientLineLength
+      LengthPercentageType.PERCENT -> position.value / 100
+      else -> null


this switch is exhaustive so this else does nothing, can you remove (this is also an internal linting error)

joevilches · 2025-01-13T22:34:16Z

...ges/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/LengthPercentage.kt

@@ -20,7 +20,7 @@ public enum class LengthPercentageType {
 }

 public data class LengthPercentage(
-    private val value: Float,
+    public val value: Float,


Ideally we do not make this public. Reading the value of a percent has a high chance of being a bug (should resolve it first). I see the current resolve is a bit specific to corner radius. Mind adding a resolve that

takes a float as the referenceLength

returns points as is and percents as a percent of said reference length

and use that resolve and make this private again?

Agree. Updated.

joevilches · 2025-01-14T00:05:47Z

...react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/LinearGradient.kt

+      LengthPercentageType.POINT -> PixelUtil.toPixelFromDIP(position.value) / gradientLineLength
+      LengthPercentageType.PERCENT -> position.value / 100


are percents eval'ed relative to the gradientLineLength?

actually, px are eval'ed relative to gradientLineLength 😅. android and iOS linear gradient APIs expect [0-1] value for color stop position. So we need this kind of resolve . e.g. if user passes 50% we just want to resolve it to 0.5 and If user passes 50px then we need to resolve it relative to gradientLineLength like 50 / gradientLineLength.

Lengths are measured along the gradient line from the starting point in the direction of the ending point.

From the color stop syntax spec

tldr; percentage are relative to gradient line length but we do not need to evaluate it as native APIs handle it. For px we need to eval.

facebook-github-bot · 2025-01-15T19:17:49Z

@joevilches has imported this pull request. If you are a Meta employee, you can view this diff on Phabricator.

linear gradient transition hint syntax

f65c873

facebook-github-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 Dec 30, 2024

intergalacticspacehighway mentioned this pull request Dec 30, 2024

feat: linear gradient transition hint syntax #46219

Closed

facebook-github-bot added the Shared with Meta Applied via automation to indicate that an Issue or Pull Request has been shared with the team. label Dec 30, 2024

cipolleschi requested review from NickGerleman, jorge-cab and joevilches December 30, 2024 12:51

nit perf

8bbcc0a

joevilches requested changes Jan 2, 2025

View reviewed changes

add more tests in processbackgroundimage

6913cdb

intergalacticspacehighway marked this pull request as draft January 5, 2025 07:31

intergalacticspacehighway added 2 commits January 5, 2025 23:39

Linear gradient with px (#3)

3c443c3

* linear gradient px support * fix test cases * handle invalid transition hint * fix multiple transition hint * final fixes

update snapshot

a21b3e6

intergalacticspacehighway marked this pull request as ready for review January 5, 2025 10:58

intergalacticspacehighway changed the title ~~feat: linear gradient transition hint syntax~~ feat: linear gradient px and transition hint syntax support Jan 5, 2025

joevilches approved these changes Jan 6, 2025

View reviewed changes

joevilches reviewed Jan 8, 2025

View reviewed changes

use LengthPercentage for position

a1048a2

jorge-cab reviewed Jan 9, 2025

View reviewed changes

pr feedback

1405715

joevilches requested changes Jan 14, 2025

View reviewed changes

add referenceLength resolve and make value private

5e31def

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: linear gradient `px` and transition hint syntax support #48410

feat: linear gradient `px` and transition hint syntax support #48410

intergalacticspacehighway commented Dec 30, 2024 •

edited

Loading

cipolleschi commented Dec 30, 2024

joevilches Jan 2, 2025

intergalacticspacehighway Jan 3, 2025 •

edited

Loading

joevilches Jan 2, 2025

intergalacticspacehighway Jan 3, 2025

joevilches Jan 2, 2025

intergalacticspacehighway Jan 3, 2025 •

edited

Loading

joevilches Jan 2, 2025

intergalacticspacehighway Jan 3, 2025 •

edited

Loading

joevilches Jan 2, 2025

intergalacticspacehighway Jan 3, 2025

intergalacticspacehighway commented Jan 5, 2025 •

edited

Loading

facebook-github-bot commented Jan 6, 2025

joevilches Jan 8, 2025

intergalacticspacehighway Jan 9, 2025 •

edited

Loading

jorge-cab Jan 9, 2025

intergalacticspacehighway Jan 9, 2025 •

edited

Loading

jorge-cab Jan 9, 2025

facebook-github-bot commented Jan 10, 2025

joevilches left a comment

joevilches Jan 13, 2025 •

edited

Loading

joevilches Jan 13, 2025

intergalacticspacehighway Jan 14, 2025 •

edited

Loading

joevilches Jan 14, 2025

intergalacticspacehighway Jan 14, 2025 •

edited

Loading

facebook-github-bot commented Jan 15, 2025

		LengthPercentageType.POINT -> PixelUtil.toPixelFromDIP(position.value) / gradientLineLength
		LengthPercentageType.PERCENT -> position.value / 100

feat: linear gradient px and transition hint syntax support #48410

Are you sure you want to change the base?

feat: linear gradient px and transition hint syntax support #48410

Conversation

intergalacticspacehighway commented Dec 30, 2024 • edited Loading

Summary:

Changelog:

Test Plan:

Todo

cipolleschi commented Dec 30, 2024

Choose a reason for hiding this comment

intergalacticspacehighway Jan 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

intergalacticspacehighway Jan 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

intergalacticspacehighway Jan 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

intergalacticspacehighway commented Jan 5, 2025 • edited Loading

facebook-github-bot commented Jan 6, 2025

Choose a reason for hiding this comment

intergalacticspacehighway Jan 9, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

intergalacticspacehighway Jan 9, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

facebook-github-bot commented Jan 10, 2025

joevilches left a comment

Choose a reason for hiding this comment

joevilches Jan 13, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

intergalacticspacehighway Jan 14, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

intergalacticspacehighway Jan 14, 2025 • edited Loading

Choose a reason for hiding this comment

facebook-github-bot commented Jan 15, 2025

feat: linear gradient `px` and transition hint syntax support #48410

feat: linear gradient `px` and transition hint syntax support #48410

intergalacticspacehighway commented Dec 30, 2024 •

edited

Loading

intergalacticspacehighway Jan 3, 2025 •

edited

Loading

intergalacticspacehighway Jan 3, 2025 •

edited

Loading

intergalacticspacehighway Jan 3, 2025 •

edited

Loading

intergalacticspacehighway commented Jan 5, 2025 •

edited

Loading

intergalacticspacehighway Jan 9, 2025 •

edited

Loading

intergalacticspacehighway Jan 9, 2025 •

edited

Loading

joevilches Jan 13, 2025 •

edited

Loading

intergalacticspacehighway Jan 14, 2025 •

edited

Loading

intergalacticspacehighway Jan 14, 2025 •

edited

Loading